mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-03-22 10:34:30 +08:00
3130a3bab2
- 在贡献指南中添加开发环境能力清单链接和说明 - 创建详细的开发环境能力清单文档，记录项目所需的运行时和工具 - 添加 .ai/environment/tools.ai.yaml 文件，为 AI 提供精简的环境能力信息 - 添加 .ai/environment/tools.raw.yaml 文件，存储完整的环境检测数据 - 创建 collect-dev-environment.sh 脚本，用于收集和输出环境信息 - 创建 generate-ai-environment.py 脚本，从原始数据生成 AI 友好的环境清单 - 在 .gitignore 中添加 .venv/ 工具目录忽略规则
97 lines
4.2 KiB
Markdown
97 lines
4.2 KiB
Markdown
# 开发环境能力清单
|
||
|
||
这份文档只记录对 `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
|
||
```
|
||
|
||
## 维护规则
|
||
|
||
- 目标不是记录“这台机器装了什么”，而是记录“GFramework 开发和 AI 协作实际该用什么”。
|
||
- 新工具只有在满足以下条件之一时才应加入清单：
|
||
- 当前仓库构建、测试、文档或验证直接依赖它
|
||
- AI 在当前仓库中会高频使用，且能明显提升效率
|
||
- 新贡献者配置当前仓库开发环境时确实需要知道它
|
||
- 不满足上述条件的工具，不写入文档，也不写入 `.ai/environment/tools.raw.yaml` / `.ai/environment/tools.ai.yaml`。
|