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 以實現持久化，因此一個容器即可在 8000 埠提供 UI 和 API。

模式	使用者的 UI	代理 API 基礎位址
容器 (make container-run)	http://localhost:8000/board	http://localhost:8000/api/agent
開發 (make run)	http://localhost:4200/board	http://localhost:8000/api/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

本文件的其餘部分為你提供代理工作流程（slug、慣例、配方），這樣你就不必從頭學習 API。對於此處未涵蓋的端點細節，請閱讀規範。

回應中包含一個 $schema URL 欄位，指向回應的 JSON 架構（huma 的慣例）。除非你在根據架構驗證回應，否則忽略它。

此技能假設的計劃檔案慣例

看板追蹤的是計劃，而計劃是儲存庫中的一個 Markdown 檔案：

• plans/<topic>.md — 每個進行中的離散計劃一個檔案，描述原因和內容。使用複選框 (- [ ] / - [x]) 表示可操作任務，並在工作進行中就地完善它們。
• plans/done/<topic>.md — 工作交付或放棄後，檔案移動到的位置，並在頂部添加簡短的「在 <版本> — <日期> 中交付」標題。
• 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（看板外，可選的第 6 個）。

• 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 會以 status=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 開啟時，移動到 awaiting_merge。
curl -sS -X PUT $KB/plans/photo-import/status \
  -H 'Content-Type: application/json' \
  -d '{"status":"awaiting_merge","note":"PR #123 open"}'

# 7. 一旦合併，切換到 done 並歸檔檔案。
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 未知的 project_slug "X" —— 在指派之前先建立專案。沒有靜默自動建立。
• project_slug: "" 清除專案，等同於 project_id: null。
• 更新插入是真實的更新插入 —— 使用 {} 的 PUT /plans/:slug 是你的「不存在則認領，存在則修補」呼叫。重新執行不會重複；只有第一次呼叫會寫入一條 create 活動記錄。
• 相同狀態的狀態 PUT 是無效操作，除非你傳遞一個 note。利用這點——你可以安全地重試。
• 活動日誌是僅追加的，可在 $KB/plans/<slug>/activity 檢視。使用筆記留下麵包屑（「階段 2 完成；開始階段 3」），而不是在主體中敘述。
• 主體是在 UI 中 task/<task_id> 渲染的 Markdown。使用標準 Markdown：標題、列表（包括 - [ ] / - [x]）、程式碼區塊、連結。表格和引用區塊也可以渲染。

何時不必理會

• 一次性錯誤修復、重構、文件微調。看板追蹤的是計劃——跨越工作階段或承載有意義上下文的步驟性計劃。單次提交的工作不需要一個工單。
• 如果你正在處理的專案本身就是看板儲存庫，它會在其 CLAUDE.md 中記錄自己的慣例——請閱讀該檔案，並忽略此檔案。
• 如果健康檢查失敗，表示看板沒有在運行。不要嘗試啟動它；只需繼續並告訴使用者。