@kevisual/router 0.0.84 → 0.0.86

package/dist/app.js

@@ -3091,7 +3091,7 @@ function pick(obj, keys) {
 // node_modules/.pnpm/eventemitter3@5.0.4/node_modules/eventemitter3/index.mjs
 var import__ = __toESM(require_eventemitter3(), 1);
 
-// node_modules/.pnpm/es-toolkit@1.44.0/node_modules/es-toolkit/dist/predicate/isPlainObject.mjs
+// node_modules/.pnpm/es-toolkit@1.45.1/node_modules/es-toolkit/dist/predicate/isPlainObject.mjs
 function isPlainObject(value) {
   if (!value || typeof value !== "object") {
     return false;
@@ -3104,12 +3104,12 @@ function isPlainObject(value) {
   return Object.prototype.toString.call(value) === "[object Object]";
 }
 
-// node_modules/.pnpm/es-toolkit@1.44.0/node_modules/es-toolkit/dist/_internal/isUnsafeProperty.mjs
+// node_modules/.pnpm/es-toolkit@1.45.1/node_modules/es-toolkit/dist/_internal/isUnsafeProperty.mjs
 function isUnsafeProperty(key) {
   return key === "__proto__";
 }
 
-// node_modules/.pnpm/es-toolkit@1.44.0/node_modules/es-toolkit/dist/object/merge.mjs
+// node_modules/.pnpm/es-toolkit@1.45.1/node_modules/es-toolkit/dist/object/merge.mjs
 function merge(target, source) {
   const sourceKeys = Object.keys(source);
   for (let i = 0;i < sourceKeys.length; i++) {
@@ -16932,7 +16932,7 @@ class Route {
     if (opts) {
       this.id = opts.id || randomId(12, "rand-");
       if (!opts.id && opts.idUsePath) {
-        const delimiter = opts.delimiter ?? "$#$";
+        const delimiter = opts.delimiter ?? "$$";
         this.id = path + delimiter + key;
       }
       this.run = opts.run;
@@ -17419,6 +17419,10 @@ class QueryRouterServer extends QueryRouter {
     }
     return super.run(msg, ctx);
   }
+  async runAction(api2, payload, ctx) {
+    const { path, key, id } = api2;
+    return this.run({ path, key, id, payload }, ctx);
+  }
 }
 
 // src/server/server.ts
@@ -17914,7 +17918,7 @@ class ServerBase {
     }
   }
   async onWsClose(ws) {
-    const id = ws?.data?.id || "";
+    const id = ws?.wsId || "";
     if (id) {
       this.emitter.emit("close--" + id, { type: "close", ws, id });
       setTimeout(() => {
@@ -17927,6 +17931,9 @@ class ServerBase {
     if (this.showConnected)
       ws.send(JSON.stringify({ type: "connected" }));
   }
+  createId() {
+    return Math.random().toString(36).substring(2, 15);
+  }
 }
 
 // node_modules/.pnpm/@kevisual+ws@8.0.0/node_modules/@kevisual/ws/wrapper.mjs
@@ -17967,6 +17974,9 @@ class WsServerBase {
         token,
         id
       };
+      if (!ws.wsId) {
+        ws.wsId = this.createId();
+      }
       ws.on("message", async (message) => {
         await this.server.onWebSocket({ ws, message, pathname, token, id });
       });
@@ -17977,6 +17987,9 @@ class WsServerBase {
       });
     });
   }
+  createId() {
+    return Math.random().toString(36).substring(2, 15);
+  }
 }
 
 class WsServer extends WsServerBase {
@@ -18292,10 +18305,14 @@ class BunServer extends ServerBase {
         open: (ws) => {
           this.sendConnected(ws);
         },
-        message: async (ws, message) => {
+        message: async (bunWs, message) => {
+          const ws = bunWs;
           const pathname = ws.data.pathname || "";
           const token = ws.data.token || "";
           const id = ws.data.id || "";
+          if (!ws.wsId) {
+            ws.wsId = this.createId();
+          }
           await this.onWebSocket({ ws, message, pathname, token, id });
         },
         close: (ws) => {
@@ -19562,7 +19579,7 @@ app
 10. **中间件找不到会返回 404**，错误信息中会包含找不到的中间件列表。
 `;
 // package.json
-var version2 = "0.0.84";
+var version2 = "0.0.86";
 
 // agent/routes/route-create.ts
 app.route({

package/dist/opencode.d.ts

@@ -146,7 +146,7 @@ type RouteOpts<U = {}, T = SimpleObject> = {
     description?: string;
     metadata?: T;
     middleware?: RouteMiddleware[];
-    type?: 'route' | 'middleware';
+    type?: 'route' | 'middleware' | 'compound';
     /**
      * $#$ will be used to split path and key
      */
@@ -450,7 +450,52 @@ declare class QueryRouterServer<C extends SimpleObject = SimpleObject> extends Q
         key?: string;
         payload?: any;
     }, ctx?: Partial<RouteContext<C>>): Promise<any>;
+    runAction<T extends {
+        id?: string;
+        path?: string;
+        key?: string;
+        metadata?: {
+            args?: any;
+        };
+    } = {}>(api: T, payload: RunActionPayload<T>, ctx?: RouteContext<C>): Promise<any>;
 }
+/** JSON Schema 基本类型映射到 TypeScript 类型 */
+type JsonSchemaTypeToTS<T> = T extends {
+    type: "string";
+} ? string : T extends {
+    type: "boolean";
+} ? boolean : T extends {
+    type: "number";
+} ? number : T extends {
+    type: "integer";
+} ? number : T extends {
+    type: "object";
+} ? object : T extends {
+    type: "array";
+} ? any[] : any;
+/** 将 args shape（key -> JSON Schema 类型）转换为 payload 类型，支持 optional: true 的字段为可选 */
+type ArgsShapeToPayload<T> = {
+    [K in keyof T as T[K] extends {
+        optional: true;
+    } ? never : K]: JsonSchemaTypeToTS<T[K]>;
+} & {
+    [K in keyof T as T[K] extends {
+        optional: true;
+    } ? K : never]?: JsonSchemaTypeToTS<T[K]>;
+};
+/** 处理两种 args 格式：完整 JSON Schema（含 properties）或简单 key->type 映射 */
+type ArgsToPayload<T> = T extends {
+    type: "object";
+    properties: infer P;
+} ? ArgsShapeToPayload<P> : ArgsShapeToPayload<T>;
+/** 从 API 定义中提取 metadata.args */
+type ExtractArgs<T> = T extends {
+    metadata: {
+        args: infer A;
+    };
+} ? A : {};
+/** runAction 第二个参数的类型，根据第一个参数的 metadata.args 推断 */
+type RunActionPayload<T> = ArgsToPayload<ExtractArgs<T>>;
 
 type Cors = {
     /**
@@ -503,15 +548,32 @@ type OnWebSocketOptions<T = {}> = {
     message: string | Buffer;
     pathname: string;
     token?: string;
+    /** data 的id提取出来 */
     id?: string;
 };
 type WS<T = {}> = {
     send: (data: any) => void;
     close: (code?: number, reason?: string) => void;
+    /**
+   * ws 自己生成的一个id，主要是为了区分不同的ws连接，方便在onWebSocket中使用
+   */
+    wsId?: string;
     data?: {
+        /**
+         * ws连接时的url，包含pathname和searchParams
+         */
         url: URL;
+        /**
+         * ws连接时的pathname
+         */
         pathname: string;
+        /**
+         * ws连接时的url中的token参数
+         */
         token?: string;
+        /**
+         * ws连接时的url中的id参数.
+         */
         id?: string;
         /**
          * 鉴权后的获取的信息

package/dist/router-browser.d.ts

@@ -187,7 +187,7 @@ type RouteOpts<U = {}, T = SimpleObject$1> = {
     description?: string;
     metadata?: T;
     middleware?: RouteMiddleware[];
-    type?: 'route' | 'middleware';
+    type?: 'route' | 'middleware' | 'compound';
     /**
      * $#$ will be used to split path and key
      */
@@ -522,9 +522,54 @@ declare class QueryRouterServer<C extends SimpleObject$1 = SimpleObject$1> exten
         key?: string;
         payload?: any;
     }, ctx?: Partial<RouteContext<C>>): Promise<any>;
+    runAction<T extends {
+        id?: string;
+        path?: string;
+        key?: string;
+        metadata?: {
+            args?: any;
+        };
+    } = {}>(api: T, payload: RunActionPayload<T>, ctx?: RouteContext<C>): Promise<any>;
 }
 declare class Mini extends QueryRouterServer {
 }
+/** JSON Schema 基本类型映射到 TypeScript 类型 */
+type JsonSchemaTypeToTS<T> = T extends {
+    type: "string";
+} ? string : T extends {
+    type: "boolean";
+} ? boolean : T extends {
+    type: "number";
+} ? number : T extends {
+    type: "integer";
+} ? number : T extends {
+    type: "object";
+} ? object : T extends {
+    type: "array";
+} ? any[] : any;
+/** 将 args shape（key -> JSON Schema 类型）转换为 payload 类型，支持 optional: true 的字段为可选 */
+type ArgsShapeToPayload<T> = {
+    [K in keyof T as T[K] extends {
+        optional: true;
+    } ? never : K]: JsonSchemaTypeToTS<T[K]>;
+} & {
+    [K in keyof T as T[K] extends {
+        optional: true;
+    } ? K : never]?: JsonSchemaTypeToTS<T[K]>;
+};
+/** 处理两种 args 格式：完整 JSON Schema（含 properties）或简单 key->type 映射 */
+type ArgsToPayload<T> = T extends {
+    type: "object";
+    properties: infer P;
+} ? ArgsShapeToPayload<P> : ArgsShapeToPayload<T>;
+/** 从 API 定义中提取 metadata.args */
+type ExtractArgs<T> = T extends {
+    metadata: {
+        args: infer A;
+    };
+} ? A : {};
+/** runAction 第二个参数的类型，根据第一个参数的 metadata.args 推断 */
+type RunActionPayload<T> = ArgsToPayload<ExtractArgs<T>>;
 
 type BaseRule = {
     value?: any;

package/dist/router-browser.js

@@ -280,7 +280,7 @@ function pick(obj, keys) {
 // node_modules/.pnpm/eventemitter3@5.0.4/node_modules/eventemitter3/index.mjs
 var import__ = __toESM(require_eventemitter3(), 1);
 
-// node_modules/.pnpm/es-toolkit@1.44.0/node_modules/es-toolkit/dist/predicate/isPlainObject.mjs
+// node_modules/.pnpm/es-toolkit@1.45.1/node_modules/es-toolkit/dist/predicate/isPlainObject.mjs
 function isPlainObject(value) {
   if (!value || typeof value !== "object") {
     return false;
@@ -293,12 +293,12 @@ function isPlainObject(value) {
   return Object.prototype.toString.call(value) === "[object Object]";
 }
 
-// node_modules/.pnpm/es-toolkit@1.44.0/node_modules/es-toolkit/dist/_internal/isUnsafeProperty.mjs
+// node_modules/.pnpm/es-toolkit@1.45.1/node_modules/es-toolkit/dist/_internal/isUnsafeProperty.mjs
 function isUnsafeProperty(key) {
   return key === "__proto__";
 }
 
-// node_modules/.pnpm/es-toolkit@1.44.0/node_modules/es-toolkit/dist/object/merge.mjs
+// node_modules/.pnpm/es-toolkit@1.45.1/node_modules/es-toolkit/dist/object/merge.mjs
 function merge(target, source) {
   const sourceKeys = Object.keys(source);
   for (let i = 0;i < sourceKeys.length; i++) {
@@ -14096,7 +14096,7 @@ class Route {
     if (opts) {
       this.id = opts.id || randomId(12, "rand-");
       if (!opts.id && opts.idUsePath) {
-        const delimiter = opts.delimiter ?? "$#$";
+        const delimiter = opts.delimiter ?? "$$";
         this.id = path + delimiter + key;
       }
       this.run = opts.run;
@@ -14583,6 +14583,10 @@ class QueryRouterServer extends QueryRouter {
     }
     return super.run(msg, ctx);
   }
+  async runAction(api2, payload, ctx) {
+    const { path, key, id } = api2;
+    return this.run({ path, key, id, payload }, ctx);
+  }
 }
 
 class Mini extends QueryRouterServer {

package/dist/router-define.d.ts

@@ -143,7 +143,7 @@ type RouteOpts<U = {}, T = SimpleObject$1> = {
     description?: string;
     metadata?: T;
     middleware?: RouteMiddleware[];
-    type?: 'route' | 'middleware';
+    type?: 'route' | 'middleware' | 'compound';
     /**
      * $#$ will be used to split path and key
      */
@@ -447,7 +447,52 @@ declare class QueryRouterServer<C extends SimpleObject$1 = SimpleObject$1> exten
         key?: string;
         payload?: any;
     }, ctx?: Partial<RouteContext<C>>): Promise<any>;
+    runAction<T extends {
+        id?: string;
+        path?: string;
+        key?: string;
+        metadata?: {
+            args?: any;
+        };
+    } = {}>(api: T, payload: RunActionPayload<T>, ctx?: RouteContext<C>): Promise<any>;
 }
+/** JSON Schema 基本类型映射到 TypeScript 类型 */
+type JsonSchemaTypeToTS<T> = T extends {
+    type: "string";
+} ? string : T extends {
+    type: "boolean";
+} ? boolean : T extends {
+    type: "number";
+} ? number : T extends {
+    type: "integer";
+} ? number : T extends {
+    type: "object";
+} ? object : T extends {
+    type: "array";
+} ? any[] : any;
+/** 将 args shape（key -> JSON Schema 类型）转换为 payload 类型，支持 optional: true 的字段为可选 */
+type ArgsShapeToPayload<T> = {
+    [K in keyof T as T[K] extends {
+        optional: true;
+    } ? never : K]: JsonSchemaTypeToTS<T[K]>;
+} & {
+    [K in keyof T as T[K] extends {
+        optional: true;
+    } ? K : never]?: JsonSchemaTypeToTS<T[K]>;
+};
+/** 处理两种 args 格式：完整 JSON Schema（含 properties）或简单 key->type 映射 */
+type ArgsToPayload<T> = T extends {
+    type: "object";
+    properties: infer P;
+} ? ArgsShapeToPayload<P> : ArgsShapeToPayload<T>;
+/** 从 API 定义中提取 metadata.args */
+type ExtractArgs<T> = T extends {
+    metadata: {
+        args: infer A;
+    };
+} ? A : {};
+/** runAction 第二个参数的类型，根据第一个参数的 metadata.args 推断 */
+type RunActionPayload<T> = ArgsToPayload<ExtractArgs<T>>;
 
 type RouteObject = {
     [key: string]: RouteOpts;

package/dist/router.d.ts

@@ -193,7 +193,7 @@ type RouteOpts<U = {}, T = SimpleObject$1> = {
     description?: string;
     metadata?: T;
     middleware?: RouteMiddleware[];
-    type?: 'route' | 'middleware';
+    type?: 'route' | 'middleware' | 'compound';
     /**
      * $#$ will be used to split path and key
      */
@@ -528,9 +528,54 @@ declare class QueryRouterServer<C extends SimpleObject$1 = SimpleObject$1> exten
         key?: string;
         payload?: any;
     }, ctx?: Partial<RouteContext<C>>): Promise<any>;
+    runAction<T extends {
+        id?: string;
+        path?: string;
+        key?: string;
+        metadata?: {
+            args?: any;
+        };
+    } = {}>(api: T, payload: RunActionPayload<T>, ctx?: RouteContext<C>): Promise<any>;
 }
 declare class Mini extends QueryRouterServer {
 }
+/** JSON Schema 基本类型映射到 TypeScript 类型 */
+type JsonSchemaTypeToTS<T> = T extends {
+    type: "string";
+} ? string : T extends {
+    type: "boolean";
+} ? boolean : T extends {
+    type: "number";
+} ? number : T extends {
+    type: "integer";
+} ? number : T extends {
+    type: "object";
+} ? object : T extends {
+    type: "array";
+} ? any[] : any;
+/** 将 args shape（key -> JSON Schema 类型）转换为 payload 类型，支持 optional: true 的字段为可选 */
+type ArgsShapeToPayload<T> = {
+    [K in keyof T as T[K] extends {
+        optional: true;
+    } ? never : K]: JsonSchemaTypeToTS<T[K]>;
+} & {
+    [K in keyof T as T[K] extends {
+        optional: true;
+    } ? K : never]?: JsonSchemaTypeToTS<T[K]>;
+};
+/** 处理两种 args 格式：完整 JSON Schema（含 properties）或简单 key->type 映射 */
+type ArgsToPayload<T> = T extends {
+    type: "object";
+    properties: infer P;
+} ? ArgsShapeToPayload<P> : ArgsShapeToPayload<T>;
+/** 从 API 定义中提取 metadata.args */
+type ExtractArgs<T> = T extends {
+    metadata: {
+        args: infer A;
+    };
+} ? A : {};
+/** runAction 第二个参数的类型，根据第一个参数的 metadata.args 推断 */
+type RunActionPayload<T> = ArgsToPayload<ExtractArgs<T>>;
 
 type BaseRule = {
     value?: any;
@@ -688,16 +733,33 @@ type OnWebSocketOptions<T = {}> = {
     message: string | Buffer;
     pathname: string;
     token?: string;
+    /** data 的id提取出来 */
     id?: string;
 };
 type OnWebSocketFn = (options: OnWebSocketOptions) => Promise<void> | void;
 type WS<T = {}> = {
     send: (data: any) => void;
     close: (code?: number, reason?: string) => void;
+    /**
+   * ws 自己生成的一个id，主要是为了区分不同的ws连接，方便在onWebSocket中使用
+   */
+    wsId?: string;
     data?: {
+        /**
+         * ws连接时的url，包含pathname和searchParams
+         */
         url: URL;
+        /**
+         * ws连接时的pathname
+         */
         pathname: string;
+        /**
+         * ws连接时的url中的token参数
+         */
         token?: string;
+        /**
+         * ws连接时的url中的id参数.
+         */
         id?: string;
         /**
          * 鉴权后的获取的信息
@@ -916,6 +978,7 @@ declare class ServerBase implements ServerType {
      */
     onWsClose(ws: WS): Promise<void>;
     sendConnected(ws: WS): Promise<void>;
+    createId(): string;
 }
 
 type WsServerBaseOpts = {
@@ -928,6 +991,7 @@ declare class WsServerBase {
     server: ServerType;
     constructor(opts: WsServerBaseOpts);
     listen(): void;
+    createId(): string;
 }
 declare class WsServer extends WsServerBase {
     constructor(server: ServerType);

package/dist/router.js

@@ -3091,7 +3091,7 @@ function pick(obj, keys) {
 // node_modules/.pnpm/eventemitter3@5.0.4/node_modules/eventemitter3/index.mjs
 var import__ = __toESM(require_eventemitter3(), 1);
 
-// node_modules/.pnpm/es-toolkit@1.44.0/node_modules/es-toolkit/dist/predicate/isPlainObject.mjs
+// node_modules/.pnpm/es-toolkit@1.45.1/node_modules/es-toolkit/dist/predicate/isPlainObject.mjs
 function isPlainObject(value) {
   if (!value || typeof value !== "object") {
     return false;
@@ -3104,12 +3104,12 @@ function isPlainObject(value) {
   return Object.prototype.toString.call(value) === "[object Object]";
 }
 
-// node_modules/.pnpm/es-toolkit@1.44.0/node_modules/es-toolkit/dist/_internal/isUnsafeProperty.mjs
+// node_modules/.pnpm/es-toolkit@1.45.1/node_modules/es-toolkit/dist/_internal/isUnsafeProperty.mjs
 function isUnsafeProperty(key) {
   return key === "__proto__";
 }
 
-// node_modules/.pnpm/es-toolkit@1.44.0/node_modules/es-toolkit/dist/object/merge.mjs
+// node_modules/.pnpm/es-toolkit@1.45.1/node_modules/es-toolkit/dist/object/merge.mjs
 function merge(target, source) {
   const sourceKeys = Object.keys(source);
   for (let i = 0;i < sourceKeys.length; i++) {
@@ -16929,7 +16929,7 @@ class Route {
     if (opts) {
       this.id = opts.id || randomId(12, "rand-");
       if (!opts.id && opts.idUsePath) {
-        const delimiter = opts.delimiter ?? "$#$";
+        const delimiter = opts.delimiter ?? "$$";
         this.id = path + delimiter + key;
       }
       this.run = opts.run;
@@ -17416,6 +17416,10 @@ class QueryRouterServer extends QueryRouter {
     }
     return super.run(msg, ctx);
   }
+  async runAction(api2, payload, ctx) {
+    const { path, key, id } = api2;
+    return this.run({ path, key, id, payload }, ctx);
+  }
 }
 
 class Mini extends QueryRouterServer {
@@ -18088,7 +18092,7 @@ class ServerBase {
     }
   }
   async onWsClose(ws) {
-    const id = ws?.data?.id || "";
+    const id = ws?.wsId || "";
     if (id) {
       this.emitter.emit("close--" + id, { type: "close", ws, id });
       setTimeout(() => {
@@ -18101,6 +18105,9 @@ class ServerBase {
     if (this.showConnected)
       ws.send(JSON.stringify({ type: "connected" }));
   }
+  createId() {
+    return Math.random().toString(36).substring(2, 15);
+  }
 }
 
 // node_modules/.pnpm/@kevisual+ws@8.0.0/node_modules/@kevisual/ws/wrapper.mjs
@@ -18141,6 +18148,9 @@ class WsServerBase {
         token,
         id
       };
+      if (!ws.wsId) {
+        ws.wsId = this.createId();
+      }
       ws.on("message", async (message) => {
         await this.server.onWebSocket({ ws, message, pathname, token, id });
       });
@@ -18151,6 +18161,9 @@ class WsServerBase {
       });
     });
   }
+  createId() {
+    return Math.random().toString(36).substring(2, 15);
+  }
 }
 
 class WsServer extends WsServerBase {
@@ -18465,10 +18478,14 @@ class BunServer extends ServerBase {
         open: (ws) => {
           this.sendConnected(ws);
         },
-        message: async (ws, message) => {
+        message: async (bunWs, message) => {
+          const ws = bunWs;
           const pathname = ws.data.pathname || "";
           const token = ws.data.token || "";
           const id = ws.data.id || "";
+          if (!ws.wsId) {
+            ws.wsId = this.createId();
+          }
           await this.onWebSocket({ ws, message, pathname, token, id });
         },
         close: (ws) => {

package/dist/ws.d.ts

@@ -193,7 +193,7 @@ type RouteOpts<U = {}, T = SimpleObject> = {
     description?: string;
     metadata?: T;
     middleware?: RouteMiddleware[];
-    type?: 'route' | 'middleware';
+    type?: 'route' | 'middleware' | 'compound';
     /**
      * $#$ will be used to split path and key
      */
@@ -497,7 +497,52 @@ declare class QueryRouterServer<C extends SimpleObject = SimpleObject> extends Q
         key?: string;
         payload?: any;
     }, ctx?: Partial<RouteContext<C>>): Promise<any>;
+    runAction<T extends {
+        id?: string;
+        path?: string;
+        key?: string;
+        metadata?: {
+            args?: any;
+        };
+    } = {}>(api: T, payload: RunActionPayload<T>, ctx?: RouteContext<C>): Promise<any>;
 }
+/** JSON Schema 基本类型映射到 TypeScript 类型 */
+type JsonSchemaTypeToTS<T> = T extends {
+    type: "string";
+} ? string : T extends {
+    type: "boolean";
+} ? boolean : T extends {
+    type: "number";
+} ? number : T extends {
+    type: "integer";
+} ? number : T extends {
+    type: "object";
+} ? object : T extends {
+    type: "array";
+} ? any[] : any;
+/** 将 args shape（key -> JSON Schema 类型）转换为 payload 类型，支持 optional: true 的字段为可选 */
+type ArgsShapeToPayload<T> = {
+    [K in keyof T as T[K] extends {
+        optional: true;
+    } ? never : K]: JsonSchemaTypeToTS<T[K]>;
+} & {
+    [K in keyof T as T[K] extends {
+        optional: true;
+    } ? K : never]?: JsonSchemaTypeToTS<T[K]>;
+};
+/** 处理两种 args 格式：完整 JSON Schema（含 properties）或简单 key->type 映射 */
+type ArgsToPayload<T> = T extends {
+    type: "object";
+    properties: infer P;
+} ? ArgsShapeToPayload<P> : ArgsShapeToPayload<T>;
+/** 从 API 定义中提取 metadata.args */
+type ExtractArgs<T> = T extends {
+    metadata: {
+        args: infer A;
+    };
+} ? A : {};
+/** runAction 第二个参数的类型，根据第一个参数的 metadata.args 推断 */
+type RunActionPayload<T> = ArgsToPayload<ExtractArgs<T>>;
 
 type Cors = {
     /**
@@ -550,15 +595,32 @@ type OnWebSocketOptions<T = {}> = {
     message: string | Buffer;
     pathname: string;
     token?: string;
+    /** data 的id提取出来 */
     id?: string;
 };
 type WS<T = {}> = {
     send: (data: any) => void;
     close: (code?: number, reason?: string) => void;
+    /**
+   * ws 自己生成的一个id，主要是为了区分不同的ws连接，方便在onWebSocket中使用
+   */
+    wsId?: string;
     data?: {
+        /**
+         * ws连接时的url，包含pathname和searchParams
+         */
         url: URL;
+        /**
+         * ws连接时的pathname
+         */
         pathname: string;
+        /**
+         * ws连接时的url中的token参数
+         */
         token?: string;
+        /**
+         * ws连接时的url中的id参数.
+         */
         id?: string;
         /**
          * 鉴权后的获取的信息

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@kevisual/router",
-  "version": "0.0.84",
+  "version": "0.0.86",
   "description": "",
   "type": "module",
   "main": "./dist/router.js",
@@ -27,17 +27,17 @@
     "@kevisual/dts": "^0.0.4",
     "@kevisual/js-filter": "^0.0.5",
     "@kevisual/local-proxy": "^0.0.8",
-    "@kevisual/query": "^0.0.49",
+    "@kevisual/query": "^0.0.53",
     "@kevisual/use-config": "^1.0.30",
-    "@opencode-ai/plugin": "^1.2.10",
-    "@types/bun": "^1.3.9",
-    "@types/node": "^25.3.0",
+    "@opencode-ai/plugin": "^1.2.20",
+    "@types/bun": "^1.3.10",
+    "@types/node": "^25.3.5",
     "@types/send": "^1.2.1",
     "@types/ws": "^8.18.1",
     "@types/xml2js": "^0.4.14",
     "eventemitter3": "^5.0.4",
     "fast-glob": "^3.3.3",
-    "hono": "^4.12.2",
+    "hono": "^4.12.5",
     "nanoid": "^5.1.6",
     "path-to-regexp": "^8.3.0",
     "send": "^1.2.1",
@@ -51,7 +51,7 @@
     "url": "git+https://github.com/abearxiong/kevisual-router.git"
   },
   "dependencies": {
-    "es-toolkit": "^1.44.0"
+    "es-toolkit": "^1.45.1"
   },
   "publishConfig": {
     "access": "public"

package/src/route.ts

@@ -7,14 +7,6 @@ import * as schema from './validator/schema.ts';
 
 export type RouterContextT = { code?: number;[key: string]: any };
 
-type ExtractArgs<A> = A extends z.ZodTypeAny ? z.infer<A> : A;
-
-type OptionalKeys<T> = {
-  [K in keyof T]-?: {} extends Pick<T, K> ? K : never;
-}[keyof T];
-
-type MakeOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
-
 type BuildRouteContext<M, U> = M extends { args?: infer A }
   ? A extends z.ZodObject<any>
   ? RouteContext<{ args?: z.infer<A> }, U>
@@ -103,7 +95,7 @@ export type RouteOpts<U = {}, T = SimpleObject> = {
   description?: string;
   metadata?: T;
   middleware?: RouteMiddleware[]; // middleware
-  type?: 'route' | 'middleware';
+  type?: 'route' | 'middleware' | 'compound'; // compound表示这个 route 作为一个聚合体，没有实际的 run，而是一个 router 的聚合列表
   /**
    * $#$ will be used to split path and key
    */
@@ -146,8 +138,6 @@ export const createSkill = <T = SimpleObject>(skill: Skill<T>): Skill<T> => {
 
 export type RouteInfo = Pick<Route, (typeof pickValue)[number]>;
 
-type ExtractMetadata<M> = M extends { metadata?: infer Meta } ? Meta extends SimpleObject ? Meta : SimpleObject : SimpleObject;
-
 /**
  * @M 是 route的 metadate的类型，默认是 SimpleObject
  * @U 是 RouteContext 里 state的类型
@@ -183,7 +173,7 @@ export class Route<M extends SimpleObject = SimpleObject, U extends SimpleObject
     if (opts) {
       this.id = opts.id || randomId(12, 'rand-');
       if (!opts.id && opts.idUsePath) {
-        const delimiter = opts.delimiter ?? '$#$';
+        const delimiter = opts.delimiter ?? '$$';
         this.id = path + delimiter + key;
       }
       this.run = opts.run as Run<BuildRouteContext<M, U>>;
@@ -789,8 +779,44 @@ export class QueryRouterServer<C extends SimpleObject = SimpleObject> extends Qu
     }
     return super.run(msg, ctx as RouteContext<C>);
   }
+
+  async runAction<T extends { id?: string; path?: string; key?: string; metadata?: { args?: any } } = {}>(
+    api: T,
+    payload: RunActionPayload<T>,
+    ctx?: RouteContext<C>
+  ) {
+    const { path, key, id } = api as any;
+    return this.run({ path, key, id, payload }, ctx);
+  }
 }
 
 
 export class Mini extends QueryRouterServer { }
 
+/** JSON Schema 基本类型映射到 TypeScript 类型 */
+type JsonSchemaTypeToTS<T> =
+  T extends { type: "string" } ? string :
+  T extends { type: "boolean" } ? boolean :
+  T extends { type: "number" } ? number :
+  T extends { type: "integer" } ? number :
+  T extends { type: "object" } ? object :
+  T extends { type: "array" } ? any[] :
+  any;
+
+/** 将 args shape（key -> JSON Schema 类型）转换为 payload 类型，支持 optional: true 的字段为可选 */
+type ArgsShapeToPayload<T> =
+  { [K in keyof T as T[K] extends { optional: true } ? never : K]: JsonSchemaTypeToTS<T[K]> } &
+  { [K in keyof T as T[K] extends { optional: true } ? K : never]?: JsonSchemaTypeToTS<T[K]> };
+
+/** 处理两种 args 格式：完整 JSON Schema（含 properties）或简单 key->type 映射 */
+type ArgsToPayload<T> =
+  T extends { type: "object"; properties: infer P }
+  ? ArgsShapeToPayload<P>
+  : ArgsShapeToPayload<T>;
+
+/** 从 API 定义中提取 metadata.args */
+type ExtractArgs<T> =
+  T extends { metadata: { args: infer A } } ? A : {};
+
+/** runAction 第二个参数的类型，根据第一个参数的 metadata.args 推断 */
+export type RunActionPayload<T> = ArgsToPayload<ExtractArgs<T>>;

package/src/server/server-base.ts

@@ -284,7 +284,7 @@ export class ServerBase implements ServerType {
    * @param ws 
    */
   async onWsClose(ws: WS) {
-    const id = ws?.data?.id || '';
+    const id = ws?.wsId || '';
     if (id) {
       this.emitter.emit('close--' + id, { type: 'close', ws, id });
       setTimeout(() => {
@@ -298,4 +298,7 @@ export class ServerBase implements ServerType {
     if (this.showConnected)
       ws.send(JSON.stringify({ type: 'connected' }));
   }
+  createId() {
+    return Math.random().toString(36).substring(2, 15);
+  }
 }

package/src/server/server-bun.ts

@@ -4,7 +4,7 @@
  * @tags bun, server, websocket, http
  * @createdAt 2025-12-20
  */
-import { ServerType, type ServerOpts, type Cors, RouterRes, RouterReq } from './server-type.ts';
+import { ServerType, type ServerOpts, type Cors, RouterRes, RouterReq, WS } from './server-type.ts';
 import { ServerBase } from './server-base.ts';
 
 export class BunServer extends ServerBase implements ServerType {
@@ -264,10 +264,14 @@ export class BunServer extends ServerBase implements ServerType {
         open: (ws: any) => {
           this.sendConnected(ws);
         },
-        message: async (ws: any, message: string | Buffer) => {
+        message: async (bunWs: any, message: string | Buffer) => {
+          const ws = bunWs as WS;
           const pathname = ws.data.pathname || '';
           const token = ws.data.token || '';
           const id = ws.data.id || '';
+          if (!ws.wsId) {
+            ws.wsId = this.createId();
+          }
           await this.onWebSocket({ ws, message, pathname, token, id });
         },
         close: (ws: any) => {

package/src/server/server-type.ts

@@ -49,16 +49,33 @@ export type OnWebSocketOptions<T = {}> = {
   message: string | Buffer;
   pathname: string,
   token?: string,
+  /** data 的id提取出来 */
   id?: string,
 }
 export type OnWebSocketFn = (options: OnWebSocketOptions) => Promise<void> | void;
 export type WS<T = {}> = {
   send: (data: any) => void;
   close: (code?: number, reason?: string) => void;
+  /**
+ * ws 自己生成的一个id，主要是为了区分不同的ws连接，方便在onWebSocket中使用
+ */
+  wsId?: string;
   data?: {
+    /**
+     * ws连接时的url，包含pathname和searchParams
+     */
     url: URL;
+    /**
+     * ws连接时的pathname
+     */
     pathname: string;
+    /**
+     * ws连接时的url中的token参数
+     */
     token?: string;
+    /**
+     * ws连接时的url中的id参数.
+     */
     id?: string;
     /**
      * 鉴权后的获取的信息

package/src/server/ws-server.ts

@@ -56,6 +56,11 @@ export class WsServerBase {
         token,
         id,
       }
+      // @ts-ignore
+      if (!ws.wsId) {
+        // @ts-ignore
+        ws.wsId = this.createId();
+      }
       ws.on('message', async (message: string | Buffer) => {
         await this.server.onWebSocket({ ws, message, pathname, token, id });
       });
@@ -66,7 +71,9 @@ export class WsServerBase {
         this.server.onWsClose(ws);
       });
     });
-
+  }
+  createId() {
+    return Math.random().toString(36).substring(2, 15);
   }
 }
 // TODO: ws handle and path and routerContext

package/src/test/run-schema.ts

@@ -0,0 +1,87 @@
+import z from "zod";
+import { App } from "../index.ts";
+
+const app = new App();
+const api = {
+  "app_domain_manager": {
+    /**
+     * 获取域名信息，可以通过id或者domain进行查询
+     *
+     * @param data - Request parameters
+     * @param data.data - {object}
+     */
+    "get": {
+      "path": "app_domain_manager",
+      "key": "get",
+      "description": "获取域名信息，可以通过id或者domain进行查询",
+      "metadata": {
+        "args": {
+          "data": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "domain": {
+                "type": "string"
+              }
+            },
+            "additionalProperties": false,
+            "required": ["id",]
+          }
+        },
+        "viewItem": {
+          "api": {
+            "url": "/api/router"
+          },
+          "type": "api",
+          "title": "路由"
+        },
+        "url": "/api/router",
+        "source": "query-proxy-api"
+      }
+    },
+    "delete": {
+      "path": "app_domain_manager",
+      "key": "delete",
+      "description": "删除域名",
+      "metadata": {
+        "args": {
+          "domainId": {
+            "type": "string",
+            "optional": true
+          }
+        }
+      }
+    }
+  },
+  "user_manager": {
+    "getUser": {
+      "path": "user_manager",
+      "key": "getUser",
+      "description": "获取用户信息",
+      "metadata": {
+        "args": {
+          "userId": {
+            "type": "string"
+          },
+          "includeProfile": {
+            "type": "boolean"
+          }
+        }
+      }
+    }
+  }
+} as const;
+type API = typeof api;
+
+// 类型推断生效：payload 根据 metadata.args 自动推断
+// get 的 args.data 是 type:"object"，所以 payload 需要 { data: object }
+app.runAction(api.app_domain_manager.get, { data: { id: "1" } })
+
+// delete 的 args 是 { domainId: { type: "string" } }，所以 payload 需要 { domainId: string }
+app.runAction(api.app_domain_manager.delete, { domainId: "d1" })
+
+// getUser 的 args 是 { userId: string, includeProfile: boolean }
+app.runAction(api.user_manager.getUser, { userId: "u1", includeProfile: true })