ai-agent-router 0.1.8 → 0.1.9

package/.claude/settings.local.json

@@ -0,0 +1,24 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(find:*)",
+      "Bash(npx tsc:*)",
+      "Bash(npm run build)",
+      "Bash(timeout 3 npm run start:*)",
+      "Bash(node:*)",
+      "Bash(curl:*)",
+      "Bash(npm install:*)",
+      "Bash(chmod:*)",
+      "Bash(npx typescript:*)",
+      "Bash(lsof:*)",
+      "Bash(xargs kill:*)",
+      "Skill(ui-ux-pro-max)",
+      "Bash(python3:*)",
+      "Bash(git diff:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "WebFetch(domain:heroicons.com)",
+      "WebSearch"
+    ]
+  }
+}

package/dist/.next/types/app/api/config/route.js

@@ -1,4 +1,4 @@
-// File: /Users/plucky/own/ai-agent-router/src/app/api/config/route.ts
+// File: /Users/pluckypan/own/AI/ai-agent-router/src/app/api/config/route.ts
 import * as entry from '../../../../../src/app/api/config/route.js';
 // Check that the entry is a valid entry
 checkFields();

package/dist/.next/types/app/api/gateway/[...path]/route.js

@@ -1,4 +1,4 @@
-// File: /Users/plucky/own/ai-agent-router/src/app/api/gateway/[...path]/route.ts
+// File: /Users/pluckypan/own/AI/ai-agent-router/src/app/api/gateway/[...path]/route.ts
 import * as entry from '../../../../../../src/app/api/gateway/[...path]/route.js';
 // Check that the entry is a valid entry
 checkFields();

package/dist/.next/types/app/api/gateway/route.js

@@ -1,4 +1,4 @@
-// File: /Users/plucky/own/ai-agent-router/src/app/api/gateway/route.ts
+// File: /Users/pluckypan/own/AI/ai-agent-router/src/app/api/gateway/route.ts
 import * as entry from '../../../../../src/app/api/gateway/route.js';
 // Check that the entry is a valid entry
 checkFields();

package/dist/.next/types/app/api/ide/claude/apply/route.js

@@ -1,4 +1,4 @@
-// File: /Users/plucky/own/ai-agent-router/src/app/api/ide/claude/apply/route.ts
+// File: /Users/pluckypan/own/AI/ai-agent-router/src/app/api/ide/claude/apply/route.ts
 import * as entry from '../../../../../../../src/app/api/ide/claude/apply/route.js';
 // Check that the entry is a valid entry
 checkFields();

package/dist/.next/types/app/api/ide/claude/available-models/route.js

@@ -1,4 +1,4 @@
-// File: /Users/plucky/own/ai-agent-router/src/app/api/ide/claude/available-models/route.ts
+// File: /Users/pluckypan/own/AI/ai-agent-router/src/app/api/ide/claude/available-models/route.ts
 import * as entry from '../../../../../../../src/app/api/ide/claude/available-models/route.js';
 // Check that the entry is a valid entry
 checkFields();

package/dist/.next/types/app/api/ide/claude/restore/route.js

@@ -1,4 +1,4 @@
-// File: /Users/plucky/own/ai-agent-router/src/app/api/ide/claude/restore/route.ts
+// File: /Users/pluckypan/own/AI/ai-agent-router/src/app/api/ide/claude/restore/route.ts
 import * as entry from '../../../../../../../src/app/api/ide/claude/restore/route.js';
 // Check that the entry is a valid entry
 checkFields();

package/dist/.next/types/app/api/ide/claude/save/route.js

@@ -0,0 +1,52 @@
+// File: /Users/pluckypan/own/AI/ai-agent-router/src/app/api/ide/claude/save/route.ts
+import * as entry from '../../../../../../../src/app/api/ide/claude/save/route.js';
+// Check that the entry is a valid entry
+checkFields();
+// Check the prop type of the entry function
+if ('GET' in entry) {
+    checkFields();
+    checkFields();
+    checkFields();
+}
+// Check the prop type of the entry function
+if ('HEAD' in entry) {
+    checkFields();
+    checkFields();
+    checkFields();
+}
+// Check the prop type of the entry function
+if ('OPTIONS' in entry) {
+    checkFields();
+    checkFields();
+    checkFields();
+}
+// Check the prop type of the entry function
+if ('POST' in entry) {
+    checkFields();
+    checkFields();
+    checkFields();
+}
+// Check the prop type of the entry function
+if ('PUT' in entry) {
+    checkFields();
+    checkFields();
+    checkFields();
+}
+// Check the prop type of the entry function
+if ('DELETE' in entry) {
+    checkFields();
+    checkFields();
+    checkFields();
+}
+// Check the prop type of the entry function
+if ('PATCH' in entry) {
+    checkFields();
+    checkFields();
+    checkFields();
+}
+// Check the arguments and return type of the generateStaticParams function
+if ('generateStaticParams' in entry) {
+    checkFields();
+    checkFields();
+}
+function checkFields() { }

package/dist/.next/types/app/api/ide/claude/status/route.js

@@ -1,4 +1,4 @@
-// File: /Users/plucky/own/ai-agent-router/src/app/api/ide/claude/status/route.ts
+// File: /Users/pluckypan/own/AI/ai-agent-router/src/app/api/ide/claude/status/route.ts
 import * as entry from '../../../../../../../src/app/api/ide/claude/status/route.js';
 // Check that the entry is a valid entry
 checkFields();

package/dist/.next/types/app/api/ide/claude/test/route.js

@@ -1,4 +1,4 @@
-// File: /Users/plucky/own/ai-agent-router/src/app/api/ide/claude/test/route.ts
+// File: /Users/pluckypan/own/AI/ai-agent-router/src/app/api/ide/claude/test/route.ts
 import * as entry from '../../../../../../../src/app/api/ide/claude/test/route.js';
 // Check that the entry is a valid entry
 checkFields();

package/dist/.next/types/app/api/logs/route.js

@@ -1,4 +1,4 @@
-// File: /Users/plucky/own/ai-agent-router/src/app/api/logs/route.ts
+// File: /Users/pluckypan/own/AI/ai-agent-router/src/app/api/logs/route.ts
 import * as entry from '../../../../../src/app/api/logs/route.js';
 // Check that the entry is a valid entry
 checkFields();

package/dist/.next/types/app/api/models/route.js

@@ -1,4 +1,4 @@
-// File: /Users/plucky/own/ai-agent-router/src/app/api/models/route.ts
+// File: /Users/pluckypan/own/AI/ai-agent-router/src/app/api/models/route.ts
 import * as entry from '../../../../../src/app/api/models/route.js';
 // Check that the entry is a valid entry
 checkFields();

package/dist/.next/types/app/api/providers/route.js

@@ -1,4 +1,4 @@
-// File: /Users/plucky/own/ai-agent-router/src/app/api/providers/route.ts
+// File: /Users/pluckypan/own/AI/ai-agent-router/src/app/api/providers/route.ts
 import * as entry from '../../../../../src/app/api/providers/route.js';
 // Check that the entry is a valid entry
 checkFields();

package/dist/.next/types/app/api/providers/test/route.js

@@ -1,4 +1,4 @@
-// File: /Users/plucky/own/ai-agent-router/src/app/api/providers/test/route.ts
+// File: /Users/pluckypan/own/AI/ai-agent-router/src/app/api/providers/test/route.ts
 import * as entry from '../../../../../../src/app/api/providers/test/route.js';
 // Check that the entry is a valid entry
 checkFields();

package/dist/.next/types/app/api/service/force-stop/route.js

@@ -0,0 +1,52 @@
+// File: /Users/pluckypan/own/AI/ai-agent-router/src/app/api/service/force-stop/route.ts
+import * as entry from '../../../../../../src/app/api/service/force-stop/route.js';
+// Check that the entry is a valid entry
+checkFields();
+// Check the prop type of the entry function
+if ('GET' in entry) {
+    checkFields();
+    checkFields();
+    checkFields();
+}
+// Check the prop type of the entry function
+if ('HEAD' in entry) {
+    checkFields();
+    checkFields();
+    checkFields();
+}
+// Check the prop type of the entry function
+if ('OPTIONS' in entry) {
+    checkFields();
+    checkFields();
+    checkFields();
+}
+// Check the prop type of the entry function
+if ('POST' in entry) {
+    checkFields();
+    checkFields();
+    checkFields();
+}
+// Check the prop type of the entry function
+if ('PUT' in entry) {
+    checkFields();
+    checkFields();
+    checkFields();
+}
+// Check the prop type of the entry function
+if ('DELETE' in entry) {
+    checkFields();
+    checkFields();
+    checkFields();
+}
+// Check the prop type of the entry function
+if ('PATCH' in entry) {
+    checkFields();
+    checkFields();
+    checkFields();
+}
+// Check the arguments and return type of the generateStaticParams function
+if ('generateStaticParams' in entry) {
+    checkFields();
+    checkFields();
+}
+function checkFields() { }

package/dist/.next/types/app/api/service/start/route.js

@@ -1,4 +1,4 @@
-// File: /Users/plucky/own/ai-agent-router/src/app/api/service/start/route.ts
+// File: /Users/pluckypan/own/AI/ai-agent-router/src/app/api/service/start/route.ts
 import * as entry from '../../../../../../src/app/api/service/start/route.js';
 // Check that the entry is a valid entry
 checkFields();

package/dist/.next/types/app/api/service/status/route.js

@@ -1,4 +1,4 @@
-// File: /Users/plucky/own/ai-agent-router/src/app/api/service/status/route.ts
+// File: /Users/pluckypan/own/AI/ai-agent-router/src/app/api/service/status/route.ts
 import * as entry from '../../../../../../src/app/api/service/status/route.js';
 // Check that the entry is a valid entry
 checkFields();

package/dist/.next/types/app/api/service/stop/route.js

@@ -1,4 +1,4 @@
-// File: /Users/plucky/own/ai-agent-router/src/app/api/service/stop/route.ts
+// File: /Users/pluckypan/own/AI/ai-agent-router/src/app/api/service/stop/route.ts
 import * as entry from '../../../../../../src/app/api/service/stop/route.js';
 // Check that the entry is a valid entry
 checkFields();

package/dist/.next/types/app/ide/page.js

@@ -1,4 +1,4 @@
-// File: /Users/plucky/own/ai-agent-router/src/app/ide/page.tsx
+// File: /Users/pluckypan/own/AI/ai-agent-router/src/app/ide/page.tsx
 import * as entry from '../../../../src/app/ide/page.js';
 // Check that the entry is a valid entry
 checkFields();

package/dist/.next/types/app/layout.js

@@ -1,4 +1,4 @@
-// File: /Users/plucky/own/ai-agent-router/src/app/layout.tsx
+// File: /Users/pluckypan/own/AI/ai-agent-router/src/app/layout.tsx
 import * as entry from '../../../src/app/layout.js';
 // Check that the entry is a valid entry
 checkFields();

package/dist/.next/types/app/logs/page.js

@@ -1,4 +1,4 @@
-// File: /Users/plucky/own/ai-agent-router/src/app/logs/page.tsx
+// File: /Users/pluckypan/own/AI/ai-agent-router/src/app/logs/page.tsx
 import * as entry from '../../../../src/app/logs/page.js';
 // Check that the entry is a valid entry
 checkFields();

package/dist/.next/types/app/models/page.js

@@ -1,4 +1,4 @@
-// File: /Users/plucky/own/ai-agent-router/src/app/models/page.tsx
+// File: /Users/pluckypan/own/AI/ai-agent-router/src/app/models/page.tsx
 import * as entry from '../../../../src/app/models/page.js';
 // Check that the entry is a valid entry
 checkFields();

package/dist/.next/types/app/page.js

@@ -1,4 +1,4 @@
-// File: /Users/plucky/own/ai-agent-router/src/app/page.tsx
+// File: /Users/pluckypan/own/AI/ai-agent-router/src/app/page.tsx
 import * as entry from '../../../src/app/page.js';
 // Check that the entry is a valid entry
 checkFields();

package/dist/.next/types/app/providers/page.js

@@ -1,4 +1,4 @@
-// File: /Users/plucky/own/ai-agent-router/src/app/providers/page.tsx
+// File: /Users/pluckypan/own/AI/ai-agent-router/src/app/providers/page.tsx
 import * as entry from '../../../../src/app/providers/page.js';
 // Check that the entry is a valid entry
 checkFields();

package/dist/docs/SDK_INTEGRATION.md

@@ -0,0 +1,357 @@
+# Claude SDK 集成指南
+
+本文档介绍如何使用官方 `@anthropic-ai/sdk` 连接到 AI Agent Router 网关。
+
+## 核心概念
+
+AI Agent Router 网关提供了统一的 API 入口，支持多种 AI 模型供应商。使用 Claude SDK 连接到网关时，您只需要：
+
+1. **配置网关地址**：将 SDK 的 `baseURL` 指向网关地址（如 `http://localhost:1357`）
+2. **提供网关 API Key**：使用网关的 API Key 进行认证
+3. **指定模型 ID**：使用在网关中配置的模型 ID
+
+## 快速开始
+
+### 1. 启动网关
+
+```bash
+aar start --port 1357
+```
+
+### 2. 配置供应商和模型
+
+访问 `http://localhost:9527` 并配置：
+- 添加 Anthropic 供应商
+- 添加模型（如 `claude-3-5-sonnet-20241022`）
+
+### 3. 使用 SDK 连接
+
+```typescript
+import { createAnthropicClient, sendMessage } from '@ai-agent-router/sdk';
+
+const client = createAnthropicClient({
+  gatewayUrl: 'http://localhost:1357',
+  apiKey: 'your-gateway-api-key',
+});
+
+const response = await sendMessage(client, {
+  model: 'claude-3-5-sonnet-20241022',
+  max_tokens: 1024,
+  messages: [{ role: 'user', content: 'Hello!' }],
+});
+
+console.log(response.content);
+```
+
+## API 参考
+
+### `createAnthropicClient(config)`
+
+创建 Claude SDK 客户端实例。
+
+#### 参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|----------|------|
+| `gatewayUrl` | `string` | 否 | `http://localhost:1357` | 网关基础 URL |
+| `apiKey` | `string` | 是 | - | 网关 API Key |
+| `timeout` | `number` | 否 | `60000` | 请求超时时间（毫秒） |
+| `maxRetries` | `number` | 否 | `3` | 最大重试次数 |
+| `enableLogging` | `boolean` | 否 | `false` | 启用详细日志 |
+
+#### 返回值
+
+返回一个标准的 `Anthropic` SDK 实例。
+
+### `sendMessage(client, params)`
+
+发送非流式消息。
+
+#### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `client` | `Anthropic` | 是 | SDK 客户端实例 |
+| `params` | `MessageCreateParamsNonStreaming` | 是 | 消息参数（不包括 `stream: true`） |
+
+#### 返回值
+
+返回 `Promise<Message>`。
+
+### `sendMessageStream(client, params)`
+
+发送流式消息。
+
+#### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `client` | `Anthropic` | 是 | SDK 客户端实例 |
+| `params` | `MessageCreateParamsStreaming` | 是 | 消息参数（包括 `stream: true`） |
+
+#### 返回值
+
+返回 `Promise<AsyncIterable<MessageStreamEvent>>`。
+
+## 使用示例
+
+### 基础对话
+
+```typescript
+import { createAnthropicClient } from '@ai-agent-router/sdk';
+
+const client = createAnthropicClient({
+  gatewayUrl: 'http://localhost:1357',
+  apiKey: process.env.GATEWAY_API_KEY,
+});
+
+const response = await client.messages.create({
+  model: 'claude-3-5-sonnet-20241022',
+  max_tokens: 1024,
+  messages: [{ role: 'user', content: 'What is 2+2?' }],
+});
+
+console.log(response.content[0].text);
+```
+
+### 多轮对话
+
+```typescript
+const response = await client.messages.create({
+  model: 'claude-3-5-sonnet-20241022',
+  max_tokens: 1024,
+  messages: [
+    { role: 'user', content: 'My name is Alice' },
+    { role: 'assistant', content: 'Hello Alice!' },
+    { role: 'user', content: 'What is my name?' },
+  ],
+});
+
+console.log(response.content[0].text);
+```
+
+### 流式响应
+
+```typescript
+const stream = await client.messages.create({
+  model: 'claude-3-5-sonnet-20241022',
+  max_tokens: 1024,
+  stream: true,
+  messages: [{ role: 'user', content: 'Count to 10' }],
+});
+
+for await (const chunk of stream) {
+  if (chunk.type === 'content_block_delta') {
+    if (chunk.delta.type === 'text_delta') {
+      process.stdout.write(chunk.delta.text || '');
+    }
+  }
+}
+```
+
+### 错误处理
+
+```typescript
+try {
+  const response = await client.messages.create({
+    model: 'claude-3-5-sonnet-20241022',
+    max_tokens: 1024,
+    messages: [{ role: 'user', content: 'Hello' }],
+  });
+} catch (error) {
+  if (error instanceof Anthropic.APIError) {
+    console.error('API 错误:', {
+      status: error.status,
+      message: error.message,
+    });
+  } else if (error instanceof Anthropic.APIConnectionError) {
+    console.error('连接错误:', error.message);
+  } else {
+    console.error('未知错误:', error);
+  }
+}
+```
+
+### 启用日志
+
+```typescript
+const client = createAnthropicClient({
+  gatewayUrl: 'http://localhost:1357',
+  apiKey: 'your-gateway-api-key',
+  enableLogging: true,
+});
+```
+
+## 运行示例
+
+项目包含多个示例脚本，可以直接运行：
+
+```bash
+# 运行测试套件
+npm run test:sdk
+
+# 运行使用示例
+npm run example:sdk
+```
+
+## 工作原理
+
+### 网关请求流程
+
+1. **客户端请求**：SDK 发送请求到网关，携带网关 API Key
+2. **自定义 Fetch**：SDK 的自定义 `fetch` 函数注入正确的认证头
+3. **网关路由**：网关根据模型 ID 自动路由到对应的供应商
+4. **供应商转发**：网关解密供应商 API Key 并转发请求
+5. **响应返回**：响应通过网关返回给 SDK
+
+### 认证头
+
+SDK 的自定义 `fetch` 函数会自动添加以下头：
+
+```typescript
+{
+  'Authorization': 'Bearer {gateway-api-key}',
+  'x-api-key': '{gateway-api-key}',
+  'Content-Type': 'application/json',
+}
+```
+
+### URL 重写
+
+自定义 `fetch` 函数会智能处理 URL：
+
+- 如果 URL 已经是完整的 HTTP/HTTPS 地址，直接使用
+- 否则，自动添加网关基础 URL
+
+## 最佳实践
+
+### 1. 环境变量配置
+
+```bash
+# .env 文件
+GATEWAY_URL=http://localhost:1357
+GATEWAY_API_KEY=your-gateway-api-key
+```
+
+```typescript
+const client = createAnthropicClient({
+  gatewayUrl: process.env.GATEWAY_URL,
+  apiKey: process.env.GATEWAY_API_KEY,
+});
+```
+
+### 2. 重试和超时
+
+```typescript
+const client = createAnthropicClient({
+  gatewayUrl: 'http://localhost:1357',
+  apiKey: 'your-gateway-api-key',
+  timeout: 120000,      // 2 分钟超时
+  maxRetries: 5,          // 最多重试 5 次
+});
+```
+
+### 3. 使用流式响应
+
+对于较长的响应，建议使用流式响应以获得更好的用户体验：
+
+```typescript
+const stream = await client.messages.create({
+  model: 'claude-3-5-sonnet-20241022',
+  max_tokens: 4096,
+  stream: true,
+  messages: [{ role: 'user', content: 'Write a long story...' }],
+});
+```
+
+### 4. Token 计数
+
+响应包含 `usage` 字段，显示 token 使用情况：
+
+```typescript
+const response = await client.messages.create({ ... });
+
+console.log('Input tokens:', response.usage.input_tokens);
+console.log('Output tokens:', response.usage.output_tokens);
+console.log('Total tokens:', response.usage.input_tokens + response.usage.output_tokens);
+```
+
+## 故障排查
+
+### 问题 1: 连接被拒绝
+
+**症状**：收到 401 或 403 错误
+
+**解决方案**：
+- 检查网关 API Key 是否正确
+- 确认网关服务是否正在运行
+- 检查网关配置是否允许 API Key 访问
+
+### 问题 2: 模型未找到
+
+**症状**：收到 404 错误，提示 "Model not found"
+
+**解决方案**：
+- 确认模型 ID 是否在网关中配置
+- 检查模型是否已启用
+- 查看网关日志了解详细错误
+
+### 问题 3: 请求超时
+
+**症状**：收到 "Request timeout" 错误
+
+**解决方案**：
+- 增加 `timeout` 配置
+- 检查网络连接
+- 尝试使用流式响应
+
+### 问题 4: 网关连接失败
+
+**症状**：收到 "Connection refused" 错误
+
+**解决方案**：
+- 确认网关服务是否正在运行
+- 检查网关地址和端口
+- 检查防火墙设置
+
+## 高级用法
+
+### 多供应商切换
+
+网关支持自动路由，也可以手动指定供应商：
+
+```typescript
+// 方法 1：使用不同模型 ID（自动路由）
+await client.messages.create({
+  model: 'claude-3-5-sonnet-20241022',  // Anthropic 模型
+  ...
+});
+
+await client.messages.create({
+  model: 'gpt-4',  // OpenAI 模型
+  ...
+});
+
+// 方法 2：在 URL 中指定供应商（需要自定义 fetch）
+// 注意：需要修改 SDK 以支持 ?provider= 查询参数
+```
+
+### 使用多个客户端实例
+
+```typescript
+const client1 = createAnthropicClient({
+  gatewayUrl: 'http://gateway1.example.com:1357',
+  apiKey: 'key1',
+});
+
+const client2 = createAnthropicClient({
+  gatewayUrl: 'http://gateway2.example.com:1357',
+  apiKey: 'key2',
+});
+```
+
+## 相关文档
+
+- [主 README](../README.md)
+- [API 端点](../docs/api-endpoints.md)
+- [供应商配置](../docs/providers.md)