persona-core 1.0.0

package/dist/utils/sharedDataUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharedDataUtils.d.ts","sourceRoot":"","sources":["../../src/utils/sharedDataUtils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE/F;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GACvC,kBAAkB,CAuBpB;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,kBAAkB,EAC3B,WAAW,EAAE,qBAAqB,GACjC,kBAAkB,CAiBpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EACxC,WAAW,CAAC,EAAE,qBAAqB,GAClC,kBAAkB,CAcpB"}

package/dist/utils/sharedDataUtils.js

@@ -0,0 +1,84 @@
+/**
+ * SharedData 工具函数
+ * 提供共享数据更新的通用逻辑
+ */
+/**
+ * 更新共享数据
+ * 区分集合类型和普通类型：
+ * - 集合类型：追加到数组
+ * - 普通类型：直接覆盖
+ *
+ * @param current - 当前共享数据实例
+ * @param updates - 要更新的字段和值
+ * @returns 更新后的共享数据实例
+ */
+export function updateSharedData(current, updates) {
+    const result = {
+        data: { ...current.data },
+        fieldTypes: { ...current.fieldTypes },
+    };
+    for (const [key, value] of Object.entries(updates)) {
+        // 检查是否为集合类型
+        if (result.fieldTypes[key]) {
+            // 集合类型：追加
+            const existing = result.data[key];
+            if (Array.isArray(existing)) {
+                result.data[key] = [...existing, value];
+            }
+            else {
+                result.data[key] = [value];
+            }
+        }
+        else {
+            // 普通类型：覆盖
+            result.data[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * 应用共享数据声明
+ * 添加新的字段类型定义和初始值
+ *
+ * @param current - 当前共享数据实例
+ * @param declaration - 共享数据声明
+ * @returns 更新后的共享数据实例
+ */
+export function applySharedDataDeclaration(current, declaration) {
+    const result = {
+        data: { ...current.data },
+        fieldTypes: { ...current.fieldTypes },
+    };
+    for (const field of declaration.fields) {
+        // 只添加新字段，不覆盖已存在的
+        if (!(field.name in result.fieldTypes)) {
+            result.fieldTypes[field.name] = field.isCollection;
+            if (field.initialValue !== undefined) {
+                result.data[field.name] = field.initialValue;
+            }
+        }
+    }
+    return result;
+}
+/**
+ * 合并共享数据更新和声明
+ * 先应用声明，再应用更新
+ *
+ * @param current - 当前共享数据实例
+ * @param updates - 要更新的字段和值
+ * @param declaration - 可选的共享数据声明
+ * @returns 更新后的共享数据实例
+ */
+export function mergeSharedDataUpdates(current, updates, declaration) {
+    let result = current;
+    // 先应用声明
+    if (declaration) {
+        result = applySharedDataDeclaration(result, declaration);
+    }
+    // 再应用更新
+    if (Object.keys(updates).length > 0) {
+        result = updateSharedData(result, updates);
+    }
+    return result;
+}
+//# sourceMappingURL=sharedDataUtils.js.map

package/dist/utils/sharedDataUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharedDataUtils.js","sourceRoot":"","sources":["../../src/utils/sharedDataUtils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAA2B,EAC3B,OAAwC;IAExC,MAAM,MAAM,GAAuB;QACjC,IAAI,EAAE,EAAE,GAAG,OAAO,CAAC,IAAI,EAAE;QACzB,UAAU,EAAE,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE;KACtC,CAAC;IAEF,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACnD,YAAY;QACZ,IAAI,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3B,UAAU;YACV,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAClC,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC5B,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,QAAQ,EAAE,KAAK,CAAC,CAAC;YAC1C,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YAC7B,CAAC;QACH,CAAC;aAAM,CAAC;YACN,UAAU;YACV,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,0BAA0B,CACxC,OAA2B,EAC3B,WAAkC;IAElC,MAAM,MAAM,GAAuB;QACjC,IAAI,EAAE,EAAE,GAAG,OAAO,CAAC,IAAI,EAAE;QACzB,UAAU,EAAE,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE;KACtC,CAAC;IAEF,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,MAAM,EAAE,CAAC;QACvC,iBAAiB;QACjB,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,IAAI,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;YACvC,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,YAAY,CAAC;YACnD,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;gBACrC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,YAAY,CAAC;YAC/C,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAA2B,EAC3B,OAAwC,EACxC,WAAmC;IAEnC,IAAI,MAAM,GAAG,OAAO,CAAC;IAErB,QAAQ;IACR,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,GAAG,0BAA0B,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC3D,CAAC;IAED,QAAQ;IACR,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpC,MAAM,GAAG,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7C,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/utils/typeGuards.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 类型守卫函数
+ * 用于替代类型断言，提高类型安全性
+ */
+import { NodeInstance, ThinkingNodeInstance, ActionNodeInstance, BranchNodeInstance } from '../types/index.js';
+/**
+ * 检查节点是否为思考节点
+ */
+export declare function isThinkingNode(node: NodeInstance): node is ThinkingNodeInstance;
+/**
+ * 检查节点是否为动作节点
+ */
+export declare function isActionNode(node: NodeInstance): node is ActionNodeInstance;
+/**
+ * 检查节点是否为分支节点
+ */
+export declare function isBranchNode(node: NodeInstance): node is BranchNodeInstance;
+/**
+ * 断言节点为思考节点
+ * @throws Error 如果节点不是思考节点
+ */
+export declare function assertThinkingNode(node: NodeInstance): asserts node is ThinkingNodeInstance;
+/**
+ * 断言节点为动作节点
+ * @throws Error 如果节点不是动作节点
+ */
+export declare function assertActionNode(node: NodeInstance): asserts node is ActionNodeInstance;
+/**
+ * 断言节点为分支节点
+ * @throws Error 如果节点不是分支节点
+ */
+export declare function assertBranchNode(node: NodeInstance): asserts node is BranchNodeInstance;
+//# sourceMappingURL=typeGuards.d.ts.map

package/dist/utils/typeGuards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typeGuards.d.ts","sourceRoot":"","sources":["../../src/utils/typeGuards.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,mBAAmB,CAAC;AAE3B;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,IAAI,oBAAoB,CAE/E;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,IAAI,kBAAkB,CAE3E;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,IAAI,kBAAkB,CAE3E;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,IAAI,oBAAoB,CAI3F;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,IAAI,kBAAkB,CAIvF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,IAAI,kBAAkB,CAIvF"}

package/dist/utils/typeGuards.js

@@ -0,0 +1,50 @@
+/**
+ * 类型守卫函数
+ * 用于替代类型断言，提高类型安全性
+ */
+/**
+ * 检查节点是否为思考节点
+ */
+export function isThinkingNode(node) {
+    return node.kind === 'thinking';
+}
+/**
+ * 检查节点是否为动作节点
+ */
+export function isActionNode(node) {
+    return node.kind === 'action';
+}
+/**
+ * 检查节点是否为分支节点
+ */
+export function isBranchNode(node) {
+    return node.kind === 'branch';
+}
+/**
+ * 断言节点为思考节点
+ * @throws Error 如果节点不是思考节点
+ */
+export function assertThinkingNode(node) {
+    if (!isThinkingNode(node)) {
+        throw new Error(`Expected thinking node, got ${node.kind}`);
+    }
+}
+/**
+ * 断言节点为动作节点
+ * @throws Error 如果节点不是动作节点
+ */
+export function assertActionNode(node) {
+    if (!isActionNode(node)) {
+        throw new Error(`Expected action node, got ${node.kind}`);
+    }
+}
+/**
+ * 断言节点为分支节点
+ * @throws Error 如果节点不是分支节点
+ */
+export function assertBranchNode(node) {
+    if (!isBranchNode(node)) {
+        throw new Error(`Expected branch node, got ${node.kind}`);
+    }
+}
+//# sourceMappingURL=typeGuards.js.map

package/dist/utils/typeGuards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typeGuards.js","sourceRoot":"","sources":["../../src/utils/typeGuards.ts"],"names":[],"mappings":"AAAA;;;GAGG;AASH;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,IAAkB;IAC/C,OAAO,IAAI,CAAC,IAAI,KAAK,UAAU,CAAC;AAClC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,IAAkB;IAC7C,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC;AAChC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,IAAkB;IAC7C,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC;AAChC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAkB;IACnD,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,+BAA+B,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAC9D,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAkB;IACjD,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,6BAA6B,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5D,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAkB;IACjD,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,6BAA6B,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5D,CAAC;AACH,CAAC"}

package/docs/add-llm-provider.md

@@ -0,0 +1,353 @@
+# 新增 LLM Provider 指南
+
+本文档介绍如何为 PersonaCore 添加新的 LLM 提供者支持。
+
+## 架构概述
+
+PersonaCore 使用 LLM 抽象层来支持多种 LLM 提供者：
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                     服务层 (Services)                    │
+│  DefaultThinkingService / DefaultActionService / ...    │
+└────────────────────────────┬────────────────────────────┘
+                             │
+┌────────────────────────────▼────────────────────────────┐
+│                    能力层 (Capabilities)                 │
+│  LLMPlanningCapability / LLMBranchDecisionCapability    │
+│  LLMContentGenerationCapability                         │
+└────────────────────────────┬────────────────────────────┘
+                             │
+┌────────────────────────────▼────────────────────────────┐
+│                 提供者层 (LLMProvider)                   │
+│  DeepSeekProvider / OpenAIProvider / ClaudeProvider     │
+└─────────────────────────────────────────────────────────┘
+```
+
+**你只需要实现 `LLMProvider` 接口**，系统会自动适配到所有服务。
+
+## 实现步骤
+
+### 1. 创建 Provider 文件
+
+在 `src/llm/providers/` 目录下创建新文件，如 `openai.ts`：
+
+```typescript
+import {
+  LLMProvider,
+  LLMMessage,
+  StructuredOutputConfig,
+  LLMCallOptions,
+} from '../interfaces.js';
+
+export interface OpenAIProviderConfig {
+  apiKey: string;
+  baseUrl?: string;
+  model?: string;
+  defaultTimeout?: number;
+}
+
+export class OpenAIProvider implements LLMProvider {
+  readonly name = 'openai';
+  
+  private config: Required<OpenAIProviderConfig>;
+  private endpoint: string;
+
+  constructor(config: OpenAIProviderConfig) {
+    this.config = {
+      apiKey: config.apiKey,
+      baseUrl: config.baseUrl ?? 'https://api.openai.com/v1',
+      model: config.model ?? 'gpt-4',
+      defaultTimeout: config.defaultTimeout ?? 60000,
+    };
+    this.endpoint = `${this.config.baseUrl}/chat/completions`;
+  }
+
+  // 实现 chat 方法
+  async chat(messages: LLMMessage[], options?: LLMCallOptions): Promise<string> {
+    // ... 实现 API 调用
+  }
+
+  // 实现 chatWithStructuredOutput 方法
+  async chatWithStructuredOutput<T>(
+    messages: LLMMessage[],
+    config: StructuredOutputConfig<T>,
+    options?: LLMCallOptions
+  ): Promise<T> {
+    // ... 实现结构化输出
+  }
+}
+```
+
+### 2. 实现 LLMProvider 接口
+
+`LLMProvider` 接口包含两个核心方法：
+
+#### `chat` - 基础对话
+
+```typescript
+async chat(messages: LLMMessage[], options?: LLMCallOptions): Promise<string>
+```
+
+- **messages**: 对话消息列表，每条消息包含 `role` (system/user/assistant) 和 `content`
+- **options**: 可选参数，包括 `temperature`、`maxTokens`、`timeout`
+- **返回**: 模型响应的文本内容
+
+**实现要点**：
+- 处理 API 调用超时
+- 抛出有意义的错误信息
+- 返回干净的响应文本
+
+#### `chatWithStructuredOutput` - 结构化输出
+
+```typescript
+async chatWithStructuredOutput<T>(
+  messages: LLMMessage[],
+  config: StructuredOutputConfig<T>,
+  options?: LLMCallOptions
+): Promise<T>
+```
+
+- **config.schema**: JSON Schema 描述字符串，告诉 LLM 期望的输出格式
+- **config.parser**: 可选的自定义解析函数
+- **返回**: 解析后的结构化对象
+
+**实现要点**：
+
+1. **增强提示词** - 在消息中添加 JSON 格式要求
+2. **提取 JSON** - 从响应中提取 JSON 内容（可能被 markdown 代码块包裹）
+3. **解析验证** - 解析 JSON 并返回
+
+示例实现：
+
+```typescript
+async chatWithStructuredOutput<T>(
+  messages: LLMMessage[],
+  config: StructuredOutputConfig<T>,
+  options?: LLMCallOptions
+): Promise<T> {
+  // 1. 增强最后一条消息，添加 JSON 格式要求
+  const enhancedMessages = [
+    ...messages.slice(0, -1),
+    {
+      role: messages[messages.length - 1].role,
+      content: `${messages[messages.length - 1].content}
+
+请严格按照以下 JSON 格式返回结果，不要包含任何其他内容：
+${config.schema}`,
+    } as LLMMessage,
+  ];
+
+  // 2. 调用基础 chat 方法
+  const content = await this.chat(enhancedMessages, options);
+  
+  // 3. 提取 JSON 内容
+  const jsonMatch = content.match(/```json\n?([\s\S]*?)\n?```/) ||
+                    content.match(/\{[\s\S]*\}/);
+  
+  if (!jsonMatch) {
+    throw new Error(`Failed to parse structured output: ${content}`);
+  }
+
+  const jsonStr = jsonMatch[1] || jsonMatch[0];
+  
+  // 4. 使用自定义解析器或默认 JSON.parse
+  if (config.parser) {
+    return config.parser(jsonStr);
+  }
+  
+  return JSON.parse(jsonStr);
+}
+```
+
+### 3. 导出 Provider
+
+在 `src/llm/providers/index.ts` 中添加导出：
+
+```typescript
+export { DeepSeekProvider } from './deepseek.js';
+export type { DeepSeekProviderConfig } from './deepseek.js';
+
+// 新增
+export { OpenAIProvider } from './openai.js';
+export type { OpenAIProviderConfig } from './openai.js';
+```
+
+## 使用新 Provider
+
+### 基础用法
+
+```typescript
+import { createServices } from 'persona-core';
+import { OpenAIProvider } from 'persona-core/llm/providers';
+
+const llmProvider = new OpenAIProvider({
+  apiKey: process.env.OPENAI_API_KEY!,
+  model: 'gpt-4-turbo',
+});
+
+const services = createServices({ llmProvider });
+
+// services.thinkingService、services.actionService、services.branchService
+// 都会使用 OpenAI 作为底层 LLM
+```
+
+### 混合使用多个 Provider
+
+可以为不同场景配置不同的 Provider：
+
+```typescript
+const services = createServices({
+  llmProvider: deepseekProvider,           // 默认 Provider
+  planningProvider: gpt4Provider,           // 规划专用（更强大的模型）
+  branchProvider: gpt35Provider,            // 分支决策（更快的模型）
+  contentProvider: claudeProvider,          // 内容生成（特定领域模型）
+});
+```
+
+## 完整示例：OpenAI Provider
+
+```typescript
+import {
+  LLMProvider,
+  LLMMessage,
+  StructuredOutputConfig,
+  LLMCallOptions,
+} from '../interfaces.js';
+
+export interface OpenAIProviderConfig {
+  apiKey: string;
+  baseUrl?: string;
+  model?: string;
+  defaultTimeout?: number;
+}
+
+export class OpenAIProvider implements LLMProvider {
+  readonly name = 'openai';
+  
+  private config: Required<OpenAIProviderConfig>;
+  private endpoint: string;
+
+  constructor(config: OpenAIProviderConfig) {
+    this.config = {
+      apiKey: config.apiKey,
+      baseUrl: config.baseUrl ?? 'https://api.openai.com/v1',
+      model: config.model ?? 'gpt-4',
+      defaultTimeout: config.defaultTimeout ?? 60000,
+    };
+    this.endpoint = `${this.config.baseUrl}/chat/completions`;
+  }
+
+  async chat(messages: LLMMessage[], options?: LLMCallOptions): Promise<string> {
+    const timeout = options?.timeout ?? this.config.defaultTimeout;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+    try {
+      const response = await fetch(this.endpoint, {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${this.config.apiKey}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          model: this.config.model,
+          messages: messages.map(m => ({ role: m.role, content: m.content })),
+          temperature: options?.temperature ?? 0.7,
+          max_tokens: options?.maxTokens,
+        }),
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`OpenAI API error: ${response.status} - ${error}`);
+      }
+
+      const data = await response.json() as {
+        choices: Array<{ message: { content: string } }>;
+      };
+      
+      return data.choices[0]?.message?.content ?? '';
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  async chatWithStructuredOutput<T>(
+    messages: LLMMessage[],
+    config: StructuredOutputConfig<T>,
+    options?: LLMCallOptions
+  ): Promise<T> {
+    const enhancedMessages = [
+      ...messages.slice(0, -1),
+      {
+        role: messages[messages.length - 1].role,
+        content: `${messages[messages.length - 1].content}
+
+请严格按照以下 JSON 格式返回结果，不要包含任何其他内容：
+${config.schema}`,
+      } as LLMMessage,
+    ];
+
+    const content = await this.chat(enhancedMessages, options);
+    
+    const jsonMatch = content.match(/```json\n?([\s\S]*?)\n?```/) ||
+                      content.match(/\{[\s\S]*\}/);
+    
+    if (!jsonMatch) {
+      throw new Error(`Failed to parse structured output: ${content}`);
+    }
+
+    const jsonStr = jsonMatch[1] || jsonMatch[0];
+    
+    if (config.parser) {
+      return config.parser(jsonStr);
+    }
+    
+    return JSON.parse(jsonStr);
+  }
+}
+```
+
+## 测试新 Provider
+
+建议编写单元测试验证：
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { OpenAIProvider } from './openai.js';
+
+describe('OpenAIProvider', () => {
+  const provider = new OpenAIProvider({
+    apiKey: process.env.OPENAI_API_KEY!,
+  });
+
+  it('should complete basic chat', async () => {
+    const response = await provider.chat([
+      { role: 'user', content: 'Say "hello" and nothing else.' }
+    ]);
+    
+    expect(response.toLowerCase()).toContain('hello');
+  });
+
+  it('should return structured output', async () => {
+    const result = await provider.chatWithStructuredOutput<{ name: string }>(
+      [{ role: 'user', content: 'Generate a random name' }],
+      { schema: '{ "name": "<人名>" }' }
+    );
+    
+    expect(result).toHaveProperty('name');
+    expect(typeof result.name).toBe('string');
+  });
+});
+```
+
+## 注意事项
+
+1. **错误处理**：确保 API 错误有清晰的错误信息
+2. **超时控制**：实现请求超时机制
+3. **速率限制**：考虑处理 API 速率限制（429 错误）
+4. **JSON 解析**：处理 LLM 可能返回不规范 JSON 的情况
+5. **流式响应**：当前接口不支持流式响应，如需支持可扩展接口
+

package/docs/external/deepseek-v32.md

@@ -0,0 +1,28 @@
+curl 调用例子：
+
+```
+curl --location 'https://ark.cn-beijing.volces.com/api/v3/responses' \
+--header "Authorization: Bearer 30f13e3e-f7d0-41da-acc2-ecc8cd65a776" \
+--header 'Content-Type: application/json' \
+--data '{
+    "model": "deepseek-v3-2-251201",
+    "stream": true,
+    "tools": [
+        {
+            "type": "web_search",
+            "max_keyword": 3
+        }
+    ],
+    "input": [
+        {
+            "role": "user",
+            "content": [
+                {
+                    "type": "input_text",
+                    "text": "今天有什么热点新闻"
+                }
+            ]
+        }
+    ]
+}'
+```