Perplexity Deep Research
调用 Perplexity Agent API（POST /v1/agent）执行带引用的多步浏览研究。在调用 API 之前，该技能需要一个结构化的信息收集+计划审批循环，以便 Agent 使用正确的来源、拥有正确的上下文，并以可快速浏览的格式返回报告。
方法论
本技能是 Growth Unhinged 深度研究方案（针对 GTM）的程序化实现：https://www.growthunhinged.com/p/deep-research-for-gtm。文章中五项建议与以下步骤一一对应：
| 文章建议 | 实施方式 |
|---|---|
| 提供全面上下文（目标、GTM/产品、约束、首选来源） | 第一步 — 五维信息收集 |
| 先请求研究计划，批准后再执行 | 第二步 — 计划审批关卡（未经批准不产生API费用） |
| 指向高质量来源；优先使用一手资料而非二手资料；引用所有内容 | 格式块 — 来源表、一手资料优先级、行内引用要求 |
| 指定报告格式；摘要和表格优于散文（金字塔原理） | 格式块 — 先写总结，再写对比表，先列结论再提供背景 |
结构化提示（<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等）、允许 vs 禁止的域名、时间范围窗口。
- 范围边界 — 明确排除的内容、Agent不应做出的假设。
决定是否提问：
- 如果所有五个维度都已充分回答 → 跳过澄清部分，直接进入第2步（起草计划）。不要仅仅为了确认已知信息而提问。
- 如果有一个或多个维度缺失或存在歧义 → 使用
AskUserQuestion只询问缺失的部分，以一个整合块的形式呈现。明确列出你已经理解的内容（以便用户纠正你）和你仍然需要了解的内容。 - 如果用户说“直接开始”/“由你判断” → 跳到第2步，在计划中列出对每个缺失维度的假设，以便用户仍能在那里纠正。
倾向于尽可能少问问题。一个完整描述的一段落查询往往不需要任何澄清——直接起草计划。
第2步 — 制定研究计划并获取批准
在调用API之前，请在回复中起草一份研究计划并请求用户批准或编辑。计划必须包括：
- 研究问题 — Agent将回答的具体子问题
- 方法论 — 如何评估/比较选项、使用什么框架
- 来源策略 — 优先考虑哪种来源类型、避免哪些类型、任何域名过滤器或时间范围窗口
- 报告结构 — 最终报告将使用的章节标题
- 可交付成果 — 除散文外，是否包含表格、对比矩阵、模板、检查清单、代码片段？
- 开放假设 — 你猜测的任何内容，用户应更正
等待明确批准（“看起来不错”、“开始”、“运行”、计划的编辑等）后再继续。如果用户编辑了计划，请在运行前重新确认。
第2.5步 — 输出预算检查（强制要求 — 防止截断）
advanced-deep-research 预设有约 ~16k tokens / ~10k 单词 每响应的实际输出上限。超出此上限的计划将被静默截断——目录中列出的章节将不会出现，大型可交付成果（钩子库、N天日历、反模式目录）会在表格中间被截断。在运行之前，你必须对照此上限进行预算。
每次调用的输出预算（硬限制）：
| 项目 | 每次调用上限 |
|---|---|
| 主要章节（H2） | 8 |
| 大型表格（6行以上，4列以上） | 4 |
| 条目化库/目录（钩子、模板、示例、想法） | 所有库总计10个条目 |
| 长篇可交付成果（N天日历、逐镜头脚本、完整剧本） | 1 |
| 总散文（不包括表格） | 约4,000单词 |
表明计划在一次调用中过大的危险信号：
- 目录超过8个章节
- 计划承诺“25+钩子”/“30天日历”/“20个模板”同时包含多个矩阵
- 计划要求在同一个调用中交付多个大型可交付成果（例如钩子库、内容日历、逐镜头模板和反模式目录）
- 计划深入覆盖>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)标题下，以便Agent不必浪费步骤重新挖掘相同内容。 - 每次调用完成后，
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）。当由Agent调用时，使用该技能相对路径——在 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词摘要，以便Agent不重新研究它们。明确说明“不要重新覆盖X、Y、Z；只关注A、B、C。” - 告知用户 被截断的内容，并在运行前展示后续计划。
展示：关键见解、报告中显示的美元成本、任何显著来源分歧、以及截断标志（如果适用）。
高级模式
以下模式可可靠地提高输出质量。在起草计划的第2步中使用它们。
在查询中引用特定专家或框架
在查询中命名3-6位相关专家、作者、创作者或命名框架，可为Agent提供具体的来源以搜索和比较。报告将变为已知观点的比较，而非匿名综合。
查询示例片段：
- "比较 、 和 用于...的框架"
- "根据 方法论，评估..."
- "协调 （在<书籍/博客>中）与 推荐的方法..."
当专家定期发表内容（论文、视频、帖子、演讲）时效果最佳——Agent可以获取他们的原始材料。
指定量化的可交付成果
不要请求“足够数量的示例”，而是说明确切的数量和形状。这将锁定范围、防止漂移，并在超出预算时及时显现（对照第2.5步检查）。
好的可交付成果说明：
- "一个对比矩阵：8行（每个供应商一行）、5列（价格、延迟、认证、SDK、合规性）"
- "一个包含恰好10个模板的库，按3个类别分组"
- "一个14天的序列，每天一个项目"
避免："全面库"、"几个示例"、"许多选项" —— 这些是导致截断或摇摆的邀请。
将上下文预加载到 --instructions 中，而非查询中
查询应保持在紧凑的1-2句话。任何关于用户情境、约束、先前决策或来源偏好的内容都放入 --instructions 中。这使Agent的搜索查询保持聚焦，同时综合结果仍扎根于你的上下文中。
必需格式指令（始终包含在 --instructions 中）
每次运行必须在 --instructions 字符串中嵌入这些格式要求，以使报告可快速浏览且可信：
SCOPE & SIZE CONSTRAINT (read first —
<此处内容已截断，但翻译应继续>