# Forge 中文版

Forge 是一个面向 Python 与 pytest 仓库的本地、MCP 原生维护代理运行时。它在隔离的 Git
工作树中运行代理，保存可审计的 SQLite 事件与制品，并且不会自动提交、推送、创建拉取
请求，也不会把补丁应用回原始工作树。

Forge `v1.0` 是首个稳定公开版本。当前受支持的工具界面是项目自带的 `forge-repo-mcp`
服务；运行时本身并不依赖某一种特定的仓库任务。

## 核心能力

- 通过 LiteLLM 管理模型提供商配置（已测试 DeepSeek 工具调用）。
- 单代理模型/工具循环，由运行时强制执行策略与预算。
- 持久的 `--read-only` 合同会向模型隐藏命令和写入工具、拒绝 shell 验证，并可通过重复
  传入 `--allow-tool` 进一步收窄工具范围。
- 有界模型上下文包含已完成工具账本、单轮工具上限、只读证据缓存、连续无进展检测和预留
  的最终综合回合。
- 默认使用 Docker 执行：断网、移除 Linux capabilities、只读基础文件系统、可写的隔离
  工作树，以及 CPU、内存和 PID 限制。
- 隔离的 Git 工作树、补丁/报告制品、JSONL 风格事件历史、SQLite 检查、检查点与恢复。
- 确定性的开发场景和冻结故障场景，覆盖模型超时、工具超时、提示注入和补丁响应丢失。

在重要仓库上使用 Forge 前，请先阅读[架构说明](docs/architecture.md)和
[安全边界](docs/security.md)。

## 环境要求

首次运行前请安装：

- Python 3.12 或 3.13。
- 用于锁定 Python 环境的 [uv](https://docs.astral.sh/uv/)。
- Git，以及一个你有权检查的 Git 仓库。
- Windows 上的 Docker Desktop，或 Linux 上的 Docker Engine。
- 所选模型提供商的 API 密钥。

> 运行 `forge-zh prepare` 或 `forge-zh run` 前必须启动 Docker。仅安装 Docker Desktop
> 还不够：请等待它的 Linux engine 明确显示已经就绪。

## 快速启动：从克隆到完成第一个任务

### 1. 克隆并一键安装全部依赖

```powershell
git clone <repository-url>
cd forge-zh
uv sync --locked --all-groups
```

`uv sync --locked --all-groups` 会一次性安装锁定版本的运行、开发和测试依赖，无需逐个
安装 Python 包。

确认 CLI 已安装，并查看内置帮助：

```powershell
uv run forge-zh --help
uv run forge-zh models --help
```

### 2. 启动并验证 Docker

Windows 用户请先启动 Docker Desktop。使用 systemd 的 Linux 主机可这样启动 Docker：

```bash
sudo systemctl start docker
```

然后确认客户端能够连接引擎：

```powershell
docker version
docker info
```

`docker version` 必须同时显示 **Client** 和 **Server**。如果没有 Server、出现命名管道或
socket 错误，或者 Docker Desktop 仍显示“正在启动”，请暂时不要运行 Forge。启动或重启
Docker 后再次检查。

### 3. 配置模型

先在当前 shell 设置提供商密钥，再保存命名配置。Forge 只保存环境变量名、提供商和模型
标识符，不保存 API 密钥值。

```powershell
$env:DEEPSEEK_API_KEY = "<your-api-key>"
uv run forge-zh models add deepseek `
  --provider deepseek `
  --model "your-model-id" `
  --api-key-env DEEPSEEK_API_KEY
```

配置名 `deepseek` 是后续命令使用的本地标签。不要把真实密钥写入 TOML、任务文本、提交、
Issue 描述或终端截图。

### 4. 验证配置

```powershell
uv run forge-zh doctor --profile deepseek
uv run forge-zh doctor --profile deepseek --probe
```

第一条命令只在本地检查配置和凭据，不会打印密钥。`--probe` 是可选项，会向提供商发送一次
最小的真实工具调用请求。

### 5. 构建 Docker 运行镜像

确认 Docker 已启动，然后构建缓存的断网 MCP 运行镜像：

```powershell
uv run forge-zh prepare
```

更新 Forge 源码或运行器依赖后需要再次执行 `prepare`。构建成功会创建 `forge-zh run`
默认使用的 `forge-zh-runner:test` 镜像。

### 6. 运行第一个安全调查任务

第一次建议使用只读模式，使模型不能执行命令或修改仓库文件：

```powershell
uv run forge-zh run <repository-path> `
  --profile deepseek `
  --read-only `
  --allow-tool repo.list_files `
  --allow-tool repo.search `
  --allow-tool repo.read_file `
  --task "分析项目结构，并找出测试覆盖最薄弱的核心模块。"
```

`<repository-path>` 必须是现有 Git 工作树的根目录。Forge 会创建独立、detached 的工作树
并打印运行 ID，不会修改原始工作树。

### 7. 检查并导出结果

把 `RUN_ID` 替换为 `forge-zh run` 打印的 ID：

```powershell
uv run forge-zh inspect RUN_ID
uv run forge-zh export RUN_ID --output .\forge-exports
```

检查命令会显示持久化的状态、事件和制品。导出命令会写出供人工审查的补丁、报告和轨迹，
不会应用或提交补丁。

## 选择运行模式

### 只读调查

适用于架构审查、代码搜索、依赖分析，或任何不得执行仓库命令和写入文件的任务：

```powershell
uv run forge-zh run <repository-path> `
  --profile deepseek `
  --read-only `
  --allow-tool repo.list_files `
  --allow-tool repo.search `
  --allow-tool repo.read_file `
  --task "解释身份验证流程并找出主要风险。"
```

不要把 `--read-only` 与 `--verify` 一起使用；不可变运行合同会拒绝这种组合。

### 修复并验证

对于已获授权的修复任务，请提供明确的验证命令，并保护敏感路径：

```powershell
uv run forge-zh run <repository-path> `
  --profile deepseek `
  --task "定位并修复失败的登录测试；不要改变公开 API。" `
  --verify "python -m pytest tests/test_login.py" `
  --protect api/public_schema.py
```

多个命令可重复传入 `--verify`，多个仓库相对路径可重复传入 `--protect`。Forge 会把补丁
保留在隔离工作树和制品中，供人工审查。

## 命令参考

使用顶层帮助查看已安装的命令；在任何命令后添加 `--help` 可查看完整参数和选项：

```powershell
uv run forge-zh --help
uv run forge-zh COMMAND --help
```

| 命令 | 作用 | 常见用途 |
| --- | --- | --- |
| `uv run forge-zh models add` | 保存不含密钥的命名提供商配置。 | 每个提供商/模型配置执行一次。 |
| `uv run forge-zh doctor` | 验证配置和所需密钥环境变量。 | 任务前执行；添加 `--probe` 可真实检查提供商。 |
| `uv run forge-zh prepare` | 构建或刷新 Docker 运行镜像。 | 首次任务前和运行器更新后执行。 |
| `uv run forge-zh run` | 启动新的隔离仓库任务。 | 传入仓库、配置、任务和可选安全约束。 |
| `uv run forge-zh resume` | 从检查点继续暂停的任务。 | `--approve` 只用于已记录的精确批准请求。 |
| `uv run forge-zh inspect` | 显示持久化状态、事件和制品。 | 在不改变任务的情况下诊断运行。 |
| `uv run forge-zh export` | 导出补丁、报告和轨迹文件。 | 不应用变更即可审查或分享证据。 |
| `uv run forge-zh eval` | 评估已持久化的场景运行。 | 执行确定性的开发和冻结故障评估。 |

常用的命令帮助页：

```powershell
uv run forge-zh models --help
uv run forge-zh run --help
uv run forge-zh resume --help
uv run forge-zh inspect --help
uv run forge-zh export --help
uv run forge-zh eval --help
```

## 运行记录、检查与恢复

运行记录保存在 `./run-records/runs/<run-id>/`。每个任务包含 SQLite 记录、JSONL 风格事件、
检查点和文本制品。如需使用其他根目录，请向 `run` 传入 `--storage <storage-path>`，并在
后续命令中复用同一个值。

### 检查运行

```powershell
uv run forge-zh inspect RUN_ID --storage <storage-path>
```

任务失败或暂停时先运行检查命令；记录的事件可以区分模型、工具、策略和沙箱故障，而且
不会重新执行任务。

### 恢复暂停任务

```powershell
uv run forge-zh resume RUN_ID --storage <storage-path>
uv run forge-zh resume RUN_ID --approve --storage <storage-path>
```

只有检查结果显示已记录的批准请求，而且你理解对应的精确操作时，才使用 `--approve`。
失败和已完成的任务不是可任意恢复的通用会话。

### 导出制品

```powershell
uv run forge-zh export RUN_ID --storage <storage-path> --output .\forge-exports
```

导出目录不能已包含冲突的任务导出。在 Forge 之外应用补丁前，必须审查每个生成的补丁。

## 常见问题排查

### `McpError: Connection closed` 或 AnyIO cancel-scope 堆栈

这通常表示 Docker 子进程在 MCP 初始化握手前已经退出。首先检查 Docker Desktop 或 Docker
Engine 是否真的在运行。后续的 `Attempted to exit cancel scope in a different task` 是连接
关闭后的清理噪声；真正的 Docker 错误通常出现在终端更前面。

1. 运行 `docker version`，确认其中包含 Server。
2. 运行 `docker info`；命名管道、socket 或“无法连接 daemon”表示 Docker 尚未就绪。
3. 启动或重启 Docker Desktop/Engine，并等待健康状态。
4. 运行 `uv run forge-zh prepare` 构建或刷新运行镜像。
5. 重新执行原来的 `forge-zh run` 命令。

```powershell
docker version
docker info
uv run forge-zh prepare
```

如果 Docker 健康但连接仍然关闭，请用 `docker image inspect forge-zh-runner:test` 确认镜像
存在，然后再次执行 `prepare`，并查看最早的容器错误，而不是最后的清理堆栈。

### 模型配置或凭据错误

先运行不带 `--probe` 的 `doctor`。它只在本地检查配置名和环境变量，不会打印密钥值：

```powershell
uv run forge-zh doctor --all
uv run forge-zh doctor --profile deepseek
```

如果密钥变量缺失，请在运行 Forge 的同一个 shell 中设置它。如果配置缺失，请用
`models add` 创建。只有本地检查通过后再使用 `--probe`。

### `forge-zh prepare` 无法构建镜像

确认 Docker 健康且磁盘空间充足，然后重新构建：

```powershell
docker info
uv run forge-zh prepare
```

构建使用锁定并带哈希的依赖。`prepare` 期间的网络、镜像仓库、代理或证书错误属于 Docker
构建问题，发生在仓库任务启动之前。

### uv 提示无法使用 hardlink

“Failed to hardlink files; falling back to full copy”不是 Forge 故障。安装会改用文件复制继续，
只可能增加时间和磁盘占用。如需主动关闭该警告：

```powershell
$env:UV_LINK_MODE = "copy"
```

## 评估与开发

仓库包含六个开发场景和四个冻结故障场景。在提供已持久化的运行 ID 前，`forge-zh eval`
会明确报告评估场景数为零，不会虚构模型结果。

```powershell
uv run forge-zh eval fixtures/dev
uv run forge-zh eval fixtures/frozen
uv run pytest
uv run ruff check src tests
uv run pyright
```

## 发布检查

在 Docker Desktop 已运行的 Windows 环境中，从干净的 Git 工作树执行可复现的 `v1.0`
发布门禁：

```powershell
.\scripts\release-check.ps1 -Profile deepseek
```

该脚本会从 `uv.lock` 创建临时环境，运行完整测试与评估套件，验证 Docker 运行器，并完成
隔离的真实提供商演示。准确验收标准见[发布检查清单](docs/release-checklist.md)。

## 更新记录与发布

人工修改产品代码、工具、依赖或测试时，必须在 [CHANGELOG.md](CHANGELOG.md) 的
`Unreleased` 小节添加简明记录；面向 `main` 的拉取请求会自动执行此检查。Dependabot 创建的
依赖更新无需手工填写，因为版本标签触发的发布工作流会将其记录到 GitHub 自动生成的 Release
Notes。推送如 `v1.1.0` 的版本标签后，工作流会创建 GitHub Release 并根据已合并的拉取请求
生成说明。

## 安全模型与限制

Docker 隔离和运行时策略能够降低风险，但不能保证任意不可信代码绝对安全。Forge 将仓库
内容、测试输出和工具输出都视为不可信输入。使用补丁和报告前必须人工审查。`v1.0` 仅支持
在本地 Docker 中运行项目自带的第一方 MCP 服务。

完整控制措施和剩余限制见[安全边界](docs/security.md)。

## 项目治理

- 按照 [SECURITY.md](SECURITY.md) 私下报告安全漏洞。
- 创建拉取请求前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。
- 使用支持和问题分流说明见 [SUPPORT.md](SUPPORT.md)。
- 面向用户的变更记录在 [CHANGELOG.md](CHANGELOG.md)。

## 许可证

Forge 采用开源 [MIT License](LICENSE)。