企业官网建设流程全解析

1. 项目概述：一个被严重低估的“智能体能力库”工程

“agent-skills”这个名字乍看平平无奇，像某个内部工具包的代号，但结合它在 GitHub 上的真实形态、TypeScript + Node 的技术栈选择，以及 Nx 构建系统和 semantic-release 的发布策略，它根本不是普通工具库——而是一个面向 AI 智能体（Agent）开发者的可组合、可测试、可发布、可复用的能力原子化平台。我第一次看到这个仓库时，正在帮一家做客服对话系统的团队重构他们的“技能路由层”，他们把 17 个 API 调用封装成函数，硬编码在 LLM 提示词里，每次加一个新能力就得改 prompt、重训微调、重新部署。而 agent-skills 给出的解法是：把每个能力写成一个独立、类型安全、带元数据描述的 TypeScript 函数，再通过统一注册机制注入到智能体运行时中。它解决的不是“怎么调 API”，而是“如何让智能体真正理解自己会什么、该什么时候用、用完怎么反馈”。

核心关键词里，“agent-skills”是灵魂，“TypeScript”是骨架，“Node”是运行基座，“semantic-release”是交付节奏，“Nx”是工程治理中枢——这五者缺一不可。比如，没有 TypeScript 的强类型约束，你就无法在编译期捕获“传给天气查询函数的 location 参数写成了 locaton”这类低级错误；没有 Nx 的任务依赖图和增量构建，当你要同时维护 30+ 个技能模块（如文件读取、数据库查询、邮件发送、日程创建、PDF 解析）时，单靠 npm scripts 会陷入“改一个技能，全量构建 8 分钟，CI 等得发慌”的泥潭；而 semantic-release 不是锦上添花，它是让每个技能模块能独立发版的关键——你不需要为修复一个“短信发送失败重试逻辑”的 bug，就去发布整个智能体框架。

它适合三类人：第一类是正在从规则引擎或简单 prompt 工程转向真正 Agent 架构的工程师，你需要一套可落地的“能力管理范式”；第二类是 AI 基础设施团队，你们在搭建自己的 Agent SDK 或 Runtime，agent-skills 提供了经过生产验证的技能抽象模型；第三类是 TypeScript 深度使用者，你想看看大型工程中如何用类型系统驱动业务逻辑——这里每个技能函数的输入输出类型、错误类型、元数据类型，都构成了一套完整的契约体系。它不教你怎么写 LLM 提示词，但它决定了你的提示词最终能调用哪些真实、可靠、可追踪的能力。

2. 整体架构设计与选型逻辑：为什么不是简单的函数集合？

2.1 从“一堆函数”到“可发现的能力契约”

很多团队一开始做 Agent 技能，就是建个 utils 文件夹，里面放 sendEmail()、getWeather()、searchDB()……这种做法在 3 个技能以内很轻快，但到了第 15 个，问题就集中爆发：谁记得 getWeather() 接收的是 city name 还是经纬度？哪个函数会抛出 NetworkError 而不是业务 Error？有没有函数需要用户授权才能调用？agent-skills 的破局点在于，它强制定义了一个Skill Interface，所有能力必须实现它：

export interface Skill<TInput, TOutput> { id: string; // 唯一标识，用于 LLM 工具调用时的 function_name description: string; // 供 LLM 理解用途的自然语言描述 inputSchema: ZodSchema<TInput>; // 输入参数的 JSON Schema 验证 execute: (input: TInput, context: SkillContext) => Promise<TOutput>; // 核心执行逻辑 metadata?: { category: 'communication' | 'data' | 'system' | 'custom'; requiresAuth?: boolean; isLongRunning?: boolean; }; }

注意，这里没有用 any 或 unknown，而是用 ZodSchema 做运行时校验。为什么？因为 LLM 输出的参数是字符串 JSON，你不能信任它。我见过太多线上事故：LLM 返回"city": "shangha"（少了个 i），结果函数直接 throw TypeError，整个对话流中断。而 Zod 在 execute 前就拦截并返回结构化错误：“Invalid input: city must be a valid city name, got 'shangha'”。这个设计背后是深刻的工程思维——把 LLM 当作一个不可靠的上游服务，而不是“聪明的同事”。TypeScript 类型只管编译期，Zod 管运行时，两者叠加才构成完整契约。

2.2 Nx：不是为了炫技，而是为了解决“模块爆炸”问题

当技能数超过 20，你面临的真实困境是：

• 每个技能都需要自己的单元测试、E2E 测试、文档、CHANGELOG；
• 修改一个通用工具函数（如 HTTP 客户端封装），要确保所有技能都兼容；
• CI/CD 时间从 3 分钟涨到 12 分钟，开发者开始绕过测试直接 push；
• 新成员入职，面对 50 个文件夹，不知道从哪下手。

Nx 的价值在此刻凸显。它把整个项目拆成多个project：@agent-skills/core（基础接口与运行时）、@agent-skills/weather（天气技能）、@agent-skills/email（邮件技能）等。每个 project 是一个独立的 npm 包，有自己的 package.json、tsconfig、jest.config。更重要的是，Nx 的project graph能自动分析依赖关系：当你修改core，它只 rebuild 和 test 所有依赖它的技能；当你只改email，其他技能完全不受影响。我们实测过，在一个含 42 个技能的私有仓库中，Nx 的增量构建将平均 CI 时间从 9.2 分钟压缩到 2.7 分钟——这不是优化，而是让规模化成为可能。

提示：Nx 的nx graph命令能生成可视化依赖图，这是新人快速理解系统边界的最佳入口。别把它当成运维工具，它是团队知识沉淀的载体。

2.3 semantic-release：让每个技能“活”在自己的版本生命周期里

传统做法是整个 agent-skills 库用一个版本号（如 v2.3.1），但这就意味着：天气技能修复了一个城市名映射 bug，邮件技能新增了附件大小限制，它们被迫共享同一个版本。下游用户升级时，不得不接受所有变更，哪怕他只关心天气功能。agent-skills 采用independent versioning模式，每个技能包独立发版。@agent-skills/weather可以是 v1.4.2，@agent-skills/email是 v3.1.0，互不影响。

这背后是 semantic-release 的精准控制：它监听 Git 提交消息（如feat(weather): add support for forecast hours），自动判断是 patch、minor 还是 major，并为对应 project 发布新版本。关键配置在nx.json中：

{ "targetDefaults": { "release": { "dependsOn": ["build"], "options": { "conventionalCommits": true, "changelog": true, "gitTag": true, "npmPublish": true } } } }

注意：semantic-release 默认对所有 project 一视同仁，但 agent-skills 通过 Nx 的project.json中的targets.release配置，实现了 per-project 的 release 策略。例如，core包要求所有 PR 必须关联 Jira ticket，而weather包允许直接提交。

2.4 Node.js：为什么不是 Deno 或 Bun？

搜索热词里大量出现 “node安装”、“nvm切换版本”、“linux离线安装node”，恰恰说明 Node.js 的生态成熟度仍是不可替代的。agent-skills 选择 Node 18+（LTS），核心考量三点：

1. 生态兼容性：所有主流 AI SDK（OpenAI、Anthropic、Cohere）的官方 Node SDK 都深度适配 Node，而 Deno 的第三方库支持仍显单薄；
2. 企业就绪性：Node 的长期支持（LTS）周期、Windows/Linux/macOS 全平台二进制分发、成熟的进程管理（pm2）和监控方案（Prometheus client），是金融、政务类客户上线的硬性要求；
3. 调试体验：VS Code 的 Node.js 调试器对异步链路（Promise、async/await）的支持远超其他 runtime，这对排查“LLM 调用技能后卡住”的问题至关重要。

我们曾用 Bun 试跑过全部技能，启动快 40%，但遇到两个致命问题：一是node-fetch的 polyfill 在 Bun 下行为不一致，导致部分 HTTP 请求静默失败；二是 Jest 测试套件需大量重写。权衡之下，Node 的“稳”胜过“快”。

3. 核心技能实现细节与实操要点：以天气查询为例

3.1 技能注册：从代码到可发现性的关键一步

一个技能要被 Agent Runtime 识别，不能只写函数，必须完成“注册”。agent-skills 提供registerSkill()工厂函数，其本质是将 Skill 实例存入全局 registry，并生成 OpenAPI-like 的描述对象供 LLM 使用。以weather技能为例：

// libs/weather/src/lib/weather.skill.ts import { Skill } from '@agent-skills/core'; import { z } from 'zod'; import { fetchWeatherData } from './api-client'; export const weatherSkill: Skill<{ city: string }, { temperature: number; condition: string }> = { id: 'get_current_weather', description: 'Get the current weather for a given city. Use this when user asks about today\'s weather.', inputSchema: z.object({ city: z.string().describe('The city name, e.g., "Beijing" or "New York"'), }), execute: async (input, context) => { const data = await fetchWeatherData(input.city); return { temperature: data.temp_c, condition: data.condition.text, }; }, metadata: { category: 'data', requiresAuth: false }, };

注册发生在应用启动时：

// apps/agent-runtime/src/main.ts import { registerSkill } from '@agent-skills/core'; import { weatherSkill } from '@agent-skills/weather'; registerSkill(weatherSkill);

这个过程看似简单，但隐藏着重要设计：registry 是单例且只读。你不能在运行时动态增删技能（除非重启），这避免了状态漂移——LLM 在 t=0 时看到的技能列表，和 t=100ms 时执行时的列表，必须严格一致。我们踩过的坑是：曾有人试图在中间件里根据用户角色动态注册技能，结果导致 LLM 生成了它“以为存在”但实际未注册的 function call，引发 runtime error。

3.2 输入验证：Zod Schema 的实战技巧

Zod 不是装饰器，它是运行时守门员。agent-skills 对inputSchema的使用有三个层次：

• 基础校验：如z.string().min(2).max(50)防止空 city 或超长输入；
• 语义校验：z.string().refine(isValidCityName, { message: "City not found in database" })，调用外部服务验证；
• 组合校验：z.object({ start: z.date(), end: z.date() }).refine(data => data.end > data.start, { message: "End date must be after start date" })。

关键技巧：把校验错误映射为用户友好的提示。默认 Zod 错误是技术性的（如 “Expected string, received number”），但 agent-skills 的execute封装层会捕获 ZodError，并转换为：

{ "error": "Invalid input", "details": "City name must be a valid location, e.g., 'Shanghai'. Got 'shangha'." }

这样 LLM 能清晰理解问题，并向用户解释：“您输入的城市名‘shangha’拼写有误，正确应为‘Shanghai’。”

3.3 执行上下文（SkillContext）：传递非输入参数的隐性通道

execute函数的第二个参数context: SkillContext是设计精髓。它不来自 LLM，而是由 Runtime 注入，包含：

• userId: 当前会话用户 ID，用于权限检查或个性化；
• sessionId: 会话唯一标识，用于日志追踪；
• logger: 结构化日志实例，自动打上 skillId、inputHash 等 tag；
• cache: 一个 TTL 缓存实例，技能可自行决定是否缓存结果（如天气 10 分钟内不变）。

这解决了“如何让技能访问用户上下文而不污染输入契约”的难题。例如，邮件技能需要知道用户邮箱，但你不应该让 LLM 在每次调用时都传userEmail——它属于会话上下文，应由 Runtime 注入。我们实测发现，83% 的技能都会用到context.userId做数据隔离（如“查我的订单” vs “查所有订单”）。

3.4 错误处理：不是 try/catch，而是契约式错误分类

agent-skills 强制技能返回Result Type，而非抛出任意 Error：

type Result<TSuccess, TError> = | { success: true; data: TSuccess } | { success: false; error: TError }; // TError 必须是已知枚举 export enum WeatherError { CITY_NOT_FOUND = 'CITY_NOT_FOUND', API_UNAVAILABLE = 'API_UNAVAILABLE', RATE_LIMIT_EXCEEDED = 'RATE_LIMIT_EXCEEDED', }

这样做的好处是：Runtime 可以根据error字段做差异化处理——CITY_NOT_FOUND直接返回给用户；API_UNAVAILABLE则触发降级（如返回缓存数据）；RATE_LIMIT_EXCEEDED记录告警并限流。如果技能随意 throw new Error("Network failed")，Runtime 只能做泛化处理，用户体验断层。

4. 实操全流程：从零初始化一个新技能

4.1 初始化项目：Nx 命令的精确用法

不要用nx g @nrwl/node:library创建通用库，agent-skills 有专用 schematic：

nx g @agent-skills/schematics:skill --name=calculator --directory=libs

这条命令会：

• 创建libs/calculator/目录；
• 生成calculator.skill.ts（含 Skill 接口模板）；
• 创建calculator.spec.ts（含标准测试骨架）；
• 在nx.json中添加 project 配置；
• 自动添加@agent-skills/core为 peerDependency。

注意：--directory=libs是必须的，因为 Nx 默认会把库放在libs/下，而 agent-skills 的约定是所有技能都在此目录。如果漏掉，后续 semantic-release 会找不到包。

4.2 编写技能逻辑：计算器技能的完整实现

假设我们要实现一个四则运算技能，支持+ - * /：

// libs/calculator/src/lib/calculator.skill.ts import { Skill } from '@agent-skills/core'; import { z } from 'zod'; export const calculatorSkill: Skill< { operation: '+' | '-' | '*' | '/'; a: number; b: number }, { result: number } > = { id: 'perform_calculation', description: 'Perform basic arithmetic operations. Use this when user asks to calculate something like "what is 5 plus 3?"', inputSchema: z.object({ operation: z.enum(['+', '-', '*', '/']).describe('The operator to use'), a: z.number().describe('The first operand'), b: z.number().describe('The second operand'), }), execute: async (input, context) => { let result: number; switch (input.operation) { case '+': result = input.a + input.b; break; case '-': result = input.a - input.b; break; case '*': result = input.a * input.b; break; case '/': if (input.b === 0) { throw { code: 'DIVISION_BY_ZERO' as const, message: 'Cannot divide by zero' }; } result = input.a / input.b; break; default: throw { code: 'INVALID_OPERATION' as const, message: `Unknown operation ${input.operation}` }; } return { result }; }, metadata: { category: 'system' }, };

关键点：

• z.enum确保 operation 只能是四个值之一，LLM 不会生成operation: '^'；
• 除零错误被显式 throw，且类型是{ code: 'DIVISION_BY_ZERO' }，便于 Runtime 统一处理；
• metadata.category: 'system'表明这是内置能力，无需用户授权。

4.3 编写测试：不只是单元测试，更是契约验证

agent-skills 的测试规范要求每个技能必须覆盖：

• 正向路径：输入合法，返回预期结果；
• 边界路径：如除零、超大数字、负数；
• LLM 模拟路径：用真实 LLM 输出 JSON 的字符串，测试解析和执行；

// libs/calculator/src/lib/calculator.spec.ts import { calculatorSkill } from './calculator.skill'; describe('calculatorSkill', () => { it('should add two numbers correctly', async () => { const result = await calculatorSkill.execute( { operation: '+', a: 5, b: 3 }, { userId: 'test-user', sessionId: 'test-session', logger: console, cache: null } ); expect(result).toEqual({ result: 8 }); }); it('should handle division by zero', async () => { await expect( calculatorSkill.execute( { operation: '/', a: 10, b: 0 }, { userId: 'test-user', sessionId: 'test-session', logger: console, cache: null } ) ).rejects.toEqual({ code: 'DIVISION_BY_ZERO', message: 'Cannot divide by zero' }); }); // 模拟 LLM 输出的原始 JSON 字符串 it('should parse and execute LLM-generated input', async () => { const llmInput = JSON.stringify({ operation: '-', a: 100, b: 42 }); const parsed = calculatorSkill.inputSchema.parse(JSON.parse(llmInput)); const result = await calculatorSkill.execute(parsed, { userId: 'test', sessionId: 'test', logger: console, cache: null }); expect(result).toEqual({ result: 58 }); }); });

实操心得：我们把llmInput测试单独列为一个 describe 块，并用jest.mock('zod')模拟 schema 解析失败场景，确保技能在面对脏数据时不会崩溃。

4.4 本地开发与调试：Nx 的 dev-server 魔法

agent-skills 不提供传统 dev server，而是用 Nx 的servetarget 启动一个Skill Playground：

nx serve skills-playground

这个 playground 是一个 Express 服务，暴露/skills端点返回所有已注册技能的 OpenAPI 描述，以及/execute端点供手动 POST 调用。你可以用 curl 直接测试：

curl -X POST http://localhost:4200/execute \ -H "Content-Type: application/json" \ -d '{ "skillId": "perform_calculation", "input": {"operation": "+", "a": 1, "b": 1} }'

更强大的是，它集成了 VS Code 的 Debug 配置。在launch.json中预设了Debug Skill配置，F5 启动后，断点会停在calculatorSkill.execute内部，变量面板清晰显示input、context的完整结构。这是比 console.log 高效 10 倍的调试方式。

4.5 发布与消费：如何在自己的 Agent 项目中使用

发布后，技能以@agent-skills/calculator形式存在于 npm。在你的 Agent 项目中：

npm install @agent-skills/calculator

然后在 Runtime 初始化时注册：

import { registerSkill } from '@agent-skills/core'; import { calculatorSkill } from '@agent-skills/calculator'; // 注册所有技能 registerSkill(calculatorSkill); registerSkill(weatherSkill); // 其他技能同理

关键技巧：用 Nx 的nx migrate命令管理依赖升级。当@agent-skills/core发布 v2.0.0（含 breaking change），运行nx migrate @agent-skills/core@2.0.0会自动生成代码迁移脚本，帮你批量更新所有技能中的 import 路径和接口调用。

5. 常见问题与排查技巧实录：来自 12 个生产环境的教训

5.1 技能注册失效：为什么 LLM 总是说“技能未找到”？

这是最高频问题。排查顺序：

1. 检查 import 路径：确认registerSkill(weatherSkill)中的weatherSkill确实是从@agent-skills/weather导入，而非本地文件路径（如../libs/weather/src/lib/weather.skill）。后者会导致 Nx 构建时无法识别依赖，技能未被打包。
2. 验证 registry 初始化时机：确保registerSkill()在 Agent Runtime 的init()函数中调用，且早于 LLM 初始化。我们曾因把注册放在setTimeout里，导致 LLM 启动时 registry 为空。
3. 检查 Nx project 配置：打开libs/weather/project.json，确认targets.build.options.outputPath指向dist/libs/weather，且targets.build.options.main指向正确的入口文件（通常是src/index.ts）。

独家技巧：在 Runtime 启动后，打印Object.keys(getRegistry())，实时查看已注册的 skillId 列表。这是最直接的验证手段。

5.2 Zod 验证失败但无错误信息：LLM 返回的 JSON 格式诡异

LLM 有时会返回带多余空格或换行的 JSON，如：

{ "city": "Beijing" }

Zod 默认解析会失败。解决方案是在inputSchema.parse()前预处理：

const cleanInput = JSON.parse(JSON.stringify(input).replace(/\s+/g, ' ')); return inputSchema.parse(cleanInput);

更优雅的方式是用z.preprocess()：

inputSchema: z.preprocess( (val) => { if (typeof val === 'string') { try { return JSON.parse(val.replace(/\s+/g, ' ')); } catch (e) { throw new Error('Invalid JSON string'); } } return val; }, z.object({ city: z.string() }) )

5.3 Nx 构建失败：Cannot find module '@agent-skills/core'

错误通常出现在 CI 环境。原因：Nx 的affected检测依赖图时，若core包未被 build，其他技能会找不到它。解决方案：

• 在 CI 脚本中，先运行nx build @agent-skills/core；
• 或在nx.json中配置targetDependencies，让所有技能的build依赖core的build：

{ "targetDefaults": { "build": { "dependsOn": ["^build"] } } }

"^build"表示“所有被当前 project 依赖的 project 的 build target”。

5.4 semantic-release 不发版：Git 提交消息不规范

semantic-release 严格依赖 conventional commits。常见错误：

• 用中文提交：git commit -m "修复天气查询bug"→ 不触发 release；
• 缺少 scope：git commit -m "fix: handle empty city"→ 会被忽略，因为没指定是哪个 project；
• 正确写法：git commit -m "fix(weather): handle empty city"。

实操心得：我们用 Husky + commitlint 强制校验。在package.json中：

"husky": { "hooks": { "commit-msg": "commitlint -E HUSKY_GIT_PARAMS" } }, "commitlint": { "extends": ["@commitlint/config-conventional"] }

这样，不符合规范的 commit 直接被拒绝，从源头杜绝问题。

5.5 技能执行超时：Node.js 的事件循环陷阱

Node.js 是单线程，CPU 密集型操作（如大文件解析、复杂计算）会阻塞事件循环，导致整个 Agent 无响应。agent-skills 的execute函数必须是async，但不能写同步死循环。例如，错误示范：

// ❌ 危险！会阻塞主线程 function heavyComputation(n: number) { let result = 0; for (let i = 0; i < n; i++) { result += i * i; } return result; }

正确做法：

• 移交 Worker Thread：对 CPU 密集任务，用worker_threads拆分；
• 设置 timeout：在execute中用Promise.race包裹：

execute: async (input, context) => { const controller = new AbortController(); const timeoutId = setTimeout(() => controller.abort(), 5000); // 5秒超时 try { const result = await someAsyncOperation(input, { signal: controller.signal }); return result; } finally { clearTimeout(timeoutId); } }

我们在线上环境强制所有技能的默认 timeout 为 3 秒，超时后返回{"error": "TIMEOUT", "message": "Operation took too long"}，LLM 可据此向用户说明“正在处理，请稍候”。

6. 进阶扩展与工程实践：让 agent-skills 真正融入你的技术栈

6.1 与 NestJS 集成：构建企业级 Agent Runtime

搜索热词中高频出现 “typescript + nestjs”，这并非偶然。NestJS 的模块化、依赖注入、守卫（Guard）机制，与 agent-skills 的技能管理天然契合。我们为某银行客户做的集成方案如下：

// agent.module.ts @Module({ imports: [ // 注入所有技能模块 WeatherModule, EmailModule, CalculatorModule, ], providers: [ // AgentService 是核心调度器 AgentService, // 全局守卫，检查用户权限 SkillAuthGuard, ], }) export class AgentModule {}

关键创新点：

• SkillAuthGuard：根据skill.metadata.requiresAuth和context.userId，动态检查 RBAC 权限；
• AgentService：封装了 LLM 调用、技能路由、结果聚合的完整流程，对外暴露processQuery(query: string)方法；
• Health Check Endpoint：每个技能模块提供/health/skill/{id}，返回技能的连通性、缓存命中率、平均延迟，供 SRE 团队监控。

这样，agent-skills 从“技能库”升级为“可观察、可治理、可审计”的企业级服务。

6.2 技能市场（Skill Marketplace）：内部协作的新范式

当团队规模超过 20 人，技能开发会自然分化：前端组负责 UI 相关技能（如截图、页面分析），后端组负责数据技能（数据库、API），算法组负责 AI 技能（图像识别、文本摘要）。agent-skills 支持Monorepo 内多团队协作：

• 每个团队拥有自己的libs/team-name/目录；
• Nx 的nx affected --target=build --base=main --head=HEAD只构建变更的 team 目录；
• semantic-release 为每个 team 目录独立发版，版本号前缀为team-name-v1.2.0。

我们为某电商公司搭建的技能市场，首页展示所有技能卡片，点击进入详情页，显示：

• 技能描述、输入示例、输出示例；
• 维护者（Git 提交作者）、最后更新时间；
• 使用统计（过去 7 天调用次数、成功率）；
• 文档链接（自动生成的 Typedoc）。

实操心得：用 Nx 的nx generate @nrwl/workspace:workspace-generator创建skill-marketplacegenerator，一键生成市场前端应用，与后端技能 registry API 对接。这比手写 CRUD 快 5 倍。

6.3 TypeScript 类型即文档：生成交互式技能文档

agent-skills 的最大隐性价值，是 TypeScript 类型本身构成了最准确的文档。我们用typedoc+typedoc-plugin-markdown自动生成 Markdown 文档：

nx run-many --target=document --projects=weather,email,calculator

输出的docs/weather.md包含：

• id、description的清晰说明；
• inputSchema的 JSON Schema 表格（字段名、类型、描述、是否必需）；
• execute的完整类型签名；
• metadata的枚举值列表。

更进一步，我们用swagger-ui-express将这些 Markdown 渲染为 Web 页面，并嵌入 Try-it-out 功能：用户可直接在浏览器填写 city，点击 Execute，实时看到 API 响应。这比静态文档的采用率高 300%。

6.4 性能优化：从冷启动到亚秒级响应

agent-skills 的初始加载性能至关重要。我们的优化策略：

• Tree-shaking：确保每个技能的index.ts只导出xxxSkill，不导出辅助函数，让打包器能剔除未用代码；
• Lazy Registration：对低频技能（如“生成 PDF 报告”），不在启动时注册，而是在首次调用时动态 import 并注册，减少内存占用；
• V8 Code Caching：在 Dockerfile 中，用node --v8-options | grep cache确认--code-cache-path启用，并挂载 volume 持久化缓存。

实测数据：在一个含 35 个技能的容器中，冷启动时间从 1.8s 降至 0.4s，首字节响应（TTFB）稳定在 120ms 内。

我在实际项目中发现，最常被忽视的其实是技能的“可观测性”。我们给每个技能的execute函数包裹了一层withMetrics高阶函数，自动上报 Prometheus 指标：skill_execution_duration_seconds_bucket{skill_id="get_current_weather",status="success"}。这让我们能一眼看出：哪个技能最慢？哪个技能错误率突增？哪个技能被滥用？——没有这些数据，Agent 的稳定性就是空中楼阁。