vafast 0.4.24 → 0.5.2

package/README.md

@@ -447,6 +447,36 @@ const routes = defineRoutes([
 ]);
 ```
 
+### 父级中间件类型注入 (withContext)
+
+当中间件在父级定义，子路由需要使用 `withContext` 获得类型推断：
+
+```typescript
+import { defineRoute, defineRoutes, withContext } from 'vafast'
+
+// 创建带 UserInfo 上下文的路由定义器
+const defineAuthRoute = withContext<{ userInfo: UserInfo }>()
+
+const routes = defineRoutes([
+  defineRoute({
+    path: '/api',
+    middleware: [authMiddleware],  // 父级中间件注入 userInfo
+    children: [
+      defineAuthRoute({  // ← 使用 defineAuthRoute
+        method: 'GET',
+        path: '/profile',
+        handler: ({ userInfo }) => {
+          // ✅ userInfo 自动有类型！
+          return { id: userInfo.id }
+        }
+      })
+    ]
+  })
+])
+```
+
+> 📖 详细文档：[withContext 使用指南](./docs/with-context.md)
+
 ### JIT 编译验证器
 
 Vafast 内置验证器 JIT 编译，自动缓存编译后的验证器：
@@ -567,7 +597,7 @@ const permissionRoutes = registry.filter('permission');
 const categories = registry.getCategories();  // ['auth', 'users']
 ```
 
-**完整 API：**
+**Registry 实例方法：**
 
 | 方法 | 说明 |
 |------|------|
@@ -582,6 +612,137 @@ const categories = registry.getCategories();  // ['auth', 'users']
 | `map(callback)` | 映射所有路由 |
 | `size` | 路由数量 |
 
+**全局便捷函数：**
+
+```typescript
+import {
+  getRoute,
+  getAllRoutes,
+  filterRoutes,
+  getRoutesByMethod,
+} from 'vafast'
+
+// 获取单个路由
+const route = getRoute('POST', '/users')
+
+// 获取所有路由
+const allRoutes = getAllRoutes()
+
+// 按字段筛选
+const webhookRoutes = filterRoutes('webhook')
+
+// 按 HTTP 方法获取
+const getRoutes = getRoutesByMethod('GET')
+const postRoutes = getRoutesByMethod('POST')
+
+// 按路径前缀筛选（自己 filter）
+const authRoutes = getAllRoutes().filter(r => r.path.startsWith('/auth'))
+```
+
+### API Spec 生成
+
+Vafast 提供 `getApiSpec` 用于生成 API 规范，支持跨仓库类型同步和 AI 工具函数生成：
+
+```typescript
+import { Server, defineRoutes, getApiSpec } from 'vafast';
+
+const routes = defineRoutes([
+  { method: 'GET', path: '/users', handler: getUsers },
+  { method: 'POST', path: '/users', handler: createUser },
+]);
+
+// 添加 API Spec 接口
+const allRoutes = [
+  ...routes,
+  { method: 'GET', path: '/api-spec', handler: getApiSpec }  // 直接作为 handler
+];
+
+const server = new Server(allRoutes);
+```
+
+**三种使用方式：**
+
+```typescript
+// 方式 1：直接作为 handler（推荐，最简洁）
+{ method: 'GET', path: '/api-spec', handler: getApiSpec }
+
+// 方式 2：显式传参（只暴露公开 API）
+{ handler: () => getApiSpec(publicRoutes) }
+
+// 方式 3：本地使用（CLI、测试）
+const spec = getApiSpec()
+```
+
+**返回格式：**
+
+```json
+{
+  "version": "1.0.0",
+  "generatedAt": "2024-01-01T00:00:00.000Z",
+  "routes": [
+    {
+      "method": "GET",
+      "path": "/users",
+      "name": "get_users",
+      "description": "获取用户列表",
+      "schema": { "query": { "type": "object", ... } }
+    }
+  ]
+}
+```
+
+### AI 工具函数生成
+
+`generateAITools` 可将路由转换为 OpenAI Function Calling / Claude Tools 格式：
+
+```typescript
+import { generateAITools } from 'vafast';
+
+const tools = generateAITools(routes);
+// [
+//   { name: 'get_users', description: '获取用户列表', parameters: {...} },
+//   { name: 'create_user', description: '创建用户', parameters: {...} }
+// ]
+
+// 直接用于 AI 调用
+const response = await openai.chat.completions.create({
+  model: 'gpt-4',
+  messages: [...],
+  tools: tools.map(t => ({ type: 'function', function: t }))
+});
+```
+
+### 跨仓库类型同步 (CLI)
+
+对于多仓库项目，使用 `@vafast/cli` 从远程服务同步类型：
+
+```bash
+# 安装 CLI
+npm install -g @vafast/cli
+
+# 从服务端同步类型
+vafast sync --url http://api.example.com --out src/api.generated.ts
+```
+
+**生成的类型文件：**
+
+```typescript
+// src/api.generated.ts
+export interface Api {
+  users: {
+    get: { query: { page?: number } }
+    post: { body: { name: string; email: string } }
+  }
+}
+
+// 使用
+import { eden } from '@vafast/api-client'
+import type { Api } from './api.generated'
+
+const api = eden<Api>('http://api.example.com')
+const { data } = await api.users.get({ query: { page: 1 } })
+```
+
 ## 📊 内置监控
 
 零依赖的性能监控，一行代码启用：
@@ -631,7 +792,9 @@ export default { port: 3000, fetch: server.fetch };
 - [快速开始](./docs/getting-started/quickstart.md)
 - [示例代码](./examples/)
 
-### 架构设计
+
+### 核心概念
+- [withContext 使用指南](./docs/with-context.md) - 父级中间件类型注入，解决跨路由类型推断
 - [路由设计与网关架构](./docs/router-design.md) - 声明式路由的设计哲学、AI 时代能力、网关优势
 - [本地工具模式](./docs/local-tools-mode.md) - 声明式路由作为 AI Tools，无需 HTTP 服务
 

package/dist/{base-server-B7MYJNsl.mjs → base-server-CE0mfqPY.mjs}

@@ -9,26 +9,25 @@ var BaseServer = class {
 		this.globalMiddleware.push(mw);
 	}
 	/**
-	* 打印扁平化后的路由信息，用于调试
+	* 打印路由信息，用于调试
 	*/
-	logFlattenedRoutes(routes, type = "路由") {
-		console.log(`🚀 扁平化后的${type}:`);
+	logRoutes(routes, type = "路由") {
+		console.log(`🚀 注册${type}:`);
 		for (const route of routes) {
 			const method = route.method || "GET";
-			const path = route.fullPath || route.path;
+			const path = route.path;
 			console.log(`  ${method} ${path}`);
-			if (route.middlewareChain && route.middlewareChain.length > 0) console.log(`    中间件链: ${route.middlewareChain.length} 个`);
+			if (route.middleware && route.middleware.length > 0) console.log(`    中间件: ${route.middleware.length} 个`);
 		}
 		console.log("");
 	}
 	/**
 	* 检测路由冲突
-	* 检查是否有路径相同但方法不同的路由，以及潜在的路径冲突
 	*/
 	detectRouteConflicts(routes) {
 		const pathGroups = /* @__PURE__ */ new Map();
 		for (const route of routes) {
-			const path = route.fullPath || route.path;
+			const path = route.path;
 			const method = route.method || "GET";
 			if (!pathGroups.has(path)) pathGroups.set(path, []);
 			pathGroups.get(path).push({
@@ -39,32 +38,21 @@ var BaseServer = class {
 		for (const [path, routeList] of pathGroups) if (routeList.length > 1) {
 			const methods = routeList.map((r) => r.method);
 			const uniqueMethods = [...new Set(methods)];
-			if (uniqueMethods.length === 1) {
-				console.warn(`⚠️  路由冲突: ${uniqueMethods[0]} ${path} 定义了 ${routeList.length} 次`);
-				routeList.forEach((route, index) => {
-					console.warn(`   ${index + 1}. ${route.method} ${path}`);
-				});
-			} else console.log(`ℹ️  路径 ${path} 支持方法: ${uniqueMethods.join(", ")}`);
+			if (uniqueMethods.length === 1) console.warn(`⚠️  路由冲突: ${uniqueMethods[0]} ${path} 定义了 ${routeList.length} 次`);
 		}
 		this.detectDynamicRouteConflicts(routes);
 	}
 	/**
-	* 检测动态路由的潜在冲突
+	* 检测动态路由冲突
 	*/
 	detectDynamicRouteConflicts(routes) {
 		const dynamicRoutes = routes.filter((r) => {
-			const path = r.fullPath || r.path;
-			return path.includes(":") || path.includes("*");
+			return r.path.includes(":") || r.path.includes("*");
 		});
 		for (let i = 0; i < dynamicRoutes.length; i++) for (let j = i + 1; j < dynamicRoutes.length; j++) {
 			const route1 = dynamicRoutes[i];
 			const route2 = dynamicRoutes[j];
-			const method1 = route1.method || "GET";
-			if (method1 === (route2.method || "GET")) {
-				const path1 = route1.fullPath || route1.path;
-				const path2 = route2.fullPath || route2.path;
-				if (this.pathsMayConflict(path1, path2)) console.warn(`⚠️  潜在路由冲突: ${method1} ${path1} 可能与 ${path2} 冲突`);
-			}
+			if (route1.method === route2.method && this.pathsMayConflict(route1.path, route2.path)) console.warn(`⚠️  潜在路由冲突: ${route1.method} ${route1.path} 与 ${route2.path}`);
 		}
 	}
 	/**
@@ -109,4 +97,4 @@ var BaseServer = class {
 
 //#endregion
 export { BaseServer as t };
-//# sourceMappingURL=base-server-B7MYJNsl.mjs.map
+//# sourceMappingURL=base-server-CE0mfqPY.mjs.map

package/dist/base-server-CE0mfqPY.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-server-CE0mfqPY.mjs","names":[],"sources":["../src/server/base-server.ts"],"sourcesContent":["import type { Middleware } from \"../types\";\n\n/**\n * 服务器基类\n * 包含所有服务器类型的公共逻辑\n */\nexport abstract class BaseServer {\n  protected globalMiddleware: Middleware[] = [];\n\n  use(mw: Middleware) {\n    this.globalMiddleware.push(mw);\n  }\n\n  /**\n   * 打印路由信息，用于调试\n   */\n  protected logRoutes(routes: any[], type: string = \"路由\"): void {\n    console.log(`🚀 注册${type}:`);\n    for (const route of routes) {\n      const method = route.method || \"GET\";\n      const path = route.path;\n      console.log(`  ${method} ${path}`);\n      if (route.middleware && route.middleware.length > 0) {\n        console.log(`    中间件: ${route.middleware.length} 个`);\n      }\n    }\n    console.log(\"\");\n  }\n\n  /**\n   * 检测路由冲突\n   */\n  protected detectRouteConflicts(routes: any[]): void {\n    const pathGroups = new Map<string, any[]>();\n\n    // 按路径分组\n    for (const route of routes) {\n      const path = route.path;\n      const method = route.method || \"GET\";\n      if (!pathGroups.has(path)) {\n        pathGroups.set(path, []);\n      }\n      pathGroups.get(path)!.push({ ...route, method });\n    }\n\n    // 检查冲突\n    for (const [path, routeList] of pathGroups) {\n      if (routeList.length > 1) {\n        const methods = routeList.map((r: { method: string }) => r.method);\n        const uniqueMethods = [...new Set(methods)];\n\n        if (uniqueMethods.length === 1) {\n          console.warn(\n            `⚠️  路由冲突: ${uniqueMethods[0]} ${path} 定义了 ${routeList.length} 次`,\n          );\n        }\n      }\n    }\n\n    // 检查动态路由冲突\n    this.detectDynamicRouteConflicts(routes);\n  }\n\n  /**\n   * 检测动态路由冲突\n   */\n  private detectDynamicRouteConflicts(routes: any[]): void {\n    const dynamicRoutes = routes.filter((r) => {\n      return r.path.includes(\":\") || r.path.includes(\"*\");\n    });\n\n    for (let i = 0; i < dynamicRoutes.length; i++) {\n      for (let j = i + 1; j < dynamicRoutes.length; j++) {\n        const route1 = dynamicRoutes[i];\n        const route2 = dynamicRoutes[j];\n        if (route1.method === route2.method && this.pathsMayConflict(route1.path, route2.path)) {\n          console.warn(`⚠️  潜在路由冲突: ${route1.method} ${route1.path} 与 ${route2.path}`);\n        }\n      }\n    }\n  }\n\n  /**\n   * 判断两个路径是否可能冲突\n   */\n  private pathsMayConflict(path1: string, path2: string): boolean {\n    const parts1 = path1.split(\"/\").filter(Boolean);\n    const parts2 = path2.split(\"/\").filter(Boolean);\n\n    if (parts1.length !== parts2.length) return false;\n\n    for (let i = 0; i < parts1.length; i++) {\n      const p1 = parts1[i];\n      const p2 = parts2[i];\n\n      // 如果两个部分都是静态的且不同，则不会冲突\n      if (\n        !p1.startsWith(\":\") &&\n        !p1.startsWith(\"*\") &&\n        !p2.startsWith(\":\") &&\n        !p2.startsWith(\"*\") &&\n        p1 !== p2\n      ) {\n        return false;\n      }\n\n      // 如果一个是通配符，另一个是动态参数，可能冲突\n      if (\n        (p1 === \"*\" && p2.startsWith(\":\")) ||\n        (p2 === \"*\" && p1.startsWith(\":\"))\n      ) {\n        return true;\n      }\n    }\n\n    return false;\n  }\n\n  /**\n   * 路径匹配\n   */\n  protected matchPath(pattern: string, path: string): boolean {\n    const patternParts = pattern.split(\"/\").filter(Boolean);\n    const pathParts = path.split(\"/\").filter(Boolean);\n\n    if (patternParts.length !== pathParts.length) {\n      return false;\n    }\n\n    for (let i = 0; i < patternParts.length; i++) {\n      if (\n        patternParts[i] !== pathParts[i] &&\n        !patternParts[i].startsWith(\":\")\n      ) {\n        return false;\n      }\n    }\n\n    return true;\n  }\n\n  /**\n   * 提取路径参数\n   */\n  protected extractParams(\n    pattern: string,\n    path: string,\n  ): Record<string, string> {\n    const params: Record<string, string> = {};\n    const patternParts = pattern.split(\"/\").filter(Boolean);\n    const pathParts = path.split(\"/\").filter(Boolean);\n\n    for (let i = 0; i < patternParts.length; i++) {\n      if (patternParts[i].startsWith(\":\")) {\n        const paramName = patternParts[i].slice(1);\n        params[paramName] = pathParts[i];\n      }\n    }\n\n    return params;\n  }\n}\n"],"mappings":"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"}

package/dist/{base-server-DLxtulAO.d.mts → base-server-Contwrlf.d.mts}

@@ -1,4 +1,4 @@
-import { o as Middleware } from "./types-D1PUFkda.mjs";
+import { r as Middleware } from "./types-B8Z3cMtZ.mjs";
 
 //#region src/server/base-server.d.ts
 
@@ -10,16 +10,15 @@ declare abstract class BaseServer {
   protected globalMiddleware: Middleware[];
   use(mw: Middleware): void;
   /**
-   * 打印扁平化后的路由信息，用于调试
+   * 打印路由信息，用于调试
    */
-  protected logFlattenedRoutes(routes: any[], type?: string): void;
+  protected logRoutes(routes: any[], type?: string): void;
   /**
    * 检测路由冲突
-   * 检查是否有路径相同但方法不同的路由，以及潜在的路径冲突
    */
   protected detectRouteConflicts(routes: any[]): void;
   /**
-   * 检测动态路由的潜在冲突
+   * 检测动态路由冲突
    */
   private detectDynamicRouteConflicts;
   /**
@@ -37,4 +36,4 @@ declare abstract class BaseServer {
 }
 //#endregion
 export { BaseServer as t };
-//# sourceMappingURL=base-server-DLxtulAO.d.mts.map
+//# sourceMappingURL=base-server-Contwrlf.d.mts.map

package/dist/{base64url-C2zopQdH.mjs → base64url-Cc77f1ms.mjs}

@@ -10,4 +10,4 @@ function base64urlDecode(str) {
 
 //#endregion
 export { base64urlEncode as n, base64urlDecode as t };
-//# sourceMappingURL=base64url-C2zopQdH.mjs.map
+//# sourceMappingURL=base64url-Cc77f1ms.mjs.map

package/dist/{base64url-C2zopQdH.mjs.map → base64url-Cc77f1ms.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"base64url-C2zopQdH.mjs","names":[],"sources":["../src/utils/base64url.ts"],"sourcesContent":["export function base64urlEncode(str: string): string {\n  return btoa(str)\n    .replace(/=/g, \"\") // ✅ 删除填充\n    .replace(/\\+/g, \"-\")\n    .replace(/\\//g, \"_\");\n}\n\nexport function base64urlDecode(str: string): string {\n  const pad = str.length % 4 === 0 ? \"\" : \"=\".repeat(4 - (str.length % 4));\n  const base64 = str.replace(/-/g, \"+\").replace(/_/g, \"/\") + pad;\n  return atob(base64);\n}\n"],"mappings":";AAAA,SAAgB,gBAAgB,KAAqB;AACnD,QAAO,KAAK,IAAI,CACb,QAAQ,MAAM,GAAG,CACjB,QAAQ,OAAO,IAAI,CACnB,QAAQ,OAAO,IAAI;;AAGxB,SAAgB,gBAAgB,KAAqB;CACnD,MAAM,MAAM,IAAI,SAAS,MAAM,IAAI,KAAK,IAAI,OAAO,IAAK,IAAI,SAAS,EAAG;CACxE,MAAM,SAAS,IAAI,QAAQ,MAAM,IAAI,CAAC,QAAQ,MAAM,IAAI,GAAG;AAC3D,QAAO,KAAK,OAAO"}
+{"version":3,"file":"base64url-Cc77f1ms.mjs","names":[],"sources":["../src/utils/base64url.ts"],"sourcesContent":["export function base64urlEncode(str: string): string {\n  return btoa(str)\n    .replace(/=/g, \"\") // ✅ 删除填充\n    .replace(/\\+/g, \"-\")\n    .replace(/\\//g, \"_\");\n}\n\nexport function base64urlDecode(str: string): string {\n  const pad = str.length % 4 === 0 ? \"\" : \"=\".repeat(4 - (str.length % 4));\n  const base64 = str.replace(/-/g, \"+\").replace(/_/g, \"/\") + pad;\n  return atob(base64);\n}\n"],"mappings":";AAAA,SAAgB,gBAAgB,KAAqB;AACnD,QAAO,KAAK,IAAI,CACb,QAAQ,MAAM,GAAG,CACjB,QAAQ,OAAO,IAAI,CACnB,QAAQ,OAAO,IAAI;;AAGxB,SAAgB,gBAAgB,KAAqB;CACnD,MAAM,MAAM,IAAI,SAAS,MAAM,IAAI,KAAK,IAAI,OAAO,IAAK,IAAI,SAAS,EAAG;CACxE,MAAM,SAAS,IAAI,QAAQ,MAAM,IAAI,CAAC,QAAQ,MAAM,IAAI,GAAG;AAC3D,QAAO,KAAK,OAAO"}

package/dist/{base64url-Dwi2Afhc.d.mts → base64url-DNUGwekK.d.mts}

@@ -3,4 +3,4 @@ declare function base64urlEncode(str: string): string;
 declare function base64urlDecode(str: string): string;
 //#endregion
 export { base64urlEncode as n, base64urlDecode as t };
-//# sourceMappingURL=base64url-Dwi2Afhc.d.mts.map
+//# sourceMappingURL=base64url-DNUGwekK.d.mts.map

package/dist/{component-route-nrrO0iSI.d.mts → component-route-Di7R40-2.d.mts}

@@ -1,4 +1,4 @@
-import { a as Middleware } from "./route-6A7umH7b.mjs";
+import { r as Middleware } from "./types-B8Z3cMtZ.mjs";
 
 //#region src/types/component-route.d.ts
 
@@ -28,4 +28,4 @@ interface FlattenedComponentRoute extends ComponentRoute {
 }
 //#endregion
 export { FlattenedComponentRoute as n, NestedComponentRoute as r, ComponentRoute as t };
-//# sourceMappingURL=component-route-nrrO0iSI.d.mts.map
+//# sourceMappingURL=component-route-Di7R40-2.d.mts.map

package/dist/{component-router-RwPL20vN.mjs → component-router-B6M5XDnp.mjs}

@@ -29,4 +29,4 @@ const componentRouter = () => {
 
 //#endregion
 export { flattenComponentRoutes as n, componentRouter as t };
-//# sourceMappingURL=component-router-RwPL20vN.mjs.map
+//# sourceMappingURL=component-router-B6M5XDnp.mjs.map

package/dist/{component-router-RwPL20vN.mjs.map → component-router-B6M5XDnp.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"component-router-RwPL20vN.mjs","names":[],"sources":["../src/middleware/component-router.ts"],"sourcesContent":["import type {\n  ComponentRoute,\n  NestedComponentRoute,\n  FlattenedComponentRoute,\n} from \"../types/component-route\";\nimport { vueRenderer, reactRenderer } from \"./component-renderer\";\n\n/**\n * 扁平化嵌套组件路由\n */\nexport function flattenComponentRoutes(\n  routes: (ComponentRoute | NestedComponentRoute)[],\n): FlattenedComponentRoute[] {\n  const flattened: FlattenedComponentRoute[] = [];\n\n  function processRoute(\n    route: ComponentRoute | NestedComponentRoute,\n    parentPath: string = \"\",\n    parentMiddleware: any[] = [],\n  ) {\n    const currentPath = parentPath + route.path;\n    const currentMiddleware = [\n      ...parentMiddleware,\n      ...(route.middleware || []),\n    ];\n\n    if (\"component\" in route) {\n      // 这是一个组件路由\n      flattened.push({\n        ...route,\n        fullPath: currentPath,\n        middlewareChain: currentMiddleware,\n      });\n    } else if (\"children\" in route && route.children) {\n      // 这是一个嵌套路由\n      for (const child of route.children) {\n        processRoute(child, currentPath, currentMiddleware);\n      }\n    }\n  }\n\n  for (const route of routes) {\n    processRoute(route);\n  }\n\n  return flattened;\n}\n\n/**\n * 组件路由处理器中间件\n * 自动检测组件类型并应用相应的渲染器\n */\nexport const componentRouter = () => {\n  return async (req: Request, next: () => Promise<Response>) => {\n    // 这里可以添加组件路由的自动处理逻辑\n    // 比如自动检测组件类型，应用相应的渲染器\n    return next();\n  };\n};\n"],"mappings":";;;;AAUA,SAAgB,uBACd,QAC2B;CAC3B,MAAM,YAAuC,EAAE;CAE/C,SAAS,aACP,OACA,aAAqB,IACrB,mBAA0B,EAAE,EAC5B;EACA,MAAM,cAAc,aAAa,MAAM;EACvC,MAAM,oBAAoB,CACxB,GAAG,kBACH,GAAI,MAAM,cAAc,EAAE,CAC3B;AAED,MAAI,eAAe,MAEjB,WAAU,KAAK;GACb,GAAG;GACH,UAAU;GACV,iBAAiB;GAClB,CAAC;WACO,cAAc,SAAS,MAAM,SAEtC,MAAK,MAAM,SAAS,MAAM,SACxB,cAAa,OAAO,aAAa,kBAAkB;;AAKzD,MAAK,MAAM,SAAS,OAClB,cAAa,MAAM;AAGrB,QAAO;;;;;;AAOT,MAAa,wBAAwB;AACnC,QAAO,OAAO,KAAc,SAAkC;AAG5D,SAAO,MAAM"}
+{"version":3,"file":"component-router-B6M5XDnp.mjs","names":[],"sources":["../src/middleware/component-router.ts"],"sourcesContent":["import type {\n  ComponentRoute,\n  NestedComponentRoute,\n  FlattenedComponentRoute,\n} from \"../types/component-route\";\nimport { vueRenderer, reactRenderer } from \"./component-renderer\";\n\n/**\n * 扁平化嵌套组件路由\n */\nexport function flattenComponentRoutes(\n  routes: (ComponentRoute | NestedComponentRoute)[],\n): FlattenedComponentRoute[] {\n  const flattened: FlattenedComponentRoute[] = [];\n\n  function processRoute(\n    route: ComponentRoute | NestedComponentRoute,\n    parentPath: string = \"\",\n    parentMiddleware: any[] = [],\n  ) {\n    const currentPath = parentPath + route.path;\n    const currentMiddleware = [\n      ...parentMiddleware,\n      ...(route.middleware || []),\n    ];\n\n    if (\"component\" in route) {\n      // 这是一个组件路由\n      flattened.push({\n        ...route,\n        fullPath: currentPath,\n        middlewareChain: currentMiddleware,\n      });\n    } else if (\"children\" in route && route.children) {\n      // 这是一个嵌套路由\n      for (const child of route.children) {\n        processRoute(child, currentPath, currentMiddleware);\n      }\n    }\n  }\n\n  for (const route of routes) {\n    processRoute(route);\n  }\n\n  return flattened;\n}\n\n/**\n * 组件路由处理器中间件\n * 自动检测组件类型并应用相应的渲染器\n */\nexport const componentRouter = () => {\n  return async (req: Request, next: () => Promise<Response>) => {\n    // 这里可以添加组件路由的自动处理逻辑\n    // 比如自动检测组件类型，应用相应的渲染器\n    return next();\n  };\n};\n"],"mappings":";;;;AAUA,SAAgB,uBACd,QAC2B;CAC3B,MAAM,YAAuC,EAAE;CAE/C,SAAS,aACP,OACA,aAAqB,IACrB,mBAA0B,EAAE,EAC5B;EACA,MAAM,cAAc,aAAa,MAAM;EACvC,MAAM,oBAAoB,CACxB,GAAG,kBACH,GAAI,MAAM,cAAc,EAAE,CAC3B;AAED,MAAI,eAAe,MAEjB,WAAU,KAAK;GACb,GAAG;GACH,UAAU;GACV,iBAAiB;GAClB,CAAC;WACO,cAAc,SAAS,MAAM,SAEtC,MAAK,MAAM,SAAS,MAAM,SACxB,cAAa,OAAO,aAAa,kBAAkB;;AAKzD,MAAK,MAAM,SAAS,OAClB,cAAa,MAAM;AAGrB,QAAO;;;;;;AAOT,MAAa,wBAAwB;AACnC,QAAO,OAAO,KAAc,SAAkC;AAG5D,SAAO,MAAM"}

package/dist/{component-server-DomPJ_7S.mjs → component-server-Cya46YN3.mjs}

@@ -1,8 +1,8 @@
-import { t as BaseServer } from "./base-server-B7MYJNsl.mjs";
-import { n as flattenComponentRoutes } from "./component-router-RwPL20vN.mjs";
-import { t as PathMatcher } from "./path-matcher-CGczAIl_.mjs";
-import { t as HtmlRenderer } from "./html-renderer-DTtJ_Yic.mjs";
-import { t as DependencyManager } from "./dependency-manager-DCmh7xFc.mjs";
+import { t as BaseServer } from "./base-server-CE0mfqPY.mjs";
+import { n as flattenComponentRoutes } from "./component-router-B6M5XDnp.mjs";
+import { t as PathMatcher } from "./path-matcher-Dp-DRUV9.mjs";
+import { t as HtmlRenderer } from "./html-renderer-D1zzDVQM.mjs";
+import { t as DependencyManager } from "./dependency-manager-CGMZJTer.mjs";
 
 //#region src/server/component-server.ts
 /**
@@ -17,7 +17,7 @@ var ComponentServer = class extends BaseServer {
 		this.routes = flattenComponentRoutes(routes);
 		this.dependencyManager = new DependencyManager();
 		this.detectRouteConflicts(this.routes);
-		this.logFlattenedRoutes(this.routes, "组件路由");
+		this.logRoutes(this.routes, "组件路由");
 		console.log("🚀 依赖按需加载，服务器启动完成");
 	}
 	/**
@@ -116,4 +116,4 @@ var ComponentServer = class extends BaseServer {
 
 //#endregion
 export { ComponentServer as t };
-//# sourceMappingURL=component-server-DomPJ_7S.mjs.map
+//# sourceMappingURL=component-server-Cya46YN3.mjs.map

package/dist/component-server-Cya46YN3.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-server-Cya46YN3.mjs","names":[],"sources":["../src/server/component-server.ts"],"sourcesContent":["import type {\n  ComponentRoute,\n  NestedComponentRoute,\n  FlattenedComponentRoute,\n} from \"../types/component-route\";\nimport { flattenComponentRoutes } from \"../middleware/component-router\";\nimport { BaseServer } from \"./base-server\";\nimport { PathMatcher } from \"../utils/path-matcher\";\nimport { HtmlRenderer } from \"../utils/html-renderer\";\nimport { DependencyManager } from \"../utils/dependency-manager\";\n\n/**\n * 组件路由服务器\n * 专门处理声明式组件路由\n */\nexport class ComponentServer extends BaseServer {\n  private routes: FlattenedComponentRoute[];\n  private dependencyManager: DependencyManager;\n\n  constructor(routes: (ComponentRoute | NestedComponentRoute)[]) {\n    super();\n    this.routes = flattenComponentRoutes(routes);\n    this.dependencyManager = new DependencyManager();\n\n    // 检测路由冲突\n    this.detectRouteConflicts(this.routes);\n    this.logRoutes(this.routes, \"组件路由\");\n    console.log(\"🚀 依赖按需加载，服务器启动完成\");\n  }\n\n  /**\n   * 处理请求\n   */\n  async fetch(req: Request): Promise<Response> {\n    const url = new URL(req.url);\n    const pathname = url.pathname;\n    const method = req.method;\n\n    // 只支持 GET 请求\n    if (method !== \"GET\") {\n      return new Response(\"Method Not Allowed\", { status: 405 });\n    }\n\n    // 查找匹配的路由\n    let matchedRoute: FlattenedComponentRoute | null = null;\n    for (const route of this.routes) {\n      if (PathMatcher.matchPath(route.fullPath, pathname)) {\n        matchedRoute = route;\n        break;\n      }\n    }\n\n    if (!matchedRoute) {\n      return new Response(\"Not Found\", { status: 404 });\n    }\n\n    try {\n      // 创建中间件上下文\n      const context = {\n        req,\n        params: PathMatcher.extractParams(matchedRoute.fullPath, pathname),\n        query: Object.fromEntries(url.searchParams),\n        pathname,\n      };\n\n      // 执行中间件链，中间件会处理组件渲染\n      return await this.executeMiddlewareChain(\n        matchedRoute.middlewareChain,\n        context,\n        matchedRoute.component,\n      );\n    } catch (error) {\n      console.error(\"组件渲染失败:\", error);\n      return new Response(\"Internal Server Error\", { status: 500 });\n    }\n  }\n\n  /**\n   * 执行中间件链\n   */\n  private async executeMiddlewareChain(\n    middlewareChain: any[],\n    context: any,\n    componentImport: () => Promise<any>,\n  ): Promise<Response> {\n    // 创建最终的渲染函数\n    const renderComponent = async () => {\n      const componentModule = await componentImport();\n      const component = componentModule.default || componentModule;\n\n      // 自动检测组件类型\n      const componentType =\n        this.dependencyManager.detectComponentType(component);\n\n      // 按需加载依赖\n      const deps = await this.dependencyManager.getFrameworkDeps(componentType);\n\n      // 根据组件类型渲染\n      if (componentType === \"vue\") {\n        return await this.renderVueComponent(component, context, deps);\n      } else if (componentType === \"react\") {\n        return await this.renderReactComponent(component, context, deps);\n      } else {\n        throw new Error(`不支持的组件类型: ${componentType}`);\n      }\n    };\n\n    // 执行中间件链\n    let index = 0;\n    const next = async (): Promise<Response> => {\n      if (index >= middlewareChain.length) {\n        return await renderComponent();\n      }\n\n      const middleware = middlewareChain[index++];\n      return await middleware(context.req, next);\n    };\n\n    return await next();\n  }\n\n  /**\n   * 渲染 Vue 组件\n   */\n  private async renderVueComponent(\n    component: any,\n    context: any,\n    deps: any,\n  ): Promise<Response> {\n    try {\n      const [vue, renderer] = deps;\n      const app = vue.createSSRApp(component);\n\n      // 提供路由信息\n      app.provide(\"routeInfo\", {\n        params: context.params || {},\n        query: context.query || {},\n        pathname: context.pathname,\n      });\n\n      const html = await renderer.renderToString(app);\n      const fullHtml = HtmlRenderer.generateVueHtml(html, context);\n\n      return new Response(fullHtml, {\n        headers: { \"Content-Type\": \"text/html; charset=utf-8\" },\n      });\n    } catch (error) {\n      console.error(\"Vue 组件渲染失败:\", error);\n      return new Response(\"Vue Component Render Error\", { status: 500 });\n    }\n  }\n\n  /**\n   * 渲染 React 组件\n   */\n  private async renderReactComponent(\n    component: any,\n    context: any,\n    deps: any,\n  ): Promise<Response> {\n    try {\n      const [react, renderer] = deps;\n      const content = react.createElement(component, {\n        req: context.req,\n        params: context.params || {},\n        query: context.query || {},\n      });\n\n      const html = renderer.renderToString(content);\n      const fullHtml = HtmlRenderer.generateReactHtml(html, context);\n\n      return new Response(fullHtml, {\n        headers: { \"Content-Type\": \"text/html; charset=utf-8\" },\n      });\n    } catch (error) {\n      console.error(\"React 组件渲染失败:\", error);\n      return new Response(\"React Component Render Error\", { status: 500 });\n    }\n  }\n\n  /**\n   * 获取依赖管理器（用于外部访问）\n   */\n  getDependencyManager(): DependencyManager {\n    return this.dependencyManager;\n  }\n}\n"],"mappings":"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"}

package/dist/{component-server-JqpDC7wy.d.mts → component-server-fR4UV6Jq.d.mts}

@@ -1,6 +1,6 @@
-import { r as NestedComponentRoute, t as ComponentRoute } from "./component-route-nrrO0iSI.mjs";
-import { t as BaseServer } from "./base-server-DLxtulAO.mjs";
-import { t as DependencyManager } from "./dependency-manager-C3_7ic4h.mjs";
+import { r as NestedComponentRoute, t as ComponentRoute } from "./component-route-Di7R40-2.mjs";
+import { t as BaseServer } from "./base-server-Contwrlf.mjs";
+import { t as DependencyManager } from "./dependency-manager-DIN9X0Gj.mjs";
 
 //#region src/server/component-server.d.ts
 
@@ -35,4 +35,4 @@ declare class ComponentServer extends BaseServer {
 }
 //#endregion
 export { ComponentServer as t };
-//# sourceMappingURL=component-server-JqpDC7wy.d.mts.map
+//# sourceMappingURL=component-server-fR4UV6Jq.d.mts.map

package/dist/contract-BKqc9fFH.mjs

@@ -0,0 +1,114 @@
+import { o as getRouteRegistry } from "./route-registry-BzExlM2t.mjs";
+
+//#region src/utils/contract.ts
+/**
+* 从路由数组生成 API 规范
+*/
+function generateSpec(routes) {
+	const routeSpecs = [];
+	for (const route of routes) {
+		const r = route;
+		if (!r.method || !r.path) continue;
+		if (r.path === "/api-spec" || r.path === "/__spec__") continue;
+		const spec = {
+			method: r.method,
+			path: r.path
+		};
+		if (r.name) spec.name = r.name;
+		if (r.description) spec.description = r.description;
+		if (r.schema) {
+			const schema = r.schema;
+			if (schema.body || schema.query || schema.params || schema.headers || schema.cookies) {
+				spec.schema = {};
+				if (schema.body) spec.schema.body = schema.body;
+				if (schema.query) spec.schema.query = schema.query;
+				if (schema.params) spec.schema.params = schema.params;
+				if (schema.headers) spec.schema.headers = schema.headers;
+				if (schema.cookies) spec.schema.cookies = schema.cookies;
+			}
+		}
+		routeSpecs.push(spec);
+	}
+	return {
+		version: "1.0.0",
+		generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		routes: routeSpecs
+	};
+}
+/**
+* 从路由数组生成 AI 工具函数
+*
+* 可直接用于 OpenAI Function Calling / Claude Tools
+*
+* @example
+* ```typescript
+* const tools = generateAITools(routes)
+* // [{ name: 'get_users', description: '获取用户列表', parameters: {...} }]
+* ```
+*/
+function generateAITools(routes) {
+	const tools = [];
+	for (const route of routes) {
+		const r = route;
+		if (!r.method || !r.path) continue;
+		if (r.path === "/api-spec" || r.path === "/__spec__") continue;
+		const tool = { name: r.name || pathToToolName(r.method, r.path) };
+		if (r.description) tool.description = r.description;
+		if (r.schema) {
+			if (r.method === "GET" && r.schema.query) tool.parameters = r.schema.query;
+			else if (r.schema.body) tool.parameters = r.schema.body;
+		}
+		tools.push(tool);
+	}
+	return tools;
+}
+/** 从路径生成工具名 */
+function pathToToolName(method, path) {
+	const cleanSegments = path.split("/").filter(Boolean).map((s) => s.startsWith(":") ? "" : s).filter(Boolean);
+	const prefix = method.toLowerCase();
+	const suffix = cleanSegments.join("_");
+	return suffix ? `${prefix}_${suffix}` : prefix;
+}
+/**
+* 获取 API 规范
+*
+* 支持多种调用方式：
+* 1. 直接作为 handler：自动从全局 Registry 获取（推荐）
+* 2. 无参调用：同上，用于 CLI/测试
+* 3. 有参调用：显式传递路由数组（灵活场景）
+*
+* @param routesOrContext - 可选，路由数组或 handler context。不传则从全局 Registry 获取
+* @returns ApiSpec 对象
+*
+* @example
+* ```typescript
+* import { getApiSpec } from 'vafast'
+*
+* // 方式 1：直接作为 handler（推荐，最简洁）
+* { method: 'GET', path: '/api-spec', handler: getApiSpec }
+*
+* // 方式 2：显式传参（只暴露公开 API）
+* { handler: () => getApiSpec(publicRoutes) }
+*
+* // 方式 3：本地使用（CLI、测试）
+* const spec = getApiSpec()
+* ```
+*/
+function getApiSpec(routesOrContext) {
+	return generateSpec(Array.isArray(routesOrContext) && routesOrContext.length > 0 && typeof routesOrContext[0]?.method === "string" ? routesOrContext : getRoutesFromRegistry());
+}
+/**
+* 从全局 Registry 获取路由列表
+* 包含 schema 信息（Registry 存储完整路由）
+*/
+function getRoutesFromRegistry() {
+	try {
+		return getRouteRegistry().getAll();
+	} catch {
+		return [];
+	}
+}
+
+//#endregion
+export { getApiSpec as n, generateAITools as t };
+//# sourceMappingURL=contract-BKqc9fFH.mjs.map

package/dist/contract-BKqc9fFH.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-BKqc9fFH.mjs","names":[],"sources":["../src/utils/contract.ts"],"sourcesContent":["/**\n * API Spec 生成器\n *\n * 用于生成 API 规范，支持：\n * - 跨仓库类型同步\n * - AI 工具函数生成\n * - Swagger/OpenAPI 文档生成\n *\n * @example\n * ```typescript\n * import { getApiSpec } from 'vafast'\n *\n * // 方式 1：直接作为 handler（推荐，自动从全局 Registry 获取）\n * const allRoutes = [\n *   ...routes,\n *   { method: 'GET', path: '/api-spec', handler: getApiSpec }\n * ]\n *\n * // 方式 2：显式传参（灵活场景，如只暴露公开 API）\n * { handler: () => getApiSpec(publicRoutes) }\n * ```\n */\n\nimport type { TSchema } from '@sinclair/typebox'\nimport type { RouteSchema } from '../defineRoute'\nimport { getRouteRegistry } from './route-registry'\n\n/** 路由规范信息 */\ninterface RouteSpec {\n  method: string\n  path: string\n  name?: string\n  description?: string\n  schema?: {\n    body?: TSchema\n    query?: TSchema\n    params?: TSchema\n    headers?: TSchema\n    cookies?: TSchema\n  }\n}\n\n/** API 规范 */\ninterface ApiSpec {\n  version: string\n  generatedAt: string\n  routes: RouteSpec[]\n}\n\n/** AI 工具函数格式 */\ninterface AITool {\n  name: string\n  description?: string\n  parameters?: TSchema\n}\n\n/**\n * 从路由数组生成 API 规范\n */\nfunction generateSpec(routes: readonly unknown[]): ApiSpec {\n  const routeSpecs: RouteSpec[] = []\n\n  for (const route of routes) {\n    const r = route as {\n      method?: string\n      path?: string\n      name?: string\n      description?: string\n      schema?: RouteSchema\n    }\n\n    if (!r.method || !r.path) continue\n\n    // 跳过 spec 接口本身\n    if (r.path === '/api-spec' || r.path === '/__spec__') continue\n\n    const spec: RouteSpec = {\n      method: r.method,\n      path: r.path,\n    }\n\n    // 直接从路由获取 name 和 description\n    if (r.name) spec.name = r.name\n    if (r.description) spec.description = r.description\n\n    // 直接从路由获取 schema\n    if (r.schema) {\n      const schema = r.schema\n      if (schema.body || schema.query || schema.params || schema.headers || schema.cookies) {\n        spec.schema = {}\n        if (schema.body) spec.schema.body = schema.body\n        if (schema.query) spec.schema.query = schema.query\n        if (schema.params) spec.schema.params = schema.params\n        if (schema.headers) spec.schema.headers = schema.headers\n        if (schema.cookies) spec.schema.cookies = schema.cookies\n      }\n    }\n\n    routeSpecs.push(spec)\n  }\n\n  return {\n    version: '1.0.0',\n    generatedAt: new Date().toISOString(),\n    routes: routeSpecs,\n  }\n}\n\n/**\n * 从路由数组生成 AI 工具函数\n *\n * 可直接用于 OpenAI Function Calling / Claude Tools\n *\n * @example\n * ```typescript\n * const tools = generateAITools(routes)\n * // [{ name: 'get_users', description: '获取用户列表', parameters: {...} }]\n * ```\n */\nexport function generateAITools(routes: readonly unknown[]): AITool[] {\n  const tools: AITool[] = []\n\n  for (const route of routes) {\n    const r = route as {\n      method?: string\n      path?: string\n      name?: string\n      description?: string\n      schema?: RouteSchema\n    }\n\n    if (!r.method || !r.path) continue\n    if (r.path === '/api-spec' || r.path === '/__spec__') continue\n\n    // 使用 name 或从 path 生成\n    const name = r.name || pathToToolName(r.method, r.path)\n\n    const tool: AITool = { name }\n    if (r.description) tool.description = r.description\n\n    // GET 用 query，其他用 body\n    if (r.schema) {\n      if (r.method === 'GET' && r.schema.query) {\n        tool.parameters = r.schema.query\n      } else if (r.schema.body) {\n        tool.parameters = r.schema.body\n      }\n    }\n\n    tools.push(tool)\n  }\n\n  return tools\n}\n\n/** 从路径生成工具名 */\nfunction pathToToolName(method: string, path: string): string {\n  const segments = path.split('/').filter(Boolean)\n  const cleanSegments = segments\n    .map(s => s.startsWith(':') ? '' : s)\n    .filter(Boolean)\n\n  const prefix = method.toLowerCase()\n  const suffix = cleanSegments.join('_')\n\n  return suffix ? `${prefix}_${suffix}` : prefix\n}\n\n/**\n * 获取 API 规范\n *\n * 支持多种调用方式：\n * 1. 直接作为 handler：自动从全局 Registry 获取（推荐）\n * 2. 无参调用：同上，用于 CLI/测试\n * 3. 有参调用：显式传递路由数组（灵活场景）\n *\n * @param routesOrContext - 可选，路由数组或 handler context。不传则从全局 Registry 获取\n * @returns ApiSpec 对象\n *\n * @example\n * ```typescript\n * import { getApiSpec } from 'vafast'\n *\n * // 方式 1：直接作为 handler（推荐，最简洁）\n * { method: 'GET', path: '/api-spec', handler: getApiSpec }\n *\n * // 方式 2：显式传参（只暴露公开 API）\n * { handler: () => getApiSpec(publicRoutes) }\n *\n * // 方式 3：本地使用（CLI、测试）\n * const spec = getApiSpec()\n * ```\n */\nexport function getApiSpec(routesOrContext?: readonly unknown[] | Record<string, unknown>): ApiSpec {\n  // 智能检测：是路由数组还是 handler context\n  // 路由数组：Array && 第一个元素有 method 属性\n  const isRoutesArray = Array.isArray(routesOrContext) &&\n    routesOrContext.length > 0 &&\n    typeof (routesOrContext[0] as Record<string, unknown>)?.method === 'string'\n\n  const routeList = isRoutesArray\n    ? routesOrContext\n    : getRoutesFromRegistry()\n\n  return generateSpec(routeList)\n}\n\n/**\n * 从全局 Registry 获取路由列表\n * 包含 schema 信息（Registry 存储完整路由）\n */\nfunction getRoutesFromRegistry(): readonly unknown[] {\n  try {\n    const registry = getRouteRegistry()\n    return registry.getAll()\n  } catch {\n    // Registry 未初始化时返回空数组\n    return []\n  }\n}\n"],"mappings":";;;;;;AA2DA,SAAS,aAAa,QAAqC;CACzD,MAAM,aAA0B,EAAE;AAElC,MAAK,MAAM,SAAS,QAAQ;EAC1B,MAAM,IAAI;AAQV,MAAI,CAAC,EAAE,UAAU,CAAC,EAAE,KAAM;AAG1B,MAAI,EAAE,SAAS,eAAe,EAAE,SAAS,YAAa;EAEtD,MAAM,OAAkB;GACtB,QAAQ,EAAE;GACV,MAAM,EAAE;GACT;AAGD,MAAI,EAAE,KAAM,MAAK,OAAO,EAAE;AAC1B,MAAI,EAAE,YAAa,MAAK,cAAc,EAAE;AAGxC,MAAI,EAAE,QAAQ;GACZ,MAAM,SAAS,EAAE;AACjB,OAAI,OAAO,QAAQ,OAAO,SAAS,OAAO,UAAU,OAAO,WAAW,OAAO,SAAS;AACpF,SAAK,SAAS,EAAE;AAChB,QAAI,OAAO,KAAM,MAAK,OAAO,OAAO,OAAO;AAC3C,QAAI,OAAO,MAAO,MAAK,OAAO,QAAQ,OAAO;AAC7C,QAAI,OAAO,OAAQ,MAAK,OAAO,SAAS,OAAO;AAC/C,QAAI,OAAO,QAAS,MAAK,OAAO,UAAU,OAAO;AACjD,QAAI,OAAO,QAAS,MAAK,OAAO,UAAU,OAAO;;;AAIrD,aAAW,KAAK,KAAK;;AAGvB,QAAO;EACL,SAAS;EACT,8BAAa,IAAI,MAAM,EAAC,aAAa;EACrC,QAAQ;EACT;;;;;;;;;;;;;AAcH,SAAgB,gBAAgB,QAAsC;CACpE,MAAM,QAAkB,EAAE;AAE1B,MAAK,MAAM,SAAS,QAAQ;EAC1B,MAAM,IAAI;AAQV,MAAI,CAAC,EAAE,UAAU,CAAC,EAAE,KAAM;AAC1B,MAAI,EAAE,SAAS,eAAe,EAAE,SAAS,YAAa;EAKtD,MAAM,OAAe,EAAE,MAFV,EAAE,QAAQ,eAAe,EAAE,QAAQ,EAAE,KAAK,EAE1B;AAC7B,MAAI,EAAE,YAAa,MAAK,cAAc,EAAE;AAGxC,MAAI,EAAE,QACJ;OAAI,EAAE,WAAW,SAAS,EAAE,OAAO,MACjC,MAAK,aAAa,EAAE,OAAO;YAClB,EAAE,OAAO,KAClB,MAAK,aAAa,EAAE,OAAO;;AAI/B,QAAM,KAAK,KAAK;;AAGlB,QAAO;;;AAIT,SAAS,eAAe,QAAgB,MAAsB;CAE5D,MAAM,gBADW,KAAK,MAAM,IAAI,CAAC,OAAO,QAAQ,CAE7C,KAAI,MAAK,EAAE,WAAW,IAAI,GAAG,KAAK,EAAE,CACpC,OAAO,QAAQ;CAElB,MAAM,SAAS,OAAO,aAAa;CACnC,MAAM,SAAS,cAAc,KAAK,IAAI;AAEtC,QAAO,SAAS,GAAG,OAAO,GAAG,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4B1C,SAAgB,WAAW,iBAAyE;AAWlG,QAAO,aARe,MAAM,QAAQ,gBAAgB,IAClD,gBAAgB,SAAS,KACzB,OAAQ,gBAAgB,IAAgC,WAAW,WAGjE,kBACA,uBAAuB,CAEG;;;;;;AAOhC,SAAS,wBAA4C;AACnD,KAAI;AAEF,SADiB,kBAAkB,CACnB,QAAQ;SAClB;AAEN,SAAO,EAAE"}

package/dist/contract-BL3JflJ7.d.mts

@@ -0,0 +1,71 @@
+import { TSchema } from "@sinclair/typebox";
+
+//#region src/utils/contract.d.ts
+
+/** 路由规范信息 */
+interface RouteSpec {
+  method: string;
+  path: string;
+  name?: string;
+  description?: string;
+  schema?: {
+    body?: TSchema;
+    query?: TSchema;
+    params?: TSchema;
+    headers?: TSchema;
+    cookies?: TSchema;
+  };
+}
+/** API 规范 */
+interface ApiSpec {
+  version: string;
+  generatedAt: string;
+  routes: RouteSpec[];
+}
+/** AI 工具函数格式 */
+interface AITool {
+  name: string;
+  description?: string;
+  parameters?: TSchema;
+}
+/**
+ * 从路由数组生成 AI 工具函数
+ *
+ * 可直接用于 OpenAI Function Calling / Claude Tools
+ *
+ * @example
+ * ```typescript
+ * const tools = generateAITools(routes)
+ * // [{ name: 'get_users', description: '获取用户列表', parameters: {...} }]
+ * ```
+ */
+declare function generateAITools(routes: readonly unknown[]): AITool[];
+/**
+ * 获取 API 规范
+ *
+ * 支持多种调用方式：
+ * 1. 直接作为 handler：自动从全局 Registry 获取（推荐）
+ * 2. 无参调用：同上，用于 CLI/测试
+ * 3. 有参调用：显式传递路由数组（灵活场景）
+ *
+ * @param routesOrContext - 可选，路由数组或 handler context。不传则从全局 Registry 获取
+ * @returns ApiSpec 对象
+ *
+ * @example
+ * ```typescript
+ * import { getApiSpec } from 'vafast'
+ *
+ * // 方式 1：直接作为 handler（推荐，最简洁）
+ * { method: 'GET', path: '/api-spec', handler: getApiSpec }
+ *
+ * // 方式 2：显式传参（只暴露公开 API）
+ * { handler: () => getApiSpec(publicRoutes) }
+ *
+ * // 方式 3：本地使用（CLI、测试）
+ * const spec = getApiSpec()
+ * ```
+ */
+declare function getApiSpec(routesOrContext?: readonly unknown[] | Record<string, unknown>): ApiSpec;
+//#endregion
+export { getApiSpec as n, generateAITools as t };
+//# sourceMappingURL=contract-BL3JflJ7.d.mts.map