企业官网建设流程全解析

1. 项目概述：Agent-Skills 不是“AI代理技能包”，而是前端工程化能力的精密组装系统

“agent-skills”这个名称在当前技术社区里极易引发第一反应——“这是不是某个大模型Agent的工具函数库？”但实际接触过Nx工作区、TypeScript深度类型系统和语义化发布流程的人，一眼就能看出：这根本不是AI应用层的玩具项目，而是一个典型的、面向中大型前端/全栈团队的工程能力抽象层。它不处理LLM调用、不封装prompt模板、不管理记忆机制；它的核心使命，是把散落在多个Nx应用与库中的、重复率极高、耦合度极深的底层能力——比如HTTP客户端统一拦截、错误分类映射、认证令牌自动刷新、离线队列重试、本地存储加密封装、日志上下文透传、国际化键值自动补全——从具体业务逻辑里“抽离”出来，变成可版本化、可组合、可类型安全消费的独立技能模块。

我带过的三个中台项目都经历过类似阶段：初期每个微前端应用自己写一套fetch封装，三个月后发现七个项目有八种错误处理逻辑；半年后接入SSO，又各自实现一遍token刷新，结果一个应用因刷新失败导致整个会话中断。直到我们把这类能力统一收口到类似@myorg/agent-skills的Nx库中，才真正实现“一次定义、处处生效”。这里的“agent”不是AI agent，而是指代每一个前端运行时环境所扮演的服务代理角色——它代理用户发起请求，代理服务返回响应，代理网络异常做兜底，代理用户行为做埋点。而“skills”就是这个代理角色必须掌握的生存技能清单。

关键词“Node.js”“TypeScript”“Nx”“semantic-release”已经勾勒出完整技术轮廓：这是一个基于Node.js生态构建、用TypeScript强类型保障、依托Nx单体仓库（monorepo）组织、通过semantic-release实现全自动版本发布的工程能力库。它不直接面向终端用户，但所有使用它的前端应用，都会因此获得更稳定、更一致、更易调试的底层行为。适合正在从单体SPA向微前端或模块联邦演进的团队，也适合需要长期维护多个内部SDK的平台型部门。如果你还在手动复制粘贴apiClient.ts文件，或者每次发版都要人工改package.json里的版本号，那这个项目的设计思路，就是你当下最该拆解的样本。

2. 整体架构设计：为什么必须用Nx而不是Lerna？TypeScript类型如何成为第一道防线？

2.1 Nx单体仓库：不是为了炫技，而是解决“依赖地狱”的物理方案

很多人看到Nx第一反应是“重”，觉得小项目用不上。但当你面对的是十几个共享库、五个以上应用、每日数十次跨库提交时，“重”恰恰是稳定性必需的代价。agent-skills之所以选择Nx而非Lerna或pnpm workspaces，核心在于三点不可替代性：

第一，增量构建与影响分析。Nx能静态分析TypeScript import路径，精确计算出修改http/skill.ts后，哪些应用和测试真正需要重新构建。我们曾在线上环境遇到过一个bug：某次更新@myorg/agent-skills的错误码映射逻辑，导致三个应用的登录态校验异常。用Nx执行nx affected:build --base=main --head=HEAD，5秒内就定位出仅auth-app和dashboard-app受影响，跳过其余8个应用的构建，发布窗口从47分钟压缩到9分钟。而Lerna的--since只能按git commit时间粗筛，无法识别类型定义变更带来的隐式依赖。

第二，任务缓存与远程缓存共享。Nx默认启用本地缓存，同一台机器上重复构建相同输入的库，耗时从12秒降至0.3秒。更关键的是，团队配置了CI服务器作为远程缓存节点。当开发者A在Mac上构建完agent-skills，开发者B在Windows上执行相同命令，Nx会直接从远程缓存拉取已编译的dist目录和类型声明文件，连tsc都不启动。我们统计过，CI流水线中build任务平均节省63%时间，尤其对agent-skills这种高频迭代的底层库，效果立竿见影。

第三，代码生成与约束强制。Nx的generator机制让“添加新技能”变成标准化动作。执行nx g @myorg/agent-skills:skill --name=offline-queue，自动生成libs/agent-skills/src/lib/offline-queue/index.ts、配套的单元测试骨架、类型定义文件，甚至自动在libs/agent-skills/src/index.ts中导出。更重要的是，generator内置了校验逻辑：检查新技能是否实现了SkillInterface，是否包含init()和destroy()生命周期方法，是否在peerDependencies中声明了所需第三方库版本。这种约束不是靠Code Review提醒，而是写进脚手架的硬性规则。

提示：Nx的project.json中targets.build.options.assets字段常被忽略。agent-skills库需将README.md和CHANGELOG.md打包进npm包，否则下游用户安装后看不到文档。我们曾因漏配此字段，导致新同事花了两小时排查“为什么npm install @myorg/agent-skills后node_modules/@myorg/agent-skills/README.md不存在”。

2.2 TypeScript类型系统：从“能跑就行”到“编译即测试”的跃迁

agent-skills的TypeScript实践，早已超越基础类型标注，进入类型即契约阶段。以最核心的HttpSkill为例，其接口定义不是简单的interface HttpSkill { request(): Promise<any> }，而是：

export interface HttpSkill { /** * 发起HTTP请求，自动注入认证头、处理401重定向、支持离线队列 * @param config 请求配置，支持AbortSignal取消 * @param options 扩展选项，如是否启用离线缓存、是否记录审计日志 * @returns Promise<HttpResponse<T>>，T由responseType严格推导 */ request<T>( config: HttpRequestConfig, options?: HttpSkillOptions ): Promise<HttpResponse<T>>; /** * 预加载技能依赖，如初始化Axios实例、建立WebSocket连接 * 必须在request前调用，否则抛出TypeError */ init(): Promise<void>; /** * 清理资源，如取消未完成请求、关闭WebSocket * 调用后request将抛出SkillNotInitializedError */ destroy(): void; }

这段定义背后是三层防御：

• 第一层：编译期契约。任何实现类若未提供init()方法，TypeScript编译直接报错Property 'init' is missing in type '...'。这比运行时throw new Error('init not called')早拦截了90%的集成错误。

• 第二层：泛型推导保障。request<T>的返回值HttpResponse<T>中，data字段类型严格等于T。当业务代码调用httpSkill.request<User>('/api/user')，后续.then(res => res.data.name)中res.data.name的类型是string而非any，IDE能实时提示属性是否存在。我们曾用此特性捕获一个严重bug：后端将user.avatar_url字段从字符串改为对象，前端调用方因未更新泛型参数<User>，编译器立刻标红res.data.avatar_url.split——因为avatar_url现在是{ url: string, size: number }类型。

• 第三层：JSDoc驱动文档生成。@param和@returns标签被TypeDoc自动提取为API文档，配合Nx的nx doc命令，一键生成交互式文档站点。更重要的是，VS Code悬停提示直接显示这些描述，新成员无需翻阅Wiki，光看IDE就能理解技能用途。

注意：TypeScript的--strict编译选项必须开启，尤其--noImplicitAny和--strictNullChecks。我们曾因关闭--strictNullChecks，导致HttpResponse<T>的error字段被误判为any，掩盖了后端返回{ error: null }时的空指针风险。开启后，编译器强制要求if (response.error !== null)，杜绝此类隐患。

3. 核心技能模块解析：HTTP、离线、日志三大支柱的实现细节

3.1 HTTP技能：不只是封装fetch，而是构建请求生命周期的控制平面

agent-skills中的HTTP模块，本质是一个请求生命周期控制器。它不替代Axios或fetch，而是站在它们之上，统一管理从请求发出到响应处理的全链路。其核心设计思想是：将网络请求视为状态机，每个环节可插拔、可监控、可降级。

实现上分为四层：

• 协议适配层（Protocol Adapter）：提供FetchAdapter和AxiosAdapter两个实现，均实现统一的HttpAdapter接口。业务代码通过new HttpSkill({ adapter: new FetchAdapter() })注入，切换底层协议零成本。我们选择同时支持两者，是因为部分老项目强依赖Axios的拦截器生态，而新项目倾向原生fetch的轻量。

• 中间件管道（Middleware Pipeline）：请求经过beforeRequest→onRequest→onResponse→afterResponse四个钩子。每个钩子接收Context对象，包含config、response、error等只读属性。例如AuthMiddleware在beforeRequest中注入Authorization头，RetryMiddleware在onResponse中判断response.status === 503则触发重试。

• 策略引擎（Strategy Engine）：针对不同场景预置策略组合。DefaultStrategy启用认证、超时、JSON解析；PublicStrategy禁用认证头；OfflineFirstStrategy启用离线队列+本地缓存。业务方只需httpSkill.useStrategy('OfflineFirstStrategy')，无需关心内部实现。

• 可观测性注入（Observability Injection）：每个请求自动注入唯一traceId，并记录startTime、endTime、retryCount。通过httpSkill.on('request:start', (ctx) => console.log(ctx.traceId))订阅事件，与公司APM系统打通。

实操中一个关键细节是错误分类映射。后端返回的HTTP状态码（如400、401、429）和业务错误码（如ERR_USER_LOCKED、ERR_INSUFFICIENT_BALANCE）混杂，前端需统一处理。agent-skills定义了HttpErrorMap类型：

export type HttpErrorMap = { [K in keyof typeof HttpStatus]: { code?: string; // 业务错误码前缀 message?: string; // 用户友好提示 action?: 'redirect' | 'retry' | 'ignore'; // 建议操作 }; }; // 实际映射配置 const ERROR_MAP: HttpErrorMap = { 401: { code: 'AUTH_', message: '登录已过期，请重新登录', action: 'redirect' }, 429: { code: 'RATE_LIMIT_', message: '操作太频繁，请稍后再试', action: 'retry' }, 500: { code: 'SERVER_', message: '服务暂时不可用', action: 'ignore' }, };

HttpSkill在onResponse钩子中，根据response.status查表，将原始错误包装为AgentHttpError实例，携带code、message、action属性。业务代码只需if (err.action === 'redirect') { navigate('/login') }，彻底解耦错误处理逻辑。

实操心得：HTTP技能的timeout参数不能设为全局常量。我们最初统一设为10秒，结果发现上传大文件接口需30秒，而健康检查接口2秒足够。后来改为按config.url正则匹配动态设置：/\/api\/upload/.test(config.url) ? 30000 : 10000。这个配置被抽成TimeoutStrategy类，方便后续扩展。

3.2 离线技能：不是简单localStorage，而是具备队列、重试、冲突解决的本地代理

离线技能（OfflineSkill）的目标很明确：当网络断开时，用户操作不中断，数据不丢失，网络恢复后自动同步。它不是localStorage.setItem的封装，而是一个微型的、内存+持久化混合的本地数据库代理。

其核心组件包括：

• 操作队列（Operation Queue）：所有写操作（POST/PUT/DELETE）被序列化为Operation对象，存入IndexedDB。每个Operation包含id（UUID）、type（'create' | 'update' | 'delete'）、entity（实体数据）、timestamp、retries（重试次数）。队列按timestamp升序排列，保证操作顺序。

• 同步引擎（Sync Engine）：网络恢复时，引擎遍历队列，逐个重放操作。关键在于幂等性保障：每个Operation携带idempotencyKey（由entity.id + timestamp + operationType哈希生成），后端接口必须校验此key，重复请求直接返回成功。我们与后端约定，所有写接口增加X-Idempotency-Key头，否则拒绝处理。

• 冲突解决器（Conflict Resolver）：当本地修改与服务端最新数据冲突时（如用户A修改订单状态为“已发货”，用户B同时修改为“已取消”），触发resolveConflict钩子。默认策略是“最后写入获胜”，但可被覆盖。例如财务模块要求人工确认，OfflineSkill会将冲突项存入conflictStore，并通过offlineSkill.on('conflict', handler)通知UI弹出选择框。

一个典型场景是“草稿箱”功能。用户在地铁里编辑文章，网络中断，OfflineSkill自动将saveDraft操作入队。到达办公室后，网络恢复，引擎检测到队列非空，立即发起同步。此时若后端返回409 Conflict（服务端版本号高于本地），OfflineSkill会拉取服务端最新版本，合并本地修改（如保留用户新增的段落），再提交最终版本。

注意：IndexedDB的put()操作是异步的，但OfflineSkill的enqueue()方法必须同步返回Promise<Operation>，以便业务代码链式调用。我们采用“双缓冲”策略：先将操作写入内存队列（同步），再由后台任务异步刷入IndexedDB。内存队列满时（如100条），才触发批量写入，避免频繁IO阻塞主线程。

3.3 日志技能：从console.log到结构化、可追溯、可采样的全链路追踪

agent-skills的日志模块（LogSkill）彻底抛弃console.log，转向结构化日志（Structured Logging）。每条日志都是JSON对象，固定包含timestamp、level、service、traceId、spanId、message，以及业务自定义字段。

其核心价值在于上下文透传。当用户触发一个复杂操作（如“提交订单”），该操作涉及HTTP请求、本地存储读写、第三方SDK调用。LogSkill通过LogContext类维护一个嵌套上下文栈：

// 初始化根上下文 logSkill.startContext({ traceId: generateTraceId(), service: 'checkout-app', orderId: 'ORD-2024-XXXX' }); // 进入支付子流程 logSkill.enterContext({ spanId: 'payment-step-1', step: 'initiate-payment' }); logSkill.info('Payment initiated', { amount: 99.99 }); // 进入风控子流程 logSkill.enterContext({ spanId: 'risk-check-1', step: 'fraud-detection' }); logSkill.debug('Risk score calculated', { score: 0.82 }); logSkill.exitContext(); // 退出风控上下文 logSkill.exitContext(); // 退出支付上下文

最终生成的日志流中，每条记录都携带完整的traceId和当前spanId，配合公司ELK栈，可在Kibana中一键追踪整个订单流程的所有日志，无需grep拼接。

另一个关键设计是采样率控制。生产环境全量日志成本过高，LogSkill支持按level和service动态配置采样率。例如error级别100%采集，info级别对checkout-app采样1%，对health-check服务采样100%。配置通过logSkill.setSamplingRate('info', 'checkout-app', 0.01)运行时调整，无需重启。

实操心得：日志的traceId必须与HTTP请求头X-Trace-ID保持一致。我们在HttpSkill的beforeRequest钩子中，自动从LogContext.current().traceId读取并注入请求头；在onResponse钩子中，从响应头X-Trace-ID读取并同步到日志上下文。这样前后端日志就能通过同一个traceId关联，真正实现全链路追踪。

4. 工程化落地：Semantic-Release如何实现“提交即发布”，Nx如何管理多版本兼容

4.1 Semantic-Release：从“人肉发版”到“提交信息即版本说明书”

agent-skills的发布流程，是semantic-release教科书级应用。它彻底废除了npm version patch && git push && npm publish的手动三步曲，代之以“提交符合规范的commit message，CI自动完成版本号计算、changelog生成、git tag、npm publish”。

其核心在于commit message的结构化约定。我们采用Angular规范，但做了团队定制：

feat(http): add support for automatic token refresh on 401 ^ ^ ^ | | | | | +-> 精确到子模块（http, offline, log） | +-> 类型：feat(新功能), fix(修复), docs(文档), chore(维护) +-> 作用域：括号内限定影响范围，避免模糊的"core"

semantic-release配置release.config.js中关键参数：

module.exports = { branches: ['main', { name: 'beta', prerelease: true }], plugins: [ '@semantic-release/commit-analyzer', // 分析commit类型 '@semantic-release/release-notes-generator', // 生成changelog '@semantic-release/npm', // 发布到npm '@semantic-release/github', // 创建GitHub Release [ '@semantic-release/exec', { // 发布后自动更新Nx workspace.json中的依赖版本 prepareCmd: 'nx run agent-skills:version-bump --version=${nextRelease.version}', } ] ] };

最关键的prepareCmd脚本，解决了Nx monorepo中跨库版本同步难题。当agent-skills发布v2.3.0，该脚本会自动扫描workspace.json，找到所有依赖@myorg/agent-skills的项目（如auth-app,dashboard-lib），将其package.json中的dependencies字段更新为^2.3.0，并提交PR。开发者只需审核合并，无需手动改版本号。

注意：semantic-release的verifyConditions插件必须校验Git用户邮箱。我们曾因CI服务器Git配置邮箱为root@localhost，导致@semantic-release/github插件拒绝创建Release，错误信息极其隐蔽。解决方案是在CI脚本中显式设置：git config --global user.email "ci@myorg.com" && git config --global user.name "CI Bot"。

4.2 Nx多版本兼容：如何让v1.x和v2.x共存于同一工作区

agent-skills的v2版本引入了破坏性变更（如HTTP Skill的request方法签名从request(url, config)改为request<T>(config, options)），但部分老应用无法立即升级。Nx提供了优雅的多版本共存方案。

第一步，在libs/agent-skills目录下创建v1和v2两个子目录，分别对应不同主版本：

libs/ agent-skills/ v1/ # v1.x源码，构建输出dist/v1/ v2/ # v2.x源码，构建输出dist/v2/ package.json # 主入口，根据NODE_ENV决定导出哪个版本

第二步，package.json的exports字段配置条件导出：

{ "exports": { ".": { "types": "./dist/v2/index.d.ts", "import": "./dist/v2/index.js", "require": "./dist/v2/index.cjs" }, "./v1": { "types": "./dist/v1/index.d.ts", "import": "./dist/v1/index.js", "require": "./dist/v1/index.cjs" } } }

第三步，老应用在package.json中直接依赖"@myorg/agent-skills": "1.5.0"，新应用依赖"@myorg/agent-skills": "^2.0.0"。Nx构建时，会根据依赖版本自动解析到对应dist目录，互不干扰。

更进一步，我们利用Nx的project.json中targets.build.options.outputPath，为不同版本指定独立输出路径，并在CI中并行构建：

{ "targets": { "build:v1": { "executor": "@nrwl/js:tsc", "options": { "outputPath": "dist/libs/agent-skills/v1", "tsConfig": "libs/agent-skills/v1/tsconfig.lib.json" } }, "build:v2": { "executor": "@nrwl/js:tsc", "options": { "outputPath": "dist/libs/agent-skills/v2", "tsConfig": "libs/agent-skills/v2/tsconfig.lib.json" } } } }

这样，一个nx build agent-skills --configuration=v1命令，就精准构建v1版本，完全不影响v2的开发流程。

实操心得：多版本共存时，peerDependencies的版本范围必须谨慎。v1版本要求"rxjs": "^6.0.0"，v2版本要求"rxjs": "^7.0.0"，若在package.json中写"rxjs": ">=6.0.0"，会导致v1应用意外安装rxjs v7，引发兼容问题。正确做法是v1和v2的package.json各自声明精确的peerDependencies，并在nx.json中配置targetDefaults确保构建时校验。

5. 常见问题与实战排障：从“类型错误”到“发布失败”的真实战场复盘

5.1 类型错误：为什么HttpSkill的泛型推导在某些场景失效？

现象：业务代码httpSkill.request<User>('/api/user')，IDE提示User类型未定义，或res.data仍为any。

排查路径：

1. 检查User接口是否在libs/agent-skills/src/lib/types/index.ts中导出。agent-skills要求所有泛型类型必须在此统一导出，否则TS无法在库外解析。
2. 检查tsconfig.json的compilerOptions.types是否包含"node"和"jest"（若用Jest测试）。缺失"node"会导致Buffer等全局类型丢失，间接影响泛型推导。
3. 最常见原因：@myorg/agent-skills的package.json中types字段指向错误路径。正确应为"types": "./dist/libs/agent-skills/index.d.ts"，若误写为"types": "./src/index.ts"，TS会尝试编译源码而非使用已生成的声明文件，导致类型丢失。

解决方案：在libs/agent-skills/project.json中，targets.build.options确保declaration为true，且outDir指向dist目录。执行nx build agent-skills后，手动检查dist/libs/agent-skills/index.d.ts是否包含export interface User。

5.2 构建失败：Nx提示“Cannot find module ‘@myorg/agent-skills’”

现象：在应用项目中import { HttpSkill } from '@myorg/agent-skills'，nx build app-name报错Cannot find module。

根本原因：Nx的tsconfig.base.json中compilerOptions.paths未正确映射。agent-skills作为Nx库，其路径别名由Nx自动生成，但需确保tsconfig.json继承正确。

验证步骤：

1. 检查apps/app-name/tsconfig.json是否包含"extends": "../../tsconfig.base.json"。
2. 检查tsconfig.base.json的compilerOptions.paths是否包含"@myorg/agent-skills": ["libs/agent-skills/src/index.ts"]。
3. 若使用@nrwl/js构建器，需在project.json中targets.build.options添加"generatePackageJson": true，确保构建后生成正确的package.json供Node.js解析。

快速修复：执行nx reset清除Nx缓存，然后nx build agent-skills重新构建库，再nx build app-name。90%的此类问题源于缓存未更新。

5.3 发布失败：semantic-release卡在“Verify GitHub authentication”

现象：CI日志显示[8:30:22 AM] [semantic-release] › ✖ Failed step "verifyConditions" of plugin "@semantic-release/github"，错误信息为Authentication failed. Please check your GH_TOKEN。

真相：GH_TOKEN权限不足。@semantic-release/github需要repo权限（而非仅public_repo），才能创建Release和上传assets。

操作清单：

• 登录GitHub，进入Settings > Developer settings > Personal access tokens > Tokens (classic)。
• 编辑现有token，勾选repo权限组下的全部子项（repo:status,repo_deployment,public_repo,repo:invite,security_events）。
• 在CI环境变量中，将GH_TOKEN值更新为新token。
• 切记：不要在release.config.js中硬编码token，必须通过环境变量注入。

5.4 运行时错误：“HttpSkill is not initialized”

现象：应用启动后调用httpSkill.request()，控制台报错HttpSkill is not initialized。

根因分析：HttpSkill的init()方法未被调用，或调用时机错误。agent-skills要求init()必须在应用启动早期、路由挂载前执行。

标准初始化模式：

// apps/auth-app/src/main.ts import { HttpSkill } from '@myorg/agent-skills'; import { environment } from './environments/environment'; const httpSkill = new HttpSkill({ baseUrl: environment.apiUrl, timeout: 10000, }); // 必须在Angular AppModule.forRoot()之前调用 httpSkill.init().then(() => { platformBrowserDynamic() .bootstrapModule(AppModule) .catch(err => console.error(err)); }).catch(console.error);

若在Angular的APP_INITIALIZER中调用，因异步时机问题，可能导致部分服务在init()完成前就尝试使用httpSkill。必须确保init()的Promise resolve后，再启动应用。

排查技巧：在HttpSkill.init()方法开头添加console.time('HttpSkill init')，结尾添加console.timeEnd('HttpSkill init')。若控制台无此计时输出，说明init()根本未被调用；若计时长达数秒，检查environment.apiUrl是否配置错误导致DNS查询超时。

6. 性能与安全加固：如何让技能库既快又稳

6.1 构建性能优化：从3分钟到22秒的冷构建提速实战

agent-skills初始构建耗时3分12秒（Mac M1 Pro），主要瓶颈在TypeScript类型检查和ESBuild打包。我们通过三步优化压缩至22秒：

第一步：启用ESBuild的incremental模式。在project.json的targets.build.executor配置中，options添加"incremental": true。ESBuild会缓存AST，后续构建仅处理变更文件，提速40%。

第二步：分离类型检查。Nx默认build任务包含tsc类型检查。我们将type-check拆为独立任务：

{ "targets": { "type-check": { "executor": "@nrwl/js:tsc", "options": { "skipLibCheck": true, "noEmit": true, "incremental": true } } } }

CI中并行执行nx build agent-skills & nx type-check agent-skills，总耗时降低至28秒。

第三步：精简tsconfig.json。移除"include": ["**/*.ts"]，改为精确指定"include": ["src/**/*.ts", "src/lib/**/*.d.ts"]，避免扫描node_modules和dist目录。此步单独节省7秒。

注意：incremental模式依赖tsconfig.json中的"tsBuildInfoFile"路径。必须确保该路径（默认./tsconfig.tsbuildinfo）不在.gitignore中，否则CI每次都是冷构建。我们将其加入git add白名单。

6.2 安全加固：防范供应链攻击与敏感信息泄露

agent-skills作为基础库，安全红线极高。我们实施三项强制措施：

1. 依赖扫描自动化：在nx.json中配置targetDefaults，为所有构建任务添加"dependsOn": ["@myorg/agent-skills:audit"]。audit任务执行snyk test --severity-threshold=high，任何高危漏洞（如axios的prototype-pollution）导致构建失败。

2. 环境变量隔离：agent-skills绝不读取process.env。所有配置（如baseUrl、timeout）必须通过构造函数传入。避免CI环境变量泄露到生产包。

3. 构建产物净化：project.json的targets.build.options中，"assets"字段严格限定为["README.md", "LICENSE"]，禁止包含src/或e2e/目录。我们曾因误配"assets": ["src/**/*"]，导致src/e2e/test-data.json（含模拟用户密码）被打包进npm包，紧急发布v1.0.1热修复。

安全心得：semantic-release的@semantic-release/exec插件执行npm publish前，必须插入prepublishOnly脚本，运行npm ls --prod --depth=0检查是否有未声明的生产依赖。我们发现一个devDependency（@types/node）被误写入dependencies，虽不影响运行，但违反最小权限原则，立即修正。

7. 团队协作与知识沉淀：如何让“agent-skills”成为团队共同资产

7.1 技能贡献指南：新人如何安全地添加一个新技能？

agent-skills的开放性不等于随意性。我们制定《技能贡献五步法》，确保每个新技能符合架构规范：

1. 提案（Proposal）：在内部Confluence提交RFC文档，说明技能目标、API设计、依赖分析、测试策略。必须包含与其他技能的交互图（如OfflineSkill如何与HttpSkill协同）。

2. 原型（Prototype）：在libs/agent-skills/src/lib/experimental/下创建原型，命名如experimental-offline-queue-v2.ts。此目录不参与构建，仅供评审。

3. 评审（Review）：发起Nx PR，标题格式[SKILL] Add OfflineQueueV2 (RFC-123)。必须@至少两位核心维护者，且CI通过nx affected:test --target=test --base=main。

4. 文档（Docs）：合并前，更新libs/agent-skills/README.md的“可用技能”表格，补充新技能的name、description、usage示例、compatibility（支持的Node.js版本）。

5. 归档（Archive）：正式发布后，删除experimental/目录下原型文件，并在CHANGELOG.md中记录BREAKING CHANGES（如有）。

经验：我们曾接受一个“WebSocket技能”提案，评审时发现其reconnect策略与现有HttpSkill的重试逻辑冲突。最终决定不单独建技能，而是将WebSocket能力作为HttpSkill的transport选项之一，统一重试策略。这体现了“技能”是能力抽象，而非技术堆砌。

7.2 知识库建设：从“口头传授”到“可执行文档”

agent-skills的知识沉淀，不是Wiki页面，而是可执行的代码示例。我们在libs/agent-skills/src/examples/下维护真实场景代码：

• examples/http-auth-refresh/：完整演示401自动刷新流程，包含Mock Service Worker拦截、Token过期模拟、UI状态反馈。
• examples/offline-draft-sync/：模拟地铁断网场景，展示草稿保存、网络恢复、冲突解决全流程。
• examples/log-trace-propagation/：Angular应用中，从Component点击事件，经Service调用，到HTTP请求，全程traceId透传的端到端示例。

每个示例目录包含：

• app.component.ts：可直接在StackBlitz运行的最小应用。
• test.spec.ts：对应场景的端到端测试。
• README.md：一行命令启动示例的说明。

新成员入职第一天，任务就是运行这三个示例，修改其中一行代码并观察效果。这种“动手即学习”的方式，比阅读10页文档更高效。

最后分享一个小技巧：在Nx中，nx graph命令可生成可视化依赖图。执行nx graph --focus=agent-skills，会打开浏览器显示agent-skills与所有应用、库的依赖关系。我们将其截图嵌入Confluence首页，新成员一眼看清“这个库到底被谁用、影响谁”，消除认知盲区。