@bowenqt/qiniu-ai-sdk 0.27.2 → 0.28.0

package/README.md

@@ -1,43 +1,75 @@
 # Qiniu AI SDK
 
-TypeScript SDK for Qiniu Cloud AI Token API.
+<div align="center">
 
-## Features
+[![npm version](https://img.shields.io/npm/v/@bowenqt/qiniu-ai-sdk.svg?style=flat-square)](https://www.npmjs.com/package/@bowenqt/qiniu-ai-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg?style=flat-square)](https://nodejs.org/)
 
-- 🚀 **Chat Completions** - OpenAI-compatible interface
-- 🖼️ **Image Generation** - Kling, Gemini models
-- 🎥 **Video Generation** - Kling, Sora, Veo models
-- 🔍 **Web Search** - Real-time web search API
-- ⏱️ **Built-in Polling** - Async task management with retry and cancellation
-- 🤖 **Agentic Layer** - Multi-step tool execution with `generateText`
-- 📋 **JSON Mode** - Structured output with `response_format`
-- 🔌 **Vercel AI SDK Adapter** - Drop-in replacement for Vercel AI SDK
-- 📦 **TypeScript First** - Full type definitions included
-- 🧠 **Skills** - Markdown-based agent knowledge injection 
-- 🔗 **MCP Client** - Model Context Protocol stdio + HTTP transport 
-- 🔐 **OAuth 2.0** - PKCE and Device Code flows for MCP HTTP 
-- 💾 **Checkpointer** - Save/restore state: Memory, Redis, PostgreSQL 
-- 📊 **Tracing** - OpenTelemetry integration with per-node spans 
+**TypeScript SDK for Qiniu Cloud AI Services**
 
-## Requirements
+[English](./README.md) | [中文](./README.zh-CN.md) | [COOKBOOK](./COOKBOOK.md)
 
-- Node.js >= 18.0.0 (uses native `fetch`)
+</div>
 
-## Installation
+---
+
+## ✨ Features
+
+### Core AI Modules
+- 🚀 **Chat Completions** — OpenAI-compatible interface with streaming support
+- 🖼️ **Image Generation** — Kling, Gemini models with unified sync/async API
+- 🎥 **Video Generation** — Kling, Sora, Veo models with first/last frame control
+- 🔍 **Web Search** — Real-time web search integration
+- 📝 **OCR** — High-precision text recognition for images and PDFs
+- 🎤 **ASR** — Multi-language speech recognition (95%+ accuracy in noisy environments)
+- 🔊 **TTS** — Text-to-speech synthesis with multiple voice options
+- 🛡️ **Content Moderation** — Image and video censorship with scene-based detection
+
+### Agentic Layer
+- 🤖 **generateText** — Multi-step tool execution with Zod schema support
+- 📊 **generateObject/streamObject** — Structured JSON output with streaming
+- 🧠 **AgentGraph** — State machine-based graph execution
+- 🏭 **createAgent** — Reusable agent factory with configurable behaviors
+
+### Advanced Capabilities
+- 📋 **Skills Injection** — Markdown-based agent knowledge (Claude Skills compatible)
+- 🔗 **MCP Client** — Model Context Protocol with stdio + HTTP + OAuth 2.0 support
+- 🖥️ **MCP Server** — Built-in Qiniu MCP server for OCR/Censor/Vframe tools
+- 💾 **Checkpointer** — State persistence (Memory, Redis, PostgreSQL, Kodo)
+- 🧠 **Memory Manager** — Short-term + long-term memory with LLM summarization
+- ✅ **Tool Approval (HITL)** — Human-in-the-loop for sensitive operations
+- ⏸️ **Interrupt/Resume** — Resumable execution with checkpoint-based restore
+- 📊 **OpenTelemetry Tracing** — Distributed tracing with per-node spans
+- 🔌 **Vercel AI SDK Adapter** — Drop-in replacement for Vercel AI SDK
+
+---
+
+## 📦 Installation
 
 ```bash
 npm install @bowenqt/qiniu-ai-sdk
 ```
 
-### Installation for Adapter Users
-
-The Vercel AI SDK adapter is optional. Install the peer dependencies when you use it:
+### Optional Peer Dependencies
 
 ```bash
-npm install @bowenqt/qiniu-ai-sdk @ai-sdk/provider ai
+# For Vercel AI SDK integration
+npm install @ai-sdk/provider ai
+
+# For Zod schema validation
+npm install zod
+
+# For Redis checkpointer
+npm install ioredis
+
+# For PostgreSQL checkpointer
+npm install pg
 ```
 
-## Quick Start
+---
+
+## 🚀 Quick Start
 
 ```typescript
 import { QiniuAI } from '@bowenqt/qiniu-ai-sdk';
@@ -53,273 +85,144 @@ const chat = await client.chat.create({
 });
 console.log(chat.choices[0].message.content);
 
-// Image generation (async)
-const imageResult = await client.image.generate({
-  model: 'kling-v1',
-  prompt: 'A futuristic city',
-});
-const imageFinal = await client.image.waitForResult(imageResult);
-console.log(imageFinal.data?.[0].url || imageFinal.data?.[0].b64_json);
-
-// Video generation (async)
-const videoTask = await client.video.create({
-  model: 'kling-video-o1',
-  prompt: 'A cat walking on the beach',
-  duration: '5',
-});
-const videoResult = await client.video.waitForCompletion(videoTask.id);
-console.log(videoResult.task_result?.videos[0].url);
-
-// Web search
-const results = await client.sys.search({
-  query: 'Latest AI news',
-  max_results: 5,
-});
-console.log(results);
-
-// Streaming Chat (New!)
+// Streaming chat
 const stream = await client.chat.createStream({
   model: 'gemini-2.5-flash',
-  messages: [{ role: 'user', content: 'Explain quantum computing' }],
+  messages: [{ role: 'user', content: 'Explain AI briefly' }],
 });
-
 for await (const chunk of stream) {
   process.stdout.write(chunk.choices[0]?.delta?.content || '');
 }
 ```
 
-## Advanced Usage
-
-### StreamAccumulator (Manual Streaming)
-
-```typescript
-import { QiniuAI, createStreamAccumulator, accumulateDelta } from '@bowenqt/qiniu-ai-sdk';
-
-const client = new QiniuAI({ apiKey: 'Sk-xxx' });
-const stream = client.chat.createStream({
-  model: 'gemini-2.5-flash',
-  messages: [{ role: 'user', content: 'Explain streaming in one sentence.' }],
-});
-
-const acc = createStreamAccumulator();
-for await (const chunk of stream) {
-  const delta = chunk.choices[0]?.delta;
-  if (delta) {
-    accumulateDelta(acc, delta);
-  }
-}
-console.log(acc.content);
-```
-
-### parseSSEStream (Custom SSE Parsing)
-
-```typescript
-import { parseSSEStream } from '@bowenqt/qiniu-ai-sdk';
-
-const response = await fetch('https://api.qnaigc.com/v1/chat/completions', {
-  method: 'POST',
-  headers: {
-    'Content-Type': 'application/json',
-    'Authorization': `Bearer ${process.env.QINIU_API_KEY}`,
-  },
-  body: JSON.stringify({
-    model: 'gemini-2.5-flash',
-    messages: [{ role: 'user', content: 'Hello!' }],
-    stream: true,
-  }),
-});
-
-for await (const chunk of parseSSEStream(response)) {
-  console.log(chunk);
-}
-```
-
-### createPoller (Custom Async Polling)
-
-```typescript
-import { createPoller } from '@bowenqt/qiniu-ai-sdk';
-
-const poller = createPoller({
-  intervalMs: 2000,
-  timeoutMs: 60000,
-  isTerminal: (result) => result.status === 'succeed' || result.status === 'failed',
-  getStatus: (id) => client.video.get(id),
-});
-
-const result = await poller.poll('task-id');
-console.log(result.result);
-```
-
-## Agentic Layer
+---
 
-The SDK provides a high-level `generateText` function for multi-step tool execution:
+## 🤖 Agentic Usage
 
-### Basic Tool Usage
+### Tool Execution with generateText
 
 ```typescript
 import { QiniuAI, generateText } from '@bowenqt/qiniu-ai-sdk';
+import { z } from 'zod';
 
 const client = new QiniuAI({ apiKey: process.env.QINIU_API_KEY || '' });
 
 const result = await generateText({
   client,
   model: 'gemini-2.5-flash',
-  prompt: 'What is the weather in Beijing?',
+  prompt: 'What is 42 * 17?',
   tools: {
-    getWeather: {
-      description: 'Get weather for a city',
-      parameters: {
-        type: 'object',
-        properties: { city: { type: 'string' } },
-        required: ['city'],
+    calculate: {
+      description: 'Perform calculation',
+      parameters: z.object({
+        operation: z.enum(['add', 'subtract', 'multiply', 'divide']),
+        a: z.number(),
+        b: z.number(),
+      }),
+      execute: async ({ operation, a, b }) => {
+        const ops = { add: a + b, subtract: a - b, multiply: a * b, divide: a / b };
+        return ops[operation];
       },
-      execute: async ({ city }) => ({ temperature: 25, city }),
     },
   },
   maxSteps: 3,
 });
 
-console.log(result.text);      // Final response
-console.log(result.steps);     // All intermediate steps
-console.log(result.toolCalls); // Tool calls from last step
+console.log(result.text);       // Final answer
+console.log(result.toolCalls);  // Tool calls made
 ```
 
-### Zod Schema Support
-
-The SDK auto-converts Zod schemas to JSON Schema:
+### Structured Output
 
 ```typescript
+import { generateObject } from '@bowenqt/qiniu-ai-sdk';
 import { z } from 'zod';
 
-const tools = {
-  calculate: {
-    description: 'Calculate math',
-    parameters: z.object({
-      operation: z.enum(['add', 'subtract', 'multiply']),
-      a: z.number(),
-      b: z.number(),
-    }),
-    execute: async ({ operation, a, b }) => {
-      if (operation === 'add') return a + b;
-      if (operation === 'subtract') return a - b;
-      return a * b;
-    },
-  },
-};
-```
-
-### JSON Mode (Structured Output)
-
-```typescript
-const result = await generateText({
+const result = await generateObject({
   client,
   model: 'gemini-2.5-flash',
-  prompt: 'List 3 scientists as JSON array',
-  responseFormat: { type: 'json_object' },
-  temperature: 0,
+  prompt: 'Generate a product listing',
+  schema: z.object({
+    name: z.string(),
+    price: z.number(),
+    category: z.string(),
+  }),
 });
 
-const data = JSON.parse(result.text);
+console.log(result.object); // Typed object
 ```
 
-### Cancellation
+---
+
+## 🖼️ Image & Video Generation
 
 ```typescript
-const controller = new AbortController();
-setTimeout(() => controller.abort(), 5000);
-
-try {
-  const result = await generateText({
-    client,
-    model: 'gemini-2.5-flash',
-    prompt: 'Write a long essay...',
-    abortSignal: controller.signal,
-  });
-} catch (error) {
-  if (error.code === 'CANCELLED') {
-    console.log('Request cancelled');
-  }
-}
-```
-
-## Agent SDK (Agentic Layer)
+// Image generation (async task)
+const imageResult = await client.image.generate({
+  model: 'kling-v2',
+  prompt: 'A futuristic city at sunset',
+});
+const finalImage = await client.image.waitForResult(imageResult);
+console.log(finalImage.data?.[0].url);
 
-Phase 2 introduces advanced agentic capabilities with Skills injection, MCP integration, and Graph-based execution.
+// Video generation with first/last frame
+const videoTask = await client.video.create({
+  model: 'kling-video-o1',
+  prompt: 'A cat jumps from one ledge to another',
+  frames: {
+    first: { url: 'https://example.com/start.jpg' },
+    last: { url: 'https://example.com/end.jpg' },
+  },
+  duration: '5',
+});
+const videoResult = await client.video.waitForCompletion(videoTask.id);
+console.log(videoResult.task_result?.videos[0].url);
+```
 
-### generateTextWithGraph
+---
 
-Extended version of `generateText` with Skills, context compaction, and Graph events:
+## 🔌 Vercel AI SDK Adapter
 
 ```typescript
-import { QiniuAI, generateTextWithGraph, SkillLoader } from '@bowenqt/qiniu-ai-sdk';
-
-const client = new QiniuAI({ apiKey: process.env.QINIU_API_KEY });
-
-// Load skills
-const loader = new SkillLoader({ skillsDir: './skills' });
-const skills = await loader.loadAll();
+import { createQiniu } from '@bowenqt/qiniu-ai-sdk/adapter';
+import { streamText } from 'ai';
 
-const result = await generateTextWithGraph({
-  client,
-  model: 'deepseek-v3',
-  messages: [{ role: 'user', content: 'Help me with Git' }],
-  skills, // Injected into system prompt
-  maxContextTokens: 32000, // Automatic context compaction
-  onStepFinish: (step) => console.log(step.type, step.content),
-  onNodeEnter: (node) => console.log(`Entering: ${node}`),
+const qiniu = createQiniu({
+  apiKey: process.env.QINIU_API_KEY,
 });
 
-console.log(result.text);
-console.log(result.graphInfo?.skillsInjected); // ['git-workflow', ...]
+const { textStream } = await streamText({
+  model: qiniu.languageModel('gemini-2.5-flash'),
+  prompt: 'Introduce Qiniu Cloud briefly.',
+});
 
-// Check if compaction occurred
-if (result.graphInfo?.compaction?.occurred) {
-  console.log('Dropped skills:', result.graphInfo.compaction.droppedSkills);
+for await (const text of textStream) {
+  process.stdout.write(text);
 }
 ```
 
-**Context Compaction**: When `maxContextTokens` is set, the SDK automatically:
-- Estimates tokens using CJK-aware algorithm (1.5x weight for Chinese/Japanese/Korean)
-- Drops low-priority skills first when context exceeds budget
-- Preserves tool call/result pairs (never orphaned)
-- Reports dropped content in `graphInfo.compaction`
+---
 
-### Skills
+## 🧠 Advanced Features
 
-Load and inject agent skills (Markdown-based knowledge):
+### Skills Injection
 
 ```typescript
-import { SkillLoader } from '@bowenqt/qiniu-ai-sdk';
-
-const loader = new SkillLoader({
-  skillsDir: './skills',
-  maxFileSize: 64 * 1024, // 64KB limit
-  allowedExtensions: ['.md', '.txt'],
-});
-
-// Load single skill
-const skill = await loader.load('git-workflow');
-console.log(skill.name, skill.tokenCount);
+import { SkillLoader, generateTextWithGraph } from '@bowenqt/qiniu-ai-sdk';
 
-// Load all skills (sorted by name)
-const allSkills = await loader.loadAll();
-```
-
-Skill format (SKILL.md):
-```markdown
----
-name: git-workflow
-description: Git best practices
----
-
-# Git Workflow
+const loader = new SkillLoader({ skillsDir: './skills' });
+const skills = await loader.loadAll();
 
-Always use conventional commits...
+const result = await generateTextWithGraph({
+  client,
+  model: 'deepseek-v3',
+  messages: [{ role: 'user', content: 'Help me with Git' }],
+  skills,
+  maxContextTokens: 32000,
+});
 ```
 
-### MCP Client (stdio)
-
-Connect to Model Context Protocol servers:
+### MCP Client (stdio + HTTP)
 
 ```typescript
 import { MCPClient } from '@bowenqt/qiniu-ai-sdk';
@@ -331,642 +234,128 @@ const mcpClient = new MCPClient({
       transport: 'stdio',
       command: 'npx',
       args: ['-y', '@modelcontextprotocol/server-github'],
-      token: process.env.GITHUB_TOKEN, // → MCP_BEARER_TOKEN env
+      token: process.env.GITHUB_TOKEN,
     },
   ],
 });
 
 await mcpClient.connect();
 const tools = mcpClient.getAllTools();
-console.log(tools.map(t => t.name));
-
-// Use tools with generateText
-const registeredTools = adaptMCPToolsToRegistry(tools, 'github', mcpClient);
 ```
 
-> **Note**: Bearer token is injected via `MCP_BEARER_TOKEN` environment variable for stdio transport.
-
-### MCP Client (HTTP + OAuth 2.0)
-
-Connect to remote MCP servers with OAuth authentication:
+### Checkpointer (State Persistence)
 
 ```typescript
-import { 
-  MCPClient, 
-  PKCEFlow, 
-  TokenManager, 
-  MemoryTokenStore 
-} from '@bowenqt/qiniu-ai-sdk';
-
-// Step 1: Obtain tokens via PKCE flow
-const oauthConfig = {
-  clientId: 'my-app',
-  scopes: ['mcp:read', 'mcp:write'],
-  authorizationUrl: 'https://auth.example.com/authorize',
-  tokenUrl: 'https://auth.example.com/token',
-};
-
-const pkceFlow = new PKCEFlow(oauthConfig);
-const state = generateState();
-const authUrl = pkceFlow.buildAuthorizationUrl('http://localhost:3000/callback', state);
-// Redirect user to authUrl...
-
-// After callback:
-const { code } = await pkceFlow.waitForCallback({ expectedState: state, timeoutMs: 300000 });
-const tokens = await pkceFlow.exchangeCode(code, 'http://localhost:3000/callback');
-
-// Step 2: Set up TokenManager
-const tokenManager = new TokenManager(new MemoryTokenStore(), oauthConfig);
-await tokenManager.setTokens(tokens);
-
-// Step 3: Connect with tokenProvider
-const mcpClient = new MCPClient({
-  servers: [
-    {
-      name: 'remote-server',
-      transport: 'http',
-      url: 'https://mcp.example.com/mcp',
-      tokenProvider: () => tokenManager.getAccessToken(),
-      oauth: oauthConfig, // Required: validates auth is configured
-    },
-  ],
-});
-
-await mcpClient.connect();
-```
-
-> **Note**: If `oauth` is configured without `token` or `tokenProvider`, MCPClient throws an error to prevent unauthenticated connections.
-
-### Checkpointer
+import { MemoryCheckpointer, RedisCheckpointer, KodoCheckpointer } from '@bowenqt/qiniu-ai-sdk';
 
-Save and restore conversation state:
+// In-memory (dev/testing)
+const memoryCheckpointer = new MemoryCheckpointer({ maxItems: 100 });
 
-```typescript
-import { MemoryCheckpointer, deserializeCheckpoint } from '@bowenqt/qiniu-ai-sdk';
-
-const checkpointer = new MemoryCheckpointer({ maxItems: 100 });
-
-// Save checkpoint
-const metadata = await checkpointer.save('thread-123', agentState);
-
-// Load latest checkpoint
-const checkpoint = await checkpointer.load('thread-123');
-if (checkpoint) {
-  const restored = deserializeCheckpoint(checkpoint, toolsMap);
-  // Resume from restored state
-}
-
-// List all checkpoints
-const list = await checkpointer.list('thread-123');
-```
-
-### Redis/PostgreSQL Checkpointer
-
-For production persistence:
-
-```typescript
-import { RedisCheckpointer, PostgresCheckpointer } from '@bowenqt/qiniu-ai-sdk';
-
-// Redis (requires ioredis peer dependency)
+// Redis (production)
 const redisCheckpointer = new RedisCheckpointer(redisClient, {
-  keyPrefix: 'chat:',
-  ttlSeconds: 86400, // 24 hours
+  keyPrefix: 'agent:',
+  ttlSeconds: 86400,
 });
 
-// PostgreSQL (requires pg peer dependency)
-const pgCheckpointer = new PostgresCheckpointer(pgPool, {
-  tableName: 'checkpoints',
-  autoCreateTable: true,
+// Kodo (cloud-native/serverless)
+const kodoCheckpointer = new KodoCheckpointer({
+  accessKey: process.env.QINIU_ACCESS_KEY!,
+  secretKey: process.env.QINIU_SECRET_KEY!,
+  bucket: 'checkpoints',
+  region: 'z0',
 });
 ```
 
-### Tracing (OpenTelemetry)
-
-Integrate with OpenTelemetry for distributed tracing:
+### OpenTelemetry Tracing
 
 ```typescript
-import { setGlobalTracer, OTelTracer, ConsoleTracer } from '@bowenqt/qiniu-ai-sdk';
-
-// Console tracer for development
-setGlobalTracer(new ConsoleTracer({ redactPII: true }));
-
-// OpenTelemetry tracer for production
+import { setGlobalTracer, OTelTracer } from '@bowenqt/qiniu-ai-sdk';
 import { trace } from '@opentelemetry/api';
+
 const otelTracer = new OTelTracer(trace.getTracerProvider());
 setGlobalTracer(otelTracer);
 
-// AgentGraph automatically creates spans:
-// - agent_graph.invoke (top-level)
-// - agent_graph.predict (per LLM call)
-// - agent_graph.execute (per tool execution round)
-```
-
-
-## Vercel AI SDK Adapter
-
-Use the adapter to integrate with the Vercel AI SDK (`streamText`, `generateText`).
-
-```typescript
-import { createQiniu } from '@bowenqt/qiniu-ai-sdk/adapter';
-import { streamText } from 'ai';
-
-const qiniu = createQiniu({
-  apiKey: process.env.QINIU_API_KEY || process.env.OPENAI_API_KEY,
-});
-
-const { textStream } = await streamText({
-  model: qiniu.languageModel('gemini-2.5-flash'),
-  prompt: 'Introduce Qiniu Cloud in one sentence.',
-});
-
-for await (const text of textStream) {
-  process.stdout.write(text);
-}
-```
-
-Notes:
-- If you already have a `QiniuAI` client, pass it via `createQiniu({ client })`.
-- You can override `baseUrl` using `createQiniu({ baseUrl })` or `QINIU_BASE_URL`.
-
-## API Reference
-
-### Client Initialization
-
-```typescript
-import { QiniuAI, consoleLogger } from '@bowenqt/qiniu-ai-sdk';
-
-const client = new QiniuAI({
-  apiKey: string;           // Required: Your Qiniu AI API key
-  baseUrl?: string;         // Optional: API base URL (default: https://api.qnaigc.com/v1)
-  timeout?: number;         // Optional: Request timeout in ms (default: 60000)
-  logger?: Logger;          // Optional: Custom logger (use consoleLogger for debug output)
-  logLevel?: LogLevel;      // Optional: 'debug' | 'info' | 'warn' | 'error' | 'silent' (default: 'info')
-});
-```
-
-### Logging
-
-Enable debug logging to see request/response details:
-
-```typescript
-import { QiniuAI, consoleLogger } from '@bowenqt/qiniu-ai-sdk';
-
-const client = new QiniuAI({
-  apiKey: 'Sk-xxx',
-  logger: consoleLogger,
-  logLevel: 'debug',
-});
-
-// Now you'll see logs like:
-// [QiniuAI:DEBUG] HTTP Request { requestId: 'req_123...', method: 'POST', url: '...', timeout: 60000 }
-// [QiniuAI:DEBUG] HTTP Response { requestId: 'req_123...', status: 200, duration: 1234 }
-```
-
-Use a custom logger (e.g., pino, winston):
-
-```typescript
-import { QiniuAI, Logger } from '@bowenqt/qiniu-ai-sdk';
-import pino from 'pino';
-
-const pinoLogger = pino();
-
-const customLogger: Logger = {
-  debug: (msg, meta) => pinoLogger.debug(meta, msg),
-  info: (msg, meta) => pinoLogger.info(meta, msg),
-  warn: (msg, meta) => pinoLogger.warn(meta, msg),
-  error: (msg, meta) => pinoLogger.error(meta, msg),
-};
-
-const client = new QiniuAI({
-  apiKey: 'Sk-xxx',
-  logger: customLogger,
-});
-```
-
-### Middleware
-
-Use middleware to intercept and modify requests/responses:
-
-```typescript
-import { QiniuAI, Middleware, retryMiddleware, headersMiddleware } from '@bowenqt/qiniu-ai-sdk';
-
-// Built-in retry middleware (retries on 5xx errors)
-const retry = retryMiddleware({ maxRetries: 3, retryDelay: 1000 });
-
-// Built-in headers middleware (adds custom headers)
-const customHeaders = headersMiddleware({
-  'X-Custom-Header': 'my-value',
-});
-
-// Custom middleware
-const loggingMiddleware: Middleware = async (request, next) => {
-  console.log('Request:', request.method, request.url);
-  const response = await next(request);
-  console.log('Response:', response.status, response.duration + 'ms');
-  return response;
-};
-
-const client = new QiniuAI({
-  apiKey: 'Sk-xxx',
-  middleware: [retry, customHeaders, loggingMiddleware],
-});
-```
-
-### Custom HTTP Adapter
-
-Replace the default `fetch` with a custom HTTP client:
-
-```typescript
-import { QiniuAI, FetchAdapter } from '@bowenqt/qiniu-ai-sdk';
-import axios from 'axios';
-
-const axiosAdapter: FetchAdapter = {
-  async fetch(url, init) {
-    const response = await axios({
-      url,
-      method: init.method as any,
-      headers: init.headers as Record<string, string>,
-      data: init.body,
-      signal: init.signal,
-      validateStatus: () => true, // Don't throw on non-2xx
-    });
-    
-    return new Response(JSON.stringify(response.data), {
-      status: response.status,
-      headers: response.headers as any,
-    });
-  },
-};
-
-const client = new QiniuAI({
-  apiKey: 'Sk-xxx',
-  adapter: axiosAdapter,
-});
-```
-
-### Modules
-
-#### `client.chat`
-
-- `create(params: ChatCompletionRequest): Promise<ChatCompletionResponse>`
-- `createStream(params: ChatCompletionRequest): AsyncGenerator<ChatCompletionChunk>` (New!)
-
-**Streaming Example with Function Calling & Reasoning:**
-
-```typescript
-const stream = await client.chat.createStream({
-  model: 'gemini-2.5-flash', // Models supporting reasoning
-  messages: [{ role: 'user', content: 'Solve this puzzle...' }],
-});
-
-for await (const chunk of stream) {
-  const delta = chunk.choices[0]?.delta;
-  
-  // Text content
-  if (delta?.content) {
-    process.stdout.write(delta.content);
-  }
-  
-  // Reasoning content (Gemini/Claude thinking process)
-  if (delta?.reasoning_content) {
-    console.log('[Thinking]:', delta.reasoning_content);
-  }
-  
-  // Function calling arguments are also streamed incrementally
-}
-```
-
-#### `client.image`
-
-- `generate(params: ImageGenerationRequest): Promise<ImageCreateResult>`
-- `waitForResult(result: ImageCreateResult, options?: WaitOptions): Promise<ImageGenerateResult>`
-- `create(params: ImageGenerationRequest): Promise<{ task_id: string }>` (deprecated)
-- `edit(params: ImageEditRequest): Promise<ImageEditResponse>`
-- `get(taskId: string): Promise<ImageTaskResponse>`
-- `waitForCompletion(taskId: string, options?: WaitOptions): Promise<ImageTaskResponse>` (deprecated)
-
-Note: For sync models (Gemini), `waitForResult` returns `status: 'succeed'` set by the SDK when data is returned.
-
-**Image Edit (Kling/Gemini):**
-
-```typescript
-// Kling multi-image edit
-const editTask = await client.image.edit({
-  model: 'kling-v1',
-  prompt: 'Make it watercolor style',
-  image_reference: 'subject',
-  subject_image_list: [{ image: 'https://example.com/subject.jpg', image_type: 'subject' }],
-  scene_image: { image: 'https://example.com/scene.jpg', image_type: 'scene' },
-  style_image: { image: 'https://example.com/style.jpg', image_type: 'style' },
-});
-
-// Gemini edit
-const geminiEdit = await client.image.edit({
-  model: 'gemini-3.0-pro-image-preview',
-  prompt: 'Add a sunset sky',
-  image_url: 'https://example.com/input.png',
-  image_config: { aspect_ratio: '16:9', image_size: '2K' },
-  mask: 'base64-mask-data',
-});
-```
-
-#### `client.video`
-
-- `create(params: VideoGenerationRequest): Promise<{ id: string }>`
-- `get(id: string): Promise<VideoTaskResponse>`
-- `remix(id: string, params: VideoRemixRequest): Promise<{ id: string }>`
-- `waitForCompletion(id: string, options?: WaitOptions): Promise<VideoTaskResponse>`
-
-**First & Last Frame Video Generation:**
-
-The SDK provides a unified `frames` parameter that works across all models (Kling, Veo):
-
-```typescript
-// Kling first/last frame (multi-frame generation)
-const klingTask = await client.video.create({
-  model: 'kling-video-o1',
-  prompt: '视频连贯在一起',
-  frames: {
-    first: { url: 'https://example.com/start.jpg' },
-    last: { url: 'https://example.com/end.jpg' }
-  },
-  size: '1920x1080',
-  mode: 'pro'
-});
-
-// Veo first/last frame
-const veoTask = await client.video.create({
-  model: 'veo-2.0-generate-001',
-  prompt: 'A cat jumping from chair to table',
-  frames: {
-    first: { url: 'https://example.com/cat-chair.jpg' },
-    last: { url: 'https://example.com/cat-table.jpg' }
-  },
-  generate_audio: true,
-  resolution: '720p',
-  seed: 12345,
-  sample_count: 1
-});
-
-// Wait for completion (works with both Kling and Veo)
-const result = await client.video.waitForCompletion(veoTask.id);
-console.log(result.task_result?.videos[0].url);
-```
-
-**Video Reference Generation (Kling):**
-
-```typescript
-const task = await client.video.create({
-  model: 'kling-video-o1',
-  prompt: '融合视频风格生成新内容',
-  video_list: [{
-    video_url: 'https://example.com/reference.mp4',
-    refer_type: 'base',
-    keep_original_sound: 'yes'
-  }]
-});
-```
-
-**Kling Native Parameters:**
-
-For backward compatibility, you can also use Kling's native parameters directly:
-
-```typescript
-// Using image_list directly (kling-video-o1)
-const task = await client.video.create({
-  model: 'kling-video-o1',
-  prompt: '...',
-  image_list: [
-    { image: 'https://...', type: 'first_frame' },
-    { image: 'https://...', type: 'end_frame' }
-  ]
-});
-
-// Using image_tail (kling-v2-5-turbo)
-const task = await client.video.create({
-  model: 'kling-v2-5-turbo',
-  prompt: '...',
-  input_reference: 'https://example.com/start.jpg',
-  image_tail: 'https://example.com/end.jpg'
-});
-```
-
-**Video Remix (Sora):**
-
-```typescript
-const remixTask = await client.video.remix('videos-123...', {
-  prompt: 'Make it cinematic',
-});
-console.log(remixTask.id);
-```
-
-#### `client.ocr`
-
-- `detect(params: OcrRequest): Promise<OcrResponse>`
-
-**OCR Example:**
-
-```typescript
-const ocrResult = await client.ocr.detect({
-  url: 'https://static.qiniu.com/ai-inference/example-resources/ocr-example.png',
-});
-console.log(ocrResult.text);
-```
-
-#### `client.asr`
-
-- `transcribe(params: AsrRequest): Promise<AsrResponse>`
-
-**ASR Example:**
-
-```typescript
-const asrResult = await client.asr.transcribe({
-  audio: {
-    format: 'mp3',
-    url: 'https://static.qiniu.com/ai-inference/example-resources/example.mp3',
-  },
-});
-console.log(asrResult.text);
-```
-
-#### `client.account`
-
-- `usage(params: UsageQuery): Promise<UsageResponse>`
-
-**Account Usage Example (API Key):**
-
-```typescript
-const usage = await client.account.usage({
-  granularity: 'day',
-  start: '2024-01-01T00:00:00+08:00',
-  end: '2024-01-31T23:59:59+08:00',
-});
-console.log(usage.data.length);
-```
-
-**Account Usage Example (AK/SK):**
-
-```typescript
-const usage = await client.account.usage({
-  granularity: 'day',
-  start: '2024-01-01T00:00:00+08:00',
-  end: '2024-01-31T23:59:59+08:00',
-  auth: {
-    accessKey: 'your-ak',
-    secretKey: 'your-sk',
-  },
-});
-console.log(usage.data.length);
+// AgentGraph will now emit spans:
+// - agent_graph.invoke
+// - agent_graph.predict
+// - agent_graph.execute
 ```
 
-#### `client.sys`
-
-- `search(params: WebSearchRequest): Promise<WebSearchResult[]>`
-
-### Advanced Usage: Generic API Access
-
-For features not yet fully wrapped in modules, use the generic `post` and `get` methods.
-
-**OCR (Optical Character Recognition):**
-
-```typescript
-const response = await client.post<any>('/images/ocr', {
-  model: 'ocr',
-  url: 'https://example.com/image.png'
-});
-console.log(response.data.result.text);
-```
-
-**TTS (Text to Speech):**
-
-```typescript
-// Get Voice List
-const voices = await client.get<any[]>('/voice/list');
-
-// Synthesize Audio
-const res = await client.post<any>('/voice/tts', {
-  request: { text: 'Hello world' },
-  audio: { voice_type: 'qiniu_zh_female_xxx' }
-});
-```
-
-### Wait Options
-
-For `waitForCompletion` and `waitForResult` methods:
-
-```typescript
-interface WaitOptions {
-  intervalMs?: number;    // Polling interval (default: 2000 for image, 3000 for video)
-  timeoutMs?: number;     // Max wait time (default: 120000 for image, 600000 for video)
-  signal?: AbortSignal;   // For cancellation support
-  maxRetries?: number;    // Max retries for transient errors (default: 3)
-}
-```
-
-### Error Handling
+---
 
-```typescript
-import { QiniuAI, APIError } from '@bowenqt/qiniu-ai-sdk';
-
-try {
-  await client.chat.create({ ... });
-} catch (error) {
-  if (error instanceof APIError) {
-    console.log(error.status);  // HTTP status code
-    console.log(error.code);    // API error code (if any)
-    console.log(error.message); // Error message
-  }
-}
-```
+## 📚 Supported Models
 
-### Cancellation
+### Chat & Reasoning (66+ models)
 
-```typescript
-const controller = new AbortController();
-
-// Cancel after 10 seconds
-setTimeout(() => controller.abort(), 10000);
-
-try {
-  const createResult = await client.image.generate({
-    model: 'kling-v2',
-    prompt: 'A cute cat',
-  });
-  const result = await client.image.waitForResult(createResult, {
-    signal: controller.signal,
-  });
-} catch (error) {
-  if (error.message === 'Operation cancelled') {
-    console.log('Task was cancelled');
-  }
-}
-```
-
-## Supported Models
-
-### Chat & Reasoning (66 models)
+| Provider | Models |
+|----------|--------|
+| **Qwen** | qwen3-235b, qwen3-max, qwen3-32b, qwen-turbo |
+| **Claude** | claude-4.5-opus/sonnet/haiku, claude-4.0-opus/sonnet, claude-3.7-sonnet, claude-3.5-sonnet/haiku |
+| **Gemini** | gemini-3.0-flash/pro, gemini-2.5-flash/pro, gemini-2.0-flash |
+| **DeepSeek** | deepseek-r1, deepseek-v3/v3.1/v3.2 |
+| **Doubao** | doubao-seed-1.6, doubao-1.5-pro |
+| **GLM** | glm-4.5/4.6/4.7 |
+| **Grok** | grok-4-fast, grok-4.1-fast |
+| **OpenAI** | gpt-5/5.2, gpt-oss-20b/120b |
+| **Kimi** | kimi-k2 |
+| **MiniMax** | minimax-m2/m2.1 |
+
+### Image Generation
 
 | Provider | Models |
 |----------|--------|
-| **Qwen** | `qwen3-235b-a22b-thinking-2507`, `qwen3-235b-a22b-instruct-2507`, `qwen3-235b-a22b`, `qwen3-max-preview`, `qwen3-max`, `qwen3-32b`, `qwen3-30b-a3b`, `qwen3-next-80b-a3b-thinking`, `qwen3-next-80b-a3b-instruct`, `qwen3-coder-480b-a35b-instruct`, `qwen-max-2025-01-25`, `qwen-turbo` |
-| **Claude** | `claude-4.5-opus`, `claude-4.5-haiku`, `claude-4.5-sonnet`, `claude-4.1-opus`, `claude-4.0-opus`, `claude-4.0-sonnet`, `claude-3.7-sonnet`, `claude-3.5-sonnet`, `claude-3.5-haiku` |
-| **Gemini** | `gemini-3.0-flash-preview`, `gemini-3.0-pro-preview`, `gemini-2.5-flash-lite`, `gemini-2.5-flash`, `gemini-2.5-pro`, `gemini-2.0-flash-lite`, `gemini-2.0-flash` |
-| **DeepSeek** | `deepseek-r1-0528`, `deepseek-r1`, `deepseek-v3`, `deepseek-v3-0324`, `deepseek-v3.1`, `deepseek/deepseek-v3.2-251201`, `deepseek/deepseek-v3.2-exp-thinking`, `deepseek/deepseek-v3.2-exp`, `deepseek/deepseek-v3.1-terminus-thinking`, `deepseek/deepseek-v3.1-terminus` |
-| **Doubao** | `doubao-seed-1.6-thinking`, `doubao-seed-1.6-flash`, `doubao-seed-1.6`, `doubao-1.5-thinking-pro`, `doubao-1.5-pro-32k` |
-| **GLM** | `glm-4.5`, `glm-4.5-air`, `z-ai/glm-4.7`, `z-ai/glm-4.6` |
-| **Grok** | `x-ai/grok-4-fast-reasoning`, `x-ai/grok-4-fast-non-reasoning`, `x-ai/grok-4-fast`, `x-ai/grok-4.1-fast-non-reasoning`, `x-ai/grok-4.1-fast-reasoning`, `x-ai/grok-4.1-fast`, `x-ai/grok-code-fast-1` |
-| **OpenAI** | `openai/gpt-5.2`, `openai/gpt-5`, `gpt-oss-20b`, `gpt-oss-120b` |
-| **Kimi** | `moonshotai/kimi-k2-thinking`, `moonshotai/kimi-k2-0905`, `kimi-k2` |
-| **MiniMax** | `minimax/minimax-m2`, `minimax/minimax-m2.1`, `MiniMax-M1`, `mimo-v2-flash` |
-| **Meituan** | `meituan/longcat-flash-chat` |
-| **StepFun** | `stepfun-ai/gelab-zero-4b-preview` |
-| **AutoGLM** | `z-ai/autoglm-phone-9b` |
-
-### Image Generation & Vision
-
-| Type | Models |
-|------|--------|
-| **Kling** | `kling-v1`, `kling-v1-5`, `kling-v2`, `kling-v2-new`, `kling-v2-1` |
-| **Gemini** | `gemini-3.0-pro-image-preview`, `gemini-2.5-flash-image` |
-| **Vision** | `doubao-1.5-vision-pro`, `qwen2.5-vl-7b-instruct`, `qwen2.5-vl-72b-instruct`, `qwen-vl-max-2025-01-25` |
+| **Kling** | kling-v1, kling-v1-5, kling-v2, kling-v2-1 |
+| **Gemini** | gemini-3.0-pro-image, gemini-2.5-flash-image |
 
 ### Video Generation
 
 | Provider | Models |
 |----------|--------|
-| **Kling** | `kling-video-o1`, `kling-v2-1`, `kling-v2-5-turbo` |
-| **Sora** | `sora-2` |
-| **Veo** | `veo-2.0-generate-001`, `veo-3.0-generate-001`, `veo-3.0-fast-generate-001`, `veo-3.0-generate-preview`, `veo-3.0-fast-generate-preview`, `veo-3.1-generate-preview`, `veo-3.1-fast-generate-preview` |
-| **Other** | `minimax/minimax-m2`, `mimo-v2-flash` |
+| **Kling** | kling-video-o1, kling-v2-1, kling-v2-5-turbo |
+| **Sora** | sora-2 |
+| **Veo** | veo-2.0, veo-3.0, veo-3.1 |
 
-### OCR (文字识别)
+---
+
+## 📁 Package Exports
+
+| Entry Point | Description |
+|-------------|-------------|
+| `@bowenqt/qiniu-ai-sdk` | Main entry (universal) |
+| `@bowenqt/qiniu-ai-sdk/node` | Node.js-only features (SkillLoader, MCPClient stdio) |
+| `@bowenqt/qiniu-ai-sdk/browser` | Browser-compatible subset |
+| `@bowenqt/qiniu-ai-sdk/adapter` | Vercel AI SDK adapter |
+| `@bowenqt/qiniu-ai-sdk/ai-tools` | Qiniu native cloud tools (OCR/Censor/Vframe) |
+
+---
 
-| Model | Description |
-|-------|-------------|
-| `ocr` | 图片/PDF文档高精度文字识别，支持 PNG、JPG、PDF 等格式 |
+## 🛠️ CLI: MCP Server
 
-### ASR (语音识别)
+Run the built-in Qiniu MCP Server:
 
-| Model | Description |
-|-------|-------------|
-| `asr` | 中英等多语种语音识别，嘈杂环境识别准确率超95%，支持 raw/wav/mp3/ogg 格式 |
+```bash
+npx qiniu-mcp-server
+```
 
-### TTS (语音合成)
+**Environment variables:**
+- `QINIU_API_KEY` — API key for OCR/Censor operations
+- `QINIU_ACCESS_KEY` / `QINIU_SECRET_KEY` — For Vframe/signed operations
 
-通过 `/voice/list` 接口获取完整音色列表，使用 `voice_type` 参数指定音色：
+---
 
-| Voice Type | Description |
-|------------|-------------|
-| `qiniu_zh_female_tmjxxy` | 甜美教学小源 |
-| `qiniu_zh_female_wwxkjx` | 温婉小课堂 |
-| ... | 更多音色请通过 API 获取 |
+## 📖 Documentation
+
+- **[COOKBOOK.md](./COOKBOOK.md)** — Copy-ready code examples for all features
+- **[Qiniu AI Developer Center](https://developer.qiniu.com/aitokenapi)** — Full API reference & pricing
 
 ---
 
-**Summary**: 66 Chat models, 11 Image models, 12 Video models, OCR, ASR, TTS
+## 📄 License
 
-For the full list and pricing, check [Qiniu AI Developer Center](https://developer.qiniu.com/aitokenapi).
+MIT © 2024-2026
 
-## License
+---
 
-MIT
+<div align="center">
+  <sub>Built with ❤️ for the Qiniu Cloud ecosystem</sub>
+</div>