# Pi Runtime 发布与回滚

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

## 发布边界

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

## Conversation 数据边界

产品只支持 Pi Conversation。项目元数据分别写入 `.makelore/project.json` 与 `.makelore/conversations.json`，Pi Session 由 Main-owned registry 绑定；运行时不探测、导入、续写或改写 OpenCode 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、生产依赖闭包、共享 Agent Server、扩展、Manifest、编码 Skills、`resolve/get_state`、无产品自有 OpenCode runtime/资源、上游 Pi provider 例外清单，以及无构建工作区绝对路径。Smoke 必须从最终产品可执行文件启动最终 `resources/pi-agent-server.mjs` 与 `resources/pi-runtime`，覆盖 session、prompt、tool、abort、settle、reopen、同一 Server 内多线程重叠与隔离、单线程关闭、Server 崩溃重启、独立子 Agent 进程和 shutdown；四条父 Conversation 并发时应只有一个父 Agent Server 进程。性能报告必须记录 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. 停止发布和自动更新，完整备份目标用户数据目录及项目中的 `.makelore` 数据。
2. 退出 Makelore，确认没有 Pi Agent Server、子 Agent 或安装器进程仍在运行。
3. 安装上一完整、已验证且支持当前 `.makelore` schema 的应用版本；不得把单独的 runtime 覆盖到 `resources`，也不得保留不同版本文件拼接后的安装目录。
4. 回滚后验证项目配置、Conversation 元数据和 Pi Session 绑定均可正常读取；不要在版本间手工复制或编辑 Session 文件。
5. 需要重新升级时安装完整 Pi 版本，并重新执行该版本的正式产物验证与 smoke。

回滚完成后，应验证应用标识与全局用户数据目录未改变、`.makelore` 项目数据未被意外改写。任何需要手工编辑项目或 Conversation 文件才能恢复的情况都应停止操作并保留备份。