thruwire/foreman
一、一句话定位
Foreman 是一个用 TypeSafe AI 的 Jev 模型监督 Codex 编码 agent 的异步运行时，相当于在“软件工厂”里放一个快速监工，独立评估慢速 worker 的产出与状态。
二、核心技术/架构亮点
- 双循环并发架构：Codex worker 循环与 Foreman 监督循环并行，worker 无需停下即可被持续观察。
- 语义监督：将九个问题（实现完成度、测试充分性、需求满足度、是否卡住、是否偏航等）打包成一次 Jev 并行请求，获得概率化判断。
- 确定性策略门控：Jev 只评估，Python 策略按安全优先级决定 continue/stop/retry/verify/finish/escalate。
- 可替换 worker：运行时只依赖小型 worker 协议，不绑定 Codex 专用类型。
- 有界观察上下文：如 20k diff、12k 输出尾部、30 条事件，避免把整个仓库塞给模型。
三、适用场景与目标用户
适合构建 coding-agent harness 的开发者，或研究多 agent 监督、任务可靠性验证的 AI 工程团队。典型场景：长任务需要持续判断进度、卡死、偏航、是否需要人工介入。
四、可动手动作
- `git clone https://github.com/thruwire/foreman`，阅读 `docs/theory.md` 和 `docs/runtime.md`。
- 配置 Python 3.11+、Codex CLI 和 `TYPESAFE_API_KEY`；先跑无需外部服务的 deterministic demo 与测试。
- 修改 `FactoryConfig` 中的观察上限、轮询间隔等，跑通 `codex exec` 启动的真实 worker 实验。
- 参考其 worker 协议，把 Codex 替换为自己的编码 agent，复用小监控层逻辑。
五、学习优先级
P1（排期）：架构思想很有价值，但依赖 Jev 与 Codex 外部服务，适合两周内落地 demo 验证；无需本周立刻动手。⌂