Agent 原生的 dev 任务看板 — 把需求调研成规格清晰的任务，端到端执行并验证验收条件。基于 Pocock 的 frontier 模式，含 spec/slug/dependency 字段和 scope 分类。
| 技能 | 用途 | 触发 |
|---|---|---|
devtask-setup |
初始化项目：检查环境、写 CLAUDE.md 引导、可选落库 | 首次引入 devtask / "初始化 devtask" / "setup devtask" |
devtask |
需求 → 落库任务，全规模路由：单点修复 / 批量分类 / Keep-Kill-Pivot / spec+subtasks | 用户说"我想做个…" / "加个功能" / "修个 bug" / "plan this out" |
devtask-doit |
端到端执行任务，自检验收条件，verify 通过后标记完成 | 用户说"做 task-N" / "执行任务" / "work on the next task" |
devtask-review |
验收条件 + 四视角清理审查 + 正确性审查，能修就修 | 用户说"review task-N" / "verify task-N" / "验收 task-N" |
单 plugin 包含 MCP server + 3 个技能，一次安装即可：
# 添加市场
claude plugins marketplace add KanoCifer/DevTaskMcp
# 安装插件
claude plugins install devtask@devtask安装后 3 个技能均自动可用。MCP server 走 .mcp.json 定义的远程 URL —— 部署后把 .mcp.json 里的域名和 token 换成真实值，本地即通过远程实例提供服务。
或在 Claude 对话框中交互完成：
/plugin marketplace add KanoCifer/DevTaskMcp
/plugin install devtask@devtask
本地开发加载：
claude --plugin-dir /path/to/DevTaskMcp默认通过 uv run 启动 server，自动解析依赖。如果机器上没有 uv，参考下方「无 uv」章节。
把技能目录链接到 Claude Code 的技能路径，并手动配置 MCP server：
# 1. 配置 MCP server（添加到 ~/.claude.json 或项目 .mcp.json，指向已部署的远程实例）
# "type": "http",
# "url": "https://你的域名/mcp/",
# "headers": { "Authorization": "Bearer 你的MCP_AUTH_TOKEN" }
# 2. 链接技能目录
# 作为 user-level 技能（全局可用）
ln -s /path/to/DevTaskMcp/skills/devtask-setup ~/.claude/skills/devtask-setup
ln -s /path/to/DevTaskMcp/skills/devtask ~/.claude/skills/devtask
ln -s /path/to/DevTaskMcp/skills/devtask-doit ~/.claude/skills/devtask-doit
ln -s /path/to/DevTaskMcp/skills/devtask-review ~/.claude/skills/devtask-review
# 或作为 project-level 技能（放在项目 .claude/skills/ 下）
mkdir -p .claude/skills
ln -s /path/to/DevTaskMcp/skills/devtask-setup .claude/skills/devtask-setup
ln -s /path/to/DevTaskMcp/skills/devtask .claude/skills/devtask
ln -s /path/to/DevTaskMcp/skills/devtask-doit .claude/skills/devtask-doit
ln -s /path/to/DevTaskMcp/skills/devtask-review .claude/skills/devtask-review注意：手动安装时技能不带有 devtask: 命名空间前缀。
如果机器上没有 uv，两种方式准备 Python 环境：
方式 A — 初始化脚本（推荐）：
scripts/setup.sh # 创建 .venv 并安装依赖
# 或指定解释器：
PYTHON=python3.11 scripts/setup.sh方式 B — 手动 pip install：
python3 -m venv .venv
.venv/bin/pip install -e .然后在 .mcp.json 中指向远程实例（同「手动安装」第 1 步的 URL 配置）。
devtask_mcp.server 以 streamable-http transport 运行：一个长驻进程服务所有调用方，供外部 agent（Claude Code remote、Cursor 等）通过 URL 调用。
1. 构建并启动（本机验证）
cp .env.example .env # 填 DEVTASK_API_KEY、MCP_AUTH_TOKEN
docker compose up --buildcompose 只把端口绑到 127.0.0.1:8003 —— 服务不直接暴露公网。
2. 反向代理 + TLS（Nginx/Caddy 等，自行部署）
把 127.0.0.1:8003 转发到 https://你的域名/mcp/（streamable-http 的标准端点路径是 /mcp/）。请求头必须原样透传，尤其是 Authorization 和 streamable-http 需要的 Mcp-Session-Id。
3. 客户端连接
{
"mcpServers": {
"devtask": {
"type": "http",
"url": "https://你的域名/mcp/",
"headers": { "Authorization": "Bearer 你的MCP_AUTH_TOKEN" }
}
}
}
MCP_AUTH_TOKEN留空时服务不启用应用层鉴权 —— 生产务必设置，并在反代层额外加 IP 白名单/限流。
cp .env.example .env
# 填写 DEVTASK_API_KEY（必填）和 DEVTASK_API_BASE（可选）DEVTASK_API_KEY 是 kanocifer-chat API 的 Bearer 为空时 server 启动会报错。
远程部署时还需配置：
MCP_AUTH_TOKEN— 外部 MCP 客户端调用时携带的 Bearer token。留空则关闭应用层鉴权（仅本地/内网）。MCP_HOST/MCP_PORT— HTTP 监听地址与端口，默认0.0.0.0:8003。
技能以 plugin 名命名空间：
/devtask:devtask-setup # 初始化：检查环境 + 写 CLAUDE.md 引导
/devtask:devtask # 需求 → 落库任务（自动按规模路由）
/devtask:devtask-doit # 领取 frontier 最前排任务执行
/devtask:devtask-doit task-42 # 执行指定 slug 的任务
/devtask:devtask-review task-42 # 验收条件 + 四视角代码审查
/devtask:devtask-setup ← 首次：初始化 + 写引导
│
▼
需求描述
│
▼
/devtask:devtask
│ 按规模路由：单点修复 / 批量分类 / spec+subtasks → 创建任务
▼
/devtask:devtask-doit [task-N]
│ 端到端执行 → 自检验收条件 → /devtask:devtask-review
▼
/devtask:devtask-review [task-N]
│ 验收条件 + 四视角清理审查 + 正确性审查
▼
标记已完成
v3 把所有长文本统一到一个 Task Document。detail 是唯一长文本字段，
正文必须使用固定章节：Goal / Plan / Acceptance Criteria / Constraints /
Context Pointers（外加 Decisions / Out of Scope）。其它结构化字段保持不变。
| 工具 | 用途 |
|---|---|
create_task |
内联参数创建任务，长文放 detail（取代旧的两个工具） |
update_task |
修改状态字段 + 可选 detail 正文；slugs=[] 批量完成 |
get_task(slug, view=...) |
summary / full |
list_children |
永远返回 summary 记录 |
| view | 返回内容 |
|---|---|
summary |
结构化字段，不包含 detail |
full |
原始任务对象（含完整 detail） |
默认 view=summary，防止 agent 误把长文拉进上下文。
| 字段 | 必填 | 含义 | 形式 |
|---|---|---|---|
slug |
自动 | task-ID，人类可读，单调递增 |
— |
title |
是 | 一行摘要，动词开头 | plain |
type |
是 | 问题 / 功能需求 / 优化 / 技术债 |
— |
priority |
是 | P0 紧急 / P1 高 / P2 中 / P3 低 |
— |
scope |
是 | <层>-<技术> 自由格式 |
— |
kind |
否 | spec / subtask |
— |
parent_slug |
否 | 子任务归属的 spec slug | — |
due_date |
否 | ISO-8601 截止日期 | — |
blocked_by |
否 | 同层前置依赖 | — |
for_agent |
是 | Agent 可认领标志 | — |
detail |
否 | Task Document 渲染后的 Markdown | Markdown |
枚举值使用 Go 后端期望的中文字面量——不要使用英文键。详细 Task Document
规范见 docs/task-document-v1.md。
DevTaskMcp/
├── .claude-plugin/
│ ├── plugin.json # Plugin 清单（元数据 + MCP server 引用）
│ └── marketplace.json # 市场发布配置（3 个技能）
├── .mcp.json # MCP server 定义（plugin 自动加载）
├── skills/
│ ├── devtask-setup/SKILL.md # 初始化：检查环境 + 写 CLAUDE.md 引导
│ ├── devtask/references/grill.md # frontier 访谈协议（渐进披露）
│ ├── devtask/SKILL.md # 需求 → 落库任务（全规模路由）
│ ├── devtask-doit/SKILL.md # 端到端执行 + verify 门控
│ └── devtask-review/SKILL.md # 验收条件 + 四视角清理审查 + 正确性审查
├── src/devtask_mcp/ # MCP server Python 包
│ ├── __init__.py
│ ├── client.py # HTTP client，信封剥离
│ ├── models.py # Pydantic 模型 + 中文枚举
│ └── server.py # FastMCP，6 个工具注册（已 slug 化）
├── Dockerfile # 容器镜像（uv slim + 锁文件）
├── docker-compose.yml # 单服务编排，端口回环绑定 8003
├── pyproject.toml
├── CLAUDE.md
└── README.md
- 边界剥离信封： Go 后端用
{code, message, data}包裹响应；client._unwrap在边界剥离，MCP 工具不会浪费 token 在包装字段上。 - 错误原样传播： 非 2xx 或
code != 0抛出DevTaskAPIError，错误信息原样呈现给 agent。 per_page上限 20，无论调用方传入多大值。- HTTP 超时： 15.0 秒。
- 单例长连接 client 在模块级别——streamable-http 下单个长驻进程服务所有调用方，client 无会话状态，共享安全。
- Slug 是规范的人类 ID——在所有 UI、对话和 MCP 工具引用中使用
task-N。后端已全面 slug 化，不再接受 ObjectID 输入。 kind/parent_slug语义分离：parent_slug承载子→父的结构归属（devtask_list_children走此索引），blocked_by只承载同层前置依赖（执行顺序）。