# Pi Runtime 发布与回滚

本文定义 Makelore Code 当前 Pi Runtime 正式包的发布门槛、兼容边界和整版本回滚方式。它是发布操作契约，不是历史证据归档；每次执行产生的 JSON、日志、安装包和性能报告都保存在忽略的 `release/` 目录或外部发布系统中。

## 发布边界

- 正式包固定使用仓库锁定的 Pi 版本和生产依赖闭包。Electron Main 从安装目录中的 `resources/pi-runtime` 解析运行时、扩展、Manifest 与编码 Skills；缺失、版本漂移、开发路径泄漏或产品自有的 OpenCode runtime/资源残留均阻断发布。锁定的 `@earendil-works/pi-ai` 生产包会静态导入其内置 `providers/opencode*` 模块；这些上游文件必须在报告中单独列出，不能冒充旧 Makelore OpenCode runtime，也不能为制造“零命中”而破坏 Pi 闭包。
- Renderer 只使用 Main-owned Host API 和产品 Conversation 契约，不读取 Pi wire 类型，也不直接启动 worker、访问本地运行时地址或接触 Provider 凭证。
- 产品保留既有 `niancode` 应用 id、协议、数据目录和项目配置兼容标识；这不代表旧 OpenCode 运行时、路由或资源仍被携带。
- 正式产品界面不提供 share/unshare、revert/unrevert、todos 或全局运行时控制。项目分支只创建新的 Conversation 历史，不表示文件回滚。

## Conversation 兼容性

升级前已有的 OpenCode Conversation 数据继续保留，项目首次进入 Pi 会显示一次迁移说明，但 Pi 不导入、续写或改写这些旧 Conversation。升级后新建的 Pi Conversation 使用新的本地契约；旧版本不能读取或续写它们。

因此，旧 Conversation 的“保留”是可回滚的数据边界，不是跨运行时续写兼容。不得通过复制 Session、混用资源目录或在同一安装中切换旧/新 runtime 来绕过该边界。

## 必须验证的正式产物

发布候选必须分别提供以下最终产品证据：

| 目标 | 最终产物 | 必须结果 |
| --- | --- | --- |
| Windows x64 | 安装器与 `win-unpacked` | 产物验证、Pi smoke、性能报告均 Pass |
| Linux x64 | 发布包与 `linux-unpacked` | 产物验证、Pi smoke、性能报告均 Pass |
| macOS x64 | 对应架构应用包 | 独立产物验证与 Pi smoke Pass |
| macOS arm64 | 对应架构应用包 | 独立产物验证与 Pi smoke Pass |

缺少任一目标的独立证据时，结论只能是 `Blocked`，不能用其他平台、staging 目录、源码测试或用户豁免替代跨平台发布就绪结论。

每个平台在完成打包后，从该平台的最终应用可执行文件运行：

```bash
pnpm run verify:artifact:pi -- --app-exe <final-product-executable> --samples 5 --report <artifact-report.json>
pnpm run smoke:pi:real -- --app-exe <final-product-executable> --samples 5 --report <smoke-report.json>
pnpm run perf:pi:release -- --app-exe <final-product-executable> --samples 5 --report <performance-report.json>
```

产物验证必须确认版本与 Node engine、生产依赖闭包、扩展、Manifest、编码 Skills、`resolve/get_state`、无产品自有 OpenCode runtime/资源、上游 Pi provider 例外清单，以及无构建工作区绝对路径。Smoke 必须从最终产品可执行文件启动最终 `resources/pi-runtime`，覆盖 session、prompt、tool、abort、settle、reopen、双 worker 重叠与隔离、子 Agent 和 shutdown。性能报告必须记录 p50/p95/max/样本数组、RSS、Main→Renderer IPC/提交延迟和 Git commit，并覆盖 Spec 17.3 的十个场景。

## Provider 验证的准确含义

`smoke:pi:real` 中的 `real` 指真实最终 Pi 进程与最终产品资源，不指真实外部 Provider。受控 Provider-shaped 回环服务只证明 Makelore/Pi 的协议与隔离路径按预期运行。

如果发布决定明确豁免真实 Provider 验证，报告必须保持 `realTurnVerified=false`，并把 QG-004/QG-005 标为 `Explicitly Waived / Accepted Risk`，不得写成 Pass。被接受的剩余风险包括真实 Provider 的协议差异、限流与并发策略、凭证隔离，以及多模态输入的供应商特定行为；报告和日志不得包含真实凭证。

## 发布判定

只有下列条件同时成立才能发布：

1. 固定 pnpm 版本的 frozen install、typecheck、lint、unit、production build 和完整 Electron E2E 通过。
2. 四个目标的最终产品产物验证与 Pi smoke 均通过，且报告对应同一 Git commit。
3. Spec 17.3 场景与性能预算通过，没有源码目录、staging 目录或开发 fallback 代替最终产物证据。
4. 真实 Provider 若未验证，已由发布负责人显式接受上述风险，并保持非 Pass 状态。

## 整版本回滚

Pi 与旧运行时之间只支持完整应用版本回滚，不支持运行时组件级回滚或混装：

1. 停止发布和自动更新，完整备份目标用户数据目录及项目中的 `.niancode` 数据。
2. 退出 Makelore，确认没有 Pi worker 或安装器进程仍在运行。
3. 安装上一完整、已验证的应用版本；不得把旧 runtime 覆盖到新版本 `resources`，也不得保留新旧文件拼接后的安装目录。
4. 旧版本只继续使用其原本可读的旧 Conversation。升级后新建的 Pi Conversation 保留在磁盘中，但对旧版本不兼容，不能读取或续写。
5. 需要重新升级时，安装完整 Pi 版本并重新执行该版本的项目迁移与一次性说明流程；不要在不同版本间复制 Session 文件。

回滚完成后，应验证应用标识与用户数据目录未改变、旧 Conversation 仍可按旧版本能力读取、Pi Conversation 字节未被旧版本改写。任何需要手工编辑 Conversation 文件才能恢复的情况都应停止操作并保留备份。