agent-tasks

面向 AI 编码代理的流水线驱动任务管理。 一个带有阶段门控流水线、多代理协作和实时看板面板的 MCP 服务器。任务流经可配置的阶段 — backlog、spec、plan、implement、test、review、done — 并支持依赖跟踪、审批工作流、工件版本管理和线程化评论。

专为 AI 编码代理（Claude Code、Codex CLI、Gemini CLI、Aider）构建，但同样适用于任何 MCP 客户端、REST 消费者或 WebSocket 监听器。

为什么选择 agent-tasks？

当你在同一代码库上运行多个 AI 代理时，它们需要一个共享的任务流水线 — 而不仅仅是一个扁平的待办列表。它们需要阶段、依赖、审批和可见性。

Related MCP server: Agent Harness Kit

功能特性

• 流水线阶段 — 可按项目配置：backlog > spec > plan > implement > test > review > done

• 任务依赖 — 带自动循环检测的 DAG；在依赖解决前阻止推进

• 审批工作流 — 阶段门控的批准/拒绝，拒绝时自动回退

• 多代理协作 — 角色（collaborator、reviewer、watcher）、认领、分配

• 子任务层级 — 带进度跟踪的父/子任务树

• 线程化评论 — 代理之间对任意任务的异步讨论

• 工件版本管理 — 按阶段的文档附件，带自动版本管理和差异查看器

• 全文搜索 — 跨任务标题和描述的 FTS5 搜索

• 实时看板面板 — 拖放、侧面板、内联创建、深色/浅色主题

• 3 种传输层 — MCP (stdio)、REST API (HTTP)、WebSocket（实时事件）

• TodoWrite 桥接 — 拦截 Claude Code 内置的 TodoWrite 并同步到流水线

• 阶段门控 — 可按项目配置的门控，带每阶段规则：推进前要求指定工件、最小工件数量、评论或批准

• 决策日志 — 通过 task_artifact(type: "decision") 记录结构化决策工件（因为 Z 而选择 X 而非 Y）

• 学习传播 — task_artifact(type: "learning") 捕获洞察（技术、陷阱、决策、模式）；完成时自动传播到父任务和兄弟任务

• 代理亲和性 — task_list(next: true) 优先将任务路由给具有相关历史（父任务、依赖、项目）的代理，作为平局决胜

• 基于心跳的清理 — 使用 agent-comm 心跳数据自动将死代理的任务标记为失败

• 任务清理钩子 — 会话停止时自动将孤立任务标记为失败，会话启动时清理过期任务

• 代理桥接 — 在任务事件（认领、推进、评论、批准）时通知已连接的代理

• 知识桥接 — 任务完成时自动将学习和决策工件推送到 agent-knowledge，带嵌入索引和自动链接

快速开始

从 npm 安装

npm install -g agent-tasks

或从源码克隆

git clone https://github.com/keshrath/agent-tasks.git
cd agent-tasks
npm install
npm run build

选项 1：MCP 服务器（用于 AI 代理）

添加到你的 MCP 客户端配置（Claude Code、Cline 等）：

{
  "mcpServers": {
    "agent-tasks": {
      "command": "npx",
      "args": ["agent-tasks"]
    }
  }
}

看板在首次 MCP 连接时自动启动于 http://localhost:3422。

选项 2：独立服务器（用于 REST/WebSocket 客户端）

node dist/server.js --port 3422

Claude Code 集成

配置完成后（参见上文快速开始），Claude Code 可以直接使用全部 8 个 MCP 工具 — 创建任务、推进阶段、添加工件、评论等。详细集成步骤请参阅设置指南。

MCP 工具（8 个）

每个工具和端点的详细描述请参阅完整 API 参考。

REST API（18 个端点）

所有端点返回 JSON。已启用 CORS。详细信息请参阅完整 API 参考。

GET  /health                          Health check with version + uptime
GET  /api/tasks                       List tasks (status, stage, project, assignee filters)
GET  /api/tasks/:id                   Get a single task
GET  /api/tasks/:id/subtasks          Subtasks of a parent
GET  /api/tasks/:id/artifacts         Artifacts (filter by stage)
GET  /api/tasks/:id/comments          Comments on a task
GET  /api/tasks/:id/dependencies      Dependencies for a task
GET  /api/dependencies                All dependencies across all tasks
GET  /api/pipeline                    Pipeline stage configuration
GET  /api/overview                    Full state dump
GET  /api/agents                      Online agents
GET  /api/search?q=                   Full-text search

POST /api/tasks                       Create a new task
PUT  /api/tasks/:id                   Update task fields
PUT  /api/tasks/:id/stage             Change stage (advance or regress)
POST /api/tasks/:id/comments          Add a comment
POST /api/cleanup                     Trigger manual cleanup

测试

npm test              # 355 tests across 13 files
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report
npm run check         # Full CI: typecheck + lint + format + test

环境变量

依赖

必需：Node.js >= 20.11、better-sqlite3（已捆绑）

可选（软依赖 — 故障开放、仅 HTTP、无 npm 依赖）：

• agent-comm — 基于心跳的任务清理和事件通知。agent-comm 跟踪心跳 → agent-tasks 检查心跳 → 自动将死代理的任务标记为失败。还会在认领/推进时发送直接消息，并在评论/批准时发布到频道。没有 agent-comm 时，过期代理检测和通知会被优雅地跳过。

• agent-knowledge — 任务学习和决策的知识持久化。任务完成时，KnowledgeBridge 通过 POST /api/knowledge 将 learning 和 decision 工件推送到 agent-knowledge。条目会自动进行嵌入索引、自动链接到相似条目，并与 git 同步。没有 agent-knowledge 时，工件仅保留在 agent-tasks 中。

文档

• API 参考 — 全部 8 个 MCP 工具、18 个 REST 端点、WebSocket 协议

• 架构 — 源码结构、设计原则、数据库模式

• 看板 — 看板功能、键盘快捷键、截图

• 设置指南 — 安装、客户端设置（Claude Code、OpenCode、Cursor、Windsurf）、钩子

• 更新日志

许可证

MIT — 参见 LICENSE