plan

name	plan
description	將模糊需求煉成可執行計畫並立即執行。僅由 `/plan {需求}` 顯式觸發。流程：呼叫 `ask_user` tool 依需求複雜度蒐集多面向資訊（核心 3 維度為底，依風險／不可逆性／資源缺口擴充至 5-7 題）→ 呼叫 `generate_plan` tool 產出結構化計畫 → 視計畫缺口 ask_user 補問 或 直接逐步執行。第一個 tool call 永遠是 `ask_user`；不自己組計畫，必走 `generate_plan` tool。

Plan — 需求煉計畫並執行

你的執行流程

收到 /plan
  ↓
呼叫 ask_user (蒐集第一面向：方向)
  ↓
依回答呼叫 ask_user (依需求複雜度逐題追問，3-7 題不等)
  ↓
判斷資訊是否足夠 generate_plan
  ├─ 不足 → 繼續 ask_user
  └─ 足夠 → 呼叫 generate_plan tool (傳入完整需求 + context)
  ↓
讀取計畫輸出
  ↓
若計畫有缺口 (未知參數 / 模糊驗收 / 多種路徑可選) → 呼叫 ask_user 補問
若計畫完整 → 判斷產出性質：
  ├─ 執行類 (操作 / 變更 / 部署) → 逐步執行並回報
  └─ 結果類 (分析 / 報告 / 文件) → 存檔成 .md 並用附件傳送
  ↓
全部完成輸出總結

每個箭頭都是「直接做下一步」。任何「等使用者文字回覆才繼續」的暫停 = 流程錯誤。禁止自己組計畫文本，計畫必須來自 generate_plan tool 的回傳結果。

步驟 1：蒐集需求（呼叫 ask_user）

收到 /plan ... 後，你的下一個 action 必須是這個 tool call：

{
  "tool": "ask_user",
  "arguments": {
    "questions": [
      {
        "question": "你 /plan 後寫的是「{使用者原文}」— 我先對齊方向：你要的具體是哪一塊？",
        "options": ["{依需求類型給 3-4 個方向選項}", "..."]
      }
    ]
  }
}

範例（投資／股票類需求）：

{
  "tool": "ask_user",
  "arguments": {
    "questions": [
      {
        "question": "你說「tsmc 分析」— 我先對齊角度：你要的是哪一塊？",
        "options": [
          "短線進出點位（幾天到幾週）",
          "中長線分批策略（數月到一年）",
          "估值合理性 / 基本面",
          "與其他標的比較"
        ]
      }
    ]
  }
}

範例（程式／工程類需求）：

{
  "tool": "ask_user",
  "arguments": {
    "questions": [
      {
        "question": "你說「重構 X 模組」— 我先對齊目標：主要動機是哪一個？",
        "options": [
          "效能優化",
          "可讀性 / 維護性",
          "支援新功能",
          "修 bug / 技術債"
        ]
      }
    ]
  }
}

收到使用者選擇後，依答案動態決定下一題（同樣是 ask_user tool call）。提問題數不固定——簡單需求 3 題即可，複雜／高風險／不可逆需求應拉到 5-7 題，直到累積資訊足以讓 generate_plan 產出無 {未填} 的計畫為止。

面向清單（依需求性質取用，非全題必問）：

類別	面向	何時必問
核心（建議全問）	方向／角度	一律問（步驟 1 第一題）
	要做到什麼（具體交付物）	一律問
	成功怎麼判斷（驗收標準）	一律問
範圍	邊界（哪些算 in-scope、哪些 out-of-scope）	需求模糊或牽涉多模組時
	時間／時程限制	含「快」「急」「截止日」字樣，或會影響選擇方案時
資源／環境	已知資源（資料源、API key、預算）	計畫會用到外部資源時
	技術棧／執行環境偏好	跨多語言／多平台可選時
風險／約束	禁止操作（不可動的檔案／系統／資料）	涉及生產環境、共用資源、第三方系統時
	不可逆動作的處理（push／發佈／下單／刪除）	計畫含上述任一時必問
	風險容忍度（要保守還是激進）	投資／策略類需求
後備	失敗時的 fallback	不可逆步驟、或步驟有相依時

停止提問的判準：

• 累積資訊足以讓 generate_plan 產出每一步都有明確驗收、無 {未填}、無分支待決的計畫
• 再問下去只會得到「我不知道，你決定」這類無資訊回答
• 達到上述任一條件就進步驟 2，不要硬湊題數

對照表：寫成這樣 → 改成這樣

你想寫的文字	應該改成的 tool call
「我先確認方向：你要的是哪一塊？回我就繼續」	呼叫 ask_user
「需求是什麼：X、要做到什麼：Y、結果要什麼：Z。對嗎？」（自己填多面向請使用者確認）	呼叫 ask_user 主動問每個面向，不是事後請確認推測
問完 3 題就停（即使資訊明顯不足以規劃）	繼續呼叫 ask_user 補問，直到資訊足夠 generate_plan
「下一步如果你要我繼續，我會...」	直接做下一步（蒐集完就輸出計畫，計畫完就執行）
「這不是 /plan 指令，所以我不走規劃技能流程」	使用者輸入以 /plan 開頭就是 /plan 指令，走流程

步驟 2：呼叫 generate_plan tool

步驟 1 蒐集到的資訊足以產出無 {未填} 計畫時，同一輪直接呼叫 generate_plan tool，不要問「要不要開始規劃」，也不要自己寫計畫。

{
  "tool": "generate_plan",
  "arguments": {
    "requirement": "{彙整使用者原始 /plan 文本 + ask_user 各輪回答，逐維度敘述}",
    "context": "{執行環境 / 已知資源 / 限制 / 禁止操作；無則留空}"
  }
}

requirement 撰寫要點：

• 含使用者原始 /plan 後接文本
• 含所有已蒐集面向的回答（不限於核心 3 題；若有問範圍／資源／風險／後備也要併入）
• 用敘述句串接，不省略 ask_user 答覆

context 撰寫要點（無則留空字串）：

• 當前對話已知的環境（OS／可用工具／資料來源）
• 使用者明示的禁止操作
• 不可逆性提示（會動到帳戶／真實交易／生產環境）

收到 tool 回傳的計畫 markdown 後進入步驟 3。

步驟 3：依計畫狀態分流（補問 or 執行）

讀完 generate_plan 回傳的計畫，判斷是否有以下缺口：

缺口類型	行為
計畫含 {未填}／<TBD>／「需確認」字樣	呼叫 ask_user 補問該欄
多個步驟有相互衝突的前置條件	呼叫 ask_user 釐清優先順序
不可逆步驟（含「刪除」「push」「發佈」「下單」）動作描述含糊	呼叫 ask_user 確認動作細節
計畫每步驟驗收明確、無未填、無衝突	直接執行第一步（步驟 4）

補問用 ask_user tool（與步驟 1 同模式），收到回答後重新呼叫 generate_plan 並把答案併入 context，再次回到步驟 3 判斷。

步驟 4：立刻執行（不問權限）

計畫無缺口後，同一輪緊接著開始執行第一個步驟。不要問「要不要執行」、不要等使用者說「開始」。使用者執行 /plan 就是要規劃並執行，無須中間確認。

先判斷產出性質，二選一：

性質	判準	走法
執行類	計畫步驟主要為操作／變更／部署／呼叫外部系統	4a 逐步執行並回報
結果類	計畫產出為分析／報告／策略／研究／文件本身	4b 存檔成 .md 用附件傳送

混合型（先研究後執行）以「最終交付物」決定；交付物是文件→走 4b。

4a. 執行類：逐步執行並回報

逐步執行，每步輸出回報：

[Step 1/N] {Step Title}
  動作: {what you did}
  產出: {observed result}
  驗收: ✅ {passed} / ❌ {failed + reason}
→ 進入 Step 2

執行規則：

• 一般步驟直接做，不需逐步問權限
• 僅不可逆操作（刪檔 / push / 發佈 / 下單 / 寫到外部系統）前呼 ask_user 二次確認
• 任一步驟驗收失敗 → 停下，呼叫 ask_user：「重試 / 跳過 / 修改計畫 / 中止」四選一
• 全部完成 → 輸出總結（執行步數、產出清單、未達成項）

4b. 結果類：存檔 + 附件傳送

結果類產出一律存成 .md 檔案並以附件傳送，避免長文塞爆後續歷史訊息。

步驟：

1. 寫檔：完整結果（含分析過程、數據、結論、附錄）寫到絕對路徑

   ~/.config/agenvoy/download/plan-{slug}-{YYYYMMDD-HHmm}.md
   

   • {slug}：取需求關鍵字 kebab-case（例：tsmc-mid-term／auth-refactor-design）
   • {YYYYMMDD-HHmm}：當前時間（從 user message 開頭 當前時間: ... 取）

2. 對話只回摘要：5-10 行內，涵蓋

   • 核心結論（1-2 行）
   • 關鍵數據／路徑／決策（3-5 行）
   • 風險／限制（1-2 行）

3. 末尾整行附 marker（必為訊息最後一行，不可中間夾雜）：

   [SEND_FILE:/Users/pardn/.config/agenvoy/download/plan-tsmc-mid-term-20260521-1430.md]
   

範例輸出：

TSMC 中長線分批策略分析完成。

核心結論：當前 925 元偏估值上緣，建議分 3 批進場（920 / 880 / 820）。
關鍵假設：2026 EPS 56-58、本益比 16-18x、台幣匯率 31-32。
主要風險：地緣政治、Apple 訂單能見度、Intel 競爭。
建議部位上限：總資金 15%。

完整分析（含估值模型、敏感度、技術面、籌碼面）見附件。

[SEND_FILE:/Users/pardn/.config/agenvoy/download/plan-tsmc-mid-term-20260521-1430.md]

禁忌：

• ❌ 把完整分析貼進對話正文（歷史訊息會爆量、後續 LLM call token 線性上升）
• ❌ marker 寫成 FILE: 或夾在段落中間（解析器只認最後行整行 [SEND_FILE:...] 或獨立行 ^FILE: <path>$）
• ❌ 檔名省略時間戳（同一 slug 多次規劃會覆蓋）
• ❌ 寫到 /tmp／~/Downloads／工作目錄（必固定 ~/.config/agenvoy/download/）

常見錯誤對照

觀察到的錯誤行為	為什麼錯	正確做法
用文字「請問...？」提問後等使用者文字回覆	ask_user 是 tool 不是文字 chat；文字回覆無法觸發 skill 的多輪結構	呼叫 ask_user tool（有 questions/options 參數的 JSON）
從 /plan 後接文本推測各面向，列出來請使用者確認	推測等於假設使用者意圖，計畫會對不上	主動 ask_user 逐題問
不論需求複雜度都只問 3 題就送 generate_plan	高風險／不可逆需求資訊不足會產出含 {未填} 的計畫	依面向清單依需求性質追問至 5-7 題
「這不是 /plan 指令」「下次用 /plan」這類拒絕走流程	使用者已用 /plan 觸發，就是要走規劃流程	走流程，不繞道
自己組計畫文本，不呼 generate_plan tool	自寫計畫格式漂移、缺結構化欄位、跳過 planning subagent 的推理	必呼 generate_plan，傳完整 requirement + context
收到 generate_plan 結果就立刻執行，不檢查缺口	計畫可能有 {未填} 或衝突，照跑會出錯	先依步驟 3 判斷缺口，必要時 ask_user 補問再 regenerate
補問完直接執行，不重新呼叫 generate_plan	計畫沒更新就照舊計畫跑，補問白費	補問結果併入 context，重新 generate_plan 再判斷
蒐集完問「要不要規劃」	使用者執行 /plan 就是要規劃，不需中間確認	直接呼 generate_plan
規劃完問「要不要執行」	使用者執行 /plan 就是要執行，不需中間確認	直接開始執行第一步
執行階段每步驟前問 ask_user	計畫已產出，逐步授權不需要	直接做；只有不可逆步驟才二次確認
結果類（分析／報告）把完整內容貼進對話	長文進歷史會讓後續 LLM call token 線性爆量	寫到 ~/.config/agenvoy/download/plan-{slug}-{ts}.md，對話只回摘要 + 末行 [SEND_FILE:...]
結果類存檔但 marker 寫中間段落	解析器只取末行整行 marker	摘要寫完，最後獨立一行放 [SEND_FILE:<絕對路徑>]