lix/mnote

Fork 0

Files

T

Agent Board c8472bb898 feat: add pi lab ai management integration

2026-07-04 21:47:42 +08:00

19 KiB

Raw Blame History

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 主线已经回正为：

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 的使用体验，但不强行复制其实现。

优先级：

真实任务区：消息、输入框、tool card、changed files、citation。
运行状态：model、session、allowed roots、abort/retry。
诊断信息：折叠在 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 选择

优先顺序：

@earendil-works/pi-web-ui
@hyperspaceng/neural-web-ui
OpenHub React UI 子集 + Pi backend
assistant-ui / CopilotKit
MNote-native debug UI

D3：Pi 托管方式