BattlePlan 是做什麼的?
從追蹤器讀取所有開啟的任務,與自上次計畫以來的實際情況進行比對,然後將其轉換為一組簡潔的平行工作執行緒,每個執行緒附帶一個起始提示,讓全新的代理工作階段可以直接接手執行。
步驟 0 — 每次呼叫都從這裡開始
BP="${SKILLS_HOME:-$HOME/.claude/skills}/BattlePlan/Tools"
uv run --script "$BP/setup_tracker.py" check
success: false或無設定 → 先執行 Workflows/Setup.md。絕不能憑空編造追蹤器、分頁名稱或情境。- 設定檔位於
$BATTLEPLAN_CONFIG,否則為${AGENT_SKILLS_CONFIG:-~/.config/agent-skills}/BattlePlan/config.json。其中包含所有者、追蹤器後端、計畫目錄以及情境階層。技能目錄絕不儲存個人資料,因此可以自由共享和更新。
路由
| 調用方式 | 工作流程 |
|---|---|
| "設定 battleplan",無設定檔,新追蹤器,新情境 | Workflows/Setup.md |
/BattlePlan [情境] [--mine] [--skip-audit] [--launch],--audit | Workflows/Plan.md |
/BattlePlan --close | Workflows/Close.md |
/BattlePlan --draft(無人值守),排程草稿 | Workflows/Draft.md |
--add、--done、--cancel、--restore、--sweep、batch-add,從票務或會議匯入任務 | Workflows/Tasks.md |
每日循環
傍晚 排程(工作日) 早上
/BattlePlan --close ──▶ /BattlePlan --draft ──▶ /BattlePlan
完成,每個執行緒的下一步, 讀取追蹤器 + 交接紀錄 + 開啟草稿;你只需確認
繼續命令 工作階段;寫入草稿 例外情況,然後開始執行
即使跳過前一個步驟,每個步驟仍能正常運作:沒有交接紀錄 → 回顧會回溯至前一個工作日;沒有草稿 → /BattlePlan 會即時建立計畫。檔案存放在 plans_dir 目錄中:
| 檔案 | 寫入者 | 內容 |
|---|---|---|
YYYY-MM-DD-handoff-<主機別名>.md | --close | 第一行 Closed: <含時區的 ISO 8601 時間戳> on <主機別名>,接著是完成項目、進行中項目(下一步 + 繼續命令)、結轉項目 |
YYYY-MM-DD-draft-<主機別名>.md | --draft | 計畫與預填的稽核建議;不寫入追蹤器 |
YYYY-MM-DD-plan.md | /BattlePlan | 已確認的計畫,供 --close 比對計畫與實際情況 |
<主機別名> 是別名(mac、wsl、linux 或 $BATTLEPLAN_HOST_ALIAS),絕不能使用主機名稱,因為這些檔案可能跨機器共享。工作階段 ID 僅能在建立它的機器上繼續:顯示其他主機的下一步,但絕不顯示它們的繼續命令。
多機器: 設定 plans_git_sync: true 並將 plans_dir 放置在 git 儲存庫內。提交時只影響剛剛寫入的檔案(git commit -- <路徑>),且在 fetch + merge --ff-only 之後執行。絕不執行 stash、reset 或 clean:其他工作階段可能正在該儲存庫中處理未提交的工作。如果快轉合併失敗,請在本地提交並通知推送尚未完成。
工具
| 腳本 | 功能 |
|---|---|
| `setup_tracker.py check | init` |
pull_tasks.py [情境] [--mine] | 以 JSON 格式輸出開啟的任務,包含計算後的緊急度、截止日期、所有者類型、相依性、票務 |
recap_sessions.py --tasks pull.json [--since auto] [--context X] | 自上次交接以來的代理工作階段 + git 提交,透過票務 ID 連結到任務 |
| `manage_tasks.py add | batch-add |
| `run_draft.sh --install | --check |
tracker.py | 儲存後端(csv、xlsx、gsheets)與設定檔載入;被其他腳本匯入 |
所有腳本都是 uv run --script 檔案,內聯依賴(PEP 723):無需管理虛擬環境。測試:uv run --with pytest --with openpyxl pytest tests/。
不可協商的原則
- 回顧只提出建議,由人類確認。 絕不能僅憑證據就標記任務完成。
- 寫入操作使用精確的行參照。 拉取任務後,使用
Tab!row參照進行一次batch-done呼叫來存檔;當已知行號時,絕不能退而求其次使用子字串搜尋。 - 機密情境(
"confidential": true)在追蹤器和交接紀錄中僅顯示票務 ID 與簡短的通用摘要。manage_tasks.py會拒絕 IP、URL 以及該情境的forbidden_patterns。 - 未經明確確認,絕不啟動執行緒。
- 追蹤器命令依序執行 — Google Sheets 每分鐘約允許 60 次讀取,並且每個命令會讀取所有分頁。
相依性
uv(brew install uv 或 curl -LsSf https://astral.sh/uv/install.sh | sh)。用於回顧提交掃描的 git。僅限 Google Sheets 後端:一個具有試算表編輯器存取權限的服務帳戶 JSON 金鑰。工作階段回顧會讀取 Claude Code 的轉錄 (~/.claude*/projects);使用其他代理時,僅報告 git 活動與交接紀錄。