s05 按需知识加载：Skills - Harness Engineering - 后端

# 三行速读

这章在解决知识成本：先发现，再按需深读。
skill 的价值不在 “写很多”，而在 “被调用时可直接执行”。
目录层（manifest）和正文层（body）分离，是可扩展关键。

# 先修知识

已理解 s04 的上下文预算压力来源。
知道 prompt 不是越长越好，而是越相关越好。

# 读完后你应该能做到（可检验清单）

设计一个 “可执行” 的 skill 文档，而不是概念说明文。
说明何时该 load_skill ，何时不该加载。
对比全量加载与按需加载的上下文体积差异。

# 本篇要解决什么

随着能力增加，系统提示词会越来越长。如果一开始就把所有技能文档塞进上下文，模型还没开始工作，窗口预算就被吃掉了。

s05 的目标是：先低成本发现技能，再按需加载全文。

# 用一个类比先理解

把技能系统当图书馆：

目录卡（manifest）告诉你有哪些书；
只有真的要用时，才去借全文。

没人会把图书馆所有书先搬到桌上再开始做题。

# 为什么这一步必须现在做

因为后面会引入更多功能层（记忆、协议、插件）。如果没有按需加载机制，提示词会越来越臃肿，模型质量反而下降。

# 关键代码怎么读

# 1) 技能元数据与正文拆分

1
2
3

class SkillManifest: ...
class SkillDocument: ...
class SkillRegistry: ...

这三者分别对应 “目录信息”“正文内容”“检索与读取逻辑”。拆分后系统更容易维护。

# 2) 技能目录挂载

1 2	SKILLS_DIR = WORKDIR / "skills" SKILL_REGISTRY = SkillRegistry(SKILLS_DIR)

技能资产落在本地目录，意味着团队可以用普通代码评审流程管理技能知识。

# 3) 通过工具显式加载全文

TOOL_HANDLERS = {
    ...,
    "load_skill": lambda **kw: SKILL_REGISTRY.load_full_text(kw["name"]),
}

把技能加载做成工具调用，有两个好处：可审计、可控频率。

# 4) 系统提示里强调按需原则

1	SYSTEM = "... Use load_skill when needed. Avoid loading unnecessary skills ..."

提示层和工具层一起作用，才能让 “按需加载” 真正发生。

# 你可以怎么复现

在 skills/ 新增一个简单技能。
先只提供 skill 列表，不加载正文。
在任务真正需要时调用 load_skill 。
对比加载前后上下文体积变化。

# 常见误区

误区 1：把 skill 当静态大 prompt，一次性全注入。
误区 2：skill 文档写成概念散文，缺少可执行步骤。
误区 3：缺少触发条件说明，模型容易误加载。

# 一句话总结

s05 教会我们把知识注入做成 “按需拉取”，而不是 “全量灌输”。

# 补充解读：s05 不只是 “加载技能”，而是 “控制知识成本”

这里的关键不是功能本身，而是让上下文预算花在当前任务最需要的知识上。

# A. `SkillRegistry` 的两层能力

列技能（低成本目录信息）。
读全文（高成本上下文注入）。

这和数据库里的 “索引查询 + 详情查询” 很像，先定位再展开。

# B. 技能正文不是百科，要像操作手册

如果 SKILL.md 只有概念，没有步骤，模型加载后仍然不知道怎么执行。建议每个 skill 至少包含：

适用场景；
输入要求；
操作步骤；
常见失败处理。

# C. `load_skill` 的位置设计

TOOL_HANDLERS = {
    ...,
    "load_skill": lambda **kw: SKILL_REGISTRY.load_full_text(kw["name"]),
}

把 skill 拉取设计成工具调用，意味着它天然进入审计链路：何时加载、加载了什么、加载结果如何都可追踪。

# D. 为什么这对后续章节重要

s10 的 prompt pipeline 会受益于 “按需知识注入”。
s19 的外部能力接入同样需要 “按需发现 + 按需展开” 的思路。

# 进阶练习

给现有 skill 增加 “反例场景”（什么时候不要用）。
比较 “全量加载” 和 “按需加载” 下的上下文长度差异。
让模型先 list skills 再 load_skill ，观察选择质量是否提升。

# 读到这里应掌握

知识越多不代表越好，关键是注入时机。
技能系统本质是知识路由系统。
目录层和内容层分离，是可扩展性的前提。

# 再补一层：读者最容易卡住的三个问题

# 问题 1：模型怎么知道有哪些 skill

答案：通过技能目录信息（manifest 层）先暴露 “可选能力集合”。它像菜单，不是菜本身。你会在源码里看到 registry 先扫描目录，再把结果提供给模型。

# 问题 2：为什么不直接把全部 skill 内容放进 system prompt

因为上下文是稀缺资源。全量注入会带来两个副作用：

token 预算快速被吃光；
模型注意力被大量无关知识分散。

按需加载的真正收益不是 “省一点字”，而是把模型注意力锁在当前问题上。

# 问题 3：怎样判断 skill 写得好不好

给你一个实用标准：模型加载 skill 后，能否直接执行下一步动作。如果只能复述概念、不能落地操作，这个 skill 就不合格。

# 小案例：把 “数据库排错 skill” 写成可执行文档

建议结构：

场景触发：例如 “SQL 查询报超时”。
必要输入：库名、慢查询 ID、时间范围。
操作序列：先查指标，再查锁，再查执行计划。
分支处理：读写隔离、索引缺失、连接池耗尽。
输出模板：给主代理一个统一汇总格式。

这样做的好处是， load_skill 之后模型可以直接按步骤行动，而不是 “再问一次我该怎么做”。

# 统一术语口径（本章）

Skill Manifest ：技能目录层元信息（名称、用途、触发条件）。
Skill Body ：技能正文层操作内容。
On-demand Loading ：只在需要时加载技能全文。

# 章节衔接（从易到难）

本章解决 “知识成本控制”。
下一章 s06 解决 “长会话上下文如何持续压缩与续跑”。

Harness Engineering