lix/mnote
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
26ff1a9c9a8c96c99cd73f99b5e78ba4fbca92bc
mnote/design/10-review/process/21-mvp-post-architecture-closure-checklist-v1.md
T

15 KiB
Raw Blame History

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. 当前锁定主链（唯一口径）

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

本地文件夹 / .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：

  • 更新 CURRENT_ARCHITECTURE.md §2.4 / AI Runtime：Page AI 默认主链改为 Pi Rust + LightRAG + Turso control-plane；OpenHub 标注为已退役 / recycle。
  • 更新 ARCHITECTURE.md 中仍写「OpenHub / native agent 默认」的段落，与上条对齐。
  • 更新 AGENTS.md：Page AI local-first 主路径表述改为 Pi Rust；OpenHub 仅 legacy 边界。
  • 在 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 主线」。
  • 核对 design/07-ai/process/7-71-*：AI 管理中心仍以 Turso control-plane 为唯一配置真相；删除「OpenHub 仍是独立默认 Page AI 主线」的过时表述，或改为历史背景。
  • 在本文件「验证记录」记一次文档 diff 摘要与审阅人。

验收：

  • 验收：上述 rg 只在 7-69 §0 历史修订/删除线上下文命中，active 主线口径无冲突。
  • 普通用户 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：

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

验收：

  • cargo test -p mnote-web --lib page_ai_pi：32 passed（2026-07-18）。
  • 机制到位：hydrate_session_from_control_plane + control-plane list/history；真实重启浏览器 smoke 作为后续运行态验证项。
  • 由既有 task535/536/537/539 local-agent smoke 与 tool_facade_enforces_directory_grant_* 覆盖（7-18 归档证据）。
  • 普通 UI 无 OpenHub fallback 入口。
  • 根入口 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：

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

验收：

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

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

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

Checklist：

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

验收：

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

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

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

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

Checklist：

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

验收：

  • 基线已记录（附录 A）；后续里程碑对照该基线做非增长检查。
  • 现默认基线为 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，在本文件保留链接与状态。

Reference in New Issue View Git Blame Copy Permalink