智能体 Skill 调优“焚诀”——业务逻辑之外的胜负手

文章内容基于作者个人技术实践与独立思考，旨在分享经验，仅代表个人观点。

引子：37 个技能的"能跑"与"能用"

今年5月底，我们在某AI投研平台借助 Coding Agent，4天完成了37个投研技能的创建与集成。传统人工预估需1~2周的工作量被大幅压缩。然而试运行期间，路由不准、上下文爆炸、输出不可信三类问题接踵而至。这些问题并非出在业务逻辑本身，而是路由、结构、规则与边界约束等工程体系层面。从"能生成"到"能生产"，需要建立一套完整的工程体系：路由分得准、结构拆得省、规则写得狠、案例配得真、评测兜得住。

一、运行时视角：skill 到底是什么

skill 不仅是静态文档，更是 Agent 主循环中的运行时组件。它由三种成分构成，各自遵循不同的物理规律：

成分	运行时行为	物理规律	优化方向
常驻索引（description / 聚合索引）	每轮请求都进上下文，参与路由决策	注意力稀释、缓存前缀	必须短、必须是路由条件、必须稳定
按需知识（templates 正文）	命中后经 read_file 注入	只在被选中时占上下文	可以厚，但要单一职责
外部确定性约束 （代码护栏）	完全不进上下文，由系统强制	100% 可执行	prompt 管语义，代码管边界

"生成快"是因为 skill 只是文本；"打磨难"是因为它是参与每轮路由与注意力分配的运行时组件。

二、什么叫"生产级 skill"

生产级 skill 需满足五条判定标准：

1. 可路由——用户的口语化问题能被准确分派到正确的技能；
2. 可治理——规则结构分层、有唯一权威源，改一条规则不用动几十个文件；
3. 可溯源——每个数据与判断都能追溯到知识库来源，缺口显式披露；
4. 可评测——每一层都有可回归的评测集，改动前后效果可量化；
5. 可迭代——现场 bad case 出现后，有明确的归因路径和修复落点。

以下按"意图层 → 套件整合 → 细节调优 → 评测闭环"的顺序展开优化实践。

三、意图层：skill 的路由器，先于 skill 本身

核心观点：skill 写得再好，意图分错全白搭。意图层是技能套件的第一道质量闸门。

1. 意图树：按"分析范式"切分，不按"话题"切分

问题：初期按"一个话题一个技能"平铺，导致意图边界模糊。收敛为9个"话题式"二级意图后，仍存在结构性混淆，"公司基本面"成为吸收各类问题的"黑洞意图"。

对策：按"分析范式"重新切分意图树。根意图下收敛为6个"范式式"二级意图（如宏观策略、行业跟踪、个股研究等）。细粒度分流交给技能层内部路由表处理。

效果：新意图树回归评测准确率提升至92.50%，系统性混淆基本消失。残留错误集中在"个股研究"且边界清晰，易于后续收敛。

原理："话题"天然共享语义空间，而"范式"互斥。两级路由将"几十选一"拆分为"六选一 + 技能内表格路由"，每一级都在其分辨率能力内工作。

2. 意图映射：让路由条件结构化、可热更

意图映射配置采用 JSON 格式，包含三个关键设计点：

• [规则基座, 聚合索引] 二元组：技能加载最小单元为"基座+业务"组合。
• typical_questions 作为 Few-shot 注入：提供真实业务风格的典型问句作为判别锚点，同时作为评测集种子。
• Redis Pub/Sub 热更新：支持不发版调整映射配置，降低变更成本。

消融实验显示，例句 few-shot 主要提升的是"确定性"（降低兜底率和延迟），而准确率的主力来自行内旧系统沉淀的判别经验。分类器需要的是判别边界，而非语义概括。

3. 改写管道：分类前先把问题治理干净

针对投研人员口语化、含指代的原始问句，在分类前置入四阶段改写管道（RewriterPipeline）。改写作为公共前置，同时服务于意图分类和知识库检索。

4. 工程可用性：回退、缓存与短路

• 失败回退：LLM 分类失败时回退至规则匹配，保证服务可用。
• 缓存：意图结果存入 Redis，应对连续追问。
• FAQ 向量化短路：高频标准问句通过 embedding 相似度直接命中，跳过意图引擎与 Agent 推理。

模型选型：意图分类作为窄判别任务，小模型（25B）与大模型（235B）准确率差异不显著，但小模型延迟更低、成本更优。应将大模型留给更需要推理能力的 ReAct 智能体。

5. 意图层优化 checklist

检查项	Demo 级	生产级
意图粒度	一个话题一个意图，几十个平铺	按分析范式切分，两级路由
路由条件	只有意图名称和描述	typical_questions 例句 + 反例
失败处理	LLM 挂了整条链路挂	规则回退，永远有答案
变更成本	改意图要发版	配置化 + 热更新
高频问题	每次都走全链路	FAQ 短路

四、套件整合：从 37 个平铺目录到三层专家套件

核心观点：生产级的解法是把"合规规则、业务路由、分析范式"拆成三层，按需加载。

1. 平铺结构的三宗罪

1. 规则重复：通用规则在多个文件中版本漂移。
2. Token 浪费：单技能全量注入，大量无关信息稀释注意力。
3. 维护失控：修改通用规则需遍历所有文件。

2. 三层架构：合规、路由、范式各归其位

将 37 个平铺技能重构为 1 + 6 + 19 的三层套件：

• L1 基座（research-baseline）：定义"怎么做合规"，包括数据源、溯源标注、范围约束等，任何意图必读。
• L2 聚合索引（6 个）：定义"这个业务怎么路由"，包含子能力路由表及少量业务专属约束。
• L3 模板（19 个）：定义"这类分析怎么做"，仅包含单一分析范式的工作流与输出结构。

各层明确声明不重复其他层已规定的内容，确保每一层只写增量。

3. description 只写 when to / not to use

生产级写法：description 是路由条件，仅回答"什么时候该用我"、"什么时候不该用我"及"产出物是什么"。功能简介应放入 SKILL.md 正文，按需加载。

尤其在聚合索引的子能力路由表中，需明确列出"触发场景"与"不适用场景"。近义技能间的路由错误多发生在边界，负样本（反例）是划清边界的关键。数据显示，补充反例后路由准确率从 73% 提升至 85%。

4. 按需加载：token 省 80% 背后的机制

L3 模板不随技能加载，而是由 Agent 根据路由表判定后，通过 read_file 动态加载。这使得单技能上下文从 ~6000 token 降至 ~1200 token，节省约 80%。

Prompt Caching 收益：基座+聚合索引作为稳定前缀常驻，利于 KV 缓存命中；模板按需追加在后，不破坏缓存。稳定的长基座比频繁变动的小提示更具成本优势。

5. 一条规则只写一遍：一处定义、处处引用

遵循 DRY 原则，主提示词只做场景路由声明，基座作为唯一权威定义源，业务 SKILL 与模板仅通过语义化引用复用。这避免了双写导致的版本漂移和指令冲突。

注意：规则落点受模型能力约束。弱模型时代可能需要将规则放在主提示词中以确保遵循度；模型升级后应及时重构，将领域规则回归至 skill 体系内。

五、bad case 驱动的细节调优：规则是在现场打磨出来的

核心观点：基座里每一条带 ✗/✓ 对例的规则，背后都是一个真实 bad case。

1. 六个典型案例解析

案例一：溯源标注被模型"美化"

现象：模型将 <1> 美化为 HTML 标签或其他符号，导致前端解析失败。

对策：防御性枚举，明确禁止所有变体，仅允许纯文本 angle-bracket 形式。

案例二：分歧数据伪装成区间

现象：不同研究员的观点被模型合并为数值区间（如 "1.6-2.0"），掩盖了分歧。

对策：严禁使用连字符呈现分歧数据，要求显式列出各来源观点。提供正误对例，引导模型以对比表格形式呈现多维分歧。

案例三：伪文档名与重复来源

现象：模型拼接切片编号构造不存在的文档名，或重复列出同一文档。

对策：在规则中展示工具返回的真实数据结构，明确指出唯一合法来源字段；枚举错误形态并给出反例；在交付确认清单中增加校验项。

案例四：时间范围被静默放宽

现象：指定年份无数据时，模型静默使用其他年份数据作答。

对策：Prompt 层要求披露范围过滤情况；代码层强制使用前端传入的时间参数，忽略 LLM 生成的时间值，实现系统级约束。

案例五：检索 query 碎片化与重复检索

现象：模型拆分自然语句导致召回率下降，或无目的反复检索。

对策：规定首轮检索必须使用用户原始问句；限制单轮对话最大检索次数，超限后基于已有信息作答；代码层设置检索上限护栏。

案例六：Mermaid 节点文字溢出

现象：图表节点文字过长导致渲染溢出。

对策：将前端渲染约束转化为模型可执行的文字规则，如字数限制、换行符插入位置等，并配图例。

2. 方法论提炼：bad case 修复五步法

1. 归因分层：判断问题属于意图、架构、模板还是工程层。
2. 落点选择：确定性约束优先代码化，语义性约束保留在 prompt。若 prompt 修复两次仍复发，应考虑代码化。
3. 落点唯一：杜绝规则双写。
4. 配 ✗/✓ 对例：每条新规则必须附带真实正反示例。
5. 登记自检 + 回填评测：规则进入自检清单，case 进入评测集以防回归。

六、评测闭环：没有评测集的 skill 调优是玄学

评测体系分三层，对应技能套件的三层制品：

1. 意图层：离线评测集 + 契约测试。引入 L0 级核心用例过滤，每次变更必须全对才能发布。评测集应使用真实业务风格问句，避免分数虚高。
2. 技能输出层：自检清单 + bad case 回归。利用模型自评测和现场 case 回填。
3. 端到端：独立评测 CLI。零依赖后端源码，从用户、系统、质量三通道采集数据进行端到端评估。

关键经验：

• 第一个失败就建评测：从少量真实失败案例起步，快速迭代。
• 区分 Pass@k 与 Pass^k：探索用 Pass@k，上线回归用 Pass^k（核心用例必须全对）。
• 先修评测，再改 Agent：排除评测系统本身的噪声和 bug，确保信号真实。

建议评测集与 typical_questions、FAQ 库同源共建，一份语料多处复用。

七、总结：从 AI 初稿到生产级技能的 checklist

37 个技能 4 天生成，但打磨用了数周。三层重构让单技能上下文减少 80%，基座规则背后均为真实 bad case。生成快、打磨慢，而打磨才是 skill 工程的主体。

skill 的本质，是把领域专家的隐性经验编译为 LLM 可执行的显性规则。AI 加速了"编译"，但"链接与调试"（路由、整合、调优、评测）仍是人的工程活。

从运行时视角看，全部优化动作可归结为：模型负责推理，外部系统负责状态和边界——不断把该外置的外置、该常驻的写短、该按需的拆开、该枚举的封死。