← Pi Agents

携带文件的技能

`SKILL.md` 可以用相对路径引用脚本、参考资料和资源;这里是目录布局、路径约定,以及如何把整个目录作为包分发。

评审守卫的清单有四十项。SKILL.md 里放上三屏 Markdown,就会在技能每次触发时把全部四十项都加载进来,包括那些只用到三项的小评审。

skills.md 提供了一个更好的安排:技能可以把脚本、参考资料和资源与它的指令打包在一起。正文保持简短并点出这些文件;文件只在指令说要读它们的时候才加载。

目录布局

review-guard/
├── SKILL.md
├── scripts/
│   ├── run-checks.sh
│   └── collect-diff.sh
├── references/
│   ├── checklist.md
│   └── severity-rubric.md
└── assets/
    └── finding-template.md

这四个目录名不是强制性的。skills.md 在它自己的示例里展示的正是这个形状——scripts/、references/、assets/——而这个约定正是让一个技能对下一个人可读的东西。没有什么阻止你添加 templates/ 或 data/;也没有什么鼓励你这么做。

用相对路径引用文件

SKILL.md 变成:

---
name: review-guard
description: 评审变更后的代码是否符合本仓库的约定,并运行它自己的检查。在评审 diff、拉取请求或未提交变更时使用。
---

# 评审守卫

1. 运行 `scripts/run-checks.sh`,在评审任何东西之前先读它的输出。
2. 读 `references/severity-rubric.md`,并给每一条发现分类。
3. 读 `references/checklist.md`,并检查其中适用于被改动文件的每一项。
4. 用 `assets/finding-template.md` 中的形状写出每一条发现。

按严重程度排序报告发现的问题。没有问题的时候就什么都不报告。

skills.md 直白地说出了规则:引用打包的文件时使用相对于技能目录的路径,因为 Pi 会告诉模型技能住在哪里,好让它解析这些路径。

最后那个从句是你要依赖的部分。你写 references/checklist.md,不是绝对路径,也不是相对于工作目录的路径。一个在项目之间搬动的技能目录会继续工作。

使用打包文件的三种方式

种类 用途 如何加载
references/ 决定要做这项工作之后查阅的细节 模型用 read 工具读它
scripts/ 不该被即兴发挥的确定性工作 模型通过 bash 运行它
assets/ 用来复制或填充的素材 模型用工具读它或写它

要紧的区别是何时。参考资料文件在技能判定任务相关之后被读;脚本在指令说要运行它的时候运行;资源在输出的那一刻被使用。把所有东西都打包进 SKILL.md,那么它全部都会在每次触发时加载。

错误:"把文件打包进技能就让模型能用上它们。"
正确:"一个打包的文件是磁盘上的一个文件。当正文告诉模型去读它时,它才到达上下文,用的是模型自己的工具。"

脚本靠无聊赢得一席之地

技能里的一个脚本应该做某件模型亲手做会更差或更不可靠的事。运行仓库自己的检查就够格:

#!/usr/bin/env bash
# scripts/run-checks.sh - run the target repository's own verification.
set -euo pipefail

# Which repository to check, in order of preference:
#   1. $PI_REVIEW_GUARD_ROOT, set by whoever launched Pi or a wrapper script.
#      Skill frontmatter does not become environment variables.
#   2. the top level of the Git working tree containing Pi's working directory.
# Counting parents would be wrong here: a project skill lives at
# repo/.pi/skills/<name>/scripts/ and a shared one at
# ~/.pi/agent/skills/<name>/scripts/, so the depth is not a constant.
root="${PI_REVIEW_GUARD_ROOT:-$(git rev-parse --show-toplevel)}"
cd "$root"

echo "== repository: $root =="
echo "== typecheck =="
pnpm typecheck

echo "== unit tests =="
pnpm test:unit

注意这个脚本不做什么:它不从自己的路径推导仓库。dirname "$0" 是技能的 scripts/ 目录,而它与仓库之间隔了多少级父目录,取决于这个技能被安装在哪里——repo/.pi/skills/<name>/ 下的项目技能和 ~/.pi/agent/skills/<name>/ 下的共享技能处于不同的深度,而打包的技能又在另一个地方。询问环境既更短,也是唯一一个在被作为包安装后仍然成立的版本。

一个变量实际上是怎么被设置的

这一点值得说得精确,因为那个显而易见的答案是错的。技能 frontmatter 不会变成环境变量。skills.md 的字段表列出了 name、description、license、compatibility、metadata、allowed-tools 和 disable-model-invocation,而 compatibility 被文档记载为环境要求——一份关于这个技能需要什么的陈述,而不是一个提供它的机制。Pi 里没有任何东西读 frontmatter 并写 process.env。本章的一个早期草稿说技能可以"在自己的 frontmatter 或一个打包的配置里设置 PI_REVIEW_GUARD_ROOT",而这只有在 Pi 真的那么做时才成立,而它并不那么做。

有三种方式真正有效,而它们值得分开来讲,因为其中只有一种是自动的。

**1. 操作者导出它。**有人运行 PI_REVIEW_GUARD_ROOT=/path/to/repo pi。脚本能读到它,是因为 shell 把它放进了它继承来的环境里。这是常见情形,也是这个变量用 PI_ 前缀命名的原因:它是给你的脚本用的约定,不是 Pi 的特性。Pi 原样传递它的环境,这一点有文档记载,也没什么了不起。

**2. 脚本读一个它确实能找到的打包配置文件。**对于一个作为包发布的技能,一个必须随技能一起走的值,更好的去处是脚本相对于自身路径定位的一个文件——而这是父目录相对解析确实正确的唯一一个地方,因为技能目录内部的一个文件在其中的深度是固定的:

config="$(dirname "$0")/../guard.conf"
[ -f "$config" ] && . "$config"
root="${PI_REVIEW_GUARD_ROOT:-${GUARD_ROOT:-$(git rev-parse --show-toplevel)}}"

这读的是包作者随包发布的一个位于同级的 guard.conf,并以同样的方式回退。这个区别正是要点:一个打包的文件可以相对于技能找到,因为它随它一起移动。一个目标仓库不可以,因为它完全在别的地方。

**3. 一个包装脚本来设置它。**如果这个值依赖于只有调用方才知道的某个东西,那就由调用方来设置:

#!/usr/bin/env bash
# review - run the guard for a specific repository.
set -euo pipefail
PI_REVIEW_GUARD_ROOT="${1:?usage: review <repository>}" \
  "$(dirname "$0")/scripts/run-checks.sh"

不起作用的是让模型凭空发明这个变量,而这一点值得直说:一个告诉模型去设置环境变量的技能,是在请它把一行 shell 写进一条命令里,到那时这个变量就是模型的主张,而不是你的。如果一个值必须是可信的,它必须来自操作者设置的环境,或来自包随带的文件——而不是来自对话。

这种发现方式是一种约定,不是一道边界。一个被告知去运行脚本的模型,已经被给了一条进入你这台机器的路径,而脚本的 git rev-parse 会捡起 Pi 被启动时所在的那个工作目录。第 42 章会恰当地处理这一点:它是一个让常见情形正确的流程,而不是针对一个有意离开仓库的模型的遏制。

skills.md 说要相对于这个技能目录运行脚本,并把环境方面的准备保持在技能内部。这是一条有意义的指令:技能为它自己的前置条件负责,而不是假定宿主已经准备好了。

大小经验法则

这是我的建议,不是有文档记载的限制。skills.md 没有给 SKILL.md 定 token 预算。理由如下:

  • 正文在技能每次触发时都会加载。让它只放步骤,不要放参考资料。
  • 如果一条规则是在决定做什么之前就需要,它属于正文。如果是在之后才需要,它属于 references/。
  • 如果一个文件在每一次运行时都需要,那它就不是真正的支撑文件;把它内联进去,并接受这个代价。

一个十五行、读三个文件的正文,通常胜过一个三百行、一个文件都不读的正文。

让打包的脚本可被审阅

第 8 章说过,项目技能可以指示模型运行脚本,而不熟悉的技能及其支撑文件应当在授予项目信任之前被审阅。那种审阅只有在脚本是一个脚本——仓库里可读的文本——而不是一个编译好的二进制文件或某个在运行时才抓取的东西时,才有可能。

谁来决定工作目录

值得说清楚,因为它正是让一个打包的脚本变得含糊的那个东西。模型通过 bash 运行脚本,而这个工具继承的是 Pi 的工作目录——你启动 Pi 时所在的那个目录,不是技能的。

    flowchart TD
  S["Pi 启动于 repo/"] --> C["cwd 是 repo/"]
  C --> M["模型调用 bash"]
  M --> B["run-checks.sh 继承 cwd:repo/"]
  K["技能目录<br/>repo/.pi/skills/review-guard/"] -. "一个完全不同的地方" .-> B
  B --> G["脚本询问 git rev-parse --show-toplevel"]
  G --> R["在仓库里运行各项检查"]
  

所以技能自身的位置从不决定脚本在哪里运行。这就是脚本要询问环境的原因。一个从 $0 往上数父目录的脚本,会是在从一个并非它执行之处的地点推导目标目录,而它需要的深度取决于技能是如何被安装的。

有两个习惯会有帮助:让每一个打包的脚本都随技能一起做版本控制,并让它大声失败而不是静默地继续:

set -euo pipefail

没有那两行,一个检查脚本可以一边跳过一切一边以状态码零退出,而模型会报告一次干净的评审。

把它作为包发布

skills.md 说要用一个 Pi 包通过 npm 或 git 分发一个或多个技能,并把环境方面的准备保持在技能内部,在包里声明任何所需的运行时依赖。

packages.md 描述那需要什么。一个包就是一个普通目录或 npm 包,而没有 pi 清单时,Pi 会从常规位置发现技能目录:

my-pi-package/
├── package.json
├── extensions/
├── skills/
├── prompts/
└── themes/

review-guard/ 直接放进 skills/。

有了显式清单,资源可以放在别处或被过滤:

{
  "name": "team-review-tools",
  "keywords": ["pi-package"],
  "pi": {
    "skills": ["./skills/review-guard"],
    "prompts": ["./resources/prompts/*.md"]
  }
}

路径相对于包根目录。数组接受 glob 模式和排除项。如果一个资源根目录以点开头或是符号链接,直接把它列出来,因为通过 glob 遍历不会发现它。

正确声明依赖

packages.md 在这一点上很坚决,而原因是技术性的,不是风格上的。Pi 向扩展和技能提供 @earendil-works/pi-ai、@earendil-works/pi-agent-core、@earendil-works/pi-coding-agent、@earendil-works/pi-tui 和 typebox。在 peerDependencies 里用 "*" 范围声明它们,并且不要打包它们。不要把它们列进 dependencies:一份物理副本可能绕过 Pi 在编译后 ESM 中的扩展模块映射,造成重复的类、注册表和初始化工作,而 Pi 在检测到这种配置时会报告一条扩展警告。

对于一个带打包 shell 脚本的技能,根本没有任何 Node 依赖。这是技能胜过扩展的一个特点。

收窄从包里加载的内容

设置里的对象形式过滤一个包的资源:

{
  "packages": [
    {
      "source": "npm:@example/team-review-tools",
      "skills": [],
      "prompts": ["prompts/review.md"],
      "extensions": ["extensions/*.ts", "!extensions/legacy.ts"]
    }
  ]
}

省略该属性就会加载这个包允许的一切;用 [] 则该类型一个都不加载。过滤器收窄的是包清单——它们不会暴露包没有声明的资源。

安装它

pi install npm:@example/team-review-tools@1.0.0
pi install git:github.com/example/pi-tools@v1
pi install ./local-package
pi -e npm:@example/pi-tools          # try it for one invocation
pi list

带版本号的 npm 规格说明会被锁定,git 标签和提交也是一样;包更新会调和检出内容,但不会移动一个已配置的 ref。相对的本地路径从包含它们的那个设置文件解析。

个人安装被写进 ~/.pi/agent/settings.json。加 --local 或 -l 可以把声明写进 .pi/settings.json,而 Pi 只在项目信任被授予之后才读它。

身份与重复加载

packages.md 解释了 Pi 如何识别一个包,好让同一个包不会加载两次:npm 包按包名识别,git 包按去掉 ref 的仓库 URL 识别,本地包按解析出的绝对路径识别。同一个包可以出现在个人设置和项目设置里;项目条目通常会替换个人条目,而加上 autoload: false 时它反而充当一个过滤性的增量。

已安装的包以各自独立的模块根加载。不要指望两个包共享同一个依赖实例。

这个一贯示例,在技能规模上完成

review-guard/ 现在在技能规模上完成了:一个简短的正文靠它的描述路由,一份清单和一份严重程度细则放在 references/ 里,外加一个在任何东西被报告之前运行仓库自身检查的脚本。

它仍然做不到的是拒绝。SKILL.md 可以说绝不运行 git push --force,而模型通常会照办——但没有任何东西强制它,因为文本是建议,只有运行在 Pi 进程内的代码才能阻止一次调用。第 15 章从那里开始。

运行了什么

examples/ch14-skill-files/ 检查关于打包文件的这些论断:

  • 技能的路径在提示词里,所以 SKILL.md 里的相对路径可以针对它的目录解析;
  • 一个打包的文件不在提示词里,并且只在模型用它自己的 read 工具读它时才到达上下文:references/checklist.md 里的一个标记一直不存在,直到脚本化的模型读了那个文件;
  • run-checks.sh 从它自己的位置解析仓库根:在一个不相关的目录下运行,路径上放一个替身的 pnpm,它在比 skills/ 高两级的地方运行了 pnpm;
  • set -euo pipefail 是一个失败的脚本和一个报告成功的脚本之间的区别:同一个失败行在有它时以非零状态退出,没有它时以零状态退出,而没有它时脚本仍然打印了它的最后一行。

最后一个结果是关于 Bash 的,不是关于 Pi 的,但它是本章给出那两行的理由,而它现在是已观察到的,而不是被断言的。