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：源码与包可运行性

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

Phase B：MNote scoped Pi runtime

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

Phase C：LightRAG tool

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

Phase D：文件 patch 闭环

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

Phase E：UI 对照

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

3. 验收结果

• pi --mode rpc 能由 MNote 托管启动，并返回 runtimePid。
• 当前页读取、LightRAG facade、文件 patch、receipt adapter、SSE UI 已形成最小闭环。
• 所有文件读写受 allowed roots 控制。
• 所有 tool call 均写 provider-neutral JSONL receipt。
• Pi 原始 bash/read/write/edit 默认不可用。
• citation/open-reference facade 已接入 MNote knowledge_rag 路径。
• 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 的截图/交互对照。