@kevisual/router 0.0.82 → 0.0.84

package/src/app.ts

@@ -1,4 +1,4 @@
-import { AddOpts, QueryRouter, Route, RouteContext, RouteOpts } from './route.ts';
+import { AddOpts, QueryRouter, QueryRouterServer, Route, RouteContext, RouteOpts } from './route.ts';
 import { ServerNode, ServerNodeOpts } from './server/server.ts';
 import { HandleCtx } from './server/server-base.ts';
 import { ServerType } from './server/server-type.ts';
@@ -10,7 +10,7 @@ import { randomId } from './utils/random.ts';
 
 type RouterHandle = (msg: { path: string;[key: string]: any }) => { code: string; data?: any; message?: string;[key: string]: any };
 type AppOptions<T = {}> = {
-  router?: QueryRouter;
+  router?: QueryRouterServer;
   server?: ServerType;
   /** handle msg 关联 */
   routerHandle?: RouterHandle;
@@ -19,18 +19,19 @@ type AppOptions<T = {}> = {
   appId?: string;
 };
 
-export type AppRouteContext<T = {}> = HandleCtx & RouteContext<T> & { app: App<T> };
+export type AppRouteContext<T> = HandleCtx & RouteContext<T> & { app: App<T> };
 
 /**
  *  封装了 Router 和 Server 的 App 模块，处理http的请求和响应，内置了 Cookie 和 Token 和 res 的处理
  *  U - Route Context的扩展类型
  */
-export class App<U = {}> extends QueryRouter {
+export class App<U = {}> extends QueryRouterServer<AppRouteContext<U>> {
   declare appId: string;
-  router: QueryRouter;
+  router: QueryRouterServer;
   server: ServerType;
+  declare context: AppRouteContext<U>;
   constructor(opts?: AppOptions<U>) {
-    super();
+    super({ initHandle: false, context: { needSerialize: true, ...opts?.routerContext } as any });
     const router = this;
     let server = opts?.server;
     if (!server) {
@@ -42,7 +43,6 @@ export class App<U = {}> extends QueryRouter {
       }
     }
     server.setHandle(router.getHandle(router, opts?.routerHandle, opts?.routerContext));
-    router.setContext({ needSerialize: true, ...opts?.routerContext });
     this.router = router;
     this.server = server;
     if (opts?.appId) {
@@ -64,50 +64,7 @@ export class App<U = {}> extends QueryRouter {
     // @ts-ignore
     this.server.listen(...args);
   }
-  addRoute(route: Route, opts?: AddOpts) {
-    super.add(route, opts);
-  }
-
   Route = Route;
-  route(opts: RouteOpts<AppRouteContext<U>>): Route<AppRouteContext<U>>;
-  route(path: string, key?: string): Route<AppRouteContext<U>>;
-  route(path: string, opts?: RouteOpts<AppRouteContext<U>>): Route<AppRouteContext<U>>;
-  route(path: string, key?: string, opts?: RouteOpts<AppRouteContext<U>>): Route<AppRouteContext<U>>;
-  route(...args: any[]) {
-    const [path, key, opts] = args;
-    if (typeof path === 'object') {
-      return new Route(path.path, path.key, path);
-    }
-    if (typeof path === 'string') {
-      if (opts) {
-        return new Route(path, key, opts);
-      }
-      if (key && typeof key === 'object') {
-        return new Route(path, key?.key || '', key);
-      }
-      return new Route(path, key);
-    }
-    return new Route(path, key, opts);
-  }
-  prompt(description: string): Route<AppRouteContext<U>>
-  prompt(description: Function): Route<AppRouteContext<U>>
-  prompt(...args: any[]) {
-    const [desc] = args;
-    let description = ''
-    if (typeof desc === 'string') {
-      description = desc;
-    } else if (typeof desc === 'function') {
-      description = desc() || ''; // 如果是Promise，需要addTo App之前就要获取应有的函数了。
-    }
-    return new Route('', '', { description });
-  }
-
-  async call(message: { id?: string, path?: string; key?: string; payload?: any }, ctx?: AppRouteContext<U> & { [key: string]: any }) {
-    return await super.call(message, ctx);
-  }
-  async run(msg: { id?: string, path?: string; key?: string; payload?: any }, ctx?: Partial<AppRouteContext<U>> & { [key: string]: any }) {
-    return await super.run(msg, ctx);
-  }
   static handleRequest(req: IncomingMessage, res: ServerResponse) {
     return handleServer(req, res);
   }

package/src/opencode.ts

@@ -10,7 +10,7 @@ export const addCallFn = (app: App) => {
     path: 'call',
     key: '',
     description: '调用',
-    middleware: ['auth'],
+    middleware: ['auth-admin'],
     metadata: {
       tags: ['opencode'],
       ...createSkill({
@@ -24,7 +24,7 @@ export const addCallFn = (app: App) => {
         args: {
           path: tool.schema.string().describe('应用路径，例如 cnb'),
           key: tool.schema.string().optional().describe('应用key，例如 list-repos'),
-          payload: tool.schema.object({}).optional().describe('调用参数'),
+          payload: tool.schema.object({}).optional().describe('调用参数, 为对象, 例如 { "query": "javascript" }'),
         }
       })
     },
@@ -59,9 +59,16 @@ export const createRouterAgentPluginFn = (opts?: {
   if (!router.hasRoute('call', '')) {
     addCallFn(router as App)
   }
-  if (!router.hasRoute('auth', '')) {
-    router.route({ path: 'auth', key: '', id: 'auth', description: '认证' }).define(async (ctx) => { }).addTo(router as App)
+  if (router) {
+    (router as any).route({ path: 'auth', key: '', id: 'auth', description: '认证' }).define(async (ctx) => { }).addTo(router as App, {
+      overwrite: false
+    });
+
+    (router as any).route({ path: 'auth-admin', key: '', id: 'auth-admin', description: '认证' }).define(async (ctx) => { }).addTo(router as App, {
+      overwrite: false
+    })
   }
+
   const _routes = filter(router.routes, opts?.query || '')
   const routes = _routes.filter(r => {
     const metadata = r.metadata as Skill
@@ -75,7 +82,7 @@ export const createRouterAgentPluginFn = (opts?: {
   });
   // opencode run "使用技能查看系统信息"
   const AgentPlugin: Plugin = async (pluginInput) => {
-    useContextKey<PluginInput>('plugin-input', () => pluginInput, true)
+    useContextKey<PluginInput>('plugin-input', () => pluginInput, { isNew: true })
     const hooks = opts?.hooks ? await opts.hooks(pluginInput) : {}
     return {
       ...hooks,

package/src/result/error.ts

@@ -47,6 +47,22 @@ export class CustomError extends Error {
   static isError(error: unknown): error is CustomError {
     return error instanceof CustomError || (typeof error === 'object' && error !== null && 'code' in error);
   }
+  static throw(code?: number | string, message?: string): void;
+  static throw(code?: number | string, opts?: CustomErrorOptions): void;
+  static throw(opts?: CustomErrorOptions): void;
+  static throw(...args: any[]) {
+    const [args0, args1] = args;
+    if (args0 && typeof args0 === 'object') {
+      throw new CustomError(args0);
+    }
+    if (args1 && typeof args1 === 'object') {
+      throw new CustomError(args0, args1);
+    } else if (args1) {
+      throw new CustomError(args0, { message: args1 });
+    }
+    // args1 不存在;
+    throw new CustomError(args0);
+  }
   parse(e?: CustomError) {
     if (e) {
       return CustomError.parseError(e);
@@ -61,6 +77,12 @@ export class CustomError extends Error {
   }
 }
 
+export interface throwError {
+  throw(code?: number | string, message?: string): void;
+  throw(code?: number | string, opts?: CustomErrorOptions): void;
+  throw(opts?: CustomErrorOptions): void;
+}
+
 /*
 try {
   //

package/src/route.ts

@@ -1,4 +1,4 @@
-import { CustomError, CustomErrorOptions } from './result/error.ts';
+import { CustomError, throwError, CustomErrorOptions } from './result/error.ts';
 import { pick } from './utils/pick.ts';
 import { listenProcess, MockProcess } from './utils/listen-process.ts';
 import { z } from 'zod';
@@ -6,7 +6,24 @@ import { randomId } from './utils/random.ts';
 import * as schema from './validator/schema.ts';
 
 export type RouterContextT = { code?: number;[key: string]: any };
-export type RouteContext<T = { code?: number }, S = 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>
+  : A extends Record<string, z.ZodTypeAny>
+  ? RouteContext<{ args?: { [K in keyof A]: z.infer<A[K]> } }, U>
+  : RouteContext<U>
+  : RouteContext<U>;
+
+export type RouteContext<T = { code?: number }, U extends SimpleObject = {}, S = { [key: string]: any }> = {
   /**
    * 本地自己调用的时候使用，可以标识为当前自调用，那么 auth 就不许重复的校验
    * 或者不需要登录的，直接调用
@@ -23,9 +40,15 @@ export type RouteContext<T = { code?: number }, S = any> = {
   code?: number;
   /** return msg */
   message?: string;
-  // 传递状态
+  /**
+   * 传递状态
+   */
   state?: S;
   // transfer data
+  /**
+   * 当前routerId
+   */
+  currentId?: string;
   /**
    * 当前路径
    */
@@ -54,19 +77,19 @@ export type RouteContext<T = { code?: number }, S = any> = {
     ctx?: RouteContext & { [key: string]: any },
   ) => Promise<any>;
   /** 请求 route的返回结果，解析了body为data，就类同于 query.post获取的数据*/
-  run?: (message: { path: string; key?: string; payload?: any }, ctx?: RouteContext & { [key: string]: any }) => Promise<any>;
+  run?: (message: { path: string; key?: string; payload?: any }, ctx?: RouteContext) => Promise<any>;
   index?: number;
-  throw?: (code?: number | string, message?: string, tips?: string) => void;
+  throw?: throwError['throw'];
   /** 是否需要序列化, 使用JSON.stringify和JSON.parse */
   needSerialize?: boolean;
-} & T;
+} & T & U;
 export type SimpleObject = Record<string, any>;
 export type Run<T extends SimpleObject = {}> = (ctx: Required<RouteContext<T>>) => Promise<typeof ctx | null | void>;
 export type RunMessage = { path?: string; key?: string; id?: string; payload?: any; };
 export type NextRoute = Pick<Route, 'id' | 'path' | 'key'>;
 export type RouteMiddleware =
   | {
-    path: string;
+    path?: string;
     key?: string;
     id?: string;
   }
@@ -123,7 +146,13 @@ export const createSkill = <T = SimpleObject>(skill: Skill<T>): Skill<T> => {
 
 export type RouteInfo = Pick<Route, (typeof pickValue)[number]>;
 
-export class Route<U = { [key: string]: any }, T extends SimpleObject = SimpleObject> {
+type ExtractMetadata<M> = M extends { metadata?: infer Meta } ? Meta extends SimpleObject ? Meta : SimpleObject : SimpleObject;
+
+/**
+ * @M 是 route的 metadate的类型，默认是 SimpleObject
+ * @U 是 RouteContext 里 state的类型
+ */
+export class Route<M extends SimpleObject = SimpleObject, U extends SimpleObject = SimpleObject> implements throwError {
   /**
    * 一级路径
    */
@@ -133,10 +162,10 @@ export class Route<U = { [key: string]: any }, T extends SimpleObject = SimpleOb
    */
   key?: string;
   id?: string;
-  run?: Run;
+  run?: Run<BuildRouteContext<M, U>>;
   nextRoute?: NextRoute; // route to run after this route
   description?: string;
-  metadata?: T;
+  metadata?: M;
   middleware?: RouteMiddleware[]; // middleware
   type? = 'route';
   /**
@@ -157,10 +186,10 @@ export class Route<U = { [key: string]: any }, T extends SimpleObject = SimpleOb
         const delimiter = opts.delimiter ?? '$#$';
         this.id = path + delimiter + key;
       }
-      this.run = opts.run;
+      this.run = opts.run as Run<BuildRouteContext<M, U>>;
       this.nextRoute = opts.nextRoute;
       this.description = opts.description;
-      this.metadata = opts.metadata as T;
+      this.metadata = opts.metadata as M;
       this.type = opts.type || 'route';
       this.middleware = opts.middleware || [];
       this.key = opts.key || key;
@@ -184,9 +213,9 @@ export class Route<U = { [key: string]: any }, T extends SimpleObject = SimpleOb
     return this;
   }
   define<T extends { [key: string]: any } = RouterContextT>(opts: DefineRouteOpts): this;
-  define<T extends { [key: string]: any } = RouterContextT>(fn: Run<T & U>): this;
-  define<T extends { [key: string]: any } = RouterContextT>(key: string, fn: Run<T & U>): this;
-  define<T extends { [key: string]: any } = RouterContextT>(path: string, key: string, fn: Run<T & U>): this;
+  define<T extends { [key: string]: any } = RouterContextT>(fn: Run<T & BuildRouteContext<M, U>>): this;
+  define<T extends { [key: string]: any } = RouterContextT>(key: string, fn: Run<T & BuildRouteContext<M, U>>): this;
+  define<T extends { [key: string]: any } = RouterContextT>(path: string, key: string, fn: Run<T & BuildRouteContext<M, U>>): this;
   define(...args: any[]) {
     const [path, key, opts] = args;
     // 全覆盖，所以opts需要准确，不能由idUsePath 需要check的变量
@@ -209,7 +238,7 @@ export class Route<U = { [key: string]: any }, T extends SimpleObject = SimpleOb
       return this;
     }
     if (typeof path === 'function') {
-      this.run = path;
+      this.run = path as Run<BuildRouteContext<M, U>>;
       return this;
     }
     if (typeof path === 'string' && typeof key === 'function') {
@@ -242,9 +271,8 @@ export class Route<U = { [key: string]: any }, T extends SimpleObject = SimpleOb
   addTo(router: QueryRouter | { add: (route: Route) => void;[key: string]: any }, opts?: AddOpts) {
     router.add(this, opts);
   }
-  throw(code?: number | string, message?: string, tips?: string): void;
   throw(...args: any[]) {
-    throw new CustomError(...args);
+    CustomError.throw(...args);
   }
 }
 
@@ -263,11 +291,11 @@ export const fromJSONSchema = schema.fromJSONSchema;
  * @parmas overwrite 是否覆盖已存在的route，默认true
  */
 export type AddOpts = { overwrite?: boolean };
-export class QueryRouter {
+export class QueryRouter<T extends SimpleObject = SimpleObject> implements throwError {
   appId: string = '';
   routes: Route[];
   maxNextRoute = 40;
-  context?: RouteContext = {}; // default context for call
+  context?: RouteContext<T> = {} as RouteContext<T>; // default context for call
   constructor() {
     this.routes = [];
   }
@@ -310,11 +338,12 @@ export class QueryRouter {
    * @param ctx
    * @returns
    */
-  async runRoute(path: string, key: string, ctx?: RouteContext) {
+  async runRoute(path: string, key: string, ctx?: RouteContext<T>): Promise<RouteContext<T>> {
     const route = this.routes.find((r) => r.path === path && r.key === key);
     const maxNextRoute = this.maxNextRoute;
-    ctx = (ctx || {}) as RouteContext;
+    ctx = (ctx || {}) as RouteContext<T>;
     ctx.currentPath = path;
+    ctx.currentId = route?.id;
     ctx.currentKey = key;
     ctx.currentRoute = route;
     ctx.index = (ctx.index || 0) + 1;
@@ -328,7 +357,7 @@ export class QueryRouter {
       ctx.code = 500;
       ctx.message = 'Too many nextRoute';
       ctx.body = null;
-      return;
+      return ctx;
     }
     // run middleware
     if (route && route.middleware && route.middleware.length > 0) {
@@ -383,7 +412,7 @@ export class QueryRouter {
         const middleware = routeMiddleware[i];
         if (middleware) {
           try {
-            await middleware.run(ctx as Required<RouteContext>);
+            await middleware.run(ctx as Required<RouteContext<T>>);
           } catch (e) {
             if (route?.isDebug) {
               console.error('=====debug====:middlerware error');
@@ -405,6 +434,7 @@ export class QueryRouter {
             return ctx;
           }
           if (ctx.end) {
+            return ctx;
           }
         }
       }
@@ -413,7 +443,7 @@ export class QueryRouter {
     if (route) {
       if (route.run) {
         try {
-          await route.run(ctx as Required<RouteContext>);
+          await route.run(ctx as Required<RouteContext<T>>);
         } catch (e) {
           if (route?.isDebug) {
             console.error('=====debug====:route error');
@@ -468,7 +498,7 @@ export class QueryRouter {
       }
     }
     // 如果没有找到route，返回404，这是因为出现了错误
-    return Promise.resolve({ code: 404, body: 'Not found' });
+    return Promise.resolve({ code: 404, body: 'Not found' } as RouteContext<T>);
   }
   /**
    * 第一次执行
@@ -476,12 +506,12 @@ export class QueryRouter {
    * @param ctx
    * @returns
    */
-  async parse(message: { path: string; key?: string; payload?: any }, ctx?: RouteContext & { [key: string]: any }) {
+  async parse(message: { path: string; key?: string; payload?: any }, ctx?: RouteContext<T> & { [key: string]: any }) {
     if (!message?.path) {
-      return Promise.resolve({ code: 404, body: null, message: 'Not found path' });
+      return Promise.resolve({ code: 404, body: null, message: 'Not found path' } as RouteContext<T>);
     }
     const { path, key = '', payload = {}, ...query } = message;
-    ctx = ctx || {};
+    ctx = ctx || {} as RouteContext<T>;
     ctx.query = { ...ctx.query, ...query, ...payload };
     ctx.args = ctx.query;
     ctx.state = { ...ctx?.state };
@@ -515,7 +545,7 @@ export class QueryRouter {
    * @param ctx
    * @returns
    */
-  async call(message: { id?: string; path?: string; key?: string; payload?: any }, ctx?: RouteContext & { [key: string]: any }) {
+  async call(message: { id?: string; path?: string; key?: string; payload?: any }, ctx?: RouteContext<T> & { [key: string]: any }) {
     let path = message.path;
     let key = message.key;
     // 优先 path + key
@@ -556,7 +586,7 @@ export class QueryRouter {
    * @param ctx 
    * @returns 
    */
-  async run(message: { id?: string; path?: string; key?: string; payload?: any }, ctx?: RouteContext & { [key: string]: any }) {
+  async run(message: { id?: string; path?: string; key?: string; payload?: any }, ctx?: RouteContext<T> & { [key: string]: any }) {
     const res = await this.call(message, { ...this.context, ...ctx });
     return {
       code: res.code,
@@ -570,7 +600,7 @@ export class QueryRouter {
    * @param ctx
    */
   setContext(ctx: RouteContext) {
-    this.context = ctx;
+    this.context = ctx as RouteContext<T>;
   }
   getList(filter?: (route: Route) => boolean): RouteInfo[] {
     return this.routes.filter(filter || (() => true)).map((r) => {
@@ -581,11 +611,11 @@ export class QueryRouter {
   /**
    * 获取handle函数, 这里会去执行parse函数
    */
-  getHandle<T = any>(router: QueryRouter, wrapperFn?: HandleFn<T>, ctx?: RouteContext) {
-    return async (msg: { id?: string; path?: string; key?: string;[key: string]: any }, handleContext?: RouteContext) => {
+  getHandle<T = any>(router: QueryRouter, wrapperFn?: HandleFn, ctx?: RouteContext) {
+    return async (msg: { id?: string; path?: string; key?: string;[key: string]: any }, handleContext?: RouteContext<T>) => {
       try {
         const context = { ...ctx, ...handleContext };
-        const res = await router.call(msg, context);
+        const res = await router.call(msg, context) as any;
         if (wrapperFn) {
           res.data = res.body;
           return wrapperFn(res, context);
@@ -610,21 +640,8 @@ export class QueryRouter {
   importRouter(router: QueryRouter) {
     this.importRoutes(router.routes);
   }
-  throw(code?: number | string, message?: string): void;
-  throw(code?: number | string, opts?: CustomErrorOptions): void;
-  throw(opts?: CustomErrorOptions): void;
   throw(...args: any[]) {
-    const [args0, args1] = args;
-    if (args0 && typeof args0 === 'object') {
-      throw new CustomError(args0);
-    }
-    if (args1 && typeof args1 === 'object') {
-      throw new CustomError(args0, args1);
-    } else if (args1) {
-      throw new CustomError(args0, { message: args1 });
-    }
-    // args1 不存在;
-    throw new CustomError(args0);
+    CustomError.throw(...args);
   }
   hasRoute(path: string, key: string = '') {
     return this.routes.find((r) => r.path === path && r.key === key);
@@ -651,7 +668,7 @@ export class QueryRouter {
         description: '列出当前应用下的所有的路由信息',
         middleware: opts?.middleware || [],
         run: async (ctx: RouteContext) => {
-          const tokenUser = ctx.state.tokenUser;
+          const tokenUser = ctx.state as unknown as { tokenUser?: any };
           let isUser = !!tokenUser;
           const list = this.getList(opts?.filter).filter((item) => {
             if (item.id === 'auth' || item.id === 'auth-can' || item.id === 'check-auth-admin' || item.id === 'auth-admin') {
@@ -697,10 +714,11 @@ export class QueryRouter {
   fromJSONSchema = fromJSONSchema;
 }
 
-type QueryRouterServerOpts = {
+type QueryRouterServerOpts<C extends SimpleObject = SimpleObject> = {
   handleFn?: HandleFn;
-  context?: RouteContext;
+  context?: RouteContext<C>;
   appId?: string;
+  initHandle?: boolean;
 };
 interface HandleFn<T = any> {
   (msg: { path: string;[key: string]: any }, ctx?: any): { code: string; data?: any; message?: string;[key: string]: any };
@@ -709,13 +727,18 @@ interface HandleFn<T = any> {
 /**
  * QueryRouterServer
  * @description 移除server相关的功能，只保留router相关的功能，和http.createServer不相关，独立
+ * @template C 自定义 RouteContext 类型
  */
-export class QueryRouterServer extends QueryRouter {
+export class QueryRouterServer<C extends SimpleObject = SimpleObject> extends QueryRouter<C> {
   declare appId: string;
   handle: any;
-  constructor(opts?: QueryRouterServerOpts) {
+  declare context: RouteContext<C>;
+  constructor(opts?: QueryRouterServerOpts<C>) {
     super();
-    this.handle = this.getHandle(this, opts?.handleFn, opts?.context);
+    const initHandle = opts?.initHandle ?? true;
+    if (initHandle || opts?.handleFn) {
+      this.handle = this.getHandle(this, opts?.handleFn, opts?.context);
+    }
     this.setContext({ needSerialize: false, ...opts?.context });
     if (opts?.appId) {
       this.appId = opts.appId;
@@ -730,37 +753,28 @@ export class QueryRouterServer extends QueryRouter {
     this.add(route, opts);
   }
   Route = Route;
-  route(opts: RouteOpts): Route<Required<RouteContext>>;
-  route(path: string, key?: string): Route<Required<RouteContext>>;
-  route(path: string, opts?: RouteOpts): Route<Required<RouteContext>>;
-  route(path: string, key?: string, opts?: RouteOpts): Route<Required<RouteContext>>;
-  route(...args: any[]) {
+  route<M extends SimpleObject = SimpleObject>(opts: RouteOpts & { metadata?: M }): Route<M, Required<RouteContext<C>>>;
+  route<M extends SimpleObject = SimpleObject>(path: string, opts?: RouteOpts & { metadata?: M }): Route<M, Required<RouteContext<C>>>;
+  route<M extends SimpleObject = SimpleObject>(path: string, key?: string): Route<M, Required<RouteContext<C>>>;
+  route<M extends SimpleObject = SimpleObject>(path: string, key?: string, opts?: RouteOpts & { metadata?: M }): Route<M, Required<RouteContext<C>>>;
+  route<M extends SimpleObject = SimpleObject>(...args: any[]) {
     const [path, key, opts] = args;
     if (typeof path === 'object') {
-      return new Route(path.path, path.key, path);
+      return new Route<M, Required<RouteContext<C>>>(path.path, path.key, path);
     }
     if (typeof path === 'string') {
       if (opts) {
-        return new Route(path, key, opts);
+        return new Route<M, Required<RouteContext<C>>>(path, key, opts);
       }
       if (key && typeof key === 'object') {
-        return new Route(path, key?.key || '', key);
+        return new Route<M, Required<RouteContext<C>>>(path, key?.key || '', key);
       }
-      return new Route(path, key);
+      return new Route<M, Required<RouteContext<C>>>(path, key);
     }
-    return new Route(path, key, opts);
+    return new Route<M, Required<RouteContext<C>>>(path, key, opts);
   }
-  prompt(description: string): Route<Required<RouteContext>>;
-  prompt(description: Function): Route<Required<RouteContext>>;
-  prompt(...args: any[]) {
-    const [desc] = args;
-    let description = ''
-    if (typeof desc === 'string') {
-      description = desc;
-    } else if (typeof desc === 'function') {
-      description = desc() || ''; // 如果是Promise，需要addTo App之前就要获取应有的函数了。
-    }
-    return new Route('', '', { description });
+  prompt(description: string) {
+    return new Route(undefined, undefined, { description });
   }
 
   /**
@@ -768,12 +782,12 @@ export class QueryRouterServer extends QueryRouter {
    * @param param0
    * @returns
    */
-  async run(msg: { id?: string; path?: string; key?: string; payload?: any }, ctx?: RouteContext & { [key: string]: any }) {
+  async run(msg: { id?: string; path?: string; key?: string; payload?: any }, ctx?: Partial<RouteContext<C>>) {
     const handle = this.handle;
     if (handle) {
       return handle(msg, ctx);
     }
-    return super.run(msg, ctx);
+    return super.run(msg, ctx as RouteContext<C>);
   }
 }
 

package/src/test/app-type.ts

@@ -1,13 +1,69 @@
-import { App } from '../app.ts'
+import { App, AppRouteContext } from "@/app.ts";
+import { QueryRouterServer, RouteContext } from "@/app.ts";
+import z from "zod";
+const route: RouteContext<{ customField: string }> = {} as any;
+route.customField
+const appRoute: AppRouteContext<{ customField: string }> = {} as any;
+appRoute.customField
+// 示例 1: 使用 App，它会自动使用 AppRouteContext<U> 作为 ctx 类型
+const app = new App<{
+  customField: string;
+}>();
+app.context.customField = "customValue"; // 可以在 app.context 中添加自定义字段，这些字段会在 ctx 中可用
+app.route({
+  path: 'test1',
+  metadata: {
+    args: {
+      name: z.string(),
+    }
+  },
+}).define(async (ctx) => {
+  // ctx.app 是 App 类型
+  const appName = ctx.app.appId;
+  // ctx.customField 来自自定义泛型参数
+  const customField: string | undefined = ctx.customField;
 
-const app = new App<{ f: string }>();
+  // ctx.req 和 ctx.res 来自 HandleCtx
+  const req = ctx.req;
+  const res = ctx.res;
 
-app.route({
-  path: 't',
-  run: async (ctx) => {
-    // ctx.r
-    ctx.app;
-  }
+  // ctx.args 从 metadata.args 推断
+  const name: string = ctx.args.name;
+  const name2: string = ctx.query.name;
+
+
+  ctx.body = `Hello ${name}!`;
+});
+// 示例 2: 使用 QueryRouterServer，它可以传递自定义的 Context 类型
+const router = new QueryRouterServer<{
+  routerContextField: number;
+}>();
+router.context.routerContextField
+router.route({
+  path: 'router-test',
+  metadata: {
+    args: {
+      value: z.number(),
+    }
+  },
+}).define(async (ctx) => {
+  const value: number = ctx.args.value;
+  const field: number | undefined = ctx.routerContextField;
+
+  ctx.body = value;
+});
+// 示例 3: 不带泛型参数的 QueryRouterServer，使用默认的 RouteContext
+const defaultRouter = new QueryRouterServer();
+defaultRouter.route({
+  path: 'default-test',
+  metadata: {
+    args: {
+      id: z.string(),
+    }
+  },
 }).define(async (ctx) => {
-  ctx.f = 'hello';
-}).addTo(app);
+  const id: string = ctx.args.id;
+
+  ctx.body = id;
+});
+export { app, router, defaultRouter };

package/src/test/chat.ts

@@ -14,4 +14,4 @@ app.prompt('获取天气的工具。\n参数是 city 为对应的城市').define
 
 export const chat = new RouterChat({ router: app.router });
 
-console.log(chat.chat());
+console.log(chat.getChatPrompt());