配置 —— 三层文件,一道信任闸门
npm install -g @earendil-works/pi-coding-agent 跑完,pi 能启动,然后呢?
多数人的第一反应是去翻配置——结果发现根本没有 pi.config.yaml,也没有 --flag 清单能覆盖的
那几十个开关。Pi 的配置就是目录里的几个文件,settings.json 只是其中最小的一个。
这一章只做一件事:把「改哪个文件、什么时候生效、谁挡住你」三件事钉死。 偏差配置是最贵的 bug——它不报错,只是让你以为 Pi 不听话。
三个问题:
- 一个设置项到底从哪来?用户层、项目层、命令行,谁压谁?
defaultTools写["+codemode"]和写["codemode"]差在哪?- 项目里的
.pi/为什么有时候完全不生效,而且不报错?
~/.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:
pi --versionpi listpi --list-models本机(v1.4.0 / Windows 24H2)实跑的前两行输出:
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-chromepi list 只报包,不报散装扩展。这一点后面 §四 会再回来:你往
~/.pi/agent/extensions/ 里丢十个 .ts,pi list 一个都不显示,但它们确实在跑。
第三个命令要配 PI_OFFLINE=1,否则会先去网上刷模型目录:
$env:PI_OFFLINE="1"; pi --list-modelsprovider 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 还有对象形式,能按资源类型过滤:
{ "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:看默认工具集到底是谁定的。
$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:
export default function (pi) { pi.on("session_start", (event) => { console.log("[hello] reason=" + event.reason); });}然后不传 -e 直接跑:
pi -p "reply with the single word: ok" --no-tools本机输出(ok 是模型回答,[hello] 是扩展打的):
ok[hello] reason=startup删除该文件后再跑一次,第二行消失。自动发现只需要放进目录,不需要写进 settings.json。
实验 3:让 Pi 报出「路径不存在」的错。
pi -e ./tmp-pif/probe.ts -p "hi" --no-toolsError: 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 从默认改成:
"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 怎么改内置模型而不用替换它的整个列表。