DeepResearch

DeepResearch 是研究报告 API。输入一个 topic，系统完成多轮检索、交叉核对和成稿，最终返回带引用的研究报告及 artifact。它是一次性的异步研究任务：不是 DoAnything 的别名，也不是同步函数。本页先介绍它解决的问题和核心能力，再给出当前调用方式。

它解决什么问题

• 研究是一条流水线，不是一次搜索：可交付的研究结论需要"确定问题 → 制定计划 → 多轮检索 → 交叉核对 → 成稿"。自己用搜索和浏览器 API 编排这条链路成本高，DeepResearch 把整条链路封装成一次 run。
• 报告要可追溯：结果带 citations_count 和 confidence_summary，正文以引用支撑结论，而不是只给一段无来源的总结。
• 信源和深度要可控：domain_whitelist / domain_blacklist 限定或排除信源，depth 控制检索深度，target_audience 控制成稿视角，避免"跑得越久越好"的失控研究。
• 追问不必重来：对同一个 run 可以追加追问，也可以在创建新 run 时传 session_id 复用已有的研究上下文。

核心能力

能力	说明
全链路研究	单次 run 依次经过 brief、plan、gather、crosscheck、synthesize 五个阶段
深度分档	depth 支持 light / standard / deep，默认 standard
信源控制	domain_whitelist / domain_blacklist 限定或排除域名
读者定向	target_audience 指定目标读者，影响成稿口径
结构化产物	返回 final_md 报告与 artifact，附引用数与置信度摘要
过程可观察	SSE 事件流跟踪各阶段进度，支持取消
追问与反馈	REST 提供追问与反馈端点（当前 SDK 未暴露对应方法）

典型场景

• 行业与技术趋势报告：给出主题，产出带引用的多信源综述。
• 竞品与市场调研初稿：先用 DeepResearch 汇总公开信息，再由人工核对补充。
• 面向特定读者的选题成稿：用 target_audience 控制报告的深度和口径。

什么时候用

• 需要的产物是一份成稿报告，而不是一批搜索命中或页面操作结果。
• 结论需要引用支撑，读者要能追溯每个论断的来源。
• 接受分钟级到小时级的异步执行时间。

只需要结构化搜索结果用 WebSearch；需要在具体网站里执行操作用 DoAnything；需要长期跟踪一组页面的变化用 Track。

请求字段

POST /api/v1/projects/{pid}/deep_research/runs
Authorization: Bearer wa_...
Content-Type: application/json

字段	类型	必填	说明
topic	string	是	研究主题
depth	light / standard / deep	否	默认 standard
output_format	report	否	当前只支持 report
target_audience	string	否	目标读者
domain_whitelist / domain_blacklist	string[]	否	限定或排除域名
max_duration_minutes	int	否	默认 600，最大 10000
session_id	string	否	复用已有 DeepResearch session 做 follow-up

Node SDK

const research = await qoni.deepResearch.run({
  token,
  prompt: "研究 2026 年浏览器自动化的主要趋势。",
  depth: "standard",
  limits: { maxDurationMinutes: 120 },
});

const result = await research.wait();
console.log(result.status, result.output);

for (const artifact of result.artifacts) {
  const bytes = await artifact.content();
  console.log(artifact.id, bytes.length);
}

创建调用返回 RunHandle，不是结果字典；用 research.id 而不是 research["run_id"]。服务端创建接口返回 202，wait() 只是等待 run 进入终态。

阶段与结果

当前 phase 值是 brief、plan、gather、crosscheck、synthesize。终态结果的核心字段是 final_md、final_artifact_id、citations_count、confidence_summary 和可能存在的 partial_sections。

事件、取消与 follow-up

GET  /api/v1/projects/{pid}/deep_research/runs/{run_id}/events
POST /api/v1/projects/{pid}/deep_research/runs/{run_id}/cancel
GET  /api/v1/projects/{pid}/deep_research/runs/{run_id}/artifacts

Node SDK 的事件使用 research.events()；取消使用 research.cancel()。

追问和反馈目前只有 REST 端点，当前 SDK（@qoniai/qoni 0.4.1）未暴露对应方法：

POST /api/v1/projects/{pid}/deep_research/runs/{run_id}/messages
Content-Type: application/json

{ "text": "补充比较 2025 年的数据。" }

POST /api/v1/projects/{pid}/deep_research/runs/{run_id}/feedback
Content-Type: application/json

{ "thumbs": "up" }

feedback 还接受 rating 和 feedback_text。需要另起一轮研究并复用已有上下文时，在创建请求里传 session_id，而不是对终态 run 追加消息。

当前后端没有 DeepResearch 的 /intervene 端点；不要写 client.deep_research.intervene()。