Perplexity Deep Research
呼叫 Perplexity Agent API（POST /v1/agent）以執行具備引用來源的多步驟瀏覽研究。在呼叫 API 之前，此技能需要一個結構化的輸入 + 計劃核准循環，以便代理使用正確的來源、擁有正確的上下文，並以易於瀏覽的格式回傳報告。
方法論
此技能是 Growth Unhinged 深度研究手冊（適用於 GTM）的程式化實作：https://www.growthunhinged.com/p/deep-research-for-gtm。文章中的五項建議與下列步驟一一對應：
| 文章建議 | 強制執行方式 |
|---|---|
| 提供全面的上下文（目標、GTM/產品、限制、偏好來源） | 步驟 1 — 五維度輸入 |
| 先要求研究計劃，核准後才執行 | 步驟 2 — 計劃核准閘門（未經核准不消耗 API 費用） |
| 指向高品質來源；優先使用一手來源而非二手來源；引用所有內容 | 格式區塊 — 來源表格、一手來源優先、要求內嵌引用 |
| 指定報告格式；摘要和表格優於純文字（金字塔原則） | 格式區塊 — 先 TL;DR，然後比較表格，結論在背景之前 |
結構化提示（<goal>、<context>、<sources>、<instructions>） | --instructions 區塊佈局 |
每次呼叫的輸出預算檢查（步驟 2.5）和多呼叫排序（步驟 2.6）是在文章基礎上新增的內容，旨在防止大型 GTM 計劃（如鉤子庫、30 天行事曆、供應商矩陣）常見的靜默截斷失敗模式。
先決條件
PERPLEXITY_API_KEY存在於環境變數中（請至 https://www.perplexity.ai/account/api 取得）- 已安裝
curl和jq
首次使用時執行一次預檢檢查，以確認一切設定正確：
bash ./scripts/check-setup.sh
它會為每個必要條件印出 ✓/✗，並提供遺失項目的複製貼上修復方式。當一切就緒時，退出碼為 0。如果任何檢查失敗，請將輸出顯示給使用者並停止 — 在預檢通過之前不要嘗試執行 API 腳本。
使用時機
- 使用者明確要求「深度研究」、「進階研究」或「perplexity 研究」
- 使用者需要一份附有來源的簡報（公司、人物、事件、技術、法規）
- 需要跨越多個來源進行多步驟瀏覽和綜合的問題
- 需要非常新近資訊且附有內嵌引用的問題
請勿用於：
- 簡單的事實查詢（「X 目前的價格是多少」）— 請改用
WebSearch/WebFetch（更便宜、更快） - 簡單的二元比較（「工具 A 或 B 哪個比較好」）— 單次
WebSearch通常就能解決 - 需要身分驗證或付費牆後方的內容（Perplexity 無法登入）
- 快速的程式碼編輯或可從程式碼庫回答的問題 — 直接內嵌處理更快
- 驗證您已具備上下文的事實 —
WebFetch的精確度已足夠
工作流程（強制性 — 不得跳過步驟）
深度研究會耗費實際金錢，且需要 2–5 分鐘。執行不佳的研究會浪費兩者。務必遵循此循環：
步驟 0 — 驗證設定（僅首次執行）
如果是專案中的首次呼叫，請執行 bash ./scripts/check-setup.sh，並僅在其退出碼為 0 時才繼續。如果報告缺少工具或環境變數未設定，請顯示修復方式並停止。在同一個工作階段的後續執行中，跳過此步驟。
步驟 1 — 審核初始查詢，然後只詢問缺少的部分
首先，閱讀使用者的初始查詢，判斷下列五個上下文維度中哪些已回答、哪些部分回答、哪些完全遺漏。不要重新詢問使用者已告知過您的事項。
五個維度：
- 目標與動機 — 他們想達成什麼目標、輸出將如何被使用（決策、文件、簡報、策略）、已完成的先期工作。
- 產品/情況背景 — 公司/產品/角色、其運作方式、相關的設定細節（規模、階段、GTM、受眾）。
- 限制條件 — 預算、截止日期、員工人數、法律/法規遵循、已排除的選項、不可協商事項。
- 偏好來源 — 指定的專家/創作者、出版類型（學術、一手/政府資料、論壇、分析師、SEC 申報文件、GitHub 等）、允許與禁止的網域、時效性區間。
- 範圍邊界 — 明確排除在範圍之外的內容、代理不應做出的假設。
決定是否提問：
- 如果所有五個維度都已充分回答 → 跳過澄清直接進入步驟 2（草擬計劃）。不要為了確認已知資訊而提問。
- 如果一個或多個維度遺漏或模糊不清 → 使用
AskUserQuestion僅針對缺口提問，並以單一合併區塊呈現。明確列出您已理解的內容（以便使用者可以更正），以及您仍需要的資訊。 - 如果使用者說「直接進行」/「由你判斷」 → 跳至步驟 2，並在計劃中列出您對每個遺漏維度的假設，以便使用者仍可在該處更正。
傾向於少問問題。一個明確的單段查詢通常不需要任何澄清 — 直接進入計劃。
步驟 2 — 草擬研究計劃並取得核准
在呼叫 API 之前，請在回應中草擬一份研究計劃，並要求使用者核准或編輯。計劃必須包含：
- 研究問題 — 代理將回答的具體子問題
- 方法論 — 如何評估/比較選項、使用何種框架
- 來源策略 — 將優先使用的來源類型、將避免的來源類型、任何網域過濾器或時效性區間
- 報告結構 — 最終報告將使用的章節標題
- 交付物 — 除了純文字之外，是否包含表格、比較矩陣、範本、檢查清單、程式碼片段？
- 開放假設 — 您猜測的任何事項，使用者應予以更正
等待明確核准（「看起來不錯」、「進行」、「執行吧」、對計劃的編輯等）後再繼續。如果使用者編輯了計劃，請在執行前重新確認。
步驟 2.5 — 輸出預算檢查（強制性 — 防止截斷）
advanced-deep-research 預設模式每次回應的實際輸出上限約為 ~16k tokens / ~10k 字。超出此上限的計劃會遭到靜默截斷 — 目錄中列出的章節根本不會出現，大型交付物（鉤子庫、N 天行事曆、反模式目錄）則會在表格中間被截斷。在執行之前，您必須針對此上限進行預算評估。
每次呼叫的輸出預算（硬性限制）：
| 項目 | 每次呼叫上限 |
|---|---|
| 主要章節 (H2) | 8 |
| 大型表格（6 行以上、4 欄以上） | 4 |
| 列舉型庫/目錄（鉤子、範本、範例、點子） | 所有目錄總計 10 項 |
| 長篇交付物（N 天行事曆、逐鏡頭腳本、完整劇本） | 1 |
| 純文字（不含表格） | ~4,000 字 |
表示單次呼叫計劃過大的紅旗訊號：
- 目錄包含超過 8 個章節
- 計劃承諾「25+ 個鉤子」/「30 天行事曆」/「20 個範本」以及多個矩陣
- 計劃在同一次呼叫中要求多個大型交付物（例如鉤子庫 AND 內容行事曆 AND 逐鏡頭範本 AND 反模式目錄）
- 計劃深入涵蓋超過 1 個不同的受眾群體或超過 1 個不同的目標
如果計劃符合預算 → 進入步驟 3。
如果計劃超出預算 → 將其拆分成順序性的多呼叫計劃（請參閱下方的「多呼叫排序」），並將其提交給使用者核准後再執行。
步驟 2.6 — 多呼叫排序（適用於大型範圍或相依研究）
有兩個不同的原因需要拆分為多個順序呼叫，兩者使用相同的機制：
(A) 預算驅動拆分 — 計劃超出步驟 2.5 中的每次呼叫輸出上限。將其拆分成重點明確的呼叫，每個呼叫專注於一個主要交付物。
(B) 相依性驅動拆分 — 呼叫 N 的範圍取決於呼叫 N-1 的結果。範例：供應商現狀調查（呼叫 1）用於決定哪些 3 家供應商需要深入分析（呼叫 2–4）。這與規模無關 — 關鍵在於讓後續呼叫能夠根據先前呼叫的結果做出反應。當您真的不知道答案，直到執行完呼叫 1 才知道時，請不要試圖預先規劃所有事項。
任何多呼叫拆分的規則：
- 依序執行呼叫，而非並行 — 每個呼叫應能夠引用或建立在先前輸出的基礎上。
- 每個呼叫必須有一個主要交付物重點。
- 每個呼叫必須符合步驟 2.5 的每次呼叫預算。
- 每個呼叫必須具有個別價值 — 不要建立僅在組合時才有意義的呼叫。
- 在後續每個呼叫的
--instructions中，貼上先前呼叫的關鍵發現（非完整報告，僅為負載較重的結論，約 200–400 字），並置於PRIOR FINDINGS (do not re-research)標題下，以免代理浪費步驟重複研究。 - 每個呼叫完成後，
Read輸出，確認沒有任何內容被截斷（檢查呼叫目錄中的每個章節是否都存在，且沒有表格在中間行結束），並在使用者開始下一個呼叫之前，簡要地向使用者摘要。
將拆分呈現為：
此計劃需要 N 個順序呼叫，因為 <預算/相依性原因>：
呼叫 1 — <重點> (~$X, ~3 分鐘)
呼叫 2 — <重點> (~$X, ~3 分鐘)
...
總計估計成本：$X。批准拆分，或告訴我要刪減什麼。
在執行任何呼叫之前，等待對拆分方案的明確核准。如果使用者編輯了拆分方案，請重新確認。
步驟 3 — 執行研究
一旦獲得核准，就呼叫腳本。透過 --instructions 傳遞已核准的計劃 + 上下文 + 格式要求。當使用者指定時，使用 --domains 和 --recency 旗標。
務必傳遞 --topic <slug>，以便輸出存入 ./docs/research/ 下的一個主題子目錄。在呼叫之前，檢查現有的子目錄（ls docs/research/），並重複使用與研究領域相符的現有 slug，或建立一個新的短 kebab-case slug。如果您要建立新主題，請選擇一個持久的 slug — 在相同領域的未來 3–5 份報告中仍會使用的 slug，而不是來自當前問題的一次性詞組。良好的 slug 形式：vendor-comparison、competitor-analysis、regulation-update、<product-area>。不良的 slug 形式：doppler-vs-vault-2026（過於特定且與日期耦合）。
腳本位於 ./scripts/research.sh（相對於此 SKILL.md）。當由代理呼叫時，請使用該技能相對路徑 — 它在 npx skills 安裝和 Claude Code /plugin 安裝中都能正確解析。
bash ./scripts/research.sh \
--preset advanced-deep-research \
--output ./docs/research \
--topic <topic-slug> \
--instructions "$(cat <<'EOF'
<paste the approved plan + context + format requirements here>
EOF
)" \
"<the research question, refined from the approved plan>"
步驟 4 — 讀取報告並摘要
腳本會印出 Markdown 路徑。在回報之前，務必 Read 該檔案。
截斷檢查（強制性）：
- 確認報告自身目錄中列出的每個章節確實存在於內文中。
- 確認沒有表格在中間行結束，且沒有列舉清單在中間項結束。
- 確認結尾的「來源」、「來源存在歧異處」以及「信心程度與差距」章節都存在。
截斷復原工作流程。 如果任何一項遺漏 → 表示輸出已被截斷。請執行以下操作：
- 確切找出遺漏的內容。 比對報告的目錄與其內文。列出遺漏的章節、不完整的表格（註明最後一個完整行），以及被截斷的清單項目（註明最後一個完整項目）。
- 量化剩餘工作。「仍需要 X 個章節、Y 個項目、Z 行。」
- 提議一個重點明確的後續呼叫，其範圍符合每次呼叫預算。請勿重試相同的範圍 — 它會再次被截斷。
- 在後續呼叫的
--instructions中包含PRIOR FINDINGS— 貼上已完成章節的約 200–400 字摘要，以便代理不會重複研究它們。明確說明「不要重新涵蓋 X、Y、Z；只專注於 A、B、C。」 - 在使用者執行之前，告知使用者哪些部分被截斷，並顯示後續計劃。
呈現：關鍵見解、報告中的美元成本、任何值得注意的來源歧異點，以及適用的截斷標記。
進階模式
這些模式能可靠地提升輸出品質。在步驟 2 草擬計劃時使用它們。
在查詢中指定特定的專家或框架
在查詢中提及 3–6 位相關的專家、作者、創作者或具名框架，為代理提供具體的搜尋來源和比較對象。報告將成為已知觀點的比較，而非匿名的綜合。
查詢片段範例：
- 「比較 <專家 A>、<專家 B> 和 <專家 C> 在... 方面使用的框架」
- 「根據 <具名框架> 方法論，評估...」
- 「調和 <作者 A>（在 <書籍/部落格> 中）與 <作者 B> 推薦的方法...」
當專家經常發表內容（論文、影片、文章、演講）時效果最佳 — 代理可以獲取他們的一手資料。
指定量化交付物
與其要求「足夠多的範例」，不如說明確切的數量和形式。這能鎖定範圍、防止偏移，並在超出預算時顯現（請對照步驟 2.5）。
良好的交付物規格：
- 「一個比較矩陣：8 行（每家供應商一行），5 欄（價格、延遲、認證、SDK、法規遵循）」
- 「一個包含恰好 10 個範本的庫，分為 3 個類別」
- 「一個 14 天的序列，每天一個項目」
避免：「一個全面的庫」、「幾個範例」、「許多選項」— 這些會導致截斷或搖擺不定。
在 --instructions 中預載上下文，而非查詢
查詢應保持簡潔的 1–2 句話。有關使用者情況、限制、先前的決定或來源偏好的任何內容都放在 --instructions 中。這使代理的搜尋查詢保持專注，同時綜合結果仍以您的上下文為基礎。
必要的格式指示（務必包含在 --instructions 中）
每次執行都必須將這些格式要求嵌入 --instructions 字串中，以便報告易於瀏覽且值得信賴：
SCOPE & SIZE CONSTRAINT (read first — …
…
[此處內容因翻譯需求而截斷]