工作力编排器 dotfrankruan/workforce-orchestrator-mcp

Workforce Orchestrator MCP

一套通用执行工作力，供 Codex 及其他 MCP 客户端使用。

编排器把规划器（Codex、Claude 或任何支持 MCP 的客户端）变成可插拔工作后端之上的监督者：任务 DAG、工作流、预算、角色、预设、验收跟踪、指标、持久进程监管、git 隔离，以及产物缓存。

规划器负责思考。工作方负责执行。编排器负责调度。监督者掌管状态与 Git。人类保留最终控制权。

Planner (Codex)
│
▼
Workforce Orchestrator
│
Backend Router
│
┌──────────────┬──────┴───────┬──────────────┐
▼ ▼ ▼ ▼
DeepSeek OpenCode OpenAI API Anthropic API
Harness CLI (direct) (direct)
│ │ │ │
└──────────────┴──────────────┴──────────────┘
│
isolated workspaces
artifacts · metrics · git

后端

| 后端 id | 运行时 | 会话续接 | 持久重连 | 凭据 |
| dsh | DeepSeek Harness CLI（headless 配置档） | 支持 | 支持 | 由 dsh 管理（~/.dsh/.env） |
| opencode | OpenCode CLI（opencode run --format json） | 支持 | 支持 | 由 OpenCode 管理（opencode auth） |
| openai | 直连 OpenAI Chat Completions 或 Responses API | 支持 | 不支持（进程内） | OPENAI_API_KEY / 配置 |
| anthropic | 直连 Anthropic Messages API | 支持 | 不支持（进程内） | ANTHROPIC_API_KEY / 配置 |
| fake | 本地测试后端，不发起 API 调用 | 支持 | 不支持 | 无 |

注册表是确定性的，绝不静默回退。选择顺序：

1. 任务/工作流任务上显式指定的 backend
2. ~/.workforce/config.json 中的 routing.roles.<role>
3. routing.default
4. default_backend
5. WORKFORCE_DEFAULT_BACKEND
6. WORKFORCE_BACKEND（除非为 auto）
7. 按 dsh → opencode → openai → anthropic 顺序，第一个本地可用的后端
8. dsh

auto 是默认值，所以全新安装会使用机器上实际可用的运行时。显式选中的后端不可用时会直接报错——不会自动安装，也不会静默替换。

v0.3 新增内容

- 移除所有厂商专属命名。环境变量、分支、状态路径、包名/可执行文件名和消息现在都是通用的。
- 新增 OpenCode 作为一等 CLI 后端，支持持久 JSONL 日志、会话续接、用量/工具事件和重连。
- 新增直连 OpenAI 后端：Chat Completions（/chat/completions）或 Responses（/responses），带工具循环。
- 新增直连 Anthropic 后端：Messages API，带工具循环。
- 直连 API 后端提供 read_file、write_file、list_directory 和 run_shell，作用范围限定在任务工作区内。
- WORKFORCE_BACKEND=auto，并自动发现本地后端。
- 工作流 token 预算改为 max_worker_tokens（厂商别名已移除）。

快速开始

npm install
npm run build

Optional: see which backends are locally available
node dist/cli.js backends

Start the MCP server on stdio
node dist/cli.js serve # or: npx workforce-mcp serve

零配置行为取决于你装了哪些东西：

- PATH 上有 dsh（或存在 /usr/local/bin/dsh）→ DeepSeek Harness
- 否则 PATH 上有 opencode → OpenCode
- 否则环境里有 OpenAI/Anthropic API key → 直连 API
- 否则服务器照常启动，但在 spawn 时报告明确的可用性错误

安装

要求：

- macOS 或 Linux
- Node.js ≥ 22（用到内置的 node:sqlite；已在 Node 24 上验证）
- git
- 至少一个 worker 后端：
- DeepSeek Harness CLI，或
- OpenCode CLI，或
- OpenAI 兼容的 API key，或
- Anthropic API key

npm install
npm run build

Codex MCP 配置

[mcp_servers.workforce]
command = "node"
args = ["/absolute/path/to/workforce-orchestrator-mcp/dist/cli.js", "serve"]

每个 argv 元素必须是独立的 TOML 字符串。写成单个 "…/cli.js serve" 字符串，node 会去找一个名字就叫 cli.js serve 的文件。

可选的环境变量覆盖：

[mcp_servers.workforce.env]
WORKFORCE_BACKEND = "auto"
WORKFORCE_MAX_CONCURRENT = "4"
WORKFORCE_ROOT = "~/.workforce/workers"
Direct API backends:
OPENAI_API_KEY = "..."
ANTHROPIC_API_KEY = "..."

后端配置（~/.workforce/config.json）

编排器零配置即可运行。可选配置文件是固定可执行文件、选择模型、路由角色的唯一入口。

- 首次启动命令行 → 文件不存在时，自动写入一份最小起步配置（{"default_backend":"auto", ...}）。它不固定任何东西，所以本地后端发现依然生效。
- 文件已存在 → 严格 JSON（不支持注释，不支持 YAML），启动时读取一次，服务器之后不再改动。
- WORKFORCE_CONFIG → 覆盖配置文件位置（适合 CI、测试或按项目配置）。
- 想从完整参考配置起步，而不是最小起步配置：

mkdir -p ~/.workforce
cp config.example.json ~/.workforce/config.json
node dist/cli.js backends

Schema

{
"default_backend": "auto",
"backends": {
"dsh": {
"command": "/usr/local/bin/dsh",
"profile": "headless"
},
"opencode": {
"command": "opencode",
"model": "anthropic/claude-sonnet-4-5",
"agent": "build",
"auto_approve": true,
"args": []
},
"openai": {
"api_key_env": "OPENAI_API_KEY",
"base_url": "https://api.openai.com/v1",
"model": "gpt-4.1",
"api": "chat_completions", // or "responses"
"max_output_tokens": 8192,
"temperature": 0.2,
"max_iterations": 48
},
"anthropic": {
"api_key_env": "ANTHROPIC_API_KEY",
"base_url": "https://api.anthropic.com",
"model": "claude-sonnet-4-5",
"api_version": "2023-06-01",
"max_output_tokens": 8192,
"max_iterations": 48
}
},
"routing": {
"default": "dsh",
"roles": {
"reviewer": "openai",
"researcher": "anthropic"
}
}
}

所有字段都可选。未知键会被忽略，以保持向前兼容。
default_backend / routing 里引用的后端 id 必须已注册，否则启动会失败，并报出明确错误。

凭据

尽量用环境变量，不要把密钥写进配置文件：

| 后端 | 主环境变量 | 备用环境变量 |
| OpenAI | WORKFORCE_OPENAI_API_KEY | OPENAI_API_KEY |
| Anthropic | WORKFORCE_ANTHROPIC_API_KEY | ANTHROPIC_API_KEY |

api_key_env 可以指定另一个环境变量名。自定义 base_url 能指向本地 OpenAI 兼容网关，这类网关不要求密钥；此时即使密钥为空，后端也算可用。

dsh 和 opencode 自己管理凭据（例如 ~/.dsh/.env 和 opencode auth）；编排器不读取也不管理它们。

环境变量

| 变量 | 默认值 | 含义 |
| WORKFORCE_BACKEND | auto | auto、dsh、opencode、openai、anthropic、fake |
| WORKFORCE_DEFAULT_BACKEND | — | 路由默认值（覆盖 WORKFORCE_BACKEND） |
| WORKFORCE_CONFIG | ~/.workforce/config.json | 配置文件路径（首次启动时若不存在则创建） |
| WORKFORCE_ROOT | ~/.workforce/workers | 状态根目录（worktree、任务工作区、db） |
| WORKFORCE_DB | <root>/workers.db | SQLite 数据库 |
| WORKFORCE_MAX_CONCURRENT | 4 | 最大并行任务数 |
| WORKFORCE_DEFAULT_TIMEOUT | 3600 | 单任务默认超时（秒） |
| WORKFORCE_MAX_TIMEOUT | 21600 | 超时上限（秒） |
| WORKFORCE_LOG_MAX_BYTES | 32768 | get_worker_log 上限 |
| WORKFORCE_DIFF_MAX_BYTES | 65536 | 完整 diff 上限 |
| WORKFORCE_FINAL_TEXT_MAX_CHARS | 8000 | 最终报告文本上限 |
| WORKFORCE_TERMINATE_GRACE_MS | 5000 | SIGTERM→SIGKILL 宽限期 |
| WORKFORCE_DSH_COMMAND | /usr/local/bin/dsh 或 PATH | dsh 可执行文件 |
| WORKFORCE_DSH_PROFILE | headless | dsh 配置档 |
| WORKFORCE_OPENCODE_COMMAND | opencode | OpenCode 可执行文件 |
| WORKFORCE_OPENCODE_MODEL | OpenCode 默认值 | provider/model |
| WORKFORCE_OPENCODE_AGENT | OpenCode 默认值 | 智能体名称 |
| WORKFORCE_OPENCODE_AUTO | true | 传入 --auto |
| WORKFORCE_OPENCODE_ARGS | — | 额外命令行参数（空格分隔） |
| WORKFORCE_OPENAI_API_KEY | — | OpenAI 密钥 |
| WORKFORCE_OPENAI_BASE_URL | https://api.openai.com/v1 | OpenAI base URL |
| WORKFORCE_OPENAI_MODEL | gpt-4.1 | OpenAI 模型 |
| WORKFORCE_OPENAI_API | chat_completions | chat_completions 或 responses |
| WORKFORCE_ANTHROPIC_API_KEY | — | Anthropic key |
| WORKFORCE_ANTHROPIC_BASE_URL | https://api.anthropic.com | Anthropic base URL |
| WORKFORCE_ANTHROPIC_MODEL | claude-sonnet-4-5 | Anthropic model |
| WORKFORCE_ANTHROPIC_VERSION | 2023-06-01 | API version header |
| WORKFORCE_ENABLE_SUBAGENTS | false | 允许委派 research/general 子代理 |
| WORKFORCE_MAX_SUBAGENT_DEPTH | 1 | 子代理深度上限 |
| WORKFORCE_MAX_SUBAGENTS_PER_TASK | 3 | 子代理数量上限 |

MCP 工具

编排

| 工具 | 用途 |
| create_workflow | 基于 key 的任务 DAG；共享工作区；预算；失败策略；拒绝环。 |
| run_workflow_preset | 围绕目标展开内置预设（options.dry_run = 只出计划）。 |
| list_presets / list_roles | 内置预设与角色模板。 |
| get_workflow / list_workflows | 透明的计划与实时状态。 |
| wait_workflow | 事件驱动等待，直到进入终态。 |
| cancel_workflow | 取消所有未进入终态的任务；保留工作区与产物。 |
| get_workflow_result | 紧凑汇总：结果、产物、指标、警告。 |
| get_workflow_diff | 相对基线的整合 diff（默认只给统计）。 |
| review_task_result | 记录验收结论（accepted/rejected/needs_revision）。 |
| get_task_metrics / get_workflow_metrics / get_system_metrics | 客观计数与质量统计。 |

任务

| 工具 | 用途 |
| spawn_task | 按任意模式派生任务，可指定工作区、交付物、能力、后端。 |
| spawn_tasks | 批量派生，最多 16 个独立任务。 |
| wait_task / wait_tasks | 高效的事件驱动等待（all/any）。 |
| get_task_result | 紧凑结果：状态、摘要、产物、交付物、用量。 |
| list_artifacts / get_artifact / get_artifact_metadata | 产物元数据与截断后的内容。 |
| get_task_usage | token、步数、按工具统计的调用次数、运行次数、耗时。 |
| list_backends / get_backend | 后端可用性、能力、事实性元数据。 |

Worker（旧版别名，完全支持）

| 工具 | 用途 |
| spawn_worker | spawn_task(mode=code, git_worktree)。 |
| get_worker / list_workers | 紧凑的 worker 状态。 |
| continue_worker | 在同一工作区/后端会话中继续任务。 |
| cancel_worker | 优雅终止；保留工作区与改动。 |
| get_worker_result | 旧版以 git 为中心的紧凑结果。 |
| get_worker_log / get_worker_diff | 脱敏、截断后的诊断信息。 |

任务模式

| 模式 | 用途 | 默认工作区 |
| code | 在隔离的 worktree 中实现、修复、测试、调试、提交 | git_worktree |
| research | 调研（可用时走网络）、综合、记录 sources.json | temporary |
| data | 分析 CSV/JSON/SQLite/日志；输入只读，输出写成文件 | directory（给了路径时） |
| docs | README/架构/迁移文档 | any |
| file | 在工作区内批量整理/分类/重命名/转换 | directory/temporary |
| ops | 日志/配置/服务诊断；只提建议，不做破坏性变更 | directory/temporary |
| review | 只读代码审查；可以运行测试 | git_worktree |
| general | 通用知识工作，产出文件交付物 | temporary |

每种模式在 src/prompts/ 下都有自己的提示词模板。

工作区

- git_worktree — 独立分支 workforce/worker/<id>，worktree 位于 ~/.workforce/workers/<repo>-<hash>/<id>/worktree。编排器从不合并、推送，也不碰你的主分支。
- directory — 调用方已有的目录，会做规范化；产物索引限定在该目录内。
- temporary — 每个任务在状态根目录下新建目录，任务完成后保留。

工作流、DAG 与 git 隔离

- 工作流共享一个工作区；git 工作流共享一个集成分支（workforce/workflow/<wf-id>）。
- git 工作流的每个任务都有自己的 worktree 和分支（workforce/task/<id>），从当前集成 HEAD 创建。
- 任务提交通过每个工作流各自的异步互斥锁，cherry-pick 到集成分支上。发生冲突时干净中止，并列出冲突的文件/提交——绝不自动解决。
- 对冲突任务执行 continue_worker，会从最新集成 HEAD 新建 worktree （workforce/task/<id>-r<N>），然后重试集成。
- 失败策略：stop_dependents（默认）、continue、 cancel_remaining。
- 预算：每个任务的 token/时间/工具/迭代上限，以及每个工作流的 max_worker_tokens、max_duration_seconds、max_concurrent_tasks、 max_tasks。超限会产生终态 budget_exceeded。

持久化监督

- 子进程后端（dsh、opencode）把 stdout/stderr 直接写入持久化日志文件，所以监督进程崩溃不会中断 worker。
- 重启时：PID 存活且身份匹配，就重新挂接（回放日志、计数器、超时、预算）；PID 已死且有持久化终态事件，就正常收尾；PID 已死且没有终态证据，就标记为 interrupted。绝不编造退出码。
- 服务优雅关闭时，worker 会被分离而不是杀掉。只有 cancel_worker、cancel_workflow、超时或预算才会终止它们。
- 直连 API 后端（openai、anthropic）在进程内运行，无法重新挂接；重启时进行中的请求会变成 interrupted，工作区和产物保留。

Git 归属

Worker 负责编辑和测试文件。监督进程在 git worktree 上验证并提交成功的变更：

- 提交信息取自最终报告里的 suggested_commit_message: 行，否则用 workforce/worker/<task-id>: apply delegated changes；
- worker 自己创建的提交会被接受，剩余的未提交文件在后续提交中收尾；
- 取消 / 超时 / 失败的运行绝不自动提交；
- 提交身份使用仓库已有的 user.name/user.email，仅在缺失时才回退到备用身份；
- supervisor 的 git 命令：status、diff、add、commit、rev-parse、 log、cherry-pick（+--abort）、worktree、branch。绝不 push、merge、 reset、clean 或 rebase。

等待与精简上下文

不要轮询。wait_task / wait_tasks / wait_workflow 由事件驱动，一旦到达终态（或等待预算耗尽）就立即返回。等待超时绝不会取消 worker。

精简结果包含状态、摘要、产物元数据、用量和警告。思考过程、原始工具输出、完整日志、完整数据集和超大 diff 永远不会自动进入上下文。需要时用 get_artifact、get_worker_log 或 get_worker_diff 显式获取；这些接口都有大小上限，并会做脱敏处理。

交付物与产物

deliverables: ["report.md", ...] 会作为硬性要求写入 worker 提示词，并在任务完成时在磁盘上校验。缺失的文件记为 deliverables_missing（任务仍可为 completed）。

每个生成的文件都会在 SQLite 中建立索引，记录路径、mime 类型、大小和 sha256。产物必须位于任务工作区内；任意路径会被拒绝。二进制产物只返回元数据。

角色与预设

内置角色：implementer、tester、researcher、reviewer、 docs_writer、data_analyst、debugger、ops_analyst。

内置预设：bug_fix、feature_development、quality_audit、 research_report、data_analysis。预设是透明的 DAG —— 用 list_presets / get_workflow 查看，或用
run_workflow_preset({options:{dry_run:true}}) 试运行。

命令行

node dist/cli.js serve
node dist/cli.js workers|tasks [--status S] [--limit N]
node dist/cli.js task <id>
node dist/cli.js inspect <id>
node dist/cli.js artifacts <id>
node dist/cli.js artifact <id> <path> [--max-bytes N]
node dist/cli.js usage <id>
node dist/cli.js logs <id> [--lines N]
node dist/cli.js diff <id> [--full]
node dist/cli.js cancel <id>
node dist/cli.js workflows
node dist/cli.js workflow <id>
node dist/cli.js workflow-wait <id> [--timeout S]
node dist/cli.js workflow-cancel <id>
node dist/cli.js review-task <id> <accepted|rejected|needs_revision> [--feedback "..."]
node dist/cli.js task-metrics <id> | workflow-metrics <id> | metrics
node dist/cli.js roles | presets | cache-stats
node dist/cli.js backends | backend <id>

开发

npm run build
npm test # unit + integration (fake/local backends, temp repos)
npm run test:unit
npm run test:integration

冒烟 / 实时 E2E 脚本：

node scripts/mcp-smoke.mjs /path/to/git/repo # MCP protocol smoke (fake backend)
node scripts/real-dsh-e2e.mjs # live dsh coding E2E
node scripts/research-e2e.mjs # live research E2E
node scripts/wait-e2e.mjs # live parallel wait E2E
node scripts/workflow-e2e.mjs # live 3-task DAG E2E
node scripts/parallel-e2e.mjs # live parallel git writers E2E
node scripts/reattach-e2e.mjs # live supervisor-restart reattach E2E

安全

- 子进程后端：只用 argv 数组启动进程；提示词和会话 id 都无法注入 shell 命令。
- 直连 API 后端：文件工具解析路径时严格限定在任务工作区内。run_shell 是智能体的一项能力，有意保留，它在该工作区内执行；不要在承担不起损失的机器上运行不可信的模型。
- 凭据：dsh/OpenCode 的凭据从不读取。API key 只从配置好的环境变量读取，绝不会出现在结果、日志、diff、产物或错误里（所有输出都经过脱敏过滤）。
- 路径：repo_path/workspace.path 会先规范化再校验；所有状态都存放在 worker 根目录下；产物、交付物、diff 的路径必须是相对路径，且不能包含路径穿越。
- 运维模式：在提示词层面禁止 sudo、破坏性命令、SSH 和系统变更；优先提方案，而不是直接改动。这只是建议，不是硬性沙箱。
- 进程归属：用 PID 跟踪，并配合启动令牌确认身份；对账时绝不单凭一个 PID 就认定进程还活着。

已知限制

- 直连 API 后端在进程内运行：supervisor 重启后无法持久重连，其 shell 工具继承服务器的权限。
- token 预算尽力而为，按后端事件逐个检查；单步执行时仍可能超出。
- 精简结果里的测试通过/失败是启发式判断（来自最终报告）；git 事实和交付物则直接核验。
- 目录型工作区的产物发现基于 mtime。
- 能力约束只是建议（提示词层面），不是安全沙箱。
- 产物缓存需手动开启，且只适用于无依赖的任务。
- 子代理支持仅限提示词/配置层面；运行时负责管理子代理。
- 不自动回收 worktree/工作区（有意设计为手动操作）。

许可证

基于 Apache License, Version 2.0 授权。
Copyright 2026 Frank Ruan。