計畫模式和任務追蹤

Triggerfish 提供兩個互補的結構化工作工具：計畫模式用於複雜的實作規劃，待辦事項追蹤用於跨工作階段的任務管理。

計畫模式

計畫模式將代理限制為唯讀探索和結構化規劃，然後才進行變更。這防止代理在理解問題之前就跳入實作。

工具

plan_enter

進入計畫模式。封鎖寫入操作（write_file、cron_create、cron_delete），直到計畫被核准。

參數	類型	必要	描述
goal	string	是	代理計畫建構/變更的內容
scope	string	否	將探索限制在特定目錄或模組

plan_exit

離開計畫模式並呈現實作計畫以供使用者核准。不會自動開始執行。

參數	類型	必要	描述
plan	object	是	實作計畫（摘要、方法、步驟、風險、檔案、測試）

計畫物件包括：

• summary —— 計畫完成什麼
• approach —— 如何完成
• alternatives_considered —— 評估了哪些其他方法
• steps —— 有序的實作步驟清單，每個都有檔案、依賴和驗證
• risks —— 已知風險和緩解措施
• files_to_create、files_to_modify、tests_to_write
• estimated_complexity

plan_status

回傳目前的計畫模式狀態：活躍模式、目標和計畫進度。

plan_approve

核准待處理的計畫並開始執行。使用者核准時呼叫。

plan_reject

拒絕待處理的計畫並回到正常模式。

plan_step_complete

在執行期間將計畫步驟標記為完成。

參數	類型	必要	描述
step_id	number	是	要標記為完成的步驟 ID
verification_result	string	是	驗證指令的輸出

plan_complete

將整個計畫標記為完成。

參數	類型	必要	描述
summary	string	是	完成了什麼
deviations	array	否	與原始計畫的任何偏差

plan_modify

請求修改已核准的計畫步驟。需要使用者核准。

參數	類型	必要	描述
step_id	number	是	需要變更的步驟
reason	string	是	為什麼需要變更
new_description	string	是	更新的步驟描述
new_files	array	否	更新的檔案清單
new_verification	string	否	更新的驗證指令

工作流程

1. 使用者要求複雜的事項
2. 代理呼叫 plan_enter({ goal: "..." })
3. 代理探索程式碼庫（僅唯讀工具）
4. 代理呼叫 plan_exit({ plan: { ... } })
5. 使用者審查計畫
6. 使用者核准 → 代理呼叫 plan_approve
   （或拒絕 → 代理呼叫 plan_reject）
7. 代理逐步執行，每步完成後呼叫 plan_step_complete
8. 代理完成後呼叫 plan_complete

何時使用計畫模式

代理在複雜任務時進入計畫模式：建構功能、重構系統、實作多檔案變更。對於簡單任務（修正錯字、重新命名變數），它會跳過計畫模式直接行動。

待辦事項追蹤

代理有一個持久的待辦事項清單，用於追蹤跨工作階段的多步驟工作。

工具

todo_read

讀取目前的待辦事項清單。回傳所有項目及其 ID、內容、狀態、優先順序和時間戳記。

todo_write

替換整個待辦事項清單。這是完全替換，不是部分更新。

參數	類型	必要	描述
todos	array	是	完整的待辦事項清單

每個待辦事項項目有：

欄位	類型	值
id	string	唯一識別碼
content	string	任務描述
status	string	pending、in_progress、completed
priority	string	high、medium、low
created_at	string	ISO 時間戳記
updated_at	string	ISO 時間戳記

行為

• 待辦事項按代理範圍（非按工作階段）——它們在工作階段、觸發器喚醒和重啟之間持久化
• 代理只在真正複雜的任務（3+ 個不同步驟）時使用待辦事項
• 一次只有一個任務為 in_progress；完成的項目立即標記
• 當代理寫入省略先前儲存項目的新清單時，那些項目會自動保留為 completed
• 當所有項目都為 completed 時，舊項目不會被保留（乾淨的開始）

顯示

待辦事項在 CLI 和 Tidepool 中都會渲染：

• CLI —— 帶有狀態圖示的樣式化 ANSI 方框：✓（已完成，刪除線）、▶（進行中，粗體）、○（待處理）
• Tidepool —— 帶有每個狀態 CSS 類別的 HTML 清單