@sensedealai/cuecue 1.0.5

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,35 @@
+# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
+# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
+
+name: Node.js Package
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm test
+
+  publish-npm:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org/
+      - run: npm ci
+      - name: Update package version
+        run: npm version ${{ github.event.release.tag_name }} --no-git-tag-version --allow-same-version
+      - run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.npm_token}}

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,220 @@
+# CueCue SDK
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@sensedealai/cuecue">
+    <img src="https://img.shields.io/npm/v/@sensedealai/cuecue.svg" alt="npm version">
+  </a>
+  <a href="https://opensource.org/licenses/Apache-2.0">
+    <img src="https://img.shields.io/badge/License-Apache%202.0-yellow.svg" alt="License: Apache 2.0">
+  </a>
+</p>
+
+> Conduct deep financial research using CueCue's AI-powered multi-agent system
+
+CueCue SDK is a TypeScript library and CLI tool that enables developers and researchers to leverage CueCue's AI-powered multi-agent system for comprehensive financial research and analysis.
+
+## Features
+
+- 🤖 **AI-Powered Research** - Leverage multi-agent AI system for in-depth research
+- 📡 **Real-time Streaming** - SSE-based streaming for live progress updates
+- 📋 **Task Tracking** - Monitor individual research tasks as they complete
+- 📝 **Report Generation** - Automatically generate comprehensive research reports
+- 🔄 **Conversation Continuity** - Continue existing research conversations
+- 📋 **Templates** - Use predefined research frameworks
+- 🎨 **Style Mimicry** - Mimic writing styles from any URL
+
+## Installation
+
+``` bash
+npm install @sensedealai/cuecue
+```
+
+## CLI Usage
+
+### Basic Usage
+
+``` bash
+# Set your API key (recommended)
+export CUECUE_API_KEY=your_api_key
+
+# Run a research query
+cuecue-research "Tesla Q3 2024 revenue analysis"
+```
+
+### Command Options
+
+| Option | Description |
+|--------|-------------|
+| `--api-key KEY` | CueCue API key (defaults to `CUECUE_API_KEY` env var) |
+| `--base-url URL` | CueCue API base URL (defaults to `https://cuecue.cn`) |
+| `--conversation-id ID` | Continue an existing conversation |
+| `--template-id ID` | Use a predefined research framework |
+| `--mimic-url URL` | Mimic writing style from a URL |
+| `--output, -o FILE` | Save report to file (markdown format) |
+| `--verbose, -v` | Enable verbose logging |
+| `--help, -h` | Show help message |
+
+### Examples
+
+``` bash
+# Specify API key directly
+cuecue-research "Tesla Q3 2024 revenue" --api-key YOUR_KEY
+
+# Save report to file
+cuecue-research "BYD financial analysis" --output report.md
+
+# Continue existing conversation
+cuecue-research "Further analysis" --conversation-id CONV_ID
+
+# Use a template
+cuecue-research "Company analysis" --template-id TEMPLATE_ID
+
+# Mimic writing style from a URL
+cuecue-research "Market analysis" --mimic-url https://example.com/article
+
+# Enable verbose logging
+cuecue-research "Analysis topic" --verbose
+```
+
+## Library Usage
+
+### Import and Initialize
+
+``` typescript
+import { CueCueDeepResearch } from '@sensedealai/cuecue';
+
+// Initialize with your API key
+const client = new CueCueDeepResearch('your-api-key');
+```
+
+### Basic Research
+
+``` typescript
+import { CueCueDeepResearch } from '@sensedealai/cuecue';
+
+const client = new CueCueDeepResearch('your-api-key');
+
+const result = await client.research('Tesla Q3 2024 revenue analysis');
+
+console.log(`Conversation ID: ${result.conversationId}`);
+console.log(`Report URL: ${result.reportUrl}`);
+console.log(`Report: ${result.report}`);
+```
+
+### Advanced Options
+
+``` typescript
+const result = await client.research('Company analysis', {
+  // Continue existing conversation
+  conversationId: 'existing-conversation-id',
+  
+  // Use a predefined template
+  templateId: 'template-id',
+  
+  // Mimic writing style from URL
+  mimicUrl: 'https://example.com/article',
+  
+  // Enable verbose logging
+  verbose: true,
+});
+```
+
+### Using Custom Base URL
+
+``` typescript
+const client = new CueCueDeepResearch('your-api-key', 'https://custom-api.example.com');
+```
+
+## API Reference
+
+### `CueCueDeepResearch`
+
+#### Constructor
+
+``` typescript
+constructor(apiKey: string, baseUrl?: string)
+```
+
+- `apiKey` - Your CueCue API key
+- `baseUrl` - Optional custom base URL (defaults to `https://cuecue.cn`)
+
+#### Methods
+
+##### `research(query: string, options?: ResearchOptions): Promise<ResearchResult>`
+
+Execute a deep research query.
+
+- `query` - The research question or topic
+- `options` - Optional research parameters (see `ResearchOptions`)
+- Returns: `Promise<ResearchResult>`
+
+### Type Definitions
+
+#### `ResearchOptions`
+
+``` typescript
+interface ResearchOptions {
+  conversationId?: string;  // Continue existing conversation
+  templateId?: string;      // Template ID for predefined framework
+  mimicUrl?: string;        // URL to mimic writing style
+  verbose?: boolean;       // Enable verbose logging
+}
+```
+
+#### `ResearchResult`
+
+``` typescript
+interface ResearchResult {
+  conversationId: string;  // Unique conversation identifier
+  chatId: string;          // Chat session identifier
+  tasks: string[];         // List of research tasks completed
+  report: string;          // Generated research report
+  reportUrl: string;       // URL to view report online
+}
+```
+
+#### SSE Events
+
+The library also exports types for SSE events:
+
+``` typescript
+import type {
+  SSEEvent,
+  RequestPayload,
+  AgentStartEvent,
+  AgentEndEvent,
+  MessageEvent,
+  FinalSessionStateEvent,
+} from '@sensedealai/cuecue';
+```
+
+## Getting an API Key
+
+1. Log in to CueCue at [https://cuecue.cn](https://cuecue.cn)
+2. Go to Settings → API Keys
+3. Generate a new API key
+
+## Building from Source
+
+``` bash
+# Install dependencies
+npm install
+
+# Build TypeScript
+npm run build
+
+# Run CLI
+npm run cli "your research query"
+```
+
+## License
+
+Apache 2.0 License - see [LICENSE](LICENSE) file for details.
+
+## Keywords
+
+- research
+- financial-analysis
+- ai-agents
+- report-generation
+- data-analysis

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@sensedealai/cuecue",
+  "version": "1.0.5",
+  "description": "TypeScript SDK for CueCue's AI-powered multi-agent research system",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "cuecue-research": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "cli": "node dist/cli.js",
+    "test": "vitest",
+    "lint": "eslint src --ext .ts"
+  },
+  "keywords": [
+    "research",
+    "financial-analysis",
+    "ai-agents",
+    "report-generation",
+    "data-analysis"
+  ],
+  "author": "CueCue Team",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "axios": "^1.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+
+/**
+ * CueCue Deep Research CLI
+ *
+ * Command-line interface for conducting deep research using CueCue's
+ * AI-powered multi-agent system.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { CueCueDeepResearch } from './client.js';
+
+interface CLIArgs {
+  query: string;
+  apiKey?: string;
+  baseUrl: string;
+  conversationId?: string;
+  templateId?: string;
+  mimicUrl?: string;
+  output?: string;
+  verbose: boolean;
+}
+
+function parseArgs(): CLIArgs {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+    printHelp();
+    process.exit(0);
+  }
+
+  const result: CLIArgs = {
+    query: '',
+    baseUrl: process.env.CUECUE_BASE_URL || 'https://cuecue.cn',
+    verbose: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    // Handle --key=value format
+    if (arg.includes('=')) {
+      const [key, value] = arg.split('=');
+      if (key === '--api-key') {
+        result.apiKey = value;
+      } else if (key === '--base-url') {
+        result.baseUrl = value;
+      } else if (key === '--conversation-id') {
+        result.conversationId = value;
+      } else if (key === '--template-id') {
+        result.templateId = value;
+      } else if (key === '--mimic-url') {
+        result.mimicUrl = value;
+      } else if (key === '--output' || key === '-o') {
+        result.output = value;
+      }
+      continue;
+    }
+
+    // Handle --key value format
+    if (arg === '--api-key') {
+      result.apiKey = args[++i];
+    } else if (arg === '--base-url') {
+      result.baseUrl = args[++i];
+    } else if (arg === '--conversation-id') {
+      result.conversationId = args[++i];
+    } else if (arg === '--template-id') {
+      result.templateId = args[++i];
+    } else if (arg === '--mimic-url') {
+      result.mimicUrl = args[++i];
+    } else if (arg === '--output' || arg === '-o') {
+      result.output = args[++i];
+    } else if (arg === '--verbose' || arg === '-v') {
+      result.verbose = true;
+    } else if (!arg.startsWith('--') && !arg.startsWith('-')) {
+      result.query = arg;
+    }
+  }
+
+  return result;
+}
+
+function printHelp(): void {
+  console.log(`
+CueCue Deep Research - AI-powered research assistant
+
+Usage:
+  cuecue-research <query> [options]
+
+Arguments:
+  query                    Research question or topic
+
+Options:
+  --api-key KEY           CueCue API key (defaults to CUECUE_API_KEY env var)
+  --base-url URL          CueCue API base URL (defaults to CUECUE_BASE_URL or https://cuecue.cn)
+  --conversation-id ID    Conversation ID to continue an existing conversation
+  --template-id ID        Template ID to use a predefined research framework
+  --mimic-url URL         URL to mimic the writing style from
+  --output, -o FILE       Output file path to save the report (markdown format)
+  --verbose, -v           Enable verbose logging
+  --help, -h              Show this help message
+
+Examples:
+  # Basic research (using environment variable)
+  export CUECUE_API_KEY=your_key
+  cuecue-research "Tesla Q3 2024 revenue"
+
+  # Or specify API key directly
+  cuecue-research "Tesla Q3 2024 revenue" --api-key YOUR_KEY
+
+  # Save report to file
+  cuecue-research "BYD financial analysis" --output report.md
+
+  # Continue existing conversation
+  cuecue-research "Further analysis" --conversation-id CONV_ID
+
+  # Use a template
+  cuecue-research "Company analysis" --template-id TEMPLATE_ID
+
+  # Mimic writing style from a URL
+  cuecue-research "Market analysis" --mimic-url https://example.com/article
+
+For more information, visit: https://cuecue.cn
+  `);
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs();
+
+  // Validate API key
+  const apiKey = args.apiKey || process.env.CUECUE_API_KEY;
+  if (!apiKey) {
+    console.error('❌ Error: API key is required');
+    console.error('\nPlease provide an API key using one of these methods:');
+    console.error('  1. Set environment variable: export CUECUE_API_KEY="your_key"');
+    console.error('  2. Use command-line argument: --api-key YOUR_KEY');
+    console.error('\nTo obtain an API key:');
+    console.error('  1. Log in to CueCue at https://cuecue.cn');
+    console.error('  2. Go to Settings → API Keys');
+    console.error('  3. Generate a new key');
+    process.exit(1);
+  }
+
+  // Validate query
+  if (!args.query) {
+    console.error('❌ Error: Research query is required');
+    console.error('Usage: cuecue-research <query> [options]');
+    console.error('Use --help for more information');
+    process.exit(1);
+  }
+
+  try {
+    const client = new CueCueDeepResearch(apiKey, args.baseUrl);
+
+    const result = await client.research(args.query, {
+      conversationId: args.conversationId,
+      templateId: args.templateId,
+      mimicUrl: args.mimicUrl,
+      verbose: args.verbose,
+    });
+
+    // Print summary
+    console.log('\n' + '='.repeat(60));
+    console.log('📊 Research Summary');
+    console.log('='.repeat(60));
+    console.log(`Conversation ID: ${result.conversationId}`);
+    console.log(`Tasks completed: ${result.tasks.length}`);
+    console.log(`Report URL: ${result.reportUrl}`);
+    console.log(`Report length: ${result.report.length} characters`);
+
+    // Save report to file
+    if (args.output) {
+      try {
+        // Expand ~ to home directory
+        let outputPath = args.output;
+        if (outputPath.startsWith('~/')) {
+          const homeDir = process.env.HOME || process.env.USERPROFILE || '';
+          outputPath = path.join(homeDir, outputPath.slice(2));
+        }
+
+        const outputDir = path.dirname(outputPath);
+        if (outputDir !== '.' && !fs.existsSync(outputDir)) {
+          fs.mkdirSync(outputDir, { recursive: true });
+        }
+
+        if (args.verbose) {
+          console.log(`\n[DEBUG] Writing to: ${outputPath}`);
+          console.log(`[DEBUG] Content length: ${result.report.length}`);
+        }
+
+        // Append report URL to the end of the report
+        const reportWithUrl = result.report + `\n\n---\n\n**Report URL:** ${result.reportUrl}\n`;
+
+        fs.writeFileSync(outputPath, reportWithUrl, 'utf-8');
+        console.log(`✅ Report saved to: ${outputPath}`);
+      } catch (fileError) {
+        console.error(`❌ Failed to save report: ${fileError}`);
+        if (args.verbose) {
+          console.error(fileError);
+        }
+      }
+    }
+  } catch (error) {
+    console.error(`❌ Execution failed: ${error}`);
+    process.exit(1);
+  }
+}
+
+main();

package/src/client.ts

@@ -0,0 +1,242 @@
+/**
+ * CueCue Deep Research Client
+ *
+ * A client for interacting with CueCue's deep research API. This client
+ * handles authentication, request formatting, and streaming response parsing.
+ */
+
+import axios, { AxiosInstance } from 'axios';
+import { randomUUID } from 'crypto';
+import { ResearchOptions, ResearchResult, RequestPayload, SSEEvent } from './types.js';
+
+export class CueCueDeepResearch {
+  private apiKey: string;
+  private baseUrl: string;
+  private client: AxiosInstance;
+
+  constructor(apiKey: string, baseUrl: string = 'https://cuecue.cn') {
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl.replace(/\/$/, '');
+    this.client = axios.create({
+      baseURL: this.baseUrl,
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      timeout: 3600000, // 1 hour
+    });
+  }
+
+  /**
+   * Execute a deep research query
+   *
+   * @param query - The research question or topic
+   * @param options - Optional research parameters
+   * @returns Research result containing tasks, report, and URL
+   */
+  async research(query: string, options: ResearchOptions = {}): Promise<ResearchResult> {
+    const conversationId = options.conversationId || randomUUID();
+    const chatId = randomUUID();
+    const messageId = `msg_${randomUUID()}`;
+
+    const reportUrl = `${this.baseUrl}/c/${conversationId}`;
+    console.log(`\nStarting Deep Research: ${query}\n`);
+
+    // Build request payload
+    const requestData: RequestPayload = {
+      messages: [
+        {
+          role: 'user',
+          content: query,
+          id: messageId,
+          type: 'text',
+        },
+      ],
+      chat_id: chatId,
+      conversation_id: conversationId,
+      need_confirm: false,
+      need_analysis: false,
+      need_underlying: false,
+      need_recommend: false,
+    };
+
+    if (options.templateId) {
+      requestData.template_id = options.templateId;
+    }
+
+    if (options.mimicUrl) {
+      requestData.mimic = { url: options.mimicUrl };
+    }
+
+    // Initialize result container
+    const result: ResearchResult = {
+      conversationId,
+      chatId,
+      tasks: [],
+      report: '',
+      reportUrl,
+    };
+
+    // State tracking
+    const state = {
+      isReporter: false,
+    };
+    const reportContent: string[] = [];
+
+    try {
+      const response = await this.client.post('/api/chat/stream', requestData, {
+        responseType: 'stream',
+      });
+
+      await this.parseStream(response.data, result, reportContent, state);
+
+      // Ensure report is set even if end_of_agent wasn't received
+      if (!result.report && reportContent.length > 0) {
+        result.report = reportContent.join('');
+      }
+
+      if (options.verbose) {
+        console.log(`\n[DEBUG] Collected ${reportContent.length} content chunks`);
+        console.log(`[DEBUG] Total report length: ${result.report.length} characters`);
+      }
+    } catch (error) {
+      if (axios.isAxiosError(error)) {
+        console.error(`HTTP error: ${error.response?.status} - ${error.response?.data}`);
+      } else {
+        console.error(`Request failed: ${error}`);
+      }
+      throw error;
+    }
+
+    return result;
+  }
+
+  /**
+   * Parse SSE stream from the API response
+   */
+  private async parseStream(
+    stream: NodeJS.ReadableStream,
+    result: ResearchResult,
+    reportContent: string[],
+    state: { isReporter: boolean },
+  ): Promise<void> {
+    return new Promise((resolve, reject) => {
+      let buffer = '';
+      let currentEvent: SSEEvent = {
+        type: 'message',
+        data: null,
+        id: null,
+      };
+
+      stream.on('data', (chunk: Buffer) => {
+        buffer += chunk.toString('utf-8');
+        const lines = buffer.split('\n');
+
+        // Keep the last incomplete line in the buffer
+        buffer = lines.pop() || '';
+
+        for (const line of lines) {
+          this.processSSELine(line, currentEvent, result, reportContent, state);
+
+          // Empty line marks end of event
+          if (line === '') {
+            currentEvent = {
+              type: 'message',
+              data: null,
+              id: null,
+            };
+          }
+        }
+      });
+
+      stream.on('end', () => {
+        // Process any remaining data
+        if (buffer) {
+          const lines = buffer.split('\n');
+          for (const line of lines) {
+            this.processSSELine(line, currentEvent, result, reportContent, state);
+          }
+        }
+        resolve();
+      });
+
+      stream.on('error', reject);
+    });
+  }
+
+  /**
+   * Process a single SSE line
+   */
+  private processSSELine(
+    line: string,
+    currentEvent: SSEEvent,
+    result: ResearchResult,
+    reportContent: string[],
+    state: { isReporter: boolean },
+  ): void {
+    if (line.startsWith('id: ')) {
+      currentEvent.id = line.slice(4);
+    } else if (line.startsWith('event: ')) {
+      currentEvent.type = line.slice(7);
+    } else if (line.startsWith('data: ')) {
+      try {
+        currentEvent.data = JSON.parse(line.slice(6));
+      } catch (e) {
+        console.warn(`Failed to parse SSE data: ${e}`);
+      }
+    } else if (line === '' && currentEvent.data !== null) {
+      this.handleSSEEvent(currentEvent, result, reportContent, state);
+    }
+  }
+
+  /**
+   * Handle a complete SSE event
+   */
+  private handleSSEEvent(
+    event: SSEEvent,
+    result: ResearchResult,
+    reportContent: string[],
+    state: { isReporter: boolean },
+  ): void {
+    const eventType = event.type;
+    const eventData = event.data as Record<string, unknown>;
+
+    if (!eventData) {
+      return;
+    }
+
+    const agentName = eventData.agent_name as string;
+
+    if (eventType === 'start_of_agent') {
+      if (agentName === 'coordinator') {
+        console.log(`\nResearch begin. You can view progress at: ${result.reportUrl}\n`);
+      } else if (agentName === 'supervisor') {
+        const taskRequirement = eventData.task_requirement as string;
+        if (taskRequirement) {
+          result.tasks.push(taskRequirement);
+          console.log(`\n📋 Task: ${taskRequirement}`);
+        }
+      } else if (agentName === 'reporter') {
+        state.isReporter = true;
+        console.log('\n📝 Generating Report...\n');
+      }
+    } else if (eventType === 'end_of_agent') {
+      if (agentName === 'reporter') {
+        state.isReporter = false;
+        result.report = reportContent.join('');
+      }
+    } else if (eventType === 'message' && state.isReporter) {
+      // Use state variable instead of checking agent_name in message event
+      const delta = eventData.delta as Record<string, unknown>;
+      if (delta && delta.content) {
+        const content = delta.content as string;
+        // Remove citation markers like 【4-4】
+        const cleanedContent = content.replace(/【\d+-\d+】/g, '');
+        reportContent.push(cleanedContent);
+        process.stdout.write(cleanedContent);
+      }
+    } else if (eventType === 'final_session_state') {
+      console.log('\n\n✅ Research complete');
+    }
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect } from 'vitest';
+import {
+  CueCueDeepResearch,
+  type ResearchOptions,
+  type ResearchResult,
+} from './index.js';
+
+describe('CueCueDeepResearch', () => {
+  describe('constructor', () => {
+    it('should create a client with default base URL', () => {
+      const client = new CueCueDeepResearch('test-api-key');
+      expect(client).toBeDefined();
+    });
+
+    it('should create a client with custom base URL', () => {
+      const client = new CueCueDeepResearch('test-api-key', 'https://custom.example.com');
+      expect(client).toBeDefined();
+    });
+
+    it('should handle base URL with trailing slash', () => {
+      const client = new CueCueDeepResearch('test-api-key', 'https://cuecue.cn/');
+      expect(client).toBeDefined();
+    });
+  });
+});
+
+describe('ResearchOptions', () => {
+  it('should allow optional conversationId', () => {
+    const options: ResearchOptions = {};
+    expect(options.conversationId).toBeUndefined();
+  });
+
+  it('should allow optional templateId', () => {
+    const options: ResearchOptions = {
+      templateId: 'template-123',
+    };
+    expect(options.templateId).toBe('template-123');
+  });
+
+  it('should allow optional mimicUrl', () => {
+    const options: ResearchOptions = {
+      mimicUrl: 'https://example.com/article',
+    };
+    expect(options.mimicUrl).toBe('https://example.com/article');
+  });
+
+  it('should allow optional verbose', () => {
+    const options: ResearchOptions = {
+      verbose: true,
+    };
+    expect(options.verbose).toBe(true);
+  });
+
+  it('should allow all options together', () => {
+    const options: ResearchOptions = {
+      conversationId: 'conv-123',
+      templateId: 'template-456',
+      mimicUrl: 'https://example.com/article',
+      verbose: true,
+    };
+    expect(options.conversationId).toBe('conv-123');
+    expect(options.templateId).toBe('template-456');
+    expect(options.mimicUrl).toBe('https://example.com/article');
+    expect(options.verbose).toBe(true);
+  });
+});
+
+describe('ResearchResult', () => {
+  it('should have required properties', () => {
+    const result: ResearchResult = {
+      conversationId: 'conv-123',
+      chatId: 'chat-456',
+      tasks: ['task1', 'task2'],
+      report: 'Test report content',
+      reportUrl: 'https://cuecue.cn/c/conv-123',
+    };
+    expect(result.conversationId).toBe('conv-123');
+    expect(result.chatId).toBe('chat-456');
+    expect(result.tasks).toHaveLength(2);
+    expect(result.report).toBe('Test report content');
+    expect(result.reportUrl).toBe('https://cuecue.cn/c/conv-123');
+  });
+
+  it('should allow empty tasks array', () => {
+    const result: ResearchResult = {
+      conversationId: 'conv-123',
+      chatId: 'chat-456',
+      tasks: [],
+      report: '',
+      reportUrl: 'https://cuecue.cn/c/conv-123',
+    };
+    expect(result.tasks).toHaveLength(0);
+    expect(result.report).toBe('');
+  });
+});
+

package/src/index.ts

@@ -0,0 +1,17 @@
+/**
+ * CueCue Deep Research TypeScript Library
+ *
+ * Main export for the CueCue Deep Research skill.
+ */
+
+export { CueCueDeepResearch } from './client.js';
+export type {
+  ResearchOptions,
+  ResearchResult,
+  SSEEvent,
+  RequestPayload,
+  AgentStartEvent,
+  AgentEndEvent,
+  MessageEvent,
+  FinalSessionStateEvent,
+} from './types.js';

package/src/types.ts

@@ -0,0 +1,62 @@
+/**
+ * Type definitions for CueCue Deep Research
+ */
+
+export interface ResearchOptions {
+  conversationId?: string;
+  templateId?: string;
+  mimicUrl?: string;
+  verbose?: boolean;
+}
+
+export interface ResearchResult {
+  conversationId: string;
+  chatId: string;
+  tasks: string[];
+  report: string;
+  reportUrl: string;
+}
+
+export interface SSEEvent {
+  type: string;
+  data: Record<string, unknown> | null;
+  id: string | null;
+}
+
+export interface RequestPayload {
+  messages: Array<{
+    role: string;
+    content: string;
+    id: string;
+    type: string;
+  }>;
+  chat_id: string;
+  conversation_id: string;
+  need_confirm: boolean;
+  need_analysis: boolean;
+  need_underlying: boolean;
+  need_recommend: boolean;
+  template_id?: string;
+  mimic?: {
+    url: string;
+  };
+}
+
+export interface AgentStartEvent {
+  agent_name: string;
+  task_requirement?: string;
+}
+
+export interface AgentEndEvent {
+  agent_name: string;
+}
+
+export interface MessageEvent {
+  delta: {
+    content: string;
+  };
+}
+
+export interface FinalSessionStateEvent {
+  [key: string]: unknown;
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ES2020",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "moduleResolution": "node"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}