# SoL-Pi 兼容矩阵

更新时间：2026-09-13。

本矩阵只记录已经执行的证据。类型检查、导出检查和单元测试不能替代真实 Pi 进程中的扩展加载、工具 schema、参数处理和执行回执。

| 宿主 | 依赖/来源 | 静态与模块检查 | 真实宿主合同 | then_run 参数链 | 结论 |
| --- | --- | --- | --- | --- | --- |
| Pi 0.84.2 | `tests/support/pi-version-matrix.ts` 临时隔离依赖树 | 通过 | 固定 write + then_run 通过 | schema、execute 入参和回执通过 | 仅证明固定夹具，不宣称完整版本支持 |
| Pi 0.85.1 | 当前 checkout 与隔离依赖树 | 通过 | 固定 write + then_run 通过 | schema、execute 入参和回执通过 | HUD/固定夹具已测，仍不等于完整发布支持 |

启动 smoke 已在 2026-09-13 运行：Pi 0.85.1 加载当前源码扩展后，TUI `--quit`、print 和 JSON 均退出成功；详见 `docs/host-smoke-0851.md`。这不替代 stub-provider、PTY 或真实工具参数链验证。

真实 Pi 0.84.2/0.85.1 隔离依赖树上的同一确定性 `write + then_run` 夹具已通过，命令为：

```bash
SOL_PI_VERSION_MATRIX=1 npx vitest run \
  tests/integration/fusion-version-matrix.test.ts \
  tests/integration/tool-schema.test.ts \
  tests/integration/tool-argument-chain.test.ts \
  --testTimeout=180000
```

结果为 3 个测试文件、6/6 通过。该结果只证明固定 provider payload 和 write 路径，不覆盖 edit、自然模型选择、第三方扩展冲突或所有错误/取消分支。

打包产物矩阵也已在 2026-09-13 运行。它在临时 prefix 中分别安装 Pi 0.84.2 和 0.85.1、同一个 `npm pack` 产物以及 `typebox`，再从安装后的 `node_modules/sol-pi` 路径启动 JSON host：

```bash
SOL_PI_PACKED_INSTALL=1 npx vitest run \
  tests/integration/packed-install.test.ts \
  --testTimeout=600000
```

结果为 1 个测试文件、1/1 通过；两种 Pi 版本均确认版本号、打包 SoL-Pi 版本、安装路径不在当前源码 checkout，并完成固定 `write + then_run` smoke。该结果证明的是可安装的打包路径，不是目标项目 scope、真实模型质量或自然任务收益。

## 已验证的公开接口

- `createEditToolDefinition`、`createWriteToolDefinition` 和 `createBashToolDefinition` 可从 `@earendil-works/pi-coding-agent` 公共入口解析。
- `ExtensionContext.ui.setWidget`、`setStatus`、`getContextUsage` 和 Pi 生命周期事件存在于 0.85.1 公共类型。
- `@earendil-works/pi-ai/compat` 是声明在包 exports 中的公共子路径；SoL-Pi 不依赖 Pi 源码目录中的 experimental 路径。

## 尚未验证的边界

- 0.84.2 真实 TUI/RPC/print/JSON 的 HUD、widget、footer 共存和 stdout 行为。
- 0.85.1 真实第三方扩展组合下的 widget、footer 共存和完整 stdout 行为。
- 其它扩展替换编辑工具、活动工具快照、Code Mode、后置 context transformer 和 SSH/容器 backend。
- 无持久会话、会话恢复、分叉、树导航、取消和迟到回调处理。

出现能力缺失时应按机制独立降级，并在诊断中显示 `未验证` 或明确原因；未知版本不得静默开启高风险转换。