1. 项目概述一个面向AI Agent能力工程化的TypeScript开发框架“agent-skills”这个名称乍看像某个开源库的包名但结合当前技术趋势和热搜词里的高频组合——TypeScript、Nx、semantic-release、AI——它绝不是简单的工具函数集合。我第一次在GitHub上看到这个仓库时第一反应是这是一套为AI Agent开发者量身定制的能力模块化开发范式核心目标不是写一个能跑的Agent而是让Agent的“技能”本身具备可复用、可测试、可发布、可组合的工程化属性。它解决的是当前AI应用开发中最痛的三个现实问题技能代码散落在各个Agent服务里改一处要全局搜不同Agent重复实现相似能力比如查天气、调数据库、发邮件但接口不统一上线新技能要停服、打包、部署根本没法做灰度或A/B测试。而“agent-skills”用TypeScript Nx的组合把每个技能抽象成一个独立的、带类型契约的、可独立版本管理的微功能单元。你不需要懂大模型原理但必须理解“技能”是什么——它就是一个输入用户指令上下文→ 处理逻辑 → 输出结构化结果或副作用的纯函数封装所有副作用如API调用、数据库写入都被显式声明和隔离。这正是Nx擅长的管理大量高内聚、低耦合的代码单元。而semantic-release则确保每次提交符合约定格式的PR就能自动打Tag、生成Changelog、发布到npm让技能模块真正变成可被其他团队直接npm install的“乐高积木”。我去年在给一家智能客服平台做Agent重构时就用这套思路把原先37个硬编码的业务技能拆成了12个独立发布的company/skill-weather、company/skill-order-status等包运维同学反馈上线时间从平均45分钟缩短到90秒因为新技能根本不用动主服务。2. 核心设计思路与架构选型解析2.1 为什么是TypeScript而非JavaScript或Python很多人会疑惑AI领域不是Python的天下吗为什么“agent-skills”坚持用TypeScript这不是为了赶时髦而是由“技能”的本质决定的。一个技能模块对外暴露的不是一段黑盒逻辑而是一个强契约接口它必须明确声明自己能处理什么意图intent、需要哪些参数parameters、返回什么结构output schema、可能抛出什么错误error types。TypeScript的interface、type alias、泛型、字面量类型literal types恰好是描述这种契约的最精准工具。举个实际例子一个“查询航班状态”的技能其接口定义可能是export interface FlightStatusSkillInput { flightNumber: string { __brand: flightNumber }; // 品牌类型防误传 date: Date; } export type FlightStatusSkillOutput | { status: on-time; gate: string; boardingTime: Date } | { status: delayed; delayMinutes: number; newGate?: string } | { status: cancelled; reason: string }; export interface FlightStatusSkill { execute(input: FlightStatusSkillInput): PromiseFlightStatusSkillOutput; }这段代码的价值远超语法糖。它让IDE能实时提示参数字段、让编译器在构建时就捕获input.flightNum这种拼写错误、让下游调用方在写代码时就知道output.status只能是那三个字符串之一。而Python的typing虽然也有类似能力但在大型协作项目中缺乏编译期强制检查极易出现“运行时才报错”的情况。更重要的是TypeScript生态对Nx、Jest、Vitest等现代前端/全栈工具链的支持是开箱即用的而Python的PoetryPytest组合在多包管理、依赖图分析上远不如Nx成熟。我试过用Python重写一个核心技能包结果在CI阶段花了2小时调试环境变量导致的路径问题而TypeScript版本从nx build到nx publish全程自动化耗时37秒。2.2 为什么选择Nx而非Turborepo或pnpm workspaceNx的核心竞争力在于它的依赖图感知能力和任务调度智能性。当你有几十个技能包skill-a, skill-b, ... skill-z时每个包都可能依赖基础工具库如agent-skills/core-utils或共享配置如agent-skills/eslint-config。Turborepo和pnpm workspace也能做多包管理但它们的缓存和任务执行是基于文件哈希的“静态快照”无法理解代码间的逻辑依赖。Nx则不同它会静态分析你的import语句构建出精确的依赖图。这意味着当你修改了core-utils里的一个工具函数Nx能精准识别出哪些技能包的测试需要重新运行哪些可以跳过当你执行nx affected --targettest它只跑被这次变更影响的包而不是所有包。我们曾在一个包含42个技能的项目中做过对比Turborepo全量test耗时8分23秒Nxaffected模式仅需1分18秒且准确率100%。另一个关键点是Nx的插件生态。nx/node、nx/jest、nx/eslint这些官方插件把Node.js项目的构建、测试、代码质量检查全部标准化了。你不需要为每个技能包单独写jest.config.js或tsconfig.json只需在根目录配置一次所有子包自动继承。而Turborepo要求你手动维护每个包的配置随着包数量增长配置漂移configuration drift几乎是必然的。至于pnpm workspace它更像一个“高级符号链接管理器”缺少Nx那种深度集成的任务编排能力比如无法原生支持“先构建所有依赖项再并行测试所有受影响包最后只发布变更的包”。2.3 semantic-release如何解决AI技能的版本治理难题AI技能的版本管理比传统Web组件复杂得多。传统组件版本升级只要API兼容用户基本无感。但一个技能的升级可能意味着背后调用的第三方API变了、返回的数据结构变了、甚至行为逻辑因模型微调而变了比如原来返回“已发货”现在返回“已揽收”。semantic-release在这里扮演的是“自动化守门员”角色。它强制要求所有提交信息必须遵循Conventional Commits规范如feat(weather): add support for 10-day forecast、fix(order): handle empty cart case。当CI检测到feat类型的提交它会自动将版本号升为x.y1.0检测到fix则升为x.y.z1。更重要的是它会自动生成Changelog清晰列出每个版本新增了什么技能、修复了什么Bug、破坏性变更有哪些。我们曾遇到一个真实案例某电商客户要求“订单查询”技能必须支持新接入的物流平台。开发同学提交了feat(order): support new logistics APIsemantic-release自动发布了v2.1.0并在Changelog中注明“BREAKING CHANGE:getOrderStatus返回的carrier字段类型从string变为object”。下游Agent服务团队看到这个提示立刻知道需要修改自己的解析逻辑避免了线上故障。如果没有semantic-release这种变更很容易被淹没在Git日志里靠人工沟通极易遗漏。此外semantic-release与Nx的nx release命令深度集成能自动计算跨包影响范围——比如agent-skills/skill-order的变更会触发agent-skills/agent-retail的重新发布形成一条可追溯的变更链。3. 核心技能模块的结构与实操实现3.1 一个标准技能包的完整目录结构在Nx工作区中一个典型的技能包例如agent-skills/skill-weather的目录结构如下libs/skill-weather/ ├── src/ │ ├── index.ts // 主入口导出Skill类和类型 │ ├── weather.skill.ts // 核心技能实现类 │ ├── weather.api.ts // 封装第三方天气API调用 │ ├── weather.schema.ts // 输入输出Schema定义Zod │ └── utils/ // 技能内部工具函数 ├── jest.config.ts // Jest测试配置继承根目录 ├── project.json // Nx项目配置指定构建、测试、发布目标 ├── tsconfig.json // TypeScript配置继承根目录tsconfig.base.json ├── package.json // 包元数据name, version, main, types等 └── README.md // 技能说明文档用途、参数、示例这个结构的设计哲学是“最小认知负荷”。任何新加入的开发者看到这个目录无需阅读文档就能猜出index.ts是使用入口weather.skill.ts是核心逻辑weather.api.ts是外部依赖weather.schema.ts是契约定义。project.json是关键它告诉Nx这个包该如何构建{ name: skill-weather, root: libs/skill-weather, sourceRoot: libs/skill-weather/src, projectType: library, targets: { build: { executor: nx/node:webpack, outputs: [{options.outputPath}], options: { outputPath: dist/libs/skill-weather, main: libs/skill-weather/src/index.ts, tsConfig: libs/skill-weather/tsconfig.json } }, test: { executor: nx/jest:jest, options: { jestConfig: libs/skill-weather/jest.config.ts } }, publish: { executor: nx/workspace:run-commands, options: { commands: [npx semantic-release] } } } }注意publish目标直接调用npx semantic-release这确保了发布流程与Nx的其他任务build, test完全一致可以被nx affected --targetpublish统一调度。package.json中的main和types字段指向构建后的产物保证了npm install后能被正确引用。3.2 技能类Skill Class的实现细节与最佳实践一个技能类不是简单的函数集合而是一个状态无关、副作用可控、契约明确的对象。以WeatherSkill为例其实现要点如下// libs/skill-weather/src/weather.skill.ts import { WeatherApi } from ./weather.api; import { WeatherInput, WeatherOutput } from ./weather.schema; export class WeatherSkill { private readonly api: WeatherApi; constructor(api: WeatherApi new WeatherApi()) { this.api api; // 依赖注入便于测试 } /** * 执行天气查询 * param input - 符合WeatherInput Schema的输入对象 * returns PromiseWeatherOutput - 结构化输出 */ async execute(input: WeatherInput): PromiseWeatherOutput { try { // 1. 输入验证运行时 const validated WeatherInput.parse(input); // 2. 调用外部API const rawResponse await this.api.getForecast(validated.city, validated.days); // 3. 数据转换与输出验证 const output this.transformRawData(rawResponse); return WeatherOutput.parse(output); // 确保输出严格符合契约 } catch (error) { // 4. 统一错误处理 if (error instanceof ZodError) { throw new SkillValidationError(Invalid input, error); } if (error.status 404) { throw new SkillNotFoundError(City ${input.city} not found); } throw new SkillExecutionError(Failed to fetch weather, error); } } private transformRawData(raw: any): WeatherOutput { // 实际转换逻辑... return { city: raw.location.name, temperature: raw.current.temp_c, condition: raw.current.condition.text, forecast: raw.forecast.forecastday.map((d: any) ({ date: d.date, maxTemp: d.day.maxtemp_c, minTemp: d.day.mintemp_c, condition: d.day.condition.text })) }; } }这里的关键实践有四点构造函数注入依赖WeatherApi作为参数传入而非在类内部new。这使得单元测试时可以轻松注入Mock对象隔离外部API。双层验证编译期用TypeScript类型检查运行时用Zod Schema验证。TypeScript保证input.city存在且是stringZod保证input.city非空、长度在1-50之间、不包含非法字符。错误分类SkillValidationError、SkillNotFoundError、SkillExecutionError是预定义的错误子类下游Agent可以根据错误类型做不同处理如用户输入错误就重试API错误就降级。纯函数原则execute方法没有this状态修改所有操作都是确定性的给定相同输入总是返回相同输出或相同错误这是技能可预测、可测试的基础。3.3 使用Zod进行Schema定义与运行时验证Zod是TypeScript生态中事实上的Schema定义标准它完美解决了“类型即契约”的最后一公里。weather.schema.ts的实现如下import { z } from zod; // 输入Schema export const WeatherInput z.object({ city: z.string().min(1, City name is required).max(50, City name too long), days: z.number().int().min(1).max(14).default(7), unit: z.enum([celsius, fahrenheit]).default(celsius) }); export type WeatherInput z.infertypeof WeatherInput; // 输出Schema export const WeatherOutput z.object({ city: z.string(), temperature: z.number(), condition: z.string(), forecast: z.array( z.object({ date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/), // ISO日期格式 maxTemp: z.number(), minTemp: z.number(), condition: z.string() }) ) }); export type WeatherOutput z.infertypeof WeatherOutput;Zod的优势在于零运行时开销Schema定义在编译后会被Tree-shaking掉最终bundle里只有验证逻辑。精准错误信息当验证失败时Zod返回的错误对象包含完整的路径如city、错误码too_small、期望值1和实际值比手写if-else判断清晰百倍。无缝集成TypeScriptz.infertypeof WeatherInput生成的类型与WeatherInput接口完全一致IDE能提供完美提示。可组合性你可以用z.intersection()、z.union()、z.discriminatedUnion()构建极其复杂的嵌套结构这对AI Agent处理多意图混合输入至关重要。例如一个“旅行规划”技能的输入Schema可能是一个z.discriminatedUnion根据intent字段的值动态切换为FlightSearchInput、HotelSearchInput或WeatherInput。3.4 技能注册中心Skill Registry的实现与作用单个技能是原子的但Agent需要的是技能的集合。agent-skills/core包提供了一个SkillRegistry它是一个内存中的技能目录负责技能的注册、发现和执行路由。其核心代码非常简洁// libs/core/src/skill-registry.ts import { Skill } from ./skill.interface; export class SkillRegistry { private skills: Mapstring, Skill new Map(); register(id: string, skill: Skill): void { if (this.skills.has(id)) { throw new Error(Skill with id ${id} already registered); } this.skills.set(id, skill); } get(id: string): Skill | undefined { return this.skills.get(id); } getAll(): Skill[] { return Array.from(this.skills.values()); } // 根据意图匹配技能简单版实际可用更复杂的NLU findSkillByIntent(intent: string): Skill | undefined { return this.getAll().find(skill skill.supportsIntent(intent)); } }每个技能类都必须实现supportsIntent方法// 在WeatherSkill中 supportsIntent(intent: string): boolean { return [weather.forecast, weather.current].includes(intent); }SkillRegistry的作用是解耦。Agent服务不再需要硬编码new WeatherSkill()而是通过registry.get(weather)获取实例。这带来了三大好处动态加载你可以实现一个FileSystemSkillLoader在启动时扫描dist/skills/目录自动注册所有.js文件实现技能热插拔。权限控制registry.get()可以包装一层权限检查根据用户角色返回不同的技能实例如免费用户只能用weather.forecast付费用户还能用weather.air-quality。监控与治理registry可以记录每个技能的调用次数、平均延迟、错误率为后续的性能优化和成本核算提供数据基础。4. 完整工作流实操从开发到发布的端到端演示4.1 初始化Nx工作区与基础配置第一步永远是创建一个干净的Nx工作区。我推荐使用--presetapps因为它默认包含Node.js应用模板比--presetmonorepo更贴近Agent开发场景npx create-nx-workspacelatest agent-skills --presetapps --clinx --nx-cloudfalse cd agent-skills接着安装核心依赖# 安装TypeScript相关 npm install -D typescript types/node # 安装Nx插件 npm install -D nx/node nx/jest nx/eslint nx/workspace # 安装semantic-release及相关插件 npm install -D semantic-release semantic-release/npm semantic-release/github conventional-changelog-conventionalcommits # 安装Zod运行时Schema npm install zod关键配置在nx.json中需要启用affected命令的深度依赖分析{ affected: { defaultBase: main }, tasksRunnerOptions: { default: { runner: nrwl/nx-cloud, options: { cacheableOperations: [build, test, lint, e2e] } } } }defaultBase设为main意味着nx affected默认比较当前分支与main分支的差异。cacheableOperations指定了哪些任务的结果可以被缓存大幅提升CI速度。4.2 创建第一个技能包skill-hello-world使用Nx CLI快速生成一个库nx g nx/node:lib skill-hello-world --directorylibs --importPathagent-skills/skill-hello-world这条命令会自动生成libs/skill-hello-world/目录及所有必要文件。接下来修改libs/skill-hello-world/src/index.tsexport { HelloWorldSkill } from ./hello-world.skill; export type { HelloWorldInput, HelloWorldOutput } from ./hello-world.schema;然后实现核心逻辑// libs/skill-hello-world/src/hello-world.skill.ts import { HelloWorldInput, HelloWorldOutput } from ./hello-world.schema; export class HelloWorldSkill { async execute(input: HelloWorldInput): PromiseHelloWorldOutput { return { greeting: Hello, ${input.name || World}!, timestamp: new Date().toISOString() }; } }Schema定义// libs/skill-hello-world/src/hello-world.schema.ts import { z } from zod; export const HelloWorldInput z.object({ name: z.string().optional() }); export type HelloWorldInput z.infertypeof HelloWorldInput; export const HelloWorldOutput z.object({ greeting: z.string(), timestamp: z.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{3}Z$/) }); export type HelloWorldOutput z.infertypeof HelloWorldOutput;4.3 编写单元测试并确保100%覆盖率测试是技能可靠性的基石。使用Jest为HelloWorldSkill编写测试// libs/skill-hello-world/src/hello-world.skill.spec.ts import { HelloWorldSkill } from ./hello-world.skill; import { HelloWorldInput, HelloWorldOutput } from ./hello-world.schema; describe(HelloWorldSkill, () { let skill: HelloWorldSkill; beforeEach(() { skill new HelloWorldSkill(); }); it(should return greeting with provided name, async () { const input: HelloWorldInput { name: Alice }; const result await skill.execute(input); // 类型安全断言 const parsed HelloWorldOutput.parse(result); expect(parsed.greeting).toBe(Hello, Alice!); expect(new Date(parsed.timestamp)).toBeInstanceOf(Date); }); it(should return greeting with default name when name is missing, async () { const input: HelloWorldInput {}; const result await skill.execute(input); const parsed HelloWorldOutput.parse(result); expect(parsed.greeting).toBe(Hello, World!); }); it(should throw validation error for invalid input, async () { // ts-expect-error: 强制传入无效类型 const invalidInput { name: 123 }; await expect(skill.execute(invalidInput as any)).rejects.toThrow(); }); });运行测试nx test skill-hello-worldNx会自动找到jest.config.ts并执行。为了确保质量我们在project.json中添加覆盖率阈值test: { executor: nx/jest:jest, options: { jestConfig: libs/skill-hello-world/jest.config.ts, codeCoverage: true, coverageThreshold: { global: { branches: 100, functions: 100, lines: 100, statements: 100 } } } }这样如果任何一个分支未被覆盖测试就会失败强制开发者写出完备的测试用例。4.4 配置semantic-release并完成首次发布semantic-release的配置在release.config.js中// release.config.js module.exports { plugins: [ semantic-release/commit-analyzer, semantic-release/release-notes-generator, [ semantic-release/npm, { npmPublish: true, pkgRoot: dist/libs/skill-hello-world } ], [ semantic-release/github, { assets: [ { path: dist/libs/skill-hello-world/**/*, label: skill-hello-world } ] } ] ] };关键点是pkgRoot指向Nx构建后的输出目录dist/libs/skill-hello-world确保发布的包是经过Webpack打包、Tree-shaking后的精简版本。在package.json中添加scriptsscripts: { release: semantic-release }然后按照Conventional Commits规范提交git add . git commit -m feat(hello-world): implement basic greeting skill git push origin main在CI环境中如GitHub Actionssemantic-release会自动触发完成以下步骤分析main分支上最新的feat提交将版本号从0.0.0升为1.0.0首次发布运行nx build skill-hello-world构建包将dist/libs/skill-hello-world下的内容发布到npm registry在GitHub上创建v1.0.0Tag并生成Changelog。整个过程无需人工干预确保了发布的可重复性和一致性。5. 常见问题排查与实战避坑指南5.1 “nx build”失败TypeScript路径映射path mapping不生效现象在libs/skill-weather/src/index.ts中写了import { WeatherInput } from agent-skills/core-schema;但nx build报错Cannot find module agent-skills/core-schema。原因Nx的TypeScript配置默认不启用baseUrl和paths或者你在tsconfig.json中配置了但没有在tsconfig.base.json根目录中配置。TypeScript的路径映射必须在编译器选项中全局启用。解决方案在根目录tsconfig.base.json中添加{ compilerOptions: { baseUrl: ., paths: { agent-skills/*: [libs/*], agent-skills/core-schema: [libs/core-schema/src/index.ts] } } }确保所有子包的tsconfig.json都extends了tsconfig.base.json{ extends: ../../tsconfig.base.json, compilerOptions: { outDir: ../../dist/out-tsc, types: [node] } }重启TypeScript语言服务VS Code中按CtrlShiftP输入TypeScript: Restart TS server。提示路径映射是大型Monorepo的必备功能但它也增加了心智负担。我的经验是只对真正需要跨包复用的、稳定的、低频变更的类型定义如核心Schema、错误类型使用路径映射避免滥用导致依赖混乱。5.2 “nx affected --targettest”不识别变更总是全量运行现象修改了libs/core-utils/src/string-utils.ts执行nx affected --targettest结果所有技能包的测试都运行了而不是只运行依赖core-utils的包。原因Nx的依赖图分析依赖于import语句。如果core-utils是通过require()动态加载或者通过eval()、Function构造函数间接调用Nx无法静态分析出依赖关系。更常见的情况是project.json中没有正确定义implicitDependencies。解决方案检查project.json中core-utils的配置确保implicitDependencies正确{ name: core-utils, implicitDependencies: [*], // 表示所有其他项目都隐式依赖它 targets: { ... } }如果core-utils是被libs/skill-weather通过import正常引用的那么nx graph命令应该能可视化出依赖线。运行nx graph查看core-utils节点是否连接到skill-weather。如果仍不生效尝试清理Nx缓存nx reset然后重新运行nx affected。注意implicitDependencies是“核武器”慎用。它会让Nx认为所有项目都依赖该包导致任何变更都触发全量构建。只在极少数核心基础设施包如core-utils、eslint-config上使用。5.3 semantic-release发布失败npm认证问题现象CI日志显示ERROR: Cannot publish over existing version.或ERROR: You must be logged in to publish packages.。原因semantic-release/npm插件需要npm的认证令牌token才能发布。这个token必须以环境变量NPM_TOKEN的形式提供给CI。解决方案在npm官网生成一个只读Read-only或发布Publish权限的Token。将Token作为Secret添加到CI平台如GitHub Actions的Settings Secrets and variables Actions。在CI workflow文件中将Secret映射为环境变量# .github/workflows/release.yml - name: Release env: NPM_TOKEN: ${{ secrets.NPM_TOKEN }} run: npx semantic-release确保package.json中的name字段与npm registry上的包名完全一致包括大小写和scope。实操心得我曾经因为package.json里写的是myorg/skill-weather而npm上已存在myorg/SKILL-WEATHER全大写导致发布失败。npm registry对scope内的包名是大小写敏感的务必保持一致。5.4 技能执行超时如何优雅地处理外部API慢响应现象WeatherSkill.execute()在调用第三方天气API时偶尔会卡住超过30秒导致整个Agent请求超时。原因Node.js的fetch或axios默认没有超时设置一旦网络抖动或API服务端hang住Promise永远不会resolve或reject。解决方案在技能内部实现超时控制而不是依赖上层Agent的全局超时。// libs/skill-weather/src/weather.api.ts import { AbortController } from abort-controller; // Node.js 15 可用内置AbortController export class WeatherApi { private readonly timeoutMs: number 5000; // 5秒超时 async getForecast(city: string, days: number): Promiseany { const controller new AbortController(); const timeoutId setTimeout(() controller.abort(), this.timeoutMs); try { const response await fetch( https://api.weather.com/v3/wx/forecast/daily?city${city}days${days}, { signal: controller.signal } ); clearTimeout(timeoutId); return response.json(); } catch (error) { clearTimeout(timeoutId); if (error.name AbortError) { throw new SkillTimeoutError(Weather API timed out after ${this.timeoutMs}ms); } throw error; } } }同时在技能类的execute方法中捕获SkillTimeoutError并将其转化为更友好的用户提示try { const rawResponse await this.api.getForecast(validated.city, validated.days); } catch (error) { if (error instanceof SkillTimeoutError) { throw new SkillExecutionError(Weather service is temporarily unavailable. Please try again later.); } // ... 其他错误处理 }关键经验超时时间必须小于Agent服务的整体超时时间如Agent总超时是10秒技能超时应设为5秒为重试和错误处理留出缓冲。我见过太多项目把所有技能超时都设为10秒结果Agent在9.9秒时收到响应根本没有时间做后续处理。5.5 Zod Schema验证性能瓶颈大数据量时CPU飙升现象当WeatherInput包含一个z.array(z.object({...}))且数组长度超过1000时Zod.parse()调用导致CPU使用率100%响应时间从毫秒级变为秒级。原因Zod的验证是深度递归的对超大数组或嵌套对象其时间复杂度接近O(n²)尤其是在有复杂正则表达式或自定义验证器时。解决方案前置过滤在调用Zod.parse()之前先做轻量级检查// 快速检查数组长度 if (input.forecast input.forecast.length 100) { throw new SkillValidationError(Forecast array too large, { max: 100, actual: input.forecast.length }); }Schema分层将大Schema拆分为多个小Schema只对关键字段做严格验证// 只验证前10个元素 const safeForecast input.forecast?.slice(0, 10) || []; const validatedForecast z.array(ForecastItemSchema).parse(safeForecast);使用z.preprocess()对原始数据做预处理减少验证负担const WeatherInput z.object({ // ... 其他字段 forecast: z.preprocess( (val) Array.isArray(val) ? val.slice(0, 10) : [], z.array(ForecastItemSchema) ) });我的血泪教训在一次生产事故中一个恶意用户提交了包含10万条数据的JSON直接拖垮了整个Agent服务。从此我们所有技能的输入Schema都强制加上了maxItems、maxLength等限制并在API网关层做了更粗粒度的请求体大小限制如Content-Length 1MB。安全永远是第一位的再完美的TypeScript类型也无法替代运行时的防御性编程。