ai-world-sdk 1.2.7 → 1.3.2

package/skills/ai-world-sdk/docs/agent-skills.md

@@ -0,0 +1,78 @@
+# Agent Skills 管理
+
+通过 `AgentSkillClient` 上传、下载、删除、列出 Agent Skills。Skills 存储在后端文件系统 `backend/skills/` 目录。
+
+## 基本用法
+
+```typescript
+import { AgentSkillClient } from 'ai-world-sdk';
+
+const skills = new AgentSkillClient();
+
+// 列出所有 skills（支持分页和名称搜索）
+const list = await skills.list({ page: 1, pageSize: 20, name: 'search' });
+// list.items: AgentSkillInfo[], list.total, list.page, list.page_size
+
+// 获取 skill 详情
+const detail = await skills.get('web-search');
+// { skill_name, name, description, user_id, created_at, updated_at }
+
+// 上传 skill（zip 文件，必须包含 SKILL.md）
+const zipFile = new File([zipContent], 'web-search.zip', { type: 'application/zip' });
+await skills.upload('web-search', zipFile);
+// { message, skill_name, is_update }
+
+// 下载 skill（返回 Blob）
+const blob = await skills.download('web-search');
+
+// 删除 skill（需要是创建者或管理员）
+await skills.delete('web-search');
+```
+
+## Skill 名称规则
+
+- 仅允许小写字母、数字和连字符: `[a-z0-9-]`
+- 不能以连字符开头或结尾
+- 示例: `web-search`, `database`, `llm`
+
+## Skill 目录结构
+
+每个 Skill 是一个包含 `SKILL.md` 的目录:
+
+```
+web-search/
+├── SKILL.md          # 必须存在，YAML frontmatter 含 name + description
+├── typescript/       # 可选子目录
+│   └── README.md
+└── python/
+    └── README.md
+```
+
+## SKILL.md 格式
+
+```markdown
+---
+name: web-search
+description: 实现 Web 搜索功能...
+---
+
+# Web Search Skill
+
+详细说明...
+```
+
+## 权限
+
+- 任何登录用户可上传 Skill
+- 创建者和管理员可删除/更新
+- 列表和下载无需登录
+
+## API 端点
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/api/agent-skills/` | 列出 skills（分页 + 搜索） |
+| POST | `/api/agent-skills/upload` | 上传 skill（FormData: skill_name + skill_zip） |
+| GET | `/api/agent-skills/{name}` | 获取详情 |
+| GET | `/api/agent-skills/{name}/download` | 下载 zip |
+| DELETE | `/api/agent-skills/{name}` | 删除 |

package/skills/ai-world-sdk/docs/common-mistakes.md

@@ -13,3 +13,6 @@
 | MinIO 路径包含前导斜杠 | 路径不要以 `/` 开头，如 `docs/file.txt` 而非 `/docs/file.txt` |
 | 资源管理与 MinIO 混用 | `MinioStorageClient` 是原始存储（无权限控制），`ResourceClient` 带 ACL |
 | 资源管理忘记权限 | 上传默认 `private`，需显式设 `accessLevel: 'public'` 才能被他人访问 |
+| 建表请求忘设 pluginId | 先调 `sdkConfig.setPluginId('xxx')`，表名会自动加 `{pluginId}_` 前缀 |
+| Agent Skill 名称含大写 | Skill 名称只允许 `[a-z0-9-]`，全小写 |
+| Agent Skill zip 缺 SKILL.md | zip 中必须包含 `SKILL.md` 文件（含 YAML frontmatter） |

package/skills/ai-world-sdk/docs/database-requests.md

@@ -0,0 +1,68 @@
+# 数据库请求
+
+通过 `DatabaseRequestClient` 提交建表/迁移请求、查看请求列表和详情。所有登录用户可提交请求，管理员审核通过后自动执行。
+
+## 基本用法
+
+```typescript
+import { DatabaseRequestClient, sdkConfig } from 'ai-world-sdk';
+
+sdkConfig.setPluginId('my-plugin');
+const dbRequests = new DatabaseRequestClient();
+
+// 提交建表请求
+const req = await dbRequests.submitCreateRequest({
+  tableName: 'user_scores',
+  schemaDefinition: {
+    columns: [
+      { name: 'id', type: 'integer', primary_key: true, auto_increment: true, nullable: false },
+      { name: 'user_id', type: 'integer', nullable: false },
+      { name: 'score', type: 'float', nullable: false },
+    ],
+    indexes: [{ name: 'idx_user_id', columns: ['user_id'] }],
+  },
+  description: '用户评分表',
+});
+
+// 提交迁移请求
+await dbRequests.submitMigrateRequest({
+  tableName: 'user_scores',
+  migrationSql: 'ALTER TABLE my_plugin_user_scores ADD COLUMN level INTEGER DEFAULT 0;',
+  description: '添加 level 字段',
+});
+
+// 列出请求（普通用户看自己的，管理员看全部）
+const list = await dbRequests.listRequests({ status: 'pending', page: 1, pageSize: 20 });
+
+// 获取请求总数
+const total = await dbRequests.getRequestCount({ status: 'pending' });
+
+// 获取请求详情
+const detail = await dbRequests.getRequest(req.id);
+
+// 审核请求（需 can_manage_database 权限）
+await dbRequests.reviewRequest(req.id, 'approve', '审核通过');
+```
+
+## 表名规则
+
+- 实际表名 = `{pluginId}_{tableName}`
+- 只允许 `[a-z0-9_]`
+
+## 列类型白名单
+
+integer, bigint, varchar, text, boolean, float, decimal, date, datetime, timestamp, json, jsonb
+
+## 迁移 SQL 限制
+
+禁止: DROP DATABASE, TRUNCATE, DROP SCHEMA
+
+## API 端点
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | `/api/database/table-requests` | 提交建表/迁移请求 |
+| GET | `/api/database/table-requests` | 列出请求 |
+| GET | `/api/database/table-requests/count` | 请求总数 |
+| GET | `/api/database/table-requests/{id}` | 请求详情 |
+| PATCH | `/api/database/table-requests/{id}` | 审核请求 |

package/skills/ai-world-sdk/docs/provider-and-models.md

@@ -5,11 +5,27 @@
 | Provider | EndpointType | 说明 |
 |----------|-------------|------|
 | `api2img` | `openai` | **推荐**，聚合所有模型（GPT、Gemini、Claude 等） |
-| `aihubmix` | `openai` | 多模型聚合 |
+| `api2img` | `gemini` | Google Gemini 原生 |
+| `api2img` | `anthropic` | Anthropic Claude 原生 |
 | `shubiaobiao` | `openai` | 数标标 |
-| `gemini` | `gemini` | Google Gemini 原生 |
+| `shubiaobiao` | `gemini` | 数标标 Gemini |
+| `shubiaobiao` | `anthropic` | 数标标 Claude |
+| `aiping` | `openai` | 平音 |
+| `aiping` | `gemini` | 平音 Gemini |
+| `aiping` | `anthropic` | 平音 Claude |
+| `gemini` | `gemini` | Google 原生，仅限 Gemini 系列模型 |
+| `openrouter` | `openrouter` | OpenRouter 兼容，模型兼容 OpenRouter 格式，可包括 GPT、以及经聚合的 Gemini/Claude 等（视 provider 能力），模型ID必须以gateway方式设置，如openai/gpt-4o-mini |
 
-规则：`gemini` provider 用 `gemini` endpoint，其余全部用 `openai`。
+## EndpointType 与模型对应关系
+
+| EndpointType | 适用模型 | 说明 |
+|--------------|----------|------|
+| `gemini` | Google Gemini | 必须使用 Google 的 Gemini 模型（如 `gemini-2.5-flash`、`gemini-2.5-pro`） |
+| `anthropic` | Claude | 必须使用 Anthropic 的 Claude 模型（如 `claude-sonnet-4-5`、`claude-3-5-sonnet`）；**仅 api2img、shubiaobiao、aiping 支持此 endpoint** |
+| `openai` | OpenAI 兼容 | 模型兼容 OpenAI 格式，可包括 GPT、以及经聚合的 Gemini/Claude 等（视 provider 能力） |
+| `openrouter` | OpenRouter 兼容 | OpenRouter 兼容，模型兼容 OpenRouter 格式，可包括 GPT、以及经聚合的 Gemini/Claude 等（视 provider 能力），模型ID必须以gateway方式设置，如openai/gpt-4o-mini |
+
+规则：**anthropic 不是 provider**，仅 **api2img**、**shubiaobiao**、**aiping** 支持 EndpointType 为 `anthropic`（调用 Claude）；`gemini` provider 用 `gemini` endpoint，其余按上表组合。
 
 > `doubao` 不通过 `createProvider` 使用，豆包有专用客户端（见 image-generation.md / video-generation.md）。
 
@@ -26,10 +42,13 @@ const model = provider.languageModel('gpt-4o-mini');
 ### 不同供应商
 
 ```typescript
-// Gemini
+// Google Gemini（EndpointType = gemini，仅 Google 模型）
 createProvider('gemini', 'gemini', 'my-plugin').languageModel('gemini-2.5-flash');
 
-// api2img 聚合（推荐，一个 provider 访问所有模型）
+// Anthropic Claude（仅 api2img / shubiaobiao / aiping 支持 endpointType = anthropic，仅 Claude 模型）
+createProvider('api2img', 'anthropic', 'my-plugin').languageModel('claude-sonnet-4-5');
+
+// OpenAI 兼容（EndpointType = openai，模型兼容 OpenAI 格式；api2img 可聚合多模型）
 const p = createProvider('api2img', 'openai', 'my-plugin');
 p.languageModel('gpt-4o-mini');
 p.languageModel('gemini-2.5-flash');
@@ -47,9 +66,10 @@ const ok = await checkModel('api2img', 'openai', 'gpt-4o-mini', 'my-plugin');
 
 | 模型 | 类型 | Provider | EndpointType |
 |------|------|----------|-------------|
-| `gpt-4o-mini` / `gpt-4o` / `gpt-5.1` | 文本 | `api2img` | `openai` |
-| `gemini-2.5-flash` / `gemini-2.5-pro` | 文本 | `gemini` | `gemini` |
-| `dall-e-3` / `gpt-image-1` | 图像 | `api2img` | `openai` |
+| `gpt-4o-mini` / `gpt-4o` / `gpt-5.1` | 文本 | `api2img` | `openai`（OpenAI 兼容） |
+| `gemini-2.5-flash` / `gemini-2.5-pro` | 文本 | `gemini` | `gemini`（仅 Google） |
+| `claude-sonnet-4-6` / `claude-opus-4-6` | 文本 | `api2img`、`shubiaobiao` 或 `aiping` | `anthropic`（仅 Claude） |
+| `dall-e-3` / `gpt-image-1` | 图像 | `api2img`、`shubiaobiao` 或 `aiping` | `openai` |
 | `doubao-seedream-4-5-251128` | 图像 | — | 专用客户端 |
 
 ## AI SDK 函数速查

package/skills/ai-world-sdk/docs/vscode-login.md

@@ -0,0 +1,198 @@
+# VSCode 扩展登录集成
+
+通过 `ai-world-sdk/vscode` 为 VSCode 扩展插件提供一步到位的 AI World 认证集成。
+
+## 安装
+
+VSCode 扩展的 `package.json`:
+
+```json
+{
+  "dependencies": {
+    "ai-world-sdk": "latest",
+    "ai": "^6.0.85"
+  },
+  "devDependencies": {
+    "@types/vscode": "^1.85.0"
+  }
+}
+```
+
+## 最简初始化（一步到位）
+
+```typescript
+import * as vscode from 'vscode';
+import { initAIWorld } from 'ai-world-sdk/vscode';
+
+export async function activate(context: vscode.ExtensionContext) {
+  const ai = await initAIWorld(context);
+  // 完成！sdkConfig 已自动配置，可直接使用所有 SDK 功能
+}
+
+export function deactivate() {}
+```
+
+`initAIWorld` 自动完成：
+1. 从 `vscode.SecretStorage` 读取缓存的 token / user / baseUrl
+2. 验证 token 有效性（有效则复用，无效则弹窗提示登录）
+3. 配置 `sdkConfig`（token / baseUrl / pluginId / headers）
+4. 注册命令：`aiWorld.login` / `aiWorld.logout` / `aiWorld.showLoginPanel`
+5. 显示状态栏登录状态
+6. 将认证信息持久化到 `vscode.SecretStorage`
+
+## pluginId 规则
+
+`pluginId` 默认取扩展 `package.json` 的 `name` 字段（即 `context.extension.packageJSON.name`）。也可通过选项手动指定：
+
+```typescript
+const ai = await initAIWorld(context, { pluginId: 'custom-id' });
+```
+
+## 带选项的初始化
+
+```typescript
+const ai = await initAIWorld(context, {
+  pluginId: 'my-extension',              // 可选，默认取 package.json name
+  baseUrl: 'https://aiworld.local:8000', // 可选，默认值
+  autoLogin: true,                       // 可选，默认 true（弹窗提示登录）
+  debug: false,                          // 可选，默认 false
+  timeout: 120000,                       // 登录超时 ms，默认 120000
+  callbackPort: 18000,                   // OAuth 回调端口，默认 18000
+});
+```
+
+## 返回实例 API
+
+`initAIWorld` 返回 `AIWorldExtension` 实例：
+
+```typescript
+const ai = await initAIWorld(context);
+
+// ── 属性 ──
+ai.token         // string | undefined - 当前 JWT token
+ai.user          // AuthenticatedUser | undefined - 当前用户
+ai.pluginId      // string - 插件 ID（默认 = package.json name）
+ai.baseUrl       // string - 后端地址
+ai.isAuthenticated // boolean - 是否已认证
+
+// ── 方法 ──
+await ai.login()        // 执行登录（有缓存则复用）
+await ai.logout()       // 退出登录（清除 SecretStorage）
+ai.showLoginPanel()     // 打开 Webview 登录管理面板
+
+// ── 事件 ──
+ai.onDidChangeAuthentication((authenticated: boolean) => {
+  console.log('认证状态:', authenticated);
+});
+```
+
+## 在任意位置获取实例
+
+```typescript
+import { getAIWorld } from 'ai-world-sdk/vscode';
+
+// 在 initAIWorld 调用后，任何地方都可以获取实例
+const ai = getAIWorld();
+const token = ai.token;
+```
+
+## 登录后使用 SDK 功能
+
+`initAIWorld` 登录成功后会自动调用 `sdkConfig.setToken()` / `sdkConfig.setBaseUrl()` / `sdkConfig.setPluginId()`，因此所有 SDK 模块都可直接使用：
+
+```typescript
+import { initAIWorld } from 'ai-world-sdk/vscode';
+import { createProvider, MinioStorageClient, ResourceClient } from 'ai-world-sdk';
+import { generateText } from 'ai';
+
+export async function activate(context: vscode.ExtensionContext) {
+  const ai = await initAIWorld(context);
+
+  // 使用 LLM
+  const provider = createProvider('api2img', 'openai', ai.pluginId);
+  const model = provider.languageModel('gpt-4o-mini');
+  const result = await generateText({ model, prompt: '你好' });
+
+  // 使用 MinIO 存储
+  const storage = new MinioStorageClient();
+  await storage.upload('path/to/file.txt', someFile);
+
+  // 使用资源管理
+  const resources = new ResourceClient();
+  const myFiles = await resources.listMy();
+}
+```
+
+## 命令注册
+
+`initAIWorld` 自动注册以下命令（需在扩展 `package.json` 的 `contributes.commands` 中声明）：
+
+```json
+{
+  "contributes": {
+    "commands": [
+      { "command": "aiWorld.login", "title": "AI World: 登录" },
+      { "command": "aiWorld.logout", "title": "AI World: 退出登录" },
+      { "command": "aiWorld.showLoginPanel", "title": "AI World: 登录面板" }
+    ]
+  }
+}
+```
+
+## 存储方式
+
+认证信息通过 `vscode.SecretStorage`（`context.secrets`）安全存储，包括：
+
+| Key | 内容 |
+|-----|------|
+| `ai-world:token` | JWT token |
+| `ai-world:user` | JSON 序列化的用户信息 |
+| `ai-world:baseUrl` | 后端地址 |
+
+SecretStorage 由 VSCode 管理，数据加密存储在系统密钥链中，无需手动管理文件。登出时自动清除。
+
+## 登录流程详解
+
+```
+扩展 activate → initAIWorld(context)
+  ├─ 从 SecretStorage 读取缓存
+  ├─ 有 token？→ validateToken(baseUrl, token)
+  │   ├─ 有效 → 获取用户信息 → 配置 sdkConfig → 保存 SecretStorage → ✅ 完成
+  │   └─ 无效 → 清除 SecretStorage → 继续下一步
+  ├─ autoLogin=true？
+  │   ├─ 弹出通知提示 "AI World: 未登录，部分功能不可用"
+  │   ├─ 用户点击"登录" →
+  │   │   ├─ 启动本地回调服务器 (端口 18000)
+  │   │   ├─ 打开浏览器 → 飞书 OAuth 登录
+  │   │   ├─ 回调返回 token
+  │   │   ├─ 获取用户信息 → 配置 sdkConfig
+  │   │   └─ 持久化到 SecretStorage → ✅ 完成
+  │   └─ 用户点击"稍后" → 等待手动触发 aiWorld.login
+  └─ autoLogin=false？→ 等待用户手动触发 aiWorld.login
+```
+
+## 构建 VSCode 扩展
+
+推荐使用 esbuild 打包，将 `vscode` 标记为 external：
+
+```javascript
+// esbuild.js
+require('esbuild').build({
+  entryPoints: ['src/extension.ts'],
+  bundle: true,
+  outfile: 'dist/extension.js',
+  external: ['vscode'],
+  format: 'cjs',
+  platform: 'node',
+});
+```
+
+打包为 .vsix：
+
+```bash
+npx @vscode/vsce package --no-dependencies
+```
+
+## 完整示例
+
+参见 `ai-world-sdk/examples/vscode-test-extension/`，包含完整的 VSCode 扩展示例代码。