GFramework/docs/zh-CN/contributor/development-environment.md

开发环境能力清单

这份文档只记录对 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 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。