@huyooo/ai-chat-core 0.1.6 → 0.1.7

package/README.md

@@ -0,0 +1,423 @@
+# @huyooo/ai-chat-core
+
+AI Chat 核心库 - 支持多模型的 Agent 框架，可插拔的工具系统。
+
+> 📖 **深入了解**：查看 [技术架构文档](../../ARCHITECTURE.md) 了解流式事件、工具调用、历史管理等核心原理。
+
+## 特性
+
+- 🤖 **多模型支持**：ARK (豆包/DeepSeek)、通义千问、Gemini、OpenRouter (Claude)
+- 🔧 **可插拔工具系统**：内置工具 + 自定义工具，完全由用户控制
+- 🔄 **Provider 模式**：统一的模型接口，易于扩展
+- 📡 **流式响应**：支持思考、搜索、工具调用等事件流
+
+## 架构
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                      HybridAgent                        │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐  │
+│  │   Router    │  │   Tools     │  │   Stateless     │  │
+│  │ (模型路由)   │  │ (工具注册)   │  │ (完全无状态)     │  │
+│  └─────────────┘  └─────────────┘  └─────────────────┘  │
+└─────────────────────────┬───────────────────────────────┘
+                          │
+          ┌───────────────┼───────────────┐
+          ▼               ▼               ▼
+    ┌──────────┐   ┌──────────┐   ┌──────────┐
+    │   ARK    │   │  Qwen    │   │ Gemini   │  ...
+    │ Provider │   │ Provider │   │ Provider │
+    └──────────┘   └──────────┘   └──────────┘
+```
+
+## 安装
+
+```bash
+npm install @huyooo/ai-chat-core
+```
+
+## 快速开始
+
+```typescript
+import { HybridAgent } from '@huyooo/ai-chat-core';
+import {
+  getWorkingDirTool,
+  executeCommandTool,
+  analyzeImageTool,
+  generateImageTool,
+  analyzeVideoTool
+} from '@huyooo/ai-chat-core';
+
+// 创建 Agent
+const agent = new HybridAgent({
+  arkApiKey: 'your-ark-api-key',
+  geminiApiKey: 'your-gemini-api-key',
+  // 注入工具（必须手动注入，不传则无工具）
+  tools: [
+    getWorkingDirTool,
+    executeCommandTool,
+    analyzeImageTool,
+  ],
+});
+
+// 发送消息
+for await (const event of agent.chat('列出当前目录的文件')) {
+  switch (event.type) {
+    case 'text_delta':
+      process.stdout.write(event.data.content);
+      break;
+    case 'tool_call_start':
+      console.log(`\n调用工具: ${event.data.name}`);
+      break;
+    case 'done':
+      console.log('\n完成');
+      break;
+  }
+}
+```
+
+## 工具系统
+
+### 内置工具
+
+| 工具 | 描述 | 依赖 |
+|------|------|------|
+| `getWorkingDirTool` | 获取当前工作目录 | - |
+| `getPlatformTool` | 获取操作系统平台信息 | - |
+| `executeCommandTool` | 执行 shell 命令 | - |
+| `analyzeImageTool` | 分析图片内容 | Gemini |
+| `generateImageTool` | 生成图片 | Gemini |
+| `analyzeVideoTool` | 分析视频内容 | Gemini |
+| `getWeatherTool` | 查询中国城市天气 | 高德 API (内置 Key) |
+
+### 按需注入
+
+```typescript
+// 只使用部分工具
+import {
+  getWorkingDirTool,
+  getPlatformTool,
+  executeCommandTool,
+  getWeatherTool
+} from '@huyooo/ai-chat-core';
+
+const agent = new HybridAgent({
+  ...config,
+  tools: [
+    getWorkingDirTool,
+    getPlatformTool,
+    executeCommandTool,
+    getWeatherTool,  // 天气查询（支持中国 337 个城市）
+  ],
+});
+```
+
+### 天气工具说明
+
+`getWeatherTool` 使用高德天气 API，支持查询中国 337 个主要城市的实时天气：
+
+```typescript
+// 工具参数
+{
+  city: string  // 城市名称，如 "北京"、"上海"、"深圳"
+}
+
+// 返回结构
+{
+  city: string        // 城市名
+  temperature: number // 温度 (°C)
+  condition: string   // 天气状况 (晴/多云/雨等)
+  humidity: number    // 湿度 (%)
+  wind: string        // 风向风力 (如 "西北风 ≤3级")
+}
+```
+
+支持的城市包括：所有省会城市、直辖市、地级市等。
+
+### 自定义工具
+
+```typescript
+import type { Tool } from '@huyooo/ai-chat-core';
+
+const myTool: Tool = {
+  name: 'my_tool',
+  description: '我的自定义工具',
+  parameters: {
+    type: 'object',
+    properties: {
+      input: { type: 'string', description: '输入参数' }
+    },
+    required: ['input']
+  },
+  execute: async (args, context) => {
+    // context.workingDir - 当前工作目录
+    // context.executeCommand - 执行 shell 命令
+    // context.geminiClient - Gemini 客户端（可选）
+    // context.signal - 取消信号（AbortSignal）
+    return `处理结果: ${args.input}`;
+  }
+};
+
+const agent = new HybridAgent({
+  ...config,
+  tools: [getWorkingDirTool, executeCommandTool, myTool],
+});
+```
+
+## 取消功能
+
+### 取消请求
+
+调用 `agent.abort()` 可以中断当前正在进行的请求：
+
+```typescript
+// 开始请求
+const chatGenerator = agent.chat('生成一张图片');
+
+// 用户点击取消按钮
+cancelButton.onclick = () => {
+  agent.abort();  // 中断请求
+};
+
+// 处理事件
+for await (const event of chatGenerator) {
+  if (event.type === 'abort') {
+    console.log('请求已取消');
+    break;
+  }
+  // 处理其他事件...
+}
+```
+
+### 取消架构
+
+取消信号 (`AbortSignal`) 从 Agent 层层传递到工具执行：
+
+```
+┌─────────────┐    abort()    ┌─────────────┐    signal    ┌─────────────┐
+│    Agent    │ ───────────►  │ Orchestrator│ ───────────► │    Tool     │
+│ AbortCtrl   │               │ 检查 aborted │              │context.signal
+└─────────────┘               └─────────────┘              └─────────────┘
+                                                                  │
+                                                                  ▼
+                                                           ┌─────────────┐
+                                                           │  fetch/API  │
+                                                           │ abortSignal │
+                                                           └─────────────┘
+```
+
+### 自定义工具支持取消
+
+如果你的工具包含**耗时操作**（如网络请求、文件读写），建议支持取消：
+
+```typescript
+const myAsyncTool: Tool = {
+  name: 'my_async_tool',
+  description: '一个耗时的异步工具',
+  parameters: { /* ... */ },
+  execute: async (args, context) => {
+    // 1. 执行前检查是否已取消
+    if (context.signal?.aborted) {
+      return '操作已取消';
+    }
+    
+    // 2. 网络请求：传递 signal 给 fetch
+    const response = await fetch('https://api.example.com/data', {
+      signal: context.signal,  // fetch 原生支持 AbortSignal
+    });
+    
+    // 3. 自定义异步操作：监听 abort 事件
+    const result = await new Promise((resolve, reject) => {
+      const abortHandler = () => {
+        reject(new Error('操作已取消'));
+      };
+      context.signal?.addEventListener('abort', abortHandler);
+      
+      // 执行异步操作...
+      doSomethingAsync().then((data) => {
+        context.signal?.removeEventListener('abort', abortHandler);
+        resolve(data);
+      });
+    });
+    
+    return result;
+  }
+};
+```
+
+### 内置工具取消支持
+
+| 工具 | 取消方式 | 说明 |
+|------|----------|------|
+| `executeCommandTool` | `spawn` + `kill` | 终止子进程 |
+| `analyzeImageTool` | Gemini `abortSignal` | 中断 API 请求 |
+| `generateImageTool` | Gemini `abortSignal` | 中断 API 请求 |
+| `analyzeVideoTool` | Gemini `abortSignal` | 中断 API 请求 |
+| `getWeatherTool` | `fetch` signal | 中断 HTTP 请求 |
+| `getWorkingDirTool` | - | 瞬时操作，无需取消 |
+| `getPlatformTool` | - | 瞬时操作，无需取消 |
+
+### 何时需要支持取消
+
+| 操作类型 | 是否需要支持取消 |
+|----------|-----------------|
+| 网络请求 | ✅ 是 |
+| Shell 命令执行 | ✅ 是 |
+| 大文件读写 | ✅ 是 |
+| 长时间计算 | ✅ 是 |
+| 返回内存变量 | ❌ 否（< 1ms） |
+| 简单字符串操作 | ❌ 否（< 1ms） |
+
+## 配置
+
+```typescript
+interface AgentConfig {
+  // API Keys
+  arkApiKey: string;           // 豆包/DeepSeek (火山引擎)
+  qwenApiKey?: string;         // 通义千问
+  geminiApiKey: string;        // Gemini (图片/视频分析)
+  openrouterApiKey?: string;   // OpenRouter (Claude 等)
+  
+  // 可选配置
+  arkApiUrl?: string;
+  qwenApiUrl?: string;
+  openrouterApiUrl?: string;
+  workingDir?: string;
+  
+  // 工具（必须手动注入）
+  tools?: Tool[];
+}
+```
+
+## 聊天选项
+
+```typescript
+/** 聊天历史消息（无状态架构） */
+interface ChatHistoryMessage {
+  role: 'user' | 'assistant' | 'system' | 'tool';
+  content: string;
+}
+
+interface ChatOptions {
+  mode?: 'agent' | 'plan' | 'ask';  // 对话模式
+  model?: string;                    // 模型 ID
+  enableWebSearch?: boolean;         // 联网搜索
+  thinkingMode?: 'enabled' | 'disabled';  // 深度思考
+  autoRunConfig?: AutoRunConfig;     // 自动运行配置
+  history?: ChatHistoryMessage[];    // 对话历史（无状态架构）
+}
+
+// 自动运行配置
+interface AutoRunConfig {
+  mode?: 'run-everything' | 'manual';  // 自动运行模式
+}
+
+// 示例：带历史的对话
+const history = [
+  { role: 'user', content: '你好' },
+  { role: 'assistant', content: '你好！有什么可以帮助你的？' },
+];
+
+for await (const event of agent.chat('继续上次的话题', {
+  mode: 'agent',
+  model: 'doubao-seed-1-6-251015',
+  enableWebSearch: true,
+  thinkingMode: 'enabled',
+  history,  // ← 传入历史，后端无状态
+  autoRunConfig: {
+    mode: 'run-everything',
+  },
+})) {
+  // 处理事件
+}
+```
+
+### 自动运行配置说明
+
+`autoRunConfig` 用于控制 Agent 的工具执行行为和安全保护：
+
+- **mode**: 自动运行模式
+  - `'run-everything'`: 运行所有内容（自动执行）
+  - `'manual'`: 手动批准模式（每次执行前询问）
+
+## 事件类型
+
+```typescript
+// 思考事件
+'thinking_start' | 'thinking_delta' | 'thinking_end'
+
+// 搜索事件
+'search_start' | 'search_result'
+
+// 工具事件
+'tool_call_start' | 'tool_call_result'
+
+// 文本事件
+'text_delta'
+
+// 状态事件
+'done' | 'error' | 'abort'
+```
+
+## 支持的模型
+
+### 原生模型
+
+| 模型 ID | 显示名称 | Provider |
+|---------|----------|----------|
+| `doubao-seed-1-6-251015` | 豆包 Seed 1.6 | ARK |
+| `deepseek-v3-1-terminus` | DeepSeek V3 | ARK |
+| `qwen3-max-preview` | 通义千问 Max | Qwen |
+| `gemini-3-pro-preview` | Gemini 3 Pro | Gemini |
+
+### OpenRouter 模型
+
+| 模型 ID | 显示名称 |
+|---------|----------|
+| `openai/gpt-5.2` | GPT-5.2 |
+| `anthropic/claude-opus-4.5` | Claude Opus 4.5 |
+| `google/gemini-3-pro-preview` | Gemini 3 Pro |
+
+## API
+
+### HybridAgent
+
+```typescript
+class HybridAgent {
+  constructor(config: AgentConfig);
+  
+  // 聊天（无状态，历史通过 options.history 传入）
+  chat(message: string, options?: ChatOptions, images?: string[]): AsyncGenerator<ChatEvent>;
+  
+  // 控制
+  abort(): void;                    // 取消当前请求
+  setWorkingDir(dir: string): void; // 设置工作目录
+  
+  // 查询
+  getConfig(): RuntimeConfig;
+  getModelCapabilities(model: string): ModelCapabilities;
+  getSupportedModels(): ModelOption[];
+}
+```
+
+### 无状态架构说明
+
+Agent 采用**完全无状态**设计：
+
+- ❌ 不维护对话历史（无 `conversationHistory`）
+- ❌ 无 `clearHistory()` / `getHistory()` / `setHistory()` 方法
+- ✅ 历史通过 `ChatOptions.history` 参数传入
+- ✅ 每次请求独立处理，可水平扩展
+
+```typescript
+// 正确用法：前端负责管理历史
+const history = loadFromDatabase(sessionId);
+for await (const event of agent.chat('问题', { history })) {
+  // ...
+}
+saveToDatabase(sessionId, newMessage);
+```
+
+## License
+
+MIT