# Configuration

更新时间：2026-09-13。

SoL-Pi 在 session 启动时读取一份有效 JSON 配置。它使用 Pi 的公开 `CONFIG_DIR_NAME` 和 `getAgentDir()`，不把固定目录写死，也不从专用环境变量读取配置。

## 文件查找与优先级

按以下顺序选择一份文件：

1. `<工作目录>/<Pi 配置目录>/sol-pi.json`，仅当 Pi 将项目标记为 trusted 且文件存在；
2. `<Pi agent 目录>/sol-pi.json`；
3. 两者都不存在时使用内置默认值。

官方 Pi 默认通常是：

```text
<项目>/.pi/sol-pi.json
~/.pi/agent/sol-pi.json
```

项目文件会替代全局文件，二者不合并。可信项目中存在项目文件时，即使全局文件启用了其它机制，也不会叠加生效；不可信项目中的项目文件不会越过 Pi 的信任边界。

实际路径、scope、解析状态和有效配置可在 session 内运行 `/sol doctor` 查看。配置文件变化不会热加载，命令会提示“修改后需重启 Pi”；不要用重新显示 HUD 代替重启。

## v1 配置

最小合法 v1 配置如下：

```json
{
  "version": 1,
  "actionFusion": false,
  "observationPack": false,
  "evidencePreservingReducer": false,
  "evidencePreservingReducerRemote": false,
  "evidencePreservingReducerProvider": "provider-id",
  "evidencePreservingReducerModel": "model-id",
  "onlineContextCompact": false,
  "cacheWriteReadRatio": 12.5
}
```

四个机制字段可省略，省略即为 `false`。`cacheWriteReadRatio` 可省略，默认 `12.5`；显式值必须是有限非负数，`0` 是有效值，表示策略认为 cache write 相对 cache read 不增加成本。这个值只参与 OCC 的一个决策，不是 provider 账单估算。

`evidencePreservingReducerProvider` 和 `evidencePreservingReducerModel` 可省略，分别使用内置 reducer route；显式值必须是非空字符串。远程 reducer 只有在 `evidencePreservingReducer=true` 且 `evidencePreservingReducerRemote=true` 时才会生效；远程开关单独为 `true` 不会注册 reducer。

未知 key、非对象 JSON、`version` 不为 1、布尔字段类型错误、ratio 非法、provider/model 为空或非字符串都会阻止配置加载。用仓库脚本检查具体文件：

```bash
node scripts/check-sol-pi-config.mjs \
  --config /absolute/path/to/effective/sol-pi.json
```

托管安装要求四个机制全部开启时再加 `--require-all-enabled`。这个参数是额外验收门禁，不会改变正常加载的默认值。

## v2 读取与迁移

当前 loader 接受以下 v2 形状，并在内存中转换成 v1 runtime contract：

```json
{
  "version": 2,
  "actionFusion": { "enabled": false },
  "observationPack": { "enabled": false },
  "evidencePreservingReducer": {
    "enabled": false,
    "remote": { "enabled": false },
    "provider": "provider-id",
    "model": "model-id"
  },
  "onlineContextCompact": { "enabled": false },
  "diagnostics": {
    "enabled": true,
    "ui": {
      "layout": "standard",
      "showNativeContext": true,
      "showCost": false,
      "maxExpandedRows": 12,
      "refreshThrottleMs": 250
    }
  }
}
```

v2 的远程 reducer 需要外层 `evidencePreservingReducer.enabled=true` 和内层 `remote.enabled=true`；只打开外层不会获得远程权限。v2 不自动改写源文件，也不自动创建备份；`writeV1MigrationBackup()` 是程序化 helper，不是 `/sol` 命令。要落盘为 v1 时，应先复制原文件，确认备份存在且只包含本地配置，再重启 Pi 验证。

v2 的 HUD 默认值为 `enabled=true`、`layout=standard`、`placement=aboveEditor`、`language=zh-CN`、`scope=branch`、`showNativeContext=true`、`showCost=false`、`maxExpandedRows=12`、`refreshThrottleMs=250`。这些是显示设置，不会打开四个机制，也不会授予远程 reducer 权限。

## 机制开关与运行输入

- `actionFusion`：注册带可选 `then_run` 的 edit/write 替代工具。默认验证使用 Pi 活动的内置 bash；其它 backend 未取得同 backend 委托时安全跳过验证。
- `observationPack`：注册 `obs_recall`，并在公开 `context` 事件中投影长工具结果。对象存储依赖 Pi 持久 session。
- `evidencePreservingReducer`：监听公开 `tool_result`，先做确定性提取，再按远程开关调用配置的 reducer provider/model。失败时保留原文。
- `evidencePreservingReducerRemote`：远程调用授权，不是独立机制；默认关闭。
- `evidencePreservingReducerProvider`：通过 Pi model registry 解析 reducer provider namespace。
- `evidencePreservingReducerModel`：通过 Pi model registry 解析 reducer model id。
- `onlineContextCompact`：注册 `update_plan`，在安全计划边界调用 Pi native compaction，并在成功后续跑。
- `cacheWriteReadRatio`：固定到当前 session 的 OCC 经济决策参数，不随模型切换自动重算。

SoL-Pi 不通过 `sol-pi.json` 配置 provider URL、凭据、主模型、shell path、命令前缀、存储路径、run ID、reasoning level 或验证 timeout。认证、主模型和 shell 行为归 Pi；持久路径由 Pi session directory/session ID 推导。

## HUD 显示控制

HUD 显示和优化权限分离：

```text
/sol hud compact
/sol hud standard
/sol hud expanded
/sol hud hide
/sol hud show
```

这些命令只改变当前 session 的显示。`hide` 不关闭机制，`/sol off` 才会暂停新的写侧优化；`/sol on` 恢复新的写侧优化。暂停后已有证据仍可读。配置文件中的开关变化必须重启 Pi 才生效。

## 全部启用示例

以下配置满足安装协议的 all-enabled preflight，但会开启远程 reducer 和 OCC，只有在已经确认 provider、凭据、成本范围和中断语义后才应使用：

```json
{
  "version": 1,
  "actionFusion": true,
  "observationPack": true,
  "evidencePreservingReducer": true,
  "evidencePreservingReducerRemote": true,
  "evidencePreservingReducerProvider": "provider-id",
  "evidencePreservingReducerModel": "model-id",
  "onlineContextCompact": true,
  "cacheWriteReadRatio": 12.5
}
```

`scripts/check-sol-pi-config.mjs --require-all-enabled` 只检查四个机制 flag；它不会验证 provider 凭据、真实模型质量、实际 backend、自然任务触发率或正式成本收益。

## Trust 与安全

项目级配置可能启用文件修改、shell 执行、本地归档和远程日志提取，只应在可信项目中使用。EPR 远程调用使用 Pi 管理的认证；不要把 key、URL、cookie、authorization、命令秘密或 session 内容写入配置。

无持久 session 时，ObservationPack 和 EPR 不进行归档替换，OCC 不能可靠保存计划/续跑状态；Action Fusion 的文件修改仍可运行，但验证是否可用仍取决于 Pi 的活动 bash backend。详见 [compatibility.md](compatibility.md) 和 [troubleshooting.md](troubleshooting.md)。