📚 编程进阶教程站

第 7 章 · Settings 设置与项目信任 ​

本章目标：掌握 pi 全局/项目两级 settings.json 的优先级与常用配置项，理解 Project Trust 安全机制，学会管理遥测开关并速查常用环境变量。

7.1 两级设置文件与优先级 ​

pi 的设置是纯 JSON 文件，只有两级：

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

日常改配置有两条路：交互模式里输入 /settings 修改常用项，或直接编辑 JSON。一个典型的全局配置：

jsonc
// ~/.pi/agent/settings.json
{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514",
  "defaultThinkingLevel": "medium",
  "theme": "dark",
  "enabledModels": ["claude-*", "gpt-4o"],
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384
  },
  "retry": { "enabled": true, "maxRetries": 3 }
}

嵌套对象是合并而非整体替换——这是最容易踩的坑：

jsonc
// 全局
{ "theme": "dark", "compaction": { "enabled": true, "reserveTokens": 16384 } }

// 项目 .pi/settings.json
{ "compaction": { "reserveTokens": 8192 } }

// 合并结果：theme=dark（继承），enabled=true（继承），reserveTokens=8192（覆盖）
{ "theme": "dark", "compaction": { "enabled": true, "reserveTokens": 8192 } }

7.2 常用设置项速览 ​

设置项很多，先记住最常用的几组（完整清单见 /settings 与官方 docs/settings.md）：

jsonc
{
  // 模型与思考
  "defaultThinkingLevel": "high",     // off/minimal/low/medium/high/xhigh/max
  "thinkingBudgets": { "high": 32768 },

  // 界面
  "externalEditor": "code --wait",    // Ctrl+G 外部编辑器，VS Code 必须带 --wait
  "quietStartup": true,               // 隐藏启动横幅

  // 工具：启动时启用的内置工具（扩展/SDK 自定义工具不受影响）
  "defaultTools": ["bash", "edit", "write"],

  // 会话存储目录；优先级：--session-dir > PI_CODING_AGENT_SESSION_DIR > 此设置
  "sessionDir": ".pi/sessions",

  // 网络
  "httpProxy": "http://127.0.0.1:7890"   // 仅全局设置有效
}

重试设置的两层结构

retry.maxRetries（默认 3）控制 pi 自身的指数退避重试（2s/4s/8s）；retry.provider.maxRetries 默认 0，官方明确建议保持为 0——把它调高会让 SDK 层重试抢在 pi 之前处理"用量超限"等错误，某些情况下会把 agent 卡到配额重置为止。

7.3 Project Trust：为什么要"信任"一个项目 ​

pi 的扩展、技能、包都是可执行任意代码的资源，而它们可以藏在项目仓库的 .pi/ 目录里。克隆一个恶意仓库然后打开 pi，如果项目资源自动执行，攻击就完成了。Project Trust 就是这道防线：

  • 交互模式启动时，若项目包含项目级设置/资源且没有保存过信任决定，pi 会弹出询问；信任后才会加载 .pi/settings.json、安装项目包、执行项目扩展；
  • 信任决定保存在 ~/.pi/agent/trust.json；交互模式里也可随时用 /trust 保存当前项目的信任（写入后需重启 pi 生效）；
  • 非交互模式（-p、--mode json、--mode rpc）不弹窗，回落到全局设置 defaultProjectTrust：
jsonc
// ~/.pi/agent/settings.json —— CI 机器上常见的配置
{
  "defaultProjectTrust": "never"   // ask(默认) / always / never
}
bash
# 一次性覆盖（不写入 trust.json）：
pi -p "运行测试" --approve     # 本次信任项目资源
pi -p "运行测试" --no-approve  # 本次忽略项目资源

安全默认值的意义

默认值是 ask——宁可多问一次。如果你发现团队里有人图省事把 CI 配成 always，请把第 18 章的安全模型转给他看。

7.4 遥测与更新检查 ​

pi 有两个相互独立的启动网络行为，关闭一个不代表关闭另一个：

行为访问目标关闭方式
更新检查pi.dev/api/latest-versionPI_SKIP_VERSION_CHECK=1
安装/更新遥测（匿名版本 ping + 部分 provider 归因头）pi.dev/api/report-installsettings 里 enableInstallTelemetry: false 或 PI_TELEMETRY=0
bash
# 一刀切：禁用上述全部启动网络行为（含包更新检查）
pi --offline
# 或环境变量方式
PI_OFFLINE=1 pi

7.5 环境变量速查表 ​

环境变量分三类，排查问题时先分清类别（完整表见官方 docs/environment-variables.md）：

bash
# ① pi 进程配置类
PI_CODING_AGENT_DIR=~/.pi/agent      # 配置目录（默认值，可覆盖）
PI_CODING_AGENT_SESSION_DIR=...      # 会话存储目录（--session-dir 优先级更高）
PI_OFFLINE=1                         # 禁用全部启动网络操作
PI_SKIP_VERSION_CHECK=1              # 仅禁用版本检查
PI_TELEMETRY=0                       # 关闭遥测与归因头

# ② 进程标记类（pi 自动设置给子进程）
AI_AGENT=pi                          # 通用标记
PI_CODING_AGENT=true                 # pi 专属标记（SDK 嵌入时不自动设置）

# ③ bash 工具会话环境类（LLM 调用 bash 时可读）
PI_SESSION_ID / PI_SESSION_FILE      # 当前会话 ID / JSONL 文件路径
PI_PROVIDER / PI_MODEL               # 当前模型提供方 / 模型 ID
PI_REASONING_LEVEL                   # 当前推理等级

第③类最有趣：模型自己也能感知会话状态。官方建议模型回答"你在用什么模型"时直接读变量而不是猜：

bash
# 在 pi 会话里让 agent 执行：
printf '%s/%s\n' "$PI_PROVIDER" "$PI_MODEL"
printf 'reasoning=%s session=%s\n' "$PI_REASONING_LEVEL" "$PI_SESSION_ID"

注意：这些变量只注入 LLM 可调用的 bash 工具，不会注入你手动输入的 !/!! 命令；切换模型后，下一条 bash 命令拿到的就是新值，无需重启。

本章小结 ​

  • 设置只有两级：全局 ~/.pi/agent/settings.json 与项目 .pi/settings.json，嵌套对象合并、标量覆盖；
  • defaultProjectTrust（ask/always/never）是非交互模式的信任回落值，信任记录在 ~/.pi/agent/trust.json，--approve/--no-approve 可单次覆盖；
  • 更新检查（PI_SKIP_VERSION_CHECK=1）与遥测（PI_TELEMETRY=0）是两件事，--offline 全关；
  • 环境变量分三类：进程配置、进程标记、bash 工具会话环境；PI_PROVIDER/PI_MODEL 等按命令启动时实时解析。

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. 全局设置里 compaction 有 enabled 和 reserveTokens 两个字段，项目设置只写了 reserveTokens: 8192，最终项目里生效的是？

2. 在 CI 的 -p 非交互模式下，项目从未保存过信任决定，pi 会如何处理项目级资源？

3. 关于更新检查与遥测，下列说法正确的是？

4. bash 工具环境里的 PI_MODEL 变量，什么时候取值？

🛠️ 动手实践 ​

  1. 配置一个全局 settings.json：默认模型、quietStartup: true、sessionDir 指向自定义目录，重启验证生效。
  2. 在某项目 .pi/settings.json 里只覆盖 compaction.reserveTokens，确认其他 compaction 子项从全局继承而非丢失。
  3. 在一台"不信任"的项目里分别用 --approve 与 --no-approve 跑 -p 模式，观察项目扩展加载行为的差异。

完成练习后，进入下一章：Prompt Templates 提示词模板。