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 前，请先阅读架构说明和 安全边界。

环境要求

首次运行前请安装：

• Python 3.12 或 3.13。

• 用于锁定 Python 环境的 uv。

• Git，以及一个你有权检查的 Git 仓库。

• Windows 上的 Docker Desktop，或 Linux 上的 Docker Engine。

• 所选模型提供商的 API 密钥。

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

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

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

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

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

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

uv run forge-zh --help
uv run forge-zh models --help

2. 启动并验证 Docker

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

sudo systemctl start docker

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

docker version
docker info

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

3. 配置模型

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

$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. 验证配置

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

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

5. 构建 Docker 运行镜像

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

uv run forge-zh prepare

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

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

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

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：

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

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

选择运行模式

只读调查

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

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 一起使用；不可变运行合同会拒绝这种组合。

修复并验证

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

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 可查看完整参数和选项：

uv run forge-zh --help
uv run forge-zh COMMAND --help

常用的命令帮助页：

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>，并在 后续命令中复用同一个值。

检查运行

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

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

恢复暂停任务

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

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

导出制品

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 命令。

docker version
docker info
uv run forge-zh prepare

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

模型配置或凭据错误

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

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

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

forge-zh prepare 无法构建镜像

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

docker info
uv run forge-zh prepare

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

uv 提示无法使用 hardlink

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

$env:UV_LINK_MODE = "copy"

评估与开发

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

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 发布门禁：

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

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

安全模型与限制

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

完整控制措施和剩余限制见安全边界。

项目治理

• 按照 SECURITY.md 私下报告安全漏洞。

• 创建拉取请求前请阅读 CONTRIBUTING.md。

• 使用支持和问题分流说明见 SUPPORT.md。

• 面向用户的变更记录在 CHANGELOG.md。

许可证

Forge 采用开源 MIT License。