Pi Agent 源码级教程
F01

配置 —— 三层文件,一道信任闸门

2,418 字 · 含 50 行代码 · 约 20 分钟

npm install -g @earendil-works/pi-coding-agent 跑完,pi 能启动,然后呢? 多数人的第一反应是去翻配置——结果发现根本没有 pi.config.yaml,也没有 --flag 清单能覆盖的 那几十个开关。Pi 的配置就是目录里的几个文件,settings.json 只是其中最小的一个。

这一章只做一件事:把「改哪个文件、什么时候生效、谁挡住你」三件事钉死。 偏差配置是最贵的 bug——它不报错,只是让你以为 Pi 不听话。

三个问题:

  1. 一个设置项到底从哪来?用户层、项目层、命令行,谁压谁?
  2. defaultTools 写 ["+codemode"] 和写 ["codemode"] 差在哪?
  3. 项目里的 .pi/ 为什么有时候完全不生效,而且不报错?
text
  ~/.pi/agent/            项目 .pi/  ├─ settings.json         ├─ settings.json      <-- 需要信任  ├─ models.json           ├─ mcp.json  ├─ auth.json             ├─ extensions/  ├─ mcp.json              ├─ skills/  ├─ trust.json  ----->    └─ prompts/  ├─ AGENTS.md   (不需要信任,任何目录都加载)  └─ extensions/        |                        |        +--------+---------------+                 v        deepMergeSettings(global, project)     core/settings-manager.ts:143                 v        deepMergeSettings(merged, overrides)   命令行/SDK                 v        resolveDefaultTools()                  core/settings-manager.ts:137

一、本章终点:先跑起来

三个命令就能看到全部真相,都不需要 API key:

powershell
pi --versionpi listpi --list-models

本机(v1.4.0 / Windows 24H2)实跑的前两行输出:

text
1.4.0User packages:  npm:pi-web-access    C:\Users\luhui2\.pi\agent\npm\node_modules\pi-web-access  npm:pi-chrome    C:\Users\luhui2\.pi\agent\npm\node_modules\pi-chrome

pi list 只报包,不报散装扩展。这一点后面 §四 会再回来:你往 ~/.pi/agent/extensions/ 里丢十个 .ts,pi list 一个都不显示,但它们确实在跑。

第三个命令要配 PI_OFFLINE=1,否则会先去网上刷模型目录:

powershell
$env:PI_OFFLINE="1"; pi --list-models
text
provider        model                       context  max-out  thinking  imagesfunagent        funagent-default            128K     16.4K    no        nofunagent-local  funagent-default            128K     16.4K    no        nosvw             doubao                      262.1K   32.8K    no        novolcengine      deepseek-v4-1-flash-260910  262.1K   32.8K    no        no

这四行全部来自 models.json,不是 Pi 内置目录——它们长得就不像内置模型名。 F02 讲怎么造这样的条目。


二、agent 目录:13 个位置,各管一件事

用户级配置全在 <agent-dir>,默认 ~/.pi/agent,可用 PI_CODING_AGENT_DIR 或 SDK 的 agentDir 改(environment-variables.md 的 Pi Process Configuration 表)。

路径 谁读它 改完怎么生效
settings.json SettingsManager /reload,或重启
models.json ModelConfig 打开 /model 时重读(models.md:67)
auth.json AuthStorage 立即;/login /logout 写它
mcp.json MCP 扩展 /reload
keybindings.json 交互模式 /reload
AGENTS.md 等 5 个名字 loadProjectContextFiles /reload
SYSTEM.md / APPEND_SYSTEM.md 系统提示词装配 /reload
extensions/ discoverAndLoadExtensions /reload
skills/ prompts/ themes/ 资源加载器 /reload
trust.json TrustManager 立即
sessions/ SessionManager —
npm/ tmp/ bin/ 包与 -e 缓存 自动

AGENTS.md 那一行要特别注意:它不属于项目配置。配置文档把 「Context files」单列一节,原话是 Context-file discovery does not require project trust(configuration.md:47)。也就是说,你 clone 一个陌生仓库、拒绝信任它, .pi/ 里的一切都被跳过,只有 AGENTS.md 照样进系统提示词。

这不是漏洞,是设计:同目录下 AGENTS.override.md 优先于 AGENTS.md, AGENTS.md 又优先于 CLAUDE.md(resource-loader.ts:213 那五个候选名)。 覆盖链只影响同目录,不会屏蔽上层的文件(configuration.md:45)。 三十章之后 F04 会把这五个名字的探索顺序完整走一遍。

三层的关系一句话:用户层是基线,项目层覆盖它,命令行和 SDK 再覆盖合并结果。


三、合并规则:深合并,数组例外

三条设置文件都是 JSON,但合并不是 Object.assign。三个函数决定了一切, 都在 settings-manager.ts 的前 150 行里:

行 函数 一句话
:61-63 isMergeableObject 对象算可合并,数组不算
:65-82 deepMergeObjects 递归合并,叶子取覆盖值
:143-147 deepMergeSettings 先深合并,再把 defaultTools 单独接回

deepMergeObjects 的循环体只有一句判断:两边都是对象就递归,否则用覆盖值。 isMergeableObject 里那个 !Array.isArray(value) 排除了数组—— 所以你在项目里写 "compaction": { "enabled": false },用户的 reserveTokens 会保留;但你写 "packages": [],用户的包声明就全没了。

defaultTools 是唯一的例外:deepMergeSettings 先深合并其它所有键, 最后单独把 defaultTools 拿出来交给 mergeDefaultTools(:145-146)。 两个函数一共八行,逻辑可直接摊成一张表(:126-140):

输入 内部动作 结果
覆盖值为 undefined 直接返回 base 继承
任一侧不是数组 返回覆盖值 替换
覆盖值里有普通名 返回覆盖值 整套替换
覆盖值全是 +/- [...base, ...overrides] 拼起来 叠加

拼接完还有一道 resolveDefaultTools:先挑出普通名(plain), 如果 plain 非空、或者整个列表就是空数组,就把它当基准; 否则拿 DEFAULT_TOOL_NAMES 当基准;最后把 +/- 逐条应用上去。

拆开读,四句话:

写在项目层的一串 +name 是「叠加」,不是「替换」。 覆盖值全是模组时直接拼接,所以用户层加的工具不会被项目层冲掉。

写了普通名字就是「整套替换」。 plain.length > 0 时基准变成 plain, 默认的那四个工具一起消失。

只有 +/- 时基准是默认四件套。 DEFAULT_TOOL_NAMES 就是 ["read", "bash", "edit", "write"](:85)。

+ / - 按顺序生效。 applyToolModifiers 从头扫到尾(:110-120), 重复 + 不会加两次,删一个不存在的名字也不报错。

你写的 最终工具集
不写 defaultTools read bash edit write
["+codemode"] 四件套 + codemode
["+codemode", "-write"] read bash edit codemode
["read", "grep"] 只有 read grep
["read", "+grep"] 非法:普通名与 + 混用(getToolListError,:97-104)
["+code*"] 非法:+/- 只收精确名,不支持 *

最后两行不是合并规则,是校验规则:getToolListError 只检查 「模组里有没有普通名」和「模组里有没有 *」。但注意注释 「Settings files are not validated」——settings.json 里的非法组合不会在启动时拦你, 命令行 --tools 才会立刻报错。


四、信任闸门:它挡的是什么,不挡什么

.pi/settings.json 写好了,pi 一启动却毫无反应——多半是信任没给。 判定写在 resolveProjectTrusted 里,一共五道卡,从上往下问:

顺序 行 依据 命中结果
1 :48-50 --approve / --no-approve 直接用命令行的布尔值
2 :51-53 目录里没有需要信任的资源 查 trust.json,无记录就算真
3 :55-71 扩展的 project_trust 事件 第一个回答 yes/no 的说了算
4 :73-76 trust.json 里的旧决定 直接返回那个布尔值
5 :78-96 defaultProjectTrust 设置 → 弹窗 always 真 / never 假 / ask 问人

第五道自己是两段的:先看设置项三选一,ask 才往下走; hasUI 为假就在 :87-89 直接 return false,有 UI 才弹窗让人选, 并且只有在选了「记住」时才写回 trust.json。

三个必须记住的后果:

目录里没有任何「需要信任」的资源,直接算可信。 hasTrustRequiringProjectResources 为假时 ?? true——空 .pi 目录不拦你 (security.md:45 也是这么写的)。

ask + 没有 UI = 拒绝。 :87-89 那三行是「非交互模式」的全部命运: hasUI 为假就直接 return false。 -p / --mode json / --mode rpc 全在这里静默跳过项目配置。 CI 里跑 Pi 却「项目配置不生效」,八成是这里。

它挡的是加载,不是运行。 官方说得很直白:project trust does not limit what tool calls can access(security.md:33)。 信任闸门只管「启动时要不要读 .pi/ 里的东西」,读完之后工具照样以你的身份跑。 唯一漏网的读是 sessionDir——它在信任之前就被读了,好让 Pi 知道会话存哪(configuration.md:3)。

defaultProjectTrust 只能写在用户层(settings-schema.ts:271-274 标了 Global setting only),默认值 "ask"(settings-defaults.ts:30)。 trust.json 里存的是逐目录的布尔决定,用 /trust 或弹窗写入。

4.1 同一个目录,三种活法

启动方式 .pi/ 是否加载 原因
pi(终端) 首次问,记住后自动 ask + 有 UI
pi -a 是 --approve 直接盖过一切
pi -p "..." 否(除非已记住或 always) ask + 无 UI
pi -p -a "..." 是 命令行覆盖优先于 defaultProjectTrust
defaultProjectTrust: "always" 后 pi -p 是 设置项直接返回 true

Windows 上注意:pi 走的是 pi.ps1 包装脚本,多行输出会被 PowerShell 当成错误流染色。判断「到底跑没跑」看第一行有没有打出来,别被红字吓到。


五、资源路径:想让 Pi 读别处的文件

settings.json 里还有五类资源声明,都能写绝对路径或相对路径:

键 收什么 出现在
packages npm: / git: / URL / 本地目录 pi list
extensions .ts / .js / 目录 / builtin:<name> 启动横幅
skills 目录(递归找 SKILL.md) 系统提示词的 <available_skills>
prompts .md / 菜单
themes .json /settings → Theme

相对路径相对声明它的那个文件解析(packages.md:44)。 这条看着琐碎,实际是团队协作里最常见的坑:.pi/settings.json 里写 "../shared/skills",人人在自己机器上都对,一进容器就全崩—— 因为容器里 cwd 变了,.pi/settings.json 的位置没变,但 ../shared 指向别处了。

packages 还有对象形式,能按资源类型过滤:

json
{  "packages": [    { "source": "npm:@acme/pi-tools", "skills": false, "themes": false }  ]}

settings-schema.ts:175-182 定义的字段是 source / autoload / extensions / skills / prompts / themes。设成 false 的那类资源不加载, 但包本身仍然装着——适合「只要它的工具,不要它的提示词」这种场景。


六、自己动手验证

环境:v1.4.0 / node v24.12.0 / Windows 24H2。下面三个实验都在本机跑过。

实验 1:看默认工具集到底是谁定的。

powershell
$env:PI_OFFLINE="1"; pi -p "hi" --tools read,grep --no-tools

加上 --no-tools 之后 read,grep 仍然生效——命令行工具选择是最后叠加的, 它盖过 defaultTools,也盖过 -nt。想确认「先 -nt 再 --tools」的优先级, 看 cli.md:119-128:-xt 在「所有其它选择选项之后」才起作用。

实验 2:把一个扩展放进全局目录,看它有没有被自动发现。

把下面这个 12 行文件存成 ~/.pi/agent/extensions/zz-book-hello.ts:

ts
export default function (pi) {  pi.on("session_start", (event) => {    console.log("[hello] reason=" + event.reason);  });}

然后不传 -e 直接跑:

powershell
pi -p "reply with the single word: ok" --no-tools

本机输出(ok 是模型回答,[hello] 是扩展打的):

text
ok[hello] reason=startup

删除该文件后再跑一次,第二行消失。自动发现只需要放进目录,不需要写进 settings.json。

实验 3:让 Pi 报出「路径不存在」的错。

powershell
pi -e ./tmp-pif/probe.ts -p "hi" --no-tools
text
Error: Failed to load extension "...\tmp-pif\probe.ts":Extension path does not exist: ...\tmp-pif\probe.tsHint: Start without extensions using "pi -ne".

这条提示 pi -ne 是逃生舱:扩展写坏了导致 Pi 起不来时,用它绕过全部扩展启动一次, 进去把文件删掉。

改一处试试

把 ~/.pi/agent/settings.json 的 defaultTools 从默认改成:

json
"defaultTools": ["+codemode", "-write"]

预期:pi 启动后模型看得到 codemode,看不到 write;read bash edit 仍在。 连带影响:codemode 会把「可调用工具」列进自己的描述,系统提示词的 Available tools 段会变长。回滚:删掉这个键即可,不要写成 [] ——空数组 [] 会一路走到 entries.length === 0 分支,等于「回到默认四件套」, 看着像生效了其实什么都没改。


七、工程暗坑

坑一:"defaultTools": [] 不等于「关掉所有工具」。 resolveDefaultTools 里 entries.length === 0 走的是 DEFAULT_TOOL_NAMES。 真要全关,用命令行 -nt,或者 + / - 逐个减。

坑二:项目层写了普通名字,用户层加的东西全丢。 mergeDefaultTools 只在 overrides 全是模组时叠加。项目里写 ["read", "bash"],你在用户层辛苦加的 +codemode 就没了。 想只减不加,写 ["-write"]。

坑三:pi list 看不到散装扩展。 它只列 settings.json 里的 packages。全局 extensions/ 目录里的文件 靠目录扫描发现(loader.ts:832-880),pi list 不参与。想确认某个扩展有没有加载, 在它里面打一行日志,或者看启动横幅的 Extensions 列表。

坑四:models.json 改了不生效,因为进程没重读。 它只在打开 /model 时重读(models.md:67)。/reload 不重读它; 改完最稳的是重启,或在交互模式里开一次 /model 再取消。

坑五:数组整体替换。 项目里想「追加一个包」,把用户层的包抄一遍再往后加; 写 "packages": ["npm:new-one"] 会把用户层的两个包全冲掉。


八、本章源码索引

文件 行数 本章用到的位置
packages/coding-agent/src/core/settings-manager.ts 1,457 deepMergeObjects / mergeDefaultTools / resolveDefaultTools
packages/coding-agent/src/core/settings-defaults.ts 68 全部默认值(defaultProjectTrust: "ask")
packages/coding-agent/src/core/settings-schema.ts 495 每一层能写哪些键
packages/coding-agent/src/core/project-trust.ts 98 resolveProjectTrusted 五级判定
packages/coding-agent/src/core/resource-loader.ts 1,320 上下文文件发现、SYSTEM.md / APPEND_SYSTEM.md
packages/coding-agent/src/core/extensions/loader.ts 881 目录扫描规则(只下一层)
packages/coding-agent/docs/configuration.md 48 13 个位置的责任表
packages/coding-agent/docs/security.md 99 信任闸门「不挡什么」

九、下一章

配置层的框架搭好了,但四条 --list-models 里的模型还没醒——因为没有 key。 下一章 F02 拆 models.json 与 auth.json:凭据五级优先级、 兼容端点怎么接本地模型、modelOverrides 怎么改内置模型而不用替换它的整个列表。