@kevisual/router 0.0.85 → 0.0.87

package/dist/opencode.d.ts

@@ -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 = {
     /**

package/dist/router-browser.d.ts

@@ -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

@@ -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

@@ -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

@@ -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;

package/dist/router.js

@@ -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 {

package/dist/ws.d.ts

@@ -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 = {
     /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@kevisual/router",
-  "version": "0.0.85",
+  "version": "0.0.87",
   "description": "",
   "type": "module",
   "main": "./dist/router.js",
@@ -27,14 +27,15 @@
     "@kevisual/dts": "^0.0.4",
     "@kevisual/js-filter": "^0.0.5",
     "@kevisual/local-proxy": "^0.0.8",
-    "@kevisual/query": "^0.0.52",
+    "@kevisual/query": "^0.0.53",
     "@kevisual/use-config": "^1.0.30",
-    "@opencode-ai/plugin": "^1.2.16",
+    "@opencode-ai/plugin": "^1.2.20",
     "@types/bun": "^1.3.10",
-    "@types/node": "^25.3.3",
+    "@types/node": "^25.3.5",
     "@types/send": "^1.2.1",
     "@types/ws": "^8.18.1",
     "@types/xml2js": "^0.4.14",
+    "commander": "^14.0.3",
     "eventemitter3": "^5.0.4",
     "fast-glob": "^3.3.3",
     "hono": "^4.12.5",
@@ -59,6 +60,7 @@
   "exports": {
     ".": "./dist/router.js",
     "./browser": "./dist/router-browser.js",
+    "./commander": "./dist/commander.js",
     "./simple": "./dist/router-simple.js",
     "./opencode": "./dist/opencode.js",
     "./skill": "./dist/app.js",

package/src/commander.ts

@@ -0,0 +1,115 @@
+import { program } from 'commander';
+import { App } from './app.ts';
+
+export const groupByPath = (routes: App['routes']) => {
+  return routes.reduce((acc, route) => {
+    const path = route.path || 'default';
+    if (!acc[path]) {
+      acc[path] = [];
+    }
+    acc[path].push(route);
+    return acc;
+  }, {} as Record<string, typeof routes>);
+}
+export const parseArgs = (args: string) => {
+  try {
+    return JSON.parse(args);
+  } catch {
+    // 尝试解析 a=b b=c 格式
+    const result: Record<string, string> = {};
+    const pairs = args.match(/(\S+?)=(\S+)/g);
+    if (pairs && pairs.length > 0) {
+      for (const pair of pairs) {
+        const idx = pair.indexOf('=');
+        const key = pair.slice(0, idx);
+        const value = pair.slice(idx + 1);
+        result[key] = value;
+      }
+      return result;
+    }
+    throw new Error('Invalid arguments: expected JSON or key=value pairs (e.g. a=b c=d)');
+  }
+}
+export const parseDescription = (route: App['routes'][number]) => {
+  let desc = '';
+  if (route.metadata?.skill) {
+    desc += `\n\t=====${route.metadata.skill}=====\n`;
+  }
+  let hasSummary = false;
+  if (route.metadata?.summary) {
+    desc += `\t${route.metadata.summary}`;
+    hasSummary = true;
+  }
+  if (route.metadata?.args) {
+    const argsLines = Object.entries(route.metadata.args).map(([key, schema]: [string, any]) => {
+      const defType: string = schema?._def?.type ?? schema?.type ?? '';
+      const isOptional = defType === 'optional';
+      const innerType: string = isOptional
+        ? (schema?._def?.innerType?.type ?? schema?._def?.innerType?._def?.type ?? '')
+        : defType;
+      const description: string =
+        schema?.description ??
+        schema?._def?.description ??
+        '';
+      const optionalMark = isOptional ? '?' : '';
+      const descPart = description ? `  ${description}` : '';
+      return `\t  - ${key}${optionalMark}: ${innerType}${descPart}`;
+    });
+    desc += '\n\targs:\n' + argsLines.join('\n');
+  }
+  if (route.description && !hasSummary) {
+    desc += `\t - ${route.description}`;
+  }
+  return desc;
+}
+export const createCommand = (opts: { app: App, program: typeof program }) => {
+  const { app, program } = opts;
+  const routes = app.routes;
+
+
+  const groupRoutes = groupByPath(routes);
+  for (const path in groupRoutes) {
+    const routeList = groupRoutes[path];
+    const keys = routeList.map(route => route.key).filter(Boolean);
+    const subProgram = program.command(path).description(`路由《${path}》 ${keys.length > 0 ? ': ' + keys.join(', ') : ''}`);
+    routeList.forEach(route => {
+      if (!route.key) return;
+      const description = parseDescription(route);
+      subProgram.command(route.key)
+        .description(description || '')
+        .option('--args <args>', 'JSON字符串参数，传递给命令执行')
+        .action(async (options) => {
+          const output = (data: any) => {
+            if (typeof data === 'object') {
+              process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+            } else {
+              process.stdout.write(String(data) + '\n');
+            }
+          }
+          try {
+            const args = options.args ? parseArgs(options.args) : {};
+            // 这里可以添加实际的命令执行逻辑，例如调用对应的路由处理函数
+            const res = await app.run({ path, key: route.key, payload: args }, { appId: app.appId });
+            if (res.code === 200) {
+              output(res.data);
+            } else {
+              output(`Error: ${res.message}`);
+            }
+          } catch (error) {
+            output(`Execution error: ${error instanceof Error ? error.message : String(error)}`);
+          }
+        });
+    });
+  }
+}
+
+program.parse(process.argv);
+
+export const parse = (opts: { app: App, description?: string, parse?: boolean }) => {
+  const { app, description, parse } = opts;
+  program.description(description || 'Router 命令行工具');
+  createCommand({ app: app as App, program });
+  if (parse) {
+    program.parse(process.argv);
+  }
+}

package/src/route.ts

@@ -779,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/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 })