CueCue Deep Research

# CueCue Deep Research TypeScript Skill

使用 CueCue 的多智能体 AI 系统执行全面的金融研究查询。该 TypeScript 实现提供了与 Python 版本相同的功能，并采用了现代的 async/await 模式和完整的类型安全。

## 此技能的作用

CueCue Deep Research 编排多个 AI 智能体来：

1. **分析** 您的研究问题并将其分解为可执行的任务 2. **研究** 使用网络爬虫、金融数据库和知识检索 3. **综合** 发现生成全面的 markdown 报告 4. **生成** 可共享的报告 URL

该技能过滤了冗长的智能体工作流，仅显示： - 📋 任务标题（来自主管智能体） - 📝 最终研究报告（来自报告员智能体） - 🔗 用于网页查看的报告 URL

⏱️ **执行时间**：根据您研究问题的复杂性，该过程可能需要 **5-30 分钟**。系统执行全面的研究，包括网络爬虫、数据分析和报告生成。请耐心等待完整的结果。

## 给 AI 助手的说明

**重要**：使用此技能时，您必须通过检查命令输出来监控研究进度：

1. **进度监控**：研究过程实时输出进度信息。您应该**每 5 分钟**检查一次输出以： - 验证研究仍在运行 - 向用户报告任务进度（📋 任务更新） - 检测任何错误或问题 - 在报告生成开始时通知用户（📝 正在生成报告...）

2. **进度 URL**：命令将输出类似“Research begin. You can view progress at: https://cuecue.cn/c/...”的 URL - 此 URL 供**人类用户**查看网页界面，而不是供您获取。您应该通过命令的 stdout 输出来监控进度。

3. **用户沟通**：让用户了解以下情况： - 研究何时开始 - 每个启动的主要任务 - 报告生成何时开始 - 研究何时完成 - 任何错误或超时

4. **超时处理**：如果命令似乎挂起或超时，请告知用户研究可能仍在服务器上处理，他们可以检查网页界面 URL。

5. **面向用户的沟通风格**：在通知用户有关进度监控时： - ✅ **应说**：“我会每 5 分钟自动检查进度并汇报” - ✅ **应说**：“研究完成后我会总结关键发现” - ❌ **不应说**：“我创建了一个 cron 任务” - ❌ **不应说**：“完成后会删除 cron” - ❌ **不应说**：技术实现细节（会话 ID、作业 ID、内部机制） **原因**：用户关心您*做*什么，而不是*怎么*做。保持沟通专注于结果和用户价值，而不是内部机制。

### 使用 Cron 进行自动进度监控

由于 AI 助手无法主动自主地“循环并检查”，请使用 OpenClaw 的 cron 系统自动化进度监控。

**推荐方法：使用隔离会话**

将 `sessionTarget: "isolated"` 与 `payload.kind: "agentTurn"` 结合使用是将进度更新直接发送到聊天通道的最可靠方法。

**步骤 1：在后台启动研究**

```javascript // Start the research task exec({ command: "cuecue-research 'Your research query' --output ~/clawd/cuecue-reports/2026-02-01-10-00-research.md", background: true }) // Returns: { sessionId: "wild-river", pid: 12345 } ```

**步骤 2：创建一个 cron 任务来监控进度**

```javascript cron.add({ name: "Monitor CueCue Research: wild-river", schedule: { kind: "every", everyMs: 300000 // 5 minutes }, sessionTarget: "isolated", wakeMode: "now", // IMPORTANT: Use "now" to trigger immediately payload: { kind: "agentTurn", message: "检查 CueCue 研究进度 (session: wild-river)。使用 process log wild-river 检查输出。如果看到 '✅ Research complete'，则：1) 读取报告文件并总结关键发现；2) 使用 cron.remove 删除此监控任务。如果仍在运行，汇报最新的 📋 Task 进度。", deliver: true, channel: "feishu", // or "telegram", "discord", etc. to: "GROUP_ID_OR_CHAT_ID" // The channel where the research was requested } }) // Returns: { id: "abc-123-def", ... } ```

**重要配置：** - **`sessionTarget: "isolated"`** - 创建一个隔离的子智能体会话 - **`payload.kind: "agentTurn"`** - 运行智能体并传递响应 - **`deliver: true`** - 确保响应发送到聊天 - **`channel`** - 指定消息平台（feishu、telegram、discord 等） - **`to`** - 应发送更新的目标聊天/群组 ID - **`wakeMode: "now"`** - 立即触发，无需等待心跳

**步骤 3：Cron 将每 5 分钟自动检查**

Cron 任务将： - 每 5 分钟在隔离会话中运行一次 - 检查 `process log wild-river` 的新输出 - 直接将进度更新发送到指定的聊天通道 - 完成后，读取报告，总结发现，并删除自己

**步骤 4：手动清理（如果需要）**

如果研究失败或您需要停止监控：

```javascript // List all cron jobs cron.list()

// Remove the monitoring job cron.remove({ jobId: "abc-123-def" }) ```

**完整示例工作流：**

```javascript // 1. Start research const result = exec({ command: "cuecue-research '2026年金银价格分析' --output ~/clawd/cuecue-reports/2026-02-01-gold-analysis.md", background: true }) const sessionId = result.sessionId // e.g., "wild-river"

// 2. Get current channel info (from runtime context) const channel = "feishu" // Current channel const chatId = "oc_abac3e3037a0726ef4b4aa330d5ed590" // Current group/chat ID

// 3. Create monitoring cron const cronJob = cron.add({ name: `Monitor CueCue: ${sessionId}`, schedule: { kind: "every", everyMs: 300000 }, sessionTarget: "isolated", wakeMode: "now", payload: { kind: "agentTurn", message: `检查研究进度 (session: ${sessionId})。完成后读取报告并总结，然后删除此 cron。`, deliver: true, channel: channel, to: chatId } })

// 4. Inform user (user-friendly, no technical details) reply(`🔭 研究已启动！ 📊 进度追踪: https://cuecue.cn/c/... ⏰ 我会每 5 分钟自动检查进度并汇报 `)

// 5. Cron handles the rest automatically // The isolated session will: // - Check progress every 5 minutes // - Send updates directly to the chat // - Summarize the report when complete // - Delete itself ```

**故障排除：**

如果您没有收到进度更新： 1. 检查 `cron.list()` 以验证任务是否正在运行（`lastStatus: "ok"`） 2. 确保设置了 `wakeMode: "now"`（而不是 `"next-heartbeat"`） 3. 验证 `deliver: true` 以及正确的 `channel` + `to` 值 4. 检查 `cron.runs({ jobId })` 以获取执行历史和错误

**替代方案：主会话（不推荐）**

如果您更喜欢将 `sessionTarget: "main"` 与 `payload.kind: "systemEvent"` 一起使用，请注意： - 响应不会自动发送到聊天 - 您必须确保 `HEARTBEAT.md` 包含非注释内容，以避免 `empty-heartbeat-file` 错误 - 隔离会话方法对于自动通知更可靠

**注意**：Cron 负载应包含删除自身的逻辑。当研究完成时，使用 `cron.remove({ jobId: "<job-id>" })`。

## 先决条件

- Node.js 18+ 或 Deno - CueCue API 密钥（从您的 CueCue 账户设置获取，网址：https://cuecue.cn） - npm 或 yarn 包管理器

## 配置

### 设置 CUECUE_API_KEY

该技能需要 CueCue API 密钥才能运行。您可以通过两种方式配置它：

#### 选项 1：OpenClaw 配置（推荐）

使用 CLI 在您的 OpenClaw 配置中设置 API 密钥：

```bash # One-line command to set the API key(openclaw command may be clawdbot or moltbot) openclaw config set skills.entries.cuecue-deep-research.env.CUECUE_API_KEY "your-api-key-here" ```

这将： - 将密钥添加到 `~/.openclaw/openclaw.json` 中的 `skills.entries.cuecue-deep-research.env` 下 - 使其自动可供技能使用 - 重启网关以应用更改

要验证配置： ```bash openclaw config get skills.entries.cuecue-deep-research.env.CUECUE_API_KEY ```

然后重启网关 ``` openclaw gateway restart ```

#### 选项 2：命令行参数

您也可以在运行命令时直接传递 API 密钥： ```bash cuecue-research "Your query" --api-key YOUR_API_KEY ```

**注意**：推荐使用 OpenClaw 配置方法，因为： - 您不需要每次都指定密钥 - 密钥安全地存储在 OpenClaw 配置中 - 所有 AI 助手都可以使用该技能，而无需在提示词中包含密钥 - 一个命令即可完成设置

### 获取您的 API 密钥

1. 访问 https://cuecue.cn 2. 登录您的账户 3. 转到账户设置 4. 找到 API 密钥部分 5. 复制您的 API 密钥

## 安装

### 作为 CLI 工具

```bash # Install globally npm install -g [email protected]

# Or install locally in your project npm install [email protected] ```

## 用法

### 命令行界面

#### 基本研究

```bash # Using environment variable (recommended) cuecue-research "Tesla Q3 2024 revenue analysis"

# Or specify API key directly cuecue-research "Tesla Q3 2024 revenue analysis" --api-key YOUR_API_KEY ```

#### 将报告保存到文件

```bash cuecue-research "BYD vs Tesla market comparison" --output ~/clawd/cuecue-reports/2026-01-30-14-30-byd-tesla-comparison.md ```

**注意**：输出路径应使用格式 `~/clawd/cuecue-reports/YYYY-MM-DD-HH-MM-descriptive-name.md`，其中时间戳代表研究启动的时间。`~` 将扩展为您的主目录。

#### 使用研究模板

```bash cuecue-research "Analyze CATL competitive advantages" \ --output ~/clawd/cuecue-reports/2026-01-30-11-20-catl-analysis.md \ --template-id TEMPLATE_ID ```

#### 继续现有对话

```bash cuecue-research "Further analyze supply chain risks" \ --output ~/clawd/cuecue-reports/2026-01-30-15-45-supply-chain-risks.md \ --conversation-id EXISTING_CONV_ID ```

#### 模仿写作风格

```bash cuecue-research "Electric vehicle market analysis" \ --output ~/clawd/cuecue-reports/2026-01-30-16-00-ev-market-analysis.md \ --mimic-url https://example.com/sample-article ```

模仿功能分析所提供 URL 的写作风格、语调和结构，并将其应用于生成的研究报告。这适用于： - 匹配您组织的报告风格 - 适应特定受众的偏好 - 在报告之间保持一致性

⚠️ **注意**：`--mimic-url` 和 `--template-id` 选项不能一起使用。选择一种方法： - 使用 `--template-id` 进行预定义的研究框架（目标、搜索计划、报告格式） - 使用 `--mimic-url` 在没有模板的情况下进行风格模仿

## 命令行选项

| 选项 | 必需 | 描述 | |--------|----------|-------------| | `query` | ✅ | 研究问题或主题 | | `--api-key` | ❌ | 您的 CueCue API 密钥（默认为 `CUECUE_API_KEY` 环境变量） | | `--base-url` | ❌ | CueCue API 基础 URL（默认为 `CUECUE_BASE_URL` 环境变量或 https://cuecue.cn） | | `--conversation-id` | ❌ | 继续现有对话 | | `--template-id` | ❌ | 使用预定义的研究模板（不能与 `--mimic-url` 一起使用） | | `--mimic-url` | ❌ | 用于模仿写作风格的 URL（不能与 `--template-id` 一起使用） | | `--output`, `-o` | ❌ | 将报告保存到文件（markdown 格式）。推荐格式：`~/clawd/cuecue-reports/clawd/cuecue-reports/YYYY-MM-DD-HH-MM-descriptive-name.md`（例如 `~/clawd/2026-01-30-12-41-tesla-analysis.md`）。`~` 将扩展为您的主目录。 | | `--verbose`, `-v` | ❌ | 启用详细日志记录 | | `--help`, `-h` | ❌ | 显示帮助信息 |

## 输出格式

该技能提供实时流式输出：

``` Starting Deep Research: Tesla Q3 2024 Financial Analysis

Check Progress: https://cuecue.cn/c/12345678-1234-1234-1234-123456789abc

📋 Task: Search for Tesla Q3 2024 financial data

📋 Task: Analyze revenue and profit trends

📝 Generating Report...

# Tesla Q3 2024 Financial Analysis

## Executive Summary [Report content streams here in real-time...]

✅ Research complete

============================================================ 📊 Research Summary ============================================================ Conversation ID: 12345678-1234-1234-1234-123456789abc Tasks completed: 2 Report URL: https://cuecue.cn/c/12345678-1234-1234-1234-123456789abc ✅ Report saved to: ~/clawd/cuecue-reports/2026-01-30-10-15-tesla-q3-analysis.md ```

## 故障排除

### 401 Unauthorized - 验证您的 API 密钥是否正确 - 检查 API 密钥是否已过期 - 确保您拥有必要的权限

### 连接超时 - 验证基础 URL 是否正确 - 检查网络连接 - 研究查询通常需要 5-30 分钟，具体取决于复杂性 - 这是正常的 - 如果您看到超时，研究可能仍在服务器上处理 - 请检查网页界面

### 空报告 - 确保您的研究问题清晰具体 - 检查服务器日志中的错误 - 尝试不同的查询以测试连接性

## 支持

如有问题或疑问： - [CueCue 网站](https://cuecue.cn) - 电子邮件：[email protected]