pi 设置系统完全指南：两级 JSON 配置、项目信任与全部参数详解

本文基于 pi coding agent 官方文档 settings.md，系统讲解 pi 的两级 JSON 配置体系（全局 ~/.pi/agent/settings.json 与项目级 .pi/settings.json）、项目信任（Project Trust）安全机制，以及模型/思考、压缩、重试、资源加载等全部设置项的类型、默认值与配置示例，并结合 settings-manager.ts 与 trust-manager.ts 的源码实现说明合并规则、迁移逻辑与落盘行为，帮助你在实际使用中正确配置、排查和定制 pi。

设置文件位置与两级配置体系

pi 使用 JSON 设置文件，项目设置覆盖全局设置：

位置	作用域
~/.pi/agent/settings.json	全局（所有项目）
.pi/settings.json	项目（当前目录）

可以直接编辑文件，也可以在交互模式下使用 /settings 修改常用选项。保存启动默认模型的方式是在 /model 中选择目标模型后按 Ctrl+S；保存启动思考级别则在 /thinking 中按 Ctrl+S。

从源码结构看，这两条路径的生成逻辑位于 config.ts：配置目录名 CONFIG_DIR_NAME 默认为 .pi，getAgentDir() 返回 ~/.pi/agent，全局设置文件即该目录下的 settings.json。FileSettingsStorage 负责读写两个文件，并在写入前通过 proper-lockfile 加锁（遇到 ELOCKED 会重试最多 10 次），避免多进程并发写坏配置文件。

合并规则：嵌套对象递归合并，其余字段直接覆盖

deepMergeSettings 实现了文档中描述的合并语义：

• 两个值都是普通对象时递归合并（如 compaction、retry、terminal）；
• 其他情况（标量、数组）项目值整体覆盖（如 theme、enabledModels、defaultTools 数组不会被拼接）。

// ~/.pi/agent/settings.json (global)
{
  "theme": "dark",
  "compaction": { "enabled": true, "reserveTokens": 16384 }
}

// .pi/settings.json (project)
{
  "compaction": { "reserveTokens": 8192 }
}

// 合并结果
{
  "theme": "dark",
  "compaction": { "enabled": true, "reserveTokens": 8192 }
}

这意味着项目里只需写差异字段：全局的 compaction.enabled 保留为 true，而 reserveTokens 被项目的 8192 覆盖。注意 defaultTools 这类数组是整体替换而非合并——项目中的 defaultTools 数组会完全替代全局数组。

旧格式自动迁移

migrateSettings 在加载配置时自动将旧版字段迁移到新格式，升级旧版 pi 的用户无需手工改文件：

• queueMode → steeringMode；
• 布尔值 websockets → transport（true 变 "websocket"，false 变 "sse"）；
• 旧的对象形式 skills: { enableSkillCommands, customDirectories } → 扁平的 enableSkillCommands + 数组形式的 skills；
• retry.maxDelayMs → retry.provider.maxRetryDelayMs。

落盘只写“本会话改过的字段”

SettingsManager 会用 modifiedFields/modifiedNestedFields 追踪本次会话中被修改过的字段，保存时只把这些字段合并回文件其余内容（persistScopedSettings）。这保证了：你用 /settings 改主题时，不会覆盖掉别人在文件里手工添加的其他键。该行为由 settings-manager.test.ts 中 “preserves externally added settings” 等用例验证。

项目信任（Project Trust）

在交互模式下启动时，如果项目目录包含项目本地设置、资源或 .agents/skills，且 ~/.pi/agent/trust.json 中没有该目录或其任一父目录的已保存决定，pi 会先询问你是否信任该项目。信任项目后，pi 才会加载 .pi/settings.json 与 .pi 下的资源、安装缺失的项目包、执行项目扩展。

trust-manager.ts 定义了哪些资源会触发信任检查：.pi 下的 settings.json、extensions、skills、prompts、themes、SYSTEM.md、APPEND_SYSTEM.md。findNearestTrustEntry 从当前目录逐级向上查找最近的信任记录，这正是“父目录决定也生效”的实现；信任记录文件路径由 trust-manager.ts#L213 确认为 ~/.pi/agent/trust.json。

非交互模式（-p、--mode json、--mode rpc）不显示信任提示，转而读取全局设置中的 defaultProjectTrust：

• "ask"（默认）与 "never"：没有可应用的已保存信任决定时，忽略上述项目资源；
• "always"：直接信任。

单次运行可用 --approve/-a 或 --no-approve/-na 覆盖一次的项目信任决定。pi config 与包管理命令走同样的信任流程，但 pi update 从不提示；对单个命令可用 --approve/--no-approve 信任或忽略项目本地设置。

在交互模式中使用 /trust 可以为当前项目（或立即的父目录）保存信任决定供后续会话使用。它只写 ~/.pi/agent/trust.json，不会重载当前会话，需要重启 pi 才生效。

信任状态还直接约束设置的读写：loadFromStorage 中，当 projectTrusted 为 false 时项目设置直接返回空对象；assertProjectTrustedForWrite 则让任何“写入项目设置”的操作在未信任时抛出 “Project is not trusted; refusing to write project settings”。

全部设置项

模型与思考

设置	类型	默认值	说明
defaultProvider	string	-	启动时的 provider（如 "anthropic"、"openai"；可在 /model 中按 Ctrl+S 保存，或手工编辑）
defaultModel	string	-	启动时的模型 ID（/model 中 Ctrl+S 保存，或手工编辑）
defaultThinkingLevel	string	-	启动时的思考级别（/thinking 中 Ctrl+S 保存）："off"、"minimal"、"low"、"medium"、"high"、"xhigh"、"max"
modelThinkingLevels	object	-	按 "provider/modelId" 为键的每模型启动思考级别；可从 /settings → Default thinking level per model 配置或手工编辑
hideThinkingBlock	boolean	false	在输出中隐藏思考块
showCacheMissNotices	boolean	false	在转写中提示显著的 prompt cache 未命中及压缩/分支摘要的开销
thinkingBudgets	object	-	每个思考级别的自定义 token 预算。Anthropic、Google 与 Bedrock 原生使用；OpenAI 兼容模型在设置了 compat.thinkingTokenBudgetField（或 supportsThinkingTokenBudget）时生效

thinkingBudgets 示例：

{
  "thinkingBudgets": {
    "minimal": 1024,
    "low": 4096,
    "medium": 10240,
    "high": 32768
  }
}

Settings 接口 中 modelThinkingLevels 的注释与文档一致：以 "provider/modelId" 为键覆盖每个模型的默认思考级别；getModelThinkingLevel 按 ${provider}/${modelId} 拼接键来查找，说明键格式是严格的 provider/modelId 两段式。

UI 与显示

设置	类型	默认值	说明
theme	string	"dark"	主题名（"dark"、"light" 或自定义）
externalEditor	string	依次回退 $VISUAL、$EDITOR，Windows 上 Notepad，其他平台 nano	Ctrl+G 外部编辑器命令，优先于环境变量
quietStartup	boolean	false	隐藏启动页头
defaultProjectTrust	string	"ask"	项目信任兜底行为："ask"、"always" 或 "never"。仅全局设置生效
collapseChangelog	boolean	false	更新后显示精简版更新日志
enableInstallTelemetry	boolean	true	首次安装或检测到更新后发送匿名安装/更新版本 ping；该开关不控制更新检查
enableAnalytics	boolean	false	选入（opt-in）的统计数据共享。目前仅实验性首次设置（PI_EXPERIMENTAL=1）时会询问
trackingId	string	-	统计跟踪标识，在开启 enableAnalytics 时生成
doubleEscapeAction	string	"tree"	双击 Esc 的动作："tree"、"fork" 或 "none"
treeFilterMode	string	"default"	/tree 的默认过滤："default"、"no-tools"、"user-only"、"labeled-only"、"all"
editorPaddingX	number	0	输入编辑器水平内边距（0-3）
outputPad	number	1	用户消息、助手消息与思考内容的水平内边距（0 或 1）
autocompleteMaxVisible	number	5	自动补全下拉框最大可见项数（3-20）
showHardwareCursor	boolean	false	显示终端硬件光标（TUI 仍会定位它以支持 IME）
tuiMode	string	"regular"	交互 TUI 模式："regular" 或实验性 "fullscreen"；/settings 修改立即生效；--tui-mode 在启动时覆盖此设置
fullscreenExitOutput	string	"transcript"	全屏退出时的输出："transcript" 打印最终转写与恢复提示；"resume-hint" 恢复之前的屏幕并只打印恢复提示。常规 TUI 模式无效
fullscreenScrollbar	string	"auto"	全屏转写滚动条："auto" 滚动时短暂显示；"always" 常驻最右列；"hidden" 隐藏。常规 TUI 模式无效
fullscreenCopyOnSelect	boolean	true	全屏模式下选中即自动复制。禁用后选区保持高亮，Ctrl+X 复制当前选区

VS Code 用户应加 --wait，让 pi 在编辑器退出后恢复：

{
  "externalEditor": "code --wait"
}

以上默认值与取值范围均可在源码中一一验证：getExternalEditorCommand 体现了 $VISUAL → $EDITOR → notepad/nano 的回退链；setEditorPaddingX 将取值钳制在 0-3；getOutputPad 只接受 0/1；setAutocompleteMaxVisible 钳制在 3-20；getDoubleEscapeAction 与 getTreeFilterMode 给出各自的合法枚举与默认值。enableAnalytics 开启时，setEnableAnalytics 会在首次选入时生成 trackingId（randomUUID）。

遥测与更新检查

enableInstallTelemetry 只控制发往 https://pi.dev/api/report-install 的匿名安装/更新 ping。关闭遥测不会禁用更新检查：pi 仍会请求 https://pi.dev/api/latest-version 查询最新版本。

• 设置 PI_SKIP_VERSION_CHECK=1 可禁用 pi 版本更新检查；
• 使用 --offline 或 PI_OFFLINE=1 可禁用此处描述的所有启动期网络操作，包括更新检查、包更新检查和安装/更新遥测。

main.ts#L564 中 --offline 与 PI_OFFLINE 的判断互等，args.ts 的帮助文本也确认二者语义相同。

网络

设置	类型	默认值	说明
httpProxy	string	-	作为 HTTP_PROXY 和 HTTPS_PROXY 应用的 HTTP 代理 URL。仅全局设置生效

{
  "httpProxy": "http://127.0.0.1:7890"
}

警告

设置	类型	默认值	说明
warnings.anthropicExtraUsage	boolean	true	当 Anthropic 订阅认证可能使用付费额外用量时显示警告

{
  "warnings": {
    "anthropicExtraUsage": false
  }
}

上下文压缩（Compaction）

设置	类型	默认值	说明
compaction.enabled	boolean	true	启用自动压缩
compaction.reserveTokens	number	16384	为 LLM 响应预留的 token 数
compaction.keepRecentTokens	number	20000	保留（不摘要）的近期 token 数

{
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  }
}

CompactionSettings 的注释与三个 getter（getCompactionEnabled）共同确认了 16384/20000 的默认值。压缩机制本身的细节可参见 compaction.md。

分支摘要（Branch Summary）

设置	类型	默认值	说明
branchSummary.reserveTokens	number	16384	分支摘要预留的 token 数
branchSummary.skipPrompt	boolean	false	/tree 导航时跳过 “Summarize branch?” 提示（默认不摘要）

重试（Retry）

设置	类型	默认值	说明
retry.enabled	boolean	true	瞬时错误时启用 agent 级自动重试
retry.maxRetries	number	3	agent 级最大重试次数
retry.baseDelayMs	number	2000	agent 级指数退避基础延迟（2s、4s、8s）
retry.provider.timeoutMs	number	SDK 默认	provider/SDK 请求超时（毫秒）
retry.provider.maxRetries	number	0	provider/SDK 重试次数
retry.provider.maxRetryDelayMs	number	60000	接受的服务端请求重试延迟上限（60s）

当 provider 请求的重试延迟超过 retry.provider.maxRetryDelayMs 时，请求立即失败并给出信息明确的错误，而不是静默等待；设为 0 可取消该限制。

除非明确需要 provider 级重试，建议保持 retry.provider.maxRetries 为 0：设为大于 0 会让 SDK/provider 重试在 pi 感知到之前先处理“超出用量限制”类错误，某些情况下可能让 agent 一直阻塞到 provider 配额恢复。

{
  "retry": {
    "enabled": true,
    "maxRetries": 3,
    "baseDelayMs": 2000,
    "provider": {
      "timeoutMs": 3600000,
      "maxRetries": 0,
      "maxRetryDelayMs": 60000
    }
  }
}

默认值来源：RetrySettings 注释与 getProviderRetrySettings 中 ?? 60000 的兜底。

消息投递（Message Delivery）

设置	类型	默认值	说明
steeringMode	string	"one-at-a-time"	steering 消息的发送方式："all" 或 "one-at-a-time"
followUpMode	string	"one-at-a-time"	follow-up 消息的发送方式："all" 或 "one-at-a-time"
transport	string	"auto"	支持多传输方式的 provider 首选传输："sse"、"websocket"、"websocket-cached" 或 "auto"
httpIdleTimeoutMs	number	300000	HTTP 头/体空闲超时（毫秒），也用于显式流空闲超时的 provider；设 0 禁用
websocketConnectTimeoutMs	number	15000	支持 WebSocket 传输的 provider 的连接/握手超时（毫秒）；设 0 禁用

注意 queueMode 是旧字段名，加载时会自动迁移为 steeringMode（见上文迁移小节）。

终端与图像

设置	类型	默认值	说明
terminal.showImages	boolean	true	终端中显示图像（若终端支持）
terminal.imageWidthCells	number	60	内联图像期望宽度（终端单元格）
terminal.clearOnShrink	boolean	false	内容变短时清空空行（可能引起闪烁）
terminal.hyperlinks	boolean 或 "auto"	"auto"	覆盖 OSC 8 超链接支持（高级，仅 JSON 可设）
terminal.images	string 或 boolean	"auto"	用 "kitty"、"iterm2"、false 或 "auto" 覆盖图像协议支持（高级，仅 JSON 可设）
terminal.trueColor	boolean 或 "auto"	"auto"	覆盖真彩色支持（高级，仅 JSON 可设）
images.autoResize	boolean	true	将图像缩放到最大 2000x2000。作用于 @file 附件、read 以及工具返回的图像
images.blockImages	boolean	false	阻止所有图像发送给 LLM

getTerminalCapabilityOverrides 展示了 hyperlinks/images/trueColor 覆盖项如何被翻译成终端能力参数："kitty"/"iterm2" 直接映射，false 映射为 images: null；"auto" 则不覆盖，走自动检测。terminal.clearOnShrink 还支持 PI_CLEAR_ON_SHRINK=1 环境变量作为无设置时的回退（getClearOnShrink）。

Shell

设置	类型	默认值	说明
shellPath	string	-	自定义 shell 路径（如 Windows 上的 Cygwin）；前导 ~ 展开为用户主目录
shellCommandPrefix	string	-	每条 bash 命令的前缀（如 "shopt -s expand_aliases"）
npmCommand	string[]	-	npm 包查询/安装操作使用的命令 argv（如 ["mise", "exec", "node@20", "--", "npm"]）

JSON 中的 Windows 路径必须使用正斜杠或转义反斜杠：

{
  "shellPath": "C:/Program Files/Git/bin/bash.exe"
}

{
  "shellPath": "C:\\Program Files\\Git\\bin\\bash.exe"
}

{
  "npmCommand": ["mise", "exec", "node@20", "--", "npm"]
}

npmCommand 用于所有 npm 包管理操作，包括安装、卸载和 git 包内部依赖安装。用户作用域的 npm 包安装到 ~/.pi/agent/npm/，项目作用域的 npm 包安装到 .pi/npm/。argv 条目应写成进程实际启动的形式。配置了 npmCommand 后，git 包的依赖安装使用普通 install，以避免在包装器或替代包管理器中引入 npm 专属参数。

工具（Tools）

设置	类型	默认值	说明
defaultTools	string[]	-	初始启用的内置工具；省略时使用 pi 的标准默认集合

defaultTools 选择启动时启用的内置工具；扩展与 SDK 自定义工具始终保留。可用内置工具为 read、bash、powershell、edit、write、grep、find、ls：

{
  "defaultTools": ["bash", "edit", "write"]
}

Windows 上可改用 powershell，或同时保留两者：

{
  "defaultTools": ["read", "powershell", "edit", "write"]
}

空数组表示不启用任何内置工具（扩展与 SDK 自定义工具保留）。命令行侧的关系：--tools 以严格允许列表取代该行为（作用于所有工具），--no-tools 禁用全部工具，--no-builtin-tools 禁用内置默认，--exclude-tools 在结果列表上做过滤。项目级 defaultTools 数组会整体替换全局数组（整体覆盖语义，见合并规则一节）。

会话（Sessions）

设置	类型	默认值	说明
sessionDir	string	-	会话文件存储目录，接受绝对/相对路径与 ~

{ "sessionDir": ".pi/sessions" }

多个来源同时指定会话目录时，优先级为：--session-dir > PI_CODING_AGENT_SESSION_DIR > settings.json 中的 sessionDir。

模型轮换（Model Cycling）

设置	类型	默认值	说明
enabledModels	string[]	-	Ctrl+P 模型轮换使用的模型模式（格式与 --models CLI 参数相同）

{
  "enabledModels": ["claude-*", "gpt-4o", "gemini-2*"]
}

Markdown 渲染

设置	类型	默认值	说明
markdown.codeBlockIndent	string	" "	代码块缩进
markdown.mermaid	string	"streaming"	Mermaid 渲染模式："off"、"final" 或 "streaming"

getMermaidRenderingMode 只接受这三个值，其余取值回退为 "streaming"。

资源（Resources）

以下设置定义从何处加载扩展、技能、提示模板与主题：

~/.pi/agent/settings.json 中的路径相对 ~/.pi/agent 解析；.pi/settings.json 中的路径相对 .pi 解析。支持绝对路径与 ~。

设置	类型	默认值	说明
packages	array	[]	用于加载资源的 npm/git 包
extensions	string[]	[]	本地扩展文件或目录路径
skills	string[]	[]	本地技能文件或目录路径
prompts	string[]	[]	本地提示模板路径或目录
themes	string[]	[]	本地主题文件路径或目录
enableSkillCommands	boolean	true	将技能注册为 /skill:name 命令

数组支持 glob 模式与排除：!pattern 排除，+path 强制包含某个精确路径，-path 强制排除某个精确路径。

packages

字符串形式加载包内全部资源：

{
  "packages": ["pi-skills", "@org/my-extension"]
}

对象形式过滤要加载的资源：

{
  "packages": [
    {
      "source": "pi-skills",
      "skills": ["brave-search", "transcribe"],
      "extensions": []
    }
  ]
}

PackageSource 类型定义还暴露了文档示例未展开的字段：autoload（false 时启动为空、只应用显式资源模式）以及 prompts、themes 过滤数组。包管理的完整细节参见 packages.md。

完整配置示例

{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514",
  "defaultThinkingLevel": "medium",
  "modelThinkingLevels": {
    "anthropic/claude-sonnet-4-20250514": "high"
  },
  "theme": "dark",
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  },
  "retry": {
    "enabled": true,
    "maxRetries": 3
  },
  "enabledModels": ["claude-*", "gpt-4o"],
  "warnings": {
    "anthropicExtraUsage": true
  },
  "packages": ["pi-skills"]
}

项目覆盖与排查建议

• 项目设置只写与全局不同的字段即可，嵌套对象（compaction、retry、terminal 等）会递归合并；
• defaultProjectTrust 与 httpProxy 是仅全局设置，写在 .pi/settings.json 中不会生效；
• 项目未信任时，.pi/settings.json 会被整体忽略（源码层面项目设置直接置空），排查“项目配置不生效”时先确认 ~/.pi/agent/trust.json 中的决定；
• 配置文件 JSON 解析失败时，tryLoadFromStorage 会记录错误并使用空设置继续运行，错误可通过 drainErrors() 取出上报，因此坏的项目配置通常表现为“像没配置一样”而不是崩溃；
• 想验证设置行为是否被正确测试覆盖，可参考 settings-manager.test.ts，其中包含外部修改保留、包迁移、reload、项目信任、TUI 模式、httpIdleTimeoutMs 等用例。

参考

• 官方设置文档：packages/coding-agent/docs/settings.md
• 设置管理器实现：packages/coding-agent/src/core/settings-manager.ts
• 项目信任实现：packages/coding-agent/src/core/trust-manager.ts
• 路径与目录常量：packages/coding-agent/src/config.ts
• 相关文档：包管理、会话格式、压缩
• 测试：packages/coding-agent/test/settings-manager.test.ts