mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-05-07 00:39:00 +08:00
66395739dc
- 更新 AGENTS.md、DOCUMENTATION_STANDARDS.md 与 gframework-doc-refresh 规则，禁止在公开文档中暴露 inventory、覆盖基线与恢复点 - 修复 Core、Game、Ecs.Arch 与 abstractions 栏目中的 XML 覆盖表述，改为面向使用者的源码阅读入口 - 补充 contributor 页面 frontmatter，并统一 landing page、验证基线等内部术语为读者导向表达 - 更新 documentation-full-coverage-governance tracking 与 trace，记录 -batch-boot 75 基线、验证结果和下一步
123 lines
6.2 KiB
Markdown
123 lines
6.2 KiB
Markdown
---
|
||
title: 开发环境能力清单
|
||
description: 说明 GFramework 当前开发和 AI 协作依赖的环境能力、推荐工具与刷新方式。
|
||
---
|
||
|
||
# 开发环境能力清单
|
||
|
||
这份文档只记录对 `GFramework` 当前开发和 AI 协作真正有用的环境能力，不收录与本项目无关的系统工具。
|
||
|
||
如果某个工具没有出现在这里，默认表示它对当前仓库不是必需项，AI 也不应因为“系统里刚好装了”就优先使用它。
|
||
|
||
## 当前验证环境
|
||
|
||
当前仓库主要在下面这组环境中验证：
|
||
|
||
- **运行环境**：WSL2
|
||
- **发行版**：Ubuntu 24.04 LTS
|
||
- **Shell**：`bash`
|
||
|
||
机器可读的环境数据分成两层：
|
||
|
||
- `GFramework/.ai/environment/tools.raw.yaml`：完整事实采集
|
||
- `GFramework/.ai/environment/tools.ai.yaml`：给 AI 看的精简决策提示
|
||
|
||
AI 应优先读取 `tools.ai.yaml`，只有在需要追溯完整事实时才查看 `tools.raw.yaml`。
|
||
|
||
## 当前项目需要的运行时
|
||
|
||
| 工具 | 是否需要 | 在 GFramework 中的用途 |
|
||
|-----------|------|---------------------------------|
|
||
| `dotnet` | 必需 | 构建、测试、打包整个解决方案 |
|
||
| `python3` | 推荐 | 运行本地辅助脚本、环境采集和轻量自动化 |
|
||
| `node` | 推荐 | 作为文档工具链的 JavaScript 运行时 |
|
||
| `bun` | 推荐 | 安装并预览 `docs/` 下的 VitePress 文档站点 |
|
||
|
||
## 当前项目需要的命令行工具
|
||
|
||
| 工具 | 是否需要 | 在 GFramework 中的用途 |
|
||
|----------|------|-----------------------------------------------|
|
||
| `git` | 必需 | 提交代码、查看 diff、审查变更 |
|
||
| `bash` | 必需 | 执行仓库脚本，例如 `scripts/validate-csharp-naming.sh` |
|
||
| `rg` | 必需 | 在仓库中快速搜索代码和文档 |
|
||
| `jq` | 推荐 | 处理 JSON 输出，便于本地脚本和 AI 做结构化检查 |
|
||
| `docker` | 可选 | 运行 MegaLinter 等容器化检查工具 |
|
||
|
||
这里只保留和当前仓库直接相关的 CLI。像 `kubectl`、`terraform`、`helm`、`java`、数据库客户端等工具，即使系统已安装，也不进入正式清单。
|
||
|
||
## Python 包
|
||
|
||
Python 包只记录两类内容：
|
||
|
||
- 当前环境里已经存在、对开发辅助有价值的包
|
||
- 明确对 AI/脚本化开发有帮助、后续可能会安装的包
|
||
|
||
| 包 | 当前状态 | 用途 |
|
||
|------------|---------|---------------------|
|
||
| `requests` | 当前环境已安装 | 用于简单 HTTP 调用和脚本集成 |
|
||
| `rich` | 当前环境已安装 | 用于更易读的终端输出 |
|
||
| `openai` | 当前环境可选 | 用于脚本化调用 OpenAI API |
|
||
| `tiktoken` | 当前环境可选 | 用于 token 估算和上下文检查 |
|
||
| `pydantic` | 当前环境可选 | 用于结构化配置和模式校验 |
|
||
| `pytest` | 当前环境可选 | 用于 Python 辅助脚本的小型测试 |
|
||
|
||
如果某个 Python 包与当前仓库没有直接关系，就不要加入清单。
|
||
|
||
## AI 使用约定
|
||
|
||
AI 在这个仓库里应优先使用：
|
||
|
||
- `rg` 做文本搜索
|
||
- `jq` 做 JSON 检查
|
||
- `bash` 执行仓库脚本
|
||
- `dotnet` 做构建和测试
|
||
- `bun` 做文档预览
|
||
- `python3 + requests` 做轻量本地辅助脚本
|
||
|
||
AI 不应直接把原始探测数据当成决策规则；应以 `tools.ai.yaml` 中的推荐和 fallback 为准。如果确实需要引入新工具，应先更新环境清单，再在任务中使用。
|
||
|
||
## 如何刷新环境清单
|
||
|
||
使用仓库脚本先采集原始环境，再生成 AI 版本：
|
||
|
||
```bash
|
||
# 输出原始环境清单到终端
|
||
bash scripts/collect-dev-environment.sh --check
|
||
|
||
# 写回原始清单
|
||
bash scripts/collect-dev-environment.sh --write
|
||
|
||
# 由原始清单生成 AI 决策清单
|
||
python3 scripts/generate-ai-environment.py
|
||
```
|
||
|
||
## 文档站 LLM 索引接入说明
|
||
|
||
### 访问路径
|
||
|
||
LLM 索引文件与文档站一起部署在 GitHub Pages，遵循 `docs/.vitepress/config.mts` 里 `base: '/GFramework/'` 的路径规则。部署之后可以直接访问 `https://gewuyou.github.io/GFramework/llms.txt` 和 `https://gewuyou.github.io/GFramework/llms-full.txt`。这些文件最终会被写入 `docs/.vitepress/dist/`，但生成动作发生在 `publish-docs` workflow 的 `demodrive-ai/llms-txt-action` 步骤，而不是单独执行 `bun run build` 时直接产出。
|
||
|
||
### 生成时机与依赖
|
||
|
||
`demodrive-ai/llms-txt-action` 负责把文档站打包后的页面转换成 LLM 索引，它的 `docs_dir` 已指定为 `docs/.vitepress/dist`，并通过 `sitemap.xml` 解析页面 URL。只能在 `bun run build` 之后（即 VitePress 将页面输出到 `dist` 并生成 `sitemap.xml`）执行；如果没有 sitemap，action 会得不到页面列表，生成的 `llms.txt` 就会不完整。
|
||
|
||
### 验证流程
|
||
|
||
1. 本地执行 `bun run build`，确认 `docs/.vitepress/dist/sitemap.xml` 已生成，并检查其中的 URL 是否与 GitHub Pages
|
||
地址一致。添加或删除文档页面后必须重新运行一次全量构建。
|
||
2. 在 Pull Request 或发布前查看 `publish-docs` workflow 日志，确认 `Verify LLM artifacts` 步骤通过，并检查
|
||
`docs/.vitepress/dist/llms.txt`、`docs/.vitepress/dist/llms-full.txt` 已作为 Pages artifact 上传。
|
||
3. 部署完成后通过 GitHub Pages 打开 `https://gewuyou.github.io/GFramework/llms.txt`
|
||
和 `https://gewuyou.github.io/GFramework/llms-full.txt`，确认可访问且内容覆盖最新页面。
|
||
4. 如果后续需要对 LLM 索引行为做变更，优先思考是否影响 `sitemap` 结构或 `docs_dir` 路径；失效通常表现为 `llms`
|
||
文件缺失、内容为空，或链接仍指向旧页面。
|
||
|
||
## 维护规则
|
||
|
||
- 目标不是记录“这台机器装了什么”，而是记录“GFramework 开发和 AI 协作实际该用什么”。
|
||
- 新工具只有在满足以下条件之一时才应加入清单：
|
||
- 当前仓库构建、测试、文档或验证直接依赖它
|
||
- AI 在当前仓库中会高频使用，且能明显提升效率
|
||
- 新贡献者配置当前仓库开发环境时确实需要知道它
|
||
- 不满足上述条件的工具，不写入文档，也不写入 `.ai/environment/tools.raw.yaml` / `.ai/environment/tools.ai.yaml`。
|