mirror of https://github.com/GeWuYou/GFramework.git synced 2026-03-22 10:34:30 +08:00

GeWuYou 3130a3bab2 feat(docs): 添加开发环境能力清单及相关工具脚本

- 在贡献指南中添加开发环境能力清单链接和说明
- 创建详细的开发环境能力清单文档，记录项目所需的运行时和工具
- 添加 .ai/environment/tools.ai.yaml 文件，为 AI 提供精简的环境能力信息
- 添加 .ai/environment/tools.raw.yaml 文件，存储完整的环境检测数据
- 创建 collect-dev-environment.sh 脚本，用于收集和输出环境信息
- 创建 generate-ai-environment.py 脚本，从原始数据生成 AI 友好的环境清单
- 在 .gitignore 中添加 .venv/ 工具目录忽略规则

2026-03-21 12:37:56 +08:00

4.2 KiB

Raw Permalink Blame History

开发环境能力清单

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

维护规则

目标不是记录“这台机器装了什么”，而是记录“GFramework 开发和 AI 协作实际该用什么”。
新工具只有在满足以下条件之一时才应加入清单：
- 当前仓库构建、测试、文档或验证直接依赖它
- AI 在当前仓库中会高频使用，且能明显提升效率
- 新贡献者配置当前仓库开发环境时确实需要知道它
不满足上述条件的工具，不写入文档，也不写入 .ai/environment/tools.raw.yaml / .ai/environment/tools.ai.yaml。

4.2 KiB Raw Permalink Blame History Unescape Escape