Foreman
一个 Boris 风格的编排器 TUI:用门控交付管线监管无头 Claude Code 代理,从计划到 e2e 全程可信任合并。
- Star 数
- ★ 362
- 最近更新
- 4 个月前
- License
- NOASSERTION
- 主语言
- Python
- FA 评分
- 79/100 · 表现良好
30 秒速览
- 运行形态
- 可在哪里用
- 平台专用Claude Code
- 费用
- 软件免费,模型调用费用自付
- 上手难度
- 中 · 需要几步配置
- 开始前需要
- 典型场景
- 维护成熟代码库的工程师,想让人工守住设计门、把 TDD 实现交给有护栏的代理并行完成
- 不适合
- 不用 Claude Code CLI 或只用其他模型供应商的团队
- 需要 Windows/macOS 原生支持且不打算用 WSL2 的用户
- 只想单个对话式提示、不需要门控交付管线的开发者
- 维护状态
- 近半年有提交最近提交 2026-06-29
- 源码审查
- 79/100 · 表现良好
这个 Agent 能做什么,适合哪些场景?
Foreman(VisionForge-OU/foreman)是一个 MIT 许可的终端编排器,用 Textual 构建键盘驱动 TUI,通过在 stream-json 无头模式下启动本地安装的 claude CLI 来执行软件交付管线:plan → ADR/PRD → issues → TDD 构建 → e2e。设计阶段(计划、ADR/PRD)必须经过人工评审门,批准以正文 SHA-256 哈希封存,文档变更会自动失效;构建阶段则由编排器而非代理自身的自律来兜底。所有状态都是提交在目标仓库内的人类可读文件(.foreman/、.claude/skills/、.claude/agents/),没有数据库,崩溃后可从磁盘完全恢复。并行 worker 各自在独立的 git worktree 中运行,按声明的 touches 集合避免冲突,且被 PreToolUse 拒绝钩子阻止写入自己的 verification.json;合并门(证据、acceptance_check、test/lint/typecheck、回归棘轮)由 Foreman 自己执行。此外还有评测飞轮:foreman retro 聚类失败并起草技能/提示补丁,补丁必须通过 foreman bench 报告才能落地。
运行 foreman init 在目标仓库中脚手架 .foreman/ 目录并把 foreman-* 技能安装到 .claude/skills/。工作流:在 TUI 中按 n 新建功能(写 request.md);按 p 运行规划代理生成 plan.md;按 g 运行 foreman-grill-docs 技能产出 ADR 和 PRD 并列出『需评审者回答的开放问题』;按 v 在评审屏审批或要求修改(开放问题未答不可批准,哈希封存的批准在文档变化时自动失效);按 s 运行 foreman-to-issues 将 PRD 切成带 acceptance_check、touches、prd_refs 的小粒度 issue 文件;按 c 确认队列后按 b 启动自主构建循环(Boris loop):初始化器写 init.sh 和 feature-state.md,每个就绪 issue 由 foreman-tdd worker 在自己的 git worktree 中以红-绿-重构方式实现,经 foreman-test 运行测试并把证据存到 runs/<id>/evidence/。Foreman 自行执行合并门:验证证据真实、acceptance_check 通过、全量 test/lint/typecheck 通过、回归棘轮不退步;随后只读 evaluator(独立 --agent、新上下文)按 1–5 评分,反对意见弹回新 worker,不确定或反复分歧则升级到 Attention 队列。全部 issue 合并后运行 e2e 代理和只读 auditor 逐条核对 PRD,偏差会起草重新进入哈希封存评审门的 PRD 修订。治理包括 per-run max_turns/max_cost_usd/timeout_min、每 issue max_retries、max_parallel、带硬停的每日成本上限,以及阻止 worker 写 verification.json 的 PreToolUse 拒绝钩子。foreman retro / foreman bench / foreman status 提供评测与补丁治理,foreman --demo 和 foreman demo 用 MockBackend 在零 token 下演练全管线。
- 维护成熟代码库的工程师,想让人工守住设计门、把 TDD 实现交给有护栏的代理并行完成
- 需要可审计交付记录的团队:每次运行的证据、验证与评审状态都以文件形式提交在仓库内
- 在意失控代理风险的开发者:需要每日成本上限、per-run 预算和 Foreman 自执行的合并门
- 用 Claude Code 但被逐次提示拖累的人:改为『循环驱动 Claude』的编排工作流
- 想持续改进代理行为的人:用 retro/bench 飞轮把重复失败聚类成必须过基准测试的技能/提示补丁
- 想在花费任何 token 前完整评估工作流的用户:foreman --demo 用模拟后端零成本演示全部门与界面
安装与配置要点
摘自下方的安装和使用说明,以项目 README 的最新说明为准。
- 安装 / 启动命令
pipx install . # 或: uv tool installpipx install
- 配置文件
.foreman/config.yaml- 运行环境
- Python 3.11+
- 安装说明涉及
- Linux · WSL
如何安装或部署这个 Agent?
需要 Python 3.11+、已安装并认证的 claude CLI(claude --version 验证)、git;开发与测试环境为 Linux/WSL2(Ubuntu)。
# 安装(暴露单一 foreman 命令)
pipx install . # 或: uv tool install .项目发布在 PyPI(包名 foreman-orchestrator),也可以直接从仓库安装。
git clone https://github.com/VisionForge-OU/foreman
cd foreman
pipx install .如何使用这个 Agent?
# 指向任意仓库
cd /path/to/your/repo
foreman init # 脚手架 .foreman/ 并把 foreman-* 技能装入 .claude/skills/
# 零 token 端到端体验
foreman demo # 用 MockBackend 在一次性样例仓库上跑完整管线
# 真实工作
foreman # 启动 TUI(等价于 foreman tui)
foreman --demo # 用模拟后端启动 TUI在 TUI 中用键盘驱动整个流程:n 新建功能 → p 运行规划器 → v 评审计划 → g 运行 grill(生成 ADR+PRD)→ v 评审文档 → s 切片成 issue → c 确认队列 → b 启动构建;w 查看实时 worker 日志,x 处理升级,m 看指标,t 管理补丁门。
CLI 命令:
foreman status # 查看技能/代理状态与功能
foreman init --force # 重建配置并重装技能/代理
foreman build # 恢复/继续自主构建
foreman retro # 聚类失败 → 门控补丁草案
foreman bench # 回放评测集,报告成功率/成本/回合变化模型与限额在 .foreman/config.yaml 中按角色配置(model_planner、model_worker、model_evaluator、model_auditor、limits、run_budget 等)。
这个 Agent 有哪些优点和局限?
- 门控而非自律:评审批准用 SHA-256 哈希封存并自动失效,合并门(证据 + acceptance_check + test/lint/typecheck + 回归棘轮)由 Foreman 自己执行,从不信任代理自报
- 崩溃安全且可审计:全部状态是提交在仓库内的人类可读文件,无数据库、无守护进程,中断后从磁盘恢复
- 真正的资源护栏:per-run 回合/成本/超时预算、每日成本硬停上限、PreToolUse 钩子阻止 worker 写自己的验证、心跳锁防止重复认领
- 评测飞轮内建:运行结果标注、指标面板、retro 补丁必须通过 bench 报告才能落地
- 零成本试用:foreman --demo / foreman demo 用模拟后端完整演示管线,测试套件全程离线运行
- 运行时锁定 Claude Code:核心操作依赖本地安装并认证的 claude CLI,无其他模型后端
- 平台约束:文档明确以 Linux/WSL2(Ubuntu)为开发与测试路径,其他系统仅『应该可以运行』
- 真实运行产生持续 token 成本:每个规划/评审/构建/评测阶段都消耗 claude API 用量,且 retro/bench 是长时高消耗运行
- 安装需从源码/本地构建(pipx install .),不是单条 npm/pip 包名安装;仓库元数据显示 License 为 NOASSERTION,需自行查阅 LICENSE/NOTICE 确认
- 学习成本:门控管线、touches 冲突集、config.yaml 多角色模型配置等概念需要时间掌握
这个 Agent 与同类方案有什么区别?
README 将 Foreman 定位为『在 while 循环里跑编码代理很容易,跑一个可信任合并的不容易』的中间监督层——即它与直接循环运行 Claude Code 的做法对比:Claude Code 提供单代理执行,而 Foreman 在其上叠加门控管线、worktree 隔离并行、Foreman 自执行的合并门与评测飞轮。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| Foreman 当前 | 79 · 表现良好 | 命令行工具免费 + 模型费 | ★ 362 | 4 个月前 | Python | Claude Code |
| Open Swarm 智能体集群控制台 | 证据不足 | — | ★ 826 | 1 个月前 | JavaScript | Claude API |
| MoAI 开发编排器 | 61 · 存在缺口 | 命令行工具免费 + 模型费 | ★ 1.3k | 9 天前 | Go | Claude Code |
| GameDesignOS:本地优先的游戏设计操作系统 | 71 · 存在缺口 | 命令行工具免费 | ★ 459 | 3 个月前 | Python | Codex · Claude Code |
FollowAgents 如何评估这个 Agent?
查看各维度的扣分理由
安全设计在同类项目中突出:人工评审门、哈希封印的批准(文档改动自动失效)、PreToolUse deny hook 阻止 worker 写自有验证状态、worktree 隔离、每轮/每日费用上限。user_confirmation 满分——设计阶段全部人工门控,foreman run 必须显式 --auto-approve。least_privilege 与 rollback 得 2:worktree 与钩子限制属实,但'钩子在 acceptEdits 下已被证明有效'是断言,包内未见钩子源码或证明;对目标仓库的 commit/merge 回滚路径只一句带过。sensitive_data_handling 仅 1:AGENTS.md 提示不要提交含密钥的 transcript,产品本身对 API key、transcript 中敏感数据的处理无任何机制。external_effects 得 2:会 spawn 本地 claude CLI、向用户仓库提交合并,README 如实描述但未经执行验证。
self_consistency 满分:README 的按键表、阶段名、文件布局与 cli.py/tui/app.py/测试代码高度一致,状态机文档与实现互相印证。dependency_availability 2:依赖极少(textual、pyyaml),但硬依赖本地已认证的 claude CLI 且仅声明 Linux/WSL2 测试过,跨平台可用性未知。failure_messages 2:CLI 对未初始化、缺 --slug、缺 --auto-approve 有清晰提示,TUI 有 notify 错误通道,但 Agent 运行失败路径(HeadlessError 之外)证据有限。
audience_and_scenarios 满分:目标用户(想在任意仓库上编排 Claude Code 的开发者)明确,demo/mock backend 面向零成本试用场景。trigger_precision 满分:四个 SKILL.md 的触发条件、输入注入、输出契约写得非常精确(何时升级、何时停止、不发自己的 SUMMARY)。capability_boundaries 2:明确 Phase 3 未实现、worker 沙箱化计划中,但对权限模式、容器建议之外的能力边界陈述偏少。environment_fit 2:Python 3.11–3.13 矩阵 CI,但坦承只在 WSL2/Ubuntu 上开发测试。
information_architecture 满分:README 目录、文件布局、配置样例、AGENTS.md 贡献指南一应俱全。install_notes 满分:pipx/uv 安装、需求、5 分钟快速启动齐全。naming_stability 满分:foreman-* 前缀强制命名空间化,避免与上游技能冲突。license 满分:MIT + NOTICE 归属上游技能。examples_and_faq、versioning_changelog 各 2:FAQ 覆盖成本/数据库/模型,但 CHANGELOG.md、DECISIONS.md、NOTICE、config.sample.yaml 在本包中均被引用而未提供,无法核实内容;已知局限仅以路线图形式呈现(known_limitations 1),无运行限制、已知 bug 的专门说明。maintenance_responsibility 2:CI/发布工作流完善(tag 校验、Trusted Publishing),作者为个人(ehsantg),无明确维护承诺。
output_usability 满分:TUI 键位完整文档化,状态全部为人类可读文件落盘。marginal_value 满分:把'信任到可合并'作为核心价值主张,评审门、回归棘轮、eval 飞轮在同类循环器中确有差异化。cost_benefit 2:设计上大量 agent 运行(grill、retro、bench、多 worker)本身消耗可观 token,demo 缓解了试用成本,但实际收益只有断言,无公开基准数据。
claim_traceability 2:'proven to hold under acceptEdits'、'crash-safe'、'fully recovers' 等强断言无法在静态包内溯源到证明。cross_source_corroboration 2:README 与 cli.py、tui/app.py、dogfood 测试在键位、阶段、预算逻辑上互相印证,但 CHANGELOG/NOTICE/DECISIONS 缺失使部分声明悬空。fact_inference_separation 满分:SKILL.md 明确标注改编来源与修改内容,路线图明确区分已实现/未实现。
- 以静态审阅为据:所有运行期声明(钩子拦截、崩溃恢复、费用上限)均未经执行验证。
- 产品会向你的真实仓库提交与合并代码,并对 claude CLI 发起真实付费调用——首次使用建议在一次性仓库或容器内运行。
- 敏感数据处理几乎空白:claude transcript 可能含密钥,仅靠贡献指南提醒,产品无脱敏或隔离机制。
- 仅声明在 WSL2/Ubuntu 下测试,其他平台可用性未知。
- CHANGELOG.md、NOTICE、DECISIONS.md 在审阅包中缺失,相关声明无法核实。
- 发布方未经验证(License 元数据 NOASSERTION),企业环境采用前应自行确认供应链。
常见问题
试用要花钱吗?
需要数据库或服务器吗?
仓库会不会被失控代理破坏?
支持哪些模型?
能在 Linux 之外用吗?
Foreman 开源吗?
Foreman 安全吗?
Foreman 还在维护吗?
Foreman 是谁开发的?
谢谢反馈,我们会据此改进页面。