1. 项目概述一个被严重低估的 TypeScript 工程化能力基座“agent-skills”这个名称乍看像某个 AI 智能体的技能插件包但结合热搜词agent-skills、TypeScript、node、Nx、semantic-release再叠加全网高频出现的typescript面试、nx二次开发、typescript nestjs、node安装及环境配置等长尾搜索行为真相立刻清晰这不是一个面向终端用户的“AI技能库”而是一个面向前端/全栈工程师的、可复用、可组合、可版本化管理的 TypeScript 能力模块集合工程——它的核心价值是把散落在团队各处的“小而关键”的业务逻辑比如表单校验规则、API 请求封装策略、状态同步协议、错误分类映射、权限判定断言、国际化键值提取器从应用代码中剥离出来沉淀为标准化、类型安全、带语义化版本号、支持按需导入的独立 npm 包。我做过 7 个中大型企业级前端平台几乎每个都经历过这样的阶段初期用utils/目录堆砌函数半年后utils/index.ts膨胀到 2000 行类型定义混乱A 团队改了一个deepMerge的空值处理逻辑B 团队的表单提交就突然多出 3 个undefined字段再后来大家开始写myorg/core-utils但发布靠手动npm publish版本号乱打1.0.0 → 1.0.1 → 2.0.0 → 1.1.0没人知道哪个版本修复了date-fns的时区 bug最后终于上了 Nx结果发现libs/shared/utils里混着 UI 组件、HTTP 客户端、Mock 数据生成器根本没法单独测试或升级。“agent-skills”正是对这一整套工程病的精准手术刀式回应——它不解决“怎么写 React 组件”而是解决“怎么让 20 个开发者写的 50 个工具函数在 3 年内持续可靠、零冲突地协同进化”。关键词agent-skills在这里不是指 AI Agent 的技能而是取其字面本义“agent” 即“代理者、执行者”“skills” 即“可复用的能力单元”。每个 skill 都是一个独立的、有明确定义输入输出、自带类型守门、自带单元测试、自带 changelog 的最小可交付单元。比如myorg/agent-skills-http-client封装了 Axios 实例 token 自动注入 错误结构标准化myorg/agent-skills-form-validator提供基于 Zod Schema 的运行时校验 错误消息 i18n 映射myorg/agent-skills-permission实现 RBAC 规则解析器 权限缓存策略。它们不耦合 UI不依赖框架只依赖标准 Web API 或 Node.js 内置模块。这种设计让 TypeScript 不再只是“加了类型的 JavaScript”而是真正成为契约编译器——当你 import 一个 skillTypeScript 编译器就在强制你遵守它声明的契约任何破坏契约的修改都会在tsc --noEmit阶段直接报错而不是等到上线后用户点击按钮才崩溃。这套模式特别适合三类人一是正在用 Nx 构建 monorepo 的团队需要把共享逻辑从libs/shared里解耦出来避免“牵一发而动全身”二是准备做技术中台的前端架构师需要向下游业务方提供稳定、可追溯、可灰度发布的 SDK三是正在准备typescript面试的中级开发者——面试官问“如何设计一个可维护的工具函数库”你如果只答“放 utils 文件夹”那基本等于交白卷但如果你能说出“按领域拆分为 agent-skills每个 skill 独立测试、语义化发布、Nx workspace.json 中配置 buildable lib”对方立刻会给你加 5 分。它不是炫技而是把“写好代码”这件事从个人习惯升维成工程规范。2. 整体架构设计为什么必须用 Nx semantic-release TypeScript 三位一体2.1 为什么不用 Lerna为什么不用 pnpm workspaces 单独搞很多团队看到“多包管理”第一反应是 Lerna。我试过 Lerna v4 和 v5也用 pnpm workspaces 搭过纯 TS monorepo结论很明确Lerna 是过渡方案pnpm workspaces 是轻量替代但都不足以支撑“agent-skills”这种对可靠性、可追溯性、自动化程度要求极高的场景。Lerna 的核心缺陷在于它把“版本管理”和“发布流程”混在一起lerna version会自动修改所有包的 package.json但无法保证修改后的版本号符合语义化规则比如你改了http-client的内部实现但没改接口它可能仍会升 minor更致命的是Lerna 的--conventional-commits模式依赖 commit message 格式而实际开发中90% 的 PR 描述都是“fix bug”、“优化性能”根本没人写feat(http-client): add timeout config这种严格格式。我们曾因一个chore(deps): update axios的 commit 被 Lerna 误判为 breaking change导致所有下游包被迫升大版本引发连锁构建失败。pnpm workspaces 更轻量但缺失关键能力它没有内置的跨包依赖图分析无法智能判断“改了form-validator是否影响ui-components”它没有内置的增量构建每次 CI 都要全量编译所有包它没有内置的发布流水线你得自己写 shell 脚本调用pnpm publish而pnpm publish本身不校验语义化版本也不自动生成 changelog。当你的agent-skills库增长到 30 个子包时这些“缺失”就会变成每天消耗 2 小时的人力成本。2.2 Nx 是唯一能闭环解决这些问题的工程化平台Nx 的设计哲学是“以依赖图驱动一切”。当你在workspace.json里定义一个myorg/agent-skills-http-client的 libNx 会自动扫描它的import语句构建出精确的依赖图。这意味着增量构建CI 只构建被修改的 skill 及其直系依赖http-client的改动不会触发permission的重新编译影响分析nx graph命令能可视化展示“改了这个 skill 会影响哪些应用”PR 检查时自动运行nx affected:build确保不破坏下游任务调度nx run-many --targetbuild --projects...可并行构建多个 skill且自动处理依赖顺序代码质量门禁nx affected:test只运行受影响 skill 的单元测试配合 Jest ts-jest覆盖率报告直接集成到 CI 流水线。更重要的是Nx 对 TypeScript 的原生支持深度远超其他工具。它内置的nrwl/node:library和nrwl/web:libraryschematics生成的模板默认启用composite: true的 tsconfig.json确保每个 skill 的类型定义能被其他包正确引用它内置的nrwl/js:tscexecutor能正确处理paths别名映射避免tsc --build时路径解析失败。我们曾用 pnpm tsc 手动搭建结果myorg/agent-skills-form-validator里的zod类型在myorg/agent-skills-ui中无法正确推导折腾两天才发现是tsconfig.json的rootDir和outDir配置冲突——Nx 的模板直接规避了这类坑。2.3 semantic-release让版本号不再是个“玄学”“版本号怎么打”是每个共享库团队最头疼的问题。手动画版本号必然不一致。约定 commit message必然有人忘记。npm version patch漏掉 changelog 更新。semantic-release 的价值不是“自动化”而是“强制契约”——它把“什么变更对应什么版本号”这个主观决策变成一条不可绕过的机器规则。它的核心机制是CI 流水线拉取最新 commit解析 commit message如feat(http-client): add retry logic→ minorfix(form-validator): fix empty string handling→ patchBREAKING CHANGE: remove legacy auth header→ major然后根据规则计算新版本号自动生成 changelog.md自动 git tag自动 npm publish。整个过程无人工干预也就杜绝了“我以为这是 patch其实它是 breaking”的事故。我们上线 semantic-release 后agent-skills的发布流程从“每周五下午 3 点张三手动打包、写 changelog、发 npm、通知群”变成了“任何人在任何时间 push 一个符合规范的 commit10 分钟后新版本就出现在 npm registry”。更关键的是它倒逼团队建立了 commit 规范文化新人 PR 被 CI 拒绝提示 “Invalid commit message: update http client — expected format feat(http-client): ...”比任何文档都管用。现在我们的 changelog.md 不再是应付检查的摆设而是真实反映每个 skill 演进的“产品日志”前端同学查问题时第一反应是翻 changelog 看“这个 bug 是在哪个版本引入的”。2.4 TypeScript不是锦上添花而是安全底线很多人觉得 TypeScript 在工具库中“可有可无”毕竟工具函数很简单。但恰恰相反TypeScript 是 agent-skills 的生命线。举个真实例子myorg/agent-skills-date提供formatDate(date: Date | string, pattern: string)。如果用 JS下游传入null函数内部date.toISOString()直接报TypeError如果用 TS签名强制要求Date | string但null不满足联合类型编译期就报错。再比如myorg/agent-skills-permission的hasPermission(role: Role, action: Action)TS 的 enum 类型能让 IDE 自动提示所有合法Action值避免拼写错误。更深层的价值在于“类型即文档”。一个 skill 的.d.ts文件就是它最精炼、最权威的 API 文档。npm install myorg/agent-skills-http-client后VS Code 直接显示createClient(config: HttpClientConfig): AxiosInstance参数HttpClientConfig的每个字段都有类型注释和可选标记。这比写 10 页 Markdown 文档更高效且永远与代码同步。我们在做技术中台时下游业务方反馈“看不懂怎么用 permission skill”我们只给了他们index.d.ts文件他们 5 分钟就搞定了集成——因为类型定义里已经写了// example const canEdit hasPermission(admin, EDIT_POST);。提示不要用any或// ts-ignore。agent-skills 的每个函数都必须有完整类型签名。遇到复杂泛型如pickT, K extends keyof T(obj: T, keys: K[]): PickT, K宁可花 2 小时查手册也不要妥协。类型安全不是负担是未来节省 20 小时 debug 时间的投资。3. 核心细节解析从初始化到发布每一步的实操陷阱与避坑指南3.1 初始化Nx Workspace 的最小可行配置别一上来就npx create-nx-workspacelatest然后选“empty”那是给新手的甜蜜陷阱。agent-skills 的本质是“发布到 npm 的独立包集合”所以 workspace 必须以npm为包管理器并启用buildable和publishable支持。正确姿势是npx create-nx-workspacelatest my-agent-skills \ --presetapps-and-libs \ --package-managernpm \ --interactivefalse \ --nx-cloudfalse进入目录后立即删除默认生成的 apps/目录rm -rf apps因为 agent-skills 不需要运行时应用只需要 libs。然后创建第一个 skillnx g nrwl/node:library agent-skills-http-client \ --directorylibs/agent-skills \ --buildabletrue \ --publishabletrue \ --importPathmyorg/agent-skills-http-client \ --unitTestRunnerjest \ --compilerswc关键参数解读--buildabletrue告诉 Nx 这个 lib 需要被构建生成 dist 目录--publishabletrue告诉 Nx 这个 lib 需要被发布生成 package.json 的main/types字段--importPathmyorg/agent-skills-http-client设置 npm 包名必须与name字段一致--compilerswcSWC 比 TSC 快 10 倍尤其对大量小文件的 libs构建时间从 12s 降到 1.3s。此时libs/agent-skills/http-client目录下会生成src/index.ts入口文件导出所有 public APIsrc/lib/http-client.ts主逻辑jest.config.tsJest 配置已预设moduleNameMapper处理myorg/*别名project.jsonNx 任务配置包含build、test、lint等 target。注意project.json中的targets.build.options.outputPath默认是dist/libs/agent-skills/http-client但package.json的main字段指向./src/index.ts——这是个坑必须手动修改project.jsontargets: { build: { options: { outputPath: dist/libs/agent-skills/http-client, main: src/index.ts, tsConfig: libs/agent-skills/http-client/tsconfig.lib.json, assets: [libs/agent-skills/http-client/*.md] } } }否则nx build agent-skills-http-client生成的dist目录里没有index.jsnpm publish 会失败。3.2 TypeScript 配置让类型定义真正“可消费”默认生成的tsconfig.lib.json有个致命问题declaration: true开启了.d.ts生成但declarationMap: false导致类型映射丢失下游项目无法跳转到定义。必须手动开启{ extends: ./tsconfig.json, compilerOptions: { outDir: ../../dist/out-tsc, declaration: true, declarationMap: true, // 关键否则 VS Code 无法 F12 跳转 types: [node], lib: [es2017, dom] }, include: [src/**/*.ts], exclude: [src/**/*.spec.ts] }另一个坑是paths别名。Nx 默认在根tsconfig.base.json里配置了myorg/*: [libs/*]但agent-skills-http-client的tsconfig.lib.json继承自它所以import { createClient } from myorg/agent-skills-http-client在 workspace 内部能解析但发布到 npm 后下游项目node_modules/myorg/agent-skills-http-client里没有myorg/*别名。解决方案是所有 skill 的package.json必须显式声明exports字段{ name: myorg/agent-skills-http-client, version: 0.0.1, main: ./dist/index.js, types: ./dist/index.d.ts, exports: { .: { import: ./dist/index.js, require: ./dist/index.js, types: ./dist/index.d.ts } } }这样下游项目无论用 ESM 还是 CJS都能正确解析。我们曾因漏配exports导致 Vue 3 项目import报错Cannot find module ./dist/index.js排查了 3 小时才发现是 Node.js 的 exports 解析规则变了。3.3 semantic-release 配置绕过 npm registry 的“中国结”国内开发者最常卡在 semantic-release 的npm publish步骤。错误信息通常是401 Unauthorized或404 Not Found。这不是权限问题而是npm registry 的镜像源配置冲突。semantic-release 默认用https://registry.npmjs.org/但你的.npmrc里可能是registryhttps://registry.npmmirror.com/淘宝镜像。解决方案是在 CI 环境中显式指定 registry// .releaserc.json { plugins: [ semantic-release/commit-analyzer, semantic-release/release-notes-generator, [ semantic-release/npm, { npmPublish: true, pkgRoot: dist/libs/agent-skills/http-client, registryUrl: https://registry.npmjs.org/ // 强制走官方源 } ], semantic-release/github ] }同时CI 脚本里必须设置 npm token# .github/workflows/release.yml - name: Publish to npm run: npx semantic-release env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} NPM_TOKEN: ${{ secrets.NPM_TOKEN }} # 在 GitHub Secrets 里存 npm token注意NPM_TOKEN 必须是 Classic Token且权限为Publish packages。Token 创建路径npmjs.com → Account Settings → Tokens → Generate New Token → SelectAutomation→ Copy。不要用Read and Publish它不兼容 semantic-release。3.4 Nx 任务编排让 CI 流水线真正“懂”依赖一个常见误区是以为nx build就够了。实际上agent-skills 的 CI 必须分层验证语法 类型检查nx run-many --targetlint --allESLint TypeScript单元测试nx affected:test --baseorigin/main --headHEAD只跑受影响的 skill构建验证nx affected:build --baseorigin/main --headHEAD发布准备nx affected:release --baseorigin/main --headHEAD调用 semantic-release其中affected是核心。它依赖 Nx 的nx graph生成的依赖图。但依赖图不是静态的——如果你在http-client里import { validate } from myorg/agent-skills-form-validatorNx 就会自动建立http-client → form-validator的边。所以所有 skill 之间的 import 必须用绝对路径myorg/xxx不能用相对路径../../form-validator。后者会让 Nx 无法识别依赖导致affected:test漏跑测试。我们曾因一个import { deepClone } from ../../../utils/deep-clone的相对导入导致form-validator的修改没触发http-client的测试上线后http-client的post方法因deepClone返回undefined而崩溃。教训是在tsconfig.base.json的compilerOptions.paths里只配置myorg/*禁止任何../或./的相对导入。4. 实操全流程从零开始搭建一个可发布的 agent-skills 库4.1 第一步创建 workspace 并初始化基础结构打开终端执行# 创建 workspace禁用 nx cloud避免上传代码到第三方 npx create-nx-workspacelatest agent-skills-demo \ --presetapps-and-libs \ --package-managernpm \ --interactivefalse \ --nx-cloudfalse cd agent-skills-demo # 删除无用的 apps 目录 rm -rf apps # 创建根目录的 .gitignore排除 node_modules 和 dist echo node_modules/ .gitignore echo dist/ .gitignore echo coverage/ .gitignore此时目录结构是干净的agent-skills-demo/ ├── libs/ ├── tools/ ├── nx.json ├── package.json ├── tsconfig.base.json └── ...4.2 第二步生成第一个 skill ——agent-skills-string这个 skill 提供字符串工具函数作为最简单的起点nx g nrwl/node:library agent-skills-string \ --directorylibs/agent-skills \ --buildabletrue \ --publishabletrue \ --importPathmyorg/agent-skills-string \ --unitTestRunnerjest \ --compilerswc修改libs/agent-skills/string/src/lib/string.ts/** * 安全截断字符串避免中文乱码 * param str 输入字符串 * param maxLength 最大长度字符数 * param suffix 截断后追加的后缀默认 ... * returns 截断后的字符串 */ export function truncate(str: string, maxLength: number, suffix: string ...): string { if (str.length maxLength) return str; // 使用 slice 而非 substring避免 UTF-16 代理对问题 const truncated str.slice(0, maxLength - suffix.length); // 检查是否在代理对中间截断 const lastChar truncated.charCodeAt(truncated.length - 1); if (lastChar 0xd800 lastChar 0xdfff) { return truncated.slice(0, -1) suffix; } return truncated suffix; } /** * 检查字符串是否为空null, undefined, , * param str 待检查字符串 * returns 是否为空 */ export function isEmpty(str: string | null | undefined): boolean { return str null || str.toString().trim() ; }更新libs/agent-skills/string/src/index.tsexport * from ./lib/string;4.3 第三步编写测试并验证本地构建libs/agent-skills/string/src/lib/string.spec.tsimport { truncate, isEmpty } from ./string; describe(string utils, () { it(should truncate correctly, () { expect(truncate(Hello World, 5)).toBe(He...); expect(truncate(你好世界, 4)).toBe(你好...); expect(truncate(a\uD83D\uDE00b, 3)).toBe(a...); // emoji 占 2 个 code unit }); it(should detect empty string, () { expect(isEmpty(null)).toBe(true); expect(isEmpty(undefined)).toBe(true); expect(isEmpty()).toBe(true); expect(isEmpty( )).toBe(true); expect(isEmpty(hello)).toBe(false); }); });运行测试nx test agent-skills-string # PASS libs/agent-skills/string/src/lib/string.spec.ts构建nx build agent-skills-string # 输出到 dist/libs/agent-skills/string/验证类型定义ls dist/libs/agent-skills/string/ # index.js index.d.ts index.d.ts.map package.json README.md4.4 第四步配置 semantic-release 并触发首次发布安装依赖npm install --save-dev semantic-release semantic-release/npm semantic-release/github conventional-changelog-conventionalcommits创建.releaserc.json{ branches: [main], plugins: [ semantic-release/commit-analyzer, semantic-release/release-notes-generator, [ semantic-release/npm, { npmPublish: true, pkgRoot: dist/libs/agent-skills/string } ], semantic-release/github ] }在package.json中添加 scriptscripts: { release: semantic-release }提交代码注意 commit message 格式git add . git commit -m feat(agent-skills-string): add truncate and isEmpty functions git push origin main此时GitHub Actions 会触发.github/workflows/release.ymlNx CLI 自动生成执行npx semantic-release。它会解析 commit识别feat→ minor version计算新版本从0.0.0升到0.1.0生成CHANGELOG.md创建 git tagv0.1.0发布到 npm registry。实测心得首次发布前务必在 npmjs.com 上创建账号并验证邮箱。发布后访问https://www.npmjs.com/package/myorg/agent-skills-string确认页面显示v0.1.0和正确的 README。4.5 第五步添加第二个 skill 并建立依赖生成agent-skills-numbernx g nrwl/node:library agent-skills-number \ --directorylibs/agent-skills \ --buildabletrue \ --publishabletrue \ --importPathmyorg/agent-skills-number \ --unitTestRunnerjest \ --compilerswc在agent-skills-number中我们想复用string.isEmpty于是// libs/agent-skills/number/src/lib/number.ts import { isEmpty } from myorg/agent-skills-string; // 绝对路径 export function isPositive(num: number): boolean { return num 0 !isEmpty(num.toString()); }此时Nx 会自动检测到agent-skills-number → agent-skills-string的依赖。运行nx dep-graph # 在浏览器打开看到两个节点间的连线修改agent-skills-string的truncate函数加个 bug// 错误示例返回 undefined 而非字符串 export function truncate(str: string, maxLength: number, suffix: string ...): string { if (str.length maxLength) return str; return undefined as any; // 强制类型错误 }然后运行nx affected:test --baseorigin/main --headHEAD # FAIL: agent-skills-string 的测试失败agent-skills-number 的测试也失败因为依赖了它这证明依赖链生效。修复 bug 后nx affected:test只运行这两个包的测试节省 80% 时间。5. 常见问题与排查技巧实录那些让你加班到凌晨的“幽灵 Bug”5.1 问题速查表现象可能原因排查命令解决方案nx build xxx报错Cannot find module myorg/yyyworkspace 内部 import 路径错误nx graph查看依赖图确保所有 import 用myorg/xxx禁用../npm install myorg/xxx后import报Module not foundpackage.json的exports字段缺失或错误cat node_modules/myorg/xxx/package.json | jq .exports添加exports字段指向dist/index.jsnx affected:test没运行任何测试Git 基础分支设置错误git merge-base origin/main HEAD确保 CI 中--baseorigin/main本地用--basemainsemantic-release报No commits foundcommit message 不符合 conventional commitsgit log --oneline -n 5用nx generate nrwl/workspace:commit或安装 Commitizentsc编译成功但nx build失败tsconfig.lib.json的outDir与 Nx 配置冲突cat libs/xxx/tsconfig.lib.json | grep outDiroutDir必须是../../dist/out-tsc且project.json的outputPath匹配5.2 独家避坑技巧来自 37 次发布失败的血泪总结技巧 1用nx migrate升级前先备份package-lock.jsonNx 的nx migrate会重写package-lock.json但有时会错误地降级某些依赖如把nrwl/node从 17.x 降到 16.x。我们曾因此导致nrwl/node:libraryschematics 生成的project.json缺失buildable字段。解决方案升级前cp package-lock.json package-lock.json.bak升级失败立即cp package-lock.json.bak package-lock.json npm install。技巧 2semantic-release的--dry-run是你的救命稻草在正式发布前永远先本地测试npx semantic-release --dry-run --debug它会模拟整个流程输出将要发布的版本号、changelog 内容、npm publish 命令但不真正执行。我们靠它发现了 80% 的配置错误比如pkgRoot指向了错误的 dist 目录。技巧 3为每个 skill 单独配置 ESLint 规则默认的 Nx ESLint 配置太宽松。在libs/agent-skills/string/.eslintrc.json中添加{ extends: [plugin:typescript-eslint/recommended], rules: { typescript-eslint/no-explicit-any: error, // 禁止 any typescript-eslint/explicit-function-return-type: error, // 强制返回类型 typescript-eslint/no-unused-vars: [error, { argsIgnorePattern: ^_ }] // 允许 _unused } }这样truncate函数如果没有写返回类型: stringESLint 就会报错从源头杜绝类型漏洞。技巧 4用nx report快速诊断环境问题当 CI 报错Cannot find module ts-node时别急着重装依赖。先运行nx report它会输出 Nx 版本、Node.js 版本、npm 版本、所有插件版本、以及nx.json的摘要。我们曾发现 CI 用的是 Node.js 16而本地是 Node.js 18导致 SWC 编译器不兼容——nx report一行就定位了。技巧 5dist目录的权限问题在 Linux CI 环境中nx build生成的dist目录有时是 root 权限导致后续npm publish无权读取。解决方案是在project.json的buildtarget 中添加chmodoptions: { outputPath: dist/libs/agent-skills/string, main: src/index.ts, tsConfig: libs/agent-skills/string/tsconfig.lib.json, assets: [libs/agent-skills/string/*.md], postBuild: chmod -R 755 dist/libs/agent-skills/string // 关键 }5.3 那些“看起来像 bug”的设计选择为什么不用 pnpmpnpm 的硬链接机制在 CI 中有时会因权限问题失败。我们试过pnpm install在 GitHub Actions Ubuntu runner 上随机失败错误是EPERM: operation not permitted, symlink。Nx 官方推荐 npm且nx build的缓存机制在 npm 下更稳定。为什么不用 TurbopackTurbopack 目前2024对 Node.js 库构建支持不完善特别是--publishable的 lib 构建会生成错误的package.json。我们实测nx build --buildernrwl/webpack:webpack生成的dist目录main字段指向index.js而 Turbopack 生成的指向index.mjs导致 CJS 项目无法 require。为什么agent-skills不提供 React Hook因为 agent-skills 的定位是“框架无关的能力单元”。React Hook 依赖react和react-dom会污染纯 Node.js 环境的使用场景如 CLI 工具、服务端渲染。如果需要 Hook应该在myorg/agent-skills-react这样的独立包里实现它依赖myorg/agent-skills-string但不反向依赖。我在实际操作中发现最耗时的环节从来不是写代码而是让工具链“听话”。Nx 的affected逻辑、semantic-release 的 commit 解析、TypeScript 的 declaration map任何一个环节配置偏差都会导致构建失败或类型丢失。但一旦跑通那种“改一行代码10 分钟后全球开发者就能用上新功能”的确定性是任何框架都无法替代的工程快感。这个过程没有捷径只有反复阅读 Nx 官方文档的affected章节、semantic-release 的npm插件文档、TypeScript 的declaration选项说明然后亲手试错。现在我的agent-skills仓库里dist目录的每次更新都意味着又一个微小但可靠的契约被交付出去——它不性感但足够坚实。