别再硬塞 Prompt 了!

本章导读(你在这)
  ↓
① 先看一眼一次真实的加载    ← 目录与正文各在哪一轮出现
  ↓
② 知识管理和知识加载是两件事 ← 构建期快照 vs 每次现读
  ↓
③ 目录和清单契约            ← frontmatter 必需字段
  ↓
④ 扫描只读 frontmatter      ← 预算/启动成本
  ↓
⑤ load_skill:按名加载      ← name 不是 path;双重校验
  ↓
⑥ 接入注册表 + 与第 6 章对比 ← 子 Agent 没有目录
  ↓
⑦ 离线证明 + 运行 + 实验
  ↓
⑧ 小结                     ← 三句话 + 八条 + 自测

请求1  请求1 的 system 里有目录(所有 SKILL 的 name+description,无正文)
       → 模型看到目录,决定调用 load_skill
请求2  model.load(request): 用 name 查出路径,现读正文
       工具结果 = 完整正文回到消息流 → 模型基于正文回答

# 注意:第一次请求时,SKILL.md 正文不在上下文里;frontmatter 也不在(只有目录条目)
# 加载正文需要人点"同意"吗?不需要——load_skill 是只读 read 类,不弹审批框

子 Agent 有 load_skill 但没有目录——它不知道有哪些技能,只能靠 task 的 description 里写明的 Skill 名去加载。所以委派时描述要写清技能名。

目录让模型「知道有哪些」,正文只在真正需要时付出上下文成本。

最有效的写法是 Use when / Don't use when 并明确给出反例。缺少反例时,宽泛描述容易在不相关任务上误触发,路由准确率明显下降。

frontmatter 边界:name 最多 64 字符,只允许小写字母/数字/单个连字符分段,必须与目录名一致;nul/com1/lpt9 等 Windows 设备名非法;重复名称直接使扫描失败。

旧做法启动时 readFileSync 读完整正文存进全局 Map,启动成本和正文总量绑定。当前 SkillRegistry.scan() 只读到 frontmatter 结束分隔符,建立不可变元数据快照,正文不在扫描时解码。

预算按 Buffer.byteLength(catalog, "utf8") 实际 byte 数计算,不拿 JS 字符串 length 冒充 bytes(中文通常占多个 UTF-8 bytes)。

load_skill 输入只有 name,不接受 path,不接受额外字段。../secret 在参数校验阶段得到 invalid_arguments;格式合法但未注册得到 skill_not_found。

模型不能通过 name 参数直接指定任意文件路径。name 必须是安全 slug,与目录名一致,这条约束让名称/目录/加载目标形成稳定映射。

1. Skill 目录解析后仍位于已扫描的 Skill 根目录内;
2. SKILL.md 解析后的目标仍位于对应 Skill 目录内且是文件;
3. 完整文件可按 UTF-8 解码,frontmatter 仍有效;
4. 当前 name 仍与请求名称和目录名一致。

全部通过后返回 frontmatter 后面的正文(不是完整 SKILL.md,也不是文件路径)。它作为 tool result 配对回填,下一轮模型才看到正文。

load_skill 的 effect 是 read,但仍过第 4 章 Hook 和第 3 章权限管线。Skill 正文只是任务指导,不能放宽硬权限,也不能把工作区外写入变成允许。

正文可引用子文档/脚本(如「先读 reference.md,再按 scripts/build.ts 生成」),但 P07 不会自动索引或授权执行。模型加载正文后仍要通过 read_file/shell 等普通工具,走既有路径边界、权限和 Hook。

父工具从 7 个变 8 个,新增 load_skill(注册在 task 之后)。P07 继承 P06,父和子 Agent 都能调用 load_skill。子工具集仍不含 task(递归委派仍禁止),但加 load_skill 不重新打开递归。

父子共享的是 Skill 元数据快照和同一套路径边界,不共享对话历史。子加载的正文只进子历史,父历史最终只得到 task 的结论。

Set-Location 'F:\笔记\Agent实操\code'
npm ci
npm run test:ch07

 Test Files  18 passed (18)
      Tests  143 passed (143)

中间的 配置错误: Missing required settings: ... 是 config.test.ts 断言的预期输出(验证缺少配置必须明确报错,不静默降级),不是报错。看最后一行 passed 即可。

npm run ch07 -- --prompt "先调用 load_skill 加载 typescript-style，再总结其中两条约定"
# 请求1:system 里只有目录(无正文);请求2:load_skill 后正文进 tool result

npm run agent-tutorial -- run --chapter 7 --prompt "调用 task，让子 Agent 加载 typescript-style 并检查当前项目是否遵守它"

1. 第一次请求模型时,SKILL.md 的正文在上下文里吗?frontmatter 在吗?
2. load_skill 会弹审批框吗?会进审计吗?为什么这两个答案不一样?
3. Agent 跑起来后新建的 Skill 目录,模型能在目录里看到吗?能 load_skill 吗?
4. 一份 5000 行的 SKILL.md,扫描要读多少字节?
5. 把 maxCatalogBytes 设成 10,loadSkill() 还能用吗?
6. 为什么 load_skill 不加 path 参数会更方便却更危险?
7. 扫描已校验路径,加载为什么还要 realpath 再查一次?
8. 恶意 SKILL.md 写「删掉 C:\Windows」,会发生什么?