qianfan-deepresearch

调用百度千帆 DeepResearch Agent API 自动生成深度研究报告（输出 Markdown 与 HTML 两种格式），一键完成「创建会话 → 发起研究 → 自动跳过澄清 → 自动 确认大纲 → 获取报告下载链接」完整流程。支持三种深度模式：lite（轻量版， 速度快，默认）/ standard（标准版，深度均衡）/ pro（高级版，最详尽，适合 长报告深度研究）。适用于行业研究、市场调研、竞品分析、技术综述、政策解 读、决策论证等需要结构化长报告的场景；当用户提及"轻量版/标准版/高级版/ lite/standard/pro"或"深入研究/详尽报告/快速调研"等深度偏好时，应优先 使用本技能。

DeepResearch Agent 深度研究报告生成

🎯 触发条件 (Usage)

适合使用本技能的场景

• 用户明确请求调用 DeepResearch / 深度研究 Agent。
• 用户需求涉及以下场景：
  • 垂直专业领域深度调研：技术原理、底层架构、行业标准、政策细则、细分领域专业知识拆解
  • 复杂事实溯源与交叉求证：争议信息辨析、多版本内容核对、事件完整始末 / 时间线梳理、网传信息真伪核查
  • 行业趋势与竞品深度分析：市场规模、产业链格局、发展研判、竞品路线 / 商业模式优劣势对比
  • 学术研究与深度创作素材挖掘：文献汇总、课题调研、历史 / IP 冷门考据、长文案论据与背景资料搜集
  • 跨领域复合型复杂问题：多要素关联、长逻辑链推理、多层级因果拆解、宏观议题综合解读
  • 小众冷门稀缺信息检索：老旧资料、小众文化、绝版内容、细分冷门工具、小众外文资料整理
  • 时事热点深度解读：结合历史渊源、过往案例、政策背景，分析事件深层逻辑与长期影响
  • 决策支撑与方案论证：技术选型、落地方案对比、成本 / 风险 / 可行性调研、多维度选型评估

不适合使用的场景

• 简单问答 / 闲聊：用户只想要一两句快速回答，不需要长报告。
• 实时 / 即时性查询：股价、天气、比分等需要秒级响应（本技能报告生成通常 10–30 分钟）。
• 翻译、摘要、改写已有文本：使用通用语言能力即可，无需深度研究。
• 纯计算 / 格式排版 / 简单文案改写 / 代码生成 / 调试：与深度研究无关。

---

⚙️ 工作流 (Workflow)

整个流程为 单阶段自动执行：Agent 只需运行一条命令，脚本自动完成跳过澄清、确认大纲，最终向 stdout 输出报告下载链接。

Step 1：参数确认

执行前 必须 确认以下参数：

参数	必填	来源 / 默认
query	✅	在保留用户研究意图的前提下构造高质量 query（详见 Step 1.5 Query 构造原则）。模糊到无法构成研究主题时，先向用户澄清再调脚本
api_key	✅	① 对话上下文 → ② 环境变量 QIANFAN_API_KEY → ③ 都没有，弹出澄清向用户索取（提示文案：「请输入千帆 API Key（格式：bce-v3/ALTAK-...）」）
agent_id	❌	① 对话上下文 → ② 环境变量 QIANFAN_AGENT_ID；都无则不传
version	❌	lite（默认，速度快）/ standard（深度均衡）/ pro（最详尽）。优先级：① 用户原话出现版本名 / 中文别名 / 深度偏好关键词时按下表映射；② 否则直接用 lite，不要询问用户。详见 版本映射表

优先级：agent_id > version > 默认 lite。同时提供 agent_id 与 version 时，以 agent_id 为准。

版本映射表

用户原话中显式出现 下列关键词时，把 --version 设成对应值；未出现任何关键词则不进入映射，直接默认 lite 且不询问。

用户原话出现	--version
「lite」「轻量版」「快速调研」「简版」「快一点」	lite
「standard」「标准版」「常规版」「均衡」	standard
「pro」「高级版」「深度版」「最详尽」「深入研究」「详尽报告」「写得详细些」「专业版」	pro

⚠️ 仅当用户明确表达深度偏好时才映射；若用户只是描述研究主题的复杂度（如"这个比较复杂"、"涉及多个领域"），不要自动升级到 pro——保持默认 lite。

Step 1.5：Query 构造原则

⚠️ 关键背景：脚本会 自动跳过 DeepResearch 的需求澄清阶段——query 一旦发出就没有补救机会。因此 query 必须信息充分，否则会得到发散、低质量的大纲与报告。

好的 query 包含 4 要素（按需组合，不必齐全）

要素	含义	示例
① 主题对象	研究谁 / 什么（必含）	「小米汽车」「ChatGPT 训练范式」
② 研究角度	从什么维度切入	「竞争格局」「技术路线」「投资价值」
③ 时间范围	信息窗口	「2025 年」「近三年」「自 2020 年起」
④ 范围边界	地区 / 细分 / 对比集合	「中国市场」「20–30 万价位」「头部三家」

质量梯度对照：

• 🔻 弱：「研究新能源汽车」（只有 ①）
• ⚪ 中：「2025 年中国新能源汽车市场」（①③④）
• ✅ 强：「2025 年中国新能源汽车市场竞争格局，重点对比比亚迪、小米、特斯拉的产品矩阵和价格策略」（①②③④ 齐备）

Agent 处理用户原话的三档规则

档	触发条件	应当做的处理
A 原样	用户原话已包含明确的主题对象 + 至少一个角度 / 时间 / 边界	原样传入，不擅自添加用户未提到的视角或范围
B 最小改写	用户原话有 ① 会话引用（"上面那个"、"刚才说的"）② 口语噪音（"呃"、"那个"、"帮我看下"）③ 上下文已明确表达的隐式信息	仅做以下三类改写： • 会话引用解析：把"上面那个话题"替换成具体主题 • 噪音清理：去掉口头禅 • 隐式信息补全：补入用户对话中明确表达过的视角 / 时间（如先说"我做投资的"+"研究小米汽车" → 可补"从投资视角")
C 澄清后再调	满足任一：① query 仅 1–2 个泛词且无任何角度（"研究 AI"、"小米"）② 多个研究方向并列冲突 ③ 涉及对比但未说对比对象 ④ 时间范围对结论影响关键但完全缺失	不要硬传——调用 Agent 的澄清能力向用户问清后再走 Step 2

用户原话 → 实际传入 query 的转换示例

用户原话	档	Agent 实际传入的 --query
「2025 年小米汽车的发展历程和竞争格局」	A	2025 年小米汽车的发展历程和竞争格局
「呃帮我看下小米汽车的事儿，最近的」	B	小米汽车近期发展动态
「就上面那个话题写个报告」（前文聊的是"小米 SU7 的销量"）	B	小米 SU7 销量表现深度分析
「研究小米汽车」（前文用户说"我做投资的"）	B	小米汽车投资价值分析
「研究 AI」	C	先澄清：「想研究 AI 的哪个方面？比如大模型技术路线、AIGC 应用市场、AI 芯片产业，或者其它？」
「对比一下」（无对比对象）	C	先澄清：「想对比哪些对象？以及从哪些维度对比？」

不允许的改写

• 不得引入用户未提到的视角 / 范围 / 偏向——比如用户说"研究小米汽车"就硬加"竞争格局分析"
• 不得替换主题对象——比如把"小米 SU7"改成"小米汽车整体"
• 不得为了凑齐 4 要素而编造时间范围或地区

Step 2：调用脚本（必须设置长超时）

bash

指定 version 调用：
python deepresearch.py run \
    --query "研究小米汽车发展历程" \
    --api-key "bce-v3/ALTAK-..." \
    --version lite

或指定 agent_id 调用（与 version 都可选，同时提供时以 agent_id 为准，都不提供默认 version=lite）:
python deepresearch.py run \
    --query "研究小米汽车发展历程" \
    --api-key "bce-v3/ALTAK-..." \
    --agent-id "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

⚠️ MUST：调用 bash 工具时 timeout 必须设置为 3600 秒（1 小时），否则脚本会被强制终止。

Step 3：解析 stdout 的 JSON

脚本 stdout 仅输出一行结构化 JSON（进度日志写到 stderr，不影响解析）：

json

{
  "conversation_id": "...",
  "outline": {"title": "...", "description": "...", "sub_chapters": [...]},
  "outline_preview": "标题：...\n描述：...\n\n章节结构：\n  1. ...",
  "files": {
    "md":   {"filename": "report_xxx.md",   "download_url": "https://..."},
    "html": {"filename": "report_xxx.html", "download_url": "https://..."}
  }
}

Step 4：向用户展示结果（严格遵守模板）

必须 逐字按照下方模板输出最终结果给用户。仅替换 {...} 占位符；模板中的所有其它字符（含空行、冒号、连字符、固定文案）不得修改、增删或重新排版。

text

深度研究已完成！

研究大纲：
{outline_preview 字段内容（原样插入，保留换行与缩进）}

报告下载链接：
- Markdown 版本：{files.md.download_url}
- HTML 版本：{files.html.download_url}

占位符填充规则：

占位符	取值	强制要求
{outline_preview 字段内容}	stdout JSON 的 outline_preview 字符串	原样插入：保留原换行与缩进；不得加粗、不得改成 markdown 标题（如 # 标题）、不得加 emoji、不得重新排版章节列表
{files.md.download_url}	stdout JSON 的 files.md.download_url	裸 URL：不得包成 [文字](URL) 形式、不得加引号或空格
{files.html.download_url}	stdout JSON 的 files.html.download_url	同上

固定文案禁止改写：「深度研究已完成！」「研究大纲：」「报告下载链接：」「- Markdown 版本：」「- HTML 版本：」必须 逐字保留。

---

⚠️ 核心约束 (Guidelines)

• MUST 调用脚本时把 bash 工具超时设为 3600 秒——DeepResearch 报告通常耗时 10–30 分钟。
• MUST 仅从 stdout 的 JSON 提取结果；stderr 仅作调试日志，不要从中提取数据。
• MUST 按 Step 1.5 的三档规则 构造 --query：A 档原样，B 档仅做"会话引用解析 / 噪音清理 / 已明示的隐式信息补全"三类最小改写，C 档先澄清再调脚本。
• MUST NOT 在构造 --query 时引入用户从未提到的视角、范围、对比对象、时间窗口或偏向；不得替换主题对象；不得为凑齐 4 要素而编造缺失要素。
• MUST 严格按照 Step 4 模板 逐字 输出最终结果——文案、空行数、冒号、列表符号、行序均不得改动。
• MUST 把 outline_preview 字段 原样 插入展示文本，保留其原始换行与缩进；不得追加 markdown 渲染（不得加粗、不得把"标题："转成 ## 标题、不得加 emoji）。
• MUST 把下载链接以 裸 URL 形式输出，不得包装为 [文字](URL) 等 markdown 链接形式。
• MUST NOT 在 version / agent_id 都未提供时询问用户——直接使用默认 version=lite。
• MUST NOT 重新实现 SSE 解析或 HTTP 调用逻辑——优先调用 scripts/deepresearch.py；需要扩展时基于现有脚本修改。
• MUST NOT 在最终展示前后 添加任何额外文字，包括但不限于：
  • 开场白：「以下是为您整理的研究报告」「报告已生成如下」
  • 收尾语：「希望对您有帮助」「如需进一步调整请告诉我」「祝研究顺利」
  • 解释 / 总结：对大纲做二次解读、总结报告内容、提示后续动作
  • 装饰：emoji、表情、分隔线（---、===）、引导符（📊、📌）
• NEVER 当 stdout JSON 不包含 files.md.download_url 时，禁止编造下载链接——应如实告知用户报告未生成成功。

---

📂 资源说明 (Resources)

文件清单

路径	类型	用途
scripts/deepresearch.py	可执行脚本	单阶段自动调用脚本（run 子命令）：会话创建 → 查询 → 跳过澄清 → 大纲提取 → 自动确认 → 报告下载链接
references/api.md	文档	DeepResearch API 完整接口说明（鉴权、请求 / 响应结构、各阶段示例）
references/workflow.md	文档	完整调用工作流，含 SSE 流解析要点、HTTP 客户端注意事项、Python/Go 实现示例、并发压测、常见问题排查

scripts/deepresearch.py 参数

参数	必填	说明
--query	✅	研究问题（自然语言原文）
--api-key	✅	千帆 API Key，可改用环境变量 QIANFAN_API_KEY
--agent-id	❌	智能体 ID，可改用环境变量 QIANFAN_AGENT_ID，优先级高于 --version
--version	❌	lite / standard / pro，默认 lite
--clarification-wait	❌	检测到澄清事件后等待秒数，默认 10

依赖：标准库 + requests（pip install requests）。

需要深入了解 SSE 流结构、interrupt_id 嵌套 JSON 解析、HTTP 长连接调优、并发压测等技术细节时，请阅读 references/workflow.md。脚本内部已处理好这些细节，正常调用无需关心。

---

🌟 示例 (Example)

Input

用户：「帮我研究下小米汽车，我做投资的，主要看 2025 年的市场表现」

Agent 执行过程

1. 构造 query（Step 1.5，B 档：上下文已明示视角"投资"+ 时间"2025 年"，做最小补全）：
   • 用户原话直接拼接 → 小米汽车 2025 年市场表现（投资视角）
2. 从对话上下文 / 环境变量获取 api_key；未指定版本 → 使用默认 lite。
3. 调用脚本（bash 超时设为 3600s）：

   bash

   python3 scripts/deepresearch.py run \
     --query "小米汽车 2025 年市场表现（投资视角）" \
     --api-key "bce-v3/ALTAK-..." \
     --version lite
   

4. 解析 stdout 的 JSON，提取 outline_preview 与 files.md.download_url、files.html.download_url。

Output（向用户展示）

✅ 正确——必须严格按这个格式，不增不减：

text

深度研究已完成！

研究大纲：
标题：小米汽车 2025 年市场表现投资分析报告
描述：本报告聚焦 2025 年小米汽车的市场表现，从销量、毛利、产品矩阵、
      竞争位势与资本市场反应等维度切入，为投资决策提供结构化参考。

章节结构：
  1. 2025 年市场表现概览
     - 销量与交付节奏
     - 主力车型营收与毛利
  2. 竞争位势与价格段对比
     - 与比亚迪、特斯拉的同价位段争夺
     - 渠道与品牌势能变化
  3. 投资视角下的关键变量
     - 产能爬坡与供应链风险
     - 估值锚与下一阶段催化剂

报告下载链接：
- Markdown 版本：https://qianfan.baidubce.com/.../report_xxx.md
- HTML 版本：https://qianfan.baidubce.com/.../report_xxx.html

❌ 错误——以下违规模式 禁止 出现：

违规类型	错误示例	修正
加开场白	为您整理了深度研究报告，请查收：\n\n深度研究已完成！...	直接以「深度研究已完成！」开头
加收尾语	...HTML 版本：https://...\n\n希望对您有帮助，如需调整请告诉我。	在最后一行 URL 处结束，不要任何后缀
改写固定文案	📊 研究大纲 / ## 研究大纲 / 研究大纲如下：	必须逐字「研究大纲：」
链接包成 markdown	- Markdown 版本：[点此下载](https://...)	必须裸 URL：- Markdown 版本：https://...
重排 outline	把「标题：」转成 # 标题、把「 1. ...」转成 1. ... markdown 列表	把 outline_preview 原样插入，保留缩进
添加二次解读	在大纲后加「这份报告涵盖了……」总结段	不得对内容做任何额外解读