# Pi Compatibility

更新时间：2026-09-13。

本文是当前 checkout 的兼容合同和证据边界。它不把依赖解析成功、类型检查或局部合同测试写成完整宿主支持，也不把真实宿主测试写成自然任务收益证明。

## 版本范围

`package.json` 的 Pi peer range 为：

```text
0.84.2 || 0.85.1
```

当前开发依赖和 `scripts/check-pi-compat.mjs` 固定解析到 Pi `0.85.1`。SoL-Pi 不修改、fork 或 vendoring 上游 Pi；Pi 负责安装和升级自己的包。

| 宿主 | 当前证据 | 当前结论 |
| --- | --- | --- |
| Pi 0.85.1 | 公共 API/export 检查；真实宿主启动 smoke；确定性 `write + then_run`；HUD PTY、模式和生命周期定向测试 | 当前主验证目标；固定路径已有证据，但完整发布、自然任务和收益仍未签字 |
| Pi 0.84.2 | 与 0.85.1 使用同一固定 `write + then_run` 夹具的隔离版本矩阵 | 有界兼容目标；真实 TUI/RPC/print/JSON、第三方扩展组合和完整发布矩阵未完成 |

可追溯记录：

- [compatibility-matrix.md](compatibility-matrix.md)：版本矩阵、公共导出和未验证边界；
- [host-smoke-0851.md](host-smoke-0851.md)：0.85.1 TUI、print、JSON 启动记录和 stub-provider 宿主夹具；
- [release-acceptance.md](release-acceptance.md)：HUD-A01 至 HUD-A16 和发布缺口；
- `scripts/check-pi-compat.mjs`：当前 checkout 的 0.85.1 解析版本、peer range 和公共 export 门禁。

当前不支持或未承诺的范围包括 Pi 0.81.1、未知版本、未经过公共 API 检查的 nightly 版本，以及把上游 Pi 内部 experimental 子路径当成稳定接口的环境。

## 公共接口

SoL-Pi 只使用以下公开能力：

- `createEditToolDefinition`、`createWriteToolDefinition`、`createBashToolDefinition`；
- `ExtensionAPI.registerTool`、`registerCommand`、公开扩展事件和 `sendMessage`；
- `context`、`before_provider_request`、`tool_result`、`turn_end`、`agent_settled`、`session_before_tree`、`session_tree`、`session_compact` 等公开事件；
- `ExtensionContext.getContextUsage()`、`compact()`、`abort()`、`model`、`modelRegistry`；
- `SessionManager.getSessionDir()`、`getSessionId()` 和公开分支/会话方法；
- `@earendil-works/pi-ai/compat` 公共 completion 子路径；
- TUI 的命名 widget、状态和渲染相关公开接口。

若宿主缺少能力，SoL-Pi 应按机制独立降级，诊断中显示 `unknown`、`unreachable` 或明确失败原因，而不是把所有机制静默关闭。

## Action Fusion

Action Fusion 基于 Pi 的内置 edit/write 定义，只额外增加可选的 `then_run`。内置定义按 `ctx.cwd` 缓存，文件目标会先解码 `file://` 和 percent-encoded 路径，再进入 SoL-Pi 的逐文件队列。

默认验证 backend 只有在以下条件同时满足时才使用：

- 宿主提供 `getAllTools()` 和 `getActiveTools()`；
- 活动工具集合含 `bash`；
- 该 `bash` 的来源是 Pi 内置工具。

如果 bash 缺失、未激活、由 SSH/container 等其它扩展提供，或来源无法确认，SoL-Pi 不从本机偷偷启动另一个命令，而是保留已完成的文件修改并将 `then_run` 标为跳过，原因通常为 `EXECUTION_BACKEND_UNSUPPORTED`。嵌入式调用方可以显式注入 `executionAdapter` 或 `bashOptions`，但 `sol-pi.json` 没有 backend 路由字段。

修改失败时不会启动验证；验证非零、超时、取消或验证期间目标文件被外部改写时，回执分别保留失败/取消/跳过状态。SoL-Pi 只锁定自己注册的融合操作，不会锁定其它扩展或用户在外部启动的进程。

## ObservationPack

ObservationPack 只改变公开 `context` 事件中发送给 provider 的投影，不改写 Pi 已保存的原始 session history。原文、JSONL ledger 和对象元数据放在：

```text
<Pi session directory>/sol-pi/<session-id>/
├── observation-pack/
└── evidence-preserving-reducer/
```

`obs_recall` 的可达性会动态检查。入口未知或不可达时，SoL-Pi 停止创建新的引用并保留全文；已存在且有效的引用仍可读。无持久 session、对象不存在、符号链接、非普通文件、哈希不一致或存储目录异常时，不把失败对象当作可信证据。

新对象先写入并校验正文，再写 `.meta.json` sidecar；召回会核对 SHA-256、字节数、字符数、行数和有限的对象指纹。缺少旧 sidecar 的历史对象可以读取，但结果明确标为 `integrity=unverified`，不能称为完整可验证证据。

## Evidence-Preserving Reducer

Reducer 监听公开 `tool_result`，只处理识别为诊断/构建/测试类的长结果。确定性结构化提取优先；远程提取默认关闭，只有配置显式允许时才调用 reducer provider/model。

远程路径通过 Pi 的 `modelRegistry` 或公开 compat completion 能力解析模型和认证，不从环境变量或 `sol-pi.json` 读取 provider URL、API key 或其它凭据。归档、候选事件、provider 回执和最终摘录使用 session-derived 路径保存。

只有在来源 hash、schema、引用原文、失败覆盖、大小和敏感信息检查都通过，并且摘录确实更短时才替换原结果。模型不可用、调用异常、取消、超时、回执不可核对、疑似敏感信息或归档失败时，原始工具结果继续传递。

## Online Context Compact

Online Context Compact 使用公开 `context`、`before_provider_request`、`turn_end`、`agent_settled` 和 native compaction 事件，不依赖 Pi fork-only 的上下文后处理接口。计划与进度状态写入 Pi session log，不创建独立 OCC 文件。

默认保留尾部估算为 `20,000` tokens；公开 context usage 不可用时使用自身估算。`cacheWriteReadRatio` 只参与一次压缩决策，默认 `12.5`，不是账单估算，也不会读取模型价格字段。成功边界压缩后发送隐藏的通用 reminder，并在同一 Pi 调用内等待续跑 settlement；取消、退出、压缩失败或边界不可信时不自动续跑。

第三方扩展若在相同 `agent_settled` 生命周期中执行长时间异步工作，属于未验证组合，需要单独真实宿主测试。树导航在压缩进行期间会被取消，压缩结束后恢复正常。

## UI 与模式

HUD 使用命名 widget `sol-pi-hud`，位置为 `aboveEditor`，不调用 `setFooter`，不清理其它扩展的 widget，也不接管输入框。TUI/RPC 在能力可用时显示；print/JSON 不输出 HUD ANSI 或自定义文本，也不保留刷新 timer。

这只证明显示和模式边界，不证明四机制在自然任务中主动触发。完整 HUD 状态、真实 PTY 和未完成场景见 [hud.md](hud.md) 与 [release-acceptance.md](release-acceptance.md)。

## 测试证据边界

模块测试、fault injection、版本矩阵和真实 Pi stub-provider 测试证明的是对应合同：注册、schema、参数、执行回执、回退、取消、存储和生命周期。它们不能替代：

- 真实模型在普通提示下主动选择 `then_run`、召回、提取或压缩；
- 真实 provider 的付费 usage、成本和质量；
- 0.84.2 全部宿主模式和第三方扩展组合；
- 0.85.1 全部后端、持久 session 重启/分叉恢复和外部原始 PTY 记录；
- 成对自然任务的延迟、质量、成本或无损收益结论。

出现能力缺失时，先使用 `/sol doctor` 和 `/sol status` 查看实际配置、Pi 能力、工具来源和机制状态，再按 [troubleshooting.md](troubleshooting.md) 的路径处理；不要把“工具名存在”或普通日志 marker 当作成功证据。