# 第 7 章：设置与信任——画好边界再谈自由
> 自由的前提是边界：信任谁、加载什么、连不联网，都应由你说了算。
## 设计思想
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` 后重启即恢复。