cuecue-deep-research

CueCue Deep Research TypeScript Skill

Execute comprehensive financial research queries using CueCue's multi-agent AI system. This TypeScript implementation provides the same functionality as the Python version with modern async/await patterns and full type safety.

What This Skill Does

CueCue Deep Research orchestrates multiple AI agents to:

1. Analyze your research question and break it down into actionable tasks
2. Research using web crawling, financial databases, and knowledge retrieval
3. Synthesize findings into a comprehensive markdown report
4. Generate a shareable report URL

The skill filters the verbose agent workflow to show only:

• 📋 Task titles (from the supervisor agent)
• 📝 Final research report (from the reporter agent)
• 🔗 Report URL for web viewing

⏱️ Execution Time: Depending on the complexity of your research question, the process may take 5-30 minutes. The system performs comprehensive research including web crawling, data analysis, and report generation. Please be patient and wait for the complete results.

For AI Assistants

Important: When using this skill, you MUST monitor the research progress by checking the command output:

1. Progress Monitoring: The research process outputs progress information in real-time. You should check the output every 5 minutes to:

   • Verify the research is still running
   • Report task progress to the user (📋 Task updates)
   • Detect any errors or issues
   • Inform the user when report generation begins (📝 Generating Report...)

2. Progress URL: The command will output a URL like "Research begin. You can view progress at: https://cuecue.cn/c/..." - this URL is for human users to view the web interface, NOT for you to fetch. You should monitor progress through the command's stdout output.

3. User Communication: Keep the user informed about:

   • When research begins
   • Each major task that starts
   • When report generation begins
   • When research completes
   • Any errors or timeouts

4. Timeout Handling: If the command appears to hang or timeout, inform the user that the research may still be processing on the server, and they can check the web interface URL.

5. User-Facing Communication Style: When informing users about progress monitoring:

   • ✅ DO SAY: "我会每 5 分钟自动检查进度并汇报" / "I'll check progress every 5 minutes and update you"
   • ✅ DO SAY: "研究完成后我会总结关键发现" / "I'll summarize key findings when complete"
   • ❌ DON'T SAY: "我创建了一个 cron 任务" / "I created a cron job"
   • ❌ DON'T SAY: "完成后会删除 cron" / "Will delete the cron when done"
   • ❌ DON'T SAY: Technical implementation details (session IDs, job IDs, internal mechanisms)

   Why: Users care about what you'll do, not how you do it. Keep communication focused on outcomes and user value, not internal plumbing.

Automated Progress Monitoring with Cron

Since AI assistants cannot actively "loop and check" on their own, use OpenClaw's cron system to automate progress monitoring.

Recommended Approach: Use Isolated Session

Using sessionTarget: "isolated" with payload.kind: "agentTurn" is the most reliable way to get progress updates delivered directly to the chat channel.

Step 1: Start research in background

// 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 }

Step 2: Create a cron job to monitor progress

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", ... }

Important Configuration:

• sessionTarget: "isolated" - Creates an isolated sub-agent session
• payload.kind: "agentTurn" - Runs the agent and delivers the response
• deliver: true - Ensures the response is sent to the chat
• channel - Specify the messaging platform (feishu, telegram, discord, etc.)
• to - The target chat/group ID where updates should be sent
• wakeMode: "now" - Triggers immediately without waiting for heartbeat

Step 3: Cron will automatically check every 5 minutes

The cron job will:

• Run in an isolated session every 5 minutes
• Check process log wild-river for new output
• Send progress updates directly to the specified chat channel
• When complete, read the report, summarize findings, and delete itself

Step 4: Manual cleanup (if needed)

If the research fails or you need to stop monitoring:

// List all cron jobs
cron.list()

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

Complete Example Workflow:

// 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

Troubleshooting:

If you don't receive progress updates:

1. Check cron.list() to verify the job is running (lastStatus: "ok")
2. Ensure wakeMode: "now" is set (not "next-heartbeat")
3. Verify deliver: true and correct channel + to values
4. Check cron.runs({ jobId }) for execution history and errors

Alternative: Main Session (Not Recommended)

If you prefer to use sessionTarget: "main" with payload.kind: "systemEvent", note that:

• Responses are NOT automatically sent to the chat
• You must ensure HEARTBEAT.md contains non-comment content to avoid empty-heartbeat-file errors
• The isolated session approach is more reliable for automated notifications

Note: The cron payload should include logic to delete itself. Use cron.remove({ jobId: "<job-id>" }) when the research completes.

Prerequisites

• Node.js 18+ or Deno
• CueCue API key (obtain from your CueCue account settings from https://cuecue.cn)
• npm or yarn package manager

Configuration

Setting up CUECUE_API_KEY

The skill requires a CueCue API key to function. You can configure it in two ways:

Option 1: OpenClaw Config (Recommended)

Set the API key in your OpenClaw configuration using the CLI:

# 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"