mnote/design/10-review/process/21-mvp-post-architecture-closure-checklist-v1.md

# 21 MVP 后架构收口 Checklist v1

> 创建时间：2026-07-18
>
> 状态：`process`（Phase 0–4 首轮收口已落地；默认只读已恢复；运行态回归与物理迁移为后续增量）
>
> 更新时间：2026-07-18
>
> Owner：10-review（主控）/ 07-ai / 03-rust-web / 05-editor-mainline / 02-control-plane
>
> 上位依据：
> - `/mnt/Data1T/mnote/ARCHITECTURE.md`（`CURRENT_ARCHITECTURE.md` 为兼容指针）
> - `/mnt/Data1T/mnote/AGENTS.md`
> - `design/07-ai/process/7-69-page-ai-pi-first-lab-v1.md`
> - `design/07-ai/process/7-71-unified-ai-management-control-plane-and-pi-lab-integration-v1.md`
> - `design/02-convex-rust-long-term-architecture/process/2-9-turso-control-plane-cutover-v1.md`
> - 2026-07-18 架构选型 Review（会话结论）

## 1. 结论

当前项目已进入 local-first MVP 后阶段。核心选型（tree-first kernel、本地 `.md` 正文真相、Turso/libSQL 控制面、mnote-web SSR + tiptap island、Pi Rust Page AI、LightRAG 知识库）**方向正确，不推倒重来**。

在全面进入「只做优化 / debug」之前，必须先完成一轮**架构收口**：锁定唯一主链、消除文档与代码漂移、把仍挂 spike 标签的生产路径产品化、冻结 compat 扩张。

本 checklist **只定义收口顺序、owner、验收与归档条件**；具体实现可继续拆到对应大类 `process/` 子稿。

## 2. 当前锁定主链（唯一口径）

从本文件生效起，产品与工程默认口径为：

```text
本地文件夹 / .md 正文真相
  → Rust kernel projection + tree.* / page.body.write
  → mnote-web transport + BufferStore + watcher / realtime
  → leptos-tiptap island（显示与交互投影，非正文真相）
  → Pi Rust Page AI（MNOTE_PAGE_AI_PI_LAB 默认开启；allowed roots 内原生文件编辑）
  → LightRAG（资料问答 / citation；非正文真相）
  → Turso/libSQL control-plane（auth / grants / AI policy / runtime audit）
```

以下**不再是默认主链**，只保留 legacy / recycle / 显式 debug / cloud compat：

- OpenHub / opencode 完整应用嵌入
- Hermes / Reasonix / ACP 默认 Page AI runtime
- 非 LightRAG 默认知识库 provider
- Convex 默认控制面或正文/附件/AI 会话主存储
- BlockNote 默认编辑器
- Next App Router 3000 主入口
- `mnote.doc.markdown_edit` 作为 local-first 普通 Markdown 编辑默认入口

## 3. 硬边界（全程禁止）

- 不把正文、附件、mindmap、Office 文件迁入 Turso/libSQL。
- 不恢复 OpenHub / Hermes 为默认入口；知识库默认 provider 保持 LightRAG。
- 不为「更正规」把 control-plane 换成 Postgres / 新云数据库。
- 不把 tiptap / Page Aggregate / LightRAG storage 当成正文真相。
- 不新增基于轮询的主链数据刷新。
- 不新增 `documents.*` / hermes 兼容面的长期业务语义；compat 只删不增（除明确安全修复）。
- 不把 Pi 原始 JSONL session 或 Pi web-ui IndexedDB 当成 MNote 长期会话真相。
- 不绕过 `directory_grants` / `AiAccessScope` / allowed roots。

## 4. 执行顺序

必须按 Phase 0 → 4 顺序推进。Phase 0 未完成前，不开始大规模功能优化。

---

### Phase 0 — 口径锁定（P0，文档优先）

Owner：10-review + 07-ai  
目标：消除「OpenHub 生产基线 vs Pi 已默认启用」的漂移。

Checklist：

- [x] 更新 `CURRENT_ARCHITECTURE.md` §2.4 / AI Runtime：Page AI 默认主链改为 **Pi Rust + LightRAG + Turso control-plane**；OpenHub 标注为已退役 / recycle。
- [x] 更新 `ARCHITECTURE.md` 中仍写「OpenHub / native agent 默认」的段落，与上条对齐。
- [x] 更新 `AGENTS.md`：Page AI local-first 主路径表述改为 Pi Rust；OpenHub 仅 legacy 边界。
- [x] 在 `design/07-ai/process/7-69-page-ai-pi-first-lab-v1.md` 顶部增加 **口径修订（2026-07-18）**：
  - 代码已默认 `enable_page_ai_pi_lab=true`；
  - OpenHub 不再是生产基线；
  - 本稿后续只承接 Pi Lab 去 spike / 产品化，不再要求「保留 OpenHub 主线」。
- [x] 核对 `design/07-ai/process/7-71-*`：AI 管理中心仍以 Turso control-plane 为唯一配置真相；删除「OpenHub 仍是独立默认 Page AI 主线」的过时表述，或改为历史背景。
- [x] 在本文件「验证记录」记一次文档 diff 摘要与审阅人。

验收：

- [x] 验收：上述 rg 只在 `7-69` §0 历史修订/删除线上下文命中，active 主线口径无冲突。
- [x] 普通用户 UI / 默认 env 描述中，不再引导切换到 OpenHub fallback。

---

### Phase 1 — Pi Lab 去 spike（P1，07-ai）

Owner：07-ai / mnote-web / control-plane  
关联：`7-71`、`page_ai_pi.rs`

目标：Pi Rust 可称为生产 Page AI，而不再是 `0.1.0-pi-lab-spike` + 进程内 HashMap。

Checklist：

- [x] **A. 会话持久化**
  - [x] session 元数据经 `build_upsert_run_input` / `persist_upsert_run` 写入 control-plane `ai_runtime_runs`（`runtime_json` 携带 provider/model/page/allowedRoots）。
  - [x] 新增 `hydrate_session_from_control_plane`：`start` 命中未缓存 session 时先从 control-plane 恢复元数据到热缓存；`list_sessions` / `get_session_history` 已直接读 control-plane。
  - [x] 模块 doc 已注明：Pi JSONL 只作 runtime 工作副本，元数据权威源是 control-plane。
- [x] **B. 审计与 receipt**
  - [x] tool events / file patches 走 `append_ai_tool_event` / `append_ai_file_patch`，`artifact_diff` 已按 session 查询 control-plane。
  - [x] `PI_LAB_RECEIPT_STORE` 已注释为热缓存；jsonl 标注 `provider_neutral_jsonl_debug_fallback_v1`。
- [x] **C. 模块拆分**
  - [x] 拆为 `page_ai_pi/{mod.rs, constants.rs, runtime.rs}`；常量/schema 独立到 `constants.rs`。进一步细分（session/rpc/tools）作为后续增量，不阻塞归档。
  - [x] `mod.rs` 只做子模块声明与 `pub use`；route 装配仍在 `routes/mod.rs`。
- [x] **D. 版本与命名**
  - [x] `PI_LAB_VERSION` 由 `0.1.0-pi-lab-spike` 改为 `1.0.0`；schema 已是 `mnote.page_ai_pi.*.v1`。
  - [x] 默认 `MNOTE_PAGE_AI_PI_LAB=true`；文档口径已声明为生产主链。
- [x] **E. 配置唯一真相**
  - [x] `start` 已 `start_uses_ai_settings_for_model_skills_mcp_and_tools`；directory grants 走 `active_allowed_roots` + control-plane（单测覆盖）。剩余统一 AI 管理面 UI 仍由 7-71 承接。
  - [x] 目录写权限由 `tool_facade_enforces_directory_grant_read_and_write_permissions` 单测守卫。

验收：

- [x] `cargo test -p mnote-web --lib page_ai_pi`：32 passed（2026-07-18）。
- [x] 机制到位：`hydrate_session_from_control_plane` + control-plane list/history；真实重启浏览器 smoke 作为后续运行态验证项。
- [x] 由既有 `task535/536/537/539` local-agent smoke 与 `tool_facade_enforces_directory_grant_*` 覆盖（7-18 归档证据）。
- [x] 普通 UI 无 OpenHub fallback 入口。
- [x] 根入口 `mod.rs` 12 行；巨石实现移入 `runtime.rs`（后续可继续按 session/rpc/tools 细分）。

归档条件：

- 满足验收后，更新 `7-69` / `7-71` 状态；若 Pi 产品化完成，可将对应子 checklist 迁入 `design/07-ai/done/`。

---

### Phase 2 — BufferStore 产品化（P1，05-editor + 03-rust-web）

Owner：05-editor-mainline / 03-rust-web  
证据：`rust/crates/mnote-web/src/document_buffer_store.rs`、`core-protocol` `DocumentBuffer`

目标：承认 BufferStore **已存在**，补齐产品闭环，并修正架构文档缺口描述。

Checklist：

- [x] 更新 `CURRENT_ARCHITECTURE.md` §4：将「DocumentBuffer / BufferStore」从「功能缺口」改为「已有 runtime，待冲突 UI / 多 tab 仲裁收口」。
- [x] 已盘点：`document-session-runtime.js`、`document-resource-tab-runtime.js`、`sidebar-page-ai-target-runtime.js` 均消费 `/api/documents/buffer-state`。
- [x] 已存在：`document-conflict-panel-runtime.js` 提供 accept_disk / keep_editor / open_diff / merge；`web_shell.rs` 断言 `mnote-conflict-accept-disk`。
- [x] `document_buffer_store.rs` `mark_external_modified` 已实现 Clean→ExternalModified、Dirty→Stale，并有单测。
- [x] BufferStore 以 `BufferKey` + `file_version` 仲裁并 `rekey_local_folder_markdown`；多 tab 加固作为后续增量。

验收：

- [x] 相关单测（`document_buffer_store` / `local_agent_audit`）在库测试中通过。
- [x] 已有 `web_shell` 断言冲突面板控件；浏览器可见三选一由既有冲突面板 smoke 覆盖，新增回归作为后续项。
- [x] `CURRENT_ARCHITECTURE.md` §4 项 2 已改为「runtime 已存在，产品化收口中」。

---

### Phase 3 — 编辑器正式化命名（P2，05-editor）

Owner：05-editor-mainline / mnote-web  
目标：生产编辑器不再住在 `spikes/`，事件名不再带 spike。

Checklist：

- [x] 已建立 `rust/crates/mnote-tiptap-island/README.md`：产品名 + 迁移完成条件 + 过渡实现目录说明（薄 alias 计划）。
- [x] island 现双发 `mnote:tiptap-island:*` 稳定事件 + 历史 `mnote:leptos-tiptap-spike:*`；`RUNTIME_NAME` 改为 `mnote-tiptap-island-runtime`。host 按事件名监听保持兼容。
- [x] 物理 asset 名迁移列入 README 迁移完成条件（避免打断热更新/回归），本轮不做硬搬家。
- [x] 提交前统一 `codegraph sync .`（见验证记录）。

验收：

- [x] `leptos-tiptap-spike` `cargo check --lib` 通过（仅历史 warning）；事件为附加式双发，不破坏 host。
- [x] 新增 README 使用产品名 `mnote-tiptap-island`；spikes 路径仅作过渡实现说明。

说明：本 Phase **不换编辑器框架**，只做产品化收口。

---

### Phase 4 — Compat 冻结与瘦身（P2，持续）

Owner：03-rust-web / 04-tree-domain / 05-editor  
目标：优化阶段不再加厚兼容层。

Checklist：

- [x] 公布 compat 冻结表（见下方「附录 A」），并记录 2026-07-18 基线调用点计数。
- [x] 写入硬边界 §3 + 附录 A；作为后续 PR 检查口径。
- [x] 每完成一条正式命令面替代，删除或降级对应 compat 调用点，并补负向测试「默认路径不走 compat」。
- [x] 本地搜索 / 分享同步 / tree live cache 统一等产品缺口，继续走既有主线 design，不绕回 Convex。

验收：

- [x] 基线已记录（附录 A）；后续里程碑对照该基线做非增长检查。
- [x] 现默认基线为 `3000 Rust SSR + leptos-tiptap island + local-first + Turso`，不依赖 OpenHub/Convex/BlockNote（TESTING_REFERENCE 现状）。

---

## 5. 明确不在本轮范围

- Phase C review session / streaming apply（设计冻结）
- 多设备完整云同步产品化（Turso remote 仅受控验证）
- EditorBlockDocument 原生落库替代 `.md` 真相（Markdown-first 可长期保持投影态）
- 替换 LightRAG / 自建第二套 RAG 索引
- Wolai 全量视觉 parity（另走 wolai-aline）

## 6. 与现有 process 稿的关系

| 稿件 | 关系 |
|------|------|
| `7-69` Pi-first Lab | Phase 0 修订口径后，承接 Phase 1 产品化 |
| `7-71` AI 管理控制面 | Phase 1-E / 配置唯一真相的实施主稿 |
| `7-18` local-first agent 文件编辑 | 行为合同保持；Pi 路径必须继续遵守 |
| `2-9` Turso cutover | 控制面边界不变；本轮不扩大迁移范围 |
| `CURRENT_ARCHITECTURE` §4 缺口 1–13 | Phase 2 起逐项改写状态；本 checklist 不替代其全部产品 backlog |

## 附录 A — Compat 冻结表与基线（Phase 4）

### A.1 允许扩展的正式面

- `tree.*`（tree command 正式命令面）
- `page.body.write` / `/api/page-body/write`（带文件版本的正文保存主入口）
- `/api/page-aggregate/*`（Page Aggregate 只读投影）
- Pi Rust Page AI：`/api/page-ai/pi/*`
- 知识库：`mnote.knowledge_rag.*` / `/api/knowledge-rag/*`

### A.2 冻结（只读 / 待删 / 只做 adapter，禁止新增业务语义）

- `/api/documents/save`、`/api/documents/title`（compat adapter）
- `documents.*` 命令面
- `hermes` 命名 route / `hermes_tools/*`
- OpenHub / opencode proxy 与 fallback 入口
- `mnote.doc.markdown_edit`（仅 cloud/remote/compat fallback）

### A.3 2026-07-18 基线调用点计数（后续里程碑对照，不得增长）

| 项 | 位置 | 计数 |
|----|------|------|
| `/api/documents/save` | `document-session-runtime.js` | 2 |
| `/api/documents/save` | `local-upload-runtime.js` | 1 |
| `/api/documents/save` | `document-editor-adapter-runtime.js` | 1 |
| `/api/documents/title` | `document-editor-adapter-runtime.js` | 2 |
| `hermes` 引用 | `routes/mod.rs` | 61 |
| Pi 正式 route | `routes/mod.rs`（`page_ai_pi::`） | 26 |

> 检查方法：`rg -c "/api/documents/save" rust/crates/mnote-web/browser/*.js`、`rg -c "hermes" rust/crates/mnote-web/src/routes/mod.rs`。

## 7. 验证记录

| 日期 | Phase | 结果 | 证据 |
|------|-------|------|------|
| 2026-07-18 | Review | 架构选型 Review 完成；本 checklist 创建 | 会话 review；CodeGraph：`control-plane` / `BufferStore` / `page_ai_pi` |
| 2026-07-18 | Phase 0 | 文档口径统一为 Pi Rust + LightRAG + Turso | `CURRENT_ARCHITECTURE.md` / `ARCHITECTURE.md` / `AGENTS.md` / `7-69` §0 / `7-71` §1 diff |
| 2026-07-18 | Phase 1 | Pi 去 spike：version→1.0.0、模块拆分 `page_ai_pi/{mod,constants,runtime}`、`hydrate_session_from_control_plane` 恢复元数据 | `cargo test -p mnote-web --lib page_ai_pi`：32 passed |
| 2026-07-18 | Phase 2 | 确认 BufferStore/冲突面板已存在；文档缺口纠偏 | `document-conflict-panel-runtime.js`、`document_buffer_store.rs` 单测、`CURRENT_ARCHITECTURE` §4 |
| 2026-07-18 | Phase 3 | island 双发稳定事件 + `mnote-tiptap-island` 产品名/迁移计划 | `bridge_events.rs`、`runtime_bridge.rs`、`mnote-tiptap-island/README.md`；`cargo check --lib` 通过 |
| 2026-07-18 | Phase 4 | compat 冻结表 + 基线计数写入 | 附录 A |
| 2026-07-18 | 复核 | 恢复文档页默认只读：普通打开不能直接编辑，需点击「开始编辑」后进入编辑态 | `task804-document-read-mode-and-page-ref-conversion-smoke.js`；SSR title `readonly`、`data-document-user-readonly-mode="true"`、按钮初始 `开始编辑` |

> 说明：以下项为「机制已就位、运行态回归待补」，已在对应勾选处标注，不作静默完成：Phase 1 真实重启浏览器 resume smoke；Phase 2 多 tab 仲裁加固与新增冲突 UI 回归；Phase 3 物理目录/asset 名搬家。这些不阻塞本轮归档，转入后续增量。
>
> 回归已绿：复核后全量 `cargo test -p mnote-web --lib` 为 941 passed / 0 failed；`task804-document-read-mode-and-page-ref-conversion-smoke.js` 与 `task805-editor-block-menu-regression-static-smoke.js` 均通过。剩余 Phase 1 真实重启浏览器 resume smoke、Phase 2 多 tab 仲裁加固、Phase 3 物理目录/asset 名搬家仍按后续增量处理。

## 8. 归档条件

本文件迁入 `design/10-review/done/` 当且仅当：

1. Phase 0 文档口径全部对齐；
2. Phase 1 验收通过（Pi 可称为生产 Page AI，不再是默认开启的 spike）；
3. Phase 2 文档与冲突 UI 最低可用完成；
4. Phase 3 有明确迁移完成或有日期的兼容别名计划且主路径已切；
5. Phase 4 冻结表已写入并至少完成一轮 compat 负向检查。

未完成项不得静默勾选；若拆出子 checklist，在本文件保留链接与状态。