@kevisual/router 0.2.11 → 0.2.14

package/dist/ws.d.ts

@@ -76,6 +76,57 @@ declare class MockProcess {
     desctroy(): void;
 }
 
+/** 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 : {};
+/** 从 API 定义中提取 metadata.returns */
+type ExtractReturns<T> = T extends {
+    metadata: {
+        returns: infer R;
+    };
+} ? R : unknown;
+/** runAction 第二个参数的类型，根据第一个参数的 metadata.args 推断 */
+type RunActionPayload<T> = ArgsToPayload<ExtractArgs<T>>;
+/** runAction 的返回类型，根据 API 定义中的 metadata.returns 推断 data 字段类型 */
+type RunActionReturns<T> = {
+    code: number | string;
+    data?: unknown extends ExtractReturns<T> ? any : ArgsToPayload<ExtractReturns<T>>;
+    message?: string;
+    [key: string]: any;
+};
+
 type RouterContextT = {
     code?: number;
     [key: string]: any;
@@ -516,8 +567,9 @@ declare class QueryRouterServer<C extends SimpleObject = SimpleObject> extends Q
         key?: string;
         metadata?: {
             args?: any;
+            returns?: any;
         };
-    } = {}>(api: T, payload: RunActionPayload<T>, ctx?: RouteContext<C>): Promise<any>;
+    } = {}>(api: T, payload: RunActionPayload<T>, ctx?: RouteContext<C>): Promise<RunActionReturns<T>>;
     /**
      * 创建认证相关的中间件，默认是 auth, auth-admin, auth-can 三个中间件
      * @param fun 认证函数，接收 RouteContext 和认证类型
@@ -526,43 +578,6 @@ declare class QueryRouterServer<C extends SimpleObject = SimpleObject> extends Q
         overwrite?: boolean;
     }): Promise<void>;
 }
-/** 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/ws.js

@@ -32,7 +32,7 @@ var __toESM = (mod, isNodeMode, target) => {
 var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
-// node_modules/ws/lib/constants.js
+// node_modules/.pnpm/@kevisual+ws@8.0.0/node_modules/@kevisual/ws/lib/constants.js
 var require_constants = __commonJS((exports, module) => {
   var BINARY_TYPES = ["nodebuffer", "arraybuffer", "fragments"];
   var hasBlob = typeof Blob !== "undefined";
@@ -51,7 +51,7 @@ var require_constants = __commonJS((exports, module) => {
   };
 });
 
-// node_modules/ws/lib/buffer-util.js
+// node_modules/.pnpm/@kevisual+ws@8.0.0/node_modules/@kevisual/ws/lib/buffer-util.js
 var require_buffer_util = __commonJS((exports, module) => {
   var { EMPTY_BUFFER } = require_constants();
   var FastBuffer = Buffer[Symbol.species];
@@ -112,7 +112,7 @@ var require_buffer_util = __commonJS((exports, module) => {
   };
 });
 
-// node_modules/ws/lib/limiter.js
+// node_modules/.pnpm/@kevisual+ws@8.0.0/node_modules/@kevisual/ws/lib/limiter.js
 var require_limiter = __commonJS((exports, module) => {
   var kDone = Symbol("kDone");
   var kRun = Symbol("kRun");
@@ -144,7 +144,7 @@ var require_limiter = __commonJS((exports, module) => {
   module.exports = Limiter;
 });
 
-// node_modules/ws/lib/permessage-deflate.js
+// node_modules/.pnpm/@kevisual+ws@8.0.0/node_modules/@kevisual/ws/lib/permessage-deflate.js
 var require_permessage_deflate = __commonJS((exports, module) => {
   var zlib = __require("zlib");
   var bufferUtil = require_buffer_util();
@@ -404,7 +404,7 @@ var require_permessage_deflate = __commonJS((exports, module) => {
   }
 });
 
-// node_modules/ws/lib/validation.js
+// node_modules/.pnpm/@kevisual+ws@8.0.0/node_modules/@kevisual/ws/lib/validation.js
 var require_validation = __commonJS((exports, module) => {
   var { isUtf8 } = __require("buffer");
   var { hasBlob } = require_constants();
@@ -584,7 +584,7 @@ var require_validation = __commonJS((exports, module) => {
   }
 });
 
-// node_modules/ws/lib/receiver.js
+// node_modules/.pnpm/@kevisual+ws@8.0.0/node_modules/@kevisual/ws/lib/receiver.js
 var require_receiver = __commonJS((exports, module) => {
   var { Writable } = __require("stream");
   var PerMessageDeflate = require_permessage_deflate();
@@ -965,7 +965,7 @@ var require_receiver = __commonJS((exports, module) => {
   module.exports = Receiver;
 });
 
-// node_modules/ws/lib/sender.js
+// node_modules/.pnpm/@kevisual+ws@8.0.0/node_modules/@kevisual/ws/lib/sender.js
 var require_sender = __commonJS((exports, module) => {
   var { Duplex } = __require("stream");
   var { randomFillSync } = __require("crypto");
@@ -1319,7 +1319,7 @@ var require_sender = __commonJS((exports, module) => {
   }
 });
 
-// node_modules/ws/lib/event-target.js
+// node_modules/.pnpm/@kevisual+ws@8.0.0/node_modules/@kevisual/ws/lib/event-target.js
 var require_event_target = __commonJS((exports, module) => {
   var { kForOnEventAttribute, kListener } = require_constants();
   var kCode = Symbol("kCode");
@@ -1470,7 +1470,7 @@ var require_event_target = __commonJS((exports, module) => {
   }
 });
 
-// node_modules/ws/lib/extension.js
+// node_modules/.pnpm/@kevisual+ws@8.0.0/node_modules/@kevisual/ws/lib/extension.js
 var require_extension = __commonJS((exports, module) => {
   var { tokenChars } = require_validation();
   function push(dest, name, elem) {
@@ -1635,7 +1635,7 @@ var require_extension = __commonJS((exports, module) => {
   module.exports = { format, parse };
 });
 
-// node_modules/ws/lib/websocket.js
+// node_modules/.pnpm/@kevisual+ws@8.0.0/node_modules/@kevisual/ws/lib/websocket.js
 var require_websocket = __commonJS((exports, module) => {
   var EventEmitter = __require("events");
   var https = __require("https");
@@ -2394,7 +2394,7 @@ var require_websocket = __commonJS((exports, module) => {
   }
 });
 
-// node_modules/ws/lib/stream.js
+// node_modules/.pnpm/@kevisual+ws@8.0.0/node_modules/@kevisual/ws/lib/stream.js
 var require_stream = __commonJS((exports, module) => {
   var WebSocket = require_websocket();
   var { Duplex } = __require("stream");
@@ -2497,7 +2497,7 @@ var require_stream = __commonJS((exports, module) => {
   module.exports = createWebSocketStream;
 });
 
-// node_modules/ws/lib/subprotocol.js
+// node_modules/.pnpm/@kevisual+ws@8.0.0/node_modules/@kevisual/ws/lib/subprotocol.js
 var require_subprotocol = __commonJS((exports, module) => {
   var { tokenChars } = require_validation();
   function parse(header) {
@@ -2542,7 +2542,7 @@ var require_subprotocol = __commonJS((exports, module) => {
   module.exports = { parse };
 });
 
-// node_modules/ws/lib/websocket-server.js
+// node_modules/.pnpm/@kevisual+ws@8.0.0/node_modules/@kevisual/ws/lib/websocket-server.js
 var require_websocket_server = __commonJS((exports, module) => {
   var EventEmitter = __require("events");
   var http = __require("http");
@@ -2841,7 +2841,7 @@ var require_websocket_server = __commonJS((exports, module) => {
   }
 });
 
-// node_modules/ws/wrapper.mjs
+// node_modules/.pnpm/@kevisual+ws@8.0.0/node_modules/@kevisual/ws/wrapper.mjs
 var import_stream = __toESM(require_stream(), 1);
 var import_receiver = __toESM(require_receiver(), 1);
 var import_sender = __toESM(require_sender(), 1);

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@kevisual/router",
-  "version": "0.2.11",
+  "version": "0.2.14",
   "description": "",
   "type": "module",
   "main": "./dist/router.js",
@@ -23,26 +23,26 @@
   "license": "MIT",
   "devDependencies": {
     "@kevisual/code-builder": "^0.0.7",
-    "@kevisual/context": "^0.0.10",
+    "@kevisual/context": "^0.1.1",
     "@kevisual/dts": "^0.0.4",
     "@kevisual/js-filter": "^0.0.6",
     "@kevisual/local-proxy": "^0.0.8",
-    "@kevisual/query": "^0.0.56",
+    "@kevisual/query": "^0.0.58",
     "@kevisual/remote-app": "^0.0.7",
     "@kevisual/use-config": "^1.0.30",
-    "@opencode-ai/plugin": "^1.14.22",
-    "@types/bun": "^1.3.13",
+    "@opencode-ai/plugin": "^1.15.13",
+    "@types/bun": "^1.3.14",
     "@types/crypto-js": "^4.2.2",
-    "@types/node": "^25.6.0",
+    "@types/node": "^25.9.1",
     "@types/send": "^1.2.1",
     "@types/ws": "^8.18.1",
     "@types/xml2js": "^0.4.14",
-    "commander": "^14.0.3",
+    "commander": "^15.0.0",
     "crypto-js": "^4.2.0",
-    "es-toolkit": "^1.46.0",
+    "es-toolkit": "^1.47.0",
     "eventemitter3": "^5.0.4",
     "fast-glob": "^3.3.3",
-    "nanoid": "^5.1.9",
+    "nanoid": "^5.1.11",
     "path-to-regexp": "^8.4.2",
     "send": "^1.2.1",
     "typescript": "^6.0.3",
@@ -54,7 +54,7 @@
     "url": "git+https://github.com/abearxiong/kevisual-router.git"
   },
   "dependencies": {
-    "zod": "^4.3.6"
+    "zod": "^4.4.3"
   },
   "publishConfig": {
     "access": "public"
@@ -70,6 +70,7 @@
     "./ws": "./dist/ws.js",
     "./mod.ts": "./mod.ts",
     "./src/*": "./src/*",
+    "./types/*": "./src/types/*",
     "./modules/*": "./src/modules/*"
   }
 }

package/src/result/error.ts

@@ -1,6 +1,7 @@
 export type CustomErrorOptions = {
   cause?: Error | string;
   code?: number;
+  data?: any;
   message?: string;
 }
 /** 自定义错误 */
@@ -19,6 +20,9 @@ export class CustomError extends Error {
     this.name = 'RouterError';
     let codeNum = opts?.code || (typeof code === 'number' ? code : undefined);
     this.code = codeNum ?? 500;
+    if (opts.data) {
+      this.data = opts.data;
+    }
     this.message = message!;
     // 这一步可不写，默认会保存堆栈追踪信息到自定义错误构造函数之前，
     // 而如果写成 `Error.captureStackTrace(this)` 则自定义错误的构造函数也会被保存到堆栈追踪信息

package/src/route.ts

@@ -1,10 +1,10 @@
 import { CustomError, throwError } from './result/error.ts';
 import { pick } from './utils/pick.ts';
 import { listenProcess, MockProcess } from './utils/listen-process.ts';
-import { z } from 'zod';
+import { z, ZodError } from 'zod';
 import { hashIdMd5Sync, randomId } from './utils/random.ts';
 import * as schema from './validator/schema.ts';
-
+import type { RunActionPayload, RunActionReturns } from './types/index.ts'
 export type RouterContextT = { code?: number;[key: string]: any };
 
 type BuildRouteContext<M, U> = M extends { args?: infer A }
@@ -57,6 +57,11 @@ export type RouteContext<T = { code?: number }, U extends SimpleObject = {}, S =
    * 进度
    */
   progress?: [string, string][];
+  safeParseAsync?: (data?: any, opts?: {
+    schema?: { [key: string]: z.ZodTypeAny },
+    zodOptions?: any,
+    stop?: boolean, // 如果验证失败，是否停止后续的 route 执行，默认 true
+  }) => Promise<{ success: boolean; data?: any; error?: any }>;
   // onlyForNextRoute will be clear after next route
   nextQuery?: { [key: string]: any };
   // end
@@ -93,7 +98,7 @@ export type RouteOpts<U = {}, T = SimpleObject> = {
   run?: Run<U>;
   nextRoute?: NextRoute; // route to run after this route
   description?: string;
-  metadata?: T;
+  metadata?: Metadata<T>;
   middleware?: RouteMiddleware[]; // middleware
   type?: 'route' | 'middleware' | 'compound'; // compound表示这个 route 作为一个聚合体，没有实际的 run，而是一个 router 的聚合列表
   isDebug?: boolean;
@@ -129,12 +134,16 @@ export const createSkill = <T = SimpleObject>(skill: Skill<T>): Skill<T> => {
 }
 
 export type RouteInfo = Pick<Route, (typeof pickValue)[number]>;
-
+export type Metadata<T = SimpleObject> = {
+  args?: Record<string, z.ZodTypeAny> | z.ZodObject<any>;
+  returns?: Record<string, z.ZodTypeAny> | z.ZodObject<any>;
+  check?: boolean;
+} & T;
 /**
  * @M 是 route的 metadate的类型，默认是 SimpleObject
  * @U 是 RouteContext 里 state的类型
  */
-export class Route<M extends SimpleObject = SimpleObject, U extends SimpleObject = SimpleObject> implements throwError {
+export class Route<M extends Metadata = Metadata, U extends SimpleObject = SimpleObject> implements throwError {
   /**
    * 一级路径
    */
@@ -315,6 +324,21 @@ export class QueryRouter<T extends SimpleObject = SimpleObject> implements throw
   removeById(uniqueId: string) {
     this.routes = this.routes.filter((r) => r.rid !== uniqueId);
   }
+  safeParseAsyncRoute(data: any, opts: { route: RouteInfo, schema?: { [key: string]: z.ZodTypeAny }, zodOptions?: any }): Promise<{ success: boolean; data?: any; error?: any }> {
+    const route = opts.route;
+    const argZod = route.metadata?.args as Record<string, z.ZodTypeAny>;
+    const schemaZod = opts.schema || {};
+    const zodOptions = opts.zodOptions;
+    const keys = Object.keys(argZod || {});
+    if (argZod && keys.length > 0) {
+      const mgZod = z.object({
+        ...argZod,
+        ...schemaZod
+      });
+      return mgZod.safeParseAsync(data, zodOptions);
+    }
+    return Promise.resolve({ success: true, data });
+  }
   /**
    * 执行route
    * @param path
@@ -332,6 +356,21 @@ export class QueryRouter<T extends SimpleObject = SimpleObject> implements throw
     ctx.currentRoute = route;
     ctx.index = (ctx.index || 0) + 1;
     const progress = [path, key] as [string, string];
+    ctx.safeParseAsync = async (data?: any, opts?: { schema?: { [key: string]: z.ZodTypeAny }, zodOptions?: any, stop?: boolean }) => {
+      const stop = opts?.stop ?? true;
+      const _query = { ...ctx.query, ...data };
+      const res = await this.safeParseAsyncRoute(_query, { route: route, ...opts });
+      if (!res.success && stop) {
+        const issues = res.error.issues;
+        ctx.throw({
+          // Unprocessable Entity
+          code: 422,
+          data: issues,
+          message: 'Validation Error:' + JSON.stringify(issues, null, 2),
+        })
+      }
+      return res;
+    }
     if (ctx.progress) {
       ctx.progress.push(progress);
     } else {
@@ -406,7 +445,7 @@ export class QueryRouter<T extends SimpleObject = SimpleObject> implements throw
             if (e instanceof CustomError || e?.code) {
               ctx.code = e.code;
               ctx.message = e.message;
-              ctx.body = null;
+              ctx.body = e.data;
             } else {
               console.error(`[router error] fn:${route.path}-${route.key}:${route.rid}`);
               console.error(`[router error] middleware:${middleware.path}-${middleware.key}:${middleware.rid}`);
@@ -427,6 +466,9 @@ export class QueryRouter<T extends SimpleObject = SimpleObject> implements throw
     if (route) {
       if (route.run) {
         try {
+          if (route.metadata?.check) {
+            await ctx.safeParseAsync(null, { stop: true });
+          }
           await route.run(ctx as Required<RouteContext<T>>);
         } catch (e) {
           if (route?.isDebug) {
@@ -437,13 +479,14 @@ export class QueryRouter<T extends SimpleObject = SimpleObject> implements throw
           if (e instanceof CustomError || e?.code) {
             ctx.code = e.code;
             ctx.message = e.message;
+            ctx.body = e.data;
           } else {
             console.error(`[router error] fn:${route.path}-${route.key}:${route.rid}`);
             console.error(`[router error] error`, e);
             ctx.code = 500;
             ctx.message = 'Internal Server Error';
+            ctx.body = null;
           }
-          ctx.body = null;
           return ctx;
         }
         if (ctx.end) {
@@ -781,11 +824,11 @@ export class QueryRouterServer<C extends SimpleObject = SimpleObject> extends Qu
   async runLocal(msg: { rid?: string; path?: string; key?: string; payload?: any, args?: any, token?: string, data?: any }, ctx?: Partial<RouteContext<C>>) {
     return this.run(msg, { ...ctx, appId: this.appId } as RouteContext<C>);
   }
-  async runAction<T extends { rid?: string; path?: string; key?: string; metadata?: { args?: any } } = {}>(
+  async runAction<T extends { rid?: string; path?: string; key?: string; metadata?: { args?: any, returns?: any } } = {}>(
     api: T,
     payload: RunActionPayload<T>,
     ctx?: RouteContext<C>
-  ) {
+  ): Promise<RunActionReturns<T>> {
     const { path, key, rid } = api as any;
     return this.run({ path, key, rid, payload }, ctx);
   }
@@ -834,30 +877,3 @@ export class QueryRouterServer<C extends SimpleObject = SimpleObject> extends Qu
 
 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/app-type.ts

@@ -15,7 +15,7 @@ app.route({
   metadata: {
     args: {
       name: z.string(),
-    }
+    },
   },
 }).define(async (ctx) => {
   // ctx.app 是 App 类型

package/src/test/route-ts.ts

@@ -1,15 +1,29 @@
 import { QueryRouterServer } from "@/route.ts";
 import z from "zod";
+import { tr } from "zod/v4/locales";
 
 const router = new QueryRouterServer()
 
 router.route({
+  path: 'test',
   metadata: {
     args: {
       a: z.string(),
-    }
+    },
+    check: true,
   },
 }).define(async (ctx) => {
-  const argA: string = ctx.args.a;
+  const argZod = ctx.currentRoute.metadata.args as Record<string, z.ZodTypeAny>;
+  const mgZod = z.object(argZod);
+  // console.log('argZod', argZod);
+  // const argA: string = ctx.args.a;
+  // const res = await ctx.safeParseAsync(null, { stop: true });
+  // // console.log('argA', argA);
+  // if (!res.success) {
+  //   console.log('res===', res.error.issues);
+  // }
   ctx.body = '1';
-}).addTo(router);
+}).addTo(router);
+
+const res = await router.run({ path: 'test', payload: { a: 'abc' } });
+console.log('res', res);

package/src/test/run-schema.ts

@@ -70,6 +70,19 @@ const api = {
           "includeProfile": {
             "type": "boolean"
           }
+        },
+        "returns": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "age": {
+              "type": "number"
+            }
+          },
+          "additionalProperties": false,
+          "required": ["name", "age"]
         }
       }
     }
@@ -85,4 +98,5 @@ app.runAction(a2.app_domain_manager.get, { data: { idd: "1" }, })
 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 })
+const res = await app.runAction(api.user_manager.getUser, { userId: "u1", includeProfile: true })
+const name: string = res.data.name;

package/src/types/index.ts

@@ -0,0 +1,39 @@
+/** 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 : {};
+
+/** 从 API 定义中提取 metadata.returns */
+type ExtractReturns<T> =
+    T extends { metadata: { returns: infer R } } ? R : unknown;
+
+/** runAction 第二个参数的类型，根据第一个参数的 metadata.args 推断 */
+export type RunActionPayload<T> = ArgsToPayload<ExtractArgs<T>>;
+
+/** runAction 的返回类型，根据 API 定义中的 metadata.returns 推断 data 字段类型 */
+export type RunActionReturns<T> = {
+    code: number | string;
+    data?: unknown extends ExtractReturns<T> ? any : ArgsToPayload<ExtractReturns<T>>;
+    message?: string;
+    [key: string]: any;
+};

package/src/test/chat.ts

@@ -1,17 +0,0 @@
-import { App } from '../app.ts'
-import { RouterChat } from '@/modules/chat.ts';
-
-const app = new App();
-
-app.prompt(`获取时间的工具`).define(async (ctx) => {
-  ctx.body = '123'
-}).addTo(app);
-
-app.prompt('获取天气的工具。\n参数是 city 为对应的城市').define(async (ctx) => {
-  ctx.body = '晴天'
-}).addTo(app);
-
-
-export const chat = new RouterChat({ router: app.router });
-
-console.log(chat.getChatPrompt());