agent-tasks

agent-tasks

面向 AI 编码 Agent 的流水线驱动任务管理。 一个 MCP 服务，提供阶段门控流水线、多 Agent 协作，以及原生 Claude Code /pipeline 面板。任务按可配置的阶段流转——backlog、spec、plan、implement、test、review、done——并支持依赖跟踪、阶段门控、工件版本管理和串联评论。

专为 AI 编码 Agent（Claude Code、Codex CLI、Gemini CLI、Aider）打造，也同样适用于任何 MCP 客户端或 REST 调用方。

用户手册展示了面板的每个视图和操作，并附有截图以及来自真实 CLI 的短片。

2.0 将 Web 仪表板替换为 Claude Code 中的 /pipeline 面板；不再提供浏览器 UI、WebSocket 或 agent-desk 插件。

从 1.x 迁移

• http://localhost:3422 上的仪表板已移除：在 Claude Code 中使用 /pipeline 打开看板（先安装下方的插件）。agent-desk 中的 Tasks 选项卡也已移除。
• REST：GET /api/overview 和 PUT /api/tasks/:id/stage 已移除（请改用 GET /api/board 和 POST /api/tasks/:id/stage，并传入 {"action": "advance"}）；所有无人调用的路由也已移除；请参阅 REST API。
• 如果某个 1.x 进程仍占用端口 3422，面板会显示其名称（An older agent-tasks (1.10.13) holds the port），状态行也会显示（old server 1.10.13 on the port）：结束仍在运行该进程的 Claude Code 会话（或终止旧的 agent-tasks 进程），让 2.x 进程占用端口，然后刷新。

---

为什么选择 agent-tasks？

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

---

功能

• 流水线阶段 — 可按项目配置：backlog > spec > plan > implement > test > review > done
• 任务依赖 — 有向无环图（DAG），自动检测循环依赖；依赖未解决前会阻止任务推进
• 多 Agent 认领 — 认领、分配任务，或说明原因后将任务退回到较早的阶段
• 子任务层级 — 父子任务树，并跟踪进度
• 线程式评论 — Agent 可围绕任何任务进行异步讨论
• 产物版本控制 — 按阶段附加文档，并自动进行版本控制
• 全文搜索 — 使用 FTS5 搜索任务标题和描述
• Claude Code /pipeline 窗格 — 在对话旁显示看板，优先支持键盘操作：按阶段查看任务、查看包含产物和评论的任务详情、推进、退回、完成、失败、取消、评论和删除任务，并提供状态栏条目
• 2 种传输层 — MCP（stdio）和由窗格读取的环回 REST API（HTTP）
• TodoWrite 桥接 — 拦截 Claude Code 内置的 TodoWrite，并将其同步到流水线
• 阶段门禁 — 可按项目配置，并为各阶段设置规则：推进前要求指定名称的产物、最低产物数量或评论（架构中也有 require_approval，但没有 MCP 工具或 REST 路由会记录审批，因此设置后将无法离开该阶段；请勿启用）
• 决策日志 — 通过 task_artifact(type: "decision") 创建结构化决策产物（因 Z 而选择 X 而非 Y）
• 经验传播 — task_artifact(type: "learning") 用于记录见解（技巧、陷阱、决策、模式）；任务完成后会自动传播给父任务和同级任务
• Agent 亲和性 — task_list(next: true) 会优先将任务路由给有相关历史记录的 Agent（父任务、依赖任务、项目），作为平局时的决胜因素
• 基于心跳的清理 — 使用 agent-comm 心跳数据，自动将失联 Agent 的任务标记为失败
• 任务清理钩子 — 会话停止时自动将孤立任务标记为失败，会话启动时清理过期任务
• Agent 桥接 — 在任务事件发生时（认领、推进、评论）通知已连接的 Agent
• 知识桥接 — 任务完成后，自动将经验和决策产物推送到 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 Agent）

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

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

第一个启动的 MCP 进程也会在 http://localhost:3422 上提供 REST API；其他进程每隔 5 s 重试一次，并在该进程退出后接管。

选项 2：Claude Code 插件（MCP 服务 + /pipeline 窗格）

claude plugin marketplace add keshrath/agent-tasks
claude plugin install agent-tasks@agent-tasks

该插件会运行 MCP 服务，并添加一个 Claude Code 模组（函数钩子，要求 Claude Code 2.1.289+）：/pipeline 会在对话旁打开看板。教程将介绍具体使用方法。请从 ~/.claude.json 中删除任何手动编写的 agent-tasks 条目，以免工具重复出现。

选项 3：独立 REST 服务

node dist/server.js --port 3422

---

Claude Code 集成

完成配置后（参见上方的快速开始），Claude Code 即可直接使用全部 8 个 MCP 工具来创建任务、推进阶段、添加产物、发表评论等。安装插件后，/pipeline 会在对话旁的窗格中打开看板（Claude Code 2.1.289+）。有关详细的集成步骤，请参阅设置指南。

---

MCP 工具（8 个）

类别	工具
任务 CRUD（4 个）	task_create、task_get（包括子任务/工件/评论/传递依赖）、task_list（搜索、下一项）、task_delete
元数据（1 个）	task_update（标题、描述、优先级、标签、项目、分配、依赖）
生命周期（1 个）	task_stage（认领、分配、推进、回退、完成、失败、取消）
工件（1 个）	task_artifact（常规、决策、学习、评论）
配置与实用工具（1 个）	task_config（流水线、会话、清理、规则）

详见完整 API 参考，了解每个工具和端点的详细说明。

REST API（8 个端点）

所有端点均返回 JSON。仅限环回访问：外部 Host 会收到 403，任何携带 Origin 标头的请求也会收到 403（浏览器不会调用此 API），且请求正文必须为 application/json。其他操作均通过 MCP 工具执行。详情请参阅完整 API 参考。

GET    /health                        Health check with version + uptime
GET    /api/tasks/:id                 One task, as task_get (?include=subtasks,comments,transitive_deps)
GET    /api/pipeline                  Pipeline stage configuration
GET    /api/board                     Open and recently closed tasks (what the pane polls)

POST   /api/tasks                     Create a task
POST   /api/tasks/:id/stage           Lifecycle action (claim, assign, advance, regress, complete, fail, cancel)
POST   /api/tasks/:id/comments        Add a comment
DELETE /api/tasks/:id                 Delete a task

---

测试

npm test              # vitest: 472 tests across 25 files
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report
npm run check         # Full CI: typecheck + lint + format + test
npm run plugin:check  # the /pipeline pane: claude plugin validate + its tests (needs the claude CLI)
npm run e2e:claude    # the pane in the real Claude Code CLI (see CONTRIBUTING.md)

---

环境变量

变量	默认值	描述
AGENT_TASKS_DB	~/.agent-tasks/agent-tasks.db	SQLite 数据库文件路径
AGENT_TASKS_PORT	3422	REST API 端口（/pipeline 面板会读取此值）
AGENT_TASKS_HOST	127.0.0.1	REST 绑定地址（0.0.0.0 会将其暴露到网络）
AGENT_TASKS_USER	操作系统用户	/pipeline 面板代表谁执行操作（created_by、评论作者、by）
AGENT_TASKS_INSTRUCTIONS	启用	设为 0 可禁用嵌入在响应中的指令
AGENT_TASKS_RETENTION_DAYS	30	清理任务保留已解决审批记录的天数
AGENT_TASKS_COMPLETED_RETENTION_DAYS	7	已完成任务在清除前保留的天数（并显示在面板的 Done 下）
AGENT_TASKS_FAILED_RETENTION_DAYS	7	失败任务在清除前保留的天数
AGENT_TASKS_CANCELLED_RETENTION_DAYS	1	已取消任务在清除前保留的天数
AGENT_TASKS_ORPHAN_TIMEOUT_MINUTES	360	无负责人的进行中任务在取消前等待的分钟数
AGENT_TASKS_COMM_TIMEOUT_MS	5000	清理流程的 agent-comm 请求超时时间
AGENT_TASKS_DEAD_SESSION_GRACE_MINUTES	60	task-cleanup-start.js：失效会话的任务失败前的空闲分钟数
AGENT_TASKS_HEARTBEAT_FRESH_MINUTES	15	task-cleanup-start.js：心跳时间在此范围内的 Agent 视为存活
AGENT_COMM_URL	http://localhost:3421	用于桥接通知的 Agent-comm REST URL
AGENT_KNOWLEDGE_URL	http://localhost:3423	用于知识桥接的 Agent-knowledge REST URL

---

依赖项

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

可选（软依赖 — 失败时放行、仅限 HTTP、无需 npm 依赖）：

• agent-comm — 基于心跳的任务清理和事件通知。agent-comm 跟踪心跳 → agent-tasks 检查心跳 → 自动将失效 Agent 的任务标记为失败。还会在认领／推进任务时发送直接消息，并在评论时向频道发布消息。没有 agent-comm 时，会平稳跳过过期 Agent 检测和通知。

• agent-knowledge — 用于保存任务经验和决策的知识持久化服务。任务完成时，KnowledgeBridge 会通过 POST /api/knowledge 将 learning 和 decision 工件推送到 agent-knowledge。条目会自动建立索引并生成嵌入向量、自动关联相似条目，并与 Git 同步。没有 agent-knowledge 时，工件只保留在 agent-tasks 中。

---

文档

• 教程 — /pipeline 面板逐步讲解，内容来自真实 CLI 录制
• 用户手册 — 按视图讲解 /pipeline 面板（含截图和 GIF）、所有工具、流水线、门控和清理
• API 参考 — 全部 8 个 MCP 工具和 REST 端点
• Hooks — scripts/setup.js 安装的 Claude Code 命令钩子
• 架构 — 源码结构、设计原则、数据库架构
• 设置指南 — 安装、客户端设置（Claude Code、OpenCode、Cursor、Windsurf）、Hooks
• 贡献指南 — 开发、测试，以及在真实 CLI 中运行端到端测试
• 更新日志

---

许可证

MIT — 参见 LICENSE