byteratio/kanban-plans

通过本地看板追踪计划

看板的存在使得不同项目和不同日期的 Claude 会话能够在会话之间保持计划状态活跃：认领计划、在状态间移动、留下备注。多个 Claude 实例可以共享一个看板——始终将你的工作放在一个项目 slug 下，这样来自不同仓库的计划就不会冲突。

当你在某台运行着看板的机器上处理一个项目中的非平凡计划时，你应该边工作边与看板交互。

看板

来源：https://github.com/hechtch/kanban —— 一个 Angular SPA 加一个基于 SQLite 的 Go API。它在本地运行；没有托管实例。

git clone https://github.com/hechtch/kanban.git
cd kanban
make container-build && make container-run   # 如果你使用 podman，则用 CONTAINER_RUNTIME=podman

make container-run 会发布 -p 8000:8000 并挂载 ~/.kanban/data 以实现持久化，所以一个容器既提供 UI 也提供 API，端口为 8000。

模式	人类用的 UI	Agent API 基础地址
容器 (make container-run)	http://localhost:8000/board	http://localhost:8000/api/agent
开发 (make run)	http://localhost:4200/board	http://localhost:8000/api/agent

Agent API 在两种模式下都在端口 8000 上——只有人类的 UI 链接不同，因为 make run 会在 4200 端口上单独提供 Angular 开发服务器。除非你知道用户正在运行 make run，否则请使用容器的 8000 UI 链接。

如果用户将其部署在其他地方（位于反向代理后面、不同的发布端口上），他们会告诉你基础 URL——使用他们提供的地址，并保留 /api/agent 后缀。

它是否在运行？

KB=http://localhost:8000/api/agent
curl -sS http://localhost:8000/api/health
# {"status":"ok"}

如果检查失败，说明看板没有运行。不要自己启动它——它会写入 ~/.kanban/data/kanban.db，如果有第二个进程争夺该数据库，还不如不追踪。告诉用户看板已关闭，提供上面的 make container-run 命令，然后继续执行实际工作，不做追踪。

权威规范——阅读此部分以获取任何端点详情

该 API 附带一个由类型化 Go 处理程序生成的完整 OpenAPI 3.1 规范。它是路径、请求/响应格式、状态码和验证规则的唯一真实来源——如有疑问，请获取该规范，而不是猜测或依赖过时的文档：

• 规范 (JSON)：http://localhost:8000/api/openapi.json
• 规范 (YAML)：http://localhost:8000/api/openapi.yaml
• Swagger UI（供人类使用）：http://localhost:8000/api/docs

本文件的其余部分为你提供 Agent 工作流（slug、约定、配方），这样你就不必从头学习 API。对于本文件未涵盖的端点细节，请阅读规范。

响应中包含一个 $schema URL 字段，指向响应的 JSON 模式（huma 的约定）。除非你在根据模式验证响应，否则忽略它。

此技能假设的计划文件约定

看板追踪的是计划，而计划是仓库中的 Markdown 文件：

• plans/<topic>.md —— 每个进行中的离散计划对应一个文件，描述原因和内容。使用复选框（- [ ] / - [x]）表示可操作的任务，并在工作进展中就地完善它们。
• plans/done/<topic>.md —— 当工作发布或放弃时，文件移动到这里，顶部带有一个简短的 "Delivered in <版本> — <日期>" 标题。
• CHANGELOG.md —— 面向公众的“变更内容”，与包含变更原因的 plans/done/ 配对。

如果仓库尚未使用此布局，请在认领计划之前在看板上创建 plans/ 目录并初始化该文件——下面的 slug 规则取决于文件名。

Slug 规则

所有内容都通过 slug 键控，而不是数字 ID。永远不要在你的提示或代码中存储 task.id。

• 计划 slug = 计划文件名去掉 .md，小写。plans/photo-import.md → photo-import。
• 项目 slug = 仓库或倡议的名称，使用短横线命名法（kebab-case）。~/projects/photo-organizer → photo-organizer。（对于名为 "Photo Organizer" 的项目，服务器会自动从名称中派生 photo-organizer；你也可以传递显式的 slug。）
• 格式（服务器端强制）：^[a-z0-9]([a-z0-9-]*[a-z0-9])?$。无效的 slug 会返回 400。小写，单词之间用短横线，不要有下划线或大写字母。

任务体就是计划

当你首次认领一个计划时，将计划 Markdown 作为 body 字段发送。从那一刻起，看板数据库就是权威来源——不要中途将编辑同步回文件。磁盘上的 plans/<slug>.md 文件是种子（只使用一次）；plans/done/<slug>.md 是归档快照，在工作发布时写入。

如果你之后重新 PUT 一个新的 body，你的版本获胜。人类也可以在 UI 的 /task/<task_id> 处的渲染视图中修正拼写错误；两次编辑都会落入同一列。

认领计划使其成为“Claude 的”

没有要设置的受托人字段。看板会自动推断：一个带有 plan_slug 的任务——这正是 PUT /plans/<slug> 创建的内容——会在侧边栏的受托人过滤器下渲染在 Claude 下，并在卡片上获得一个 Claude 徽章。人类手动创建的任务没有 plan_slug，并保留在你下面。

因此，通过此 API 认领计划是一个可见的行为。不要仅仅为了在计划上留下备注而认领人类自己在做的工作。

状态

五个看板列，固定：

todo  →  doing  →  blocked  →  awaiting_merge  →  done

加上 backlog（看板外，可选的第六个）。

• blocked —— 工作无法继续；在备注中说明原因。
• awaiting_merge —— 代码已编写并推送，等待 PR 合并或手动合并。与 done 不同，因为工作尚未发布。
• 仅在分支实际合并到主线时才切换到 done。不要自动转换。

'waiting' 不是有效状态——它在一次迁移中被重命名为 'blocked'。

Git 分支

计划（以及任何任务）可以携带 git_branch 字段——正在进行工作的分支。在创建功能分支时设置它，以便人类可以在卡片上看到它：

curl -sS -X PUT $KB/plans/photo-import \
  -H 'Content-Type: application/json' \
  -d '{"git_branch":"feat/photo-import"}'

使用 {"git_branch": null} 清除。该分支会在卡片上渲染为等宽字体徽章。

建议的模型和努力程度

每个任务可以携带 model 和 effort——供下一个接手工作的代理参考。人类在工单中设置这些（或者，当你了解计划的重量时，你也可以设置），它们会在卡片上渲染为 fable / xhigh 徽章。遵守它们：当你恢复一个其任务标有 sonnet / high 的计划时，这就是所有者希望花费的层级；一个 fable / xhigh 审计计划希望使用大模型和高努力程度。

curl -sS -X PUT $KB/plans/security-audit \
  -H 'Content-Type: application/json' \
  -d '{"model":"fable","effort":"xhigh"}'

• model 是一个自由形式的简写——fable、opus、sonnet、haiku 是标准集合；服务器会将其小写并去除首尾空格，拒绝超过 40 个字符的任何值。
• effort 必须是 low、medium、high、xhigh、max（Claude Code 的推理努力程度层级）之一；其他任何值都会导致 422。
• 两者都是可选的且相互独立；使用 null 清除。缺失表示“无偏好——使用会话默认值”。

项目：归档和默认标签

一个项目除名称和颜色外还有两个字段，都可以通过相同的 PUT $KB/projects/<slug> 更新操作设置：

• archived —— 项目已完成。其计划会从侧边栏和看板上消失（折叠到人类可以展开的“已归档”部分），但不会被删除，且每个端点仍会返回它们。当项目的工作已发布时设置：

  curl -sS -X PUT $KB/projects/photo-organizer \
    -H 'Content-Type: application/json' -d '{"archived":true}'
  

• tags —— 项目中每个任务携带的标签。服务器在读取时将标签合并到每个任务的 tags 中，因此在一个标记为 ["infra"] 的项目下的计划，返回时会带有 infra 标签，而无需单独标记。替换整个集合，与任务标签类似：

  curl -sS -X PUT $KB/projects/photo-organizer \
    -H 'Content-Type: application/json' -d '{"tags":["media","infra"]}'
  

  由于合并发生在读取时，从项目中删除一个标签会同时从所有任务中删除该标签。不要单独将项目标签设置在任务上——服务器会从任务自身集合中剥离继承的标签，所以你只是写了一个空操作。

每个会话的工作流程

KB=http://localhost:8000/api/agent

# 1. 确保你的项目存在（幂等——首次 201，之后 200）。
curl -sS -X PUT $KB/projects/photo-organizer \
  -H 'Content-Type: application/json' \
  -d '{"name":"Photo Organizer","color":"#d4654a"}'

# 2. 认领计划 + 发送其当前内容 + 将其放在你的项目下。
#    首次 PUT 创建时状态为 todo；后续 PUT 为补丁。
BODY=$(jq -Rs . < plans/photo-import.md)
curl -sS -X PUT $KB/plans/photo-import \
  -H 'Content-Type: application/json' \
  -d "{\"title\":\"Photo Import\",\"project_slug\":\"photo-organizer\",\"body\":$BODY}"

# 3. 创建一个功能分支并告诉看板。
git checkout -b feat/photo-import
curl -sS -X PUT $KB/plans/photo-import \
  -H 'Content-Type: application/json' \
  -d '{"git_branch":"feat/photo-import"}'

# 4. 切换到进行中并添加备注。状态 PUT 是幂等的——相同状态不带备注是为空操作；带备注则写入一条活动条目。
curl -sS -X PUT $KB/plans/photo-import/status \
  -H 'Content-Type: application/json' \
  -d '{"status":"doing","note":"starting Phase 2"}'

# 5. 边工作边留下备注（比状态切换更轻量）。
curl -sS -X POST $KB/plans/photo-import/notes \
  -H 'Content-Type: application/json' \
  -d '{"text":"phase 2 done; running tests"}'

# 6. 当 PR 打开时，移动到等待合并。
curl -sS -X PUT $KB/plans/photo-import/status \
  -H 'Content-Type: application/json' \
  -d '{"status":"awaiting_merge","note":"PR #123 open"}'

# 7. 一旦合并，切换到已完成并归档文件。
curl -sS -X PUT $KB/plans/photo-import/status \
  -H 'Content-Type: application/json' \
  -d '{"status":"done","note":"merged in v0.3.0"}'
# 然后 `git mv plans/photo-import.md plans/done/photo-import.md`

当你刚刚创建或移动了一个计划时，请提及人类的 UI 链接——http://localhost:8000/board（开发模式下为 :4200）。

规则与注意事项

• 状态枚举固定：todo、doing、blocked、awaiting_merge、done、backlog。不要发明新的。
• 未知的 project_slug 返回 422 unknown project_slug "X"——先创建项目再分配。不会静默自动创建。
• project_slug: "" 会清除项目，等同于 project_id: null。
• Upsert 是真正的 upsert —— PUT /plans/:slug 带 {} 是你的“不存在则认领，存在则补丁”调用。重新运行不会重复；只有第一次调用会写入 create 活动条目。
• 相同状态的状态 PUT 为空操作，除非你传递了 note。利用这一点——你可以安全地重试。
• 活动日志是只追加的，可在 $KB/plans/<slug>/activity 查看。使用备注留下线索（“Phase 2 done; starting Phase 3”），而不是在 body 中叙述。
• Body 是在 UI 的 /task/<task_id> 处渲染的 Markdown。使用标准 Markdown：标题、列表（包括 - [ ] / - [x]）、代码块、链接。表格和块引用也能正确渲染。

何时不需要使用

• 一次性错误修复、重构、文档微调。看板追踪的是计划——跨会话或携带重要上下文的多步骤方案。单次提交的工作不需要工单。
• 如果你正在工作的项目本身就是看板仓库，它在其 CLAUDE.md 中记录了自身约定——请阅读该文件并忽略本文件。
• 如果健康检查失败，说明看板未运行。不要尝试启动它；只需继续并告知用户。