65 lines
5.9 KiB
Markdown
65 lines
5.9 KiB
Markdown
# 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 文件才能恢复的情况都应停止操作并保留备份。
|