← Pi Agents

设置,以及配置来自哪里

Pi 会合并智能体目录与项目 .pi 两个设置文件:标量值被覆盖,资源列表取并集,而环境变量和命令行标志是按设置逐项记录的,并不是两个更高的层。

你改了 settings.json,运行 /reload,而设置没有生效。或者它生效了,但方式不是你能预料的。两者出于同一个原因:你在对着一个文件推理,而 Pi 合并的是好几个。

configuration.md 用一句话给出了轮廓。Pi 支持用户级与项目级配置。用户级配置住在智能体目录中,默认是 ~/.pi/agent。项目级配置住在工作目录下的 .pi 中,并在项目获得信任之后才加载——有一个例外:sessionDir,Pi 会在判定信任之前就读它,以便定位会话。

智能体目录

一切用户级的东西都在这里。PI_CODING_AGENT_DIR 可以搬走它,SDK 的 agentDir 选项也可以。

路径 负责什么
<agent-dir>/settings.json 设置、资源路径,以及 Pi 包的声明
<agent-dir>/keybindings.json 自定义终端 UI 与应用键位绑定
<agent-dir>/mcp.json 在所有项目中都可用的 MCP 服务器
<agent-dir>/models.json 兼容的端点、模型,以及模型覆盖
<agent-dir>/auth.json 保存的 API 密钥与 OAuth 凭据
<agent-dir>/AGENTS.override.md, AGENTS.md, AGENTS.MD, CLAUDE.md, CLAUDE.MD 跨工作目录生效的用户指令
<agent-dir>/SYSTEM.md 替换 Pi 的默认系统提示词
<agent-dir>/APPEND_SYSTEM.md 向 Pi 的系统提示词追加指令
<agent-dir>/extensions/, skills/, prompts/, themes/ 用户资源

注意,这些指令文件名与 SYSTEM.md 位于同一个目录里,但做的事不同。指令与系统提示词是两个独立的界面,第 18 章会把它们分开讲。

设置会合并,资源列表不会

settings.md 开篇就是那条让人意外的规则:项目设置覆盖智能体目录的设置,而资源列表会被合并。

标量设置遵循普通的覆盖规则。资源列表——extensions、skills、prompts、themes、packages——会取两级的并集,而过滤语法正是为此而生:

条目 含义
一个裸路径 加载它
+path 包含一条确切路径
-path 排除一条确切路径
!pattern 排除匹配的 glob

用一张图说明这条规则,连同那个行为不同的列表:

    flowchart TD
  K["一个你想改动的设置"] --> Q{"它是哪个键?"}
  Q -->|"标量"| S["项目的值胜出"]
  Q -->|"资源列表"| L["两个文件都加载,取并集"]
  L --> L2["少列一项不会移除任何东西"]
  L2 --> L3["移除必须是显式的"]
  Q -->|"defaultTools"| T["普通名称替换,+ 与 - 编辑"]
  

错误:“项目文件列出了它想要的资源,加载的就是这些。”

正确:两个文件的资源列表会取并集,所以项目文件并不能靠"不列出"来取消选择任何东西。要让某个东西不加载,你得用 -path 或 !pattern 点名它,而且是在列出它的那个文件里。项目文件里的过滤器,够不到用户文件列出的资源。

defaultTools 是那个不遵循并集规则的列表:普通名称替换,+name 和 -name 编辑。那次合并是第 6 章的主题,这里不重复。

路径按作用域不同而不同地解析:用户资源路径从智能体目录解析,项目资源路径从项目的 .pi 目录解析。绝对路径和 ~ 在两者中都可以用。

三个只存在于某一级的设置

settings.md 用粗体标出了这几个:

  • defaultProjectTrust——仅智能体目录设置。
  • httpProxy——仅智能体目录设置。
  • cacheWarming——仅全局设置。

一个试图设置 defaultProjectTrust 的项目文件并不是在叠加一层偏好;那里的这个设置会被忽略。当你指望某个仓库的 .pi 自行决定它的信任姿态时,这一点就重要了。

环境变量改变了什么

environment-variables.md 把 Pi 从环境里读取的东西分了组。其中只有一个会改变配置从哪里找:

变量 说明
PI_CODING_AGENT_DIR 覆盖配置目录;默认是 ~/.pi/agent
PI_CODING_AGENT_SESSION_DIR 覆盖会话存储;会被 --session-dir 覆盖
PI_PACKAGE_DIR 覆盖包目录,用于 Nix/Guix store 路径时很有用
PI_OFFLINE 禁用自动网络活动,包括模型目录刷新
PI_SKIP_VERSION_CHECK 禁用向 pi.dev 请求最新版本
PI_TELEMETRY 用 1/true/yes 或 0/false/no 覆盖安装/更新遥测
PI_CACHE_RETENTION 设为 long,在支持的地方延长 provider 提示词缓存
PI_SHARE_VIEWER_URL 覆盖 /share 使用的基 URL
PI_RADIUS_GATEWAY 覆盖 /bug 上传使用的 Radius gateway 源
VISUAL, EDITOR 当 externalEditor 未设置时的外部编辑器后备

--offline 是 PI_OFFLINE=1 的命令行等价物。无论哪种方式,环境变量都只对一个进程生效,这使它成为临时覆盖的正确工具,也成为任何你想保留下来的东西的错误工具:

PI_OFFLINE=1 pi --print "Summarize this repository"
PI_CODING_AGENT_DIR=/srv/pi pi --session-dir /srv/sessions

如果它需要持久化,就改用 settings.json。

三个文件,以及越过它们的覆盖项

文件顺序本身只有一句话长,而它的地板是内置默认值。.pi/settings.json 只有在项目获得信任之后才加入其中,那是第 8 章的内容。

环境变量和命令行选项并不是叠在上面的另外两层。它们是按设置逐项记录的,而且它们并不总是赢:

覆盖项 记录在何处
--session-dir PI_CODING_AGENT_SESSION_DIR 与 sessionDir 设置
--tools, --no-tools, --no-builtin-tools defaultTools,包括在重新加载时
--no-mcp extensions 配合 -builtin:mcp,只对一次运行有效,不是永久有效
--system-prompt 替换默认系统提示词
--append-system-prompt 向它追加,且可重复
--verbose quietStartup

当某项能力同时有设置和环境变量时,赢家是针对那项能力声明的,不是全局的:terminal-setup.md 说,在覆盖检测到的终端特性时,设置优先于环境变量。

与一个层栈的区别在于,它们没有什么普遍的东西需要记忆:只有少数几个具名设置,每一个都有它自己记录在案的覆盖项。sessionDir 是会让人栽跟头的那一个,因为 Pi 在授予信任之前就读它——这是下一章的内容。

一个可用的起始文件

{
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  },
  "defaultTools": ["+grep", "+find", "+ls"],
  "shellPath": "C:\\Program Files\\Git\\bin\\bash.exe",
  "shellCommandPrefix": "export CI=1",
  "retry": {
    "enabled": true,
    "maxRetries": 3
  },
  "extensions": ["+./extensions", "!./extensions/experimental.ts"],
  "defaultProjectTrust": "ask"
}

有两个条目值得一说。retry.provider.maxRetries 默认是 0,这是有意的,原因第 29 章会讲。而 defaultProjectTrust 属于智能体目录,不属于项目文件。

重新加载不是对称的

手动改完设置、键位、指令或资源后,运行 /reload。它对工具做不到的事,正是第 6 章的重载陷阱,同样的规则在这里也适用:如果一个改动看起来没有反应,先重启,再去调试它。

读设置,不要猜

/settings 会为常见偏好打开设置 UI。除此之外,settings.md 是参考资料,而 pi config 是资源检查器:packages.md 把它描述为列出已发现的资源和 Pi 的内置扩展,加上 --local 可以从项目覆盖项开始。

到目前为止,一切都假定了项目设置文件是 Pi 会读的文件之一。在一个问题得到回答之前,它并不是。第 8 章讲的就是那个问题,以及一个文件夹所提供的、无论怎样拒绝都关不掉的资源。

运行了什么

第 6 章和第 7 章共用 examples/ch07-settings/,它通过 Pi 自己的 SettingsManager 和 DefaultResourceLoader,在真实文件上跑这些合并规则:

  • 标量设置:项目的值胜出,而项目没有设置的嵌套键仍然来自用户文件;
  • 一个未获信任的项目的设置根本不会被读取,而事后授予信任会让项目层生效;
  • 在项目文件里设置的 defaultProjectTrust 会被忽略:智能体目录的值保持有效;
  • 两个文件的资源列表都会被加载,而在项目文件里少列一项不会移除任何东西。

它还发现了本章初稿没有写出的一个限制。**排除过滤器只在列出该资源的那个文件里生效。用户文件里的 !pattern 或 -path 会移除用户的技能。同一个过滤器放在项目文件里,试了三种方式,用户级技能仍然加载着,而项目过滤器确实移除了项目自己的条目。所以一个仓库无法通过在自己的 .pi/settings.json 里点名,来关掉你个人配置的东西。这是在 1.0.4 上观察到的,而 settings.md 对此两种说法都没有——它只说资源数组支持这些过滤器,以及 Pi 会加载两个文件里列出的资源。