Foreman

<div align="center"> <img src="assets/brand/banner.png" alt="Foreman — a small white robot inspecting your agents' work with a magnifying glass, thinking: Prove it." width="100%"> **您的AI工作队伍的审核收件箱** *您的代理说“完成”。Foreman 说“证明”。* [](https://www.npmjs.com/package/foremanjs) [](https://github.com/rohitkumarmanne-442/foreman/blob/main/src/test/smoke.test.ts) [](https://nodejs.org) [](#connect-your-agent) [](#local-first-by-design) [](LICENSE) </div> --- 您让AI代理编写代码。它们产生的变更比任何人类都多，所以您快速浏览，批量审核 — 有一天，代理重写了一个869行的生产应用程序，缩减到97行，宣布 *"一切正常！"*，然后强制推送，而您却没注意到。 这种情况曾经发生在我身上。Foreman 的存在就是为了让这种情况不再悄悄发生。 Foreman 的全部理念都体现在它的思维云中：**“证明”。** 您的代理提出的每个声明都会被检查是否与它们实际执行的操作相符。 ## Foreman 的 11 秒演示  *您刚刚看到的内容：一个关键卡片（强制推送 + 89% 文件重写 + 未验证的“一切正常”），点击查看差异，审阅者标记它并附上注释 **该注释将被注入到代理的下一个会话**，以及 ed25519 签名的 MCP 收据日志。*  ## 刚刚发生的事情，浓缩在一屏之内 上面的代理结束了它的会话，说道 *"一切正常，结账流程完全功能正常。完成！"* Foreman 的卡片却讲述了一个不同的故事： | 代理版本 | Foreman 记录的内容 | |---|---| | “一切正常” | **运行零验证命令** — 声明未经验证 ❓ | | “简化 app.py” | 重写 **869 → 97 行** （89% 文件被删除） | | *(未提及)* | `git push --force origin main` | 每个代理会话都变成一个 **审核卡片**，按风险等级排序，放入一个本地收件箱，您可以像使用电子邮件一样处理：**✓ 批准** 安全的操作，**⚑ 标记** 不安全的操作 — 附带注释，代理将在下一个会话中阅读。收件箱为空意味着每个 AI 变更都经过了人工审核。 ## 诚实的数字 Foreman 是一个观察者，所以唯一重要的数字是它为您节省的和它捕获的数字： - **0 代币**。Foreman 从不触及您的提示或模型账单。（有一个例外，您可以自行选择：标记会话的注释被注入为上下文 — 这就是目的。） - **~120 毫秒每钩事件** — 普通 Windows 笔记本电脑上 15 次冷运行的中位数，几乎所有时间都花在 Node 进程启动上，而不是工作上。钩子记录并退出；它们不能阻塞、破坏或减慢代理的推理。 - **规则捕获的内容：** 21 种破坏性命令模式，14 种秘密格式，大规模重写（整个文件和单次编辑），敏感路径，失败后声称成功，以及 MCP 工具定义偏移。每个检查都运行在代理 **实际执行** 的记录上 — 而不是凭感觉。 - **26/26 端到端测试**，包括：篡改的收据失败签名验证，重排序的日志破坏哈希链，被拒绝的伪造团队包，以及实际的无头会话生成关键卡片。 没有基准测试：观察者无法让您的代理更快或更便宜。它让 **您** 更快 — 您花 10 分钟处理危险会话，花 10 秒修复 README。 ## 工作原理 ```text Claude Code 钩子 ──┐ Cursor 钩子 ───────┤ Gemini CLI 钩子 ───┤ OpenCode 插件 ────┤ ┌─→ 审查卡片，按风险排序 → 收件箱（Foreman UI） Codex 通知 ───────┼─→ ~/.foreman/*.jsonl ───┼─→ 标记和注释 → 返回代理（Foreman 简报） Foreman 运行 ────────┤ 追加日志 ├─→ CI 门控（Foreman 门控） Foreman 监视 ──────┤ └─→ 审计报告（Foreman 报告） Foreman 包装 ───────┘ └─ ed25519 签名，哈希链收据 + 工具指纹 ``` 无守护进程，无数据库，无帐户。日志是纯 JSONL，您可以 grep；收件箱是一个本地页面，实时读取日志；收据独立验证 `foreman verify`. ## 安装 ```bash npm install -g foremanjs foreman demo && foreman ui # 30 秒内生成一个已填充的收件箱 ``` 需要 Node 18+。随时使用 `foreman demo --clear` 删除示例数据。 ## 连接您的代理 <details> <summary><b>Claude Code</b> — 钩子，丰富的数据</summary> ```bash cd your-project foreman init ``` 将钩子添加到 `.claude/settings.json`。每个新会话都会提交一个包含差异、命令、声明的卡片 — 并在启动时接收您未完成的标记作为上下文。`foreman init --global` 涵盖所有仓库；`--agent claude` 仅为 Claude Code 安装。 </details> <details> <summary><b>Cursor</b> — 钩子（Cursor 1.7+）</summary> ```bash cd your-project foreman init ``` 将 Foreman 添加到 `.cursor/hooks.json`：shell 命令、文件编辑、MCP 调用和会话结束根据 [Cursor 钩子 API](https://cursor.com/docs/hooks) 被捕获。 `--agent cursor` 仅为 Cursor 安装。 </details> <details> <summary><b>Gemini CLI</b> — 原生钩子，包含反馈环</summary> ```bash cd your-project foreman init ``` 根据 [Gemini CLI 钩子参考](https://github.com/google-gemini/gemini-cli/blob/main/docs/hooks/reference.md)，Foreman 被添加到 `.gemini/settings.json`：shell 命令、文件写入/编辑和会话结束都会变成卡片数据 — 您的未完成标记作为 `SessionStart` 的上下文注入，Gemini 获得与 Claude Code 相同的反馈环。 `--agent gemini` 仅为 Gemini 安装。 </details> <details> <summary><b>OpenCode</b> — 原生插件</summary> ```bash cd your-project foreman init ``` 将插件放入 `.opencode/plugins/` （根据 [OpenCode 插件 API](https://opencode.ai/docs/plugins/) 自动加载），将 bash/edit/write 事件转换为 `foreman ingest`。 `--agent opencode` 仅为 OpenCode 安装； `--global` 使用 `~/.config/opencode/plugins/`。 </details> <details> <summary><b>Codex CLI、Copilot CLI、aider — 任意终端代理</b></summary> 通过 Foreman 启动代理。它的 TTY 未被触及；当它退出时，卡片关闭： ```bash foreman run --name codex -- codex foreman run --name copilot -- copilot foreman run --name aider -- aider ``` **Codex 奖励** — 捕获 Codex 在每次对话结束时 **声明** 的内容（提供声明与证据的对比）。在 `~/.codex/config.toml` 中： ```toml notify = ["foreman", "hook", "codex"] ``` </details> <details> <summary><b>Windsurf、JetBrains AI 或其他</b> — 通用监视模式</summary> ```bash cd your-project foreman watch ``` 无需钩子：Foreman 差异化 git 工作树并记录任何工具做的每个更改。检测大规模重写、秘密和敏感路径； `Ctrl+C` 关闭卡片。需要项目是 git 仓库。 </details> <details> <summary><b>您自己的工具 / Foreman 尚不支持的代理</b> — 20 行适配器</summary> 任何可以发出 JSON 的内容都是一个一流的适配器。将规范化的事件输送到 `foreman ingest`（一个对象、数组或 JSONL）： ```bash echo '{"agent":"mytool","session":"s1","kind":"command","command":"npm test","ok":true}' | foreman ingest echo '{"agent":"mytool","session":"s1","kind":"file","file":"src/a.ts","lines_before":120,"lines_after":10}' | foreman ingest echo '{"agent":"mytool","session":"s1","kind":"end","message":"All tests pass."}' | foreman ingest ``` 三种类型 — `command`、`file`、`end` — Foreman 派生其他所有内容：风险评分、声明与证据的对比、差异（发送 `content` / `edits`）、工作。 当代理提供原生钩子 API 时，首方适配器只是一个转换层 — 欢迎 PR。 </details> <details> <summary><b>MCP 服务器</b> — 签名收据 + 防拉 rug 检测</summary> 在您的代理的 MCP 配置中，添加服务器命令前缀： ```jsonc // 之前 { "command": "npx", "args": ["@someone/github-mcp"] } // 之后 { "command": "foreman", "args": ["wrap", "--name", "github", "--", "npx", "@someone/github-mcp"] } ``` 查看 [MCP 认证](#mcp-attestation-make-tool-calls-provable) 以了解您获得的内容。 </details> 然后打开收件箱并保持打开 — 卡片实时出现： ```bash foreman ui # → http://127.0.0.1:4517 ``` 键盘优先：`j`/`k` 导航 · `a` 批准 · `f` 标记 · `/` 搜索 · `?` 帮助。 **新来者？** 您的第一次访问会启动 **60 秒引导游览**，重点介绍屏幕上的每个选项 — 风险评分的含义、声明与证据的工作原理、标记的位置。随时从 `?` 帮助菜单重新启动它。 ## 反馈环：标记教导代理 批准是一半的工作。 **标记关闭环路。** 标记会话并附加注释 — *“绝不强制推送。还原 app.py 并进行外科手术编辑。”* 从那时起： - **Claude Code** — 该仓库中的每个新会话在开始工作之前都会接收您的标记、注释和确切的发现作为上下文（SessionStart 钩子）。 - **其他所有** — `foreman brief` 打印相同的反馈；将其粘贴或指向您的规则文件。 批准或取消标记，简报就会静默。您的审核不再是废弃的否决，成为训练信号。 ## 在 CI 中阻塞您的 CI ```bash foreman gate # 存在未批准的高/关键会话时退出 1 foreman gate --level critical # 仅在关键时阻塞 ``` 将其放入 pre-push 钩子或 CI 作业中：**代理编写的更改在生成它们的生产会话获得批准之前不会发布。** 它会打印哪些会话正在阻塞，并忽略演示数据。 ## 将证据放到 PR 上 审阅者不应仅凭“代理测试了”而相信。 一个命令将一个会话变成 PR 评论，包含收据 — 风险评分、声明与证据的对比、发现、文件、验证命令： ```bash foreman pr # 在当前分支的 PR 上评论（通过 gh） foreman pr --pr 42 # 特定 PR foreman pr --print # 打印 markdown — 粘贴到任何地方（GitLab、电子邮件...） ``` 收件箱与 **📋 PR 评论** 按钮在每个卡片上。批准的卡片会显示这样做；标记的卡片会携带您的注释。您的 PR 审查从证据开始，而不是凭感觉。 ## 实时在您的菜单栏中 ```bash foreman tray # Windows · macOS · Linux ``` 在您的栏中运行收件箱服务器无头并带有存在感： - **Windows** — 一个真正的托盘图标（WinForms NotifyIcon）：实时工具提示计数、新关键卡片的气球点击打开、退出停止。 - **macOS** — Foreman 编写一个 [xbar](https://xbarapp.com)/SwiftBar 插件，将 🧑‍🏭 实时计数放入您的实际菜单栏（下拉菜单中的顶部会话，点击查看收件箱），以及使用 `osascript` 的原生通知程序，用于新的关键卡片。 - **Linux** — 通过 `yad` 安装托盘图标，通过 `notify-send` 进行关键卡片通知。 每个平台上的零 npm 依赖。 ## MCP 认证：使工具调用可证明 MCP 的 `tool_calls → tool_result` 循环在诚信系统上运行 — 没有证据证明服务器做了它声称的事情，也没有注意到服务器悄悄 *更改其工具说服的内容*。包装服务器会得到： - **签名收据** — 每个 `tools/call` 都记录了 SHA-256 参数和结果的哈希、延迟、结果 — **由一个从不离开您机器的密钥进行 ed25519 签名**。 - **哈希链接链** — 每个收据都提交到前一个哈希的哈希。编辑收据会破坏其签名； **删除或重新排序历史记录会破坏链条。** `foreman verify` 检查两者并指出更改的确切收据。 代理和服务器永远不知道它存在。 ## 团队模式：git 是同步层 ```bash foreman team sync git add .foreman-team && git commit -m "foreman packs" && git push``` 将此仓库的审阅卡片导出为 **ed25519 签名包**，并导入它找到的每个队友包 — 失败签名验证的包被直接拒绝。队友卡片在您的收件箱中显示 👥 所有者徽章。审查权限保留本地：您为您审批。 ## 命令 | 命令 | 它做什么 | |---|---| | `foreman init [--agent claude\|cursor\|gemini\|opencode\|all] [--global]` | 为此仓库（或所有仓库）安装原生钩子 | | `foreman ui [--port 4517]` | 打开审阅收件箱 | | `foreman run [--name X] -- <cmd…>` | 监督任意终端代理进行一个会话 | | `foreman watch [path]` | 连续监视一个仓库 — 任意 IDE，任意工具 | | `foreman brief [path]` | 打印未完成的标记（代理读取此内容） | | `foreman gate [--level high\|critical]` | 存在未批准的风险会话时退出 1 | | `foreman pr [--pr N] [--session id] [--print]` | 在 PR 上发布会话证据注释 | | `foreman tray` | 菜单栏/托盘收件箱（Windows/macOS/Linux） | | `foreman ingest` | 从任何工具规范化 JSON 事件（stdin） | | `foreman wrap --name <srv> -- <cmd…>` | 认证一个 MCP 服务器 | | `foreman trust <srv>` | 重新基线服务器的工具定义 | | `foreman verify` | 验证每个签名 + 链条连续性 | | `foreman team sync` | 通过仓库交换签名卡片包 | | `foreman report [--out audit.md]` | 每会话的 markdown 审计 | | `foreman status` | 终端中的一屏总结 | | `foreman demo [--clear]` | 展示/删除展示数据 | | `foreman config` | 显示路径 + 活动设置 | | `foreman config` | 显示路径 + 活动设置 | | `foreman uninstall [--global]` | 删除钩子（您的日志仍在） | ## 风险规则 | 规则 | 严重程度 | 触发条件 | |---|---|---| | `destructive_command` | 关键 | `rm -rf`，强制推送，`git reset --hard`，`DROP`/`TRUNCATE`，`DELETE` 无 `WHERE`，`kubectl delete`，`terraform destroy`，... | | `mass_rewrite` | 关键 | 一个大于 50 行的文件重写为小于 40% 的大小 — 整个文件或单个编辑（阈值可配置） | | `secret_in_code` | 关键 | AWS · Anthropic · Stripe · GitHub · GitLab · Google · Slack · SendGrid · npm 密钥，私钥，JWT，硬编码密码 | | `failed_verification` | 关键 | 代理在自身检查失败后声称成功 | | `unverified_claims` | 高 | 代理声称成功但从未运行任何可能证明它的操作 | | `sensitive_path` | 高 | `.env`，机密，身份验证，迁移，CI 工作流，`.ssh`，`.npmrc` 触及 | | `mcp_tool_drift` | 高 | MCP 服务器与其受信任基线相比发生变化 | | `untested_change` | 中等 | 代码已更改，但未执行任何操作 | | 声明检测是反向意识的：*“测试失败”和“应该现在有效”永远不会被算作成功声明。* 发现重复，成功声明如果没有代码更改则得分较低（可能是 Q&A）。 | ## 调整 `~/.foreman/config.json`（`foreman config` 显示路径和实时值）： ```jsonc { "port": 4517, "ignore": ["node_modules/", "dist/", "*.lock", "generated/"], // 永远不要跟踪这些路径 "disable_rules": ["untested_change"], // 您不想的规则 "mass_rewrite_min_lines": 50, "mass_rewrite_ratio": 0.4, "notify_command": "powershell -c \"[console]::beep(880,300)\"" // 每当出现新的关键卡片时运行 // 通知命令 env: FOREMAN_SESSION, FOREMAN_LEVEL, FOREMAN_SCORE, FOREMAN_REPO } ``` ## Foreman 对比 相邻工具解决相邻问题 — 大多数团队将需要超过一种工具： | | 护栏（策略引擎，沙盒） | 评估环境（代理基准测试） | 代码来源（“git blame for AI”） | **Foreman** | |---|---|---|---|---| | 行为 | **之前** 操作 | 离线，在测试任务中 | 提交后 | **操作后，在您信任它之前** | | 保护免受 | 已知不良操作 | 代理质量回归 | 不清楚的归属 | **未经审查的更改 + 未经证明的声明** | | 声明 vs 证据 | — | — | — | **✓** | | MCP 调用签名记录 | 部分代理身份检查 | — | — | **✓ 哈希链收据** | | 将人类决策反馈给代理 | — | — | — | **✓** | | 适用于任何代理 | 取决于 | 特定于环境的 | 特定于编辑器 | **✓ 钩子 + 运行 + 监视** | 护栏限制机器。Foreman 让人类更快 — 审查能力是瓶颈，护栏无法触及。 ## 本地优先，按设计 - 所有内容都位于 `~/.foreman/` 作为纯 JSONL — 可 grep，可 diff，可删除，属于您。 - 收件箱仅绑定到 `127.0.0.1`。无服务器，无帐户，无遥测，无异常。 - 钩子记录并以毫秒为单位退出，即使在内部失败的情况下 — 代理永远不会被 Foreman 阻塞。 ## 常见问题 **我的代码会离开我的机器吗？** 绝不会。只有您选择提交的内容（`foreman team sync` 打包）或粘贴（`foreman report`）才会离开。 **会减慢我的代理速度吗？** 大约 120 毫秒每次钩子事件，这就是 Node 启动的时间。您的模型在两个令牌之间执行的操作远不止于此。 **为什么不直接读取代理自己的摘要？** 摘要是代理对其自身作业的评分。“所有测试通过”和 *运行零测试* 经常在同一会话中出现 — 这正是 Foreman 所关注的。 **它会阻塞任何内容吗？** 默认情况下不会 — Foreman 进行观察。如果您 *需要* 强制执行，则 `foreman gate` 在 CI 中会阻塞合并，直到会话获得批准。值得信赖的观察比您关闭的强制执行更好。 **对于它不了解的代理怎么办？** `foreman run -- <anything>` 和 `foreman watch` 不关心工具是什么。如果它编辑了 git 仓库中的文件，则它就会被覆盖。 **聪明的代理能欺骗它吗？** 代理无法撤销强制推送或撤销写入 20 行文件（之前有 869 行） — 日志记录了操作，而不是叙述。声明检查是启发式的（正则表达式，感知否定），并且会改进；将 UNVERIFIED 视为“仔细查看”，而不是判决。 **如何删除所有内容？** 在每个仓库（或 `--global`）中运行 `foreman uninstall`，然后删除 `~/.foreman/`。完成。 **Windows？macOS？Linux？** 这三个平台都支持。Foreman 是在 Windows 上开发的，通常是那个容易出问题的平台。 ## 卸载 ```bash foreman uninstall # 删除此仓库的钩子 foreman uninstall --global # 删除用户级钩子 npm uninstall -g foremanjs # 删除 CLI # 您的数据：随时删除 ~/.foreman/ — 它只是 JSONL ``` `uninstall` 仅删除 Foreman 自己添加的钩子条目；其余的设置文件保持不变。 ## 开发 ```bash git clone https://github.com/rohitkumarmanne-442/foreman cd foreman npm install npm test # 构建并运行 19 个端到端测试 ``` 零运行时依赖 — TypeScript、Node 标准库和一个用于 inbox 的静态 HTML 文件。测试套件为钩子生成真正的子进程，通过代理驱动一个假的 MCP 服务器，为观察者初始化 git 仓库，并伪造一个团队包以证明它被拒绝。欢迎提交 PR；保持高标准。 ## 路线图 - [x] Claude Code + Cursor + Codex 适配器 · `foreman run` · 通用监视模式 - [x] 批准/标记工作流、差异查看器、风险引擎、审计报告 - [x] 反馈环 — 将标记注释注入代理的下一个会话 - [x] 哈希链接的收据链 · 团队包 · CI 门 · 关键卡通知 - [x] PR 回写 — `foreman pr` 在拉取请求上发布会话的证据 - [x] 通用适配器 API (`foreman ingest`) — 任何工具都可以 20 行代码成为适配器 - [x] 原生适配器：Claude Code · Cursor · **Gemini CLI** · **OpenCode** · Codex 通知 - [x] **Windows、macOS (xbar/SwiftBar) 和 Linux (yad) 上的菜单栏/托盘**，带有关键卡警报 - [ ] 随着更多代理交付钩子 API（每个都是 `foreman ingest` 的一层薄薄的封装），将有更多原生适配器 ## 许可证 MIT — 您可以随心所欲，但请保留声明。