ai-world-sdk 1.3.3 → 1.3.6

package/skills/ai-world-sdk/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ai-world-sdk
-description: Use when initializing ai-world-sdk or calling AI models in ai-world projects. Covers sdkConfig initialization, createProvider with Vercel AI SDK (generateText, streamText, generateImage), Doubao image/video generation/understanding, MinIO object storage (MinioStorageClient), resource management with ACL (ResourceClient), database requests (DatabaseRequestClient), agent skills management (AgentSkillClient), and VSCode extension login (initAIWorld). Triggers on ai-world-sdk, createProvider, sdkConfig, generateText, streamText, generateImage, doubao, video understanding, VideoUnderstandingClient, MinioStorageClient, minio, ResourceClient, resource management, access control, file sharing, DatabaseRequestClient, database request, table creation, AgentSkillClient, agent skill, vscode extension, initAIWorld, or any AI model integration.
+description: Use when initializing ai-world-sdk or calling AI models in ai-world projects. Covers sdkConfig initialization, createProvider with Vercel AI SDK (generateText, streamText, generateImage), Doubao image/video generation/understanding, MinIO object storage (MinioStorageClient), resource management with ACL (ResourceClient), versioned resource management (VersionedResourceClient), agent skills management (AgentSkillClient), VSCode extension login (initAIWorld), user auth (AuthClient, getCurrentUserInfo), download proxy (DownloadClient), admin management (AdminClient for user/role/database), plugin management (PluginManagementClient), statistics (StatsClient, DashboardClient), shared resources (SharedResourceClient), and chrome extensions (ChromeExtensionClient). Triggers on ai-world-sdk, createProvider, sdkConfig, generateText, streamText, generateImage, doubao, video understanding, VideoUnderstandingClient, MinioStorageClient, minio, ResourceClient, resource management, access control, file sharing, VersionedResourceClient, versioned resource, version management, AgentSkillClient, agent skill, vscode extension, initAIWorld, AuthClient, getCurrentUserInfo, DownloadClient, AdminClient, admin API, user management, role management, database management, PluginManagementClient, plugin management, StatsClient, DashboardClient, statistics, SharedResourceClient, shared resources, ChromeExtensionClient, chrome extension, or any AI model integration.
 ---
 
 # AI World SDK
@@ -18,7 +18,7 @@ ai-world-sdk 是 AI World 平台的 TypeScript SDK，通过 `createProvider` 创
 - 使用 Doubao 豆包图像/视频生成
 - 使用 MinIO 对象存储（文件上传/下载/管理）
 - 使用资源管理系统（权限控制: private/specific_users/public）
-- 提交数据库建表/迁移请求
+- 使用版本化资源管理（资源名称+版本号管理）
 - 管理 Agent Skills（上传/下载/删除/列表）
 - **开发 VSCode 扩展**时集成 AI World 登录和 SDK 功能
 
@@ -129,8 +129,9 @@ sdkConfig.setPluginId('my-plugin');
 ### Provider 与模型 → `docs/provider-and-models.md`
 
 - `createProvider(provider, endpointType, pluginId)` 创建 Vercel AI SDK Provider
-- Provider 对照表：`api2img`(推荐) / `gemini` / `aihubmix` / `shubiaobiao` / `aiping` / `openrouter`
+- Provider 对照表：`api2img`(推荐) / `gemini` / `aihubmix` / `shubiaobiao` / `aiping` / `openrouter` / `kunpo`
 - **OpenRouter**：使用专用代理端点 `/api/llm/openrouter`，模型 ID 格式为 `provider/model`（如 `openai/gpt-4o-mini`、`anthropic/claude-sonnet-4-20250514`、`google/gemini-2.5-flash-preview`）
+- **KUNPO API**：统一 LLM 网关（https://llm.ziy.cc），兼容 OpenAI 接口，使用专用代理端点 `/api/llm/kunpo`，一个 Key 访问 150+ 模型
 - 常用模型列表和 AI SDK 函数速查
 
 #### OpenRouter 快速示例
@@ -158,6 +159,31 @@ for await (const chunk of stream.textStream) {
 }
 ```
 
+#### KUNPO API 快速示例
+
+```typescript
+import { createProvider } from 'ai-world-sdk';
+import { generateText, streamText } from 'ai';
+
+// KUNPO API（endpointType 传 'openai'，兼容 OpenAI 接口）
+const provider = createProvider('kunpo', 'openai', 'my-plugin');
+
+// 非流式
+const result = await generateText({
+  model: provider.languageModel('google/gemini-3.1-pro-preview'),
+  prompt: '你好',
+});
+
+// 流式
+const stream = streamText({
+  model: provider.languageModel('anthropic/claude-haiku-4.5'),
+  prompt: '请介绍人工智能',
+});
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk);
+}
+```
+
 ### 文本生成 → `docs/text-generation.md`
 
 - `generateText` / `streamText` / `generateObject` / `streamObject`
@@ -185,16 +211,23 @@ for await (const chunk of stream.textStream) {
 - 三级权限: `private` / `specific_users` / `public`
 - 插件隔离与跨插件访问
 
-### 数据库请求 → `docs/database-requests.md`
+### 版本化资源 → `docs/versioned-resource.md`
 
-- `DatabaseRequestClient` — 建表/迁移请求提交、列表、审核
-- 表名规则: `{pluginId}_{tableName}`
+- `VersionedResourceClient` — 全局版本化资源管理
+- 资源名称为唯一 ID，支持语义化版本号
+- 支持 `latest` 别名获取/下载最新版本
 
 ### Agent Skills → `docs/agent-skills.md`
 
 - `AgentSkillClient` — Skills 上传/下载/删除/列表
 - Skill 名称全小写，zip 必须包含 SKILL.md
 
+### 认证与下载 → `docs/auth-and-download.md`
+
+- `AuthClient` / `getCurrentUserInfo()` — 获取当前用户信息（id / email / full_name / is_superuser 等）
+- `DownloadClient` — 经后端代理下载任意 URL 文件，支持流式下载和浏览器下载
+- HTTP 通用代理 `/api/http-proxy/{path}`（`X-Target-URL` 头指定目标）
+
 ### VSCode 扩展登录 → `docs/vscode-login.md`
 
 - `initAIWorld(context)` 一步初始化（登录 + sdkConfig + 状态栏 + 命令）
@@ -203,6 +236,21 @@ for await (const chunk of stream.textStream) {
 - `pluginId` 默认取扩展 `package.json` 的 `name` 字段
 - 完整示例见 `examples/vscode-test-extension/`
 
+### 管理员 API → `docs/admin-api.md`
+
+- `AdminClient` — 用户管理、角色管理、数据库表管理（需管理员权限）
+- 用户: `listUsers` / `getUser` / `activateUser` / `deactivateUser` / `makeAdmin` / `removeAdmin` / `setUserRole` / `batchSetRole`
+- 角色: `listRoles` / `getRole` / `createRole` / `updateRole` / `deleteRole` / `getRoleUserCounts`
+- 数据库表: `listTables` / `getTableSchema` / `getTableData` / `insertRow` / `updateRow` / `deleteRow`
+
+### 平台通用 API → `docs/platform-api.md`
+
+- `PluginManagementClient` — 插件 CRUD、启用/禁用/重载/重启、模板管理
+- `StatsClient` — AI 接口调用统计/趋势、插件访问统计（管理员）
+- `DashboardClient` — 当前用户统计（无需管理员权限）
+- `SharedResourceClient` — 平台级文件共享（与 `ResourceClient` 的插件级 ACL 不同）
+- `ChromeExtensionClient` — Chrome 插件管理
+
 ### 常见错误 → `docs/common-mistakes.md`
 
 - endpointType 匹配规则、AI SDK v6 用法变更、MinIO 路径规范等

package/skills/ai-world-sdk/docs/admin-api.md

@@ -0,0 +1,133 @@
+# 管理员 API
+
+通过 `AdminClient` 管理用户、角色和数据库表。所有接口需管理员权限。
+
+## 基本用法
+
+```typescript
+import { AdminClient } from 'ai-world-sdk';
+
+const admin = new AdminClient();
+```
+
+---
+
+## 用户管理
+
+```typescript
+// 列出用户（分页 + 搜索 + 角色过滤）
+const users = await admin.listUsers({ page: 1, pageSize: 20, search: '张三' });
+// users.items, users.total, users.page, users.page_size
+
+// 按角色过滤
+const devs = await admin.listUsers({ roleId: 2 });
+const noRole = await admin.listUsers({ noRole: true });
+
+// 获取用户详情
+const user = await admin.getUser(42);
+
+// 激活 / 停用用户
+await admin.activateUser(42);
+await admin.deactivateUser(42);
+
+// 设置/移除管理员
+await admin.makeAdmin(42);
+await admin.removeAdmin(42);
+
+// 设置用户角色
+await admin.setUserRole(42, 2);  // roleId=2
+
+// 批量设置角色（roleId 为 null 则移除角色）
+await admin.batchSetRole([1, 2, 3], 2);
+await admin.batchSetRole([4, 5], null);  // 移除角色
+```
+
+### ListUsersOptions
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `page` | number? | 页码（默认 1） |
+| `pageSize` | number? | 每页数量（1-100，默认 20） |
+| `search` | string? | 搜索用户名/邮箱 |
+| `roleId` | number? | 按角色 ID 过滤 |
+| `noRole` | boolean? | 仅无角色用户 |
+
+---
+
+## 角色管理
+
+```typescript
+// 列出所有角色
+const roles = await admin.listRoles();
+
+// 获取角色详情
+const role = await admin.getRole(1);
+
+// 获取每个角色的用户数
+const counts = await admin.getRoleUserCounts();
+// [{ role_id, role_name, user_count }, ...]
+
+// 创建角色（仅超级用户）
+const newRole = await admin.createRole({
+  name: 'developer',
+  description: '开发者角色',
+  permissions: { can_upload_shared_resources: true },
+});
+
+// 更新角色（仅超级用户，所有字段可选）
+await admin.updateRole(newRole.id, { description: '更新描述' });
+
+// 删除角色（仅超级用户）
+await admin.deleteRole(newRole.id);
+```
+
+### RoleInfo 字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | number | 角色 ID |
+| `name` | string | 角色名称 |
+| `description` | string? | 描述 |
+| `permissions` | Record<string, boolean> | 权限映射 |
+
+---
+
+## 数据库表管理
+
+```typescript
+// 列出所有表
+const tables = await admin.listTables();  // string[]
+
+// 获取表结构
+const schema = await admin.getTableSchema('users');
+// [{ name, type, nullable, default, primary_key }, ...]
+
+// 查询表数据（分页 + 搜索 + 排序）
+const data = await admin.getTableData('users', {
+  page: 1,
+  pageSize: 50,
+  sortBy: 'created_at',
+  sortOrder: 'desc',
+  search: 'test',
+});
+// data.data: Record[], data.total, data.page, data.page_size
+
+// 插入行
+await admin.insertRow('users', { name: '张三', email: 'zhang@example.com' });
+
+// 更新行
+await admin.updateRow('users', { id: 1 }, { name: '李四' });
+
+// 删除行
+await admin.deleteRow('users', { id: 1 });
+```
+
+### ListTableDataOptions
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `page` | number? | 页码（默认 1） |
+| `pageSize` | number? | 每页数量（1-200，默认 20） |
+| `search` | string? | 全文搜索 |
+| `sortBy` | string? | 排序字段 |
+| `sortOrder` | "asc" \| "desc"? | 排序方向 |

package/skills/ai-world-sdk/docs/auth-and-download.md

@@ -0,0 +1,87 @@
+# 认证与下载
+
+## AuthClient — 用户认证
+
+通过 `AuthClient` 或便捷函数 `getCurrentUserInfo()` 获取当前登录用户信息。
+
+```typescript
+import { AuthClient, getCurrentUserInfo } from 'ai-world-sdk';
+
+// 方式1: 便捷函数（自动从 sdkConfig 读取 token）
+const user = await getCurrentUserInfo();
+console.log(user.id, user.full_name, user.email);
+
+// 方式2: 实例化（可传自定义 config）
+const auth = new AuthClient({ token: 'custom-token' });
+const user2 = await auth.getCurrentUserInfo();
+```
+
+### UserInfo 字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | `number` | 用户 ID |
+| `email` | `string?` | 邮箱 |
+| `full_name` | `string?` | 全名 |
+| `avatar_url` | `string?` | 头像 URL |
+| `feishu_user_id` | `string` | 飞书用户 ID |
+| `is_active` | `boolean` | 是否激活 |
+| `is_superuser` | `boolean` | 是否超级管理员 |
+| `created_at` | `string` | 创建时间 |
+
+### API 端点
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/api/auth/me` | 获取当前用户信息（需 Bearer token） |
+| POST | `/api/auth/logout` | 登出（需 Bearer token） |
+| GET | `/api/auth/login` | SDK/Vite 登录入口（需 `redirect` 参数） |
+| GET | `/api/auth/feishu/login` | 前端飞书登录 URL |
+
+---
+
+## DownloadClient — 下载代理
+
+通过 `DownloadClient` 经后端代理下载任意 URL 文件，解决前端跨域限制。
+
+```typescript
+import { DownloadClient } from 'ai-world-sdk';
+
+const dl = new DownloadClient();
+
+// 普通下载（返回 Blob）
+const blob = await dl.download({ url: 'https://example.com/file.zip' });
+
+// 流式下载（AsyncGenerator，适合大文件）
+let totalSize = 0;
+for await (const chunk of dl.streamDownload({ url: 'https://example.com/big.zip' })) {
+  totalSize += chunk.length;
+}
+
+// 触发浏览器下载对话框
+await dl.downloadAsFile(
+  { url: 'https://example.com/report.pdf' },
+  'report.pdf'
+);
+```
+
+---
+
+## HTTP 通用代理
+
+后端提供通用 HTTP 代理，支持所有 HTTP 方法。SDK 未封装此接口，需手动调用。
+
+```typescript
+const resp = await fetch(`${baseUrl}/api/http-proxy/your/path`, {
+  method: 'POST',
+  headers: {
+    'X-Target-URL': 'https://external-api.com/api/endpoint',
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({ key: 'value' }),
+});
+```
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| * | `/api/http-proxy/{path}` | 通用代理，`X-Target-URL` 头指定目标 URL |

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

@@ -1,18 +1,39 @@
 # 常见错误与正确做法
 
+## SDK 使用
+
 | 错误 | 正确做法 |
 |------|---------|
-| endpointType 与 provider 不匹配 | `gemini`→`gemini`，其余→`openai` |
+| endpointType 与 provider 不匹配 | `gemini`→`gemini`，其余→`openai`；仅 api2img/shubiaobiao/aiping 支持 `anthropic` |
 | 手动传 API Key | 不需要，自动经后端代理鉴权 |
 | `result.usage.promptTokens` | AI SDK v6 改为 `inputTokens` / `outputTokens` |
 | `provider.image()` 类型报错 | 用 `(provider as any).image()` |
 | 忘装 `ai` 包 | 需同时装 `ai-world-sdk` 和 `ai` |
 | Vite dev 时调不通 | 在 `vite.config.ts` 中使用 `aiWorldPlugin()` 自动登录 |
 | 用 `createProvider` 调豆包 | 豆包用专用客户端 `DoubaoImageGenerationClient` / `VideoGenerationClient` |
+
+## 存储与资源
+
+| 错误 | 正确做法 |
+|------|---------|
 | MinIO 操作缺少 `X-Plugin-Id` | 先调 `sdkConfig.setPluginId('xxx')` 或在构造函数传入 `pluginId` |
 | MinIO 路径包含前导斜杠 | 路径不要以 `/` 开头，如 `docs/file.txt` 而非 `/docs/file.txt` |
 | 资源管理与 MinIO 混用 | `MinioStorageClient` 是原始存储（无权限控制），`ResourceClient` 带 ACL |
 | 资源管理忘记权限 | 上传默认 `private`，需显式设 `accessLevel: 'public'` 才能被他人访问 |
-| 建表请求忘设 pluginId | 先调 `sdkConfig.setPluginId('xxx')`，表名会自动加 `{pluginId}_` 前缀 |
+| 混淆四种资源系统 | `MinioStorageClient`=原始存储、`ResourceClient`=插件级ACL、`VersionedResourceClient`=全局版本化、`SharedResourceClient`=平台级共享 |
+
+## Agent Skills
+
+| 错误 | 正确做法 |
+|------|---------|
 | Agent Skill 名称含大写 | Skill 名称只允许 `[a-z0-9-]`，全小写 |
 | Agent Skill zip 缺 SKILL.md | zip 中必须包含 `SKILL.md` 文件（含 YAML frontmatter） |
+
+## Admin 与平台 API
+
+| 错误 | 正确做法 |
+|------|---------|
+| 用普通用户调 AdminClient | `AdminClient` 需管理员权限（`is_superuser=true` 或对应角色权限） |
+| HTTP 代理忘设目标 URL | `/api/http-proxy/{path}` 需通过 `X-Target-URL` 请求头指定目标 URL |
+| 统计 API 权限不足 | `StatsClient` 仅管理员可用；普通用户用 `DashboardClient.getMyStats()` 查看个人统计 |
+| 插件模板权限不足 | `createRegisteredTemplate` / `updateRegisteredTemplate` / `deleteRegisteredTemplate` 仅超级用户 |

package/skills/ai-world-sdk/docs/platform-api.md

@@ -0,0 +1,186 @@
+# 平台通用 API
+
+## 插件管理 — PluginManagementClient
+
+```typescript
+import { PluginManagementClient } from 'ai-world-sdk';
+
+const plugins = new PluginManagementClient();
+
+// 列出插件（分页 + 搜索 + 排序）
+const list = await plugins.list({
+  page: 1, pageSize: 20, sortBy: 'updated_at', sortOrder: 'desc', enabledOnly: true,
+});
+
+// 获取 ID 列表
+const ids = await plugins.listIds(true);  // string[]
+
+// 获取插件信息 / 状态
+const info = await plugins.get('my-plugin');
+const status = await plugins.getStatus('my-plugin');
+
+// 创建插件
+await plugins.create({
+  pluginId: 'new-plugin',
+  name: '新插件',
+  description: '描述',
+  staticZip: someZipFile,   // 可选，含 index.html 的 zip
+  serverZip: serverZipFile, // 可选，JS 后端 zip
+});
+
+// 启用 / 禁用 / 重载 / 重启后端
+await plugins.enable('my-plugin');
+await plugins.disable('my-plugin');
+await plugins.reload('my-plugin');
+await plugins.restartServer('my-plugin');
+
+// 获取后端日志
+const logs = await plugins.getServerLogs('my-plugin', 200);
+
+// 删除插件（管理员或创建者）
+await plugins.delete('my-plugin');
+```
+
+### 模板管理
+
+```typescript
+// 列出可用模板
+const templates = await plugins.listTemplates();
+const detail = await plugins.getTemplate('vue-starter');
+
+// 从模板生成插件 zip
+const zip = await plugins.generateFromTemplate('new-plugin', 'vue-starter', {
+  name: '新插件', author: '作者',
+});
+
+// 模板注册表 CRUD（超级用户）
+const regList = await plugins.listRegisteredTemplates({ page: 1, name: 'vue' });
+await plugins.createRegisteredTemplate({
+  pluginId: 'tpl-vue', name: 'Vue 模板', gitUrl: 'https://github.com/...',
+  category: 'frontend',
+});
+await plugins.updateRegisteredTemplate(1, { description: '更新描述' });
+await plugins.deleteRegisteredTemplate(1);
+```
+
+---
+
+## 统计 API — StatsClient（管理员）
+
+```typescript
+import { StatsClient } from 'ai-world-sdk';
+
+const stats = new StatsClient();
+
+// AI 接口调用统计
+const calls = await stats.getAiApiCalls({ provider: 'api2img', page: 1, pageSize: 50 });
+const summary = await stats.getAiApiCallsSummary();
+const trend = await stats.getAiApiCallsTrend({ period: 'daily', days: 30 });
+const byUser = await stats.getAiApiCallsTrendByUser({ period: 'daily', limit: 10 });
+
+// 插件访问统计
+const access = await stats.getPluginAccess({ pluginId: 'my-plugin' });
+const accessSummary = await stats.getPluginAccessSummary();
+```
+
+### 参数说明
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `period` | "daily" \| "weekly" \| "monthly" | 统计周期 |
+| `days` | number? | 统计天数 |
+| `userId` | number? | 按用户筛选 |
+| `apiType` | string? | API 类型（llm / image / video） |
+| `provider` | string? | 提供商 |
+| `model` | string? | 模型 |
+| `pluginId` | string? | 插件 ID |
+
+---
+
+## Dashboard — DashboardClient
+
+```typescript
+import { DashboardClient } from 'ai-world-sdk';
+
+const dashboard = new DashboardClient();
+const myStats = await dashboard.getMyStats();  // 无需管理员权限
+```
+
+---
+
+## 共享资源 — SharedResourceClient
+
+平台级文件共享，与 `ResourceClient`（插件级 ACL）不同。
+
+```typescript
+import { SharedResourceClient } from 'ai-world-sdk';
+
+const shared = new SharedResourceClient();
+
+// 列出（分页 + 搜索 + 分类/标签过滤）
+const list = await shared.list({ page: 1, search: 'config', tag: 'tools' });
+
+// 上传
+const file = new File(['content'], 'data.json', { type: 'application/json' });
+const res = await shared.upload(file, { name: '配置文件', description: '描述', tags: 'config,tools' });
+
+// 获取详情
+const info = await shared.get(res.id);
+
+// 更新元数据（owner 或超级用户）
+await shared.update(res.id, { name: '新名称', tags: ['updated'] });
+
+// 下载
+const blob = await shared.download(res.id);
+
+// 删除
+await shared.delete(res.id);
+```
+
+---
+
+## Chrome 插件 — ChromeExtensionClient
+
+```typescript
+import { ChromeExtensionClient } from 'ai-world-sdk';
+
+const chrome = new ChromeExtensionClient();
+
+// 列出
+const list = await chrome.list({ page: 1, name: 'adblock' });
+
+// 获取详情
+const ext = await chrome.get('my-ext');
+
+// 创建/更新
+await chrome.create({
+  extensionId: 'my-ext',
+  name: '我的扩展',
+  description: '描述',
+  version: '1.0.0',
+  extensionZip: zipFile,  // 可选，更新时可省略仅修改元数据
+});
+
+// 下载
+const zip = await chrome.download('my-ext');
+
+// 删除
+await chrome.delete('my-ext');
+```
+
+---
+
+## 其他接口
+
+### 文档下载（无需 SDK 封装，直接 GET）
+
+```
+GET /api/docs/ai-world-sdk-skill      → 下载 SDK Skill zip
+GET /api/docs/http-proxy-usage-guide   → HTTP 代理使用指南
+```
+
+### SDK 版本检查（SDK 内部自动调用）
+
+```
+POST /api/sdk/version-check
+```

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

@@ -15,6 +15,7 @@
 | `aiping` | `anthropic` | 平音 Claude |
 | `gemini` | `gemini` | Google 原生，仅限 Gemini 系列模型 |
 | `openrouter` | `openai` | OpenRouter 聚合服务，SDK 内部自动使用 `createOpenRouter` 和专用代理端点 `/api/llm/openrouter`。模型 ID 格式为 `provider/model`（如 `openai/gpt-4o-mini`、`anthropic/claude-sonnet-4-20250514`） |
+| `kunpo` | `openai` | KUNPO API 统一 LLM 网关（https://llm.ziy.cc），兼容 OpenAI 接口，一个 Key 访问 150+ 模型。SDK 内部使用 `createOpenAI` 并路由到专用代理 `/api/llm/kunpo` |
 
 ## EndpointType 与模型对应关系
 
@@ -25,7 +26,7 @@
 | `openai` | OpenAI 兼容 | 模型兼容 OpenAI 格式，可包括 GPT、以及经聚合的 Gemini/Claude 等（视 provider 能力） |
 | `openai` | OpenRouter 兼容 | 当 provider 为 `openrouter` 时，`endpointType` 传 `openai`，SDK 内部自动切换到 `createOpenRouter` 和专用代理端点 |
 
-规则：**anthropic 不是 provider**，仅 **api2img**、**shubiaobiao**、**aiping** 支持 EndpointType 为 `anthropic`（调用 Claude）；`gemini` provider 用 `gemini` endpoint；`openrouter` provider 的 `endpointType` 传 `openai`，SDK 内部会自动使用 `@openrouter/ai-sdk-provider` 的 `createOpenRouter` 并路由到专用代理 `/api/llm/openrouter`，其余按上表组合。
+规则：**anthropic 不是 provider**，仅 **api2img**、**shubiaobiao**、**aiping** 支持 EndpointType 为 `anthropic`（调用 Claude）；`gemini` provider 用 `gemini` endpoint；`openrouter` provider 的 `endpointType` 传 `openai`，SDK 内部会自动使用 `@openrouter/ai-sdk-provider` 的 `createOpenRouter` 并路由到专用代理 `/api/llm/openrouter`；`kunpo` provider 的 `endpointType` 传 `openai`，SDK 内部使用 `createOpenAI` 并路由到专用代理 `/api/llm/kunpo`；其余按上表组合。
 
 > `doubao` 不通过 `createProvider` 使用，豆包有专用客户端（见 image-generation.md / video-generation.md）。
 
@@ -60,6 +61,13 @@ const or = createProvider('openrouter', 'openai', 'my-plugin');
 or.languageModel('openai/gpt-4o-mini');
 or.languageModel('anthropic/claude-sonnet-4-20250514');
 or.languageModel('google/gemini-2.5-flash-preview');
+
+// KUNPO API（endpointType 传 'openai'，SDK 内部使用 createOpenAI + 专用代理 /api/llm/kunpo）
+// 兼容 OpenAI Chat Completions 格式，支持 150+ 模型
+const kp = createProvider('kunpo', 'openai', 'my-plugin');
+kp.languageModel('google/gemini-3.1-pro-preview');
+kp.languageModel('anthropic/claude-haiku-4.5');
+kp.languageModel('GLM-5.1');
 ```
 
 ### 检测模型可用性
@@ -80,6 +88,11 @@ const ok = await checkModel('api2img', 'openai', 'gpt-4o-mini', 'my-plugin');
 | `openai/gpt-4o-mini` / `openai/gpt-4o` | 文本 | `openrouter` | `openai`（SDK 自动处理） |
 | `anthropic/claude-sonnet-4-20250514` | 文本 | `openrouter` | `openai`（SDK 自动处理） |
 | `google/gemini-2.5-flash-preview` | 文本 | `openrouter` | `openai`（SDK 自动处理） |
+| `google/gemini-3.1-pro-preview` | 文本 | `kunpo` | `openai`（KUNPO API） |
+| `anthropic/claude-haiku-4.5` | 文本 | `kunpo` | `openai`（KUNPO API） |
+| `GLM-5.1` / `z-ai/glm-5v-turbo` | 文本 | `kunpo` | `openai`（KUNPO API） |
+| `x-ai/grok-4.20` | 文本 | `kunpo` | `openai`（KUNPO API） |
+| `google/gemma-4-26b-a4b-it` | 文本 | `kunpo` | `openai`（KUNPO API） |
 | `doubao-seedream-4-5-251128` | 图像 | — | 专用客户端 |
 
 ## AI SDK 函数速查

package/skills/ai-world-sdk/docs/versioned-resource.md

@@ -0,0 +1,64 @@
+# 版本化资源管理
+
+独立于 SharedResource 的版本化资源系统。资源名称为全局唯一标识（不区分用户），支持语义化版本号管理。
+存储在 MinIO `ai-world-res` bucket 的 `resources/{name}/{version}/{filename}` 路径下。
+
+## 基本用法
+
+```typescript
+import { VersionedResourceClient } from 'ai-world-sdk';
+
+const vr = new VersionedResourceClient();
+
+// 上传新版本（版本号必须高于当前最新版本）
+const file = new File(['{"key": "value"}'], 'config.json', { type: 'application/json' });
+const res = await vr.upload('my-config', '1.0.0', file, '初始版本');
+
+// 上传更高版本
+const file2 = new File(['{"key": "new"}'], 'config.json', { type: 'application/json' });
+await vr.upload('my-config', '1.1.0', file2, '更新配置');
+
+// 获取最新版本信息
+const latest = await vr.getLatest('my-config');
+console.log(latest.version); // "1.1.0"
+
+// 获取指定版本信息
+const v1 = await vr.getVersion('my-config', '1.0.0');
+
+// 列出所有版本（按版本号降序）
+const versions = await vr.listVersions('my-config');
+
+// 下载指定版本
+const blob = await vr.download('my-config', '1.0.0');
+
+// 下载最新版本（使用 "latest" 别名）
+const latestBlob = await vr.download('my-config', 'latest');
+
+// 列出所有资源（分页，聚合最新版本信息）
+const list = await vr.list({ page: 1, pageSize: 20, search: 'config' });
+
+// 删除指定版本
+await vr.deleteVersion('my-config', '1.0.0');
+```
+
+## 版本号规则
+
+| 规则 | 说明 |
+|------|------|
+| 格式 | 语义化版本号（semver），如 `1.0.0`、`2.1.3` |
+| 唯一性 | 同一资源名称下版本号唯一 |
+| 递增约束 | 上传新版本时，版本号必须高于当前最新版本 |
+| latest 别名 | 获取/下载时可使用 `latest` 代替具体版本号 |
+
+## 权限模型
+
+| 操作 | 权限要求 |
+|------|----------|
+| 上传/删除 | `can_upload_shared_resources` 权限 |
+| 查看/下载 | 所有已登录用户 |
+
+## 与 SharedResource / ResourceClient 的区别
+
+- `SharedResource` — 平台级文件共享，按用户上传，无版本概念
+- `ResourceClient` — 插件级资源管理，按 plugin_id 隔离，三级 ACL
+- `VersionedResourceClient` — 全局版本化资源，资源名称为唯一 ID，支持多版本管理