trip-research

name	trip-research
description	旅行規劃第二步（研究）：派研究 agent 深度調查目的地（景點 / 美食 / 交通 / 安全 / 住宿）。觸發條件：(a) 使用者打 /trip-research、(b) 從 /trip 流程串接進來、(c) 使用者說以下**特定意圖自然語言**：『研究目的地』『查資料』『研究這個地方』『了解這個城市』。**通用詞如『下一步』『繼續』『接下來』請走 /trip 讓 dispatcher 判斷進度，不要直接執行本 skill**。使用者單純說『想了解某個地方』『這裡好玩嗎』也不算觸發條件。
user-invocable	true

/trip-research — 深度研究目的地

使用與使用者相同的語言回覆（預設繁體中文）。根據使用者的旅行者畫像和目的地，派出研究 agent 進行深度調查。

前置檢查

0. 解析當前行程資料夾（永遠先做）

1. 用 Read 讀 ./current-trip 取得當前行程資料夾名，令 $TRIP = 該資料夾名（trim 空白 / 換行）
2. 若 ./current-trip 不存在、為空、或指向不存在的資料夾 → 告訴使用者先打 /trip（由 /trip 解決指標檔問題）；不要自行建立或猜測
3. 在回應最開頭顯示一行「📍 目前在規劃 {$TRIP}」讓使用者知道正在改哪個行程

1. 讀取行程檔案

1. 讀取 ./$TRIP/trip-meta.md，確認目的地、日期、旅行風格等資訊
2. 讀取根目錄的 ./traveler-profile.md，取得旅行者畫像（畫像所有行程共用）
3. 如果任一檔案不存在，提醒使用者先執行 /trip-plan

重要：以下所有 research/... 路徑都是指 ./$TRIP/research/...，別寫到根目錄。

執行紀律（先讀根目錄 CLAUDE.md「派 sub-agent 通則」+「環境感知」章節）

本 skill 的派 agent 規則繼承自根目錄 CLAUDE.md §派 sub-agent 通則 + §環境感知，不重複。以下只列 trip-research 特有的硬規則：

硬規則 — 不得違反（trip-research specific）

1. 預設用「迷你 agent」策略：每個 agent 只負責 2-4 個清單項，可一次派 5-10 個

   • 實測（2026-04 釜山案）：原本 5-7 項 / agent 的設計，4/5 個 sub-agent 撞 idle timeout，只交付骨架。改成 2-3 項 / agent 後成功率 100%。
   • 原因：sub-agent 在主執行緒看不到 token 流動，但 sub-agent 自己內部仍然要避免「搜尋 → 思考 → 沒寫檔」之間靜默太久。任務範圍越小，搜尋次數越少（≤8 次），逐項寫檔的頻率自然越高，越不可能撞 5 分鐘 idle timeout。
   • 新做法：把原本 "R1 景點 + 文化 + 拍照 + 夜生活"（6-8 項）拆成 R1a（A1-A2，2 項）+ R1b（A3-A6，4 項）。R2 飲食拆成 R2a（B1+B2+B4）+ R2b（B3+B5）。R_shop 拆成 R_shop_a（I1+I3+I4）+ R_shop_b（I2+I5+I6）。
   • 單一 response 派 agent 的硬上限 = 10 個：迷你 agent 的 prompt 短（~150-250 token），10 個一起寫只 ~2000 token，遠低於 idle timeout 風險。> 10 才需要分多輪 response（例：14 個迷你 agent → 第一輪派 7 個 + 第二輪派 7 個，中間講一句狀態）。
   • 做法：該拆就拆，不要為了符合舊規則硬擠成大 agent。任務小、搜尋少、逐項 flush 才是不撞 timeout 的真正關鍵。

2. 使用者問「進度如何 / 還在嗎」時要具體回答

   • 好:「R1 景點 3 分鐘前回來、R2 美食還在跑、R3 交通剛派」
   • 壞：「還在跑，等一下」

Mode 選擇（這趟旅行第一次跑 trip-research 時必做）

不同 Claude 訂閱方案 token 預算差很多，必須在派 agent 前確認使用者要走哪個 mode。詳見根目錄 CLAUDE.md「派 sub-agent 通則」§B。

流程

1. 讀 ./$TRIP/trip-meta.md 「Claude 模式」欄位：

   • 值為 multi-agent → 走 Multi-agent mode（派 sub-agent 平行）
   • 值為 no-agent → 走 No-agent mode（主 Claude 自己跑）
   • 值為 尚未設定 或欄位不存在 → 用 AskUserQuestion 問使用者，選完寫回 trip-meta.md

2. 詢問範例（用最白話、不要用「sub-agent / 配額 / token」這類術語）：

   題目：「這趟旅行第一次研究資料。你 Claude 訂閱是哪個？」 選項（單選）：

   • Pro 版：我自己慢慢跑（約 8-10 分鐘，比較省）
   • Max 版：派幾個小幫手平行做（約 3 分鐘，比較快但會吃較多配額）
   • Other（讓使用者自己打字 — 例如「我用 API」「我有別的訂閱」）

   ⚠️ 不要加「不知道（我幫你猜）」這種選項 — 因為 Claude 沒辦法從別處得知訂閱，「猜」實際上只能預設 Pro，等於跟直接選 Pro 一樣，是冗餘選項。

3. 寫回 trip-meta.md：用 Edit 把「Claude 模式」欄位更新為 no-agent 或 multi-agent。

Multi-agent mode 流程

走第一階段（並行起跑 + 派 gate agent）→ 第二階段（研究清單）→ 第三階段（迷你 agent 派發） → 第四階段（agent prompt）→ 第五階段（回收）。這就是現有 SKILL.md 後面的完整流程，不變。

No-agent mode 流程（主 Claude 自己跑、不用 Task tool）

核心理念：把原本派給 sub-agent 的清單，主 Claude 在主執行緒多輪迭代地做。每完成一個清單區段就 Edit 寫到 ./$TRIP/research/agent-X.md（檔名 / 格式跟 multi-agent mode 完全一致，方便 trip-go 後續讀）。

⚠️ 關鍵紀律：Pro mode 也要多輪 + 持久化！主 Claude 一口氣跑 30 次搜尋會撞 idle timeout、context 也會爆。每批處理 5-6 項 → 寫檔 → 講進度 → 下一批才是正解。

1. 算總批數（事前規劃，類比 Multi-agent 的 agent 總數）

從 research-checklist.md 算有效項數，每批 5-6 項：

batch_count = ceil(有效項數 / 5)              # 每批平均 5 項

範例：清單 38 項 → 估 8 批。

2. 寫 dispatch-plan.md（持久化 — 跟 Multi-agent 用同一個檔）

# 派送計畫 — {目的地}

> Mode：no-agent（Pro，主 Claude 自己跑）
> 預估批數：{batch_count}
> 目前批次：{current_batch} / {batch_count}+

## 批次清單

| 批號 | 負責清單項 | 狀態 | 報告檔 |
|---|---|---|---|
| 1 | A1-A5 | pending | `agent-A.md` |
| 2 | A6-A10 | pending | `agent-A.md` (續) |
| 3 | B1-B5 | pending | `agent-B.md` |
| ... | ... | ... | ... |

3. 跑批次

步驟	做什麼
第 1 批前	dispatch-plan.md 該批 status: pending → running，講「開始第 1 批」
跑第 1 批	主 Claude 自己連續 5-6 次 WebSearch（不用 Task tool）
寫檔	每完成 1 個項目就 Edit 寫到 ./$TRIP/research/agent-A.md（逐項 flush，不要等整批做完）
第 1 批完	dispatch-plan.md status: running → completed，講進度（「5/38 項完成，下一批 A6-A10**）
第 2 批	重複
全部完	gate / 主清單 / season 都做完，進收尾

核心紀律：每批內也要逐項寫檔（不只是每批寫一次）— 防止主 Claude 中途撞 timeout，已寫的不會丟。

4. 中斷續跑（Resume）

session 掛掉重啟 → 讀 dispatch-plan.md 看哪批 status 不是 completed → 從那批接續。 讀對應的 agent-X.md 看寫到哪一項 → 從下一項開始（不重做已寫的）。

5. Pro mode 預算注意

主 Claude 自己跑時，每次 WebSearch 結果都進主 context。清單超過 30 項時主 context 會吃緊：

• 提示使用者：「研究項目較多（35 項），主 Claude 自己跑會吃緊。要改派 sub-agent 嗎？這趟可以暫時切到 Max mode（不影響你訂閱）。」
• 改 mode 要記得寫回 trip-meta.md

為什麼兩個 mode 輸出格式要相容

/trip-go 之後會讀 ./$TRIP/research/agent-*.md 排行程，它不關心是 sub-agent 寫的還是主 Claude 寫的。只要檔名、H2 結構、Source citation 規則一樣，下游就無感。所以 No-agent mode 寫檔時 必須照 multi-agent 的格式來：每個負責項 1 個 H2、每段附 URL、用「⚠️」標分歧或缺資料。

---

第一階段：並行起跑（讓使用者第一眼就進入旅遊話題）

核心設計：/trip-research 開頭不要一口氣問「國籍」「護照」這類行政問題，要先讓使用者感覺「我正在跟你聊旅遊」，同時把 gate agent 派到背景跑。

流程

Step 1 — 開場（一段話講完）：

直接告訴使用者：

要開始研究 {目的地} 了。我會同時做兩件事：

1. 背景派 gate agent 把關簽證 / 護照 / 保險（大約 30-60 秒）
2. 跟你確認研究優先主題，好讓 agent 聚焦

先問你：這趟最想深度挖的 1-3 個主題是什麼？從你的核心興趣（{畫像中的興趣}）我推測會是 {Claude 依興趣推測 2-3 個}，但你可以改。

Step 2 — 同時進行兩件事：

• （A）背景派 gate agent：若畫像「國籍」或「護照狀態」任一為空，先用一句話補齊（「順便問：哪國護照 + 護照現況？」），拿到後立刻派 gate agent 到背景（使用 run_in_background: true）。不要等 gate 完成。
• （B）同時跟使用者收集優先主題：用開放式對話、也可以用 AskUserQuestion multiSelect 給選項（美食 / 景點 / 住宿 / 交通 / 夜生活 / 活動預約 / 當季特殊 等，依畫像興趣動態產）。

Step 3 — gate 回來了：

使用者表達完主題後，gate 通常也跑完了。顯示結果：

對了，gate 跑完了：

• 簽證：{免簽 90 天 / 需 e-Visa 4 天 / 需申辦面簽}
• 護照：{OK / 要換發}
• 保險：{強制申根 30,000 EUR / 非強制}
• 燈號：🟢 綠燈 / 🟡 黃燈立刻辦 / 🔴 紅燈

Step 4 — 依燈號分流：

• 🟢 → 直接往下進入第二階段（研究清單）
• 🟡 → 跟使用者講清楚「先辦護照再辦簽證的時程」，然後繼續
• 🔴 → 中斷，用下方 🔴 的 AskUserQuestion 處理

補齊國籍與護照狀態（gate agent 派出前才問）

從畫像讀「國籍」「護照狀態」。任一欄為空時，在 Step 2 的背景派 agent 之前一次問完（告訴使用者「我順便查你的簽證，幫我確認兩件事」）：

1. 國籍（開放式填答）：「哪一國護照？」— 例如「中華民國」「日本」「加拿大」，不預設
2. 護照狀態（用 AskUserQuestion 單選 4 選項）：
   • 有，效期超過 6 個月
   • 有，但 6 個月內到期
   • 已過期 / 還沒辦
   • 幫我確認（我不確定）

若選「6 個月內到期」或「已過期 / 還沒辦」，不要當場警告時程（避免打斷優先主題討論），等 gate 回來後在紅黃綠燈一併講。若選「幫我確認」遲遲無法確認，直接記「待確認」往下走。

補完後寫回根目錄 ./traveler-profile.md（不是寫進 $TRIP/）。

派出 gate agent

重要：從畫像的「國籍」欄位取得使用者持有的護照國，所有簽證/免簽查詢都以使用者護照國為基準（不要預設中華民國）。派 agent 時務必用 run_in_background: true，讓 agent 在背景跑、主對話繼續跟使用者聊優先主題。

Prompt 要求：

• 查目的地國家對**{使用者國籍}**護照持有人的簽證政策（免簽 / 落地簽 / 電子簽證 / 需事先申請）
• 若行程含轉機，同時查轉機國對 {使用者國籍} 護照的過境簽需求（例如美國過境需 ESTA、加拿大需 eTA、澳洲需 ETA，中國大陸過境 144 小時免簽限定口岸）
• 簽證辦理所需工作天數（含郵寄 / 預約面試的時間）
• 護照效期要求（通常要求入境時剩餘 6 個月以上）
• 當地是否強制旅遊保險（申根、部分國家要求）
• 每個結論都必須附資料來源 URL（使用者國籍的外交部 / 領事局、各國官方網站）
• 來源必須是不同 root domain：例如官方 .gov 網站 + 一個可靠的第二來源（旅遊社群、權威媒體）。若兩個來源不一致，標「⚠️ 資訊分歧，建議再次確認」

報告存為 ./$TRIP/research/agent-0-gate.md。

讀取結果後的紅黃綠燈判斷

從 ./$TRIP/trip-meta.md 取出發日期，算「距出發天數」。從畫像取「護照狀態」與「國籍」。

護照辦理 / 換發時程依國籍不同（中華民國：一般件 10 個工作天、急件 3 個工作天；其他國籍請用 WebSearch 確認該國護照局時程）。

計算「真實所需總時間」時，要考慮依賴鏈：許多電子簽證 / 面試簽都要求先有有效護照才能送件（例如印度 e-Visa 要護照掃描檔、美國 B1/B2 面試要帶護照）。若使用者護照需換發，總時間 = 護照辦理時間 + 簽證辦理時間 + 3 個工作天 buffer（不是平行進行）。

條件	判定	行動
距出發天數 > 真實所需總時間 × 2（且護照沒問題）	🟢 充裕	直接繼續主體研究，在總結中順帶提醒辦理時程
距出發天數 > 真實所需總時間，但不到兩倍	🟡 來得及但要立刻辦	在繼續主體研究前，明確告訴使用者：「這幾件事請今天或明天就開始辦」。清單化列出，標明「先護照、再簽證」的順序
距出發天數 < 真實所需總時間	🔴 來不及	停下來，用 AskUserQuestion 問使用者要怎麼辦（見下表）；選了再決定要不要繼續研究

🔴 時的 AskUserQuestion（4 個選項，不含「幫我決定」以符合 4 選項上限）：

選項	說明
改期（推薦）	請使用者給新日期，重新計算後再判斷
改目的地（免簽或容易辦的）	回到 /trip-plan 重選目的地
機票已訂，辦急件	附急件辦理窗口、所需文件清單、護照急件同步辦法；繼續後續研究，但在報告開頭標紅字警告
取消這次規劃	結束流程，並把 ./$TRIP/trip-meta.md 的「狀態」欄位改為 aborted

如果使用者把四個選項都跳過、或回覆「幫我決定」「你決定就好」這類訊號，依下列規則自動選（並在對話中告知「根據你的 X，我替你選了 Y，可後續再改」）：

• 距出發天數 < 真實所需總時間 × 0.5 → 改期
• 其他情況（差距不大） → 機票已訂，辦急件

第二階段：定義研究清單（NEW，派 agent 前必做）

在派主體研究 agent 之前，先產出一份完整的「研究項目清單」，放在 ./$TRIP/research/research-checklist.md。用途：

1. 派 agent 時，明確告訴每個 agent 他負責清單中的哪幾項
2. agent 全部回報後，主 Claude 逐項審核清單，確認每一項都有被回答
3. 有遺漏的項目主動補派 agent 或告訴使用者

清單內容（根據畫像動態產生）

清單格式（每項都對應到哪個 agent、是否完成）：

# 研究項目清單

> 目的地：{目的地}　出發日期：{日期}　畫像關鍵字：{興趣、旅伴、預算等級}

## A. 核心體驗（對應畫像核心興趣動態產出）
- [ ] A1: {根據興趣動態} — 由 agent ?
- [ ] A2: ...

## B. 飲食
- [ ] B1: 每日飲食花費試算（早/午/晚）
- [ ] B2: 當地必吃食物清單（附街道 / 地址與 Google Maps 連結）
- [ ] B3: 飲食限制替代方案（素食 / 過敏 / 清真）
- [ ] B4: 飲水資訊（自來水可否飲用、免費飲水點）

## C. 交通
- [ ] C1: 機場到市區所有選項
- [ ] C2: 市內交通（地鐵 / 公車 / 計程車 App / 步行）
- [ ] C3: 交通票券比較（日票 / 多日票 / 單程）
- [ ] C4: 城際交通（若多城市）
- [ ] C5: MCT 轉機時間（若行程含轉機）

## D. 住宿
- [ ] D1: 推薦 3-5 間比較表
- [ ] D2: 位置建議
- [ ] D3: Check-in/out 時間、行李寄放、WiFi
- [ ] D4: 家庭旅行：家庭房、廚房、洗衣機、嬰兒床

## E. 安全與實用資訊
- [ ] E1: 治安整體評估
- [ ] E2: 常見詐騙與扒竊高風險區
- [ ] E3: 緊急聯絡（急診醫院、報案、駐外館處電話）
- [ ] E4: 保險理賠須知（報案證明取得流程）
- [ ] E5: 插座規格、電壓（是否有燒機風險、轉接頭需求）
- [ ] E6: 小費文化
- [ ] E7: 廁所資訊（付費 / 免費）

## F. 當季特殊狀況
- [ ] F1: 節日、慶典、市集
- [ ] F2: 季節限定體驗（楓葉、櫻花、極光、雪季）
- [ ] F3: 特殊展覽、音樂節、體育賽事
- [ ] F4: 國定假日對商店營業時間的影響
- [ ] F5: **罷工 / 政治集會 / 夏令時切換**（歐美常見、影響交通）

## G. 機票（若使用者尚未訂）
- [ ] G1: 可用航班、價格、轉機、飛行時間
- [ ] G2: 訂票平台建議

## H. 保險
- [ ] H1: 目的地是否強制保險（申根 30,000 EUR、部分國家強制）
- [ ] H2: 建議醫療保障金額（依目的地錨點：美/加 ≥ NT$500 萬、歐洲 ≥ NT$300 萬、日韓東南亞 ≥ NT$200 萬）
- [ ] H3: 除外條款檢查（登山 2500m 以上、滑雪、潛水、機車、冒險活動常被排除；若行程含這些活動要選有涵蓋的保單）
 [ ] H4: 是否有醫療直付醫院網絡（減少現場自墊的負擔）
 [ ] H5: 報案 / 理賠文件要求（事發當地 24 小時內要拿到警察報案三聯單、就醫收據正本）

研究清單會根據畫像調整：

• 若使用者已有機票 → G 全部標完成（跳過）
• 若無轉機 → C5 刪除
• 若非歐美 → F5 可省略（但仍列出以防誤判）
• 若畫像興趣含「戶外冒險」→ A 加「步道難度、裝備、天氣」
• 若家庭帶小孩 → D4 必留

分派對照

派 agent 時，在每個 agent 的 prompt 裡標明「你負責清單中的 X1、X2、X3 三項，最後報告中按清單編號回答」，方便回收時對照。

第三階段：研究 Agent 策略（事前算總數 → 算輪數 → 跑批 → 失敗拆細重派）

⚠️ 重要：「研究深度（標準/深度）」維度已拿掉。所有研究都做深度研究，差別只在 Mode（Pro = 主 Claude 自己跑 / Max = 派 sub-agent 平行）。詳見 Mode 選擇章節。

1. 算總 agent 數（事前規劃）

從剛寫好的 research-checklist.md 算有效項數：

• 跳過的整組類別不算（例如使用者已訂住宿 → D 整組省、已訂機票 → G 整組省）
• 其餘實際列出的項目累計

每個 sub-agent 最佳工作量 ≈ 2-4 個清單項（迷你 agent 策略 — 實測過 5-7 項會觸發 idle timeout）。

估算公式（只是預估，會自我修正）：

agent_count_estimate = ceil(有效項數 / 3)     # 每個 agent 平均 3 項

範例：清單 38 項 → 估 13 個 agent。

2. 算輪數

每輪派 10-15 個 sub-agent（一輪 ≥ 16 會吃太多 main token、講進度也照顧不到）：

rounds = ceil(agent_count / 12)               # 12 是 10-15 的中位

範例：13 個 agent → 1 輪派完（一次派 13 個）。 範例：22 個 agent → 2 輪（11 + 11，或 15 + 7）。 範例：40 個 agent → 3 輪（15 + 15 + 10）。

3. 跑批次（事前確定的批次，不是動態看夠不夠）

步驟	做什麼
派發前	寫 dispatch-plan.md（含每個 agent 的 ID / 負責項 / 所在輪 / status: pending）
第 1 輪	一次派 10-15 個 sub-agent（全部 run_in_background: true）
等回來	檢查每個 agent status：completed / failed / 沒寫到報告
處理失敗	死掉的 agent 絕對要重派（不能放掉它的工作）；重派時拆細（見下節）
第 2 輪	派下一批（含失敗拆細補的）
重複	直到所有規劃的 agent 都 completed（含拆細補的）

每輪之間務必講一句文字（為了 idle timer 重置 + 使用者看得到進度）。

4. 失敗拆細重派（自我修正預估）

死掉 = 訊號，告訴你「他的工作量比你預估的大」→ 重派要拆細：

失敗情況	處理
Agent 死掉、報告完全空	工作量低估嚴重 → 拆 3 個 agent 接他的工作
Agent 死掉但寫了一半（H2 部分有內容）	看剩下的多少 → 拆 2 個 補（每個負責剩餘的一半）
Agent 沒死但內容很淺（搜尋預算耗盡）	不拆，加派 1 個 專攻同主題深挖

→ 原本預估 38 個 → 實際跑完可能變 45-50 個（含補拆的）。這個機制讓「總數估錯」自我修正。

5. 持久化到 dispatch-plan.md（防 session 掛掉）

所有狀態必須寫進 markdown，不能只活在對話 context：

• 每派一個 agent → 寫入新 row（status: pending → running）
• 每個 agent 回來 → Edit 該 row 的 status（completed / failed / partial）
• 失敗拆細 → 加新 row（標明拆自誰、所在輪次）
• 每輪結束 → 更新「目前輪次」欄

下次 session 重啟時，讀 dispatch-plan.md 就知道哪些 agent 沒跑完、從哪接續。詳見「Resume 模式」章節。

3. 使用者特殊需求 → 獨立 agent

若使用者在 /trip-plan 步驟 3 的開放式補充、或 /trip-research 第一階段的優先主題中，強烈表達特定需求（不是一般興趣，而是「這趟一定要 X」），這個需求自動升格為獨立 agent，不要擠進既有主 agent 裡。

偵測訊號（任一）：

• 「一定要」「必須」「重點就是」「主要為了」這類詞
• 跟同行旅伴有關的差異化需求（例如「女生想買彩妝保養品」「小孩一定要玩水」）
• 有特定節目 / 季節限定活動（K-pop 演唱會、煙火大會、球賽）
• 有特殊身體條件影響景點挑選（膝傷不能登山、孕婦要低強度）

例（本次測試場景，釜山案）：使用者強調「女生要彩妝保養品 + 知名購物點」→ 獨立 R_shop agent 專攻購物 + 彩妝，負責清單 I1-I6 這類專題項，不擠進 R1 核心體驗。

6. 序列依賴（gate agent 與主研究的關係）

gate agent（簽證 / 護照 / 保險）有輕微序列依賴：簽證決定要不要繼續做研究，所以 gate 比主研究 agent 早一點點派、但可以平行跑。

階段	派什麼
派發前（並行起跑階段內）	派 gate agent 到背景（run_in_background: true）。不等 gate 回，繼續跟使用者收集優先主題、寫 research-checklist
第 1 輪派 sub-agent	規劃好的主迷你 agent（10-15 個一輪）+ 季節 agent（如有）
gate 結果	gate 通常在第 1 輪期間就回來。若 🟢 → 主研究繼續；若 🔴 紅燈 → 中止主研究、用 AskUserQuestion 處理

5. 範例分派（清單 ~38 項、深度 mode、有特殊購物需求）— 釜山案實測

Agent	負責清單項	搜尋預算	派送輪
gate	A0-1~A0-4 簽證 / 護照 / 保險	15	第 1 輪（背景）
R1a	A1 釜山景點 + A2 IG spot	8	第 2 輪
R1b	A3 慶州 + A4 大邱景點 + A5 夜生活 + A6 韓服	8	第 2 輪
R2a	B1 預算 + B2 釜山必吃 + B4 飲水	8	第 2 輪
R2b	B3 慶州大邱必吃 + B5 IG 咖啡	6	第 2 輪
R3a	C1 機場接駁 + C2 市內交通 + C3 票券	7	第 2 輪
R3b	C4 城際 KTX + G1 航班 + G2 訂票	7	第 2 輪
R4	D1-D4 住宿 + E1-E7 安全 + H1-H5 保險	25	第 2 輪
R_shop_a	I1 購物熱點 + I3 藥妝店 + I4 退稅	8	第 2 輪
R_shop_b	I2 必買清單 + I5 大邱購物 + I6 IG 選物店	8	第 2 輪
R_season	F1-F4 9 月初當季特殊	6	第 2 輪（同步派）

共 11 個 agent，gate 1 個第 1 輪、其餘 10 個第 2 輪一次派完。實測成功率 100%（早期版本拆成 5 個大 agent 時失敗率 80%）。

若使用者走住宿自理 → R4 縮成只做安全 + 保險；若已訂機票 → R3b 只做城際。

6. 派送總表（Dispatch Plan）— 派 agent 前必須先列給使用者看

為什麼必要：使用者（尤其手機 / 桌電 App）看不到 sub-agent 內部活動，只能靠主執行緒輸出的文字判斷進度。**先有一份「總表」**讓他們知道：「我請了 11 個小幫手，分別在做這 11 件事」，後續每個 agent 回報時對得上號，焦慮會大幅降低。同時這份總表也是後續 resume / 補派 / 完成度檢查的單一真實來源。

流程

1. 寫完 research-checklist.md 後，立即依上一節策略決定 agent 拆法（誰負責哪幾項、搜尋預算多少）
2. 把 agent 拆法寫進 ./$TRIP/research/dispatch-plan.md（格式如下）
3. 在主對話用表格輸出給使用者看，並告知「我馬上開始派，每個 agent 回來會立刻講」
4. 同步用 TodoWrite 為每個 agent 建一個 todo（status=pending），這樣 App UI 也看得到進度

dispatch-plan.md 格式

# 派送計畫 — {目的地}

> 建立時間：{YYYY-MM-DD HH:MM}
> 最後更新：{YYYY-MM-DD HH:MM}（每次狀態變動更新）
> Mode：multi-agent（從 trip-meta.md 讀）
> 研究清單總項數：{N}
> 預估 agent 總數：{M}（會因失敗拆細變動）
> **預計輪次：{ceil(M / 12)} 輪 — 第 1 輪 {n1} 個 + 第 2 輪 {n2} 個 + ...**
> **目前輪次：{R} / {total_rounds}+**

## 拆分原則
- 每個迷你 agent 負責 2-4 個清單項
- 每個 agent 搜尋上限 6-10 次
- 嚴格逐項 flush（每寫完 1 項立即覆寫整檔）
- 一輪 ≤ 15 個 agent（避免 main token 爆）

## Agent 清單

| Agent ID | 負責清單項 | 主題摘要 | 搜尋預算 | 所在輪 | 狀態 | 報告檔 | 失敗原因 / 拆自 |
|---|---|---|---|---|---|---|---|
| gate | A0-1~A0-4 | 簽證 / 護照 / 保險 | 15 | 0 (背景) | pending | `agent-0-gate.md` | — |
| R1a | A1, A2 | 釜山景點 + IG spot | 8 | 1 | pending | `agent-R1a.md` | — |
| R1b | A3-A6 | 慶州大邱景點 | 8 | 1 | pending | `agent-R1b.md` | — |
| R1b-1 | A3, A4 | 慶州景點 + 美食 | 6 | 2 | pending | `agent-R1b-1.md` | 拆自 R1b（timeout）|
| R1b-2 | A5 | 韓服 | 4 | 2 | pending | `agent-R1b-2.md` | 拆自 R1b（timeout）|
| R1b-3 | A6 | 夜生活 | 4 | 2 | pending | `agent-R1b-3.md` | 拆自 R1b（timeout）|
| ... | ... | ... | ... | ... | ... | ... | ... |

狀態值定義

• pending — 已寫進清單，還沒派
• running — 已派出去，等回報
• completed — 回來了 + 報告完整（≥ 80% 有內容）
• partial — 回來了但內容不足（50-79%）
• failed — 撞 timeout / 報告完全空 / < 50%
• superseded — 被拆細補派取代（之後不再看 — 用拆細的 row）

何時更新（每個狀態變動都要 Edit 寫回）

• 每派一個 agent → status: pending → running
• 每個 agent 回來 → 改 status（completed / partial / failed）+ 在主對話講一句
• 失敗 → 加新 row（拆細補派 row 標明「拆自誰」）+ 把舊 row status 改 failed 或 superseded
• 每輪結束 → 更新「目前輪次」+ 「最後更新」時間

為什麼每次都要寫：防止 session 異常掛掉。下次 Claude 重啟讀 dispatch-plan.md 就能 resume，不用全重跑。

第四階段：Agent Prompt 撰寫指引

派出 agent 時，每個 agent 的 prompt 必須包含：

1. 目的地和旅行日期
2. 負責的清單項編號（例如「你負責 A1、A2、B1、B3」），要求 agent 在報告中按清單編號組織回答
3. 使用者在第一階段指定的優先主題（例如「使用者特別想挖美食與歷史文化」），要求 agent 在這些主題上深度挖、非優先主題走標準深度
4. 從畫像中提取的相關偏好（不要把整個畫像丟進去，只取相關部分）
5. 明確的研究範圍和產出格式
6. 要求附上 Google Maps 連結（格式：https://www.google.com/maps/search/{名稱+街道或地址}，搜尋字串一律帶街道名或完整地址）
7. 要求以使用者的語言撰寫報告（從對話語言判斷）
8. 使用 subagent_type: "general-purpose" 確保有網路搜尋能力
9. 防呆規則（下一節，逐字複製到 prompt）

Sub-agent 防呆規則（必須逐字寫進每個 agent 的 prompt）

實測過：sub-agent 在跑社群密集型任務（IG / TikTok / 小紅書搜尋）時，常陷入「一直搜、不寫檔」的 loop，最終逾時。以下規則必須逐字複製到每個 agent 的 prompt 末尾（不要溫柔改寫，硬指令才會被遵守）：

【執行紀律 — 不得違反】

1. 你的「第一個工具呼叫」必須是 Write，把報告骨架寫到指定路徑。
   骨架必須含每一個你負責的清單項作為 H2 標題（例如 ## A1: ..., ## A2: ...），
   每個 H2 下面先放 `TODO: 待補` 占位符。
   在寫出骨架前，禁止任何 WebSearch / WebFetch / 其他工具呼叫。

2. **每完成 1 個區段（甚至每加 1 個推薦項目）必須用 Write 覆寫整個報告檔（flush 進度）。**
   不是「2-3 個」是「1 個就 flush」。實測過：等 2-3 個區段才 flush 會撞 5 分鐘 idle timeout，
   前面的工作會全部消失。寧可多寫幾次 Write（成本很低）也不要等。

3. 搜尋上限（**這是迷你 agent，總預算很緊**）：
   - **整份報告總 WebSearch 次數上限 6-10 次**（看主 Claude 在派你時給的數字）
   - **社群（IG / TikTok / 小紅書）很重要要查，但用對姿勢**：
     - 首選：Google 搜「{關鍵字} site:instagram.com」「{關鍵字} 小紅書」這類間接搜尋
     - 次選：搜「{地點} ptt 2025」「{地點} blog 推薦」找第三方攻略整理文（已經吸收社群口碑）
     - **直接 WebFetch IG / TikTok 個別貼文連 2 次失敗就停手**，改走前兩個姿勢，不要 loop
     - 不論抓不抓得到，**報告必附社群搜尋連結**（IG / TikTok / 小紅書）讓使用者自驗
   - 多用「合併搜尋」：一次搜「釜山 必訪景點 ptt 2025」就拿到 8-10 個景點，
     不要每個景點各搜一次（10 個景點 = 10 次搜，預算就爆了）
   - 超過上限剩下的項目標「⚠️ 因搜尋預算耗盡未深查」並收尾
   - 寧可寫出「不完美但完整」的報告，也不要追求完美而逾時

4. 完成的定義：每個負責的清單項都必須有內容（即使是「⚠️ 無可靠資料」），
   不能留 TODO。最後一個工具呼叫應該是 Write 收尾版。

9. Source citation 規則：
   • 每個關鍵事實（票價、營業時間、餐廳地址、交通時刻、簽證要求等）都必須附 URL，格式為「來源」或直接附 URL
   • 若找不到可靠來源，該項必須標「⚠️ 無可靠來源，請自行確認」
   • 不得寫出未經查證的數字或名稱
10. 交叉驗證規則：

• 關鍵事實（會直接影響行程或金錢的：票價、營業時間、簽證規則、保險要求）至少須有 2 個來源
• 兩個來源必須是不同 root domain（例如 gov.tw + lonelyplanet.com，不能是 example.com/a + example.com/b）
• 若兩個來源說法不一致，標「⚠️ 資訊分歧：A 說 X，B 說 Y，建議出發前再次確認」並附雙方 URL

11. 資訊來源優先順序（依清單類別分流）：

體驗類（A 核心體驗、B2 必吃食物、F1-F3 節日市集、夜生活、拍照 spot、hidden gems、咖啡 / bar / 當紅店）— 使用者真正要的是「此刻在地人 / 旅人推什麼」。Instagram / TikTok / 小紅書是潮流訊號的命脈，必須優先使用，傳統旅遊媒體（Lonely Planet / TripAdvisor）往往過時或太主流。

優先序：

• Instagram > TikTok > 小紅書 > YouTube vlog > Reddit > Google Maps reviews
• 目的地為日韓 / 東南亞時，小紅書 升到第 2
• 使用者國籍為中港台時，小紅書 升到第 1-2

如何用社群（戰術重點）— 2026-04 釜山案實測歸納：

• ✅ 首選：用 Google 搜「{關鍵字} site:instagram.com」「{關鍵字} 小紅書」「{關鍵字} reddit」。Google 索引到的公開貼文 / 標籤頁 / 第三方整理文章，多半可以讀到摘要、點讚數、推薦理由
• ✅ 次選：搜「{地點} ptt 2025」「{地點} blog 推薦」「{地點} 小紅書 攻略」，這類部落格 / 攻略文常常已經彙整好 IG / 小紅書熱門推薦，等於間接吸收社群口碑
• ✅ 報告中一律附「社群搜尋連結」讓使用者自驗（IG: https://www.instagram.com/explore/search/keyword/?q={店名}、TikTok: https://www.tiktok.com/search?q={店名}、小紅書: https://www.xiaohongshu.com/search_result?keyword={店名}）— 因為實時人氣每月在變，使用者點開看當下狀態最準
• ⚠️ 要小心：直接 WebFetch IG / TikTok 個別貼文 URL 經常會回登入牆或 404。遇到 2 次抓失敗就停手，改用上面的 Google 搜尋姿勢，不要在同一個項目重複硬抓（會吃光搜尋預算）
• ⚠️ 小紅書相對友善：很多公開頁面 WebFetch 抓得到，可優先嘗試，但若主題沒有中文使用者熱度（例如歐美小眾景點），命中率仍低
• 抓不到任何社群信號的項目就標「⚠️ 無社群驗證，請點搜尋連結自驗」並前進，不要 loop

行政類（A0 簽證、C 交通、D 住宿政策、E1-E5 安全 / 電壓、G 機票規則、H 保險）— 錯了會出事：

• 優先序：官方政府 / 公司網站 > 權威媒體（Lonely Planet、BBC Travel、官方觀光局）> 其他
• 此類不看社群，社群資料無論幾顆愛心都不能當行政決策依據

第五階段：回收 + 完成度檢查 + 失敗回復

所有 agent 回報（或部分回報逾時 / 撞 limit）後，必做的三件事：

1. 掃每份報告的完成度（先做，才知道要不要重派）

跑 Bash：

cd "$TRIP/research"
for f in agent-*.md; do
  [ -f "$f" ] || continue
  h2=$(grep -c '^## ' "$f")
  todo=$(grep -c 'TODO' "$f")
  [ "$h2" -eq 0 ] && echo "$f: 骨架未寫（嚴重失敗）" && continue
  complete=$((h2 - todo))
  percent=$((complete * 100 / h2))
  echo "$f: $complete/$h2 區段完成（${percent}%）"
done

完成度判定：

完成度	視為	動作
≥ 80%	✅ 完成	納入最終報告
50-79%	⚠️ 部分完成	關鍵項缺要補派，其他項在結尾 disclaim
< 50% 或骨架未寫	❌ 失敗（可能撞 usage limit / timeout）	見下節「失敗回復」

2. 失敗回復（usage limit 偵測）

若 多份報告 同時完成度 < 50%，高機率是撞 usage limit（token 額度爆）。告訴使用者，用 AskUserQuestion：

選項	說明
等 limit 重置後重派（推薦，最完整）	告訴使用者重置時間（從通知訊息裡的 resets XX:XX UTC 取出）。記下失敗的 agent 清單。使用者下次打 /trip-research 進 resume 模式只重派失敗的
用簡化 prompt 立刻重派	每個失敗 agent 改派簡化版：搜尋上限砍半（30 → 15）、只做 must-have 項、略過 nice-to-have。雖然可能再撞 limit，但 token 用量較低
直接拿現有資料進 /trip-go	缺的部分在後續行程表標「⚠️ 未研究，建議行前自查」。適合時間緊迫的使用者

若 單一報告 < 50%（其他都 OK）→ 直接補派簡化版就好，不用驚動使用者。

3. 對照清單 + 補派關鍵缺項

讀 research-checklist.md，每項更新：

• - [x] 已覆蓋（對應 H2 有、非 TODO、有內容）
• - [~] 部分覆蓋（H2 有但短 / 標「⚠️ 無可靠來源」）
• - [ ] 未覆蓋（完全沒寫 / TODO）

關鍵項缺 → 補派一個簡短 agent（例如「只查 E3 緊急聯絡」）。搜尋上限 10 次，專攻 1-3 個項目。 關鍵項定義：簽證、護照、保險、緊急聯絡、核心景點、使用者特殊需求、機票（若需要）。

次要項缺 → 在結尾 disclaim：「小費文化 / 廁所資訊 這幾項沒查到，建議出發前自行確認」。

4. Source citation 覆蓋率

掃每份報告，計算「關鍵數字 / 事實後 100 字內有沒有 URL」比率。低於 80% 時列出缺來源的項目，警告使用者。

5. 更新清單檔

回收結果存為 ./$TRIP/research/research-checklist.md（覆蓋空白版）。

Resume 模式（重新執行 /trip-research 時）

核心：讀 ./$TRIP/research/dispatch-plan.md 看 agent 狀態，從中斷點接續（這是 session 異常掛掉的救命機制）。

偵測時機

skill 開頭第一件事（在讀 trip-meta / profile 之前），檢查兩個條件：

1. ./$TRIP/research/dispatch-plan.md 存在 → 進 Resume 流程
2. ./$TRIP/research/agent-*.md 已有報告（但無 dispatch-plan.md，舊版資料）→ 走原本的「補失敗 / 全部重跑」流程

Resume 流程（有 dispatch-plan.md）

**讀 dispatch-plan.md，逐 row 看 status，**自動分流：

Status	動作
pending	還沒派出去，這輪重派（對應 agent ID 的 prompt 重新組）
running	上次派了沒收到回報（session 中途斷）→ 檢查報告檔是否有內容 → 有就改 partial，沒就改 pending 重派
completed / partial	不動，已有結果
failed 但下面沒有對應拆細 row	加拆細 row、改 status 為 superseded
superseded	跳過（看拆細 row）

用 AskUserQuestion 跟使用者確認：

選項	說明
從中斷點接續（推薦）	自動把 pending / running 重派、failed 拆細補派；現有 completed 不動
全部重跑	rm -f ./$TRIP/research/agent-*.md dispatch-plan.md research-checklist.md，跑完整 skill 流程
取消	什麼都不做，退出

選「從中斷點接續」時，跳過第一階段（不重問國籍 / 護照 / 優先主題，因為畫像已有 + checklist 已寫）。直接從「讀 dispatch-plan.md → 重派該重派的 → 跑剩下的輪次」開始。

為什麼 dispatch-plan.md 是救命關鍵

session 異常掛掉時：

• 對話 context 全失（Claude 不記得跑到哪）
• 但 dispatch-plan.md 在 disk 上，每個 agent 狀態都有寫
• 重啟新 session 讀檔就還原全部進度

核心紀律：所有 agent 狀態變動都必須 Edit 寫進 dispatch-plan.md（不能只活在對話 context 裡）。

報告儲存

每份 agent 報告存到 ./$TRIP/research/ 目錄：

• 前置調查：agent-0-gate.md（一律有）
• 研究清單：research-checklist.md（派 agent 前建立、回收後更新）
• 標準方案：agent-A.md、agent-B.md
• 深度方案：agent-R1.md ~ agent-R6.md
• 補派（如有）：agent-patch-{編號}.md

建立或更新 ./$TRIP/research/index.md，列出所有報告的主題和連結。

派 agent 時記得：每個 agent 的 prompt 裡要明確告訴 agent 報告寫到 ./$TRIP/research/agent-X.md（把 $TRIP 展開成實際資料夾名），agent 沒辦法自己讀 current-trip 指標檔。

研究完成後

1. 摘要關鍵發現 — 不要只說「報告已生成」，要摘出 3-5 個最重要的發現直接告訴使用者
2. 顯示研究清單完成度 — 「清單 28 項，26 項已覆蓋、2 項建議自行確認」
3. 顯示 Source citation 覆蓋率 — 低於 80% 列出缺來源的項目
4. 預算初步試算 — 彙整住宿+交通+飲食+門票的概算
5. 提出需要使用者決策的問題 — 用 AskUserQuestion 呈現。每題必須含「幫我決定（推薦）」兜底選項。問題來自研究中發現的重要分歧點（例如：去 A 還是 B、選哪個活動、要不要租車）

「幫我決定」處理原則（決策問題）：

• 依使用者興趣、預算、旅伴給合理預設
• 選後在對話中告知「根據你的 X，我替你選了 Y，可後續再改」

進度追蹤

用 TaskUpdate 更新任務狀態（任務由 /trip-plan 建立）：

• 開始時：把「研究目的地」設為 in_progress（activeForm: 「研究中，agent 跑完會自動回報」）

• 完成時：把「研究目的地」設為 completed，告訴使用者「跟我說『下一步』就會繼續（或直接打 /trip-go）」

  ⚠️ 不要在收尾推使用者用 /trip-go 自己的特定意圖詞（例如「排行程」），那會繞過 /trip 的進度偵測。讓使用者統一用「下一步」走 dispatcher 最安全。