1143 lines
57 KiB
Markdown
1143 lines
57 KiB
Markdown
# ML-CODE-PI-001 实施票据与依赖图
|
||
|
||
## 0. 文档信息
|
||
|
||
| 字段 | 值 |
|
||
| --- | --- |
|
||
| 关联 Spec | `ML-CODE-PI-001` |
|
||
| 状态 | 实施中；`PI-000` Done with explicit waivers |
|
||
| Task | `20260822-pi-runtime-spec-b6e2c9a4` |
|
||
| `PI-000` 实施基线 | `2bc423ebc58589307442ebdaf1c81d83ec9dc2d5`（`feat: qualify Pi runtime cutover foundation`） |
|
||
| 目标 | 把完整硬切换拆成可验证、无循环依赖的执行图 |
|
||
| 当前 Ready Frontier | `PI-010`, `PI-020`, `PI-030`（`PI-000` 已 Done with explicit waivers） |
|
||
| Phase-0 macOS | **Explicitly Waived / Deferred by user on 2026-08-22**；不是 Pass，实际验收移至 `PI-150` |
|
||
| 真实 Provider | `QG-004`/`QG-005` **Explicitly Waived / Accepted Risk by user on 2026-08-22**；不是 Pass，也不再阻断 release |
|
||
|
||
本文中的“票据”是仓库内实施单元，不代表已经创建 GitHub Issue、分支、PR 或子智能体。后续执行者可以把票据同步到外部 issue tracker，但票据 ID、依赖和验收语义必须保持。
|
||
|
||
## 0.1 当前规划状态（2026-08-22）
|
||
|
||
| 字段 | 当前判断 |
|
||
| --- | --- |
|
||
| `PI-000` 实施任务 | `20260822-pi-runtime-qualification-c52e8a14`；commit `2bc423e`；`ready_for_integration` |
|
||
| `PI-000` 状态 | Done with explicit waivers；不是全部 QG Pass |
|
||
| 规划 frontier | `PI-010`, `PI-020`, `PI-030`；其余票据继续按 31 条依赖边锁定 |
|
||
| `PI-010` 交接 | `20260822-pi-conversation-contracts-a61d9c42`；基线 `2bc423e`；当前 `planning` |
|
||
| 资格证据 | `.project-docs/50-evidence/topics/20260822-pi-runtime-qualification-c52e8a14__pi-runtime-qualification.md` |
|
||
|
||
已确认事实：
|
||
|
||
- `PI-000` 已作为 commit
|
||
`2bc423ebc58589307442ebdaf1c81d83ec9dc2d5` 提交；实施工作树干净，任务登记为
|
||
`ready_for_integration`。`PI-010` 已在该 commit 上建立独立工作树并进入
|
||
`planning`；这不改变依赖已满足的 Ready Frontier 定义。
|
||
- 精确候选 pin 为 `@earendil-works/pi-coding-agent@0.84.2`；上游 tag
|
||
`v0.84.2`、npm `gitHead` 与 commit 均为
|
||
`914cf1472e715297caa30db4b9535d534a9eb718`。
|
||
- Windows x64 的 workspace、临时 production closure，以及独立受控 Electron
|
||
Builder `dir`/`app.asar` probe 均可通过 `ELECTRON_RUN_AS_NODE=1` 启动 Pi
|
||
RPC。受控 artifact 使用 `MakelorePiProbe.exe` 和
|
||
`resources/app.asar/dist/cli.js`，刻意不继承 Makelore 正式
|
||
`electron-builder.yml` 的 OpenCode/Python/UV/signing/install hooks，也没有
|
||
改动最终产品打包 wiring。
|
||
- 受控 artifact 可定位 Pi 0.84.2、CLI、130 个 Windows 适用 production
|
||
packages、9 个按平台跳过项和 6 个 runtime WASM/native assets；`.node`
|
||
位于 `app.asar.unpacked`。Electron Builder 把同版本
|
||
`@types/retry@0.12.0` 从 `p-retry` nested layout 扁平化到 root
|
||
`node_modules`，属于可解析布局变化，不是依赖丢失。
|
||
- 受控 packaged artifact 的 5 cold / 5 warm 样本分别为：cold
|
||
p50/p95/max 668/682/682 ms，warm 660/663/663 ms；10 个 RSS 样本
|
||
138404/141320/141320 KiB；exit 16/18/18 ms。session/reopen、
|
||
deterministic failure、local shell overlap、单侧 abort isolation、stdin
|
||
close 均通过，结束后没有 artifact 或 Pi RPC 残留进程。
|
||
- packaged runtime 上的 `127.0.0.1` HTTP/SSE 合同 probe 已覆盖
|
||
`openai-completions`、`openai-responses`、`anthropic-messages`、`openrouter`。
|
||
每种协议恰好产生 4 个 POST，验证 base URL/path、环境凭据 header、custom
|
||
header、model、PNG image、双 worker 成功 settled、turn 重叠、单侧 abort
|
||
与另一侧成功以及 stdin-close；最终收紧重跑的重叠时间依次为
|
||
304/309/290/297 ms。
|
||
- Anthropic 配置使用 Provider root，由 SDK 追加 `/v1/messages`；OpenAI 风格
|
||
base URL 以 `/v1` 结尾，再追加 `chat/completions` 或 `responses`。该差异应
|
||
进入后续 Provider catalog fixture，而不能对四种协议统一拼接路径。
|
||
- 最终 focused suite 为 9 tests；scoped ESLint、typecheck、`build:vite`、
|
||
`git diff --check` 和 project-doc drift gate 已通过。
|
||
- Linux x64 在 WSL2 Ubuntu 24.04、kernel
|
||
`6.6.87.2-microsoft-standard-WSL2` 中取得 workspace、staged production
|
||
closure 与 controlled Electron Builder `dir/app.asar` 三层证据。隔离快照以
|
||
Node 22.22.2 和仓库 pin `pnpm@10.33.4` frozen install，运行 seam 为
|
||
Electron 43.4.0 与 embedded Node 24.18.1。
|
||
- Linux workspace 5 cold / 5 warm：cold p50/p95/max 426/853/853 ms，warm
|
||
432/437/437 ms，RSS p95 170388 KiB，exit p95 8 ms。staged closure：cold
|
||
426/428/428 ms，warm 423/440/440 ms，RSS p95 175956 KiB，exit p95 8 ms。
|
||
- Linux controlled `dir/app.asar`：cold 526/545/545 ms，warm 545/569/569
|
||
ms，RSS p95 181928 KiB，exit p95 7 ms；131 个 Linux 适用 package、8 个
|
||
platform skip、6 个 runtime asset 和 unpacked native assets 均无缺失，只有
|
||
与 Windows 相同的同版本 `@types/retry@0.12.0` flattening。
|
||
- Linux packaged 四协议 loopback 每种恰好 4 个 POST，路径、鉴权头、自定义
|
||
header、model、PNG image、双 worker overlap、单侧 abort isolation 与清理
|
||
均通过；overlap 依次为 292/290/277/288 ms，结束后无 artifact/Pi RPC
|
||
残留进程。Linux 报告代码也已移除运行时仍硬编码“Linux missing”的字段，
|
||
改为 cross-platform aggregate requirement；7 tests、scoped ESLint、
|
||
typecheck 和 1-sample integration probe 通过。
|
||
- macOS 实跑前发现并修复一个真实 packaged-closure path defect：旧 inspector
|
||
在 artifact 内用 `dirname(process.execPath)/resources` 推导资源目录；macOS
|
||
executable 位于 `<app>/Contents/MacOS/MakelorePiProbe`，旧逻辑会错误读取
|
||
`Contents/MacOS/resources/app.asar`，实际路径是
|
||
`Contents/Resources/app.asar`。
|
||
- 修复后由外层 platform-aware `packagedResourcesDirectory()` 只计算一次资源
|
||
目录，并通过 `PI_PROBE_RESOURCES_DIRECTORY` 传入 artifact process；closure
|
||
inspector 不再二次推导。focused test 已覆盖 darwin executable →
|
||
`Contents/Resources`。
|
||
- 修复后的 Windows controlled packaged actual regression 以 1 cold / 1 warm
|
||
样本通过，ready 为 650/641 ms；130 个适用 package、6 个 runtime asset 与
|
||
unpacked native asset 均无缺失，证明显式资源目录传递没有破坏 Windows。
|
||
这只验证修法和 Windows 回归，不是 macOS 运行证据。
|
||
|
||
未验证但由用户于 2026-08-22 明确接受、且不再阻断 `PI-000` 或 release 的风险：
|
||
|
||
- 四协议 loopback 只证明 Pi request serialization、SSE parsing、图片/header/
|
||
model/credential plumbing、worker 重叠与 abort 隔离。它没有发起外部请求或
|
||
产生费用，也不证明任何真实 Provider Account、认证、proxy、rate-limit 或
|
||
provider-specific response variance；四协议真实 endpoint/account/credential/
|
||
successful settled/concurrency/abort/reopen/image-where-supported 样本仍缺失。
|
||
- 用户明确接受真实认证/endpoint/proxy/rate-limit/provider-specific response
|
||
variation，base URL/header/environment credential/model/image 的真实协议兼容，
|
||
真实 provider 并发或串行/限流，以及跨 worker abort/event/session/model/
|
||
credential 隔离风险。`QG-004`、`QG-005` 因此标记为 **Explicitly Waived /
|
||
Accepted Risk**，不是 Pass；所有资格/发布报告继续保留
|
||
`realTurnVerified: false`。
|
||
|
||
用户明确豁免并延期的 Phase-0 项（不是 Pass，也不再阻断 `PI-000`）：
|
||
|
||
- 用户于 2026-08-22 决定跳过 `PI-000` 的 macOS 实跑。macOS x64 与 macOS
|
||
arm64 标记为 **Explicitly Waived / Deferred by user**；workspace、staged
|
||
production closure、controlled packaged seam、packaged loopback、资源和
|
||
metrics 全部移至 `PI-150`。
|
||
- darwin 资源路径 preflight defect 已修并有静态测试，但两个架构都尚未实际
|
||
运行，所以不得标记 macOS Pass。延后可能使 packaging/native/resource/
|
||
performance defect 到 release stage 才暴露并造成返工；这是用户接受的风险，
|
||
不是已消除风险。
|
||
|
||
范围限定和后续约束：
|
||
|
||
- 当前 Linux 证据来自真实 Ubuntu 24.04 x64 用户空间、Linux executable/native
|
||
selection、asar layout 和 process seam，但 kernel 为 WSL2 且 artifact 是
|
||
controlled Builder `dir`。正式 Spec 的 `QG-002` 只明确要求 Linux packaged
|
||
app，没有额外要求 non-WSL kernel、native compositor、AppImage 或 deb，
|
||
因此这些不是新增的 `PI-000` blocker；若它们属于最终发行格式，仍必须在
|
||
`PI-150` 以实际 release artifact 验收。
|
||
- 已发布包的 shrinkwrap 是 production-only，但 package root 仍列出 10 个
|
||
devDependencies；npm 11 的直接 `ci --omit=dev` 会在 omit 前因不同步失败。
|
||
当前资格 probe 只在临时副本移除该字段后复用原 shrinkwrap。`PI-030`
|
||
必须把永久 staging 处理定义为显式、可复现的实现与验收项，不能把临时
|
||
workaround 当成最终打包已通过。
|
||
- `PI-150` 的 macOS handoff 要求 x64/arm64 各使用独立 checkout、对应架构
|
||
Node/Electron download 与 frozen install，依次运行 workspace 5+5、staged
|
||
5+5、controlled packaged 5+5、packaged loopback、closure/native/resource
|
||
检查和 metrics，再验证最终目标 artifact；不得跨架构复用 `node_modules`
|
||
或 artifact。`PI-000` waiver 不得在 `PI-150` 被当作证据。
|
||
- 当前执行环境没有仓库 CI definition、macOS runner/SSH host、GitLab runner
|
||
CLI 或 Provider credential environment variable。internal GitLab remote 只能
|
||
提供源码远端，不能生成真实 Provider 证据，也不能提前补齐 `PI-150` 延期的
|
||
macOS 证据；前者已由用户接受为非阻断风险，后者仍将在 release stage 阻断
|
||
`PI-150`。
|
||
|
||
当前 QG 状态（编号严格以 `ML-CODE-PI-001` 第 8.1 节为准；实施证据中的
|
||
task-local 状态表不是规范编号来源）：
|
||
|
||
| Gate | 状态 | 规划解释 |
|
||
| --- | --- | --- |
|
||
| `QG-001` | Pass | 精确 identity、pin、engine、CLI 已确认 |
|
||
| `QG-002` | Pass | 修订后的 Phase-0 平台范围为 Windows x64 + Linux x64；两者 packaged qualification artifact 的 spawn/RPC/session/prompt/abort/settle/reopen/exit 已通过。macOS x64/arm64 Explicitly Waived / Deferred，不是 Pass |
|
||
| `QG-003` | Pass | 修订后的 Phase-0 平台范围内，Windows/Linux controlled qualification artifact 的完整适用 package、WASM/native asset 可解析；最终产品 artifact 与 macOS 实跑留在 `PI-150` |
|
||
| `QG-004` | Explicitly Waived / Accepted Risk | 不是 Pass。Windows/Linux packaged 四协议 loopback 合同通过且 `realTurnVerified=false`；真实 Account/auth/endpoint/proxy/rate-limit/response variance 与真实 base URL/header/environment credential/model/image 兼容未验证，由用户接受风险 |
|
||
| `QG-005` | Explicitly Waived / Accepted Risk | 不是 Pass。provider-shaped loopback two-worker overlap/单侧 abort 通过；真实 provider 并发或串行/限流及跨 worker abort/event/session/model/credential 隔离未验证，由用户接受风险 |
|
||
| `QG-006` | Pass | 修订后的 Phase-0 平台范围内，Windows/Linux cold/warm/RSS/exit 的 p50/p95/max 与样本数已报告；macOS metrics Explicitly Waived / Deferred 到 `PI-150`，不是 Pass |
|
||
| `QG-007` | Pending / 未触发 | 尚无已确认失败；只有未豁免的 packaging/provider-shaped contract/concurrency/abort/预算门确认失败才触发 utility-process SDK 修订。用户 waiver 不是失败 |
|
||
|
||
规划判断：逐项审计 `PI-000` Required work、Acceptance 与 Stop condition 后，
|
||
所有未豁免要求均已有证据且没有已确认失败。macOS Phase-0 明确 deferred 到
|
||
`PI-150`；`QG-004`/`QG-005` 明确 Accepted Risk；两类均不是 Pass。`QG-007`
|
||
保持 Pending / not triggered。因此 `PI-000` 标记为 **Done with explicit
|
||
waivers**。按未修改的 DAG 重新计算，精确新 Ready Frontier 是 `PI-010`、
|
||
`PI-020`、`PI-030`。真实外部 Provider 不再是 `PI-000`/`PI-150`/release
|
||
blocker；macOS x64/arm64 在 `PI-150` 仍是不可豁免的 release blocker。若未来
|
||
任何未豁免的 packaging、provider-shaped contract/concurrency/abort 或预算门
|
||
出现确认失败，继续按 Stop condition 修订为 SDK-in-Electron-utility-process；
|
||
仍禁止 OpenCode fallback 或 RPC/SDK 双生产路径。
|
||
|
||
## 1. 执行规则
|
||
|
||
1. 所有产品代码票据属于同一个 OpenCode → Pi 硬切换 release unit。中间提交可以存在新旧源码，但任何部分不得以双 runtime 形式发布。
|
||
2. `PI-000` 是阻断式资格门；当前已 Done with explicit waivers。任何历史或未来执行中，它未完成前仍不得开始会制造迁移成本的产品实现；本图将所有实施票据显式依赖它。
|
||
3. 只有依赖全部 `Done` 的票据才进入 Ready Frontier。依赖不满足时，不得以“先写一点”绕过。
|
||
4. 每张票据只拥有其“主要文件/责任区”。共享文件必须由依赖更靠前的票据定义合同，后续票据按合同消费；需要改变合同必须先更新上游测试和关联 Spec。
|
||
5. 一张票据只有在自身 acceptance 和 verification 全部通过后才能标 `Done`。仅编译、仅单测、仅人工体验均不充分。
|
||
6. `PI-000`～`PI-150` 构成一个实施分支/PR 的完整代码范围；不得把未删除 OpenCode 的中间状态合入 release。
|
||
7. `PI-160` 是终端 Integration/Release Gate。它在实现 PR 完成后执行最终审阅、集成、canonical promotion 和发布阻断检查。
|
||
8. 本票据图不要求任何特定协作方式。当前文档任务按用户要求不创建子智能体；未来执行也必须遵守当时用户和仓库并发所有权规则。
|
||
|
||
## 2. 依赖图
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
P000[PI-000 Runtime qualification gate]
|
||
P010[PI-010 Conversation contracts & reducer]
|
||
P020[PI-020 Schema v2 & migration]
|
||
P030[PI-030 Pi process/RPC foundation]
|
||
P040[PI-040 Provider & managed resources]
|
||
P050[PI-050 Worker pool & session registry]
|
||
P060[PI-060 Event projector & hydration]
|
||
P070[PI-070 Extension host, interactions & lease]
|
||
P080[PI-080 Subagent scheduler]
|
||
P090[PI-090 Product tools & change tracker]
|
||
P100[PI-100 Core /api/coding Host API]
|
||
P105[PI-105 Files/changes/skills Host API]
|
||
P110[PI-110 Renderer protocol store]
|
||
P120[PI-120 Core Chat & first-Conversation UX]
|
||
P130[PI-130 Feature-complete Coding UI]
|
||
P140[PI-140 OpenCode removal & cutover migration]
|
||
P150[PI-150 Packaging, E2E & performance release proof]
|
||
P160[PI-160 Integration and release gate]
|
||
|
||
P000 --> P010
|
||
P000 --> P020
|
||
P000 --> P030
|
||
P020 --> P040
|
||
P030 --> P040
|
||
P010 --> P050
|
||
P020 --> P050
|
||
P030 --> P050
|
||
P040 --> P050
|
||
P010 --> P060
|
||
P050 --> P060
|
||
P060 --> P070
|
||
P040 --> P070
|
||
P070 --> P080
|
||
P070 --> P090
|
||
P020 --> P090
|
||
P020 --> P100
|
||
P060 --> P100
|
||
P070 --> P100
|
||
P020 --> P105
|
||
P090 --> P105
|
||
P010 --> P110
|
||
P100 --> P110
|
||
P110 --> P120
|
||
P080 --> P130
|
||
P090 --> P130
|
||
P105 --> P130
|
||
P120 --> P130
|
||
P130 --> P140
|
||
P140 --> P150
|
||
P150 --> P160
|
||
```
|
||
|
||
## 3. 票据总览
|
||
|
||
| ID | 标题 | Depends on | 主要责任区 | 完成后解锁 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `PI-000` | Runtime qualification gate | — | 精确版本、packaged probe、Provider/并发/RSS 证据 | `010`, `020`, `030` |
|
||
| `PI-010` | Conversation contracts & reducer | `000` | shared contracts、fixtures、in-memory runtime | `050`, `060`, `110` |
|
||
| `PI-020` | Schema v2 & migration | `000` | `coding-projects`、project/conversation schema、backup | `040`, `050`, `090`, `100`, `105` |
|
||
| `PI-030` | Pi process/RPC foundation | `000` | bundler、worker process、LF framer、RPC client | `040`, `050` |
|
||
| `PI-040` | Provider & managed resources | `020`, `030` | provider catalog、secret、prompt/skill/resource loader | `050`, `070` |
|
||
| `PI-050` | Worker pool & session registry | `010`, `020`, `030`, `040` | runtime、pool、registry、lifecycle、telemetry base | `060` |
|
||
| `PI-060` | Event projector & hydration | `010`, `050` | live assembly、active leaf、snapshot/reconcile/recover | `070`, `100` |
|
||
| `PI-070` | Extension host, interactions & lease | `040`, `060` | managed extension bridge、ask_user、write lease | `080`, `090`, `100` |
|
||
| `PI-080` | Subagent scheduler | `070` | `subagent.v1`、child process、caps、abort | `130` |
|
||
| `PI-090` | Product tools & change tracker | `020`, `070` | browser/game/task/changed-file/skills、change tracker | `105`, `130` |
|
||
| `PI-100` | Core `/api/coding` Host API | `020`, `060`, `070` | project/conversation routes、SSE、interactions | `110` |
|
||
| `PI-105` | Files/changes/skills Host API | `020`, `090` | file/search/change/skill routes | `130` |
|
||
| `PI-110` | Renderer protocol store | `010`, `100` | typed facade、per-Conversation store、snapshot/patch | `120` |
|
||
| `PI-120` | Core Chat & first-Conversation UX | `110` | Composer、timeline、optimistic prompt、render batching | `130` |
|
||
| `PI-130` | Feature-complete Coding UI | `080`, `090`, `105`, `120` | model/thinking/queue/compaction/interactions/subagents/changes | `140` |
|
||
| `PI-140` | OpenCode removal & cutover migration | `130` | 删除旧 runtime/routes/deps/UI/tests/resources、migration notice | `150` |
|
||
| `PI-150` | Packaging, E2E & performance proof | `140` | artifact、real smoke、full E2E、Windows/Linux/macOS x64+arm64、perf report | `160` |
|
||
| `PI-160` | Integration and release gate | `150` | final review、zero residue、canonical docs、release decision | Release |
|
||
|
||
## 4. Ready Frontier 演进
|
||
|
||
下面是依赖完成后的预期 frontier，不是必须串行执行的阶段清单：
|
||
|
||
| 条件 | 新 Ready Frontier |
|
||
| --- | --- |
|
||
| 初始，以及 `PI-000` 完成前 | `PI-000`（唯一 frontier；未 Done，无下游解锁） |
|
||
| 2026-08-22 `PI-000` Done with explicit waivers | `PI-010`, `PI-020`, `PI-030` |
|
||
| `PI-020` + `PI-030` Done | `PI-040`（同时等待中的 `PI-010` 可继续） |
|
||
| `PI-010` + `PI-020` + `PI-030` + `PI-040` Done | `PI-050` |
|
||
| `PI-050` Done | `PI-060` |
|
||
| `PI-060` Done | `PI-070`；`PI-100` 仍等 `PI-070` |
|
||
| `PI-070` Done | `PI-080`, `PI-090`, `PI-100` |
|
||
| `PI-090` Done | `PI-105` |
|
||
| `PI-100` Done | `PI-110` |
|
||
| `PI-110` Done | `PI-120` |
|
||
| `PI-080` + `PI-090` + `PI-105` + `PI-120` Done | `PI-130` |
|
||
| `PI-130` Done | `PI-140` |
|
||
| `PI-140` Done | `PI-150` |
|
||
| `PI-150` Done | `PI-160` |
|
||
|
||
## 5. 票据详情
|
||
|
||
## PI-000 — Runtime qualification gate
|
||
|
||
### Objective
|
||
|
||
在写业务迁移前，证明选定 Pi 版本能在 Makelore qualification 打包边界中满足 runtime、四协议 packaged loopback/provider-shaped 并发、资源和退出要求；对明确未验证的真实外部 Provider 风险作出显式人类决定，确认失败时尽早终止错误架构。
|
||
|
||
### Dependencies
|
||
|
||
- None。
|
||
|
||
### Current planning status
|
||
|
||
- **Done with explicit waivers**；实施任务为
|
||
`20260822-pi-runtime-qualification-c52e8a14`。这不是全部 QG Pass。
|
||
- Windows x64 与 WSL2 Linux x64 的 workspace/staged/controlled packaged RPC、
|
||
session、process、closure、loopback 四协议合同与预算证据通过；受控 artifact
|
||
不是最终 bundler 或 release installer。
|
||
- 用户于 2026-08-22 将 macOS x64/arm64 明确标记为 **Explicitly Waived /
|
||
Deferred** for `PI-000`。packaged resource path defect 已修并通过 focused path
|
||
test 与 Windows actual regression，但 macOS 没有实跑、不是 Pass；workspace/
|
||
staged/controlled packaged/loopback/metrics 全部移交 `PI-150`。
|
||
- 用户于 2026-08-22 明确接受四协议真实 Provider Account/兼容与真实双 worker
|
||
并发/隔离风险，`QG-004`、`QG-005` 为 Explicitly Waived / Accepted Risk，
|
||
不是 Pass。loopback 不得被归类为 Provider Account qualification，报告保持
|
||
`realTurnVerified=false`。
|
||
- Linux 最终 release artifact 与 macOS 全套实跑属于 `PI-150`；macOS 仍是
|
||
release blocker。当前 `PI-000` 无剩余 Phase-0 blocker，已解锁 `PI-010`、
|
||
`PI-020`、`PI-030`。
|
||
|
||
### Owns
|
||
|
||
- 精确 Pi version/tag/commit 决策。
|
||
- 最小 package pin 与 lockfile 变更。
|
||
- 最小 `scripts/probe-pi-runtime.*`、临时/受控 packaged probe、结果报告。
|
||
- 资格证据，不拥有最终 Chat、Host route 或迁移实现。
|
||
|
||
### Required work
|
||
|
||
1. 复核候选 `@earendil-works/pi-coding-agent@0.84.2`；锁定确切 package version、CLI entry、Node engine、RPC/session docs 对应 tag/commit。
|
||
2. 以 Electron Node 在 Phase-0 平台范围 Windows x64、Linux x64 的 unpackaged 与 packaged qualification seam 启动 RPC。
|
||
3. 验证 `get_state`、persistent session create/open、prompt accepted、abort、`agent_settled`、reopen、clean shutdown。
|
||
4. 从 frozen dependency graph stage Windows x64、Linux x64 的最小完整 production closure，验证 packaged qualification artifact 的 WASM/native/optional resources；最终产品 artifact 留给 `PI-150`。
|
||
5. 用 Windows/Linux packaged loopback 覆盖所有受支持协议的 base URL/path、headers、environment credential plumbing、模型、图片 request/SSE 合同；记录真实外部 Provider Account 验证已 Explicitly Waived / Accepted Risk，`realTurnVerified=false`。
|
||
6. 两个独立 worker 同时运行 provider-shaped loopback turn，证明受控时间窗口重叠、单侧 abort 与另一侧 settled；记录真实 provider 并发/串行/限流及跨 worker abort/event/session/model/credential 隔离为 Accepted Risk。
|
||
7. 在 Windows x64、Linux x64 运行 cold/warm/RSS/exit samples，报告 p50/p95/max、样本数、平台和 artifact 状态。
|
||
8. 明确 `AGENTS.md`/context、offline、trust、resource discovery、shell 的锁定版本行为。
|
||
|
||
macOS x64/arm64 在本票据中 Explicitly Waived / Deferred by user on
|
||
2026-08-22；这不是平台通过证据。对应 workspace/staged/controlled packaged/
|
||
loopback/metrics 工作由 `PI-150` 接管。
|
||
|
||
### Closure audit（2026-08-22）
|
||
|
||
| Required work | 审计状态 | 依据 |
|
||
| --- | --- | --- |
|
||
| 1. identity/pin/engine/entry | Pass | Pi 0.84.2、tag/commit、CLI、Electron Node engine 与 frozen lockfile 已确认 |
|
||
| 2. platform process seam | Pass + explicit macOS deferral | Windows x64 与 Linux x64 workspace/staged/controlled packaged 已通过；macOS x64/arm64 不是 Pass，转 `PI-150` |
|
||
| 3. session/RPC lifecycle | Pass | get_state、create/open、prompt accepted、abort、settled、reopen、clean shutdown 已通过 |
|
||
| 4. production closure/assets | Pass | Windows/Linux 适用 packages、WASM/native/optional assets 在 qualification artifact 可解析；最终 artifact 留 `PI-150` |
|
||
| 5. protocol compatibility | Explicitly Waived / Accepted Risk；替代 smoke Pass | 四协议 packaged loopback 的 base URL/path/header/environment credential plumbing/model/image request/SSE 已通过；真实外部 Provider 未验证且 `realTurnVerified=false` |
|
||
| 6. two-worker concurrency/isolation | Explicitly Waived / Accepted Risk；替代 smoke Pass | provider-shaped two-worker overlap、单侧 abort、另一侧 settled 与受控路由已通过；真实 provider 行为未验证 |
|
||
| 7. latency/RSS/exit budgets | Pass | Windows/Linux cold/warm/RSS/exit 样本与 p50/p95/max 已记录并满足预算 |
|
||
| 8. context/offline/trust/resources/shell | Pass | 锁定版本以 explicit no-discovery/no-context/no-approve/offline flags 运行，shell 与 abort 行为已验证 |
|
||
|
||
审计未发现除上述两类显式 waiver 外的未完成 Required work。Acceptance 的
|
||
非豁免证据均成立，Stop condition 没有已确认失败，因此 `QG-007` 不触发。
|
||
|
||
### Acceptance
|
||
|
||
- Spec `QG-001`、`QG-002`、`QG-003`、`QG-006` 在修订后的 Phase-0 平台范围内有可重复证据；`QG-004`、`QG-005` 有明确人类 waiver、完整风险记录和不可误标 Pass 的证据状态。
|
||
- cold `rpc.ready` p95 ≤ 3,000 ms；warm p95 ≤ 1,500 ms；10 秒 operational deadline 内确定性失败。
|
||
- 两 worker packaged provider-shaped loopback turn 重叠；一个 worker abort/crash 不改变另一个受控状态。真实外部 Provider turn 不属于 hard gate。
|
||
- 完整 dependency closure 从 Windows/Linux packaged qualification artifact resolve，退出无遗留 Pi child；最终产品 artifact closure 属于 `PI-150`。
|
||
- Packaged loopback matrix 覆盖当前实际支持的每种协议类型；真实外部 Account 兼容保持 `realTurnVerified=false` 和 Accepted Risk，不 silently fallback 或伪报 Pass。
|
||
- 精确 pin，不使用 `^`/`~`。
|
||
- macOS waiver 只允许 `PI-000` 不等待该平台，既不构成 macOS Pass，也不满足 `PI-150` 的 cross-platform acceptance。
|
||
- `QG-004`/`QG-005` waiver 只移除真实外部 Provider hard gate；Windows/Linux 及最终 artifact 的 packaged loopback/provider-shaped overlap/abort smoke 仍必须通过。
|
||
|
||
### Stop condition
|
||
|
||
若修订后 Phase-0 范围内未豁免的 packaging、provider-shaped contract/concurrency/abort 或预算不通过：本票据保持或重新进入 Blocked，停止后续实现。只能通过修订 Spec/ADR 选择“Pi SDK in Electron utility process”后重新验收；不得引入 OpenCode fallback 或 RPC/SDK 双生产路径。缺少已豁免的真实外部 Provider 样本不是失败，不触发 `QG-007`。延期的 macOS 验证若在 `PI-150` 失败，则必须阻断 release 并返工或修订架构，不得以本 waiver 放行。
|
||
|
||
### Verification
|
||
|
||
- Probe command 和结果可以在干净安装依赖后重跑。
|
||
- artifact dependency resolve verifier。
|
||
- 两 worker packaged provider-shaped loopback overlap/abort smoke；结果明确 `realTurnVerified=false`。
|
||
- process-tree clean-exit 检查。
|
||
|
||
## PI-010 — Conversation contracts and reducer
|
||
|
||
### Objective
|
||
|
||
先固化 vendor-neutral Conversation 领域协议，使 Main、Renderer 和测试不再围绕 OpenCode/Pi wire 结构耦合。
|
||
|
||
### Dependencies
|
||
|
||
- `PI-000`。
|
||
|
||
### Owns
|
||
|
||
- `electron/coding-runtime/contracts.ts` 或 shared 等价位置。
|
||
- `ConversationSnapshot`、`ConversationPatchEnvelope`、node/run/queue/context/interaction/model/error DTO。
|
||
- 统一 normalization reducer。
|
||
- `InMemoryConversationRuntime`。
|
||
- 锁定 Pi 版本的 wire fixture → product fixture 边界定义。
|
||
|
||
### Required work
|
||
|
||
1. 实现 Spec 第 5、10 节全部公开类型，公共 export 不导入 Pi/OpenCode。
|
||
2. reducer 支持 snapshot replace、严格 generation/seq、gap invalidation、message/block/tool/queue/interaction/compaction/subagent/context ops。
|
||
3. UI ID 与 durable source ID 分离；optimistic user node 通过 `clientRequestId` reconcile。
|
||
4. 用同一个 reducer 处理 live fixture 和 hydrated fixture。
|
||
5. 实现 in-memory runtime，供 Renderer/Host product tests 使用。
|
||
6. 明确 unknown op/schema 的 fail-closed 行为。
|
||
|
||
### Acceptance
|
||
|
||
- 混合 text/thinking/tool、parallel tools、tool error、retry、compaction willRetry、queue、interaction、subagent、unknown custom fixture 全通过。
|
||
- seq gap 只 invalidates 目标 Conversation；旧 generation patch 被丢弃。
|
||
- `toolResult` 不成为 message；cumulative tool output 不重复。
|
||
- `agent_end` fixture 不产生 idle；`agent_settled` 才产生 idle。
|
||
- Renderer contract test 没有任何 Pi/OpenCode import。
|
||
|
||
### Verification
|
||
|
||
- Focused contract/reducer unit tests。
|
||
- Type-level no-vendor import check 或 scoped `rg` assertion。
|
||
- Snapshot → patches → snapshot equivalence fixture。
|
||
|
||
## PI-020 — Project and Conversation schema v2 migration
|
||
|
||
### Objective
|
||
|
||
把项目/伙伴/Conversation 产品数据从 OpenCode runtime identity 中解耦，并保证一次性迁移可回退、不会误删用户数据。
|
||
|
||
### Dependencies
|
||
|
||
- `PI-000`。
|
||
|
||
### Owns
|
||
|
||
- `electron/coding-projects/project-config.ts`。
|
||
- `project-store.ts`、`conversation-store.ts`、migration/backup helpers。
|
||
- schema v2 types/tests。
|
||
- 项目、伙伴、空 Conversation 的 local-only create flow。
|
||
|
||
### Required work
|
||
|
||
1. 定义 project schema v2 `ProductModelRef` 和 model unresolved 状态。
|
||
2. 定义 Conversation schema v2、产品 UUID、optional Pi binding、opaque sessionKey。
|
||
3. 实现 schema v1 backup → model mapping → v2 atomic write。
|
||
4. 无唯一 model mapping 时保留 Agent，标记用户选择；禁止默认模型。
|
||
5. v1 Conversation metadata 备份后初始化空 v2，不将旧 OpenCode Session 放入 sidebar。
|
||
6. 只清理已证明未修改的 generated `.opencode/agent`；uncertain/modified 移到 backup。
|
||
7. project/partner/Conversation create 不调用 runtime。
|
||
|
||
### Acceptance
|
||
|
||
- stable Agent ID/name/prompt/skills/archive 完整保持。
|
||
- 无 backup 时绝不覆写 v1；任意写失败保留可重试原状态。
|
||
- `sessionKey` path traversal/absolute path 被拒绝。
|
||
- 两个并发首发只建立一个 Pi session binding（通过 store single-flight contract fixture；实际 runtime 在后续票据接入）。
|
||
- 旧 Conversation 不显示；一次性 notice 状态可被 UI 后续消费。
|
||
- userData/opencode 和不确定 `.opencode` 内容未被递归删除。
|
||
- 项目、伙伴、Conversation metadata 性能可单独测量，且无 child process。
|
||
|
||
### Verification
|
||
|
||
- Migration table tests：unique/unresolved/no-account/corrupt write/retry/modified Agent file。
|
||
- Atomic persistence tests。
|
||
- Local-create integration test with spawn spy = 0。
|
||
|
||
## PI-030 — Pi process and RPC foundation
|
||
|
||
### Objective
|
||
|
||
提供可打包、可测试、可恢复的 Pi child process/RPC 底座，不掺入项目 CRUD 或 Renderer 逻辑。
|
||
|
||
### Dependencies
|
||
|
||
- `PI-000`。
|
||
|
||
### Owns
|
||
|
||
- `electron/coding-runtime/pi/worker-process.ts`。
|
||
- `rpc-framer.ts`、`rpc-client.ts`、process errors。
|
||
- 初版 `scripts/bundle-pi-runtime.mjs` 与 runtime manifest。
|
||
- programmable fake Pi child test fixture。
|
||
|
||
### Required work
|
||
|
||
1. Electron Node + `ELECTRON_RUN_AS_NODE=1` 启动锁定 Pi entry。
|
||
2. 显式 offline/no-approve/no-auto-resource 参数；stdout RPC only、stderr log only。
|
||
3. 自有 strict LF framer，支持 chunk 边界和 U+2028/U+2029。
|
||
4. command ID correlation、out-of-order response、event dispatch、timeout/AbortSignal。
|
||
5. malformed/oversized stdout、unexpected exit、stderr sanitizer、backpressure。
|
||
6. process graceful shutdown 3 秒 + forced kill，确保整个 child tree 清理。
|
||
7. stage 完整 production closure 与 manifest。
|
||
8. 为已发布 Pi package 的 production-only shrinkwrap 与 root 10 个
|
||
devDependencies 不同步选择并测试一个显式、可复现的永久 staging 机制；
|
||
不把 `PI-000` 临时副本处理或受控 Electron Builder probe 直接当成最终
|
||
bundler。artifact verifier 按可解析 package/version/asset 验证 closure，
|
||
不把 Electron Builder 的同版本依赖扁平化误判为缺失。
|
||
|
||
### Acceptance
|
||
|
||
- Spec `RPC-001`～`RPC-005` 全部通过。
|
||
- stdout 任意非 JSONL 导致目标 worker protocol error，不污染其他 worker。
|
||
- pending command 在 exit/abort/generation invalidation 时全部 settle，无 promise leak。
|
||
- prompt 类 command timeout 不自动重发。
|
||
- fake child 可脚本化输出 response/event/crash/partial line/large line，供后续 Main integration 使用。
|
||
- bundler 在 frozen install 上确定性生成相同 manifest 内容（不要求额外 checksum 文件）。
|
||
- 永久 staging 能在 npm 11 下从发布 package/shrinkwrap 可重复生成 production
|
||
closure，且测试覆盖 root devDependencies 不同步与同版本 nested-to-root
|
||
flattening；不依赖开发机已有 `node_modules` 或受控 probe 的临时目录。
|
||
|
||
### Verification
|
||
|
||
- Focused process/RPC unit tests。
|
||
- Real Pi `get_state` protocol smoke。
|
||
- Packaged entry load/exit smoke。
|
||
|
||
## PI-040 — Provider and managed resources
|
||
|
||
### Objective
|
||
|
||
把当前 Provider Account、Works gateway、credential、伙伴 prompt 和 skills 映射为锁定 Pi 版本的受管输入，同时保持 Main-owned secret/trust 边界。
|
||
|
||
### Dependencies
|
||
|
||
- `PI-020`。
|
||
- `PI-030`。
|
||
|
||
### Owns
|
||
|
||
- `electron/coding-runtime/pi/provider-config.ts`。
|
||
- `resource-loader.ts`、prompt/Agent manifest cache。
|
||
- `resources/coding-skills` 与 registry 映射。
|
||
- Provider revision/staleness contract。
|
||
|
||
### Required work
|
||
|
||
1. 实现 `PiProviderDescriptor` 和 account → runtime catalog 投影。
|
||
2. 迁移 Works `/v1`、proxy token、custom header/base URL 语义。
|
||
3. credential 只通过 worker environment/受管 provider 注入，完整日志脱敏。
|
||
4. account refresh single-flight；认证恢复最多一次。
|
||
5. provider/resource revision：idle stale 下次 prompt 前重建，running settled 后重建。
|
||
6. 生成受管伙伴 prompt/Agent manifest，不生成 `.pi/agents`。
|
||
7. 移动内建 skills 到 vendor-neutral resources，仅显式传 selected paths。
|
||
|
||
### Acceptance
|
||
|
||
- 当前支持的每种 Provider Account/协议配置 fixture 都能构建有效 catalog，并通过
|
||
packaged provider-shaped loopback 完成 prompt/settled；真实外部 Provider prompt
|
||
保持可选、非阻断，未取得证据时 `realTurnVerified=false`。
|
||
- 两个同 vendor account 的 runtime ID 不冲突。
|
||
- model/image capability 校验准确；不可用模型原子失败。
|
||
- token/header/prompt 内容不出现在 argv、snapshot、SSE、Renderer、diagnostics 或 test snapshot。
|
||
- 项目/用户 `.pi` resources 不被自动加载。
|
||
- provider revision 不打断 running run；settled 后才重建。
|
||
|
||
### Verification
|
||
|
||
- Provider catalog fixtures。
|
||
- Secret-redaction tests over argv/env-safe projection/stderr/API DTO。
|
||
- Resource discovery negative tests。
|
||
- Packaged provider-shaped loopback smoke from qualification matrix；可选 real account
|
||
smoke 只能作为非阻断诊断，不得把 waiver 改写为 Pass。
|
||
|
||
## PI-050 — Worker pool and session registry
|
||
|
||
### Objective
|
||
|
||
实现一 Conversation 一 worker 的真实并发、session 持久绑定、资源调度和生命周期隔离。
|
||
|
||
### Dependencies
|
||
|
||
- `PI-010`。
|
||
- `PI-020`。
|
||
- `PI-030`。
|
||
- `PI-040`。
|
||
|
||
### Owns
|
||
|
||
- `electron/coding-runtime/pi/runtime.ts`。
|
||
- `worker-pool.ts`、session registry、permit queue、idle LRU。
|
||
- prepare/prompt/queue/abort/model/thinking/compact/fork/dispose lifecycle orchestration。
|
||
- telemetry base/span correlation。
|
||
|
||
### Required work
|
||
|
||
1. per-Conversation `prepare` single-flight 和 lazy session open/create。
|
||
2. worker state machine、generation、pending commands/interactions/children references。
|
||
3. top-level running cap 4、warm idle cap 4、total process soft cap integration。
|
||
4. running 不 eviction，idle LRU，app quit shutdown。
|
||
5. prompt/steer/follow-up acceptance，不等待 settle。
|
||
6. abort/model/thinking/compact/fork/recover/dispose 目标隔离。
|
||
7. Provider/resource stale 在安全边界重建。
|
||
8. `worker.queue_wait/spawn/rpc.ready/session.open/resources.ready/prompt.accepted` telemetry。
|
||
|
||
### Acceptance
|
||
|
||
- 一 worker 永不并行承载两个 Conversation。
|
||
- 第 5 个 top-level run 进入自己的 queue；前四个 settled 后按公平顺序继续。
|
||
- running worker 不被 LRU kill；idle 超限准确 eviction/reopen。
|
||
- crash generation 清理 pending RPC/permit/interaction/child reference，并不影响其他 worker。
|
||
- prompt HTTP/RPC acceptance 与 run completion 分离。
|
||
- model/thinking 只改变目标 Conversation；不可用模型不改变旧状态。
|
||
- app quit 3 秒后无遗留 parent worker。
|
||
|
||
### Verification
|
||
|
||
- Worker-pool focused tests：single-flight、caps、fair queue、LRU、crash、quit、stale revision。
|
||
- Two-worker fake + packaged provider-shaped loopback concurrent run integration；真实外部 Provider 非阻断且不得写成已验证。
|
||
- Process-tree cleanup test。
|
||
|
||
## PI-060 — Event projector, hydration, and recovery
|
||
|
||
### Objective
|
||
|
||
把 Pi live RPC 和 persisted session tree 正确投影为 Makelore Snapshot/Patch，解决 streaming identity、active branch、settled reconciliation 和恢复。
|
||
|
||
### Dependencies
|
||
|
||
- `PI-010`。
|
||
- `PI-050`。
|
||
|
||
### Owns
|
||
|
||
- `event-projector.ts`。
|
||
- `session-projector.ts`。
|
||
- attachment projection hooks。
|
||
- snapshot creation、durable reconcile、recover orchestration integration。
|
||
|
||
### Required work
|
||
|
||
1. 按 `contentIndex` 组装 text/thinking/toolcall；`message_end` 权威替换。
|
||
2. cumulative `partialResult` replace；`toolResult` attach tool card。
|
||
3. run/turn/retry/compaction/queue/interaction/usage/context 映射。
|
||
4. `agent_end` checkpoint、`agent_settled` idle。
|
||
5. entries + leafId + parentId active path hydration；废弃分支排除。
|
||
6. live UI ID 与 durable entry ID reconcile。
|
||
7. generation/seq envelope、gap invalidation、snapshot rebuild。
|
||
8. unknown/custom bounded diagnostics、large image attachment ref。
|
||
9. recover：旧 generation close、资源清理、reopen、hydrate、新 snapshot。
|
||
|
||
### Acceptance
|
||
|
||
- Spec 第 10、11、18 节 event/session/failure 规则全部有 fixture。
|
||
- live run 完成后的 Snapshot 与从 session 冷 hydrate 的 Snapshot 等价。
|
||
- compaction `willRetry` 不 idle；queue continuation 不提前释放 permit。
|
||
- abandoned branch 永不进入 active timeline。
|
||
- tool partial output 不重复；camel-case `toolResult` 不变 assistant。
|
||
- SSE gap/recover 只替换目标 Conversation。
|
||
- unreadable session 保留原文件并进入 recoverable error，不自动截断。
|
||
|
||
### Verification
|
||
|
||
- Projector/session unit fixtures from exact Pi version。
|
||
- Fake Pi end-to-end run → settle → reopen comparison。
|
||
- Small real Pi drift smoke。
|
||
|
||
## PI-070 — Managed extension host, interactions, and write lease
|
||
|
||
### Objective
|
||
|
||
建立唯一受管 extension entry、最小 child→Main seam、用户 interaction 和同项目 mutation lease。
|
||
|
||
### Dependencies
|
||
|
||
- `PI-040`。
|
||
- `PI-060`。
|
||
|
||
### Owns
|
||
|
||
- `extensions/makelore-runtime.ts`。
|
||
- extension internal endpoint/IPC bridge 与 worker token registry。
|
||
- `interaction.ts`、`write-lease.ts`。
|
||
- interaction Host-side store and projector integration。
|
||
|
||
### Required work
|
||
|
||
1. 只显式加载一个 versioned extension bundle。
|
||
2. 每 worker loopback/IPC token，dispose/recover 后失效。
|
||
3. 验证 conversationId/generation/runId 与 worker registry。
|
||
4. `ask_user` select/confirm/input/editor；notify/status/widget/title/editor-text 安全投影。
|
||
5. 同项目 mutation write lease、可取消等待、所有终态释放。
|
||
6. worker crash/abort 清理 interaction/lease。
|
||
7. unknown UI/widget/details 只诊断，不 raw dump。
|
||
|
||
### Acceptance
|
||
|
||
- 项目/用户第三方 Pi extension 不会被加载。
|
||
- 伪造旧 generation/token 的 request 被拒绝且不影响当前 worker。
|
||
- interaction response 严格按 ID；crash/abort 后全部 cancelled。
|
||
- 同项目 mutation 串行；不同项目并行；read-only 不等待 lease。
|
||
- complete/error/abort/timeout/crash 全部释放 lease，无永久占用。
|
||
- Textarea draft revision 已变化时 `set_editor_text` 不覆盖。
|
||
|
||
### Verification
|
||
|
||
- Extension integration tests through real bridge, not direct function-only mocks。
|
||
- Lease concurrency/cancellation matrix。
|
||
- Interaction lifecycle and stale-token tests。
|
||
|
||
## PI-080 — Subagent scheduler and nested protocol
|
||
|
||
### Objective
|
||
|
||
用 Makelore-owned `subagent.v1` 实现多 child Pi 调度，不依赖官方示例的非稳定 GUI details。
|
||
|
||
### Dependencies
|
||
|
||
- `PI-070`。
|
||
|
||
### Owns
|
||
|
||
- `extensions/subagent.ts`。
|
||
- child process supervisor、global semaphore、parent-child registry。
|
||
- `subagent.v1` schema/projector fixtures。
|
||
|
||
### Required work
|
||
|
||
1. `single`、`parallel`、`chain` dispatch validation；单次最多 8 tasks。
|
||
2. 每 child 独立 Pi process/context，使用受管 Agent manifest/model/tool profile。
|
||
3. 全应用最多 4 running child，和 parent process 组成 soft cap 8。
|
||
4. read-only/coding tool profile；coding child 接入 write lease。
|
||
5. parent abort/crash 传播 child；child exit 清理 permit。
|
||
6. parallel 保留其他完成结果；chain 首失败停止并标 skipped。
|
||
7. nested progress/details 只输出 `subagent.v1`。
|
||
|
||
### Acceptance
|
||
|
||
- 1、4、8 tasks 的 single/parallel/chain fixture 正确；第 9 个 schema validation 拒绝。
|
||
- 两个 parent 争用全局 child semaphore 时总 running child ≤ 4。
|
||
- parent abort 后无 child orphan；permit 全释放。
|
||
- 一个 parallel child failure 不删除其他 summary/usage；chain 后续标 skipped。
|
||
- unknown schema/version 不崩 UI、不 dump raw JSON。
|
||
- 同项目 coding child 与 parent mutation 遵守同一 lease。
|
||
|
||
### Verification
|
||
|
||
- Fake child scheduler integration tests。
|
||
- One real subagent child packaged smoke。
|
||
- Process-tree and semaphore leak check。
|
||
|
||
## PI-090 — Product tools and Conversation change tracker
|
||
|
||
### Objective
|
||
|
||
迁移 Makelore 真实使用的 browser、game asset、task/changed-file 和 skill 能力，并以 Main-owned tracker 替代 OpenCode Session diff。
|
||
|
||
### Dependencies
|
||
|
||
- `PI-020`。
|
||
- `PI-070`。
|
||
|
||
### Owns
|
||
|
||
- `extensions/agent-browser.ts`、`game-assets.ts`、`task-state.ts`、`changed-file.ts`。
|
||
- `electron/coding-projects/skill-registry.ts`。
|
||
- `conversation-change-tracker.ts`。
|
||
- Main browser/attachment integration at the existing seam。
|
||
|
||
### Required work
|
||
|
||
1. `agent_browser` extension 直连现有 Main browser service；删除对 MCP 的运行时依赖。
|
||
2. 迁移现有 game asset browse/review 产品语义，不复制 OpenCode plugin API。
|
||
3. `task_state` 使用版本化 typed details；不暴露旧 todos endpoint。
|
||
4. `changed_file` 上报 relative touched paths。
|
||
5. run start 记录 git head/status baseline；settled 后刷新 status/diff，bash 触发 project-level refresh。
|
||
6. 只读 changed path diff；untracked 有界 preview；无 per-file hash/checkpoint。
|
||
7. selected skills registry 与 command catalog 安全投影。
|
||
|
||
### Acceptance
|
||
|
||
- browser tool 不启动 `@playwright/mcp`/MCP child，screenshot 使用 attachment ID。
|
||
- game asset/product tool 有 real/fake integration coverage。
|
||
- changes panel 数据不来自 Pi message 文本猜测。
|
||
- write/edit touched path 精准刷新；bash 后能发现未上报改动。
|
||
- untracked preview 有界且无绝对路径。
|
||
- fork UI 不暗示文件回滚。
|
||
- 没有为 diff 增加 hash/checkpoint framework。
|
||
|
||
### Verification
|
||
|
||
- Browser/game tool packaged smoke。
|
||
- Git/no-git/dirty/untracked/bash change tracker tests。
|
||
- Skill command and explicit-path tests。
|
||
|
||
## PI-100 — Core `/api/coding` Host API
|
||
|
||
### Objective
|
||
|
||
用产品域 Host API 连接 project/conversation service、runtime Snapshot/Patch 和 interactions，完全移除 Renderer 对 OpenCode route contract 的依赖。
|
||
|
||
### Dependencies
|
||
|
||
- `PI-020`。
|
||
- `PI-060`。
|
||
- `PI-070`。
|
||
|
||
### Owns
|
||
|
||
- `electron/api/routes/coding-projects.ts`。
|
||
- `electron/api/routes/coding-conversations.ts`。
|
||
- `/api/coding/events` SSE。
|
||
- interactions route、runtime diagnostics 安全投影。
|
||
- Renderer typed facade 的 Main contract half。
|
||
|
||
### Required work
|
||
|
||
1. 实现 Spec 第 12.1 节除 files/skills/changes 外的核心 routes。
|
||
2. prompt/steer/follow-up 返回 HTTP 202 acceptance；不等待 settle。
|
||
3. `clientRequestId` bounded dedupe 与 uncertain request 行为。
|
||
4. SSE envelope、per-Conversation seq/generation、snapshot-first reconnect。
|
||
5. request validation、conversation/project ownership、sanitized errors。
|
||
6. diagnostics 只给 worker state/revision/stage summary，无 secret/absolute session path。
|
||
7. interactions list/respond ID correlation。
|
||
|
||
### Acceptance
|
||
|
||
- Renderer-facing core route 中不出现 `/api/opencode` 或 Pi wire field。
|
||
- project/partner/Conversation create route 不启动 runtime。
|
||
- prompt 202 在 provider first token/settled 前返回。
|
||
- seq gap test 只 GET 目标 snapshot；SSE reconnect 不重发 prompt。
|
||
- duplicate accepted `clientRequestId` 返回相同 acceptance；uncertain mutation 不二次发送。
|
||
- raw stderr/provider/extension path/credential 不穿透。
|
||
|
||
### Verification
|
||
|
||
- Route contract tests with in-memory and fake Pi runtime。
|
||
- Host API → SSE → snapshot integration。
|
||
- Error redaction and timeout tests。
|
||
|
||
## PI-105 — Files, changes, skills, and command Host API
|
||
|
||
### Objective
|
||
|
||
提供 vendor-neutral project file、search、changes、skills 和 command API，使 Renderer 不再依赖 OpenCode 的文件/Session diff/todo 路由。
|
||
|
||
### Dependencies
|
||
|
||
- `PI-020`。
|
||
- `PI-090`。
|
||
|
||
### Owns
|
||
|
||
- `electron/api/routes/coding-files.ts`。
|
||
- file/status/find/content/search facade。
|
||
- Conversation changes、skills、commands route integration。
|
||
- Renderer typed facade 的 file/tool catalog contract half。
|
||
|
||
### Required work
|
||
|
||
1. 迁移现有受支持 file status/find/content/search 行为到 product service。
|
||
2. 所有 path 相对 active project，保持现有内容/搜索边界。
|
||
3. expose Conversation changes snapshot，不 expose Pi/session diff。
|
||
4. 合并 Pi extension/skill commands 与 Makelore commands，稳定 DTO。
|
||
5. 删除 todos/revert/unrevert/share 相关 API 外形。
|
||
|
||
### Acceptance
|
||
|
||
- Renderer 无绝对项目路径和任意 filesystem proxy 能力。
|
||
- files/search 行为与现有受支持 UX 等价。
|
||
- changes 与 target Conversation/run 关联，数据来自 tracker。
|
||
- skills/commands 只包含显式受管资源。
|
||
- route/type/test 中无旧 todos/share/revert contract。
|
||
|
||
### Verification
|
||
|
||
- Focused file/search/change/command route tests。
|
||
- Path boundary and redaction tests。
|
||
- Renderer facade contract tests。
|
||
|
||
## PI-110 — Renderer Snapshot/Patch store
|
||
|
||
### Objective
|
||
|
||
建立按 Conversation 分片、可 gap recovery、无 vendor import 的 Renderer 状态层和 typed Host facade。
|
||
|
||
### Dependencies
|
||
|
||
- `PI-010`。
|
||
- `PI-100`。
|
||
|
||
### Owns
|
||
|
||
- `src/stores/coding-conversations.ts`。
|
||
- `src/types/coding-conversation.ts` 或 shared re-export。
|
||
- `src/lib/coding-conversations.ts`/existing Host API facade integration。
|
||
- SSE subscription/reconnect、snapshot loader、draft state。
|
||
|
||
### Required work
|
||
|
||
1. 每 Conversation 独立 snapshot/run/error/queue/model/draft/unread/cursor。
|
||
2. Snapshot first load + SSE live，generation/seq/gap reducer。
|
||
3. hidden Conversation 只更新 lightweight summary。
|
||
4. optimistic user node/draft revision/clientRequestId reconciliation。
|
||
5. target-only error/recover；top-level error 只用于真实全局错误。
|
||
6. Selector 粒度避免 token 时全 store rerender。
|
||
|
||
### Acceptance
|
||
|
||
- 两 Conversation simultaneous patch 不串 node/run/error/queue/model/draft。
|
||
- seq gap 只刷新目标；旧 generation 丢弃。
|
||
- optimistic accept/reject/uncertain state 可恢复 draft/附件。
|
||
- hidden Conversation streaming 不触发其 Markdown component render。
|
||
- store/facade/types 无 Pi/OpenCode import/name。
|
||
- 旧 `src/stores/opencode.ts` 不再被新 UI 读取；实际删除留 `PI-140`。
|
||
|
||
### Verification
|
||
|
||
- Store reducer/selector tests。
|
||
- Two-Conversation SSE integration。
|
||
- Render-count fixture for hidden/current Conversation。
|
||
|
||
## PI-120 — Core Chat and first-Conversation UX
|
||
|
||
### Objective
|
||
|
||
交付 vendor-neutral Chat core，彻底修复首次 Conversation 输入框被全局 runtime/loading 阻塞，并控制流式渲染成本。
|
||
|
||
### Dependencies
|
||
|
||
- `PI-110`。
|
||
|
||
### Owns
|
||
|
||
- `CodingChatPanel` 核心组合层。
|
||
- Composer、message/timeline/tool blocks 的 vendor-neutral components。
|
||
- optimistic prompt/recover UI。
|
||
- delta batching/attachment preview/render performance。
|
||
|
||
### Required work
|
||
|
||
1. Textarea enable rule严格实现 `UX-010`～`UX-014`。
|
||
2. create/select Conversation 不等待 runtime；prewarm 仅显示局部状态。
|
||
3. first send optimistic node、202 acceptance、preparing/queued/running/error/recover UI。
|
||
4. message/thinking/tool/compaction/boundary 基础渲染。
|
||
5. 16–33 ms Main batching 的 Renderer局部 block 更新；memo/折叠/虚拟化。
|
||
6. attachment ID/preview URL，不持有重复 base64。
|
||
7. 组件拆分，避免把旧 4k 行面板机械改名。
|
||
|
||
### Acceptance
|
||
|
||
- Runtime/metadata response 被测试故意 hold 时，selected Agent 的 Textarea 仍可输入。
|
||
- fresh userData 选择首 Conversation → Composer p95 ≤ 500 ms。
|
||
- cold local prepare 超过 10 秒显示 recoverable error，Textarea 仍可编辑。
|
||
- prompt accepted 前后 user node不丢；Provider error 不回滚 user message。
|
||
- 100 KB cumulative tool/长 thinking 下 Main delta → Renderer commit p95 ≤ 50 ms，输出不重复。
|
||
- hidden Conversation 不做全文 Markdown rerender。
|
||
|
||
### Verification
|
||
|
||
- Red-capable first-Conversation component test。
|
||
- Core Chat focused tests。
|
||
- Render commit/IPC payload benchmark fixture。
|
||
- First prompt Electron E2E。
|
||
|
||
## PI-130 — Feature-complete Coding UI
|
||
|
||
### Objective
|
||
|
||
在新协议上补齐需要保留的 Code 产品能力和多会话/subagent 交互，使旧 OpenCode UI 可以完整拆除。
|
||
|
||
### Dependencies
|
||
|
||
- `PI-080`。
|
||
- `PI-090`。
|
||
- `PI-105`。
|
||
- `PI-120`。
|
||
|
||
### Owns
|
||
|
||
- model/thinking controls。
|
||
- steer/follow-up queue UI。
|
||
- compaction/retry/context UI。
|
||
- interactions、subagent nested graph、changes/files/browser/skills/commands UI。
|
||
- Conversation fork/title/archive/unread/recover/diagnostics UI。
|
||
|
||
### Required work
|
||
|
||
1. model/thinking Conversation setting，与伙伴默认分离。
|
||
2. queue 两种 mode、position、等待和 abort。
|
||
3. retry/compaction willRetry/settled 正确生命周期。
|
||
4. select/confirm/input/editor interactions 与 stale/cancelled 状态。
|
||
5. `subagent.v1` nested nodes、parallel/chain error/abort。
|
||
6. Conversation changes/file preview、browser attachment、skills/commands。
|
||
7. “从这里创建新对话分支”替代 revert 文案，不暗示文件回滚。
|
||
8. 删除 share/todo/global runtime controls 的产品入口。
|
||
|
||
### Acceptance
|
||
|
||
- 文本、图片、thinking、tools、retry、compaction、queue、interaction、model/thinking、files/changes、browser、skills 全部可在新 UI 使用。
|
||
- 两 Conversation 同时 streaming，切换/隐藏/abort/model 互不污染。
|
||
- subagent single/parallel/chain nested UI 正确；child error/abort 可理解。
|
||
- `agent_end` 不清 busy；`agent_settled` 才释放 queue。
|
||
- tool result 不独立 bubble；compaction summary/raw custom details 不泄露。
|
||
- share/unshare/revert/unrevert/todos/global runtime controls UI 不存在。
|
||
|
||
### Verification
|
||
|
||
- Focused UI tests for every retained/removed behavior。
|
||
- Electron E2E：concurrency、model、queue、compaction、interaction、subagent、image、browser/skill、recover。
|
||
|
||
## PI-140 — OpenCode removal and cutover migration
|
||
|
||
### Objective
|
||
|
||
在新链路达到 feature completeness 后，删除所有生产 OpenCode 源码、依赖、route、资源、脚本和旧 UI，并接通最终一次性迁移/提示。
|
||
|
||
### Dependencies
|
||
|
||
- `PI-130`。
|
||
|
||
### Owns
|
||
|
||
- 删除 `electron/opencode`、OpenCode route/manager/client/materialization/provider/plugin code。
|
||
- 删除/重命名 `src/*opencode*`、`shared/opencode-*`、旧 tests/E2E。
|
||
- package/lockfile OpenCode 与 MCP dependency removal。
|
||
- `.opencode` packaged resources、bundle/smoke script removal。
|
||
- 迁移 notice、legacy data inert policy、release-facing removed-feature copy。
|
||
|
||
### Required work
|
||
|
||
1. 删除 `/api/opencode/*` 与 Renderer 调用。
|
||
2. 删除 `opencode-ai`、`@opencode-ai/plugin`、仅服务 OpenCode 的 `@playwright/mcp`。
|
||
3. 删除 manager/client/project-agent-runtime/provider-config/playwright-mcp/plugin materialization。
|
||
4. 删除旧 store/types/normalizer/panel/runtime controls/diff preview 和浅 Implementation tests。
|
||
5. 删除 share/unshare/revert/unrevert/todos/global runtime controls 的 route/type/test/doc copy。
|
||
6. 移动保留的 product skills/assets 到 vendor-neutral 资源。
|
||
7. 接通 schema migration、一次性 notice、userData inert/no-read。
|
||
8. 保持 app id/protocol/storage identifiers。
|
||
|
||
### Acceptance
|
||
|
||
- 生产源码/route/dependency/runtime resource 不包含 OpenCode。
|
||
- `rg -i` 只命中明确允许的历史/迁移文本，并逐项分类记录。
|
||
- package/lockfile 无 OpenCode package/plugin/MCP dependency。
|
||
- 新应用不读取项目 `.opencode` 或 `<userData>/opencode`。
|
||
- uncertain/modified `.opencode/agent` 被 backup，未误删。
|
||
- stable Agent IDs/app id/protocol/storage 保持。
|
||
- 全部 Code UI/Host tests 已指向 `/api/coding` 和新 store。
|
||
|
||
### Verification
|
||
|
||
- Zero-residue source/package search。
|
||
- Migration E2E from schema v1 fixture。
|
||
- Full focused Code tests + typecheck/build before `PI-150`。
|
||
|
||
## PI-150 — Packaging, E2E, and performance release proof
|
||
|
||
### Objective
|
||
|
||
把硬切换打成可发布 artifact，运行完整自动化、真实 Pi、三平台和性能验收，产出可审阅证据。
|
||
|
||
### Dependencies
|
||
|
||
- `PI-140`。
|
||
|
||
### Owns
|
||
|
||
- 最终 `bundle-pi-runtime`、electron-builder staging、artifact verifier。
|
||
- `smoke:pi:real`。
|
||
- rewritten/new Electron E2E suite。
|
||
- performance harness/report、release note/runbook draft、README current product update。
|
||
- feature task verification record与 promotion candidates；canonical docs 留 `PI-160` Integration Gate。
|
||
|
||
### Required work
|
||
|
||
1. stage exact Pi production closure、extensions、skills、manifest。
|
||
2. artifact verifier 检查 version/engine/resources/resolve/get_state/no-OpenCode/no-dev-path。
|
||
3. actual packaged Pi smoke：通过受控 loopback/provider-shaped endpoint 覆盖 session、prompt、tool、abort、settle、reopen、two-worker overlap/isolation、subagent、shutdown；不要求真实外部 Provider Account，报告保持 `realTurnVerified=false`。
|
||
4. 完整 typecheck/lint/unit/build/E2E。
|
||
5. Windows x64、Linux x64 最终产品 artifact 的 packaged verifier/smoke。
|
||
6. 对 macOS x64 与 arm64 分别使用独立 checkout/frozen install，运行 workspace 5+5、staged 5+5、controlled packaged 5+5、packaged loopback、closure/native/resource 检查和 metrics，再验证各自最终目标 artifact；不得用静态 path test、其他平台结果或 `PI-000` waiver 替代。
|
||
7. Spec 第 17.3 节全部场景，报告 p50/p95/max/samples/RSS/IPC/commit。
|
||
8. release note：旧 Conversation、删除能力、完整版本回退、Pi 新 Conversation 不兼容旧版。
|
||
9. README 同步当前 runtime/功能，不写历史迁移日记。
|
||
|
||
### Acceptance
|
||
|
||
- `pnpm run typecheck`、`pnpm run lint:check`、`pnpm test`、`pnpm run build:vite`、`pnpm run test:e2e` 全通过。
|
||
- artifact verifier 与 real Pi smoke 全通过。
|
||
- 最终 packaged 四协议 loopback、provider-shaped two-worker overlap、单侧 abort 与另一侧 settled 全通过；真实外部 Provider waiver 不是 Pass，也不是 release blocker。
|
||
- Windows x64、Linux x64、macOS x64、macOS arm64 目标 artifact 与对应验证全部通过；macOS 任一架构缺失即不允许宣称 cross-platform release-ready。
|
||
- `PI-000` 的 macOS Explicitly Waived / Deferred 到本票据即失效；延期造成 release-stage packaging/native/resource/performance 返工的风险已经接受，但任何实际失败仍必须阻断 release。
|
||
- Composer、worker、acceptance、render p95 全达 Spec 预算。
|
||
- 4 parent + 4 child 压力下 UI 可交互，无 orphan process/permit/lease。
|
||
- 最终 artifact 无 OpenCode package/binary/plugin/resource、无开发机绝对路径。
|
||
- 性能报告分离本地 overhead 与受控 provider-shaped first-event，不使用一次体验替代统计；可选真实外部 Provider 样本只能作为非阻断诊断。
|
||
|
||
### Verification
|
||
|
||
- 保存命令、版本、artifact、平台、样本数和结果摘要到 task evidence。
|
||
- macOS x64/arm64 分架构保存 workspace/staged/controlled packaged/loopback/metrics 与最终 artifact 实跑证据；不得只记录 waiver 或静态测试。
|
||
- 保存最终 packaged loopback/provider-shaped concurrency/abort 证据并明确 `realTurnVerified=false`；不得因缺少真实外部 Account/credential 把 release 标为 Blocked，也不得把 waiver 写成 Pass。
|
||
- 对允许的 `opencode` 搜索命中逐项解释。
|
||
- 更新 task record 的验证和未完成外部环境项；任何 release 阻断不得藏在 follow-up。
|
||
|
||
## PI-160 — Integration and release gate
|
||
|
||
### Objective
|
||
|
||
以 Integration Task 所有权完成最终 Spec/Standards 审阅、合并验证、canonical memory 提升和 release go/no-go；不让 feature branch 的自证替代集成事实。
|
||
|
||
### Dependencies
|
||
|
||
- `PI-150`。
|
||
|
||
### Owns
|
||
|
||
- Integration Task record、merge/rebase conflict handling。
|
||
- merge tree 的最终验证与独立 Spec/Standards review。
|
||
- accepted ADR、canonical current state/architecture/data flow/domain/success/evidence/commitments 清理。
|
||
- release decision、tag/runbook handoff；不自动 push/release，除非用户另行授权。
|
||
|
||
### Required work
|
||
|
||
1. 重新运行 Concurrent Task Gate，确认 main/worktree ownership 和最新 base。
|
||
2. 集成完整 feature tip，不选择性合并会留下双 runtime 的部分提交。
|
||
3. 在 merge tree 重跑风险相称的 focused/full/build/E2E/artifact/real smoke/perf checks。
|
||
4. 对照 `ML-CODE-PI-001` 逐条审阅，不以 ticket 自报 Done 代替证据。
|
||
5. 新增 accepted ADR：Pi 唯一 runtime、无 OpenCode fallback。
|
||
6. 更新 system overview/module map/data flow/business rules/success criteria/current state/README/evidence。
|
||
7. 关闭或改写仅对 OpenCode 有意义的 model-switch、dual-session、compaction、saturation commitments。
|
||
8. 执行零残留和 release note/rollback runbook 审阅。
|
||
|
||
### Acceptance
|
||
|
||
- 全部 Spec requirements 和 DoD 有可追踪证据，无未解释偏离。
|
||
- merge tree 与 feature tree 验证一致，无 main 回归。
|
||
- accepted ADR 和 canonical docs 描述实际 Pi 架构，不提前声称未跑的 macOS 或已豁免的真实外部 Provider 证据通过。
|
||
- accepted ADR、release note 与风险记录明确真实外部 Provider compatibility/concurrency/isolation 是用户接受的未验证风险，不声称 Pass；macOS x64/arm64 仍须有实际发布证据。
|
||
- OpenCode commitments 不再伪装为当前待办；需要保留的历史证据仍可追踪。
|
||
- 无 runtime fallback/compat layer/old route/dependency/artifact。
|
||
- release go/no-go 明确；若任一硬门不通过，状态保持 Blocked，不发布。
|
||
|
||
### Verification
|
||
|
||
- Integration Gate scripts、documentation drift gate。
|
||
- Final full command suite + artifact/real/runtime/performance evidence review。
|
||
- Independent human/reviewer Spec and Standards review；不要求特定智能体机制。
|
||
|
||
## 6. 票据状态模板
|
||
|
||
后续若同步为 task/issue，每张票据至少维护：
|
||
|
||
```text
|
||
Status: Pending | Ready | In progress | Blocked | Done
|
||
Depends on: <ticket ids>
|
||
Owner/worktree: <explicit owner>
|
||
Owned files/responsibility: <bounded scope>
|
||
Acceptance evidence: <tests, artifacts, measurements>
|
||
Contract changes: <none or linked upstream update>
|
||
Blockers: <concrete unmet condition>
|
||
```
|
||
|
||
禁止使用“代码基本完成”“看起来正常”“后续再测”作为 Done 证据。阻断项如果属于 Spec 硬门，必须留在当前 ticket，不得降级为 release 后 follow-up。
|