内容
# 开放代码监管
**克劳德规划和检查工作。免费模型负责输入。**
[](LICENSE)
[](package.json)
[](https://github.com/Namit-nair/opencode-foreman/actions/workflows/ci.yml)
[](#MCP服务器)
`开放代码监管`是您代码库的监管者：它将实际的文件逐一实现交给运行免费模型的[开放代码CLI](https://opencode.ai)处理，而克劳德则负责编写规范并验收完成的工作。您可以在不花费克劳德自己的代币的情况下，获得有效的差异。
它既可以作为您可以脚本的**CLI**，也可以作为克劳德可以在对话中调用的**MCP服务器**。
---
## 为什么
克劳德代码/合作会话会花费大量代币在最不重要的部分：编写和重写实现代码。`开放代码监管`颠覆了劳动分工——
| | 克劳德 | 开放代码监管 |
|---|---|---|
| 编写任务规范 | ✅ | |
| 编写实现 | | ✅（通过免费模型） |
| 运行测试/构建 | | ✅ |
| 独立对比git结果 | | ✅ |
| 判断是否完成 | ✅ | |
克劳德永远不需要相信代理的说法——每个结果都会在克劳德看到之前，通过实际的`git diff`和实际的验证命令进行检查。
## 工作原理
```
克劳德 开放代码监管 开放代码CLI + 免费模型
────── ──────────────── ─────────────────────────
"修复bug， ─────▶ 1. git checkpoint
这里是验证命令" 2. 确保安全防护 ───────────────────────▶ 读取，编辑，运行bash
4. git diff（真实结果） ◀──── 声称完成
5. 运行验证命令
6. 压缩包
◀─────────────── （摘要 + 差异 + 验证结果）
"看起来不错" / "重试
再次" / "切换
模型" / "恢复"
```
代理自己的声明永远不会被信任——更改的文件和差异来自`git`，而通过/失败则来自实际运行验证命令。
## 功能
- **CLI 和 MCP 服务器**，相同的底层引擎，因此您可以脚本化或让克劳德直接调用。
- **免费模型优先**：发现实际可用的免费模型（开箱即用的OpenCode Zen免费层，设置`OPENROUTER_API_KEY`后为`openrouter/*`），并允许您为每个项目、每个会话或每次调用选择一个。
- **会话恢复，任务中途切换模型/代理/努力** — 后续的`continue`调用可以在不丢失OpenCode会话上下文的情况下切换模型。
- **Git checkpoint，单命令恢复** — 每个委托运行都先进行快照；`revert`会将目录精确恢复，包括删除代理新创建的文件。
- **类似真正监管者的防护措施 — 强制站点安全，而不是规定方法。** 硬限制即使在`--auto`下也生效：合并的拒绝列表（`rm -rf`，`git push`，`npm publish`，`sudo`，...）和`external_directory: deny`，以限制代理到目标目录。但`doom_loop`设置为`allow` — 允许工作器迭代自己的方式（重试，回溯，重新思考），而不是在过程中被硬停止；失控迭代从外部被超时，无输出监视器和无进展/振荡检测所限制。 `--auto`本身是无条件的 — OpenCode 没有跳过权限授予的非交互模式，因此它总是被传递；拒绝规则无论如何都有效。
- **默认高推理，并且有思考空间** — 委托运行使用高推理努力（`defaultVariant`），除非调用将其降低，并且无输出监视器故意耐心（真正的沉默几分钟，而不是几秒钟），以便模型在思考时不会被杀死。
- **更丰富的任务上下文，非侵入式** — `delegate_task`接受一个可选的`context`字段，用于支持后台（文件路径，代码片段，约束），工作器可以借鉴，保持与任务分开，明确*不*作为如何实现的指令。
- **超时 + 无输出监视器，自动模型故障转移** — 真正挂起或速率限制的模型（这种情况确实会发生）会被杀死，并且在报告失败之前，会在`maxModelFallbacks`限制下，透明地重试下一个免费模型。
- **目标差异统计和代币/成本使用** 在每个包中（`diffStats`，`tokens`，`cost`）— 文件更改/ +/- 计数直接来自`git diff --numstat`，独立于代理对其自身工作的说明。
- **工具篡改警告** — 如果运行的差异触及`package.json`脚本，锁定文件，`.npmrc`或其他文件，则在验证命令通过shell执行之前发出警告（而不是阻止）。
- **机密清洗** — 已知API密钥形状和任何明确已知的机密值都会从返回给克劳德的所有内容中删除。
- **构建后绝不运行，除非您要求** — 每个MCP工具描述都明确指示克劳德不要自主调用它，并与`ask`模式权限规则（见下文）配对，该规则强制每次调用都需要批准提示，无论克劳德做出什么决定。
- 跨平台：Windows，WSL，macOS，Linux。
## 先决条件
- [Node.js](https://nodejs.org) ≥ 18
- [开放代码CLI](https://opencode.ai) 已安装并在`PATH`上
- 使用OpenCode Zen的免费层模型立即免费使用 — 无需API密钥。 如果您还想要`openrouter/*`模型，请在环境中设置`OPENROUTER_API_KEY`。
## 安装
```bash
git clone https://github.com/Namit-nair/opencode-foreman.git
cd opencode-foreman
npm install
npm run build
npm link # 将`opencode-foreman`和`opencode-foreman-mcp`放在PATH上
```
## CLI
```bash
opencode-foreman models # 列出当前可用的免费模型
opencode-foreman agents # 列出代理（构建，计划，...）
opencode-foreman set-model <id> --dir <dir> [--agent build] [--variant high]
opencode-foreman run "<task>" --dir <dir> [--verify "npm test"] [--context "..."] [--model <id>] [--variant high] [--max-attempts 3]
opencode-foreman continue "<message>" --session <id> --dir <dir> [--model <id>]
opencode-foreman status --session <id> --dir <dir>
opencode-foreman revert --dir <dir> [--session <id> | --checkpoint <commit>]
```
每个命令都打印JSON结果，失败时退出状态非零 — 容易脚本化或管道。
## MCP 服务器
全局注册一次，使其在每个项目中都可用：
```bash
claude mcp add opencode-foreman -s user -- opencode-foreman-mcp
```
或手动，在MCP客户端配置文件中：
```json
{
"mcpServers": {
"opencode-foreman": {
"command": "opencode-foreman-mcp"
}
}
}
```
**工具：** `list_models`，`list_agents`，`set_session_defaults`，`get_session_defaults`，
`delegate_task`，`delegate_continue`，`delegate_status`，`delegate_revert`，`fetch_full_diff`.
如果目录中尚未选择模型，则`delegate_task`返回一个提示列表，列出可用的免费模型 — 调用`set_session_defaults`一次，该目录中所有后续调用都将静默重用它。 任何调用都可以覆盖`model` / `agent` / `variant`仅用于自身，并传递可选的`context`（支持后台工作器可以借鉴 — 不是方法）。
**希望克劳德仅在请求时触及此内容，而非自主发起？** 添加一个权限规则，以便每次调用都需要您明确批准：
```json
// ~/.claude/settings.json
{
"permissions": {
"ask": ["mcp__opencode-foreman__*"]
}
}
```
## 配置
分层：内置默认值 → `~/.opencode-foreman/config.json` → `<dir>/.opencode-foreman.json` → 会话默认值 → 调用覆盖。
| 键 | 含义 |
|---|---|
| `timeoutMs` | 每个运行的硬时钟超时（默认值：20分钟 — 慷慨，以便长但高效的高推理运行不会被切断） |
| `noOutputTimeoutMs` | 仅在真正沉默时杀死运行（默认值：5分钟）。 模型在推理时保持沉默；这必须远高于单个思考步骤，否则您将禁用模型思考中途 |
| `maxAttempts` | 验证失败时的内部自动重试循环（默认值：3 — 给免费模型留有迭代空间，因为首次尝试成功不太可能）。 传递`1`以强制进行单个克劳德驱动的运行 |
| `defaultVariant` | 传递给OpenCode的`--variant`的推理努力，除非调用/会话覆盖它（默认值：`high`） |
| `maxModelFallbacks` | 如果一个模型挂起，可以尝试多少个备用模型（默认值：2 — 始终开启，独立于`maxAttempts`） |
| `preferredModels` | 有序列表，首先建议选择模型，并作为故障转移链的头部（默认值：`["opencode/deepseek-v4-flash-free"]`） |
| `diffTruncateLines` | 在截断前内联多少差异（始终可获取完整差异） |
| `verify` | 默认验证命令 |
| `denyList` | 额外的bash模式，在内置列表之上拒绝 |
| `allowedRoot` | 将所有`dir`参数限制在此根目录下 |
| `defaultAgent` | 未设置代理时使用的代理（默认值：`build`） |
| `pure` | 使用OpenCode的`--pure`，绕过全局OpenCode插件（默认值：`true`） |
## 安全
- 每个委托运行首先进行git checkpoint；`revert`将目录恢复到确切的状态。
- 目标目录中的`opencode.json`获得合并的拒绝列表和`external_directory: deny`（隔离） — 这些即使在`--auto`下也有效，因为`--auto`仅自动批准否则会询问的规则。 `doom_loop`被设置为`allow`，以便工作器可以自由迭代；失控循环被外部超时，无输出监视器和无进展/振荡检测捕获。
- 拒绝在文件系统/系统根目录或裸家目录上操作。
- 已知机密形状 — 和任何明确已知的机密值，如`OPENROUTER_API_KEY` — 从返回给克劳德的所有内容中删除。
- 时钟超时和无输出监视器杀死挂起的运行；选择加入自动重试循环检测无进展和振荡的差异并停止，而不是无限循环。
## 贡献
问题和PR欢迎 — 这是一个MVP，还有很多成长空间（成本/代币会计，并行委托，更丰富的差异总结，更多免费模型提供商）。
## 许可证
[MIT](LICENSE) 2026 Namit Nair
