MCP Task Orchestrator

MCP 任务编排器

由服务端强制执行的 AI Agent 工作流规范。

基于提示词的框架寄希望于大模型遵循指令。而这个工具会在大模型不遵循时阻止调用。

Task Orchestrator 是一个 MCP 服务，为 AI 编码 Agent 提供持久化工作项图，并由服务端而非提示词强制执行质量关卡。它面向运行多 Agent 或多会话编码工作流的开发者：负责调度子 Agent 的编排器、接手昨天工作的新会话，或持续清空积压任务的自主循环。它以 Docker 镜像形式提供，可与任何 MCP 客户端配合使用，还提供可选的 Claude Code 插件，可在此基础上添加技能和钩子。

初次使用？请从图解指南开始。 指南通过简短的可视化页面介绍本页的概念，其中有些页面可交互：在阶段关卡上触发事件，点击工作拆分查看其依赖关系，并观察架构如何解析。

---

问题

多 Agent 工作流需要模型本身不具备的基础设施。当编排器跨会话调度子 Agent 时，没有内置方式来强制要求工作开始前必须具备哪些文档、跟踪哪些 Agent 做了哪些更改，或保证工作拆分中的依赖顺序。这些都是结构性问题——应由服务端处理，而不是写进提示词。

Task Orchestrator 将这些能力放在服务端。如果必需的设计说明尚未填写，advance 会返回一条指出缺失说明的错误。如果上游依赖尚未完成，状态转换就会被阻止。每次状态转换和说明都会记录执行者。新会话只需一次调用即可恢复完整状态，无需重放对话。此外，规则采用 YAML 配置，而非硬编码在提示词中——无需更改代码即可调整规则。

效果展示

Morning — new session, new agent, zero context:

Agent: items_read(select="context")
       → 2 items in work, 1 blocked, 1 stalled (missing implementation-notes)
Agent: items_read(select="history", since="2026-01-14T17:00:00Z")
       → Recent transitions show orchestrator-1 dispatched 3 sub-agents yesterday

Agent: advance(ops=[{ op: "transition", itemId: "a3f28c01", trigger: "start" }])
       -> gate_blocked: "Item a3f28c01-... is missing 1 required notes." (detail.missing: requirements)

Agent: notes_write(ops=[{ op: "upsert", itemId: "a3f28c01", key: "requirements", role: "queue",
         body: "Validate email format, enforce password complexity..." }])
       -> results[0]: { ok: true, id: "...", version: 1, created: true }

Agent: advance(ops=[{ op: "transition", itemId: "a3f28c01", trigger: "start" }])
       → queue → work. Caller recorded. No context rebuilding.

---

快速开始

前提条件：Docker 已安装并正在运行。

1. 注册服务

最简单的配置是使用按会话运行的 STDIO 容器：无需端口、守护进程或 REST API。将其添加到项目的 .mcp.json 中：

{
  "mcpServers": {
    "mcp-task-orchestrator": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "mcp-task-data:/app/data",
        "ghcr.io/jpicklyk/task-orchestrator:latest"
      ]
    }
  }
}

Claude Code 用户也可以通过 CLI 注册相同的配置：

claude mcp add-json mcp-task-orchestrator '{
  "command": "docker",
  "args": ["run", "--rm", "-i", "-v", "mcp-task-data:/app/data", "ghcr.io/jpicklyk/task-orchestrator:latest"]
}'

重启客户端。服务会在首次运行时创建 SQLite 数据库。没有配置文件时，所有工具都会以无架构模式运行：没有关卡，也没有必需的说明。需要强制执行规则时，再添加架构。

2. 启用工作流架构

在项目中创建 .taskorchestrator/config.yaml（示例请参阅工作流强制执行，也可以使用插件的 /task-orchestrator:manage-schemas 技能），并将该文件夹挂载到容器中：

{
  "mcpServers": {
    "mcp-task-orchestrator": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "mcp-task-data:/app/data",
        "-v", "/absolute/path/to/your/project/.taskorchestrator:/project/.taskorchestrator:ro",
        "-e", "AGENT_CONFIG_DIR=/project",
        "ghcr.io/jpicklyk/task-orchestrator:latest"
      ]
    }
  }
}

每次启动时，服务都会将挂载的文件导入数据库（server-config-import 启动步骤），之后使用存储的副本提供服务；编辑文件后，改动会在下次重启时生效。如果多个容器共享一个数据卷，但挂载了不同的文件，则以最后启动的容器为准；多项目配置请使用第 3 步。

请使用绝对主机路径。Claude Code 的 .mcp.json 只会展开环境变量（${VAR} 和 ${VAR:-default}），不会替换 ${workspaceFolder} 这类编辑器占位符。服务只能访问 .taskorchestrator/ 文件夹，无法访问项目的其余部分。

3. 多项目设置（HTTP + config-sync）

如果你需要在多个代码库中工作，可以运行一个启用了 REST API 的常驻服务。每个项目的 .taskorchestrator/config.yaml 随后都会通过插件的 config-sync 钩子自动同步到该服务：无需为每个项目运行容器，也无需手动挂载；配置更改会热重载，无需重启。插件的 /task-orchestrator:configure-server 技能会以交互方式生成此设置；手动设置方式如下：

docker pull ghcr.io/jpicklyk/task-orchestrator:latest

docker run -d --name mcp-task-orchestrator-http --restart unless-stopped \
  -v mcp-task-data:/app/data \
  -e MCP_TRANSPORT=http -e API_ENABLED=true -e API_AUTH_MODE=none -e API_ALLOW_UNAUTHENTICATED=true \
  -p 127.0.0.1:3001:3001 \
  ghcr.io/jpicklyk/task-orchestrator:latest

使用 HTTP 格式在 .mcp.json 中注册：

{
  "mcpServers": {
    "mcp-task-orchestrator": {
      "type": "http",
      "url": "http://localhost:3001/mcp"
    }
  }
}

并导出客户端变量，告知 config-sync 服务的位置（如果没有该变量，config-sync 会静默地不执行任何操作）：

export TASK_ORCHESTRATOR_API_URL=http://localhost:3001

也可以使用 client.json（仅含 apiUrl，不含令牌）提供 URL。项目模式下的 /task-orchestrator:init 会将其写在项目配置旁边，且仅适用于环回服务，并且只能使用不带路径、查询参数或片段的裸源站（将 .taskorchestrator/client.json 添加到 .gitignore，因为 URL 因机器而异）；/task-orchestrator:init --user 会写入用户级文件，此文件适用于任何主机。优先顺序为：环境变量、项目级文件，然后是用户级文件。/task-orchestrator:init 会为当前目录设置项目根目录，而 /task-orchestrator:init --user 会创建个人根目录，为所有没有自身配置的目录提供服务。

安全： 未经身份验证的模式（REST 和 /mcp 均如此）意味着任何能够访问端口的人都拥有完整的读写和删除权限，并且都以唯一的 local 主体身份操作。只有将端口限制为仅环回地址发布（-p 127.0.0.1:3001:3001），这种模式才是安全的。 切勿将其发布到 0.0.0.0 或范围更广的网络接口。对于共享或联网部署，请使用 bearer 令牌或 JWKS 身份验证，详见 集群部署。

不想使用 Docker？CONTRIBUTING.md 介绍了如何从源代码构建 fat JAR。

---

核心能力

阶段模型

每个工作项都有一个角色：queue（尚未开始）、work（进行中）、review（可选，按架构选择启用）、blocked（上游依赖尚未满足）和 terminal（已完成或已取消）。每个角色对应一个或多个可配置状态。Agent 使用 advance 工具的 transition 操作来推进工作项，而不是直接编辑状态；每道关卡都会在该调用中检查。架构会为角色设置备注要求：声明为 role: queue 的备注必须存在，工作项才能离开队列阶段。

图解：阶段关卡将角色和触发器绘制为一条轨道，并附带关卡模拟器。

工作流执行

架构定义 Agent 在每个阶段必须产出的内容，服务会阻止工作项继续推进，直到要求全部完成。架构还会设定一个规划底线：Agent 进入计划模式时，架构会告知它开始实施前必须具备哪些文档，从而塑造计划本身。

# .taskorchestrator/config.yaml
work_item_schemas:
  feature-task:
    notes:
      - key: requirements
        role: queue
        required: true
        description: "Acceptance criteria before starting"
        guidance: "Cover: problem statement, acceptance criteria, alternatives considered, test strategy."
        skill: "spec-quality"
      - key: implementation-notes
        role: work
        required: true
        description: "What was built and why"

使用此架构时，从 queue 阶段通过 advance 的 transition 操作并设置 trigger: "start"，要求先填写 requirements。服务会返回 gate_blocked 错误，准确列出缺少的备注。

guidance 字段会提供创作说明，并在适当时机显示：Agent 即将填写该备注时，响应会将其命名为 guidanceKey（如果备注指向某个技能，还会附带 skillPointer），而 items_read schema 会返回说明文本。skill 字段更进一步，会指定 Agent 在填写备注前应调用的技能，让评估遵循既定框架，而不是依赖自由形式的文字。

可组合特征

特征可为任何架构添加横切的笔记要求，无需重复定义。只需定义一次特征，即可将其应用于任何条目类型：

traits:
  needs-security-review:
    notes:
      - key: security-assessment
        role: review
        required: true
        description: "Security review of auth, data handling, and access control"
        skill: "security-review"

work_item_schemas:
  feature-task:
    default_traits:
      - needs-security-review
    notes:
      # ... base notes

每个 feature-task 条目都会自动继承 security-assessment 要求。也可以在 items_write 的 create 或 update 中通过 traits 数组逐项应用特征，因此，涉及身份验证的任务会获得 needs-security-review，而 CSS 清理任务则不会。

图解：架构与特征展示了类型、其默认特征和逐项特征如何共同解析为一道门禁。席位介绍了如何由多个 Agent 分担一个阶段。

持久化工作项图

所有内容都是分层图中的一个WorkItem。条目可以嵌套任意深度，并通过带类型的依赖边相连。可原子化地创建整个工作分解：

{ "ops": [{
    "op": "create_tree",
    "root": { "title": "User Authentication", "type": "feature-task" },
    "children": [
      { "ref": "schema", "title": "Database schema", "type": "feature-task" },
      { "ref": "api",    "title": "Login API",       "type": "feature-task" },
      { "ref": "tests",  "title": "Integration tests", "type": "feature-task" }
    ],
    "deps": [
      { "from": "schema", "to": "api" },
      { "from": "api",    "to": "tests" }
    ]
} ] }

（items_write，编排配置文件。）

当 schema 到达终态时，api 会自动解除阻塞。所有子项完成后，生命周期为 auto 的父项会级联到终态（处于 review 的父项需要显式推进）。依赖顺序由服务在结构上强制执行，而非依靠约定。

图解：工作图提供了这棵树的可交互版本，展示阻塞、解除阻塞和父项级联。

操作者归属

每次写入都会归属于传输主体：服务根据连接方式识别调用者身份，而不是依据请求中的某个字段。Bearer 或 JWT 凭证标识其持有者（api:<id>）；stdio，以及未启用凭证模式的 HTTP，则以唯一的 local 主体运行。请求正文中的 actor 会被拒绝，并返回 unknown_parameter。

对于允许查看归属信息的调用者，notes_read 和 items_read 的 history 条目会携带这些信息：谁写了哪条笔记、谁进行了哪次状态转换。事后调试由此成为数据查询，而不必在对话中考古。

要区分不同的 Agent，请为每个 Agent 提供自己的凭证（或者在一次运行中为其提供自己的席位令牌）：使用 API_AUTH_MODE=bearer 或 jwks 启用 REST API，/mcp 会使用同一令牌进行身份验证。每个 stdio 或本地模式会话都属于同一个 local 主体，因此这些会话共享声明和笔记所有权。参阅舰队部署。

会话连续性

无需重建上下文。一次调用即可恢复完整情况：

{ "select": "context" }
{ "select": "history", "since": "2026-01-15T09:00:00Z" }

（items_read。）第一个调用返回活动条目、受阻条目、缺少笔记的停滞条目以及声明摘要；第二个调用返回带操作者归属信息的近期状态转换。添加 "fields": ["ancestors"] 可获取祖先链。新会话通过两个简短响应即可获得完整状态。

图解：查找工作将会话中的各个问题对应到解答这些问题的读取调用，并展示下一个条目的排序方式。

作为结构化上下文的笔记

笔记是附加到工作项上的阶段专属文档。实施 Agent 只需阅读适用于其任务的简明需求笔记，而无需检索更广泛的项目上下文。

笔记支持键、角色范围和查询：

{ "select": "list", "itemId": "a3f28c01", "role": "work" }

（notes_read。）列表只返回元数据（id、key、role、version、bodyLength），因此 Agent 无需支付读取每条笔记正文的令牌成本，就能检查已有内容；get 则可读取单条正文。

全文搜索

按关键词搜索工作项和笔记。搜索结果按相关性排序，因此 Agent 查找相关工作或长时间间隔后重新接手时，会优先看到最匹配的结果。

{ "select": "search", "query": "authentication login", "kinds": ["item"] }
{ "select": "search", "query": "password validation", "kinds": ["note"] }

（items_read。）

搜索范围可限定为某个子树，并按角色、标签或优先级筛选，也可以覆盖整个工作区。

REST API

可选的 HTTP 层（API_ENABLED=true）通过一个 RPC 路由（POST /api/v1/ops/{tool}）提供每个工具的服务，还提供条目和笔记资源的 GET 接口、租约管理、服务元信息和实时 SSE 事件，供仪表板、CI 系统和运维人员使用。它支持静态 bearer token、JWKS JWT 身份验证，以及快速入门中展示的未经身份验证的回环模式。它也为 config-sync 提供支持，因此一个服务可以为多个项目提供服务，并为每个项目使用各自的架构。请参阅 REST API 参考。

图解：运行时地图介绍服务的各层、两种部署形态、REST API、声明和参与者身份。

设计理念

Task Orchestrator 强制执行工作流结构，但不强加方法论。服务负责设置护栏：角色转换、依赖排序、关卡执行和归属标注。Agent 负责其他一切。没有强制的规划仪式，也不限制 Agent 采用何种实现方式。架构、特征和参与者身份验证都是可选层，可在 .taskorchestrator/config.yaml 中配置。随着模型能力不断提升，框架会尽量不妨碍它们。

---

Claude Code 插件

该插件在 MCP 服务之上添加工作流自动化功能：技能、钩子和编排上下文。

安装：

/plugin marketplace add https://github.com/jpicklyk/task-orchestrator
/plugin install task-orchestrator@task-orchestrator-marketplace

新增内容：

层	功能
技能	常见工作流的斜杠命令，包括 /task-orchestrator:quick-start、/task-orchestrator:init、/task-orchestrator:configure-server、/task-orchestrator:manage-schemas 和 /task-orchestrator:create-item
钩子	在会话开始时注入上下文、集成计划模式、传递子 Agent 上下文并执行阶段关卡、同步每个项目的配置，以及在运行结束时提示回顾
编排上下文	SessionStart 钩子会提供编排核心（并附带 orchestrate 技能，详述层级和委派）：Claude 负责规划、委派给子 Agent 并跟踪进度，不直接编写代码
Director 模式	/task-orchestrator:director 将会话作为一个由开放运行、决策和汇总组成的看板来运行；保护钩子会使其远离代码，并将所有读取操作委派给协调者
运行	/task-orchestrator:run-wave 和 /task-orchestrator:ralph 会使用每个席位的令牌启动服务端运行，关闭运行时会触发回顾

MCP 服务无需插件也能运行。该插件让它与 Claude Code 无缝协作。

可选扩展（早期体验）： task-orchestrator-mod 是一个独立的可选插件，提供进程内函数钩子：实时工作图窗格、运行中标记和状态行，以及进程内的回顾、阶段保护和调用形态钩子。它依赖早期体验版 Claude Code API，建议与当前版本的 task-orchestrator 插件搭配使用。

/plugin install task-orchestrator-mod@task-orchestrator-marketplace

图解：编排一次运行展示一个功能从提出请求到条目完成的全过程。改进循环展示如何将工作中发现的问题转化为经过评审的配置更改。

---

MCP 工具

类别	工具	用途
事项	items_read, items_write	读取、搜索和汇总工作事项层级，查找下一个事项、门控状态和转换历史（items_read 选择）；创建、更新、删除、创建整棵树、完成整棵树并重新置顶（items_write 操作）
笔记	notes_read, notes_write	按阶段划分的持久文档，支持版本管理和批量写入
依赖关系	deps_read, deps_write	带有模式快捷方式（线性、扇出、扇入）的类型化边，以及阻塞图
工作流	advance	带有门控检查和依赖关系验证的触发式转换，以及适用于多 Agent 集群的认领、释放和心跳操作
文档	docs_read, docs_write	每个项目根目录下的版本化计划、规则和页面文档
项目配置	config	推送、验证、回滚和检查每个项目的架构配置及规则文本

每个工具都会返回一个响应封装；任何调用设置 describe: true 都会返回该工具的架构。knowledge 配置（/mcp/knowledge，或在 stdio 上设置 MCP_TOOL_PROFILE=knowledge）提供较精简的读写子集，不含编排功能；director 配置（/mcp/director，或设置 MCP_TOOL_PROFILE=director）仅提供事项和依赖关系读取，以及 report 工具。事项 ID 支持短十六进制前缀：当前缀（8 到 32 个十六进制字符）没有歧义时，可以用 itemId="a3f28c01" 代替完整 UUID。从 3.x 升级？请参阅变更日志中的“从 3.x 升级”。有关每个工具的参数和响应结构，请参阅 API 参考。

---

文档

资源	内容
实地指南	配有插图、部分支持交互的核心理念指南。最适合作为入门读物。
快速入门指南	完整的设置指南，包含创建第一个工作事项
API 参考	每个 MCP 工具的参数、响应结构和操作方归属信息
REST API 参考	RPC 路由、资源 GET 请求、租约管理、SSE、身份验证、ETag
工作流指南	架构、阶段门控、依赖关系、生命周期模式
集群部署	多 Agent 操作员：REST 和 /mcp 身份验证、调用方身份、健康检查、SQLite 调优、容量规划
Wiki	完整的文档中心
变更日志	发布历史
贡献指南	开发者设置和贡献流程

---

技术栈

• Kotlin 和 Coroutines
• SQLite + Exposed ORM，支持 FTS5 全文搜索，零配置
• Flyway 版本化架构迁移
• MCP Kotlin SDK，支持 STDIO 和 Streamable HTTP 传输
• Ktor，用于 REST API 和 SSE
• Docker，支持一键部署

采用分层架构（Domain → Application → Infrastructure → Interfaces，由 Konsist 分层测试和包循环测试强制执行，两者的基线均为空），并配有全面的 JUnit 5 测试套件。

---

许可证

MIT 许可证 — 可免费用于个人和商业用途。