第 7 章：设置与信任——画好边界再谈自由

Markdown

自由的前提是边界：信任谁、加载什么、连不联网，都应由你说了算。

设计思想

Pi 的扩展能力越强，"项目里的代码能自动执行什么"就越需要明确边界。设置体系分全局/项目两层，项目层可覆盖全局；信任机制则在加载项目本地资源（.pi/ 设置、扩展、skills）前要求你显式授权，防止 clone 一个仓库就被执行任意代码。遥测与更新检查也各自独立开关，可精确控制 pi 的对外网络行为。

原理

设置文件

位置 作用域
~/.pi/agent/settings.json 全局（所有项目）
.pi/settings.json 项目级，覆盖全局同名项

常用项（/settings 界面可改）：主题、steeringMode/followUpMode 消息投递、transport（sse/websocket/auto）、自动压缩、defaultProjectTrust、enableInstallTelemetry 等。完整选项见 docs/settings.md。

项目信任（Project Trust）

  • 触发条件：交互模式启动时，若项目目录含有本地设置/资源或项目 .agents/skills，且 ~/.pi/agent/trust.json 中没有对该目录（或其父目录）的既有决定，pi 会先询问。
  • 信任的效果：允许加载 .pi/settings.json 与 .pi/ 资源、安装缺失的项目包、执行项目扩展。
  • 信任前的加载范围：仅上下文文件、用户/全局扩展、CLI -e 指定的扩展——保证 project_trust 事件处理器本身可用。
  • 切换会话同样适用：切到另一个 cwd 且信任未决的会话时，遵循同样的拆分逻辑。
  • 非交互模式（-p、--mode json、--mode rpc）不弹询问，按全局 defaultProjectTrust 处理：ask（默认）与 never 忽略项目资源，always 信任。单次运行可用 --approve/-a 或 --no-approve/-na 覆盖。
  • /trust：保存当前项目的信任决定（含直接父目录），只写 trust.json，需重启生效。
  • pi config 走同一信任流程；pi update 从不弹询问。

遥测与更新检查（两件独立的事）

机制 行为 关闭方式
更新检查 启动时请求 pi.dev/api/latest-version 检查新版本 PI_SKIP_VERSION_CHECK=1
安装/更新遥测 首次安装或检测到更新后发送匿名版本 ping 到 pi.dev/api/report-install；同时控制 OpenRouter/Cloudflare/NVIDIA NIM 请求的 provider 归因头 settings 设 enableInstallTelemetry: false，或 PI_TELEMETRY=0

注意：关遥测不会关更新检查。一键离线：--offline 或 PI_OFFLINE=1 禁用全部启动期网络操作（更新检查、包更新检查、遥测）。

用法

  • 个人偏好放全局：主题、键位、默认模型等写进 ~/.pi/agent/settings.json，全项目生效。
  • 项目约定放项目：某仓库专属的工具白名单/资源放 .pi/settings.json，覆盖全局。
  • 打开陌生仓库：首次启动遇到信任询问时，审一眼 .pi/ 里有什么再决定；选"信任"后可用 /trust 记住决定，之后不再询问。
  • CI/脚本中跑 pi：非交互不弹窗，明确传 -a（信任项目资源）或 -na（忽略），避免行为依赖 defaultProjectTrust。
  • 合规环境：PI_OFFLINE=1 + PI_TELEMETRY=0 + PI_SKIP_VERSION_CHECK=1 可做到启动期零外联。
  • 排查"扩展没加载"：先想信任机制——项目未受信时 .pi/extensions/ 会被跳过，/trust 后重启即恢复。