agent-foreman-mcp

v1.0.0

Published

a month ago

面向任意 MCP 宿主的通用 AI-Agent 编排 MCP server —— 驱动 Codex 桌面端、TraeWork GUI 与 ZCode GUI 完成项目开发、验收、失败返修与再验收闭环。

0High
0Medium
0Low

lotteai

mcp model-context-protocol ai-agent orchestration mcp-orchestration codex zcode traework

agent-foreman-mcp

面向任意 MCP 宿主的通用 AI-Agent 编排 MCP server

由你选择的 MCP 宿主（Claude Desktop / Cursor / ZCode / Cline / Windsurf 等）接入，作为标准 MCP server，调度外部 AI-Agent（Codex 桌面端、TraeWork / TRAE SOLO CN、ZCode 均经 CDP 驱动桌面 UI）完成 项目开发 → 验收 → 失败返修 → 再验收 的闭环。

视觉验收（含可选 AI 内容校验）：中文指南 · 验证状态

English · 简体中文

这是什么

宿主（任何 MCP 宿主）是指挥；本 MCP server 是调度层 + 执行面 + 客观验收仪；外部 AI-Agent（Codex / TraeWork / ZCode GUI）是执行开发的「工人」。server 本身不绑定任何特定宿主——凡支持 stdio 传输的 MCP 宿主都可接入，接入方式见宿主接入指南。

11 个 MCP 工具：run_task / continue_task / query_task / list_tasks / get_task_report / cancel_task / verify_task / rework_task / get_profiles，外加视觉验收的 prepare_visual_baseline / approve_visual_baseline。
双轨返回：结果同时以「人类可读文本 + ---agent-foreman-meta--- JSON 块」与 MCP 标准 structuredContent 投递，同一份字段、单一事实来源。旧式宿主可正则抽取文本块，现代宿主可直接消费结构化字段；工具已声明 outputSchema，字段名稳定且只增不改。
异步契约：run_task 秒回 taskId，长任务用 query_task 轮询（长任务不卡 tools/call）。
客观验收：自动命令检查（typecheck/lint/test/build，缺则跳过 + 技术栈推导）+ 程序化代码分析（变更清单/diffstat/TODO·debugger·密钥形态等可疑标记），全部相对 git 基线，不自动 commit/stash。验收引擎 fail-closed：测试命令退出码为 0 但输出显示零用例时判失败；git 项目默认要求相对动工前基线产生变更（纯分析任务可在 .agent-foreman/acceptance.json 设 "requireChanges": false 显式关闭）。
验收并行度：命令检查默认有界并行（verifyConcurrency，默认 2、范围 1–4）。检查项之间有顺序依赖时（后续检查读取 build 产物、带 --fix、共享缓存目录）请设 1 完全退化为串行；项目级 .agent-foreman/acceptance.json 可覆盖，server 级在 config.json。报告与日志格式不变（结果按声明顺序返回）。
失败返修闭环：自动返修（autoFixRounds）+ 手动 rework_task；验收失败时自动生成修复计划文件（默认落在项目内 .agent-foreman/plans/）并回填给 agent；轮次用尽 → needs_attention 等宿主裁决。
执行面：driver: "gui" 由显式 adapter 驱动桌面 UI（Codex / TraeWork / ZCode 各自使用隔离的 CDP 流程）；driver: "spawn" 走外部 CLI 子进程。
无项目派发（ZCode）：run_task 的 projectPath 可省略——ZCode 在 default 工作区承接任务，不登记/导入项目、不采集 Git 基线、不执行项目验收（结果以 verificationNotApplicable: "no_project" 结构化标注，verify_task/get_task_report 返回不适用说明）。配套 allowCreateProject: false 可在目标目录未登记时于任何导入副作用之前停止派发。详见 ZCode CDP 适配器。
调度纪律：每项目串行队列 + 全局并发上限（默认 2，可配）。
可选 AI 内容校验（默认关闭）：校验图片或页面截图内容是否符合你显式声明的期望描述。判定完全委托给你自备的本地命令（MCP 不读取、不存储、不转发任何密钥，也不内置模型客户端），默认仅告警、逐规则可升级为致败；采样多数票 + 任务级缓存防抖，票不集中或低于置信度阈值判 uncertain（永不阻塞、不触发返修）。配置与命令契约见视觉验收。
不碰密钥：各 agent 用自己的登录态；本 server 不保存/转发任何 API key。可选 AI 内容校验同样不引入凭证管理——判定命令自己管密钥（见 SECURITY.md）。
可扩展：新 agent = 一个 profile（数据）+（如需）一个 adapter 文件，零改编排核心。
想理解内部结构：见 ARCHITECTURE.md（分层模型、模块边界、状态机、验收流水线、扩展点与已知缺口）。

快速开始

前置条件

| 项 | 要求 | |---|---| | Node.js | ≥ 20（CI 覆盖 20 / 22 / 24） | | 包管理器 | npm（仓库含 package-lock.json） | | 操作系统 | Windows / macOS / Linux（CI 三平台矩阵验证） |

被驱动的 agent 需按需自行安装：Codex 桌面端 / TraeWork（TRAE SOLO CN）/ ZCode 桌面端（GUI 驱动），或 codex CLI（无头路径，见下）。本 server 不需要它们的任何密钥。

安装 npm 包

npm i -g agent-foreman-mcp
# 或免安装直接用
npx -y agent-foreman-mcp

接入你的宿主

在宿主的 MCP 配置里加一段 stdio server（键名视宿主而定，通常为 mcpServers）：

{
  "mcpServers": {
    "agent-foreman": {
      "command": "npx",
      "args": ["-y", "agent-foreman-mcp"]
    }
  }
}

各宿主（Claude Desktop / Cursor / ZCode / Cline / Windsurf）的具体配置位置、环境变量、冒烟步骤与常见问题，见 宿主接入指南。

从源码构建

npm ci
npm run build          # 产出 dist/
node dist/index.js     # 以 stdio 启动（由宿主拉起，通常无需手动运行）

开发与门禁命令：npm run dev、npm run typecheck、npm run lint、npm test、npm run check:stdio（严格校验 stdout 只承载 MCP 协议消息）。

数据目录

默认 ~/.agent-foreman（可用环境变量 AGENT_FOREMAN_HOME 覆盖），首次启动自动创建。项目级验收配置放在项目内 <项目>/.agent-foreman/acceptance.json。

工具面（11 个）

| 工具 | 能力 / 审批 | 作用 | |---|---|---| | run_task | write + 审批 | 派活（可带自动验收/自动返修），异步返回 taskId | | continue_task | write + 审批 | 恢复 needs_user 的原会话 | | query_task | read | 轮询状态 / 进度 / 日志尾 | | list_tasks | read | 历史任务过滤列表 | | get_task_report | read | 某轮验收报告全文（report.md） | | cancel_task | write + 审批 | 取消运行中任务：CLI agent kill 进程树；GUI agent 经 CDP 点击停止并在 gui.cancelWaitMs（默认 15s）内有界等待 GUI 空闲，未确认停止时终态明示 | | verify_task | read | 对任务/项目路径做一次验收（不改源码） | | rework_task | write + 审批 | 手动返修（把失败报告喂回同一 agent） | | get_profiles | read | 查看 agent 适配与可执行探测结果 | | prepare_visual_baseline | write + 审批 | 截图或导入参考图，生成待审阅候选和摘要 | | approve_visual_baseline | write + 审批 | 用户审阅后校验摘要并写入基准与审批记录 |

返回值双轨：人类可读文本 + ---agent-foreman-meta--- JSON 块（便于宿主正则抽取），同时以 MCP 标准 structuredContent 返回同一份字段（现代宿主直接消费）。错误路径同样提供 structuredContent（至少含 ok:false 与 message）。

审批由宿主实施：上表的「write + 审批」是暴露给宿主的标注（_meta.requireApproval / annotations），标注本身不是安全边界——实际授权控制必须由宿主提供。

路径安全闸门：projectPath 在提交时校验——必须绝对路径、目录必须存在、符号链接经 realpath 归一（回执明示解析来源）；主目录本身与系统/根级目录直接拒绝，防止 worker 写权限覆盖整棵系统子树；git 仓库有未提交变更时回执附带共处警示。

无项目派发（ZCode 专用）：省略 projectPath 时任务在 ZCode 的 default 工作区运行，跳过项目登记、Git 基线、项目快照、项目锁与项目验收（终态标注 not_applicable: no_project）。allowCreateProject=false 可禁止自动导入未登记的项目。详见 docs/zcode-cdp.md。

日志与 stdio 契约

本 server 是标准 MCP stdio server，严格遵守传输契约：

stdout 只承载 MCP JSON-RPC 消息。任何诊断日志都不会写入 stdout——否则会破坏 JSON-RPC 流，导致严格客户端握手或工具调用失败。
所有级别日志（DEBUG/INFO/WARN/ERROR）写入 stderr，同时追加到数据目录下的 logs/server.log（UTF-8，ISO 时间戳，含级别标签）。
因此 stderr 里出现 INFO/WARN 不代表服务器出错；它是正常诊断信息。只有启动失败（agent-foreman-mcp 启动失败:）才是致命错误，并会以非 0 退出码结束。

数据目录默认 ~/.agent-foreman（可用 AGENT_FOREMAN_HOME 覆盖），日志文件位于 <数据目录>/logs/server.log。排查连接问题时以 server.log 为准；不要因为 stderr 有输出就判定 server 异常。

技能自装

server 启动时会把自带的编排技能幂等同步到 ~/.agents/skills/agent-foreman-mcp/（Agents Skills 开放标准，用户级）：

内容 hash 一致 → 跳过；不一致 → 先把旧版备份为 .bak-<时间戳> 再覆盖；
安装失败只告警、不阻断 server；
该目录由 os.homedir() 决定，不受 AGENT_FOREMAN_HOME 影响；
可用 --no-skill-install 或 AGENT_FOREMAN_NO_SKILL_INSTALL=1 关闭。

技能文档（SKILL.md / usage-examples.md）以仓库 skills/agent-foreman-mcp/ 为准，涵盖工具面、任务书模板、meta 字段全表、错误码速查与返修提示语模板。

文档

| 文档 | 内容 | |---|---| | docs/host-integration.md | 宿主接入指南：通用 mcpServers 配置、各宿主位置、环境变量、冒烟步骤、FAQ | | ARCHITECTURE.md | 架构说明：分层模型与模块边界、启动装配、数据目录、状态机、验收与返修流水线、Agent 驱动层契约、GUI 实例生命周期、跨平台策略、安全红线、扩展点、已知缺口 | | HANDOFF.md | 项目交接文档：当前状态快照、架构导览、硬性红线、已知限制、接手建议 | | docs/agent-profiles.md | agent profiles 字段说明 + 真实机器样例 | | docs/adapter-matrix.md | 各 Agent 能力调研矩阵（Codex / ZCode / TraeWork / 扩展位） | | docs/acceptance-config.md | 项目级验收配置（.agent-foreman/acceptance.json）写法 | | docs/visual-acceptance.md | 视觉验收：截图对比、图片规格、基准批准与冻结、AI 内容校验 | | docs/visual-validation.md | 视觉验收的验证口径与覆盖边界（以 CI 矩阵为事实来源） | | docs/codex-gui-cdp.md | Codex 桌面端 GUI 驱动：MSIX COM 激活、CDP 接管、选择器、运行检测、验收返修 | | docs/traework-cdp.md | TraeWork GUI 驱动（CDP）：原理、配置、模式切换、选择器、安全红线 | | docs/zcode-cdp.md | ZCode GUI 驱动：安装探测、精确项目/模型、完全访问、暂停继续、验收返修 | | docs/npm-publish-guide.md | 发布流程（门禁、版本、凭据、发布后核验、GitHub Release） | | CONTRIBUTING.md | 开发环境、工程规范、提交与发布流程、如何新增 agent | | SECURITY.md | 安全模型（凭证零管理 / 命令白名单 / 进程与桌面自动化边界）与私密报告渠道 | | CODE_OF_CONDUCT.md | 贡献者行为准则 | | CHANGELOG.md | 版本变更日志 | | LICENSE | Apache License 2.0（详细说明见下节） |

Agent 适配现状

| agentId | driver / adapter | status | 说明 | |---|---|---|---| | codex | gui / codex-gui | ready（macOS 为 research） | Codex 桌面端 GUI（Windows：MSIX COM 激活 + CDP；macOS：spawn .app + CDP）；支持 model/reasoningLevel/planDoc/designSystem；等待用户确认、取消与重派护栏均已真机验证。Windows 真机已验证；macOS 基本闭环已真机验证，取消/返修矩阵补齐前保持 research | | zcode | gui / zcode-gui | research | CDP GUI adapter 已实现且 Windows 真机闭环通过；支持模型菜单、项目绑定与回读加固、无项目派发与 allowCreateProject；macOS 基本闭环已真机验证，取消/返修/新建项目矩阵补齐前保持 research | | traework | gui / traework-gui | ready | CDP 驱动 TRAE SOLO CN 桌面 UI；三种面板模式真机验证通过 | | stub | spawn | 仅测试 | test/stub-agent/stub-agent.mjs 三剧本（good / fix-on-first / never） |

新增 agent 通常只需加一个 profile，详见 docs/agent-profiles.md 与 CONTRIBUTING.md。

无头路径：codex-cli（用户 profile）

内置 codex 走桌面端 GUI 驱动。若不想依赖 GUI 自动化，codex CLI 无头模式可用——无需改 server 代码，在数据目录加一个 driver=spawn 的用户 profile 即可。

前置条件：

codex CLI（npm i -g @openai/codex）。请保持最新：旧版签名证书曾被吊销，macOS Gatekeeper 会直接 SIGKILL（Killed: 9）。
已 codex login（复用 ~/.codex 登录态）。

~/.agent-foreman/agent-profiles.json：

{
  "profiles": {
    "codex-cli": {
      "displayName": "Codex CLI (OpenAI 无头)",
      "type": "cli",
      "driver": "spawn",
      "status": "ready",
      "command": null,
      "argsTemplate": ["exec", "<prompt:arg>", "--skip-git-repo-check", "--sandbox", "workspace-write"],
      "promptMode": "arg",
      "cwd": "task",
      "env": {},
      "timeoutMs": 1800000,
      "killTree": "taskkill",
      "authNote": "复用 ~/.codex 登录态；勿与 --approve-for-me 同用（实测互斥）",
      "executableDiscovery": {
        "dirs": ["/opt/homebrew/bin", "/usr/local/bin"],
        "fileNames": ["codex"],
        "fallbackCommand": "codex"
      }
    }
  }
}

用法与内置 agent 一致：

run_task(projectPath=/path/to/项目, agentId=codex-cli, task="任务书", autoVerify=true, autoFixRounds=2)

行为与限制：

get_profiles 会列出 codex-cli 并探测 PATH 上的 codex 可执行。
model 参数对 spawn agent 不生效——CLI 使用 ~/.codex/config.toml 的默认模型；要锁模型可在 argsTemplate 追加 "-m", "<模型名>"。
写入被 workspace-write 沙箱限制在项目目录内；POSIX 下取消/超时自动对进程组 SIGTERM→SIGKILL（killTree 值在非 Windows 平台被忽略）。

渊源与切换

渊源：本项目源自 tianshu-mcp v0.5.4（Apache-2.0）独立分化，自 1.0.0 起独立演进。两者是并行维护的两个独立项目：tianshu-mcp 的历史（发布记录、真机验收、里程碑叙事）归属其自身仓库，本仓库不保留、不复述；两个项目互不依赖、互不读取对方数据。

从 tianshu-mcp 切换过来的用户须知（四项用户可见的行为变化）：

数据目录不共享：本项目的默认数据目录是 ~/.agent-foreman（环境变量 AGENT_FOREMAN_HOME）。原 ~/.tianshu-mcp 下的任务历史、项目登记、agent profiles 与配置不会被读取、也不会迁移——本项目从全新目录开始。
项目级验收配置需重建：本项目只读 <项目>/.agent-foreman/acceptance.json，不读取 .tianshu-mcp/acceptance.json。已有项目需把配置复制到新路径（.agent-foreman/）。
Codex GUI profile 目录变更：Codex 桌面端的专属浏览器 profile 目录从 …/tianshu-mcp/codex-gui/profile 改为 …/agent-foreman/codex-gui/profile（Windows 在 %LOCALAPPDATA% 下，macOS 在 ~/.agent-foreman/ 下）。该目录承载登录态，因此首次运行需要重新登录 Codex。
Codex 状态备份后缀变更：登记项目前的备份文件后缀改为 .agent-foreman-backup.json，并兼容识别旧后缀 .tianshu-mcp-backup.json——若磁盘上已存在旧备份（那是「任何工具动手之前」的干净快照），本项目不会覆盖它、也不会另建新备份，日志会打印实际生效的那份路径。因此仍可按旧文件回滚。

其余对外契约相对 tianshu-mcp v0.5.4 的变化（新包名、structuredContent 双轨返回、技能自装目录迁移到 ~/.agents/skills/、移除 Gitee 集成等），见 CHANGELOG.md。

开源协作

主仓库：https://github.com/lanlan0811/agent-foreman-mcp（GitHub）
问题反馈：Bug / 功能请求走仓库 Issue 模板；安全漏洞请按 SECURITY.md 私密报告，不要开公开 Issue。

贡献者

感谢为本项目做出贡献的社区成员（按首次参与顺序排列）。其中部分成员在项目的前身 tianshu-mcp 时期参与贡献，其贡献随代码一并承继：

许可

本项目源自 tianshu-mcp（Apache-2.0）独立分化；依 Apache-2.0 要求，原始版权、许可与免责声明随 LICENSE 一并保留。

授予你的权利

商业使用：可在商业产品与服务中使用；
修改：可自由修改源码；
分发：可再分发原始或修改后的版本；
私用：可在组织内部私有使用；
专利使用：贡献者授予你实施其贡献所涉专利的许可（受下述终止条款约束）。

你必须履行的义务

保留声明：分发时须随附 LICENSE 全文，并保留其中的版权、许可与免责声明；
标注修改：若修改了文件，须在修改的文件中附带显著的「已修改」声明；
保留 NOTICE：若原作品含 NOTICE 文件，分发时须保留其内容（本项目当前无 NOTICE 文件）；
不得附加限制：不得对本许可授予的权利附加额外限制。

明确不授予 / 授权终止

商标：本许可不授予任何商标、商号或服务标记的使用权；
专利终止：若你对本项目或其贡献者发起专利诉讼（包括交叉诉讼与反诉），本许可授予你的专利授权自动终止。

免责声明

软件按 「现状」 提供，不附带任何明示或暗示的担保，包括但不限于适销性、特定用途适用性和非侵权担保。在任何情况下，作者或版权持有人均不对因软件、软件的使用或其他交易而产生的任何索赔、损害或其他责任负责（无论是在合同诉讼、侵权诉讼还是其他诉讼中）。

第三方依赖许可

运行时依赖主要为 MIT / ISC / Apache-2.0 许可，与 Apache-2.0 兼容：

| 依赖 | 许可 | 用途 | |---|---|---| | @modelcontextprotocol/sdk | MIT | MCP 协议实现 | | zod | MIT | 外部输入校验 | | cross-spawn | MIT | 跨平台子进程 | | puppeteer-core / @puppeteer/browsers | Apache-2.0 | GUI 驱动与受管浏览器 | | pixelmatch | ISC | 视觉像素比对 |

开发依赖（TypeScript、ESLint、Prettier、Vitest、Vite、tsx 等）各自遵循其开源许可，且不随 npm 发布产物分发。

与安全边界的关系

本 MCP 不保存、不读取、不转发任何 AI-Agent 的 API key 或登录态（详见 SECURITY.md）。许可条款不改变这一设计边界。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

agent-foreman-mcp

这是什么

快速开始

前置条件

安装 npm 包

接入你的宿主

从源码构建

数据目录

工具面（11 个）

日志与 stdio 契约

技能自装

文档

Agent 适配现状

无头路径：codex-cli（用户 profile）

推荐用法

渊源与切换

开源协作

贡献者

许可

授予你的权利

你必须履行的义务

明确不授予 / 授权终止

免责声明

第三方依赖许可

与安全边界的关系