第 7 课：设置与配置

Pi 通过 JSON 设置文件配置——两层结构，优先级规则很清晰。

两个层级

位置	作用域
~/.pi/agent/settings.json	全局——适用于所有项目
.pi/settings.json	项目——覆盖全局

项目覆盖全局，嵌套对象是合并而不是替换：

// 全局
{ "theme": "dark", "compaction": { "enabled": true, "reserveTokens": 16384 } }
// 项目
{ "compaction": { "reserveTokens": 8192 } }
// 结果
{ "theme": "dark", "compaction": { "enabled": true, "reserveTokens": 8192 } }

你可以直接编辑文件，也可以用 /settings 调整常用选项。

值得了解的设置

模型与思考：

{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514",
  "defaultThinkingLevel": "medium",
  "enabledModels": ["claude-*", "gpt-4o"]
}

enabledModels 驱动 Ctrl+P 循环。thinkingBudgets 允许你按等级设置自定义 token 预算，获得比默认更精细的控制。

压缩（上下文填满时自动总结）：

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

keepRecentTokens = 有多少近期历史可以完整保留。

消息投递： steeringMode / followUpMode — "one-at-a-time"（默认，等待每条回复）或 "all"（一次投递所有排队消息）。transport 选择 sse、websocket 或 auto。

重试： retry.enabled、maxRetries（默认 3）、指数退避，以及提供商级超时。把 retry.provider.maxRetries 保持在 0——设置更高可能让提供商吞掉配额错误，静默阻塞你的代理。

界面细节： theme、quietStartup（隐藏头部）、externalEditor（例如 VS Code 用 "code --wait"）、treeFilterMode、doubleEscapeAction。

终端与图片： terminal.showImages、images.autoResize、images.blockImages（如果你永远不想把图片发给 LLM）。

Shell： shellPath（自定义 shell）、shellCommandPrefix（给每条 bash 命令加前缀，如 "shopt -s expand_aliases"）、npmCommand（用于 node 版本管理器环境：["mise", "exec", "node@20", "--", "npm"]）。

会话： sessionDir — 例如 ".pi/sessions" 把会话文件放在仓库里。

警告： warnings.anthropicExtraUsage — 订阅认证可能产生付费额外用量时发出警告。

资源与信任

设置里的 packages、extensions、skills、prompts、themes 数组指向要加载的额外资源。它们支持带排除项的 glob 模式——!pattern 排除、+path 强制包含、-path 强制排除：

{
  "skills": ["~/.claude/skills"],
  "packages": ["pi-skills"],
  "enableSkillCommands": true
}

注意：项目级设置只有在你信任项目之后才会加载（第 4 课）。defaultProjectTrust 控制回退行为："ask"（默认）、"always" 或 "never"。非交互模式从不询问——它们使用这个设置，或通过 --approve/--no-approve 单次覆盖。

网络与遥测

• httpProxy — 仅全局设置，用于代理环境
• enableInstallTelemetry — 匿名安装统计；用 false 或 PI_TELEMETRY=0 关闭
• PI_SKIP_VERSION_CHECK=1 — 跳过更新检查
• --offline / PI_OFFLINE=1 — 禁用所有启动时的网络操作

你的工作流

1. 打开 /settings 四处看看——它是交互式的，不用编辑文件。
2. 持久的偏好放进 ~/.pi/agent/settings.json。
3. 团队级配置放进 .pi/settings.json（想保持一致就提交它）。

---

作业： 通过 /settings 或直接编辑，把 defaultThinkingLevel 设为 low 用一天，感受速度和费用的差异，再决定。如果头部信息烦人，也可以加上 quietStartup: true。