deepresearch conversation

# Deep Research Conversation

此技能允许 OpenClaw 代理针对给定主题与用户进行深入的研究讨论。API 密钥会从 OpenClaw 配置中自动加载 — 无需手动设置。

## API 表 | name | path | description | |------------|---------------------------------|---------------------------------------| |DeepresearchConversation|/v2/agent/deepresearch/run|多轮流式深度研究对话（通过 Python 脚本）| |ConversationCreate|/v2/agent/deepresearch/create|创建新的对话会话，返回 conversation_id| |FileUpload|/v2/agent/file/upload|上传对话文件| |FileParseSubmit|/v2/agent/file/parse/submit|提交上传的文件进行解析| |FileParseQuery|/v2/agent/file/parse/query|查询文件解析任务的状态|

## 工作流

### 路径 A：无文件的主题讨论 1. 直接使用用户的查询调用 **DeepresearchConversation**。系统会自动创建一个新的对话。

### 路径 B：带文件的主题讨论 1. 调用 **ConversationCreate** 获取 `conversation_id`。 2. 使用 `conversation_id` 调用 **FileUpload** 上传文件。 3. 使用返回的 `file_id` 调用 **FileParseSubmit**。 4. 每隔几秒轮询 **FileParseQuery**，直到解析成功。 5. 使用 `query`、`conversation_id` 和 `file_ids` 调用 **DeepresearchConversation**。

### 多轮对话规则 - DeepresearchConversation API 是一个 **SSE 流式** 接口，会增量返回数据。 - 在首次调用之后，你 **必须** 在所有后续调用中传递 `conversation_id`。 - 如果响应包含 `interrupt_id`（用于“要求澄清”或“大纲确认”），下一次调用 **必须** 包含该 `interrupt_id`。 - 如果响应包含 `structured_outline`，请将其展示给用户以供确认/修改，然后在下一次调用中传递最终的大纲。 - 持续迭代调用 DeepresearchConversation，直到用户对结果满意。

## API

### ConversationCreate API

#### 参数 无参数

#### 执行 Shell ```bash curl -X POST "https://qianfan.baidubce.com/v2/agent/deepresearch/create" \ -H "X-Appbuilder-From: openclaw" \ -H "Authorization: Bearer $BAIDU_API_KEY" \ -H "Content-Type: application/json" \ -d '{}' ```

### FileUpload API

#### 参数 - `agent_code`: 固定值 `"deepresearch"`（必填） - `conversation_id`: 来自 ConversationCreate 的响应（必填） - `file`: 本地文件二进制数据（与 file_url 互斥）。最多 10 个文件。支持的格式： - 文本: .doc, .docx, .txt, .pdf, .ppt, .pptx (txt ≤ 10MB, pdf ≤ 100MB/3000 页, doc/docx ≤ 100MB/2500 页, ppt/pptx ≤ 400 页) - 表格: .xlsx, .xls (≤ 100MB, 仅限单个 Sheet) - 图片: .png, .jpg, .jpeg, .bmp (每个 ≤ 10MB) - 音频: .wav, .pcm (≤ 10MB) - `file_url`: 文件的公开 URL（与 file 互斥）

#### 本地文件上传 ```bash curl -X POST "https://qianfan.baidubce.com/v2/agent/file/upload" \ -H "Authorization: Bearer $BAIDU_API_KEY" \ -H "Content-Type: multipart/form-data" \ -H "X-Appbuilder-From: openclaw" \ -F "agent_code=deepresearch" \ -F "conversation_id=$conversation_id" \ -F "file=@local_file_path" ```

#### 文件 URL 上传 ```bash curl -X POST "https://qianfan.baidubce.com/v2/agent/file/upload" \ -H "Authorization: Bearer $BAIDU_API_KEY" \ -H "Content-Type: multipart/form-data" \ -H "X-Appbuilder-From: openclaw" \ -F "agent_code=deepresearch" \ -F "conversation_id=$conversation_id" \ -F "file_url=$file_url" ```

### FileParseSubmit API

#### 参数 - `file_id`: 来自 FileUpload 的响应（必填）

#### 执行 Shell ```bash curl -X POST "https://qianfan.baidubce.com/v2/agent/file/parse/submit" \ -H "Authorization: Bearer $BAIDU_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Appbuilder-From: openclaw" \ -d '{"file_id": "$file_id"}' ```

### FileParseQuery API

#### 参数 - `task_id`: 来自 FileParseSubmit 的响应（必填）

#### 执行 Shell ```bash curl -X GET "https://qianfan.baidubce.com/v2/agent/file/parse/query?task_id=$task_id" \ -H "Authorization: Bearer $BAIDU_API_KEY" \ -H "X-Appbuilder-From: openclaw" ```

### DeepresearchConversation API

#### 参数 - `query`: 用户的问题或研究主题（必填） - `conversation_id`: 首次调用时可选（自动生成）。后续调用时必填。 - `file_ids`: 已解析文件 ID 列表（可选，仅在讨论文件时使用） - `interrupt_id`: 当响应上一轮的“要求澄清”或“大纲确认”时必填。可在上一次 SSE 响应的 `content.text.data` 中找到。 - `structured_outline`: 研究报告大纲。如果上一轮生成了大纲，则在后续调用中必填。结构： ```json { "title": "string", "locale": "string", "description": "string", "sub_chapters": [ { "title": "string", "locale": "string", "description": "string", "sub_chapters": [] } ] } ``` - `version`: `"Lite"`（更快，10 分钟内）或 `"Standard"`（更深，更慢）。默认：`"Standard"`。

#### 执行 Shell ```bash python3 scripts/deepresearch_conversation.py '{"query": "your question here", "version": "Standard"}' ```

#### 包含所有参数的示例 ```bash python3 scripts/deepresearch_conversation.py '{"query": "the question", "file_ids": ["file_id_1"], "interrupt_id": "interrupt_id", "conversation_id": "conversation_id", "structured_outline": {"title": "Report Title", "locale": "zh", "description": "desc", "sub_chapters": [{"title": "Chapter 1", "locale": "zh", "description": "chapter desc", "sub_chapters": []}]}, "version": "Standard"}' ```