追蹤器 —— 追蹤流動的工作
何時適合使用此技能
關鍵提問： 「……的狀態是什麼？」 或 「誰擁有這個？」
追蹤器 = 在不同狀態間移動的項目，具有擁有者和時間軸，且值得保留歷史記錄。
路由測試
你需要至少滿足兩項條件，才夠資格使用追蹤器：
- 隨時間變化的狀態（不是屬性 —— 而是移動）
- 人的指派對象
- 截止日期
- 層級結構：群組 → 子群組 → 項目
少於兩項？→ registry。⚠️ 預設總是使用註冊表。
建構方式
一個引擎，多種 schema。
<tracker-dir>/
schema.json 狀態、優先級、層級標籤、額外欄位
tracker.db SQLite：項目 + 群組 + item_history
引擎：engine/tracker.py（與此 SKILL.md 相鄰）· Python 3.9+ · 零依賴（內建 sqlite3）。
層級結構： group → subgroup → item。標籤會根據領域改變 —— 對任務來說是專案 → 模組 → 任務，對錯誤來說是產品 → 元件 → 錯誤，對發票來說是客戶 → 訂閱 → 發票。
與用戶協作
- 執行路由測試。 扁平列表 →
registry。 - 提出 schema： 有哪些狀態、什麼算「已關閉」、有哪些優先級、層級結構為何、有哪些額外欄位。呈現給用戶並請求核准。
- 檢查
presets/中是否有預設集。 - 使用
init建立，新增群組，然後在工作區層級的registries.json索引中註冊該追蹤器。 - 說明更新可以用自然語言回報 —— 代理會將其轉換為指令。
指令
路徑相對於工作區根目錄。請根據此技能安裝的位置調整 SKILL_DIR（例如 .pi/skills/tracker）。
T=<SKILL_DIR>/engine/tracker.py
D=trackers/bugs
python3 $T --dir $D init --preset bugs
python3 $T --dir $D group add webapp --name "Web App"
python3 $T --dir $D group add checkout --name "Checkout" --parent webapp
python3 $T --dir $D add "Double booking in calendar" --group webapp --subgroup checkout \
--assignee dana --priority sev2 --client acme --due 2026-08-05
python3 $T --dir $D update 3 --status in-progress --notes "reproduced"
python3 $T --dir $D list --assignee dana --group-by status
python3 $T --dir $D list --status blocked
python3 $T --dir $D show 3
python3 $T --dir $D history 3
python3 $T --dir $D report # 摘要：按狀態、按指派人、逾期、被封鎖
python3 $T --dir $D delete 3 --yes # ⚠️ 永久刪除
不帶篩選條件的 list 會自動隱藏已關閉的項目。使用 --all 則顯示全部。
可用的預設集
tasks 任務 · bugs 錯誤和客戶問題 · invoices 發票和催收 ·
features 功能管線
預設集解析順序
init --preset <name> 會按此順序解析 <name>.json —— 第一個匹配的勝出：
<workspace>/trackers/presets/<name>.json— 工作區本地的預設集，相對於引擎執行時的工作目錄<SKILL_DIR>/presets/<name>.json— 上述列出的內建預設集
與內建預設集同名的本地預設集會覆蓋它。若找不到預設集，則會列出兩個位置中所有可用的名稱，並分別標記 [space] / [built-in]。
建立工作區本地預設集： 將一個 schema JSON（格式與 schema.json 相同，請參考內建預設集的範例）放入 trackers/presets/ 目錄。該目錄僅在明確使用 --preset <name> 時才會被讀取 —— 其他檔案會被忽略。
鐵則
- 📊 追蹤器是唯一真相來源 —— 絕不將狀態保留在代理的記憶體中。一律查詢。
- ⛔
blocked狀態必須在備註中說明原因 —— 否則封鎖毫無價值。 - 🗑️ 刪除需要
--yes和明確的使用者確認。 預設沒有「已取消」狀態 —— 如果需要，請將其加入 schema 而非刪除。 - 📜 每次更動都會記錄在
item_history中 —— 絕不手動編輯資料庫。 - 🔁 三個或更少的狀態，沒有指派對象且沒有截止日期 = 這本該是一個註冊表。