mnote/design/07-ai/done/7-69-page-ai-pi-first-lab-checklist-v1.md

# 7-69 Page AI Pi-first Lab Spike Checklist v1

状态：done（最小可验证 spike）
Owner：07-ai / mnote-web / control-plane
日期：2026-07-04

## 1. 结论

7-69 的最小可验证 spike 已完成：OpenHub 继续作为默认 Page AI 主线，Pi Lab 仅在 `MNOTE_PAGE_AI_PI_LAB=1` 下启用，运行时默认禁用 Pi 原始 `bash/read/write/edit`，文件读写只走 MNote-owned tool facade 与 allowed roots。

Pi 可以进入下一阶段受控验证，但不能进入生产默认路径。下一阶段的门槛是 Turso/libSQL 正式 receipt 表、登录态 watcher -> tiptap 端到端验证、selection snapshot 注入和 UI 产品化。

## 2. Phase Checklist

### Phase A：源码与包可运行性

- [x] 重新拉取并核验当前 Pi 源码：`tmp/pi-research-20260703/pi-mono`，commit `23d14626 fix(ai): rotate stale Codex websocket sessions`。
- [x] 核验当前 npm 包：`@earendil-works/pi-coding-agent@0.80.3`，并通过 `MNOTE_PAGE_AI_PI_BIN` wrapper 跑通真实 RPC。
- [x] 跑通 `pi --mode rpc` 最小托管路径。
- [x] 记录 RPC event schema 到 MNote SSE `pi_rpc_event` 映射。
- [x] 验证 `abort`：MNote 可向 Pi RPC 发送 abort 并清理子进程。
- [ ] `steer` / `follow_up` 行为未纳入本轮 spike，留到下一阶段真实 agent turn 验收。

### Phase B：MNote scoped Pi runtime

- [x] 新增内部 runtime manager，不替换 OpenHub 默认入口。
- [x] `sessionDir` 派生到 MNote 管控目录：`<workspace>/.mnote/ai/pi-sessions/<actor>/<session>`。
- [x] 禁止全局 `~/.pi/agent/sessions` 作为默认 MNote session 落点。
- [x] 只开放 MNote-owned tools，默认不开放 Pi builtin `bash/read/write/edit`。
- [x] 路径越界读写被拒绝，并写入 provider-neutral receipt。

### Phase C：LightRAG tool

- [x] 实现 `mnote.knowledge_rag.query` facade。
- [x] 通过现有 `knowledge_rag::query_rag` 调用 LightRAG provider facade，不引入第二套 RAG。
- [x] tool envelope 保留 citation/open-reference 所需字段。
- [x] UI 支持 citation 展示。
- [x] 实现 `mnote.reference.open` facade，支持 citation 回跳入口。

### Phase D：文件 patch 闭环

- [x] 当前页面可通过 `rootUri + pagePath` 解析到真实 `.md`。
- [x] `mnote.local_file.patch` 支持 content 或 text operations patch 当前文件。
- [x] patch 写入前后记录 file version 与 diff summary。
- [x] patch 响应声明 watcher/document-session refresh，并显式 `polling=false`。
- [ ] 登录态浏览器中验证 watcher 实际刷新 tiptap 当前页仍未完成，是下一阶段阻塞项。
- [ ] changed file chip 打开对应资源未纳入本轮 spike，是下一阶段 UI 验收项。

### Phase E：UI 对照

- [x] 新增 MNote-native Pi Lab internal UI，支持 start/send/events/abort，并集成到当前 MNote Page AI 抽屉。
- [x] Pi RPC stream 的 `thinking_*` 事件不进入可见 assistant bubble；截图验证 Omniroute/freefirst 最终可见回复为 `OK`。
- [x] UI 支持 SSE stream、tool card、citation、diff summary、receipt 诊断。
- [x] 重新拉取并评估 `@earendil-works/pi-web-ui@0.75.3`；确认其 UI 成熟，但默认 browser Agent/IndexedDB/API key/tools/artifacts 边界不适合直接承接 MNote 托管 Pi RPC/SSE。
- [x] 采用参考官方 `ChatPanel/AgentInterface` 形态的 MNote-native adapter，并保留后续 remote-session adapter 接官方组件的迁移条件。
- [ ] 与 OpenHub 当前面板并排截图对照未纳入本轮 spike。
- [ ] 移动端 / 窄 sidebar 布局未纳入本轮 spike。
- [ ] retry / session resume 仍是下一阶段 UI 产品化项。

## 3. 验收结果

- [x] `pi --mode rpc` 能由 MNote 托管启动，并返回 `runtimePid`。
- [x] 当前页读取、LightRAG facade、文件 patch、receipt adapter、SSE UI 已形成最小闭环。
- [x] 所有文件读写受 allowed roots 控制。
- [x] 所有 tool call 均写 provider-neutral JSONL receipt。
- [x] Pi 原始 `bash/read/write/edit` 默认不可用。
- [x] citation/open-reference facade 已接入 MNote knowledge_rag 路径。
- [x] Pi Lab 与 OpenHub 并存，OpenHub 仍为默认 Page AI。
- [ ] Turso/libSQL 正式 receipt 表未完成。
- [ ] watcher -> tiptap 真实端到端刷新未完成。
- [ ] UI 尚未达到可替代 OpenHub 的生产级体验。

## 4. 验证命令

- `node scripts/task-pi-lab-static-smoke.js`：通过，78 checks。
- `node scripts/task-pi-lab-api-endpoint-smoke.js`：通过，10/10。
- `node scripts/task-pi-lab-mock-api-smoke.js`：通过。
- `node scripts/task-pi-lab-browser-smoke.js`：通过。
- `node scripts/task-pi-lab-rpc-api-smoke.js`：新增固化 RPC smoke；需以 `MNOTE_PAGE_AI_PI_LAB_RUNTIME=rpc` 和 `MNOTE_PAGE_AI_PI_BIN` 启动服务后运行。
- `cd rust && cargo check -p mnote-web`：通过。

## 5. 下一阶段条件

进入下一阶段前必须补齐：

- Turso/libSQL control-plane 表：`ai_provider_sessions`、`ai_tool_events`、`ai_file_patches`。
- 登录态浏览器 smoke：Pi patch 当前 `.md` 后，watcher 驱动 tiptap 当前页刷新，不允许高频轮询。
- sidebar host 注入真实 selection snapshot。
- Pi RPC send 的真实 agent turn 自动化验证，固定兼容版本范围或安装方式。
- UI 与 OpenHub baseline 的截图/交互对照。