实现篇第10章 把经验写进说明书——Skill ​

本章导读: 实现篇扩展第 2 章。概念篇讲过 Skill 是“经验的可发现说明层”。这一章推演 mini-agent 里怎么加一个最小
SkillCatalog。不写进src,只讲清发现、加载、冲突和失败语义怎么设计。
小A发现自己的 Agent 每次处理“发布任务”都要重复讲一遍流程:先跑测试、再打标签、再推送。他在 system prompt 里塞过几次,上下文越来越长,还经常被新任务挤掉。他问老Z:“能不能把流程写成一份说明,让 Agent 需要时才读?”
“能。你要的是一个 Skill 说明包,不是代码,是文字。”老Z说,“但‘需要时才读’是关键。一次性把几十个 Skill 都塞进上下文,你的 Agent 会像带着一整本手册回答问题,所以先想清楚发现和加载怎么分离。”
小A追问:“那这跟我在 system prompt 里直接写流程,到底差在哪?”
“差在‘什么时候进上下文’。”老Z说,“system prompt 每次请求都带,你的发布流程在用户问‘今天天气怎样’时也占着 token。Skill 是按需加载的:模型先看一份轻量索引,判断这次任务要不要用,要了才把正文读进来。mini-agent 的 runAgent 现在只有一个 system 字符串参数(见 agent.ts 的 options),没有动态注入通道;Skill 要进来,就得在循环里多一个‘读说明’的动作。这一章不写进 src,是推演这个动作的接口长什么样。”
小A:“那我现在把流程写进 system,跟写进 agent.ts 的 options.system 有什么区别吗?”
“没区别,它们最终都进 client.stream 的同一个参数。”老Z说,“runAgent 把 options.system 原样传给 client.stream({ system, ... }),循环里没有别的地方碰它。所以问题不是‘写在哪’,而是‘几时进’。你写进 system,它在每一轮、每一条 user 消息上都占着字符:当前 runAgent 把 system 作为单独参数传给 Provider;estimateContextChars 和 trimContext 只处理 messages,不把 system、工具定义和 Provider 额外开销计入这个字符预算。Skill 要的恰好相反,只在任务相关时才出现,任务结束就让位。”
老Z列了一张对比表:
| 维度 | system prompt 里的流程 | Skill 按需加载 |
|---|---|---|
| 进上下文的时机 | 每轮固定带 | 模型判定相关才加载 |
| 占用的成本 | 常驻,始终计费 | 按需,用完可裁 |
| 更新的方式 | 改代码重部署 | 改 Markdown 文件 |
| 多份共存 | 挤在一处互相稀释 | 各自独立、按名取用 |
| mini-agent 现状 | 已实现(options.system) |
未实现(本章推演) |
“这张表的最后一列是现状:一个已实现,一个纯推演。你别读成‘该换 Skill 了’,你现在连一个正式加载过的 Skill 都没有。推演的意义是先把接口形状想清楚,不是让你这章就动手写。”
Skill 是软约束,不是代码 ​
“先立边界。”老Z说,“Skill 是一份带 frontmatter 的 Markdown 说明,name、description,再加正文步骤。它通过文本影响模型的决策,模型可能不遵守,真正的硬约束要靠工具和审批。所以 Skill 的接口只负责‘找到说明并返回’,不负责‘保证模型照做’。”
---
name: release-process
description: 发布任务的固定流程:先测试、再打标签、再推送
---
1. 运行 npm test,失败则停止
2. 通过后打 git tag
3. 推送到远程小A看着这段 Markdown:“等等,这不就是给模型看的 prompt 片段吗?它跟工具的 description 字段有什么区别?”
“区别在谁触发、何时生效。”老Z说,“工具的 description 是常驻的,模型每轮都看得见,因为它随时可能被调;Skill 的正文是临时进上下文的,任务结束了就该让位。更关键的是:工具 description 描述的是‘这个动作怎么用’,Skill 描述的是‘这类任务该按什么顺序做’。一个讲动作,一个讲流程。mini-agent 里 createWorkspaceTools 给 read/write/bash 各写了一句 description(见 tools.ts),那是动作说明;你发布流程里的‘先测试再打标签’,是任何单个工具都讲不清的跨步骤编排,Skill 补的就是这一层。”
“那既然是软约束,模型不照办怎么办?”小A问。
“两条退路。”老Z数着指头,“第一,模型读了说明却跳过‘先测试’,直接调 bash 去打标签,这时候 denyBashByDefault(见 approval.ts)会先把 bash 拦下来,硬约束兜底。第二,把‘是否真的跑了测试’写进 Skill 的正文,让模型在工具结果里看到证据,比如要求 npm test 的输出贴回上下文。Skill 负责‘告诉’,工具和审批负责‘兜底’。mini-agent 现在只有后一层,前一层空着。”
小A还是不踏实:“软约束这个性质,会不会让 Skill 的价值打折?我写半天说明,模型照样不听。”
“不会,因为你要的不是‘听话’,是‘概率上升’。”老Z说,“模型在任务相关时读到一份结构化的流程,照着做的概率远高于在 2000 字 system prompt 里翻找同一段话。软约束做不到 100% 执行,但能把‘经常忘’变成‘很少忘’。真正不能错的动作,靠工具和审批做硬门槛,denyBashByDefault 拦截 bash 是确定性的,不赌模型表现。”
| 约束层级 | 例子 | 失效时 | mini-agent 现状 |
|---|---|---|---|
| Skill 正文 | 发布先跑测试 | 模型忽略,流程被跳过 | 未实现(推演) |
| 工具 schema | bash.command 必须为 string |
模型传坏参数,工具返回 isError |
已实现 |
| 审批策略 | bash 默认拒绝 | 策略异常,循环抛错 | 已实现(denyBashByDefault) |
“这三层里,只有 Skill 那层是文字说服,下面两层是代码强制。把哪一层当防线,取决于那句流程是‘最好照做’还是‘必须照做’。”
设计一个最小 SkillCatalog ​
老Z沿 mini-agent 的风格推演了一个接口:
// 设计草图:SkillCatalog(未进 src,先确认需求)
export interface Skill { name: string; description: string; content: string; }
export interface SkillCatalog {
/** 扫描目录,返回所有 Skill 的名称与描述(不加载正文) */
discover(): Promise<SkillSummary[]>;
/** 按名称加载完整正文 */
load(name: string): Promise<Skill>;
}“发现和加载分离,是 Skill 设计的核心。”老Z说,“discover 只读 frontmatter(名称和描述),load 才读正文。这样 Agent 可以用几十个 Skill 的索引做判断,只在真正需要时加载那一个的正文,上下文不会因为 Skill 数量线性膨胀。这就是概念篇讲的‘发现/触发/渐进加载’三步。”
小A盯着接口看了会儿:“这个 discover,是不是有点像 createWorkspaceTools 扫工具那一段?”
“对,最像的就是那段。”老Z说,“runAgent 在循环开始前,先用 options.tools.map((tool) => tool.spec) 把所有工具的 name 和 description 收集起来,塞进 client.stream 的 tools 参数(见 agent.ts)。模型看到的是一份工具索引,不是每个工具的执行逻辑。discover 干的是一样的事:给模型一份‘有哪些 Skill 可选’的目录,正文先不给。工具的 spec 是常驻索引,Skill 的 summary 是按需索引,前者每轮都在,后者只在任务进来时刷新一次。”
“那为什么不干脆一个 getAll(),一次全读?”小A问。
“因为一次全读,‘轻量索引’就不存在了。”老Z说,“getAll() 把正文也加载进来,Skill 越多、每轮请求越重,你还是在往上下文塞东西,只是换了个入口。拆开的依据是读取成本不同:frontmatter 一读就是,正文可能几十行。让模型基于便宜的索引做判断,只把贵的正文留给真正要用的那一个。”
“那正文到底怎么进上下文?”小A接着问。
“两条候选,各有代价。”老Z比划着,“一是当成一条 role: 'user' 消息插进去。但 mini-agent 的 Message 类型(见 types.ts)里 user 消息是模型可见的,Skill 正文就成了对话历史的一部分,下一轮还在,一直占 token。二是做成一个‘读 Skill’的工具,让模型主动调,这样正文以 tool result 的形式进来,trimContext(见 context.ts)在上下文超预算时能把它和对应 assistant 消息一起裁掉。第二种更合 mini-agent 的脾气:让模型用工具去取,而不是宿主硬塞。但这也意味着你得新增一个 read_skill 工具,又回到‘先有需求再加工具’的老规矩。”
| 正文进上下文的方式 | 生命周期 | 可被 trim 裁掉 | 代价 |
|---|---|---|---|
宿主塞 role: user 消息 |
成为对话历史,常驻 | 只有整体超预算才被裁 | 下一轮还占 token |
模型调 read_skill 工具 |
以 tool result 形式存在 | 和对应 assistant 成组裁掉 | 要新增一个工具 |
本章其余小节为付费内容
登录后可购买;已购 Pi Cookbook Pro?登录即解锁完整章节。