ai-world-sdk 1.5.17 → 1.5.18

package/dist/config.d.ts

@@ -9,7 +9,7 @@
  *
  * 注意: {VERSION} 占位符会在构建时被替换为实际版本号
  */
-export declare const SDK_SIGNATURE = "AI_WORLD_SDK_V:1.5.17";
+export declare const SDK_SIGNATURE = "AI_WORLD_SDK_V:1.5.18";
 /**
  * 版本兼容性错误
  */
@@ -35,8 +35,8 @@ declare class SDKConfig {
     private _authCheckPromise;
     private _currentUser;
     private _cliMode;
-    readonly sdkSignature = "AI_WORLD_SDK_V:1.5.17";
-    readonly sdkVersion = "1.5.17";
+    readonly sdkSignature = "AI_WORLD_SDK_V:1.5.18";
+    readonly sdkVersion = "1.5.18";
     constructor();
     /**
      * Set global base URL

package/dist/config.js

@@ -7,7 +7,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.sdkConfig = exports.VersionCompatibilityError = exports.SDK_SIGNATURE = void 0;
 // SDK 版本号（构建时自动从 package.json 更新）
 // 此版本号会在运行 npm run build 时自动从 package.json 读取并更新
-const SDK_VERSION = "1.5.17";
+const SDK_VERSION = "1.5.18";
 /**
  * SDK 特征码 - 用于在构建后的 JS 文件中识别 SDK 版本
  * 格式: AI_WORLD_SDK_V:版本号
@@ -15,7 +15,7 @@ const SDK_VERSION = "1.5.17";
  *
  * 注意: {VERSION} 占位符会在构建时被替换为实际版本号
  */
-exports.SDK_SIGNATURE = "AI_WORLD_SDK_V:1.5.17";
+exports.SDK_SIGNATURE = "AI_WORLD_SDK_V:1.5.18";
 /**
  * 版本兼容性错误
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-world-sdk",
-  "version": "1.5.17",
+  "version": "1.5.18",
   "description": "TypeScript SDK for AI World Platform - Chat Models, Image Generation, and Video Generation",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

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

@@ -1,6 +1,6 @@
 ---
 name: ai-world-sdk
-description: Use when initializing ai-world-sdk, calling AI models in ai-world projects, or using the ai-world CLI. 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), AI config listing (AIConfigClient, getProviders, getProviderModels), statistics (StatsClient, DashboardClient), shared resources (SharedResourceClient), chrome extensions (ChromeExtensionClient), and CLI command-line tool (ai-world). Triggers on ai-world-sdk, ai-world, cli, 命令行, npx ai-world, command line, 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.
+description: Use when initializing ai-world-sdk, calling AI models in ai-world projects, or using the ai-world CLI. 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), plugin backend configuration (Python venv, Node.js, backend lifecycle), AI config listing (AIConfigClient, getProviders, getProviderModels), statistics (StatsClient, DashboardClient), shared resources (SharedResourceClient), chrome extensions (ChromeExtensionClient), and CLI command-line tool (ai-world). Triggers on ai-world-sdk, ai-world, cli, 命令行, npx ai-world, command line, 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, plugin backend, backend configuration, venv, python backend, node backend, StatsClient, DashboardClient, statistics, SharedResourceClient, shared resources, ChromeExtensionClient, chrome extension, or any AI model integration.
 ---
 
 # AI World SDK
@@ -13,16 +13,11 @@ ai-world-sdk 是 AI World 平台的 TypeScript SDK，通过 `createProvider` 创
 ## When to Use
 
 - 在 ai-world 插件中调用 AI 模型（文本、图像、视频生成/理解）
-- 需要初始化 ai-world-sdk 配置
-- 使用 `createProvider` 调用 Vercel AI SDK
-- 使用 Doubao 豆包图像/视频生成
-- 使用 MinIO 对象存储（文件上传/下载/管理）
-- 使用资源管理系统（权限控制: private/specific_users/public）
-- 使用版本化资源管理（资源名称+版本号管理）
-- 管理 Agent Skills（上传/下载/删除/列表）
-- **开发 VSCode 扩展**时集成 AI World 登录和 SDK 功能
-- **使用命令行（CLI）调用 AI World API**
-- **AI Agent 场景**下需要 CLI 工具调用平台功能
+- 初始化 ai-world-sdk 配置（浏览器/Vite/VSCode/脚本/插件后端）
+- 使用 MinIO 存储、资源管理、版本化资源、Agent Skills
+- 开发 VSCode 扩展集成 AI World
+- 使用 CLI 命令行调用平台功能
+- 配置插件后端（Node.js / Python）
 
 ## 安装
 
@@ -34,292 +29,65 @@ npm install ai-world-sdk ai
 
 ### 浏览器环境（ai-world 插件内）
 
-**自动初始化**，无需手动配置：
-- `baseUrl` — 自动从 `window.location.origin`
-- `token` — 自动从 cookie `auth_token`
-- `pluginId` — 自动从 `window.__INITIAL_DATA__.plugin_id`
+**自动初始化**，无需手动配置（baseUrl / token / pluginId 均自动获取）。
 
-### Vite 开发模式（推荐：Vite Plugin 自动登录）
-
-在 `vite.config.ts` 中添加 `aiWorldPlugin()`，dev server 启动时自动完成以下所有配置：
-
-1. 检测 `.env.local` 中的 `DEBUG_TOKEN`，缺失或过期时通过后端 `/api/auth/login` 自动打开浏览器完成飞书登录
-2. 登录后将 `DEBUG=true`、`DEBUG_TOKEN`、`PLUGIN_ID` 写入 `.env.local`
-3. `PLUGIN_ID` 按优先级：`plugin.json` 的 `plugin_id` → `package.json` 的 `name` → 项目目录名
-4. 通过 `window.__AI_WORLD_CONFIG__` 将配置注入到浏览器页面，SDK 自动读取
+### Vite 开发模式
 
 ```typescript
 import { aiWorldPlugin } from 'ai-world-sdk/vite'
 
 export default defineConfig({
-  plugins: [
-    vue(), // 或 react() 等
-    aiWorldPlugin()  // baseUrl 默认 https://aiworld.local:8000
-  ]
+  plugins: [vue(), aiWorldPlugin()]  // baseUrl 默认 https://aiworld.local:8000
 })
 ```
 
-首次 `npm run dev` 时自动打开浏览器完成飞书登录，后续启动 token 有效则直接跳过。无需在代码中手动调用 `sdkConfig.setToken()` 或 `sdkConfig.setPluginId()`，一切自动完成。
-
-如需自定义后端地址：
-
-```typescript
-aiWorldPlugin({ baseUrl: 'https://your-server:8000' })
-```
-
-### VSCode 扩展（推荐：initAIWorld 一步到位）
+自动完成：token 获取/刷新、PLUGIN_ID 推断、浏览器注入。详见 → `docs/vscode-login.md`
 
-在 VSCode 扩展中使用 `ai-world-sdk/vscode`，一行代码完成所有配置：
+### VSCode 扩展
 
 ```typescript
-import * as vscode from 'vscode';
 import { initAIWorld } from 'ai-world-sdk/vscode';
-import { createProvider } from 'ai-world-sdk';
-import { generateText } from 'ai';
-
-export async function activate(context: vscode.ExtensionContext) {
-  const ai = await initAIWorld(context, {
-    pluginId: 'my-extension',  // 可选，默认从 package.json name 推断
-  });
-
-  // sdkConfig 已自动配置，直接使用 SDK 功能
-  if (ai.isAuthenticated) {
-    const provider = createProvider('api2img', 'openai', ai.pluginId);
-    const model = provider.languageModel('gpt-4o-mini');
-    const result = await generateText({ model, prompt: '你好' });
-  }
-}
+const ai = await initAIWorld(context, { pluginId: 'my-extension' });
 ```
 
-`initAIWorld` 自动完成：登录认证、sdkConfig 配置、命令注册、状态栏、缓存持久化到 `vscode.SecretStorage`。pluginId 默认取 `package.json` 的 `name`。
-
-扩展 `package.json` 需声明 SDK 自动注册的命令：
-
-```json
-{
-  "contributes": {
-    "commands": [
-      { "command": "aiWorld.login", "title": "AI World: 登录" },
-      { "command": "aiWorld.logout", "title": "AI World: 退出登录" },
-      { "command": "aiWorld.showLoginPanel", "title": "AI World: 登录面板" }
-    ]
-  }
-}
-```
-
-详细用法见 → `docs/vscode-login.md`
+自动完成：登录认证、sdkConfig、命令注册、状态栏、SecretStorage 缓存。详见 → `docs/vscode-login.md`
 
 ### 非浏览器环境（测试、脚本）
 
 ```typescript
 import { sdkConfig } from 'ai-world-sdk';
-
 sdkConfig.setBaseUrl('https://aiworld.local:8000');
 sdkConfig.setToken('your-jwt-token');
 sdkConfig.setPluginId('my-plugin');
 ```
 
-也可通过环境变量自动初始化（SDK 自动读取 `.env.local` > `.env` > `AI_WORLD_ENV_FILE` 指定文件）：
-- `AI_WORLD_BASE_URL` — 服务端地址，插件后端启动时由平台自动注入
-- `PLUGIN_ID` — 插件 ID
-- `DEBUG_TOKEN` — 调试用 JWT Token
-- `AI_WORLD_TOKEN` — 用户登录后获取的 JWT Token
-- `AI_WORLD_ENV_FILE` — 指定自定义 `.env` 文件路径（绝对或相对路径均可）
-
-### 插件后端环境（平台自动注入）
-
-当插件配置了后端（`plugin.json` 的 `backend` 字段），平台启动子进程时会自动注入以下环境变量：
-
-| 环境变量 | 说明 |
-|----------|------|
-| `PORT` | **插件后端必须监听的端口**（平台自动分配，范围 19000~19999） |
-| `SERVER_PORT` | 同 `PORT`，兼容别名 |
-| `PLUGIN_ID` | 当前插件 ID |
-| `AI_WORLD_BASE_URL` | 平台后端地址（默认 `http://127.0.0.1:8000`） |
-| `AI_WORLD_ENV_FILE` | 平台写入的 `.env` 文件路径（`server/.env`），SDK 自动加载 |
-| `NODE_ENV` | 固定为 `production`（仅 Node.js 后端） |
-
-**重要**：插件后端 **必须** 监听 `PORT` 环境变量指定的端口，否则平台无法正确代理请求。
-
-#### plugin.json backend 配置
-
-```json
-{
-  "backend": {
-    "type": "node",
-    "entry": "index.js",
-    "install_cmd": "npm install",
-    "health_check": "/health"
-  }
-}
-```
-
-| 字段 | 说明 |
-|------|------|
-| `type` | 后端类型：`"node"` 或 `"python"`（默认 `"node"`） |
-| `entry` | 入口文件（Node.js 默认 `index.js`，Python 默认 `start.py`） |
-| `install_cmd` | 依赖安装命令（Node.js 默认 `npm install`，Python 默认 `pip install -r requirements.txt`） |
-| `start_cmd` | 启动命令（可选，默认 `node {entry}` 或 `python {entry}`） |
-| `health_check` | 健康检查路径（默认 `/health`） |
-| `enable_websocket` | 是否启用 WebSocket 代理（默认 `false`） |
-
-#### Node.js 后端示例
-
-```javascript
-// server/index.js
-const express = require('express');
-const app = express();
-const port = process.env.PORT || 3000;
-
-app.get('/health', (req, res) => res.json({ status: 'ok' }));
-app.get('/api/hello', (req, res) => res.json({ message: 'Hello from plugin backend!' }));
-
-app.listen(port, () => {
-  console.log(`Plugin backend listening on port ${port}`);
-});
-```
-
-#### Python 后端示例
-
-```python
-# server/start.py
-import os
-from fastapi import FastAPI
-import uvicorn
-
-app = FastAPI()
-port = int(os.environ.get("PORT", "3000"))
-
-@app.get("/health")
-def health():
-    return {"status": "ok"}
-
-@app.get("/api/hello")
-def hello():
-    return {"message": "Hello from Python plugin backend!"}
-
-if __name__ == "__main__":
-    uvicorn.run(app, host="0.0.0.0", port=port)
-```
-
-对应 `plugin.json`：
-```json
-{
-  "backend": {
-    "type": "python",
-    "entry": "start.py",
-    "install_cmd": "pip install -r requirements.txt",
-    "health_check": "/health"
-  }
-}
-```
-
-### 插件前端请求插件后端（HTTP 代理）
-
-平台为每个后端插件注册了 HTTP 反向代理路由，**插件前端不需要知道后端实际端口**，统一通过以下地址访问：
-
-```
-{AI_WORLD_BASE_URL}/api/{plugin-id}/server/{path}
-```
-
-例如插件 ID 为 `my-plugin`，后端有 `/api/hello` 接口，前端请求地址为：
-
-```
-https://aiworld.local:8000/api/my-plugin/server/api/hello
-```
+环境变量自动初始化：`AI_WORLD_BASE_URL` / `PLUGIN_ID` / `DEBUG_TOKEN` / `AI_WORLD_TOKEN` / `AI_WORLD_ENV_FILE`
 
-在插件前端代码中使用 `sdkConfig` 获取 baseUrl：
+### 插件后端环境
 
-```typescript
-import { sdkConfig } from 'ai-world-sdk';
+平台启动后端子进程时自动注入 `PORT`、`PLUGIN_ID`、`AI_WORLD_BASE_URL` 等环境变量，SDK 自动读取，无需手动配置。
 
-// 插件前端请求插件后端
-const baseUrl = sdkConfig.getServerUrl();
-const pluginId = sdkConfig.getPluginId();
-const response = await fetch(`${baseUrl}/api/${pluginId}/server/api/hello`, {
-  headers: { 'Authorization': `Bearer ${sdkConfig.getToken()}` }
-});
-```
+**插件后端必须监听 `PORT` 环境变量指定的端口。**
 
-WebSocket 同理：`ws(s)://{host}/api/{plugin-id}/server/ws`
+详见 → `docs/plugin-backend.md`
 
 ## 功能模块
 
-以下功能的详细用法和代码示例请查阅对应的子文档。
-
 ### Provider 与模型 → `docs/provider-and-models.md`
 
 - `createProvider(provider, endpointType, pluginId)` 创建 Vercel AI SDK Provider
-- 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`）
-- **OpenRouter Reasoning**：通过 `providerOptions.openrouter.reasoning` 启用模型思考，支持 `effort`（`xhigh`/`high`/`medium`/`low`/`minimal`）和 `max_tokens` 参数，适用于 Claude / DeepSeek-R1 / o1 / o3 / Gemini 等支持思考的模型
-- **KUNPO API**：统一 LLM 网关（https://llm.ziy.cc），兼容 OpenAI 接口，使用专用代理端点 `/api/llm/kunpo`，一个 Key 访问 150+ 模型
-- 常用模型列表和 AI SDK 函数速查
-
-#### OpenRouter 快速示例
+- Provider：`api2img`(推荐) / `gemini` / `shubiaobiao` / `aiping` / `openrouter` / `kunpo`
+- OpenRouter / KUNPO：模型 ID 格式 `provider/model`，支持 reasoning
 
 ```typescript
 import { createProvider } from 'ai-world-sdk';
-import { generateText, streamText } from 'ai';
-
-// OpenRouter（endpointType 传 'openai'，SDK 内部自动使用 createOpenRouter）
-const provider = createProvider('openrouter', 'openai', 'my-plugin');
-
-// 非流式
-const result = await generateText({
-  model: provider.languageModel('openai/gpt-4o-mini'),
-  prompt: '你好',
-});
-
-// 流式
-const stream = streamText({
-  model: provider.languageModel('anthropic/claude-sonnet-4-20250514'),
-  prompt: '请介绍人工智能',
-});
-for await (const chunk of stream.textStream) {
-  process.stdout.write(chunk);
-}
-
-// 启用思考/推理（OpenRouter / KUNPO 均支持）
-const thinkResult = await generateText({
-  model: provider.languageModel('anthropic/claude-sonnet-4-20250514'),
-  prompt: '证明根号2是无理数',
-  providerOptions: {
-    openrouter: {
-      reasoning: {
-        effort: 'high',         // 思考深度: xhigh / high / medium / low / minimal
-        // max_tokens: 10000,   // 可选：限制思考 token 数量
-      },
-    },
-  },
-});
-console.log('思考过程:', thinkResult.reasoning);
-console.log('最终回答:', thinkResult.text);
-```
-
-#### KUNPO API 快速示例
-
-```typescript
-import { createProvider } from 'ai-world-sdk';
-import { generateText, streamText } from 'ai';
+import { generateText } 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'),
+  model: provider.languageModel('deepseek/deepseek-v4-pro'),
   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`
@@ -335,7 +103,7 @@ for await (const chunk of stream.textStream) {
 ### 视频生成 & 视频理解 → `docs/video-generation.md`
 
 - `VideoGenerationClient`（豆包 Seedance）
-- `VideoUnderstandingClient`（豆包视频理解，基于 Chat Completions API）
+- `VideoUnderstandingClient`（豆包视频理解）
 - `OpenAIVideoGenerationClient`（Sora）
 
 ### MinIO 对象存储 → `docs/minio-storage.md`
@@ -345,97 +113,54 @@ for await (const chunk of stream.textStream) {
 
 ### 资源管理 → `docs/resource-management.md`
 
-- `ResourceClient` — 带 ACL 的资源管理
-- 三级权限: `private` / `specific_users` / `public`
+- `ResourceClient` — 带 ACL 的资源管理（private / specific_users / public）
 - 插件隔离与跨插件访问
 
 ### 版本化资源 → `docs/versioned-resource.md`
 
-- `VersionedResourceClient` — 全局版本化资源管理
-- 资源名称为唯一 ID，支持语义化版本号
-- 支持 `latest` 别名获取/下载最新版本
+- `VersionedResourceClient` — 全局版本化资源（名称+语义化版本号）
 
 ### 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` 头指定目标）
+- `AuthClient` / `getCurrentUserInfo()` — 用户信息
+- `DownloadClient` — 代理下载
+- HTTP 通用代理 `/api/http-proxy/{path}`
 
 ### VSCode 扩展登录 → `docs/vscode-login.md`
 
-- `initAIWorld(context)` 一步初始化（登录 + sdkConfig + 状态栏 + 命令）
+- `initAIWorld(context)` 一步初始化
 - `getAIWorld()` 获取实例
-- 认证信息通过 `vscode.SecretStorage` 安全存储（token / user / baseUrl）
-- `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`
+- `AdminClient` — 用户/角色/数据库表管理（需管理员权限）
 
 ### 平台通用 API → `docs/platform-api.md`
 
-- `AIConfigClient` — 配置驱动的 AI 供应商与模型列表（登录即可）：`getProviders()`、`getProviderModels(providerId)`
-- `PluginManagementClient` — 插件 CRUD（`create` / `update` 分离）、启用/禁用/重载/重启、模板管理
-  - `create(data)` — 创建新插件（POST `/api/plugins/create`），插件不存在时使用
-  - `update(data)` — 更新已有插件（POST `/api/plugins/update`），插件必须已存在，未传入的字段保留原值
-  - 两者均支持: pluginId / name / description / author / version / staticZip / serverZip / backendType / backendEntry / backendWebsocket / disableSdkUpdateNotice
-  - `backendType` — 后端类型：`"node"` 或 `"python"`（默认 node）
-- `StatsClient` — AI 接口调用统计/趋势、插件访问统计（管理员）
-- `DashboardClient` — 当前用户统计（无需管理员权限）
-- `SharedResourceClient` — 平台级文件共享（与 `ResourceClient` 的插件级 ACL 不同）
+- `AIConfigClient` — AI 供应商与模型列表
+- `PluginManagementClient` — 插件 CRUD（`create` / `update` 分离）、启用/禁用/重载/重启
+- `StatsClient` / `DashboardClient` — 统计
+- `SharedResourceClient` — 平台级文件共享
 - `ChromeExtensionClient` — Chrome 插件管理
-- `PluginTokenClient` — 插件 Token 管理（创建/列表/更新/删除/重新生成/启停），需 `can_manage_plugin_tokens` 权限 → `docs/admin-api.md`
+- `PluginTokenClient` — 插件 Token 管理
 
-### CLI 命令行工具 → `docs/cli-usage.md`
-
-- `ai-world` 命令行工具，所有 SDK 功能的命令行模式
-- 安装: `npm install -g ai-world-sdk` 或 `npx ai-world-sdk`
-- 认证: `ai-world login` 或环境变量 `DEBUG_TOKEN`
-- 输出: 默认 JSON（AI Agent 友好），支持 `--format table`
-- 默认值: plugin-id=`cli`，provider=`kunpo`，endpoint=`openai`，model=`deepseek/deepseek-v4-pro`
-- 版本检查: `ai-world version`（从后端读取最新版本）
-- 帮助: `ai-world help` / `ai-world help <command>`（中文详细说明）
-- 完整命令参考 → `docs/cli-commands.md`
+### 插件后端配置 → `docs/plugin-backend.md`
 
-#### 快速开始
-
-```bash
-# 安装
-npm install -g ai-world-sdk
+- Python 后端：自动创建 `.venv` 虚拟环境，隔离依赖
+- Node.js 后端：使用服务器当前 Node.js 版本
+- 更新时 `server/` 原有文件保留，相同路径覆盖替换
+- 代理路由：`/api/{pluginId}/server/{path}` → `http://127.0.0.1:{port}/{path}`
 
-# 登录
-ai-world login
-
-# 配置默认值（可选，默认 kunpo/openai/deepseek-v4-pro）
-ai-world config set provider=kunpo endpoint=openai model=deepseek/deepseek-v4-pro
-
-# 文本生成
-ai-world text generate --prompt "你好"
-
-# 流式文本生成
-ai-world text stream --prompt "请介绍人工智能"
-
-# 查看插件列表
-ai-world plugin list --format table
-
-# 创建插件
-ai-world plugin create ./dist.zip --plugin-id my-plugin --name "My Plugin" --version 1.0.0
-
-# 更新插件（插件必须已存在，未传入的字段保留原值）
-ai-world plugin update ./dist.zip --plugin-id my-plugin --version 1.1.0
+### CLI 命令行工具 → `docs/cli-usage.md`
 
-# 版本检查
-ai-world version
-```
+- 安装: `npm install -g ai-world-sdk`
+- 认证: `ai-world login`
+- 默认值: provider=`kunpo`，model=`deepseek/deepseek-v4-pro`
+- 完整命令参考 → `docs/cli-commands.md`
 
 ### 常见错误 → `docs/common-mistakes.md`
 

package/skills/ai-world-sdk/docs/plugin-backend.md

@@ -0,0 +1,250 @@
+# 插件后端配置与使用
+
+平台支持为插件配置独立的后端服务（Node.js 或 Python），由 `PluginManager` 自动管理子进程生命周期并注册反向代理。
+
+## plugin.json backend 配置
+
+```json
+{
+  "plugin_id": "my-plugin",
+  "backend": {
+    "type": "node",
+    "entry": "index.js",
+    "install_cmd": "npm install",
+    "start_cmd": "node index.js",
+    "health_check": "/health",
+    "enable_websocket": false,
+    "env": {}
+  }
+}
+```
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `type` | string | `"node"` | 后端类型：`"node"` 或 `"python"` |
+| `entry` | string | Node: `"index.js"`, Python: `"start.py"` | 入口文件（相对于 `server/` 目录） |
+| `install_cmd` | string | Node: `"npm install"`, Python: `"pip install -r requirements.txt"` | 依赖安装命令 |
+| `start_cmd` | string | Node: `"node {entry}"`, Python: `".venv/bin/python {entry}"` | 启动命令（可选，覆盖默认） |
+| `health_check` | string | `"/health"` | 健康检查路径 |
+| `enable_websocket` | bool | `false` | 是否启用 WebSocket 代理 |
+| `env` | object | `{}` | 额外环境变量（合并到默认环境变量中） |
+
+## 运行环境
+
+### Node.js 后端
+
+- **运行时**：使用服务器当前安装的 Node.js 版本（即 `PATH` 中的 `node` 命令）
+- **依赖安装**：当 `server/package.json` 存在且 `node_modules/` 不存在时，自动执行 `npm install`（或 `install_cmd` 指定的命令）
+- **启动命令**：默认 `node {entry}`，可通过 `start_cmd` 覆盖
+- **进程检测**：监控 `node`, `npm`, `npx`, `yarn`, `pnpm`, `bun` 进程
+
+### Python 后端
+
+- **运行时**：自动创建隔离的虚拟环境 `.venv`（通过 `python -m venv .venv`）
+- **虚拟环境**：
+  - 首次启动时自动在 `server/` 目录下创建 `.venv`
+  - 如果 `.venv` 存在但不完整（缺少 `bin/python`），自动重建
+  - `.venv` 在插件更新时不会被删除，持久保留
+- **依赖安装**：当 `server/requirements.txt` 存在时，使用 `.venv/bin/pip install -r requirements.txt` 安装依赖
+- **启动命令**：默认 `.venv/bin/python {entry}`，可通过 `start_cmd` 覆盖
+- **环境变量**：自动设置 `VIRTUAL_ENV=.venv`，并将 `.venv/bin` 加入 `PATH` 头部
+- **进程检测**：监控 `python`, `python3`, `uvicorn`, `gunicorn`, `flask` 进程
+
+## 平台自动注入的环境变量
+
+| 环境变量 | 说明 | 适用 |
+|----------|------|------|
+| `PORT` | 插件后端必须监听的端口（平台自动分配，范围 19000~19999） | 全部 |
+| `SERVER_PORT` | 同 `PORT`，兼容别名 | Node.js |
+| `PLUGIN_ID` | 当前插件 ID | 全部 |
+| `AI_WORLD_BASE_URL` | 平台后端地址（默认 `http://127.0.0.1:8000`） | 全部 |
+| `AI_WORLD_ENV_FILE` | 空字符串（Node.js 后端不自动加载 .env） | Node.js |
+| `NODE_ENV` | 固定为 `production` | Node.js |
+| `PYTHONUNBUFFERED` | 固定为 `1`，确保日志实时输出 | Python |
+| `VIRTUAL_ENV` | 固定为 `.venv` | Python |
+| `PATH` | Python: `.venv/bin:$PATH`; Node.js: 系统 `$PATH` | 全部 |
+| `HOME` | 系统用户目录 | 全部 |
+| `LANG` | 系统语言设置 | 全部 |
+
+可通过 `backend.env` 字段注入自定义环境变量，会合并到上述默认变量之上。
+
+## 插件更新时的文件处理
+
+### 通过 `POST /api/plugins/update` 更新
+
+| 目录 | 行为 |
+|------|------|
+| `server/` | **原有文件保留**，zip 中相同路径的文件会覆盖替换，新文件会添加。仅删除 `node_modules/`（确保重新安装依赖） |
+| `static/` | 如果上传了 `static_zip`，则**清空旧目录**后解压新文件；未上传则保留原有文件 |
+| `.venv/` | **始终保留**，不会被删除（zip 中即使包含也会被忽略，不会解压覆盖） |
+| `plugin.json` | 仅更新传入的字段，未传入的字段保留原值 |
+
+### zip 解压时自动忽略的目录/文件
+
+解压 `server_zip` 时，以下目录和文件会被自动过滤，不会被写入：
+
+- **目录**：`node_modules/`, `__pycache__/`, `.git/`, `.venv/`, `venv/`, `.idea/`, `.vscode/`, `.tox/`, `.mypy_cache/`, `.pytest_cache/`, `.ruff_cache/`
+- **文件**：`.DS_Store`, `Thumbs.db`, `desktop.ini`
+
+### 更新后的自动行为
+
+1. **卸载旧插件**：停止后端进程，释放端口
+2. **文件操作**：按上述规则处理 `server/` 和 `static/` 目录
+3. **重新加载**：读取 `plugin.json`，根据 `backend.type` 选择对应管理器
+4. **安装依赖**：
+   - Node.js：由于 `node_modules/` 被删除，会重新执行 `npm install`
+   - Python：`.venv` 已保留，检查 `requirements.txt` 后执行 `pip install`（增量安装）
+5. **启动进程**：执行启动命令，等待健康检查通过
+6. **注册代理**：为新端口注册 HTTP/WebSocket 反向代理路由
+
+## 目录结构
+
+### Node.js 后端
+
+```
+plugins/{plugin_id}/
+├── __init__.py          # Python BasePlugin 壳子
+├── plugin.json          # 含 backend 配置 (type: "node")
+├── plugin_state.json
+├── static/              # 前端静态文件
+│   └── index.html
+└── server/              # Node.js 后端代码
+    ├── package.json
+    ├── node_modules/    # npm install 自动生成（更新时会被清除后重装）
+    └── index.js
+```
+
+### Python 后端
+
+```
+plugins/{plugin_id}/
+├── __init__.py          # Python BasePlugin 壳子
+├── plugin.json          # 含 backend 配置 (type: "python")
+├── plugin_state.json
+├── static/              # 前端静态文件
+│   └── index.html
+└── server/              # Python 后端代码
+    ├── .venv/           # 自动创建的虚拟环境（更新时保留）
+    ├── requirements.txt
+    └── start.py
+```
+
+## 代理路由
+
+平台为每个后端插件注册反向代理，插件前端无需知道实际端口：
+
+| 类型 | 请求路径 | 代理目标 |
+|------|----------|----------|
+| HTTP | `/api/{pluginId}/server/{path}` | `http://127.0.0.1:{port}/{path}` |
+| WebSocket | `/api/{pluginId}/server/ws` | `ws://127.0.0.1:{port}/ws` |
+| WebSocket | `/api/{pluginId}/server/ws/{path}` | `ws://127.0.0.1:{port}/ws/{path}` |
+
+## 端口规则
+
+- 允许范围: 19000 ~ 19999
+- 黑名单端口: 22, 80, 443, 3000, 3306, 5432, 6379, 8000, 8080, 9100, 27017
+- 不指定端口时自动分配（排除运行中插件端口、已配置端口、系统占用端口）
+- Node.js 和 Python 后端共享同一端口池
+
+## 完整示例
+
+### Node.js 后端
+
+**plugin.json:**
+```json
+{
+  "plugin_id": "my-node-plugin",
+  "name": "My Node Plugin",
+  "backend": {
+    "type": "node",
+    "entry": "index.js",
+    "install_cmd": "npm install",
+    "health_check": "/health",
+    "enable_websocket": true
+  }
+}
+```
+
+**server/index.js:**
+```javascript
+const express = require('express');
+const app = express();
+const port = process.env.PORT || 3000;
+
+app.get('/health', (req, res) => res.json({ status: 'ok' }));
+app.get('/api/hello', (req, res) => res.json({ message: 'Hello!' }));
+
+app.listen(port, () => {
+  console.log(`Backend listening on port ${port}`);
+});
+```
+
+**server/package.json:**
+```json
+{
+  "name": "my-node-plugin-server",
+  "dependencies": {
+    "express": "^4.18.0"
+  }
+}
+```
+
+### Python 后端
+
+**plugin.json:**
+```json
+{
+  "plugin_id": "my-python-plugin",
+  "name": "My Python Plugin",
+  "backend": {
+    "type": "python",
+    "entry": "start.py",
+    "install_cmd": "pip install -r requirements.txt",
+    "health_check": "/health"
+  }
+}
+```
+
+**server/start.py:**
+```python
+import os
+from fastapi import FastAPI
+import uvicorn
+
+app = FastAPI()
+port = int(os.environ.get("PORT", "3000"))
+
+@app.get("/health")
+def health():
+    return {"status": "ok"}
+
+@app.get("/api/hello")
+def hello():
+    return {"message": "Hello from Python!"}
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=port)
+```
+
+**server/requirements.txt:**
+```
+fastapi>=0.100.0
+uvicorn>=0.23.0
+```
+
+## 生命周期管理 API
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | `/api/plugins/{plugin_id}/restart-server` | 重启后端（停止 → 重装依赖 → 启动） |
+| GET | `/api/plugins/{plugin_id}/server-logs?lines=200` | 获取后端日志 |
+| DELETE | `/api/plugins/{plugin_id}/server-logs` | 清空后端日志 |
+
+## 注意事项
+
+1. **必须监听 PORT**：插件后端必须使用 `PORT` 环境变量指定的端口，否则平台代理无法转发请求
+2. **健康检查**：平台启动后端后会请求 `health_check` 路径，确保返回 2xx 状态码
+3. **Python 虚拟环境**：平台为每个 Python 插件自动管理独立 `.venv`，避免依赖冲突。更新插件时 `.venv` 被保留，pip 会增量安装新增依赖
+4. **Node.js 依赖**：每次更新后 `node_modules` 会被清除并重新安装，确保依赖与新代码匹配
+5. **日志输出**：子进程 stdout/stderr 写入 `backend/logs/{plugin_id}/server.log`（5MB 自动轮转，保留 3 份）
+6. **进程清理**：平台启动前会检测并清理端口/目录下的残留进程，确保干净启动

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

@@ -70,6 +70,32 @@ kp.languageModel('anthropic/claude-haiku-4.5');
 kp.languageModel('GLM-5.1');
 ```
 
+### OpenRouter / KUNPO Reasoning（启用思考）
+
+```typescript
+import { createProvider } from 'ai-world-sdk';
+import { generateText } from 'ai';
+
+const provider = createProvider('openrouter', 'openai', 'my-plugin');
+
+const result = await generateText({
+  model: provider.languageModel('anthropic/claude-sonnet-4-20250514'),
+  prompt: '证明根号2是无理数',
+  providerOptions: {
+    openrouter: {
+      reasoning: {
+        effort: 'high',         // xhigh / high / medium / low / minimal
+        // max_tokens: 10000,   // 可选：限制思考 token 数量
+      },
+    },
+  },
+});
+console.log('思考过程:', result.reasoning);
+console.log('最终回答:', result.text);
+```
+
+适用于 Claude / DeepSeek-R1 / o1 / o3 / Gemini 等支持思考的模型。KUNPO 同样支持 reasoning 参数。
+
 ### 检测模型可用性
 
 ```typescript