1. 项目概述一个被严重低估的“技能抽象层”设计实践“agent-skills”这个名称乍看像某个AI Agent框架里的插件包但实际它根本不是为大模型服务的——它是我在三年前接手一个大型企业级Node.js微前端平台时为解决“跨团队能力复用混乱”而亲手打磨出的一套可组合、可版本化、可类型安全校验的函数能力封装体系。它不依赖任何AI运行时也不对接LLM API核心目标只有一个让不同业务线开发的“能力模块”比如文件解析、权限校验、第三方API调用、数据脱敏能像乐高积木一样在Nx单体仓库中被任意项目安全引用、灰度升级、语义化发布。你搜到的那些“node.js安装”“typescript教程”“nx二次开发”热词恰恰暴露了当前前端/全栈工程中一个普遍被忽视的痛点我们花大量时间教人怎么装环境、写基础语法、搭脚手架却极少有人系统性地讲清楚——当代码规模突破50万行、协作人数超30人、交付节奏要求周级迭代时“把功能写出来”和“把能力可持续地管起来”完全是两件事。agent-skills就是后者那个“管起来”的基础设施。它用TypeScript的泛型联合类型约束输入输出契约用Nx的project graph实现跨项目依赖拓扑分析用semantic-release自动触发npm包发布与changelog生成最终让一个“导出Excel”技能从A团队开发、B团队验证、C团队集成全程无需人工协调版本号、无需手动拷贝代码、无需担心类型不一致。如果你正在用Nx管理多个Node.js服务或前端应用又常遇到“改一个工具函数要通知七八个组同步升级”这种事那这个项目不是玩具而是能直接砍掉20%协作成本的生产级方案。2. 核心设计思路为什么不用现有方案三个关键取舍2.1 拒绝“纯工具库”能力必须带上下文感知市面上绝大多数工具库如lodash、date-fns的设计哲学是“无状态、无依赖、纯函数”。这在小项目里很优雅但在企业级Nx单体仓库中会迅速失效。举个真实例子我们有个“用户信息脱敏”技能需要根据当前请求的租户IDtenantId动态选择脱敏规则。如果把它写成function maskUserInfo(user: User): User调用方就必须自己传入tenantId而不同业务模块获取tenantId的方式完全不同——有的从Express req.headers有的从Next.js getServerSideProps context有的从NestJS的RequestScope service。若强制要求所有调用方都做相同参数处理等于把耦合点从技能内部转移到了调用方。agent-skills的解法是定义技能执行上下文SkillContextexport interface SkillContext { tenantId: string; userId: string; requestTraceId: string; // 可扩展字段由Nx workspace根目录下的context.config.ts统一注入 }每个技能函数签名强制接收SkillContext作为第一个参数export const maskUserInfo async ( ctx: SkillContext, user: User ): PromiseUser { const rule await getMaskRule(ctx.tenantId); // 自动获得tenantId return applyRule(user, rule); };提示这不是简单的参数传递。Nx构建时会通过自定义builder自动将context.config.ts中的配置注入到所有技能的编译上下文中确保ctx对象在运行时必然存在且类型安全。这避免了传统DI容器在Node.js CLI工具中启动慢、内存占用高的问题。2.2 拒绝“全局注册”依赖关系必须可静态分析很多团队用类似SkillRegistry.register(maskUserInfo, maskUserInfo)的方式管理技能看似灵活实则埋下隐患。Nx的project graph无法识别这种运行时注册导致无法做增量构建改了一个技能不知道哪些项目会受影响无法做依赖可视化nx graph看不到技能调用链无法做权限隔离A团队的技能被B团队误用agent-skills采用文件即契约的设计每个技能必须放在libs/skills/skill-name/src/index.ts且导出必须是命名导出named export禁止default export。Nx的nrwl/jsbuilder会扫描所有libs/skills/**/src/index.ts文件自动生成libs/skills/skills-index.ts内容如下// libs/skills/skills-index.ts (自动生成勿手动修改) export * as maskUserInfo from ./mask-user-info/src; export * as parseCsv from ./parse-csv/src; export * as sendSms from ./send-sms/src; // ...其他技能这样任何项目想使用技能只能通过明确的路径导入import { maskUserInfo } from myorg/skills; // 注意这是整个skills包的入口 // 或更精确地 import { maskUserInfo } from myorg/skills/mask-user-info;Nx的nx dep-graph命令就能清晰显示apps/payment-service→libs/skills/mask-user-info→libs/shared/config的完整依赖链。当mask-user-info更新时Nx自动计算出所有受影响的应用并只重建它们。2.3 拒绝“手动发版”语义化发布必须与代码变更强绑定团队曾尝试用npm version patch npm publish流程管理技能包结果出现严重错乱A团队提交了maskUserInfo的breaking change移除了legacyMode参数但忘记改versionB团队在CI中执行npm install myorg/skills拉到的是旧版运行时报TypeError: maskUserInfo is not a function运维查日志发现同一时间线上有3个不同版本的skills包在运行agent-skills强制集成semantic-release但做了关键改造发布触发器不是监听git tag而是监听libs/skills/**/package.json的version字段变更通过Nx的affected命令版本计算逻辑分析libs/skills/skill-name/CHANGELOG.md中最近一次变更的typefeat、fix、BREAKING CHANGE而非整个仓库的commit message发布粒度每个技能独立发版myorg/skills-mask-user-info1.2.0主包myorg/skills仅作为聚合索引version跟随最高子包这样当A团队提交PR修改mask-user-info时CI检测到该技能的CHANGELOG新增了BREAKING CHANGE条目自动执行npm version major npm publish生成myorg/skills-mask-user-info2.0.0。其他技能不受影响B团队无需任何操作即可继续使用myorg/skills-parse-csv3.1.4。3. 核心实现细节从零搭建可落地的技能体系3.1 技能契约定义用TypeScript泛型锁定输入输出每个技能的index.ts必须导出一个符合SkillDefinition接口的函数// libs/skills/src/lib/skill-definition.ts export interface SkillDefinition Input extends Recordstring, unknown, Output extends Recordstring, unknown { /** * 技能唯一标识格式团队名-技能名用于日志追踪和监控 * 例payment-mask-user-info */ id: string; /** * 技能描述用于自动生成文档和IDE提示 */ description: string; /** * 执行函数第一个参数必为SkillContext第二个为业务输入 */ execute: (ctx: SkillContext, input: Input) PromiseOutput | Output; /** * 输入参数Schema用于运行时校验可选 * 使用zod定义但类型推导仍靠TS */ inputSchema?: ZodSchemaInput; }以parseCsv技能为例其index.ts实现// libs/skills/parse-csv/src/index.ts import { z } from zod; import { SkillDefinition, SkillContext } from myorg/skills/src/lib/skill-definition; export const parseCsv: SkillDefinition { content: string; delimiter?: string }, { rows: string[][]; headers: string[] } { id: data-parsing-parse-csv, description: 将CSV字符串解析为二维数组和表头, inputSchema: z.object({ content: z.string(), delimiter: z.string().optional().default(,), }), execute: async (ctx, input) { // 实际解析逻辑... return { rows: [], headers: [] }; }, };关键点在于SkillDefinition的泛型参数Input和Output直接决定了调用方的类型提示。当其他项目导入并调用时import { parseCsv } from myorg/skills/parse-csv; // TypeScript自动推导input参数必须包含content:string可选delimiter:string const result await parseCsv.execute(ctx, { content: a,b,c\n1,2,3, delimiter: ; // IDE会提示此参数可选 }); // result类型自动为{ rows: string[][]; headers: string[] } console.log(result.rows[0][1]); // 安全访问无类型错误注意这里没有用any或unknown绕过类型检查。zod的inputSchema仅用于运行时校验防止恶意输入而TypeScript的泛型约束保证了编译期类型安全。二者分工明确——Zod管运行时TS管编译时。3.2 Nx工作区配置让技能成为一等公民agent-skills不是独立npm包而是Nx workspace内的标准library project。其project.json需特殊配置// libs/skills/parse-csv/project.json { name: skills-parse-csv, root: libs/skills/parse-csv, sourceRoot: libs/skills/parse-csv/src, projectType: library, targets: { build: { executor: nrwl/js:webpack, // 使用Webpack而非tsc支持tree-shaking options: { outputPath: dist/libs/skills/parse-csv, main: libs/skills/parse-csv/src/index.ts, tsConfig: libs/skills/parse-csv/tsconfig.lib.json, assets: [libs/skills/parse-csv/*.md] } }, publish: { executor: nx-plugin:publish, // 自定义executor封装semantic-release dependsOn: [build], options: { registry: https://npm.pkg.github.com, packageName: myorg/skills-parse-csv } } }, tags: [type:skill, scope:data-parsing] // 用于Nx affected命令过滤 }最关键的改造在tsconfig.lib.json// libs/skills/parse-csv/tsconfig.lib.json { extends: ../../../tsconfig.base.json, compilerOptions: { outDir: ../../dist/out-tsc, types: [node, jest], // 关键启用declarationMap让消费方能跳转到源码 declarationMap: true, // 关键禁用skipLibCheck确保技能间类型引用严格校验 skipLibCheck: false }, include: [**/*.ts], exclude: [jest.config.ts, **/*.spec.ts] }这样配置后Nx的nx build skills-parse-csv会生成dist/libs/skills/parse-csv/index.d.ts类型声明文件dist/libs/skills/parse-csv/index.jsESM模块dist/libs/skills/parse-csv/index.mjsESM模块dist/libs/skills/parse-csv/index.cjsCommonJS模块消费方无论用import还是require都能获得正确的类型和运行时代码。3.3 语义化发布流水线精准控制每个技能的生命周期agent-skills的CI发布不是简单跑npx semantic-release而是分三步执行第一步生成变更摘要pre-publishNx的affected命令扫描所有修改的skills提取其CHANGELOG中的变更类型# 在CI中执行 nx affected --targetprint-changelog --baseorigin/main --headHEAD \ --projectsskills-* --selectprojects输出JSON[ { project: skills-mask-user-info, changes: [ { type: BREAKING CHANGE, subject: remove legacyMode param } ] }, { project: skills-parse-csv, changes: [ { type: feat, subject: add support for quoted fields } ] } ]第二步按类型升级版本version根据变更类型执行npm versionBREAKING CHANGE→npm version majorfeat→npm version minorfix或其他 →npm version patch第三步独立发布publish对每个技能执行npm publish并打Git tag# 发布skills-mask-user-info cd dist/libs/skills/mask-user-info npm publish --taglatest git tag myorg/skills-mask-user-info2.0.0 git push origin myorg/skills-mask-user-info2.0.0实操心得我们曾因未打tag导致npm view myorg/skills-mask-user-info versions返回空数组。后来在publish脚本末尾强制添加git push --tags并用npm view命令做最终校验——只有npm view返回非空版本列表才认为发布成功。3.4 技能调用层封装让业务代码干净得像伪代码业务项目如apps/payment-service不直接调用技能函数而是通过统一的SkillExecutor// apps/payment-service/src/lib/skill-executor.ts import { SkillContext } from myorg/skills/src/lib/skill-definition; import { maskUserInfo } from myorg/skills/mask-user-info; export class SkillExecutor { static async executeTInput, TOutput( skill: { execute: (ctx: SkillContext, input: TInput) PromiseTOutput }, ctx: SkillContext, input: TInput ): PromiseTOutput { try { const result await skill.execute(ctx, input); // 统一日志记录skill.id、耗时、输入摘要脱敏后 console.log([SKILL] ${skill.id} executed in 120ms); return result; } catch (error) { // 统一错误处理添加skill.id上下文便于追踪 throw new Error(Skill ${skill.id} failed: ${error.message}); } } }业务代码调用变得极其简洁// apps/payment-service/src/app/payment.controller.ts import { SkillExecutor } from ../lib/skill-executor; import { maskUserInfo } from myorg/skills/mask-user-info; Controller() export class PaymentController { Post(/process) async process(Body() dto: PaymentDto) { // 构建SkillContext从request中提取tenantId等 const ctx: SkillContext { tenantId: dto.tenantId, userId: dto.userId, requestTraceId: this.generateTraceId(), }; // 一行代码调用技能类型安全日志统一错误可追溯 const maskedUser await SkillExecutor.execute(maskUserInfo, ctx, dto.user); return this.paymentService.process(maskedUser, dto.order); } }4. 实操全流程从创建新技能到上线监控4.1 创建新技能标准化五步法假设要新增一个“发送短信验证码”技能按以下步骤操作Step 1生成Nx library projectnx g nrwl/js:library skills-send-sms \ --directoryskills/send-sms \ --importPathmyorg/skills-send-sms \ --publishabletrue \ --no-interactiveStep 2编写技能契约强制编辑libs/skills/send-sms/src/index.tsimport { z } from zod; import { SkillDefinition, SkillContext } from myorg/skills/src/lib/skill-definition; export const sendSmsCode: SkillDefinition { phone: string; templateId: string; params: Recordstring, string }, { requestId: string; expireAt: number } { id: notification-send-sms-code, description: 向手机号发送短信验证码返回请求ID和过期时间, inputSchema: z.object({ phone: z.string().regex(/^1[3-9]\d{9}$/), templateId: z.string(), params: z.record(z.string()), }), execute: async (ctx, input) { // 调用阿里云SMS SDK const result await aliyunSms.send(input.phone, input.templateId, input.params); return { requestId: result.RequestId, expireAt: Date.now() 5 * 60 * 1000, // 5分钟过期 }; }, };Step 3编写CHANGELOG强制libs/skills/send-sms/CHANGELOG.md# Change Log All notable changes to this project will be documented in this file. ## [1.0.0](https://github.com/myorg/workspace/compare/skills-send-sms-v0.9.0...skills-send-sms-v1.0.0) (2024-06-15) ### Features - add sendSmsCode skill for sending verification code ([#1234](https://github.com/myorg/workspace/pull/1234))Step 4添加测试用例强制libs/skills/send-sms/src/index.spec.tsimport { sendSmsCode } from ./index; describe(sendSmsCode, () { it(should return requestId and expireAt, async () { // Mock SDK jest.mock(aliyun-sms-sdk, () ({ send: jest.fn().mockResolvedValue({ RequestId: req-123 }), })); const ctx { tenantId: t1, userId: u1, requestTraceId: trace-1 }; const result await sendSmsCode.execute(ctx, { phone: 13800138000, templateId: SMS_123, params: { code: 1234 }, }); expect(result.requestId).toBe(req-123); expect(result.expireAt).toBeGreaterThan(Date.now()); }); });Step 5提交PR并触发CI提交包含以上4个文件的PRCI自动执行nx test skills-send-sms→ 运行单元测试nx build skills-send-sms→ 生成dist包nx affected --targetpublish→ 检测变更并发布myorg/skills-send-sms1.0.04.2 技能升级如何安全地做breaking change某天发现sendSmsCode需要支持多通道短信/邮件/站内信原签名execute(ctx, input)已不够用。按以下流程升级Step 1创建新版本分支git checkout -b feat/sms-multi-channel origin/mainStep 2修改技能定义保持向后兼容// libs/skills/send-sms/src/index.ts export const sendSmsCode: SkillDefinition { channel: sms | email | internal; // 新增channel字段 phone?: string; // 原phone字段变为可选 email?: string; templateId: string; params: Recordstring, string; }, { requestId: string; expireAt: number } { id: notification-send-sms-code, description: 支持多通道的消息发送技能, inputSchema: z.object({ channel: z.enum([sms, email, internal]), phone: z.string().regex(/^1[3-9]\d{9}$/).optional(), email: z.string().email().optional(), templateId: z.string(), params: z.record(z.string()), }), execute: async (ctx, input) { if (input.channel sms) { // 兼容旧逻辑 return await sendSms(input.phone!, input.templateId, input.params); } // 新逻辑... }, };Step 3更新CHANGELOG标记breaking change## [2.0.0](https://github.com/myorg/workspace/compare/skills-send-sms-v1.0.0...skills-send-sms-v2.0.0) (2024-07-20) ### BREAKING CHANGES - remove required phone field, add channel and email fields ([#1567](https://github.com/myorg/workspace/pull/1567))Step 4CI自动发布v2.0.0同时保留v1.0.0由于语义化发布是独立的myorg/skills-send-sms1.0.0和myorg/skills-send-sms2.0.0同时存在于npm registry。老项目继续用v1新项目可选择v2。注意事项Nx的affected命令会检测到skills-send-sms的major version变更自动标记所有依赖它的项目为“可能受影响”需人工确认是否升级。这是故意设计的“安全阀”避免自动化升级引发线上事故。4.3 监控与可观测性给每个技能装上仪表盘agent-skills内置轻量级监控无需额外部署PrometheusStep 1在SkillExecutor中注入监控// apps/payment-service/src/lib/skill-executor.ts import { performance } from perf_hooks; export class SkillExecutor { static async executeTInput, TOutput( skill: { id: string; execute: (ctx: SkillContext, input: TInput) PromiseTOutput }, ctx: SkillContext, input: TInput ): PromiseTOutput { const start performance.now(); try { const result await skill.execute(ctx, input); const duration performance.now() - start; // 上报到内部监控服务伪代码 monitor.report({ skillId: skill.id, tenantId: ctx.tenantId, duration, status: success, inputSize: JSON.stringify(input).length, }); return result; } catch (error) { const duration performance.now() - start; monitor.report({ skillId: skill.id, tenantId: ctx.tenantId, duration, status: error, errorType: error.constructor.name, }); throw error; } } }Step 2生成技能健康报告Nx提供nx report skills-health命令汇总所有技能的最近7天调用次数、成功率、P95延迟各版本使用占比如skills-send-sms1.0.0占80%2.0.0占20%未被任何项目引用的“僵尸技能”报告样例Skill IDVersionCalls(7d)Success RateP95 LatencyConsumersnotification-send-sms-code2.0.012,45099.98%320mspayment, auth>paths: { myorg/skills-*: [libs/skills/*/src/index.ts] }确认apps/payment-service/tsconfig.json的extends指向../../tsconfig.base.json重启TS ServerVS Code中按CtrlShiftP→TypeScript: Restart TS server避坑技巧在Nx workspace中永远不要手动修改node_modules/myorg/skills-*的package.json中的types字段。所有类型声明均由Nx的nrwl/jsbuilder自动生成并写入dist/目录package.json中的types应始终指向./index.d.ts。5.2 发布失败npm publish报错“403 Forbidden”现象CI中执行npm publish失败错误信息为403 Forbidden - PUT https://registry.npmjs.org/myorg/skills-send-sms - You do not have permission to publish myorg/skills-send-sms. Are you logged in as the correct user?根因NPM Token权限不足或Token过期。解决方案登录NPM官网进入Account Settings→Tokens确认Token具有Publish权限在CI中将Token设为Secret如GitHub Actions的NPM_TOKEN并在publish步骤中注入- name: Publish to NPM run: npm publish env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}关键检查确认package.json中的name字段与NPM registry中组织名完全一致包括大小写。MyOrg/skills-send-sms≠myorg/skills-send-sms。5.3 技能调用超时为什么execute()卡住不返回现象sendSmsCode.execute()调用后Promise永不resolve也无reject。根因技能函数内部未正确处理异步异常或SDK未设置timeout。解决方案在技能函数中强制添加timeout包装export const sendSmsCode { // ...其他字段 execute: async (ctx, input) { const controller new AbortController(); const timeoutId setTimeout(() controller.abort(), 5000); // 5秒超时 try { const result await aliyunSms.send(input.phone, input.templateId, input.params, { signal: controller.signal // 传递AbortSignal给SDK }); clearTimeout(timeoutId); return result; } catch (error) { clearTimeout(timeoutId); if (error.name AbortError) { throw new Error(SMS send timeout after 5s); } throw error; } } };在SkillExecutor中增加全局timeoutstatic async executeTInput, TOutput( skill: { execute: (ctx: SkillContext, input: TInput) PromiseTOutput }, ctx: SkillContext, input: TInput, timeoutMs: number 10000 // 默认10秒 ) { const controller new AbortController(); const timeoutId setTimeout(() controller.abort(), timeoutMs); try { const result await Promise.race([ skill.execute(ctx, input), new Promisenever((_, reject) setTimeout(() reject(new Error(Skill ${skill.id} timeout)), timeoutMs) ) ]); clearTimeout(timeoutId); return result; } catch (error) { clearTimeout(timeoutId); throw error; } }5.4 版本混乱为什么npm view myorg/skills-send-sms versions返回空现象本地npm publish成功但npm view查不到版本其他项目npm install失败。根因Git tag未推送或NPM registry缓存延迟。解决方案确认tag已推送git tag查看本地taggit ls-remote --tags origin查看远程tag若tag缺失手动推送git push origin tag-name清除NPM缓存npm cache clean --force终极验证直接访问https://registry.npmjs.org/myorg/skills-send-sms查看返回JSON中的versions字段实操心得我们曾因CI脚本中git push --tags命令失败但未设set -e导致tag丢失。现在所有publish脚本开头都加set -euxo pipefail确保任一命令失败立即终止。5.5 技能滥用如何防止业务代码绕过SkillExecutor直接调用现象审计发现apps/auth-service中有代码直接import { sendSmsCode } from myorg/skills-send-sms并调用sendSmsCode.execute()绕过了统一的日志和监控。根因缺乏代码规范约束。解决方案在tslint.json或eslint.config.js中添加自定义规则no-direct-skill-import: { meta: { type: suggestion, docs: { description: 禁止直接导入skills必须通过SkillExecutor调用, }, }, create: (context) { return { ImportDeclaration: (node) { const source node.source.value; if (source.startsWith(myorg/skills-)) { context.report({ node, message: Direct import of skills is forbidden. Use SkillExecutor instead., }); } }, }; }, }在CI中强制执行nx lint失败则阻断发布这样任何绕过SkillExecutor的导入都会在PR阶段被拦截从源头杜绝监控盲区。6. 后续演进从技能封装到能力治理平台agent-skills已稳定运行三年支撑了公司23个核心业务系统。但真正的挑战不在技术实现而在组织协同。我们正推动三个方向的演进第一技能市场Skills Marketplace计划将libs/skills目录转为内部Git repo各团队以PR方式提交技能由架构委员会审核。审核项包括是否有完备的单元测试覆盖率≥80%CHANGELOG是否符合规范含type、subject、link是否提供性能基准测试对比同类技能 审核通过后自动合并并触发发布。这不再是“我写你用”而是“大家共建共享”。第二技能SLA契约为关键技能如payment-process-payment定义SLAP99延迟 ≤ 200ms年度可用率 ≥ 99.99%故障响应时间 ≤ 15分钟SLA指标接入公司统一监控平台未达标自动触发告警并计入团队OKR。第三技能AI辅助利用TypeScript AST分析为开发者提供智能建议当检测到if (user.phone) { sendSms(...) }时提示“检测到短信发送逻辑是否使用myorg/skills-send-sms技能点击一键替换”当sendSmsCode.execute()调用缺少try/catch时提示“技能调用建议包裹错误处理参考SkillExecutor模式”这些不是炫技而是把三年来沉淀的“最佳实践”变成开发者触手可及的生产力工具。agent-skills的终点从来不是代码本身而是让每个工程师都能在复杂系统中依然写出清晰、可靠、可演进的代码。 
长河君 · 2026/9/16 5:10:30 · 阅读 1.2k Nx工作区下的可组合技能封装体系设计与实践
1. 项目概述一个被严重低估的“技能抽象层”设计实践“agent-skills”这个名称乍看像某个AI Agent框架里的插件包但实际它根本不是为大模型服务的——它是我在三年前接手一个大型企业级Node.js微前端平台时为解决“跨团队能力复用混乱”而亲手打磨出的一套可组合、可版本化、可类型安全校验的函数能力封装体系。它不依赖任何AI运行时也不对接LLM API核心目标只有一个让不同业务线开发的“能力模块”比如文件解析、权限校验、第三方API调用、数据脱敏能像乐高积木一样在Nx单体仓库中被任意项目安全引用、灰度升级、语义化发布。你搜到的那些“node.js安装”“typescript教程”“nx二次开发”热词恰恰暴露了当前前端/全栈工程中一个普遍被忽视的痛点我们花大量时间教人怎么装环境、写基础语法、搭脚手架却极少有人系统性地讲清楚——当代码规模突破50万行、协作人数超30人、交付节奏要求周级迭代时“把功能写出来”和“把能力可持续地管起来”完全是两件事。agent-skills就是后者那个“管起来”的基础设施。它用TypeScript的泛型联合类型约束输入输出契约用Nx的project graph实现跨项目依赖拓扑分析用semantic-release自动触发npm包发布与changelog生成最终让一个“导出Excel”技能从A团队开发、B团队验证、C团队集成全程无需人工协调版本号、无需手动拷贝代码、无需担心类型不一致。如果你正在用Nx管理多个Node.js服务或前端应用又常遇到“改一个工具函数要通知七八个组同步升级”这种事那这个项目不是玩具而是能直接砍掉20%协作成本的生产级方案。2. 核心设计思路为什么不用现有方案三个关键取舍2.1 拒绝“纯工具库”能力必须带上下文感知市面上绝大多数工具库如lodash、date-fns的设计哲学是“无状态、无依赖、纯函数”。这在小项目里很优雅但在企业级Nx单体仓库中会迅速失效。举个真实例子我们有个“用户信息脱敏”技能需要根据当前请求的租户IDtenantId动态选择脱敏规则。如果把它写成function maskUserInfo(user: User): User调用方就必须自己传入tenantId而不同业务模块获取tenantId的方式完全不同——有的从Express req.headers有的从Next.js getServerSideProps context有的从NestJS的RequestScope service。若强制要求所有调用方都做相同参数处理等于把耦合点从技能内部转移到了调用方。agent-skills的解法是定义技能执行上下文SkillContextexport interface SkillContext { tenantId: string; userId: string; requestTraceId: string; // 可扩展字段由Nx workspace根目录下的context.config.ts统一注入 }每个技能函数签名强制接收SkillContext作为第一个参数export const maskUserInfo async ( ctx: SkillContext, user: User ): PromiseUser { const rule await getMaskRule(ctx.tenantId); // 自动获得tenantId return applyRule(user, rule); };提示这不是简单的参数传递。Nx构建时会通过自定义builder自动将context.config.ts中的配置注入到所有技能的编译上下文中确保ctx对象在运行时必然存在且类型安全。这避免了传统DI容器在Node.js CLI工具中启动慢、内存占用高的问题。2.2 拒绝“全局注册”依赖关系必须可静态分析很多团队用类似SkillRegistry.register(maskUserInfo, maskUserInfo)的方式管理技能看似灵活实则埋下隐患。Nx的project graph无法识别这种运行时注册导致无法做增量构建改了一个技能不知道哪些项目会受影响无法做依赖可视化nx graph看不到技能调用链无法做权限隔离A团队的技能被B团队误用agent-skills采用文件即契约的设计每个技能必须放在libs/skills/skill-name/src/index.ts且导出必须是命名导出named export禁止default export。Nx的nrwl/jsbuilder会扫描所有libs/skills/**/src/index.ts文件自动生成libs/skills/skills-index.ts内容如下// libs/skills/skills-index.ts (自动生成勿手动修改) export * as maskUserInfo from ./mask-user-info/src; export * as parseCsv from ./parse-csv/src; export * as sendSms from ./send-sms/src; // ...其他技能这样任何项目想使用技能只能通过明确的路径导入import { maskUserInfo } from myorg/skills; // 注意这是整个skills包的入口 // 或更精确地 import { maskUserInfo } from myorg/skills/mask-user-info;Nx的nx dep-graph命令就能清晰显示apps/payment-service→libs/skills/mask-user-info→libs/shared/config的完整依赖链。当mask-user-info更新时Nx自动计算出所有受影响的应用并只重建它们。2.3 拒绝“手动发版”语义化发布必须与代码变更强绑定团队曾尝试用npm version patch npm publish流程管理技能包结果出现严重错乱A团队提交了maskUserInfo的breaking change移除了legacyMode参数但忘记改versionB团队在CI中执行npm install myorg/skills拉到的是旧版运行时报TypeError: maskUserInfo is not a function运维查日志发现同一时间线上有3个不同版本的skills包在运行agent-skills强制集成semantic-release但做了关键改造发布触发器不是监听git tag而是监听libs/skills/**/package.json的version字段变更通过Nx的affected命令版本计算逻辑分析libs/skills/skill-name/CHANGELOG.md中最近一次变更的typefeat、fix、BREAKING CHANGE而非整个仓库的commit message发布粒度每个技能独立发版myorg/skills-mask-user-info1.2.0主包myorg/skills仅作为聚合索引version跟随最高子包这样当A团队提交PR修改mask-user-info时CI检测到该技能的CHANGELOG新增了BREAKING CHANGE条目自动执行npm version major npm publish生成myorg/skills-mask-user-info2.0.0。其他技能不受影响B团队无需任何操作即可继续使用myorg/skills-parse-csv3.1.4。3. 核心实现细节从零搭建可落地的技能体系3.1 技能契约定义用TypeScript泛型锁定输入输出每个技能的index.ts必须导出一个符合SkillDefinition接口的函数// libs/skills/src/lib/skill-definition.ts export interface SkillDefinition Input extends Recordstring, unknown, Output extends Recordstring, unknown { /** * 技能唯一标识格式团队名-技能名用于日志追踪和监控 * 例payment-mask-user-info */ id: string; /** * 技能描述用于自动生成文档和IDE提示 */ description: string; /** * 执行函数第一个参数必为SkillContext第二个为业务输入 */ execute: (ctx: SkillContext, input: Input) PromiseOutput | Output; /** * 输入参数Schema用于运行时校验可选 * 使用zod定义但类型推导仍靠TS */ inputSchema?: ZodSchemaInput; }以parseCsv技能为例其index.ts实现// libs/skills/parse-csv/src/index.ts import { z } from zod; import { SkillDefinition, SkillContext } from myorg/skills/src/lib/skill-definition; export const parseCsv: SkillDefinition { content: string; delimiter?: string }, { rows: string[][]; headers: string[] } { id: data-parsing-parse-csv, description: 将CSV字符串解析为二维数组和表头, inputSchema: z.object({ content: z.string(), delimiter: z.string().optional().default(,), }), execute: async (ctx, input) { // 实际解析逻辑... return { rows: [], headers: [] }; }, };关键点在于SkillDefinition的泛型参数Input和Output直接决定了调用方的类型提示。当其他项目导入并调用时import { parseCsv } from myorg/skills/parse-csv; // TypeScript自动推导input参数必须包含content:string可选delimiter:string const result await parseCsv.execute(ctx, { content: a,b,c\n1,2,3, delimiter: ; // IDE会提示此参数可选 }); // result类型自动为{ rows: string[][]; headers: string[] } console.log(result.rows[0][1]); // 安全访问无类型错误注意这里没有用any或unknown绕过类型检查。zod的inputSchema仅用于运行时校验防止恶意输入而TypeScript的泛型约束保证了编译期类型安全。二者分工明确——Zod管运行时TS管编译时。3.2 Nx工作区配置让技能成为一等公民agent-skills不是独立npm包而是Nx workspace内的标准library project。其project.json需特殊配置// libs/skills/parse-csv/project.json { name: skills-parse-csv, root: libs/skills/parse-csv, sourceRoot: libs/skills/parse-csv/src, projectType: library, targets: { build: { executor: nrwl/js:webpack, // 使用Webpack而非tsc支持tree-shaking options: { outputPath: dist/libs/skills/parse-csv, main: libs/skills/parse-csv/src/index.ts, tsConfig: libs/skills/parse-csv/tsconfig.lib.json, assets: [libs/skills/parse-csv/*.md] } }, publish: { executor: nx-plugin:publish, // 自定义executor封装semantic-release dependsOn: [build], options: { registry: https://npm.pkg.github.com, packageName: myorg/skills-parse-csv } } }, tags: [type:skill, scope:data-parsing] // 用于Nx affected命令过滤 }最关键的改造在tsconfig.lib.json// libs/skills/parse-csv/tsconfig.lib.json { extends: ../../../tsconfig.base.json, compilerOptions: { outDir: ../../dist/out-tsc, types: [node, jest], // 关键启用declarationMap让消费方能跳转到源码 declarationMap: true, // 关键禁用skipLibCheck确保技能间类型引用严格校验 skipLibCheck: false }, include: [**/*.ts], exclude: [jest.config.ts, **/*.spec.ts] }这样配置后Nx的nx build skills-parse-csv会生成dist/libs/skills/parse-csv/index.d.ts类型声明文件dist/libs/skills/parse-csv/index.jsESM模块dist/libs/skills/parse-csv/index.mjsESM模块dist/libs/skills/parse-csv/index.cjsCommonJS模块消费方无论用import还是require都能获得正确的类型和运行时代码。3.3 语义化发布流水线精准控制每个技能的生命周期agent-skills的CI发布不是简单跑npx semantic-release而是分三步执行第一步生成变更摘要pre-publishNx的affected命令扫描所有修改的skills提取其CHANGELOG中的变更类型# 在CI中执行 nx affected --targetprint-changelog --baseorigin/main --headHEAD \ --projectsskills-* --selectprojects输出JSON[ { project: skills-mask-user-info, changes: [ { type: BREAKING CHANGE, subject: remove legacyMode param } ] }, { project: skills-parse-csv, changes: [ { type: feat, subject: add support for quoted fields } ] } ]第二步按类型升级版本version根据变更类型执行npm versionBREAKING CHANGE→npm version majorfeat→npm version minorfix或其他 →npm version patch第三步独立发布publish对每个技能执行npm publish并打Git tag# 发布skills-mask-user-info cd dist/libs/skills/mask-user-info npm publish --taglatest git tag myorg/skills-mask-user-info2.0.0 git push origin myorg/skills-mask-user-info2.0.0实操心得我们曾因未打tag导致npm view myorg/skills-mask-user-info versions返回空数组。后来在publish脚本末尾强制添加git push --tags并用npm view命令做最终校验——只有npm view返回非空版本列表才认为发布成功。3.4 技能调用层封装让业务代码干净得像伪代码业务项目如apps/payment-service不直接调用技能函数而是通过统一的SkillExecutor// apps/payment-service/src/lib/skill-executor.ts import { SkillContext } from myorg/skills/src/lib/skill-definition; import { maskUserInfo } from myorg/skills/mask-user-info; export class SkillExecutor { static async executeTInput, TOutput( skill: { execute: (ctx: SkillContext, input: TInput) PromiseTOutput }, ctx: SkillContext, input: TInput ): PromiseTOutput { try { const result await skill.execute(ctx, input); // 统一日志记录skill.id、耗时、输入摘要脱敏后 console.log([SKILL] ${skill.id} executed in 120ms); return result; } catch (error) { // 统一错误处理添加skill.id上下文便于追踪 throw new Error(Skill ${skill.id} failed: ${error.message}); } } }业务代码调用变得极其简洁// apps/payment-service/src/app/payment.controller.ts import { SkillExecutor } from ../lib/skill-executor; import { maskUserInfo } from myorg/skills/mask-user-info; Controller() export class PaymentController { Post(/process) async process(Body() dto: PaymentDto) { // 构建SkillContext从request中提取tenantId等 const ctx: SkillContext { tenantId: dto.tenantId, userId: dto.userId, requestTraceId: this.generateTraceId(), }; // 一行代码调用技能类型安全日志统一错误可追溯 const maskedUser await SkillExecutor.execute(maskUserInfo, ctx, dto.user); return this.paymentService.process(maskedUser, dto.order); } }4. 实操全流程从创建新技能到上线监控4.1 创建新技能标准化五步法假设要新增一个“发送短信验证码”技能按以下步骤操作Step 1生成Nx library projectnx g nrwl/js:library skills-send-sms \ --directoryskills/send-sms \ --importPathmyorg/skills-send-sms \ --publishabletrue \ --no-interactiveStep 2编写技能契约强制编辑libs/skills/send-sms/src/index.tsimport { z } from zod; import { SkillDefinition, SkillContext } from myorg/skills/src/lib/skill-definition; export const sendSmsCode: SkillDefinition { phone: string; templateId: string; params: Recordstring, string }, { requestId: string; expireAt: number } { id: notification-send-sms-code, description: 向手机号发送短信验证码返回请求ID和过期时间, inputSchema: z.object({ phone: z.string().regex(/^1[3-9]\d{9}$/), templateId: z.string(), params: z.record(z.string()), }), execute: async (ctx, input) { // 调用阿里云SMS SDK const result await aliyunSms.send(input.phone, input.templateId, input.params); return { requestId: result.RequestId, expireAt: Date.now() 5 * 60 * 1000, // 5分钟过期 }; }, };Step 3编写CHANGELOG强制libs/skills/send-sms/CHANGELOG.md# Change Log All notable changes to this project will be documented in this file. ## [1.0.0](https://github.com/myorg/workspace/compare/skills-send-sms-v0.9.0...skills-send-sms-v1.0.0) (2024-06-15) ### Features - add sendSmsCode skill for sending verification code ([#1234](https://github.com/myorg/workspace/pull/1234))Step 4添加测试用例强制libs/skills/send-sms/src/index.spec.tsimport { sendSmsCode } from ./index; describe(sendSmsCode, () { it(should return requestId and expireAt, async () { // Mock SDK jest.mock(aliyun-sms-sdk, () ({ send: jest.fn().mockResolvedValue({ RequestId: req-123 }), })); const ctx { tenantId: t1, userId: u1, requestTraceId: trace-1 }; const result await sendSmsCode.execute(ctx, { phone: 13800138000, templateId: SMS_123, params: { code: 1234 }, }); expect(result.requestId).toBe(req-123); expect(result.expireAt).toBeGreaterThan(Date.now()); }); });Step 5提交PR并触发CI提交包含以上4个文件的PRCI自动执行nx test skills-send-sms→ 运行单元测试nx build skills-send-sms→ 生成dist包nx affected --targetpublish→ 检测变更并发布myorg/skills-send-sms1.0.04.2 技能升级如何安全地做breaking change某天发现sendSmsCode需要支持多通道短信/邮件/站内信原签名execute(ctx, input)已不够用。按以下流程升级Step 1创建新版本分支git checkout -b feat/sms-multi-channel origin/mainStep 2修改技能定义保持向后兼容// libs/skills/send-sms/src/index.ts export const sendSmsCode: SkillDefinition { channel: sms | email | internal; // 新增channel字段 phone?: string; // 原phone字段变为可选 email?: string; templateId: string; params: Recordstring, string; }, { requestId: string; expireAt: number } { id: notification-send-sms-code, description: 支持多通道的消息发送技能, inputSchema: z.object({ channel: z.enum([sms, email, internal]), phone: z.string().regex(/^1[3-9]\d{9}$/).optional(), email: z.string().email().optional(), templateId: z.string(), params: z.record(z.string()), }), execute: async (ctx, input) { if (input.channel sms) { // 兼容旧逻辑 return await sendSms(input.phone!, input.templateId, input.params); } // 新逻辑... }, };Step 3更新CHANGELOG标记breaking change## [2.0.0](https://github.com/myorg/workspace/compare/skills-send-sms-v1.0.0...skills-send-sms-v2.0.0) (2024-07-20) ### BREAKING CHANGES - remove required phone field, add channel and email fields ([#1567](https://github.com/myorg/workspace/pull/1567))Step 4CI自动发布v2.0.0同时保留v1.0.0由于语义化发布是独立的myorg/skills-send-sms1.0.0和myorg/skills-send-sms2.0.0同时存在于npm registry。老项目继续用v1新项目可选择v2。注意事项Nx的affected命令会检测到skills-send-sms的major version变更自动标记所有依赖它的项目为“可能受影响”需人工确认是否升级。这是故意设计的“安全阀”避免自动化升级引发线上事故。4.3 监控与可观测性给每个技能装上仪表盘agent-skills内置轻量级监控无需额外部署PrometheusStep 1在SkillExecutor中注入监控// apps/payment-service/src/lib/skill-executor.ts import { performance } from perf_hooks; export class SkillExecutor { static async executeTInput, TOutput( skill: { id: string; execute: (ctx: SkillContext, input: TInput) PromiseTOutput }, ctx: SkillContext, input: TInput ): PromiseTOutput { const start performance.now(); try { const result await skill.execute(ctx, input); const duration performance.now() - start; // 上报到内部监控服务伪代码 monitor.report({ skillId: skill.id, tenantId: ctx.tenantId, duration, status: success, inputSize: JSON.stringify(input).length, }); return result; } catch (error) { const duration performance.now() - start; monitor.report({ skillId: skill.id, tenantId: ctx.tenantId, duration, status: error, errorType: error.constructor.name, }); throw error; } } }Step 2生成技能健康报告Nx提供nx report skills-health命令汇总所有技能的最近7天调用次数、成功率、P95延迟各版本使用占比如skills-send-sms1.0.0占80%2.0.0占20%未被任何项目引用的“僵尸技能”报告样例Skill IDVersionCalls(7d)Success RateP95 LatencyConsumersnotification-send-sms-code2.0.012,45099.98%320mspayment, auth>paths: { myorg/skills-*: [libs/skills/*/src/index.ts] }确认apps/payment-service/tsconfig.json的extends指向../../tsconfig.base.json重启TS ServerVS Code中按CtrlShiftP→TypeScript: Restart TS server避坑技巧在Nx workspace中永远不要手动修改node_modules/myorg/skills-*的package.json中的types字段。所有类型声明均由Nx的nrwl/jsbuilder自动生成并写入dist/目录package.json中的types应始终指向./index.d.ts。5.2 发布失败npm publish报错“403 Forbidden”现象CI中执行npm publish失败错误信息为403 Forbidden - PUT https://registry.npmjs.org/myorg/skills-send-sms - You do not have permission to publish myorg/skills-send-sms. Are you logged in as the correct user?根因NPM Token权限不足或Token过期。解决方案登录NPM官网进入Account Settings→Tokens确认Token具有Publish权限在CI中将Token设为Secret如GitHub Actions的NPM_TOKEN并在publish步骤中注入- name: Publish to NPM run: npm publish env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}关键检查确认package.json中的name字段与NPM registry中组织名完全一致包括大小写。MyOrg/skills-send-sms≠myorg/skills-send-sms。5.3 技能调用超时为什么execute()卡住不返回现象sendSmsCode.execute()调用后Promise永不resolve也无reject。根因技能函数内部未正确处理异步异常或SDK未设置timeout。解决方案在技能函数中强制添加timeout包装export const sendSmsCode { // ...其他字段 execute: async (ctx, input) { const controller new AbortController(); const timeoutId setTimeout(() controller.abort(), 5000); // 5秒超时 try { const result await aliyunSms.send(input.phone, input.templateId, input.params, { signal: controller.signal // 传递AbortSignal给SDK }); clearTimeout(timeoutId); return result; } catch (error) { clearTimeout(timeoutId); if (error.name AbortError) { throw new Error(SMS send timeout after 5s); } throw error; } } };在SkillExecutor中增加全局timeoutstatic async executeTInput, TOutput( skill: { execute: (ctx: SkillContext, input: TInput) PromiseTOutput }, ctx: SkillContext, input: TInput, timeoutMs: number 10000 // 默认10秒 ) { const controller new AbortController(); const timeoutId setTimeout(() controller.abort(), timeoutMs); try { const result await Promise.race([ skill.execute(ctx, input), new Promisenever((_, reject) setTimeout(() reject(new Error(Skill ${skill.id} timeout)), timeoutMs) ) ]); clearTimeout(timeoutId); return result; } catch (error) { clearTimeout(timeoutId); throw error; } }5.4 版本混乱为什么npm view myorg/skills-send-sms versions返回空现象本地npm publish成功但npm view查不到版本其他项目npm install失败。根因Git tag未推送或NPM registry缓存延迟。解决方案确认tag已推送git tag查看本地taggit ls-remote --tags origin查看远程tag若tag缺失手动推送git push origin tag-name清除NPM缓存npm cache clean --force终极验证直接访问https://registry.npmjs.org/myorg/skills-send-sms查看返回JSON中的versions字段实操心得我们曾因CI脚本中git push --tags命令失败但未设set -e导致tag丢失。现在所有publish脚本开头都加set -euxo pipefail确保任一命令失败立即终止。5.5 技能滥用如何防止业务代码绕过SkillExecutor直接调用现象审计发现apps/auth-service中有代码直接import { sendSmsCode } from myorg/skills-send-sms并调用sendSmsCode.execute()绕过了统一的日志和监控。根因缺乏代码规范约束。解决方案在tslint.json或eslint.config.js中添加自定义规则no-direct-skill-import: { meta: { type: suggestion, docs: { description: 禁止直接导入skills必须通过SkillExecutor调用, }, }, create: (context) { return { ImportDeclaration: (node) { const source node.source.value; if (source.startsWith(myorg/skills-)) { context.report({ node, message: Direct import of skills is forbidden. Use SkillExecutor instead., }); } }, }; }, }在CI中强制执行nx lint失败则阻断发布这样任何绕过SkillExecutor的导入都会在PR阶段被拦截从源头杜绝监控盲区。6. 后续演进从技能封装到能力治理平台agent-skills已稳定运行三年支撑了公司23个核心业务系统。但真正的挑战不在技术实现而在组织协同。我们正推动三个方向的演进第一技能市场Skills Marketplace计划将libs/skills目录转为内部Git repo各团队以PR方式提交技能由架构委员会审核。审核项包括是否有完备的单元测试覆盖率≥80%CHANGELOG是否符合规范含type、subject、link是否提供性能基准测试对比同类技能 审核通过后自动合并并触发发布。这不再是“我写你用”而是“大家共建共享”。第二技能SLA契约为关键技能如payment-process-payment定义SLAP99延迟 ≤ 200ms年度可用率 ≥ 99.99%故障响应时间 ≤ 15分钟SLA指标接入公司统一监控平台未达标自动触发告警并计入团队OKR。第三技能AI辅助利用TypeScript AST分析为开发者提供智能建议当检测到if (user.phone) { sendSms(...) }时提示“检测到短信发送逻辑是否使用myorg/skills-send-sms技能点击一键替换”当sendSmsCode.execute()调用缺少try/catch时提示“技能调用建议包裹错误处理参考SkillExecutor模式”这些不是炫技而是把三年来沉淀的“最佳实践”变成开发者触手可及的生产力工具。agent-skills的终点从来不是代码本身而是让每个工程师都能在复杂系统中依然写出清晰、可靠、可演进的代码。