chore: checkpoint turso and ai runtime work

2026-07-03 23:20:16 +08:00
parent a75b3d11f9
commit 36d027a4a1
67 changed files with 4224 additions and 914 deletions
@@ -4,7 +4,7 @@
 >
 > 当前状态：`DONE`
 >
-> 2026-06-25 历史口径：本文记录 LightRAG provider 当时已完成的历史事实，不再代表当前新主线。当前 `7-68 OpenHub + WeKnora + MNote Page AI 深度融合` 将默认知识库 provider 切到 WeKnora；LightRAG 仅保留为 `lightrag_legacy` / fallback / 迁移对照边界。
+> 2026-07-03 口径回正：当前 runtime 已回到 OpenHub / native agent + LightRAG + Turso/libSQL。本文重新作为当前默认知识库 provider 的完成基线；此前 `7-68 OpenHub + WeKnora + MNote Page AI 深度融合` 中将 WeKnora 设为默认 provider 的口径已标记 stale，仅保留为历史设计、参考实现或备用 provider 边界。
 >
 > Owner：07-ai / knowledge-rag / plugin-ui / external-provider
 >
@@ -4,7 +4,7 @@
 >
 > 状态：`done`
 >
-> 2026-06-25 历史口径：本文记录 LightRAG hardening 当时已完成的历史事实，不再代表当前新主线。当前 `7-68 OpenHub + WeKnora + MNote Page AI 深度融合` 将默认知识库 provider 切到 WeKnora；本文只作为 `lightrag_legacy` / fallback / 迁移对照边界。
+> 2026-07-03 口径回正：当前 runtime 已回到 OpenHub / native agent + LightRAG + Turso/libSQL。本文重新作为当前默认 LightRAG provider 的 hardening 基线；此前 `7-68 OpenHub + WeKnora + MNote Page AI 深度融合` 中将 WeKnora 设为默认 provider 的口径已标记 stale。
 >
 > Owner：07-ai / knowledge-rag / 03-rust-web / plugin-ui
 >
@@ -4,7 +4,7 @@
 >
 > 当前状态：`DONE`
 >
-> 2026-06-25 历史口径：本文记录 LightRAG 图片 OCR 与搜索召回链路当时已完成的历史事实，不再代表当前新主线。当前 `7-68 OpenHub + WeKnora + MNote Page AI 深度融合` 将默认知识库 provider 切到 WeKnora；本文只作为 `lightrag_legacy` / fallback / 迁移对照边界。
+> 2026-07-03 口径回正：当前 runtime 已回到 OpenHub / native agent + LightRAG + Turso/libSQL。本文重新作为当前默认 LightRAG provider 的图片 OCR 与搜索召回链路 hardening 基线；此前 `7-68 OpenHub + WeKnora + MNote Page AI 深度融合` 中将 WeKnora 设为默认 provider 的口径已标记 stale。
 >
 > Owner：07-ai / knowledge-rag / local-search
 >
@@ -4,7 +4,7 @@
 >
 > 当前状态：`done`
 >
-> 2026-06-25 历史口径：本文记录 LightRAG DOCX 引用与定位合同当时已完成的历史事实，不再代表当前新主线。当前 `7-68 OpenHub + WeKnora + MNote Page AI 深度融合` 将默认知识库 provider 切到 WeKnora；本文只作为 `lightrag_legacy` / fallback / 迁移对照边界。
+> 2026-07-03 口径回正：当前 runtime 已回到 OpenHub / native agent + LightRAG + Turso/libSQL。本文重新作为当前默认 LightRAG provider 的 DOCX 引用与定位合同基线；此前 `7-68 OpenHub + WeKnora + MNote Page AI 深度融合` 中将 WeKnora 设为默认 provider 的口径已标记 stale。
 >
 > Owner：07-ai / knowledge-rag / 03-rust-web / office-preview
 >
@@ -4,7 +4,7 @@
 >
 > 当前状态：`done`
 >
-> 2026-06-25 历史口径：本文记录 LightRAG native DOCX sidecar 当时已完成的历史事实，不再代表当前新主线。当前 `7-68 OpenHub + WeKnora + MNote Page AI 深度融合` 将默认知识库 provider 切到 WeKnora；本文只作为 `lightrag_legacy` / fallback / 迁移对照边界。
+> 2026-07-03 口径回正：当前 runtime 已回到 OpenHub / native agent + LightRAG + Turso/libSQL。本文重新作为当前默认 LightRAG provider 的 native DOCX sidecar 定位基线；此前 `7-68 OpenHub + WeKnora + MNote Page AI 深度融合` 中将 WeKnora 设为默认 provider 的口径已标记 stale。
 >
 > Owner：07-ai / knowledge-rag / LightRAG native parser / office-preview
 >
@@ -4,7 +4,7 @@
 >
 > 当前状态：`DONE`
 >
-> 2026-06-25 历史口径：本文中 LightRAG 相关能力记录的是当时已完成的历史事实，不再代表当前新主线。当前 `7-68 OpenHub + WeKnora + MNote Page AI 深度融合` 将默认知识库 provider 切到 WeKnora；本文只作为 run/config/facade 参考与 `lightrag_legacy` 迁移对照边界。
+> 2026-07-03 口径回正：当前 runtime 已回到 OpenHub / native agent + LightRAG + Turso/libSQL。本文中的 Knowledge RAG facade 重新作为当前 LightRAG 默认 provider 的 run/config/facade 参考；此前 `7-68 OpenHub + WeKnora + MNote Page AI 深度融合` 中将 WeKnora 设为默认 provider 的口径已标记 stale。
 >
 > Owner：07-ai / Page AI runtime / Hermes client runs / Reasonix ACP / Knowledge RAG facade
 >
@@ -1,6 +1,6 @@
 # 7-18 [process] local-first agent 文件编辑控制面 v1

-> 2026-06-28 覆盖说明：本文中的 Hermes / Reasonix 主路径口径已退为历史参考。当前 Page AI / agent runtime 主线以 OpenHub / opencode / WeKnora 融合设计为准，见 `7-68-openhub-weknora-mnote-deep-fusion-v1.md` 与 `7-69-weknora-native-embed-mnote-openhub-governance-v1.md`。本文仅保留 local-first 文件授权、watcher 同步和冲突模型的参考价值。
+> 2026-07-03 口径更新：本文中的 Hermes / Reasonix 主路径口径已退为历史参考。当前 Page AI / agent runtime 主线以 OpenHub / native agent + LightRAG + Turso/libSQL 为准；`7-68-openhub-weknora-mnote-deep-fusion-v1.md` 与 `7-69-weknora-native-embed-mnote-openhub-governance-v1.md` 的 WeKnora 默认 provider 口径已标记 stale。本文仅保留 local-first 文件授权、watcher 同步和冲突模型的参考价值。

 > 创建时间：2026-05-22
 >
@@ -1,10 +1,10 @@
-> 状态补充（2026-06-25）：本稿冻结为 opencode runtime / 官方 opencode WebUI iframe fallback 参考；Page AI 产品主线由 `7-68-openhub-weknora-mnote-deep-fusion-v1.md` 接管。官方 iframe 仅在 OpenHub AI 面板不可用、调试 opencode 原生行为或做回归对照时启用，不再作为默认产品路径。
+> 状态补充（2026-07-03）：本稿冻结为 opencode runtime / 官方 opencode WebUI iframe fallback 参考；Page AI 产品主线为 OpenHub / native agent + LightRAG + Turso/libSQL。官方 iframe 仅在 OpenHub AI 面板不可用、调试 opencode 原生行为或做回归对照时启用，不再作为默认产品路径。此前指向 `7-68-openhub-weknora-mnote-deep-fusion-v1.md` 的 WeKnora 默认 provider 口径已标记 stale。

 # 7-65 [process] Page AI opencode WebUI embed v1

 > 创建时间：2026-06-23
 >
-> 当前状态：`FROZEN / 官方 opencode iframe fallback，OpenHub + WeKnora + MNote 深度融合为主线`
+> 当前状态：`FROZEN / 官方 opencode iframe fallback，OpenHub + LightRAG + MNote 深度融合为主线`
 >
 > Owner：07-ai / Page AI / opencode WebUI embed
 >
@@ -21,11 +21,11 @@

 ## 1. 核心结论

-废弃 MNote Page AI 自研 provider 接入与 Board-first 产品壳后，本稿曾把 **opencode 官方 runtime + 官方 WebUI** 作为主线；截至 `7-68`，该方案降级为 fallback。
+废弃 MNote Page AI 自研 provider 接入与 Board-first 产品壳后，本稿曾把 **opencode 官方 runtime + 官方 WebUI** 作为主线；当前该方案已降级为 fallback，默认产品主线为 OpenHub / native agent + LightRAG + Turso/libSQL。

 ```text
 fallback MNote Page AI = MNote 宿主壳 + opencode 官方 WebUI iframe + MNote 打开/刷新/上下文集成
-主线 Page AI          = MNote 宿主壳 + OpenHub AI 面板 + OpenHub FastAPI/Redis/opencode client + WeKnora
+主线 Page AI          = MNote 宿主壳 + OpenHub AI 面板 + OpenHub FastAPI/Redis/opencode client + LightRAG
 opencode              = agent runtime / HTTP server / OpenAPI / SSE / SDK / opencodego provider
 ```

@@ -53,7 +53,7 @@ MNote 不再直接维护 Reasonix / ZCode / Hermes / Chat-only / Board worker

 ### 2.2 仍可保留的边界

- `mnote.doc.*`、`mnote.block.*`、旧 LightRAG legacy facade 等工具可继续作为 fallback/compat 边界；默认知识库工具应改向 WeKnora。
+- `mnote.doc.*`、`mnote.block.*` 等工具可继续作为 fallback/compat 边界；默认知识库工具走 LightRAG + provider-neutral `mnote.knowledge_rag.*` facade。
 - Agent Board 仍可作为外部 workflow/QA/review 系统，不再作为 Page AI 默认聊天后端。
 - CodexMobile 可保留为备选 spike 或体验对照，不作为当前实现目标。

@@ -61,7 +61,7 @@ MNote 不再直接维护 Reasonix / ZCode / Hermes / Chat-only / Board worker

 ### 3.1 MNote 只做四件事

-1. **上下文**：当前页、选区、页面标题、真实 `.md` 路径、workspaceId、allowed roots、WeKnora 引用；旧 LightRAG 只作为 legacy/fallback 口径保留。
+1. **上下文**：当前页、选区、页面标题、真实 `.md` 路径、workspaceId、allowed roots、LightRAG 引用；WeKnora 只作为历史设计、参考实现或备用 provider 边界。
 2. **授权**：把 MNote local-first 文件权限转换为 opencode permission / external_directory / working directory。
 3. **嵌入**：第一版通过 MNote 同源受登录态保护反代嵌入 opencode 官方 WebUI；`npm run dev:hot` 默认拉起 `opencode serve --hostname=127.0.0.1 --port 4096`。
 4. **回执**：监听 opencode event/diff，触发 MNote watcher 刷新，记录 Page AI session binding。
@@ -204,7 +204,7 @@ MNote open Page AI
 - 当前页真实 Markdown 路径。
 - selection 文本。
 - allowed roots 与读写权限。
- WeKnora 引用摘要；旧 LightRAG 引用只作为 legacy/fallback。
+- LightRAG 引用摘要；WeKnora 引用只作为备用 provider / 历史参考。
 - 当前任务约束：优先编辑 primaryTarget，禁止越权修改。

 当前状态：`done for MVP`。host chrome 已展示当前页、真实 Markdown path（可定位时）、selection、allowed roots/writable 状态；打开 Page AI 时会调用 `/api/page-ai/opencode/session`，用 `noReply=true` 向 opencode session 注入 MNote context envelope，并把 iframe 打到绑定 session URL。2026-06-24 已按 opencode-chat 参考改回官方 WebUI iframe 主路径，MNote-native timeline 仅保留为 debug/receipt 边界。
@@ -524,7 +524,7 @@ $MNOTE_DATA/users/<user-id>/opencode/<workspace-hash>/state/opencode/
 - 第一阶段只做 Chat/Session/Message/Diff/File open 五件事，不引入 OpenHub 登录/admin/知识库/team。
 ### 11.9 OpenHub 知识库实现与 WeKnora 对照

-用户最新判断：Page AI 要做深度融合；MNote 当前已放弃 LightRAG，知识库方向原计划是 WeKnora。因此需要单独核验 OpenHub 自带知识库是否能替代 WeKnora。
+2026-07-03 口径回正：Page AI 要做深度融合；当前默认知识库主线为 LightRAG + OpenHub tool facade，WeKnora 仅保留为历史设计、参考实现或备用 provider。因此本节只作为当时 OpenHub 自带知识库能力对照记录。

 源码核验结论：**OpenHub 自带知识库是轻量 SQLite 文本知识库，不是完整 RAG/知识库底座；适合复用 UI、API 形状和 prompt 注入链路，不建议替代 WeKnora。**

@@ -542,7 +542,7 @@ OpenHub 知识库真实实现：

 - WeKnora 应继续作为 MNote 长期知识库底座候选：负责文档解析、索引、检索、召回、引用、权限过滤与跨文档问答。
 - OpenHub 知识库不应替代 WeKnora；它更像“用户短记忆/轻量知识片段/企业公告文本”的 fallback。
- 最优融合方式是 **OpenHub Knowledge UI + MNote Rust 知识库 adapter + WeKnora provider**：前端交互复用 OpenHub，后端接口形状兼容 OpenHub，但真正的 ingestion/search/citation 由 MNote 调 WeKnora。
+- 当前融合方式是 **OpenHub AI 面板 + MNote Rust 知识库 adapter + LightRAG provider**：OpenHub 负责 Page AI 对话与工具事件承载，真正的 ingestion/search/citation 由 MNote 通过 provider-neutral facade 调 LightRAG。
 - OpenHub 的 `knowledge_sources` schema 可以作为 MNote control-plane 的 source registry 参考，但需要增加 `workspace_id/root_uri/resource_id/source_uri/provider_doc_id/index_status/permission_scope/citation_locator` 等 MNote 字段。
 - OpenHub 的 prompt 注入链路可以短期复用为 Page AI context block，但 WeKnora 命中结果必须带 citation/open-reference 映射，不能只塞纯文本。

@@ -551,5 +551,5 @@ OpenHub 知识库真实实现：
 1. Page AI 主 UI 继续选 OpenHub Chat 子系统，而不是官方 opencode iframe。
 2. Knowledge 模块第一阶段只迁移 UI 与 API contract，不迁移其 SQLite 文本检索为长期底座。
 3. MNote Rust adapter 提供 OpenHub-compatible `/api/knowledge/*`，内部走 WeKnora 或本地 fallback。
-4. 保留 OpenHub 轻量知识库作为“未配置 WeKnora 时的 local fallback / 用户手工短知识”，但不能称为默认知识库主线。
+4. 保留 OpenHub 轻量知识库作为“未配置 LightRAG 时的 local fallback / 用户手工短知识”，但不能称为默认知识库主线。
 5. 新设计稿应明确：`OpenHub UI` 负责交互，`MNote control-plane` 负责用户与权限，`WeKnora` 负责知识库索引与检索，`opencode` 负责 agent 执行。
@@ -1,6 +1,6 @@
 # 7-66 [process] Page AI opencode-native UI v1

-> 状态补充（2026-06-25）：本稿冻结为 native UI fallback / debug receipt 参考；Page AI 产品主线由 `7-68-openhub-weknora-mnote-deep-fusion-v1.md` 接管。不得继续扩写 MNote 自研聊天框作为默认 Page AI UI。
+> 状态补充（2026-07-03）：本稿冻结为 native UI fallback / debug receipt 参考；Page AI 产品主线为 OpenHub / native agent + LightRAG + Turso/libSQL。不得继续扩写 MNote 自研聊天框作为默认 Page AI UI。此前指向 `7-68-openhub-weknora-mnote-deep-fusion-v1.md` 的 WeKnora 默认 provider 口径已标记 stale。

 > 创建时间：2026-06-24
 >
@@ -10,12 +10,12 @@

 ## 1. 结论

-本稿提出的 MNote-native opencode UI 方向已冻结为 fallback。当前主线不是在 MNote 内复刻 opencode 消息流、tool UI、permission UI，也不是回到官方 opencode WebUI iframe 默认路径，而是 `7-68` 定义的 **MNote 薄宿主壳 + OpenHub AI 面板 + OpenHub FastAPI/Redis/opencode client + WeKnora**。
+本稿提出的 MNote-native opencode UI 方向已冻结为 fallback。当前主线不是在 MNote 内复刻 opencode 消息流、tool UI、permission UI，也不是回到官方 opencode WebUI iframe 默认路径，而是 **MNote 薄宿主壳 + OpenHub AI 面板 + OpenHub FastAPI/Redis/opencode client + LightRAG**。

 因此 `7-66` 只作为反例和 fallback 保留：native message timeline / composer / permission cards 可以临时作为 debug receipt、故障诊断或 OpenHub 不可用时的降级参考，但不得成为 Page AI 主 UI，也不继续扩写自研聊天框。

 ```text
-主线 Page AI      = MNote host chrome + OpenHub AI 面板 + OpenHub FastAPI/Redis/opencode client + WeKnora
+主线 Page AI      = MNote host chrome + OpenHub AI 面板 + OpenHub FastAPI/Redis/opencode client + LightRAG
 native fallback  = MNote debug receipt + opencode session/event/diff 摘要
 iframe fallback  = 7-65 官方 opencode WebUI iframe
 ```
@@ -1,4 +1,4 @@
-> 状态补充（2026-06-25）：本稿为 OpenHub 初步融合稿，已被 `7-68-openhub-weknora-mnote-deep-fusion-v1.md` 覆盖。路线从“抽取/重写 OpenHub 组件 + MNote Rust adapter”改为“嵌入 OpenHub AI 面板 + 保留 OpenHub FastAPI/Redis/opencode client + WeKnora 工具/知识底座”。
+> 状态补充（2026-07-03）：本稿为 OpenHub 初步融合稿，OpenHub AI 面板 / FastAPI / Redis / opencode client 方向仍保留参考价值；其中 WeKnora 默认知识库底座口径已被当前 OpenHub / native agent + LightRAG + Turso/libSQL 主线覆盖。`7-68-openhub-weknora-mnote-deep-fusion-v1.md` 已标记 stale，不再作为当前默认 provider 依据。

 # 7-67 OpenHub Page AI 深度融合设计 v1

@@ -10,14 +10,14 @@ Owner：07-ai / mnote-web / control-plane

 `7-65` 的 opencode 官方 WebUI iframe 路线验证了 opencode runtime、同源反代、session binding、文件打开/刷新等接缝，但 UI 深度融合受 iframe 与官方 WebUI 结构限制。用户目标已经调整为：尽量复用成熟社区项目 OpenHub 的前端、消息库、权限、知识库 UI 和 opencode 接入模式，把 MNote Page AI 做成类似 VSCode + Cline 的一体化侧边栏，而不是 MNote 自研一个简陋聊天框。

-当前 Page AI 主路径以 `7-68` 为准：
+当前 Page AI 主路径已回正为 OpenHub / native agent + LightRAG + Turso/libSQL：

 ```text
 MNote Rust SSR / control-plane / local workspace
  -> OpenHub AI 面板（只暴露 AI 能力，裁剪非 AI 入口）
-  -> OpenHub FastAPI + Redis + OpenHub SQLite session/skill/tool permission；MCP 由 MNote/WeKnora/opencode 工具配置承接
+  -> OpenHub FastAPI + Redis + OpenHub SQLite session/skill/tool permission；MCP/tool 由 MNote/LightRAG/opencode 工具配置承接
  -> OpenHub opencode client / opencode serve runtime
-  -> WeKnora knowledge provider（唯一知识库底座）
+  -> LightRAG knowledge provider（默认知识库底座）
 ```

 `7-65` 降级为 opencode runtime / 官方 iframe fallback；`7-66` 降级为 native UI fallback；本稿的 Rust adapter / 自建 message store 路线也冻结为参考，不再作为执行主线。
@@ -27,7 +27,7 @@ MNote Rust SSR / control-plane / local workspace
 - 不恢复 Reasonix / ZCode / Hermes / Board / CodexMobile 为 Page AI 默认后端。
 - 不新增 Page AI Leptos island；Page AI 仍属于 `mnote-web` host runtime 与普通前端资源。
 - 不直接引入 OpenHub 登录、admin、FileManager、KnowledgeManager 等非 AI 入口；用户、权限、workspace 真相归 MNote control-plane。
- 不把 OpenHub 自带 SQLite 文本知识库当作 MNote 长期知识库底座；长期知识库 provider 是 WeKnora。
+- 不把 OpenHub 自带 SQLite 文本知识库当作 MNote 长期知识库底座；当前默认长期知识库 provider 是 LightRAG。
 - 不使用 `--dangerously-skip-permissions` 作为默认路径。
 - 不把 opencode 原生 session 列表裸露给前端；所有 session 必须绑定 MNote 用户、rootUri、page path。
 - 不通过高频轮询刷新消息或 changed files；优先使用 opencode event stream、MNote watcher、programmatic refresh。
@@ -103,7 +103,7 @@ MNote 采用：

 - UI：复用 OpenHub `KnowledgeManager` 交互。
 - API：提供 OpenHub-compatible `/api/knowledge/*`。
- Provider：默认走 WeKnora。
+- Provider：默认走 LightRAG。
 - Fallback：未配置 WeKnora 时，可临时用 OpenHub-like SQLite 文本知识源做短知识。
 - Citation：WeKnora 结果必须保留 source/resource/open-reference 映射，方便点击回 MNote 文件或资源页。

@@ -137,12 +137,12 @@ MNote 采用：
 - [ ] DiffViewer 中所有 file path 点击都映射到 MNote resource/file open。
 - [ ] 文件路径必须限制在当前 rootUri / allowed roots 内。

-### Phase E：Knowledge / WeKnora adapter
+### Phase E：Knowledge / LightRAG adapter

 - [ ] 兼容 OpenHub `knowledgeService` 的 list/create/upload/search/stats API。
- [ ] 后端默认调用 WeKnora ingestion/search。
- [ ] 将 WeKnora 命中结果转成 OpenHub UI 可展示的 source/citation。
- [ ] 未配置 WeKnora 时启用 SQLite fallback，并在 UI 明确标注 fallback。
+- [ ] 后端默认调用 LightRAG ingestion/search。
+- [ ] 将 LightRAG 命中结果转成 OpenHub UI 可展示的 source/citation。
+- [ ] 未配置 LightRAG 时启用 SQLite fallback，并在 UI 明确标注 fallback。

 ### Phase F：浏览器真实验证

@@ -151,7 +151,7 @@ MNote 采用：
 - [ ] Page AI 看到 OpenHub-derived UI，而不是旧简陋聊天框或官方 iframe。
 - [ ] 发送真实消息，模型能识别当前 rootUri 内文件。
 - [ ] 让 opencode 修改测试 Markdown，MNote changed chip 可打开，当前页可刷新。
- [ ] Knowledge UI 可上传/检索，WeKnora provider 有真实命中与引用。
+- [ ] Knowledge UI 可上传/检索，LightRAG provider 有真实命中与引用。
 - [ ] 保存截图与 smoke 输出。

 ## 6. 验收标准
@@ -1,9 +1,11 @@
-# 7-68 OpenHub + WeKnora + MNote 深度融合执行 Checklist v1
+# [stale] 7-68 OpenHub + WeKnora + MNote 深度融合执行 Checklist v1

-状态：process
+状态：stale / reference-only（不再作为当前 process 主线）
 Owner：07-ai / mnote-web / control-plane / knowledge-provider
 日期：2026-06-25

+2026-07-03 stale 说明：当前 runtime 口径已改为 OpenHub / native agent + LightRAG + Turso/libSQL。本文 checklist 中将 WeKnora 定义为默认知识库 provider、LightRAG 退为 legacy 的条目不再作为当前主线执行；当前知识库主路径以 LightRAG provider 和 MNote provider-neutral `mnote.knowledge_rag.*` facade 为准。WeKnora 仅保留为历史设计、参考实现或备用 provider 边界。
+
 上位设计：`design/07-ai/process/7-68-openhub-weknora-mnote-deep-fusion-v1.md`

 ## 0. 执行原则
@@ -220,7 +222,7 @@ P1 WeKnora tool 记录：
 - Hermes tool manifest 与 dispatch 已新增 `mnote.weknora.search/open_reference/list_sources/get_source_status`。
 - Tool wrapper 要求 `rootUri` 以及 `scope/allowlist/allowedRoots/aiAccessScope/sourcePaths` 之一，否则返回 `mnote_weknora_scope_required`。
 - 当前通过 MNote HTTP facade 调用 WeKnora；没有把 WeKnora API key 暴露到浏览器/localStorage，也没有默认开放 Python mcp-server 写能力。
- 2026-06-26 task782 可写 worker：OpenHub backend 新增 MNote host mode `/api/mnote/tools/call` 只读 facade，通过 MNote 反代受控 headers 与 server-side `X-MNote-Session-Cookie` 调 `/api/hermes/tools/mnote/call`，支持 `mnote.weknora.search/open_reference/list_sources/get_source_status`；OpenHub 不接触 WeKnora API key，也不把 MNote cookie 暴露给前端 localStorage。`stream.py` 在 MNote host mode 下对知识库/资料库/WeKnora/citation/source 类问题先调用 MNote WeKnora search，把结构化 tool result 注入 OpenHub/opencode prompt，并向 OpenHub 前端推送 `mnote.weknora.search` tool event。
+- 2026-06-28 主控收口：MNote 新增中性 tool executor alias `/api/mnote/tools/{manifest,call,audit}`，OpenHub backend 已改为调用 `/api/mnote/tools/call`；旧 `/api/hermes/tools/mnote/*` 只保留 legacy alias。OpenHub host mode 只读 facade 通过 MNote 反代受控 headers 与 server-side `X-MNote-Session-Cookie` 调 MNote tool executor，支持 `mnote.weknora.search/open_reference/list_sources/get_source_status`；OpenHub 不接触 WeKnora API key，也不把 MNote cookie 暴露给前端 localStorage。`stream.py` 在 MNote host mode 下对知识库/资料库/WeKnora/citation/source 类问题先调用 MNote WeKnora search，把结构化 tool result 注入 OpenHub/opencode prompt，并向 OpenHub 前端推送 `mnote.weknora.search` tool event。
 - 2026-06-26 task782 可写 worker：OpenHub 前端 `AssistantMessage` 从 WeKnora tool output 的 `citations/uiCitations/references` 渲染 `data-mnote-openhub-citation` 可点击 citation，点击经 `postMNoteOpenReference` 发 `mnote:open-reference`；MNote Page AI host 已接受 `openhub-citation` 并复用 document pane open-file bridge 打开本地页面。新增 `scripts/task782-openhub-weknora-tool-citation-bridge-smoke.js` 覆盖后端 facade、scope/cookie/API key 边界、stream auto tool bridge、citation button 与 postMessage runtime。主控复核：OpenHub `/openapi.json` 已暴露 `/api/mnote/tools/call`，`node scripts/task782-openhub-weknora-tool-citation-bridge-smoke.js` 通过；边界仍标 partial，不宣称 opencode 原生 MCP 自动选 tool 完成。

 ## 11. P1 验收与证据
@@ -1,10 +1,12 @@
-# 7-68 OpenHub + WeKnora + MNote Page AI 嵌入式集成设计 v1
+# [stale] 7-68 OpenHub + WeKnora + MNote Page AI 嵌入式集成设计 v1

-状态：process
+状态：stale / reference-only（不再作为当前 process 主线）
 Owner：07-ai / mnote-web / control-plane / knowledge-provider
 日期：2026-06-25

-执行说明：本文是 Page AI / OpenHub / WeKnora 深度融合的当前主设计，不表示代码已完成。具体落地按本文第 10 节与配套清单 `design/07-ai/process/7-68-openhub-weknora-mnote-deep-fusion-checklist-v1.md` 执行；若实现中发现源码能力与本文假设不一致，优先遵循“保留原系统已完成能力，只在产品真相冲突处做最小胶水/嫁接/裁剪”的总原则。
+2026-07-03 stale 说明：本文仍保留 Page AI / OpenHub / WeKnora 融合的历史设计上下文，但当前 runtime 口径已改为 OpenHub / native agent + LightRAG + Turso/libSQL。本文中将 WeKnora 定义为默认知识库 provider、LightRAG 退为 legacy 的内容不再作为当前主线执行；当前知识库主路径以 LightRAG provider 和 MNote provider-neutral `mnote.knowledge_rag.*` facade 为准。WeKnora 仅保留为历史设计、参考实现或备用 provider 边界。
+
+执行说明：本文不再是当前主设计，仅作为 WeKnora 方向历史方案和 OpenHub 集成参考。当前实现与后续新增能力不得从本文推导出“WeKnora 是默认 provider”或“LightRAG 已退出主线”的口径。

 ## 0. 结论先行

@@ -0,0 +1,474 @@
+# 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. 后续产物
+
+本稿通过后新增：
+
+- `7-69-page-ai-pi-first-lab-checklist-v1.md`
+- `scripts/task*-page-ai-pi-rpc-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 产品化边界。