chore: checkpoint turso and ai runtime work

ARCHITECTURE.md

@@ -2,13 +2,13 @@
 
 > 更新时间：2026-06-07
 >
-> 2026-05-22 口径更新：产品形态已切换为 local-first workspace，且初步 MVP 已建立；本地文件夹是默认数据真相，Turso/libSQL control-plane（SQLite fallback）承接 auth、membership、share grants、sync state、AI policy、OpenHub scope / AI policy 等默认控制面。旧 ACP/Hermes runtime session 只保留为迁移兼容层。Convex 仅保留为历史迁移源、显式 cloud source / compat / sync replica 边界；根 `convex/` functions 源码已软删除到 `recycle/20260522-convex-runtime-retirement/convex/`，不再作为 active deploy source。相关设计已完成并迁入 `design/02-convex-rust-long-term-architecture/done/2-2-local-first-workspace-convex-control-plane-v1.md` 与 `design/02-convex-rust-long-term-architecture/done/2-8-convex-replace-with-rust-sqlite-control-plane-v1.md`。本地 Markdown 图片与附件上传已新增 `/api/local-folder/assets/upload`，页面内上传默认写入 `{mdBase}.assets/` 并保存相对 Markdown 路径，不再走 Convex media asset。
+> 2026-05-22 口径更新：产品形态已切换为 local-first workspace，且初步 MVP 已建立；本地文件夹是默认数据真相，Turso/libSQL control-plane 承接 auth、membership、share grants、sync state、AI policy、OpenHub scope / AI policy 等默认控制面。旧 ACP/Hermes runtime session 只保留为迁移兼容层。Convex 仅保留为历史迁移源、显式 cloud source / compat / sync replica 边界；根 `convex/` functions 源码已软删除到 `recycle/20260522-convex-runtime-retirement/convex/`，不再作为 active deploy source。相关设计已完成并迁入 `design/02-convex-rust-long-term-architecture/done/2-2-local-first-workspace-convex-control-plane-v1.md` 与 `design/02-convex-rust-long-term-architecture/done/2-8-convex-replace-with-rust-sqlite-control-plane-v1.md`。本地 Markdown 图片与附件上传已新增 `/api/local-folder/assets/upload`，页面内上传默认写入 `{mdBase}.assets/` 并保存相对 Markdown 路径，不再走 Convex media asset。
 >
 > **当前阶段：local-first MVP 后阶段。** 3000 下文档页、Sidebar/File Tree/Page Tree 三层树模型、tree command（`tree.*` preferred）、tree realtime WS 主链 / SSE fallback、本地 Markdown 上传、上传下载、AI 会话本地化与 VSCode-like agent 运行口径均已建立。剩余工作集中在 `WorkspacePath/ObjectIdentity` runtime 消费统一、`DocumentBuffer/BufferStore`、Page Aggregate compat 瘦身、tree command context、live cache 统一、VSCode-like 冲突合并 UI、agent diff 审计、本地轻量搜索 / 分享 / 同步闭环，而不是继续扩张专用 page-ai fast-path 或 Convex 主存储链。
 >
 > 2026-05-26 口径更新：前端 runtime 大块已完成模块级拆分。`layout.rs` / `tree.rs` / `web_shell.rs` 不再是浏览器 JS 功能的主要符号定位入口；Sidebar、FileTree、document adapter、tree shell 等 runtime 入口位于 `rust/crates/mnote-web/browser/*.js`，tiptap island 入口位于 `rust/spikes/leptos-tiptap-spike/src/editor_runtime/*.rs`。CodeGraph 可直接索引这些 JS / Rust 模块；当前 smoke 分类见 `scripts/TESTING_REFERENCE.md`。
 >
-> 2026-06-28 口径更新：LightRAG / Hermes / Reasonix 已退出当前主线。知识库问答、资料 ingestion / query / citation / open-reference 和 Page AI 融合方向以 WeKnora / OpenHub 为准；LightRAG 仅保留 legacy fallback / parse 兼容边界，Hermes / Reasonix 仅保留 legacy/debug/外部工作流边界。旧 `/api/hermes/*`、`hermes_tools/*`、ACP runtime 命名属于历史命名或迁移中的兼容层，不代表当前产品定义。
+> 2026-07-03 口径更新：当前 runtime 已收口为 OpenHub / native agent + LightRAG + Turso/libSQL。知识库问答、资料 ingestion / query / citation / open-reference 默认走 LightRAG provider；OpenHub 负责 Page AI 面板、opencode/native agent 执行、会话和工具事件承载；WeKnora 只保留为历史设计、参考实现或可选备用 provider 边界，不再作为当前默认知识库主链。Hermes / Reasonix 仅保留 legacy/debug/外部工作流边界。旧 `/api/hermes/*`、`hermes_tools/*`、ACP runtime 命名属于历史命名或迁移中的兼容层，不代表当前产品定义。
 
 本文只描述当前仓库中真实成立的主线结构，以及当前最优先的架构收口点。
 
@@ -23,22 +23,22 @@
 当前主线固定为：
 
 1. `tree-first graph kernel` 是长期对象真相层
-2. 本地文件夹是默认数据真相，Turso/libSQL + SQLite fallback control-plane 是默认账号、分享、同步、协作和 AI 隔离控制面；Convex 退居历史迁移源与显式 cloud / compat 边界
+2. 本地文件夹是默认数据真相，Turso/libSQL control-plane 是默认账号、分享、同步、协作和 AI 隔离控制面；Convex 退居历史迁移源与显式 cloud / compat 边界
 3. `mnote-web` 是当前 Rust Web 主执行面，负责 3000 gateway、server-first shell、query / command / projection / transport 与 realtime stream；Next App Router 已降为 legacy compat / island bundle source，不再是当前主入口
 4. 文档页默认主编辑器已切到页面内 `leptos-tiptap` island
 5. `BlockNote` 已退出文档页默认主路径，仅作为历史参考实现 / 对照材料保留
 6. 页面 AI 当前最合理的长期形态是：MNote 只负责页面定位、白名单目录权限、OpenHub / native agent scope 管理、文件变更同步；OpenHub / native agent 直接在授权工作区内编辑本地文件。`page_ai_workflow` 只保留为 debug / 历史兼容门面，`mnote.doc.markdown_edit` 不作为 local-first 默认正文编辑入口，只在显式 cloud / remote / compat 且无法直接授权文件访问的边界中作为受控 fallback；`mnote.block.*` 只保留为复杂结构辅助层
-7. 知识库资料处理主线是 WeKnora / OpenHub：资料 ingestion、检索、引用和跨文档问答由 WeKnora/OpenHub 承担；LightRAG 仅 legacy fallback / parse 兼容，MNote 不再并行维护 LiteParse / evidence SQLite / OCR sidecar 作为资料库索引真相
+7. 知识库资料处理主线是 LightRAG + OpenHub：资料 ingestion、检索、引用和跨文档问答默认由 LightRAG provider 承担；OpenHub / native agent 通过 MNote provider-neutral tool facade 使用知识库能力；WeKnora 仅作为历史设计、参考实现或备用 provider 边界，MNote 不再并行维护 LiteParse / evidence SQLite / OCR sidecar 作为资料库索引真相
 
 一句话收口：
 
-> **Rust 持有语义主导权，本地文件夹是默认数据真相，Turso/libSQL + SQLite fallback control-plane 持有默认控制面；Convex 只保留历史迁移源、显式 cloud source / compat / sync replica 能力，前端逐步从重壳转向消费稳定 projection 与少量交互 island。**
+> **Rust 持有语义主导权，本地文件夹是默认数据真相，Turso/libSQL control-plane 持有默认控制面；Convex 只保留历史迁移源、显式 cloud source / compat / sync replica 能力，前端逐步从重壳转向消费稳定 projection 与少量交互 island。**
 
 补充口径：
 
 > **主 Web 执行面当前以 `mnote-web` 为 3000 owner；Next App Router 只保留为 legacy compat、交互 island bundle source 与显式 debug/迁移辅助边界。**
 >
-> **页面 AI 的 local-first 主路径应尽量贴近 VSCode：当前页面解析成真实 `.md` 文件，OpenHub / native agent 在授权目录白名单内直接读写，tiptap 只消费后台文件变化后的最新投影。知识库问答走 WeKnora/OpenHub provider，经 MNote source registry 和 citation/open-reference 回到本地资源。**
+> **页面 AI 的 local-first 主路径应尽量贴近 VSCode：当前页面解析成真实 `.md` 文件，OpenHub / native agent 在授权目录白名单内直接读写，tiptap 只消费后台文件变化后的最新投影。知识库问答默认走 LightRAG provider，并经 MNote source registry 和 citation/open-reference 回到本地资源。**
 
 ## 2. 当前主线目录
 
@@ -51,7 +51,7 @@
 - `/mnt/Data1T/mnote/rust/crates/mnote-web/`
   Rust Web route、kernel projection、documents/search/mindmap shell、OpenHub bridge、stream transport、compat，以及显式开启时的 debug shell；它是当前主 Web gateway / shell / transport owner。旧 Hermes bridge 命名仅作为 legacy route / tool facade 兼容层存在。
 - `/mnt/Data1T/mnote/recycle/20260522-convex-runtime-retirement/convex/`
-  根 `convex/` functions 源码已退役并软删除到这里；不再作为 active deploy source。历史 `schema.ts`、`aiSessions.ts`、Auth functions 仅用于审计 / 迁移对照，默认控制面已由 Turso/libSQL control-plane（SQLite fallback）承接。
+  根 `convex/` functions 源码已退役并软删除到这里；不再作为 active deploy source。历史 `schema.ts`、`aiSessions.ts`、Auth functions 仅用于审计 / 迁移对照，默认控制面已由 Turso/libSQL control-plane 承接。
 - `/mnt/Data1T/mnote/recycle/wolai-frontend/convex/`
   已随 wolai-frontend 移入 recycle，不允许作为当前 Convex deploy fallback。
 - `/mnt/Data1T/mnote/recycle/20260522-convex-runtime-retirement/infra/convex/`
@@ -356,24 +356,25 @@ OnlyOffice 仍然是：
 - `/mnt/Data1T/mnote/design/07-ai/process/7-18-local-first-agent-file-editing-control-plane-v1.md`
 - `/mnt/Data1T/mnote/design/old/07-ai/process/7-14-local-first-ai-markdown-editing-convergence-v1.md`（历史回收稿；不再作为当前实现依据）
 
-### 8.5 Knowledge RAG / WeKnora
+### 8.5 Knowledge RAG / LightRAG
 
 目标：
 
-- 把资料库 ingestion、检索、引用和跨文档问答统一交给 WeKnora / OpenHub。
+- 把资料库 ingestion、检索、引用和跨文档问答统一交给 LightRAG provider；OpenHub / native agent 只通过 MNote provider-neutral tool facade 调用。
 - MNote 只保留 source registry、allowed roots / 权限、FileTree 灯号、资料库设置 UI、provider status UI、citation/open-reference 映射和 agent tool facade。
 - LiteParse、旧 OCR sidecar、旧 evidence search / local-index agent tools 作为历史迁移和 recycle 边界，不再作为默认 fallback。
 
-当前进度（2026-06-28）：
+当前进度（2026-07-03）：
 
-- ✅ WeKnora / OpenHub 是当前默认知识库与 Page AI 融合方向。
+- ✅ LightRAG 是当前默认知识库 provider，OpenHub / native agent 是 Page AI 执行与交互主链。
 - ✅ MNote `source registry` 记录 `workspaceId/rootUri/sourcePath/sourceHash/providerDocId/stale/deletedAt/status`，FileTree 灯号从 registry 映射为已索引 / 正在索引 / 失败 / 未索引；历史 `lightRagDocId` 只作为兼容字段。
-- ✅ LightRAG dashboard/status bridge 仅作为 legacy fallback，不再作为新增主路径。
+- ✅ WeKnora 仅保留为历史设计、参考实现或备用 provider 边界，不再作为新增主路径。
 - ✅ Agent 默认使用 `mnote.knowledge_rag.status/query/open_reference`，不再暴露旧 `mnote.evidence.*` 作为资料库检索主路径。
 
 对应设计稿：
 
-- `/mnt/Data1T/mnote/design/07-ai/process/7-68-openhub-weknora-mnote-deep-fusion-checklist-v1.md`
+- `/mnt/Data1T/mnote/design/07-ai/done/7-50-lightrag-knowledge-rag-provider-v1.md`
+- `/mnt/Data1T/mnote/design/10-review/done/20-post-lightrag-runtime-hardening-checklist-v1.md`
 
 ### 8.6 定向 Bug Hunt 与质量基线
 
@@ -411,42 +412,47 @@ OnlyOffice 仍然是：
 - “当前最优先是先做树域 UI 重构”
 - “Rust Web 还只是实验，没有接真实页面链路”
 - “页面 AI 编辑必须经过 Hermes agent，没有快路径”
-- “LightRAG 是当前默认知识库 provider。”
+- “WeKnora 是当前默认知识库 provider。”
 - “Hermes / Reasonix 是当前 Page AI 默认 agent runtime。”
 - “页面 AI 编辑必须经过 MNote 专用工具才能改普通 Markdown”
 
 当前真正的卡点已经从“能不能跑”变成：
 
-> **管理员目录授权、文件版本冲突合并、agent diff 审计、本地轻量搜索 / 分享 / 同步如何产品化；知识库 RAG 已转向 WeKnora / OpenHub；Page Aggregate ClientState、projection / command / realtime 兼容链如何继续瘦身。**
+> **管理员目录授权、文件版本冲突合并、agent diff 审计、本地轻量搜索 / 分享 / 同步如何产品化；知识库 RAG 主路径为 LightRAG + OpenHub tool facade，WeKnora 仅备用；Page Aggregate ClientState、projection / command / realtime 兼容链如何继续瘦身。**
 
 ## 10. Control-plane 后端架构与运行配置
 
 ### 10.1 后端架构
 
-当前 control-plane 存储后端已从单一 `rusqlite` 抽象为 `ControlPlaneStore` trait，支持多后端切换：
+当前 control-plane 存储后端已从单一 `rusqlite` 抽象为 `ControlPlaneStore` trait；mnote-web 运行时只允许 Turso/libSQL 系列后端：
 
 ```text
 ControlPlaneStore trait
-  ├── SqliteControlPlaneStore     本地 fallback / 回滚 / 测试（rusqlite）
-  ├── TursoControlPlaneStore      默认目标后端（Turso/libSQL remote）
-  └── libsql-local 模式           无云纯本地 libSQL 模式
+  ├── TursoControlPlaneStore      mnote-web 运行时后端
+  │   ├── libsql-local            默认本地运行模式，无云依赖
+  │   ├── turso-remote            真实 Turso dev/prod DB
+  │   ├── turso-local-replica     本地 replica + remote sync
+  │   └── turso-synced            libSQL synced database
+  └── SqliteControlPlaneStore     仅限 control-plane-admin 迁移/导出和 Rust 测试隔离
 ```
 
 ### 10.2 环境变量
 
 ```text
-MNOTE_CONTROL_PLANE_BACKEND=sqlite|turso|turso-local-replica
-MNOTE_CONTROL_PLANE_DB_PATH=/mnt/Data1T/Mnote_data/control-plane/control-plane.db
+MNOTE_CONTROL_PLANE_BACKEND=libsql-local|turso-remote|turso-local-replica|turso-synced
+MNOTE_TURSO_LOCAL_PATH=/mnt/Data1T/Mnote_data/control-plane/control-plane-libsql.db
 MNOTE_TURSO_DATABASE_URL=libsql://...
 MNOTE_TURSO_AUTH_TOKEN=...
 MNOTE_TURSO_LOCAL_REPLICA_PATH=/mnt/Data1T/Mnote_data/control-plane/control-plane-replica.db
+MNOTE_TURSO_SYNCED_PATH=/mnt/Data1T/Mnote_data/control-plane/control-plane-synced.db
+MNOTE_TURSO_SYNC_INTERVAL_MS=5000
 ```
 
 ### 10.3 默认策略
 
-- **开发初期**：`sqlite` 为默认，`turso` 显式开启。
-- **Turso ready 后**：本机开发默认 `turso-local-replica`，CI 跑 `sqlite` 和 `turso` 双矩阵。
-- **稳定后**：普通运行默认 `turso-local-replica`，保留 `sqlite` 作为离线和回滚模式。
+- **普通开发/desktop/prod runtime**：默认 `libsql-local`，不再读取 `MNOTE_CONTROL_PLANE_DB_PATH`。
+- **云端验证**：显式使用 `turso-remote`、`turso-local-replica` 或 `turso-synced`，并从本机私有 env/secret manager 加载 URL/token。
+- **SQLite 边界**：`sqlite` 不能作为 mnote-web runtime backend；只允许 `control-plane-admin` 做迁移源、导出备份格式和 Rust 单测隔离。
 
 ### 10.4 未迁移数据（第一阶段不迁）
 
@@ -456,14 +462,9 @@ MNOTE_TURSO_LOCAL_REPLICA_PATH=/mnt/Data1T/Mnote_data/control-plane/control-plan
 - LightRAG 自身存储、WeKnora / OpenHub 自身存储。
 - OpenHub 自身 SQLite 会话库（第二阶段单独评估）。
 
-### 10.5 回滚策略
+### 10.5 备份与恢复策略
 
-```text
-MNOTE_CONTROL_PLANE_BACKEND=sqlite
-MNOTE_CONTROL_PLANE_DB_PATH=/mnt/Data1T/Mnote_data/control-plane/control-plane.db
-```
-
-回滚前从 Turso 导出最新 control-plane dump，恢复后保留 Turso DB 至少 30 天用于审计。
+SQLite 不再作为运行时回滚后端。需要离线留档或人工核验时，用 `control-plane-admin export-target-to-sqlite` 导出备份；恢复方向应是从备份重新导入 libSQL/Turso 目标库，而不是让 mnote-web 改回 SQLite 运行。
 
 ### 10.6 测试与脚本纪律