配置与项目上下文

Pi Coding Agent 的配置决定程序行为，项目上下文则向模型说明约定与背景。二者可能都来自项目目录，但作用不同：JSON 设置由程序解析，指令正文进入模型上下文。

本文按 2026 年 9 月 18 日可查的官方资料说明；命令、配置和默认行为应结合所安装版本核对。

全局与项目设置

全局设置位于 ~/.pi/agent/settings.json，项目设置位于 .pi/settings.json。项目设置在适用且被信任加载时覆盖全局对应项；嵌套对象会合并。具体字段与规则见官方设置文档。

例如，全局配置启用上下文压缩，项目只调整压缩的保留预算，不代表必须把整个压缩对象重复一遍。某些选项只允许全局配置，不能简单假定所有字段都支持项目覆盖。

启动参数可为一次运行指定模型、工具或资源，但不宜把所有选项概括为同一套优先级。模型恢复、资源发现和设置覆盖有各自规则；排查时应核对对应参数和实际会话状态。

项目指令与系统提示

按照使用文档，Pi 会从全局、父目录和当前目录加载约定文件。一个目录含有 AGENTS.override.md 时，它替代该目录的 AGENTS.md 或 CLAUDE.md；其他目录的上下文仍可叠加。

项目的 .pi/SYSTEM.md 用于替换默认系统提示，APPEND_SYSTEM.md 用于追加内容。替换与追加影响不同，应先确认是否真的要改变默认提示。

例如，“测试命令是某个脚本”适合写进项目指令；“主题使用浅色”属于程序配置；“这个任务仅分析不修改”则是本次任务约束。把三者混在同一个配置文件里，不会自动得到预期效果。

资源加载与按需读取

扩展、Skills、提示模板和主题可以来自全局目录、项目目录或 Packages。项目本地资源是否加载，还受项目信任控制。

Skills 的名称和描述用于发现，完整操作说明按需读取。项目存在一个 Skill 文件，并不意味着每次模型请求都包含全部正文。具体过程见Skills 文档。

配置没有生效时

建议依次确认：

1. 当前工作目录是不是预期项目。
2. 修改的是全局设置还是项目设置。
3. 项目资源是否被允许加载。
4. 启动参数或恢复的会话状态是否影响结果。
5. 对应资源是否需要重载或重新启动。

/reload 可以重载多类资源与上下文文件，但不应把它理解为重建所有运行状态。涉及信任决策等特定设置时，应遵循该设置的生效说明。

配置合并示例

假设全局设置为：

{
  "theme": "dark",
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384
  }
}

项目的 .pi/settings.json 只包含：

{
  "compaction": {
    "reserveTokens": 8192
  }
}

在项目设置被信任并加载后，嵌套对象会合并：主题仍为 dark，自动压缩仍启用，reserveTokens 变为 8192。这个例子来自官方项目覆盖说明，用于展示对象合并，不代表该数值适合所有模型。

数组和具体资源字段可能有自己的筛选、排除或去重规则，不能从对象合并例子推断所有设置都按同一种方式处理。

启动时可以观察什么

交互界面的启动区域会列出已加载的上下文文件、提示模板、Skills 和 Extensions。底部还会显示工作目录、当前模型及上下文用量等信息。它们是排查“当前运行到底加载了什么”的第一手线索。

例如，项目 Skill 没有出现时，应先确认启动目录和项目信任；模型不符合预期时，应查看当前模型，而不是只检查全局设置文件。

重载、重启与新会话

项目信任通过 /trust 保存后，官方说明要求重启 Pi 才能使当前会话按新的信任决策重新加载项目资源。不同配置项可能即时生效、下次请求生效或下次启动生效，应以相应设置文档为准。

一个排查例子

如果全局 Extension 在交互模式出现，而同一项目的非交互脚本没有加载项目 Extension，可以按以下顺序检查：

1. 脚本启动时的工作目录；
2. 项目中是否存在正确的资源路径；
3. 非交互模式采用的项目信任策略；
4. 命令行是否通过 --no-extensions 等参数禁用了资源；
5. 启动输出或结构化事件中是否报告加载错误。

配置文件存在只是候选输入，实际加载状态才决定本次运行行为。