coze-coding-dev-sdk 0.2.0

package/README.md

@@ -0,0 +1,881 @@
+# Coze Coding Dev SDK - TypeScript
+
+> 优雅、模块化的多功能 AI SDK，支持图片生成、视频生成、语音合成、语音识别、大语言模型和联网搜索
+
+[![TypeScript](https://img.shields.io/badge/typescript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+[![npm](https://img.shields.io/npm/v/coze-coding-dev-sdk.svg)](https://www.npmjs.com/package/coze-coding-dev-sdk)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](../../LICENSE)
+
+## ✨ 特性
+
+- 🎨 **图片生成** - 基于豆包 SeeDream 模型的高质量图片生成
+- 🎬 **视频生成** - 文本/图片生成视频，支持多种模型和配置
+- 🤖 **大语言模型** - 支持流式对话、思考链、缓存机制
+- 🔍 **联网搜索** - Web 搜索、AI 总结、图片搜索
+- 🎙️ **语音合成 (TTS)** - 多音色、高质量的文本转语音
+- 🎧 **语音识别 (ASR)** - 快速准确的语音转文字
+- 🖥️ **CLI 工具** - 强大的命令行工具，支持所有功能
+- 🏗️ **模块化设计** - 清晰的模块划分，易于扩展
+- 🔒 **类型安全** - 完整的 TypeScript 类型定义
+- 🔄 **自动重试** - 内置重试机制
+- 📊 **Promise/Async** - 现代异步编程支持
+
+## 📦 安装
+
+### 作为 SDK 使用
+
+```bash
+npm install coze-coding-dev-sdk
+# 或
+yarn add coze-coding-dev-sdk
+# 或
+pnpm add coze-coding-dev-sdk
+```
+
+### 作为 CLI 工具使用
+
+```bash
+npm install -g coze-coding-dev-sdk
+```
+
+安装后可以使用 `coze-coding-ai` 命令：
+
+```bash
+coze-coding-ai --version
+coze-coding-ai --help
+```
+
+## 🚀 快速开始
+
+### 环境配置
+
+```bash
+export COZE_WORKLOAD_IDENTITY_API_KEY="your_api_key"
+export COZE_INTEGRATION_BASE_URL="https://api.coze.com"
+export COZE_INTEGRATION_MODEL_BASE_URL="https://model.coze.com"
+```
+
+### 图片生成
+
+```typescript
+import { ImageGenerationClient, Config } from 'coze-coding-dev-sdk';
+
+const config = new Config({
+  apiKey: process.env.COZE_WORKLOAD_IDENTITY_API_KEY,
+  baseUrl: process.env.COZE_INTEGRATION_BASE_URL,
+});
+
+const client = new ImageGenerationClient(config);
+
+const response = await client.generate({
+  prompt: 'A beautiful sunset over mountains',
+  size: '2K',
+});
+
+const helper = client.getResponseHelper(response);
+console.log('Image URLs:', helper.imageUrls);
+```
+
+## 🎯 核心模块
+
+### 1. 图片生成 (Image)
+
+```typescript
+import { ImageGenerationClient } from 'coze-coding-dev-sdk';
+
+const client = new ImageGenerationClient();
+
+const response = await client.generate({
+  prompt: 'A cute cat sitting on a windowsill',
+  size: '4K',
+  watermark: false,
+});
+
+const helper = client.getResponseHelper(response);
+console.log('Success:', helper.success);
+console.log('Image URLs:', helper.imageUrls);
+```
+
+**功能特性：**
+
+- 支持 2K/4K 或自定义尺寸 (WIDTHxHEIGHT)
+- 文生图 (text-to-image)
+- 图生图 (image-to-image)
+- 批量生成
+- 返回 URL 或 Base64 格式
+- 组图生成功能
+- 提示词优化
+
+**参数说明：**
+
+```typescript
+interface ImageGenerationRequest {
+  prompt: string; // 提示词（必需）
+  size?: string; // 尺寸：'2K' | '4K' | 'WIDTHxHEIGHT'
+  watermark?: boolean; // 是否添加水印
+  image?: string | string[]; // 参考图片（单个或多个）
+  responseFormat?: 'url' | 'b64_json'; // 返回格式
+  optimizePromptMode?: string; // 提示词优化模式
+  sequentialImageGeneration?: 'auto' | 'disabled'; // 组图功能
+  sequentialImageGenerationMaxImages?: number; // 最大图片数量 (1-15)
+}
+```
+
+**批量生成：**
+
+```typescript
+const responses = await client.batchGenerate([
+  { prompt: 'A spring cherry blossom', size: '2K' },
+  { prompt: 'A summer beach scene', size: '4K' },
+  { prompt: 'An autumn forest', size: '2K' },
+]);
+
+responses.forEach((response, index) => {
+  const helper = client.getResponseHelper(response);
+  console.log(`Image ${index + 1}:`, helper.imageUrls);
+});
+```
+
+**图生图：**
+
+```typescript
+const response = await client.generate({
+  prompt: 'Transform into watercolor painting style',
+  image: 'https://example.com/reference-image.jpg',
+  size: '4K',
+});
+```
+
+**Base64 响应：**
+
+```typescript
+const response = await client.generate({
+  prompt: 'A professional portrait',
+  size: '2K',
+  responseFormat: 'b64_json',
+});
+
+const helper = client.getResponseHelper(response);
+console.log('Base64 data:', helper.imageB64List);
+```
+
+### 2. 联网搜索 (Search)
+
+```typescript
+import { SearchClient } from 'coze-coding-dev-sdk';
+
+const client = new SearchClient();
+
+const response = await client.webSearch('AI 最新进展', 10);
+
+console.log(`Found ${response.web_items.length} results`);
+response.web_items.forEach(item => {
+  console.log(`${item.title}: ${item.url}`);
+});
+```
+
+**功能特性：**
+
+- Web 搜索
+- Web 搜索 + AI 智能摘要
+- 图片搜索
+- 高级过滤（站点、时间范围、内容要求）
+- 结构化结果返回
+
+**搜索类型：**
+
+```typescript
+const response1 = await client.webSearch('Python 教程', 10);
+
+const response2 = await client.webSearchWithSummary('量子计算原理', 10);
+
+const response3 = await client.imageSearch('可爱的猫咪', 20);
+```
+
+**高级搜索：**
+
+```typescript
+const response = await client.advancedSearch('Python 教程', {
+  searchType: 'web',
+  count: 20,
+  needContent: true,
+  needUrl: true,
+  sites: 'python.org,github.com',
+  blockHosts: 'example.com',
+  timeRange: '1m',
+  needSummary: true,
+});
+
+console.log('Summary:', response.summary);
+response.web_items.forEach(item => {
+  console.log(`${item.title}`);
+  console.log(`  Site: ${item.site_name}`);
+  console.log(`  Authority: ${item.auth_info_level}`);
+});
+```
+
+**自定义搜索请求：**
+
+```typescript
+const response = await client.search({
+  query: '最新科技新闻',
+  search_type: 'web_summary',
+  count: 10,
+  filter: {
+    need_content: true,
+    need_url: true,
+    sites: 'techcrunch.com,wired.com',
+    block_hosts: 'spam.com',
+  },
+  need_summary: true,
+  time_range: '1d',
+});
+```
+
+**搜索结果结构：**
+
+```typescript
+interface SearchResponse {
+  web_items: WebItem[];
+  image_items: ImageItem[];
+  summary?: string;
+}
+
+interface WebItem {
+  id: string;
+  sort_id: number;
+  title: string;
+  site_name?: string;
+  url?: string;
+  snippet: string;
+  summary?: string;
+  content?: string;
+  publish_time?: string;
+  logo_url?: string;
+  rank_score?: number;
+  auth_info_des: string;
+  auth_info_level: number;
+}
+
+interface ImageItem {
+  id: string;
+  sort_id: number;
+  title?: string;
+  site_name?: string;
+  url?: string;
+  publish_time?: string;
+  image: {
+    url: string;
+    width?: number;
+    height?: number;
+    shape: string;
+  };
+}
+```
+
+### 3. 语音功能 (Voice)
+
+#### 语音合成 (TTS)
+
+```typescript
+import { TTSClient } from 'coze-coding-dev-sdk';
+
+const client = new TTSClient();
+
+const response = await client.synthesize({
+  uid: 'user123',
+  text: '你好，欢迎使用 Coze SDK！',
+  speaker: 'zh_female_xiaohe_uranus_bigtts',
+  audioFormat: 'mp3',
+  sampleRate: 24000,
+});
+
+console.log('Audio URI:', response.audioUri);
+console.log('Audio Size:', response.audioSize, 'bytes');
+```
+
+**功能特性：**
+
+- 文本转语音 (TTS)
+- 支持 SSML 格式
+- 30+ 音色选择
+- 可调节语速和音量
+- 多种音频格式（MP3/PCM/OGG）
+- 流式返回
+
+**TTS 参数：**
+
+```typescript
+interface TTSRequest {
+  uid: string; // 用户 ID（必需）
+  text?: string; // 文本内容
+  ssml?: string; // SSML 格式文本
+  speaker?: string; // 音色
+  audioFormat?: 'pcm' | 'mp3' | 'ogg_opus'; // 音频格式
+  sampleRate?: number; // 采样率
+  speechRate?: number; // 语速 (-5 到 5)
+  loudnessRate?: number; // 音量 (-5 到 5)
+}
+```
+
+**SSML 示例：**
+
+```typescript
+const ssmlText = `
+  <speak>
+    <prosody rate="slow">慢速说话</prosody>
+    <break time="500ms"/>
+    <prosody rate="fast">快速说话</prosody>
+  </speak>
+`;
+
+const response = await client.synthesize({
+  uid: 'user123',
+  ssml: ssmlText,
+  speaker: 'zh_female_xiaohe_uranus_bigtts',
+});
+```
+
+**自定义参数：**
+
+```typescript
+const response = await client.synthesize({
+  uid: 'user123',
+  text: '这是一段测试语音',
+  speaker: 'zh_female_xiaohe_uranus_bigtts',
+  audioFormat: 'mp3',
+  sampleRate: 24000,
+  speechRate: 1, // 加快语速
+  loudnessRate: 2, // 增大音量
+});
+```
+
+#### 语音识别 (ASR)
+
+```typescript
+import { ASRClient } from 'coze-coding-dev-sdk';
+
+const client = new ASRClient();
+
+const response = await client.recognize({
+  uid: 'user123',
+  url: 'https://example.com/audio.mp3',
+});
+
+console.log('Recognized Text:', response.text);
+console.log('Duration:', response.duration, 'seconds');
+```
+
+**功能特性：**
+
+- 语音转文字 (ASR)
+- 支持 URL 和 Base64 输入
+- 多种音频格式
+- 详细的时间戳信息
+- 最长 2 小时音频
+
+**音频要求：**
+
+- 音频时长 ≤ 2小时
+- 音频大小 ≤ 100MB
+- 支持编码: PCM/WAV/MP3/OGG OPUS
+
+**ASR 参数：**
+
+```typescript
+interface ASRRequest {
+  uid?: string; // 用户 ID
+  url?: string; // 音频 URL
+  base64Data?: string; // Base64 编码的音频数据
+}
+```
+
+**从 URL 识别：**
+
+```typescript
+const response = await client.recognize({
+  uid: 'user123',
+  url: 'https://example.com/audio.mp3',
+});
+```
+
+**从 Base64 识别：**
+
+```typescript
+const response = await client.recognize({
+  uid: 'user123',
+  base64Data: 'base64_encoded_audio_data',
+});
+```
+
+**TTS + ASR 完整流程：**
+
+```typescript
+const ttsClient = new TTSClient();
+const asrClient = new ASRClient();
+
+const originalText = '这是一段测试文本';
+
+const ttsResponse = await ttsClient.synthesize({
+  uid: 'user123',
+  text: originalText,
+});
+
+const asrResponse = await asrClient.recognize({
+  uid: 'user123',
+  url: ttsResponse.audioUri,
+});
+
+console.log('Original:', originalText);
+console.log('Recognized:', asrResponse.text);
+```
+
+### 4. 视频生成 (Video)
+
+```typescript
+import { VideoGenerationClient } from 'coze-coding-dev-sdk';
+
+const client = new VideoGenerationClient();
+
+const task = await client.textToVideo('一只可爱的小猫在草地上玩耍', {
+  config: {
+    resolution: '720p',
+    ratio: '16:9',
+    duration: 5,
+  },
+});
+
+console.log('Video URL:', task.video_url);
+```
+
+**功能特性：**
+
+- 文本生成视频 (text-to-video)
+- 图片生成视频 (image-to-video)
+- 支持首帧、尾帧、参考图片
+- 异步任务轮询
+- 多种分辨率和比例
+- 可配置时长、水印等
+
+**视频配置：**
+
+```typescript
+interface VideoGenerationConfig {
+  resolution?: '720p' | '1080p'; // 分辨率
+  ratio?: '16:9' | '9:16' | '1:1'; // 宽高比
+  duration?: number; // 时长 (5-10秒)
+  watermark?: boolean; // 水印
+  seed?: number; // 随机种子
+  camerafixed?: boolean; // 固定镜头
+}
+```
+
+**文生视频：**
+
+```typescript
+const task = await client.textToVideo('一只可爱的小猫在草地上玩耍', {
+  config: {
+    resolution: '1080p',
+    ratio: '16:9',
+    duration: 5,
+  },
+  pollInterval: 5,
+  maxWaitTime: 300,
+});
+```
+
+**图生视频（首帧）：**
+
+```typescript
+const task = await client.imageToVideo('小猫从坐着到站起来', {
+  firstFrameUrl: 'https://example.com/cat_sitting.jpg',
+  config: {
+    resolution: '720p',
+    ratio: '16:9',
+    duration: 5,
+  },
+});
+```
+
+**图生视频（首帧+尾帧）：**
+
+```typescript
+const task = await client.imageToVideo('小猫的动作变化', {
+  firstFrameUrl: 'https://example.com/cat_sitting.jpg',
+  lastFrameUrl: 'https://example.com/cat_standing.jpg',
+  config: {
+    resolution: '720p',
+    ratio: '16:9',
+    duration: 5,
+  },
+});
+```
+
+**参考图片生成：**
+
+```typescript
+const task = await client.imageToVideo('根据参考图片生成视频', {
+  referenceImages: ['https://example.com/reference1.jpg', 'https://example.com/reference2.jpg'],
+  config: {
+    resolution: '720p',
+    ratio: '9:16',
+    duration: 5,
+  },
+});
+```
+
+**检查任务状态：**
+
+```typescript
+const task = await client.checkTask('task_id');
+
+console.log('Status:', task.status);
+if (task.status === 'completed') {
+  console.log('Video URL:', task.video_url);
+} else if (task.status === 'failed') {
+  console.log('Error:', task.error_message);
+}
+```
+
+### 配置 (Config)
+
+```typescript
+import { Config } from 'coze-coding-dev-sdk';
+
+const config = new Config({
+  apiKey: process.env.COZE_WORKLOAD_IDENTITY_API_KEY,
+  baseUrl: process.env.COZE_INTEGRATION_BASE_URL,
+  modelBaseUrl: process.env.COZE_INTEGRATION_MODEL_BASE_URL,
+  retryTimes: 5,
+  retryDelay: 2,
+  timeout: 120000,
+});
+```
+
+### 异常处理
+
+```typescript
+import {
+  CozeSDKError,
+  APIError,
+  NetworkError,
+  ValidationError,
+  ConfigurationError,
+} from 'coze-coding-dev-sdk';
+
+try {
+  // SDK 调用
+} catch (error) {
+  if (error instanceof ValidationError) {
+    console.error(`参数错误: ${error.field} = ${error.value}`);
+  } else if (error instanceof APIError) {
+    console.error(`API 错误: ${error.message}, 状态码: ${error.statusCode}`);
+  } else if (error instanceof NetworkError) {
+    console.error(`网络错误: ${error.message}`);
+  } else if (error instanceof ConfigurationError) {
+    console.error(`配置错误: ${error.missingKey}`);
+  }
+}
+```
+
+## 📁 项目结构
+
+```
+typescript/
+├── src/
+│   ├── core/           # 核心层
+│   │   ├── config.ts   # 配置管理
+│   │   ├── client.ts   # 基础客户端
+│   │   └── exceptions.ts # 异常定义
+│   ├── image/          # 图片生成模块 ✅
+│   │   ├── client.ts   # ImageGenerationClient
+│   │   ├── models.ts   # 数据模型
+│   │   └── index.ts    # 导出
+│   ├── search/         # 搜索模块 ✅
+│   │   ├── client.ts   # SearchClient
+│   │   ├── models.ts   # 数据模型
+│   │   └── index.ts    # 导出
+│   ├── voice/          # 语音模块 ✅
+│   │   ├── tts.ts      # TTSClient
+│   │   ├── asr.ts      # ASRClient
+│   │   ├── models.ts   # 数据模型
+│   │   └── index.ts    # 导出
+│   ├── video/          # 视频生成模块 ✅
+│   │   ├── client.ts   # VideoGenerationClient
+│   │   ├── models.ts   # 数据模型
+│   │   └── index.ts    # 导出
+│   ├── llm/            # 大语言模型模块 ✅
+│   │   ├── client.ts   # LLMClient
+│   │   ├── models.ts   # 数据模型
+│   │   └── index.ts    # 导出
+│   ├── cli/            # CLI 工具 ✅
+│   │   ├── index.ts    # CLI 入口
+│   │   └── commands/   # 命令实现
+│   │       ├── image.ts
+│   │       ├── video.ts
+│   │       ├── search.ts
+│   │       ├── voice.ts
+│   │       └── chat.ts
+│   └── index.ts        # 主入口
+├── bin/
+│   └── coze-coding-ai.js # CLI 可执行文件
+├── examples/           # 使用示例
+│   ├── image-generation-example.ts
+│   ├── search-example.ts
+│   ├── voice-example.ts
+│   ├── video-example.ts
+│   └── llm-example.ts
+├── dist/               # 编译输出
+├── package.json        # npm 配置
+├── tsconfig.json       # TypeScript 配置
+├── CLI.md              # CLI 使用指南
+└── PUBLISHING.md       # 发布指南
+```
+
+### 5. 大语言模型 (LLM)
+
+```typescript
+import { LLMClient } from 'coze-coding-dev-sdk';
+
+const client = new LLMClient();
+
+const response = await client.invoke(
+  [
+    { role: 'system', content: '你是一个有帮助的AI助手。' },
+    { role: 'user', content: '介绍一下Python编程语言的特点' },
+  ],
+  { temperature: 0.7 }
+);
+
+console.log(response.content);
+```
+
+**功能特性：**
+
+- 流式对话 (stream)
+- 非流式对话 (invoke)
+- 支持 thinking 模式
+- 支持 caching 机制
+- 可配置温度、模型等参数
+- 多轮对话支持
+
+**流式对话：**
+
+```typescript
+const stream = client.stream([{ role: 'user', content: '介绍一下TypeScript' }], {
+  temperature: 0.7,
+});
+
+for await (const chunk of stream) {
+  if (chunk.content) {
+    process.stdout.write(chunk.content.toString());
+  }
+}
+```
+
+**LLM 配置：**
+
+```typescript
+interface LLMConfig {
+  model?: string; // 模型名称
+  thinking?: 'enabled' | 'disabled'; // 思考链
+  caching?: 'enabled' | 'disabled'; // 缓存
+  temperature?: number; // 温度 (0-2)
+  streaming?: boolean; // 是否流式
+}
+```
+
+## 🖥️ CLI 工具
+
+除了作为 SDK 使用，本包还提供了强大的命令行工具。
+
+### 全局安装
+
+```bash
+npm install -g coze-coding-dev-sdk
+```
+
+### 环境配置
+
+```bash
+export COZE_CODING_API_KEY="your-api-key-here"
+export COZE_CODING_BASE_URL="https://api.coze.cn"  # 可选
+export COZE_CODING_MODEL_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"  # 可选
+```
+
+### CLI 命令
+
+#### 1. 图片生成
+
+```bash
+# 基本用法
+coze-coding-ai image -p "a beautiful sunset over the ocean"
+
+# 指定尺寸并保存
+coze-coding-ai image -p "a cat" --size 4K -o output.jpg
+```
+
+#### 2. 视频生成
+
+```bash
+# 生成视频
+coze-coding-ai video -p "a cat playing with a ball" --duration 5
+
+# 查询状态
+coze-coding-ai video-status --task-id <task-id>
+```
+
+#### 3. 联网搜索
+
+```bash
+# 网页搜索
+coze-coding-ai search -q "TypeScript 最新特性" --count 10
+
+# 图片搜索
+coze-coding-ai search -q "sunset" --type image
+```
+
+#### 4. 语音合成
+
+```bash
+coze-coding-ai tts -t "你好，世界" --speaker zh_female_xiaohe_uranus_bigtts
+```
+
+#### 5. 语音识别
+
+```bash
+# 使用 URL
+coze-coding-ai asr -u "https://example.com/audio.mp3"
+
+# 使用本地文件
+coze-coding-ai asr -f ./audio.mp3
+```
+
+#### 6. AI 对话
+
+```bash
+# 基本对话
+coze-coding-ai chat -p "什么是人工智能？"
+
+# 流式输出
+coze-coding-ai chat -p "写一首诗" --stream
+
+# 带系统提示
+coze-coding-ai chat -p "解释量子计算" -s "你是一个物理学教授"
+```
+
+### CLI 使用场景
+
+**场景 1: 快速生成产品图片**
+
+```bash
+coze-coding-ai image \
+  -p "A modern smartphone with sleek design" \
+  --size 4K \
+  -o product.jpg
+```
+
+**场景 2: 内容研究**
+
+```bash
+# 搜索信息
+coze-coding-ai search -q "AI trends 2024" --count 20
+
+# AI 总结
+coze-coding-ai chat \
+  -p "总结一下 AI 在 2024 年的主要趋势" \
+  -s "你是一个 AI 研究专家"
+```
+
+**场景 3: 自动化工作流**
+
+```bash
+#!/bin/bash
+# 生成图片
+coze-coding-ai image -p "logo design" -o logo.jpg
+
+# 生成描述
+coze-coding-ai chat -p "为这个 logo 写一段营销文案" -o description.txt
+
+# 转语音
+coze-coding-ai tts -t "$(cat description.txt)"
+```
+
+查看完整的 CLI 文档：[CLI.md](./CLI.md)
+
+## 🛠️ 开发
+
+### 安装依赖
+
+```bash
+npm install
+```
+
+### 构建
+
+```bash
+npm run build
+```
+
+### 开发模式
+
+```bash
+npm run dev
+```
+
+### 本地测试 CLI
+
+```bash
+# 构建并链接
+npm run build
+npm link
+
+# 测试命令
+coze-coding-ai --version
+coze-coding-ai --help
+
+# 取消链接
+npm unlink -g coze-coding-dev-sdk
+```
+
+### 代码检查
+
+```bash
+npm run lint
+```
+
+### 格式化
+
+```bash
+npm run format
+```
+
+### 测试
+
+```bash
+npm test
+```
+
+## 📊 版本历史
+
+查看 [../../CHANGELOG.md](../../CHANGELOG.md) 了解详细的版本变更记录。
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+查看 [../../CONTRIBUTING.md](../../CONTRIBUTING.md) 了解如何参与贡献。
+
+## 📄 许可证
+
+本项目采用 [MIT License](../../LICENSE) 开源协议。
+
+## 🙏 致谢
+
+基于 Coze AI Integrations 和豆包大模型构建。
+
+## 📞 联系方式
+
+- 项目主页: https://github.com/coze/coze-sdk
+- 问题反馈: https://github.com/coze/coze-sdk/issues
+- 邮箱: support@coze.com