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

7-69 Page AI Pi-first Lab 设计 v1

状态：process Owner：07-ai / mnote-web / control-plane 日期：2026-07-03

0. 口径修订（2026-07-18）

覆盖本稿原「保留 OpenHub 生产基线 / Pi 不作为默认入口」结论。

• 代码已默认 enable_page_ai_pi_lab=true（MNOTE_PAGE_AI_PI_LAB）。
• OpenHub / Pi TS 已退役到 recycle 边界，不再是生产基线。
• 当前 Page AI 默认主链为 Pi Rust + LightRAG + Turso/libSQL control-plane。
• 本稿后续只承接 Pi Lab 去 spike / 产品化（持久化、模块拆分、命名），不再要求「保留 OpenHub 主线」。
• 上位收口：design/10-review/process/21-mvp-post-architecture-closure-checklist-v1.md。

1. 结论

本稿原确认方向为：保留 OpenHub 作为生产基线，同时新开 Pi-first Page AI Lab。该「双主线」结论已被 2026-07-18 口径修订覆盖；以下历史正文仅作背景，实施以 §0 与 checklist 21 为准。

这里的 Pi 指当前官方仓库 earendil-works/pi / 旧 badlogic/pi-mono，当前 npm 主包已迁到 @earendil-works/*。本轮重新拉取的源码证据位于：

• /mnt/Data1T/mnote/tmp/pi-research-20260703/pi-mono
• 当前核验 commit：23d14626 fix(ai): rotate stale Codex websocket sessions
• 关键包：@earendil-works/pi-coding-agent、@earendil-works/pi-ai、@earendil-works/pi-agent-core、@earendil-works/pi-tui

Pi 不是 OpenHub 的直接替代品，但它是当前最值得优先 spike 的底层候选。原因是：Pi 已经具备 coding agent、RPC、session tree、tool event、extension / skill / package、provider auth、多模型和可扩展工具体系；这些比通用 UI 框架更贴近 MNote 的 local-first Page AI 目标。

硬边界（2026-07-18 修订）：

• 不替换当前 OpenHub 主线。 → OpenHub 已退役；Pi Rust 为默认 Page AI。
• 不把 Pi Lab 作为默认 Page AI 入口。 → 默认开启；「Lab」仅为入口名。
• 不把 Pi JSONL session 直接当作 MNote 长期会话真相（元数据走 control-plane）。
• 不绕过 MNote AiAccessScope / allowed roots / Turso control-plane。
• 不把第三方 Pi package 当成已验收能力；每个第三方包必须通过本地 smoke 后才能纳入。

2. 背景

当前 Page AI 主线已经回正为：

MNote local-first workspace
  -> OpenHub / native agent
  -> LightRAG knowledge provider
  -> Turso/libSQL control-plane

OpenHub 的价值在于完整体验：Web 聊天 UI、消息流、tool card、diff/history、session/API、opencode/native agent 接入和当前已经实现的 MNote proxy/bootstrap/scope 注入。

但 OpenHub 仍有长期问题：

• UI、后端、session、agent runtime 是完整应用栈，MNote 深度融合需要持续 patch。
• MNote 的权限、workspace、page selection、citation、watcher、Turso 审计只能通过宿主桥接注入。
• OpenHub 自身会话与 MNote control-plane 的边界需要长期维护。

Pi 的候选价值不是“立刻复刻 OpenHub 并替换”，而是验证另一条更原生的路线：

MNote host chrome / sidebar
  -> Pi Lab gateway（MNote 托管）
  -> Pi RPC / SDK agent runtime
  -> MNote tools: current page / selection / allowed roots / LightRAG / file patch
  -> Turso/libSQL: session binding / tool audit / AI policy
  -> MNote watcher: editor refresh / changed file chips

3. 本轮取证结论

3.1 官方已证实能力

从当前源码与 npm registry 核验，Pi 官方具备：

• RPC mode：pi --mode rpc，stdin/stdout JSONL 协议，适合由 mnote-web 或 sidecar 托管。
• SDK：createAgentSession() / AgentSession，适合 Node/TS 应用直接嵌入。
• session persistence：JSONL session，支持 tree / resume / fork / clone / import / export / share。
• agent event stream：message / tool execution / compaction / queue 等事件。
• tool interception：beforeToolCall / afterToolCall，以及 extension 事件 tool_call 可阻断或改写。
• extensions / skills / Pi packages：pi install npm:...、git:...、本地路径，支持工具、命令、提示词、主题和热加载。
• project trust：控制是否加载项目 .pi settings/resources/extensions。
• provider auth：多 provider、API key、OAuth、订阅登录和 credential store。
• default file tools：read、write、edit、bash。
• diff：edit 工具与 session/export 链路能表达代码/文件变更。
• file watcher：官方 extension 示例中已有 file-trigger / watcher 类能力。
• containerization guidance：官方明确建议容器、VM、OpenShell 等外部隔离方案。

3.2 官方缺口

Pi 官方也明确不是完整 Web Agent 平台：

• 没有内建多租户 / 多用户控制面。
• 没有内建 MNote 所需的 workspace membership / share grants / AI policy。
• 没有内建 RAG / knowledge provider。
• 没有内建 MCP，官方文档明确倾向通过 extension/package 自行接入。
• 没有内建权限 sandbox；官方说明 Pi 默认继承启动进程权限。
• 没有面向 MNote 的 tool audit 数据库。
• 没有稳定的 HTTP 业务 API；官方主路径是 CLI / RPC / SDK。

3.3 已核验第三方 / 周边能力

以下包真实存在，但只作为候选，不直接成为主线依赖：

• @earendil-works/pi-web-ui：npm 上存在，提供 AI chat Web Components；当前 Git 主仓未见同名源码包，需要单独拉包验证。
• @hyperspaceng/neural-web-ui：基于 Pi AI 的 Web UI 组件。
• pi-mcp-adapter：Pi 的 MCP adapter extension。
• pi-workspace-history：workspace undo/redo、snapshot、rewind 类扩展。
• pi-hermes-memory：SQLite FTS5 memory / session search / secret scanning。
• @tintinweb/pi-subagents：Pi subagents 扩展。
• safe-coder：permission gate / protected paths 类安全 guardrail package。
• @cmdctrl/pi：Pi coding agent daemon。
• pi-codemode-extension：第三方 code mode / exec tool 扩展。

未证实：

• Craft 作为 Pi 官方或主流第三方项目名。
• Echo 作为 Pi 官方或主流第三方项目名。
• “Pi 官方一键提供 OpenHub 全套 Web UI + 多租户 + RAG + audit”的说法。

4. 目标与非目标

4.1 目标

Pi Lab 的目标是验证 MNote 原生融合，不是做第二个 OpenHub：

• 在 MNote sidebar 中跑出可用聊天 UI。
• 通过 Pi RPC / SDK 驱动真实 agent turn。
• 让 Pi 只通过 MNote tool facade 访问页面和文件。
• 用 AiAccessScope / allowed roots 拦截文件读写和 bash。
• LightRAG 作为 Pi tool 返回 citation，并能 open-reference 回 MNote。
• session binding、tool event、diff summary 写入 Turso/libSQL。
• 文件修改后由 MNote watcher 刷新 tiptap 页面。
• 与 OpenHub 并存，可在同一测试页面对照体验。

4.2 非目标

• 不做 OpenHub 迁移。
• 不做完整多用户 SaaS agent 平台。
• 不复刻 OpenHub admin / login / FileManager / KnowledgeManager。
• 不引入第二套 RAG provider。
• 不把 Pi 的 bash 默认开放给普通 Page AI。
• 不把 Pi package 的第三方能力不经审计直接暴露给用户。
• 不把 UI 做成长期自研简陋聊天框；若 pi-web-ui 不够，继续评估 OpenHub UI 或 assistant-ui/CopilotKit。

5. 方案对比

方向	适合作用	优点	风险	当前定位
OpenHub 继续收口	当前生产基线	体验完整，已接入 MNote scope / proxy / LightRAG 口径	长期 patch 成本，融合边界厚	P0
Pi-first Lab	新 Page AI 原生 runtime	coding agent + RPC + session tree + tool hook + package 生态	Web/multi-tenant/RAG/audit 需 MNote 补齐	P1 首选 spike
OpenHub UI + Pi backend	复用 OpenHub UI，替换 runtime	UI 完整，后端更可控	OpenHub 前后端格式耦合可能很深	P1b
opencode serve direct	去掉 OpenHub，保留 opencode	runtime 成熟	UI/tool card/diff/session 需自研	P2
assistant-ui / CopilotKit / AG-UI	前端交互协议和 UI	应用内 AI UI 生态强	不是 coding agent runtime，需要另配后端 agent	P2 UI 备选
LangGraph / Mastra / VoltAgent	agent/workflow 编排	编排能力强	与本地文件 patch / coding agent 体验不如 Pi 直接	P2 backend 备选
纯 Rust 自研	终极控制	单栈、权限可深度类型化	agent/provider/tool/UI 工作量过大	暂不做

当前推荐：

P0：OpenHub + LightRAG + Turso 继续作为默认 Page AI
P1：Pi-first Page AI Lab 做隔离 spike
P1b：如果 pi-web-ui 不达标，评估 OpenHub UI + Pi backend
P2：assistant-ui/CopilotKit/AG-UI 只作为 UI/协议备选，不作为 runtime 首选

6. 目标架构

6.1 Runtime 拆分

Browser sidebar
  -> MNote Page AI host chrome
  -> Pi Lab panel（feature flag）
  -> /api/page-ai/pi/*

mnote-web
  -> auth/session truth: mnote_session
  -> AiAccessScope / allowed roots
  -> Pi runtime manager
  -> Turso/libSQL run + tool audit
  -> LightRAG provider facade
  -> local folder watcher / page aggregate refresh

Pi runtime
  -> RPC subprocess or Node SDK sidecar
  -> MNote-owned tool set
  -> no direct unbounded workspace access

6.2 入口

第一阶段只加内部入口：

• URL：/page-ai/pi 或 sidebar 内 data-page-ai-provider="pi-lab"。
• Env：MNOTE_PAGE_AI_PI_LAB=1。
• 不在普通用户 UI 暴露“切换 OpenHub fallback”入口。
• OpenHub 入口保持默认。

6.3 Pi 托管方式

Spike 阶段优先使用 RPC 子进程：

mnote-web -> spawn pi --mode rpc --session-dir <mnote scoped dir> --no-approve

理由：

• Rust 侧容易托管进程、stdin/stdout、超时和 abort。
• 不要求 MNote 主进程引入 Node SDK 生命周期。
• 更接近未来 sandbox / container 边界。

备选：

mnote-web -> Node sidecar -> @earendil-works/pi-coding-agent SDK

使用条件：

• 需要更细粒度地替换 Pi session manager / credential store。
• 需要把 Turso 直接接进 AgentSession 生命周期。
• RPC 事件格式无法满足 UI 或审计需求。

6.4 Session 存储

Pi JSONL 只能作为 runtime log / recovery source，不作为 MNote 会话主真相。

MNote control-plane 新增或复用 provider-neutral 表：

• ai_runs
• ai_messages
• ai_tool_events
• ai_file_patches
• ai_provider_sessions

字段必须包含：

• mnote_user_id
• workspace_id
• root_uri
• page_path
• provider = pi
• pi_session_id
• pi_session_file
• allowed_roots_snapshot
• model_provider
• model_id
• created_at / updated_at

Pi 的 sessionDir 必须派生到 MNote 管控目录，例如：

<workspace>/.mnote/ai/pi-sessions/<mnote-user-key>/

或私有用户目录：

~/.mnote/ai/pi-sessions/<workspace-id>/<mnote-user-key>/

具体路径由 privacy / sharing 设计决定，但不能写到全局 ~/.pi/agent/sessions 后失去 MNote 归属。

6.5 Tool set

第一阶段只开放 MNote 自有工具：

• mnote.current_page.read
• mnote.selection.read
• mnote.allowed_roots.describe
• mnote.local_file.read
• mnote.local_file.patch
• mnote.knowledge_rag.query
• mnote.reference.open
• mnote.tool_receipt.write

默认禁用或替换 Pi 内置工具：

• 禁用原始 bash。
• 禁用不受 MNote allowed roots 约束的 read / write / edit。
• 如必须使用 Pi edit 能力，必须在 beforeToolCall / extension tool_call 中做路径规范化、root containment、dirty version 检查。

第二阶段可评估：

• pi-mcp-adapter：只允许 MNote 注册的 MCP server。
• pi-workspace-history：用于 agent undo/rewind。
• safe-coder：作为权限 guardrail 参考。
• pi-hermes-memory：只作为 session search / memory 参考，不作为 MNote 长期记忆真相。

6.6 权限与审计

所有 tool call 必须走 MNote control-plane 审计：

tool_call_start
  -> normalize args
  -> allowed roots check
  -> dirty buffer / file version check
  -> policy decision
  -> execute
  -> result / diff summary
  -> watcher refresh
  -> audit receipt

审计 receipt 至少包含：

• actor：mnote_user_id
• workspace / rootUri
• page path / selection snapshot id
• tool name
• normalized file path
• allowed / denied
• deny reason
• diff summary
• before / after file version
• provider session id
• model provider / model id

7. UI 设计原则

Pi Lab UI 目标是接近 OpenHub 的使用体验，但不强行复制其实现。

优先级：

1. 真实任务区：消息、输入框、tool card、changed files、citation。
2. 运行状态：model、session、allowed roots、abort/retry。
3. 诊断信息：折叠在 diagnostics，不默认挤占首屏。

第一阶段 UI 候选：

• @earendil-works/pi-web-ui：优先验证。
• @hyperspaceng/neural-web-ui：若官方 web-ui 不稳定，作为对照。
• OpenHub React Chat 子组件：作为视觉和交互 baseline。
• assistant-ui / CopilotKit：只在 Pi UI 不达标时评估。

最低 UI 要求：

• 流式文本。
• reasoning 折叠。
• tool call start / update / end 卡片。
• 文件 patch / diff 摘要。
• citation list + open-reference。
• abort / retry。
• session list / resume。
• 错误态显示真实错误，不伪装成功。

8. Spike 阶段

Phase A：源码与包可运行性

• 在 tmp/pi-research-20260703/pi-mono 跑通当前 Pi build / smoke。
• 安装当前 @earendil-works/pi-coding-agent 与 @earendil-works/pi-web-ui。
• 跑通 pi --mode rpc 最小 prompt。
• 记录 RPC event schema，映射到 MNote ai_tool_events。
• 验证 abort / steer / follow_up 行为。

Phase B：MNote scoped Pi runtime

• 新增内部 runtime manager 设计，不先实现到生产入口。
• 用临时脚本从 MNote workspace 派生 sessionDir。
• 禁止全局 ~/.pi/agent/sessions 作为默认落点。
• 只开放 MNote mock tools，不开放 bash。
• 路径越界读写必须被拒绝并写 receipt。

Phase C：LightRAG tool

• 注册 mnote.knowledge_rag.query。
• 调用现有 /api/knowledge-rag/* 或内部 provider facade。
• 返回 source id、resource path、snippet、score。
• UI 显示 citation。
• citation 点击回 MNote open-reference。

Phase D：文件 patch 闭环

• 当前页面解析到真实 .md。
• Pi tool 请求 patch 当前文件。
• MNote 检查 dirty buffer / version。
• 写入文件后 watcher 刷新 tiptap。
• changed file chip 能打开对应资源。

Phase E：UI 对照

• 在 MNote sidebar 内嵌 pi-web-ui 或等价组件。
• 与 OpenHub 当前面板并排截图对照。
• 核验移动端 / 窄 sidebar 布局。
• 核验 tool card、diff、citation、error、abort/retry。

9. 验收门槛

Pi Lab 进入下一阶段必须满足：

• pi --mode rpc 或 SDK 能由 MNote 稳定托管。
• 当前页读取、LightRAG 查询、文件 patch、watcher 刷新形成闭环。
• 所有文件读写都受 allowed roots 控制。
• 所有 tool call 都有 Turso/libSQL receipt。
• bash 默认不可用，或只能在显式 dev/debug scope 下使用。
• citation 能点击回 MNote 文件或资源。
• UI 不低于 OpenHub baseline 的核心交互：stream、tool card、diff/citation、abort/retry、session resume。
• Pi Lab 与 OpenHub 并存，不影响默认 Page AI。

失败条件：

• 5 个工作日内无法跑通 RPC/SDK 最小 agent。
• pi-web-ui 或候选 UI 无法稳定嵌入 MNote sidebar。
• 文件 patch 难以在 MNote allowed roots / dirty buffer 模型下约束。
• LightRAG citation 无法可靠回跳。
• 第三方 package 需要过多不可控 patch 才能满足权限边界。

10. 决策点

D1：Pi 是否作为新 Page AI runtime

通过条件：

• Phase A-D 全部完成。
• UI 至少达到 OpenHub 核心体验的 70%。
• 权限、审计、RAG、watcher 都由 MNote 控制。

若通过：

OpenHub = 默认生产入口
Pi Lab = 内部/高级用户入口
下一稿 = Pi Page AI runtime implementation checklist

若未通过：

OpenHub 继续主线
Pi 降级为 provider/runtime 参考
assistant-ui / CopilotKit / AG-UI 进入 UI 备选评估

D2：Pi UI 选择

优先顺序：

1. @earendil-works/pi-web-ui
2. @hyperspaceng/neural-web-ui
3. OpenHub React UI 子集 + Pi backend
4. assistant-ui / CopilotKit
5. MNote-native debug UI

D3：Pi 托管方式

优先顺序：

1. RPC subprocess
2. Node SDK sidecar
3. OpenHub backend adapter

不做：

• Rust 直接重写 agent loop。
• 浏览器直接持有 provider API key 调 Pi。

11. 后续产物

本稿通过后新增：

• design/07-ai/done/7-69-page-ai-pi-first-lab-checklist-v1.md
• scripts/task-pi-lab-rpc-api-smoke.js
• scripts/task*-page-ai-pi-lightrag-smoke.js
• scripts/task*-page-ai-pi-file-patch-smoke.js

临时研究目录只作为证据，不进入产品路径：

• /mnt/Data1T/mnote/tmp/pi-research-20260703/pi-mono
• /mnt/Data1T/mnote/tmp/pi-research-20260703/pi-skills
• /mnt/Data1T/mnote/tmp/pi-research-20260703/openclaw

12. 最终建议

当前最稳的路线是：

继续 OpenHub P0
并行启动 Pi-first Page AI Lab P1
用真实 smoke 决定是否扩大 Pi 权重

Pi 不应被过早否定；它已经有足够多的 runtime 与生态基础，值得作为首选实验底座。 Pi 也不应被过早宣布替换 OpenHub；MNote 需要自己补齐多用户控制面、Turso 审计、LightRAG tool、allowed roots 和 UI 产品化边界。

13. Spike 执行记录（2026-07-03）

本稿对应的最小可验证 spike 已落地到代码，验收记录见：

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

当前完成范围：

• /api/page-ai/pi/* 与 /page-ai/pi dev-only 入口。
• Pi RPC/mock runtime manager 与 MNote 管控 sessionDir。
• 8 个 MNote-owned tool facade。
• allowed roots 越界拒绝、file version、diff summary、deny reason、receipt JSONL adapter。
• LightRAG 仍通过 knowledge_rag facade 暴露给 Pi，不引入第二套 RAG。
• 文件 patch 返回 watcher refresh metadata，且 polling=false。
• MNote-native Pi Lab UI 支持 start/send/events/abort、SSE stream、tool/citation/diff/receipt 显示。
• OpenHub 仍保持默认 Page AI 主线。

当前未完成范围：

• 全局 pi CLI 仍未进入 PATH；但已通过 MNOTE_PAGE_AI_PI_BIN=/tmp/mnote-pi-cli-wrapper.sh 包装 npx -y @earendil-works/pi-coding-agent@0.80.3 跑通真实 pi --mode rpc 端到端 smoke。
• Turso/libSQL 正式 receipt 表迁移；当前仍为 provider_neutral_jsonl_adapter_v1。
• 登录态浏览器中验证 watcher 刷新 tiptap 当前页。
• @earendil-works/pi-web-ui 未成为长期 UI 基座，本轮由 MNote-native debug UI 承接。

验证结果：

• node scripts/task-pi-lab-static-smoke.js：通过。
• node scripts/task-pi-lab-api-endpoint-smoke.js：通过。
• node scripts/task-pi-lab-mock-api-smoke.js：通过，覆盖 mock runtime、SSE、allowed roots、越界拒绝、当前页读取、当前 .md patch、watcher refresh metadata、LightRAG facade、citation/open-reference facade、send、abort。
• node scripts/task-pi-lab-browser-smoke.js：通过，覆盖 /page-ai/pi 独立页、Pi Lab 面板、输入框、启动/发送/清空按钮、runtime asset、status API。
• 真实 Pi RPC smoke：通过，覆盖 MNote 托管启动 pi --mode rpc、runtimePid、当前页读取、越界拒绝、当前 .md patch、send accepted、abort。
• node scripts/task-pi-lab-rpc-api-smoke.js：新增，覆盖 runtimeMode=rpc 下 status、runtimePid 真实子进程、start/send/abort 端点、tool-call MNote facades（allowed roots、越界拒绝、.md patch、watcher refresh、LightRAG、citation）、SSE 事件流、多会话生命周期、Pi 进程清理。需要真实 Pi CLI（MNOTE_PAGE_AI_PI_BIN）与可选 API key 验证 send。
• cd rust && cargo check -p mnote-web：通过。