ai-world-sdk 1.5.15 → 1.5.17

package/dist/cli/commands/help.js

@@ -109,7 +109,7 @@ const COMMAND_DETAILS = {
     },
     plugin: {
         desc: '插件管理 —— 部署、启用/禁用、重启、查看日志',
-        usage: 'ai-world plugin <list|get|ids|create|enable|disable|reload|restart|logs|status|delete>',
+        usage: 'ai-world plugin <list|get|ids|create|update|enable|disable|reload|restart|logs|status|delete>',
         examples: [
             'ai-world plugin list',
             'ai-world plugin ids --enabled-only',
@@ -117,6 +117,8 @@ const COMMAND_DETAILS = {
             'ai-world plugin enable my-plugin',
             'ai-world plugin logs my-plugin --lines 50',
             'ai-world plugin create ./dist.zip --plugin-id my-plugin --name "我的插件"',
+            'ai-world plugin create --plugin-id py-plugin --server-zip server.zip --backend-type python',
+            'ai-world plugin update --plugin-id my-plugin --server-zip server.zip --backend-type node',
         ],
     },
     admin: {

package/dist/cli/commands/plugin.js

@@ -191,8 +191,9 @@ function registerPluginCommands(program) {
         .option('--description <text>', '插件描述')
         .option('--author <author>', '插件作者')
         .option('--version <ver>', '插件版本')
-        .option('--server-zip <path>', 'JS 后端 zip 包路径')
-        .option('--backend-entry <entry>', 'JS 后端入口文件（默认 index.js）')
+        .option('--server-zip <path>', '后端代码 zip 包路径')
+        .option('--backend-type <type>', '后端类型: node 或 python（默认 node）')
+        .option('--backend-entry <entry>', '后端入口文件（Node.js 默认 index.js，Python 默认 start.py）')
         .option('--backend-websocket', '启用 WebSocket 代理')
         .option('--disable-sdk-update-notice', '禁用 SDK 更新提示')
         .action(async (zipFile, options, cmd) => {
@@ -206,6 +207,7 @@ function registerPluginCommands(program) {
             });
             (0, utils_1.initSDK)(auth);
             const client = new plugin_management_1.PluginManagementClient();
+            const bt = options.backendType;
             const res = await client.create({
                 pluginId: options.pluginId,
                 name: options.name,
@@ -214,6 +216,7 @@ function registerPluginCommands(program) {
                 version: options.version,
                 staticZip: zipFile ? (0, utils_1.readFileAsFile)(zipFile) : undefined,
                 serverZip: options.serverZip ? (0, utils_1.readFileAsFile)(options.serverZip) : undefined,
+                backendType: bt === 'node' || bt === 'python' ? bt : undefined,
                 backendEntry: options.backendEntry,
                 backendWebsocket: options.backendWebsocket === true ? true : undefined,
                 disableSdkUpdateNotice: options.disableSdkUpdateNotice === true ? true : undefined,
@@ -232,8 +235,9 @@ function registerPluginCommands(program) {
         .option('--description <text>', '插件描述')
         .option('--author <author>', '插件作者')
         .option('--version <ver>', '插件版本')
-        .option('--server-zip <path>', 'JS 后端 zip 包路径')
-        .option('--backend-entry <entry>', 'JS 后端入口文件（默认 index.js）')
+        .option('--server-zip <path>', '后端代码 zip 包路径')
+        .option('--backend-type <type>', '后端类型: node 或 python（默认 node）')
+        .option('--backend-entry <entry>', '后端入口文件（Node.js 默认 index.js，Python 默认 start.py）')
         .option('--backend-websocket', '启用 WebSocket 代理')
         .option('--disable-sdk-update-notice', '禁用 SDK 更新提示')
         .action(async (zipFile, options, cmd) => {
@@ -247,6 +251,7 @@ function registerPluginCommands(program) {
             });
             (0, utils_1.initSDK)(auth);
             const client = new plugin_management_1.PluginManagementClient();
+            const bt = options.backendType;
             const res = await client.update({
                 pluginId: options.pluginId,
                 name: options.name,
@@ -255,6 +260,7 @@ function registerPluginCommands(program) {
                 version: options.version,
                 staticZip: zipFile ? (0, utils_1.readFileAsFile)(zipFile) : undefined,
                 serverZip: options.serverZip ? (0, utils_1.readFileAsFile)(options.serverZip) : undefined,
+                backendType: bt === 'node' || bt === 'python' ? bt : undefined,
                 backendEntry: options.backendEntry,
                 backendWebsocket: options.backendWebsocket === true ? true : undefined,
                 disableSdkUpdateNotice: options.disableSdkUpdateNotice === true ? true : undefined,

package/dist/config.d.ts

@@ -9,7 +9,7 @@
  *
  * 注意: {VERSION} 占位符会在构建时被替换为实际版本号
  */
-export declare const SDK_SIGNATURE = "AI_WORLD_SDK_V:1.5.15";
+export declare const SDK_SIGNATURE = "AI_WORLD_SDK_V:1.5.17";
 /**
  * 版本兼容性错误
  */
@@ -35,8 +35,8 @@ declare class SDKConfig {
     private _authCheckPromise;
     private _currentUser;
     private _cliMode;
-    readonly sdkSignature = "AI_WORLD_SDK_V:1.5.15";
-    readonly sdkVersion = "1.5.15";
+    readonly sdkSignature = "AI_WORLD_SDK_V:1.5.17";
+    readonly sdkVersion = "1.5.17";
     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.15";
+const SDK_VERSION = "1.5.17";
 /**
  * SDK 特征码 - 用于在构建后的 JS 文件中识别 SDK 版本
  * 格式: AI_WORLD_SDK_V:版本号
@@ -15,7 +15,7 @@ const SDK_VERSION = "1.5.15";
  *
  * 注意: {VERSION} 占位符会在构建时被替换为实际版本号
  */
-exports.SDK_SIGNATURE = "AI_WORLD_SDK_V:1.5.15";
+exports.SDK_SIGNATURE = "AI_WORLD_SDK_V:1.5.17";
 /**
  * 版本兼容性错误
  */
@@ -291,6 +291,7 @@ class SDKConfig {
             const path = require('path');
             const fs = require('fs');
             const cwd = process.cwd();
+            console.log('server cwd:', cwd);
             // .env.local 优先级最高（仅次于已有 process.env）
             const envLocalPath = path.resolve(cwd, '.env.local');
             if (fs.existsSync(envLocalPath)) {

package/dist/index.d.ts

@@ -34,7 +34,7 @@ export { VersionedResourceClient, type VersionedResourceClientConfig, type Versi
 export { AgentSkillClient, type AgentSkillClientConfig, type AgentSkillInfo, type AgentSkillListResponse, type ListSkillsOptions, } from "./agent-skills";
 export { AuthClient, getCurrentUserInfo, type AuthConfig, type UserInfo, };
 export { AdminClient, type AdminClientConfig, type AdminUserInfo, type AdminUserListResponse, type ListUsersOptions, type RoleInfo, type CreateRoleData, type UpdateRoleData, type RoleUserCount, type TableColumn, type TableDataResponse, type ListTableDataOptions, } from "./admin";
-export { PluginManagementClient, type PluginManagementClientConfig, type PluginInfo, type PluginListResponse, type ListPluginsOptions, type CreatePluginData, type PluginStatus, type PluginTemplateInfo, type PluginTemplateListResponse, type ListPluginTemplatesOptions, type CreatePluginTemplateData, type UpdatePluginTemplateData, } from "./plugin-management";
+export { PluginManagementClient, type PluginManagementClientConfig, type PluginInfo, type PluginListResponse, type ListPluginsOptions, type CreatePluginData, type UpdatePluginData, type PluginStatus, type RestartServerResult, type PluginTemplateInfo, type PluginTemplateListResponse, type ListPluginTemplatesOptions, type CreatePluginTemplateData, type UpdatePluginTemplateData, } from "./plugin-management";
 export { StatsClient, DashboardClient, type StatsClientConfig, type AiApiCallsOptions, type AiApiCallsTrendOptions, type AiApiCallsTrendByUserOptions, type PluginAccessOptions, } from "./stats";
 export { AIConfigClient, type AIConfigClientConfig, } from "./ai-config";
 export { SharedResourceClient, type SharedResourceClientConfig, type SharedResourceInfo, type SharedResourceListResponse, type ListSharedResourceOptions, type UpdateSharedResourceData, } from "./shared-resource";

package/dist/plugin-management.d.ts

@@ -14,7 +14,13 @@ export interface PluginInfo {
     author?: string;
     version?: string;
     enabled: boolean;
-    has_server: boolean;
+    has_backend?: boolean;
+    backend_type?: "node" | "python";
+    backend_port?: number;
+    backend_running?: boolean;
+    backend_entry?: string;
+    backend_websocket?: boolean;
+    has_static_file?: boolean;
     created_at?: string;
     updated_at?: string;
     [key: string]: any;
@@ -45,6 +51,7 @@ export interface CreatePluginData {
     templateId?: string;
     staticZip?: File | Blob;
     serverZip?: File | Blob;
+    backendType?: "node" | "python";
     backendEntry?: string;
     backendWebsocket?: boolean;
     disableSdkUpdateNotice?: boolean;
@@ -57,6 +64,7 @@ export interface UpdatePluginData {
     version?: string;
     staticZip?: File | Blob;
     serverZip?: File | Blob;
+    backendType?: "node" | "python";
     backendEntry?: string;
     backendWebsocket?: boolean;
     disableSdkUpdateNotice?: boolean;
@@ -64,8 +72,7 @@ export interface UpdatePluginData {
 export interface PluginStatus {
     plugin_id: string;
     enabled: boolean;
-    has_server: boolean;
-    server_running?: boolean;
+    exists: boolean;
     [key: string]: any;
 }
 export interface PluginTemplateInfo {
@@ -92,6 +99,14 @@ export interface ListPluginTemplatesOptions {
     name?: string;
     category?: string;
 }
+export interface RestartServerResult {
+    message: string;
+    plugin_id: string;
+    port: number;
+    backend_type: string;
+    install_logs: string;
+    startup_logs: string;
+}
 export interface CreatePluginTemplateData {
     pluginId: string;
     name: string;
@@ -135,9 +150,7 @@ export declare class PluginManagementClient {
     reload(pluginId: string): Promise<{
         message: string;
     }>;
-    restartServer(pluginId: string): Promise<{
-        message: string;
-    }>;
+    restartServer(pluginId: string): Promise<RestartServerResult>;
     getServerLogs(pluginId: string, lines?: number): Promise<string>;
     listTemplates(): Promise<any[]>;
     getTemplate(templateId: string): Promise<any>;

package/dist/plugin-management.js

@@ -118,6 +118,8 @@ class PluginManagementClient {
             formData.append("static_zip", data.staticZip);
         if (data.serverZip)
             formData.append("server_zip", data.serverZip);
+        if (data.backendType)
+            formData.append("backend_type", data.backendType);
         if (data.backendEntry)
             formData.append("backend_entry", data.backendEntry);
         if (data.backendWebsocket !== undefined)
@@ -153,6 +155,8 @@ class PluginManagementClient {
             formData.append("static_zip", data.staticZip);
         if (data.serverZip)
             formData.append("server_zip", data.serverZip);
+        if (data.backendType)
+            formData.append("backend_type", data.backendType);
         if (data.backendEntry)
             formData.append("backend_entry", data.backendEntry);
         if (data.backendWebsocket !== undefined)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-world-sdk",
-  "version": "1.5.15",
+  "version": "1.5.17",
   "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

@@ -119,11 +119,129 @@ sdkConfig.setToken('your-jwt-token');
 sdkConfig.setPluginId('my-plugin');
 ```
 
-也可通过环境变量自动初始化：
-- `AI_WORLD_BASE_URL` — 服务端地址，插件 JS 后端启动时由平台自动注入
+也可通过环境变量自动初始化（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
+```
+
+在插件前端代码中使用 `sdkConfig` 获取 baseUrl：
+
+```typescript
+import { sdkConfig } from 'ai-world-sdk';
+
+// 插件前端请求插件后端
+const baseUrl = sdkConfig.getServerUrl();
+const pluginId = sdkConfig.getPluginId();
+const response = await fetch(`${baseUrl}/api/${pluginId}/server/api/hello`, {
+  headers: { 'Authorization': `Bearer ${sdkConfig.getToken()}` }
+});
+```
+
+WebSocket 同理：`ws(s)://{host}/api/{plugin-id}/server/ws`
 
 ## 功能模块
 
@@ -269,7 +387,8 @@ for await (const chunk of stream.textStream) {
 - `PluginManagementClient` — 插件 CRUD（`create` / `update` 分离）、启用/禁用/重载/重启、模板管理
   - `create(data)` — 创建新插件（POST `/api/plugins/create`），插件不存在时使用
   - `update(data)` — 更新已有插件（POST `/api/plugins/update`），插件必须已存在，未传入的字段保留原值
-  - 两者均支持: pluginId / name / description / author / version / staticZip / serverZip / backendEntry / backendWebsocket / disableSdkUpdateNotice
+  - 两者均支持: pluginId / name / description / author / version / staticZip / serverZip / backendType / backendEntry / backendWebsocket / disableSdkUpdateNotice
+  - `backendType` — 后端类型：`"node"` 或 `"python"`（默认 node）
 - `StatsClient` — AI 接口调用统计/趋势、插件访问统计（管理员）
 - `DashboardClient` — 当前用户统计（无需管理员权限）
 - `SharedResourceClient` — 平台级文件共享（与 `ResourceClient` 的插件级 ACL 不同）

package/skills/ai-world-sdk/docs/cli-commands.md

@@ -139,7 +139,8 @@ ai-world plugin disable <plugin-id>
 ai-world plugin reload <plugin-id>
 ai-world plugin restart <plugin-id>
 ai-world plugin logs <plugin-id> [--lines 100]
-ai-world plugin create ./plugin.zip --plugin-id my-plugin [--name "My Plugin"] [--description "说明"]
+ai-world plugin create ./plugin.zip --plugin-id my-plugin [--name "My Plugin"] [--description "说明"] [--backend-type node|python] [--server-zip server.zip] [--backend-entry index.js]
+ai-world plugin update [zip-file] --plugin-id <id> [--name "Name"] [--backend-type node|python] [--server-zip server.zip] [--backend-entry entry.js]
 ai-world plugin delete <plugin-id>
 ai-world plugin status <plugin-id>
 ```

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

@@ -19,13 +19,23 @@ const ids = await plugins.listIds(true);  // string[]
 const info = await plugins.get('my-plugin');
 const status = await plugins.getStatus('my-plugin');
 
-// 创建插件
+// 创建插件（Node.js 后端）
 await plugins.create({
   pluginId: 'new-plugin',
   name: '新插件',
   description: '描述',
   staticZip: someZipFile,   // 可选，含 index.html 的 zip
-  serverZip: serverZipFile, // 可选，JS 后端 zip
+  serverZip: serverZipFile, // 可选，后端代码 zip
+  backendType: 'node',      // 可选，'node' | 'python'，默认 'node'
+});
+
+// 创建 Python 后端插件
+await plugins.create({
+  pluginId: 'py-plugin',
+  name: 'Python 插件',
+  serverZip: pyZipFile,
+  backendType: 'python',
+  backendEntry: 'start.py',
 });
 
 // 启用 / 禁用 / 重载 / 重启后端