# 开发环境能力清单

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