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

## 1. 结论

本稿确认一个新方向：**保留 OpenHub 作为当前生产基线，同时新开 Pi-first Page AI Lab，验证 Pi 是否能成为 MNote-native Page AI runtime**。

这里的 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 目标。

硬边界：

- 不替换当前 OpenHub 主线。
- 不把 Pi Lab 作为默认 Page AI 入口。
- 不把 Pi JSONL session 直接当作 MNote 长期会话真相。
- 不绕过 MNote `AiAccessScope` / allowed roots / Turso control-plane。
- 不把第三方 Pi package 当成已验收能力；每个第三方包必须通过本地 smoke 后才能纳入。

## 2. 背景

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

```text
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 并替换”，而是验证另一条更原生的路线：

```text
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 工作量过大 | 暂不做 |

当前推荐：

```text
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 拆分

```text
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 子进程：

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

理由：

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

备选：

```text
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 管控目录，例如：

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

或私有用户目录：

```text
~/.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 审计：

```text
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 控制。

若通过：

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

若未通过：

```text
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. 最终建议

当前最稳的路线是：

```text
继续 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`：通过。