chore: 收口 review 执行清单与 runtime 验证

- 补齐 design/10-review 执行清单、验收标准与相关设计治理记录 - 迁移已完成的 tree、mindmap、runtime fallback、AI kernel 等设计和缺陷条目 - 推进 Rust Web runtime、tree/sidebar、page aggregate、mindmap 与 OnlyOffice 路由侧验证支撑 - 增加 task177-task180 smoke/audit 脚本及前端相关测试覆盖
2026-05-14 05:52:08 +08:00
parent b4a452a8b7
commit 96e03645f7
69 changed files with 4780 additions and 979 deletions
@@ -5,6 +5,7 @@
 > 状态说明：
 > - 本稿对应的页面设置 `popover`、页面 AI `drawer`、入口位置与最小接线方案已在当前 `mnote-web` 文档壳中落地，故迁入 `done/`
 > - 本稿中的 deferred 项继续由后续独立任务推进，不影响这一轮“页面设置 + 页面 AI 交互壳”完成判定
+> - 2026-05-13 追加说明：本文中 `CLI-first` / `mnote-cli host` 是 2026-05-06 完成时的历史接线口径；当前 AI 长期方向已由 `design/07-ai/process/7-3-page-ai-hermes-panel-and-mnote-plugin-v1.md` 覆盖为 Hermes 页面内客户端 + mnote Hermes skill/plugin
 >
 > 关联文档：
 > - `/mnt/Data1T/mnote/ARCHITECTURE.md`
@@ -13,7 +14,7 @@
 > - `/mnt/Data1T/mnote/design/05-editor-mainline/process/5-6-page-aggregate-alignment-checklist-v1.md`
 > - `/mnt/Data1T/mnote/design/05-editor-mainline/process/5-7-wolai-page-tree-main-editor-experience-restoration-v1.md`
 > - `/mnt/Data1T/mnote/design/05-editor-mainline/process/5-9-wolai-aline-continuous-checklist-v1.md`
-> - `/mnt/Data1T/mnote/design/07-ai/process/7-phase7-ai-kernel-projection-plan-v4.md`
+> - `/mnt/Data1T/mnote/design/07-ai/process/7-3-page-ai-hermes-panel-and-mnote-plugin-v1.md`
 > - `/mnt/Data1T/mnote/design/08-wolai-aline-test-flow/process/wolai-aline-test-flow-v1.md`

 ## 1. 文档目的
@@ -28,7 +29,7 @@

 1. 页面设置入口与面板形态
 2. 页面级 AI 入口与右侧抽屉
-3. 两者与现有 `Page Aggregate` / `mnote-cli` 主线的接线方式
+3. 两者与现有 `Page Aggregate` / Hermes 面板主线的接线方式

 一句话收口：

@@ -45,7 +46,7 @@
 - 页面设置 UI 已存在：`PageOptionsSidebar`
 - 页面设置写链已存在：`page.layout.updateOptions`
 - 页面 AI host 已存在：`DocumentAiAgentPanel`
- AI 执行面已收口到 `mnote-cli` host / client
+- 历史实现已具备 `mnote-cli` host / client 最小返回链；后续应替换为 Hermes 页面内客户端
 - 评论 drawer、历史 drawer、分享 dialog 都已有各自最小实现

 但当前现网文档页仍然存在两个明显错位：
@@ -141,14 +142,15 @@

 > **把现有设置项放进更接近 Wolai 的容器，同时继续显式区分“已正式接通”和“仅保存字段/待接通”。**

-### 4.2 页面 AI 继续服从 `CLI-first`
+### 4.2 页面 AI 继续服从 Hermes 面板主线

 页面 AI 界面可以继续做产品壳，但它不能重新变成独立执行面。

-当前长期方向已经明确：
+当前长期方向已经改为：

- `mnote-cli` 是唯一长期 agent 执行面
- Web AI 面板只是 host / client
+- Hermes 是 AI session/message/tool event/usage/model 的会话真相
+- Web AI 面板只是页面内 Hermes client
+- mnote 通过 Hermes skill/plugin 暴露页面、树、artifact、edge 等业务工具

 因此本轮 AI 界面改造只处理：

@@ -326,7 +328,7 @@ Wolai 里页面设置和 AI 的第一感受，首先是：

 本轮不改：

- `mnote-cli` 执行链
+- 历史 `mnote-cli` 执行链
 - 工具注册表
 - 页面 AI 读写命令族
 - AI 输出协议
@@ -510,11 +512,11 @@ Rust `mnote-web` 当前在文档壳中已有顶栏占位按钮与右下角浮动

 ### 9.3 页面 AI 重复造轮子的风险

-如果为了像 Wolai 而新做一层 AI drawer runtime，会直接偏离 `CLI-first`。
+如果为了像 Wolai 而在 mnote 里新做一层独立 AI drawer runtime，会直接偏离当前 Hermes 面板主线。

 本轮约束：

-> **页面 AI 只换壳，不换执行面。**
+> **页面 AI 交互壳可继续沿用本轮成果，执行主线后续切到 Hermes client proxy + mnote plugin。**

 ### 9.4 范围失控风险

@@ -535,11 +537,11 @@ Rust `mnote-web` 当前在文档壳中已有顶栏占位按钮与右下角浮动
 - 页面设置入口、容器、关闭语义已和 Wolai 基线一致
 - 页面 AI 入口、容器、关闭语义已和 Wolai 基线一致
 - 页面设置仍继续走 `page.layout.updateOptions`
- 页面 AI 仍继续走 `DocumentAiAgentPanel -> mnote-cli`
+- 页面 AI 交互壳保留右下角入口 + 右侧抽屉；后续执行主线切到 Hermes client proxy + mnote plugin
 - 没有新增第二套页面设置真相
 - 没有新增第二套页面 AI 执行面
 - 评论、协作、成员、演示模式没有被混入首批范围

 本轮完成后的正确口径应是：

-> **文档页“页面设置”和“AI 界面”的交互壳开始按 Wolai 收口，但页面域单一真源与 CLI-first AI 的主线保持不变。**
+> **文档页“页面设置”和“AI 界面”的交互壳开始按 Wolai 收口；页面域单一真源保持不变，AI 长期主线改为 Hermes 面板 + mnote plugin。**
@@ -5,6 +5,7 @@
 > 状态说明：
 > - 本清单覆盖的页面设置 A/B、页面 AI C、集成护栏 D 均已完成并有 `task160/161/162` 证据，故迁入 `done/`
 > - `X1-X6` 属于明确 deferred 项，不构成这轮完成阻塞
+> - 2026-05-13 追加说明：本文保留 `task161/162` 对旧 `/api/ai-agent/run -> mnote-cli` 返回链的历史验证证据；AI 长期方向已由 `design/07-ai/process/7-3-page-ai-hermes-panel-and-mnote-plugin-v1.md` 改为 Hermes 页面内客户端 + mnote Hermes skill/plugin
 >
 > 本清单服务于：
 > - `/mnt/Data1T/mnote/design/05-editor-mainline/done/5-10-wolai-page-settings-and-ai-surface-alignment-v1.md`
@@ -231,9 +232,9 @@ GREEN：
 | C4 | GREEN | 顶栏 `页面AI` 降级 | `task161` 已断言顶栏不再保留 `页面AI` 主入口 |
 | C5 | GREEN | 页面 AI 容器类型 | `task161` 已断言页面 AI 以右侧抽屉打开、无遮罩、不跳新页面 |
 | C6 | GREEN | 页面 AI 关闭语义 | `task161` 已断言 `Esc`、点击空白无效，右上角 `X` 有效 |
-| C7 | GREEN | 页面 AI 页面级绑定 | `task161` 已断言 `/api/ai-agent/run` 请求体携带当前 `documentId` 与 `pageOptions` |
-| C8 | GREEN | 页面 AI 执行面不分裂 | 真实 `/api/ai-agent/run` 已改为 `Next 兼容优先 -> 本地 mnote-cli fallback -> 旧 orchestrator 兜底`；`task162` 已验证真实页面可返回文本结果 |
-| C9 | GREEN | AI chrome 与 Wolai 接近 | `task161` 已断言标题、输入区、`新会话 / 历史会话 / mnote-cli` chrome 可见 |
+| C7 | GREEN | 页面 AI 页面级绑定 | `task161` 已断言历史 `/api/ai-agent/run` 请求体携带当前 `documentId` 与 `pageOptions`；后续同类上下文应进入 Hermes run/session context |
+| C8 | GREEN | 页面 AI 历史返回链不分裂 | 真实 `/api/ai-agent/run` 曾改为 `Next 兼容优先 -> 本地 mnote-cli fallback -> 旧 orchestrator 兜底`；`task162` 已验证真实页面可返回文本结果；长期主线已改为 Hermes client proxy + mnote plugin |
+| C9 | GREEN | AI chrome 与 Wolai 接近 | `task161` 已断言标题、输入区、`新会话 / 历史会话 / mnote-cli` chrome 可见；后续文案应改为 Hermes session / model / history |

 ### 6.1 本阶段 smoke 建议

@@ -286,8 +287,8 @@ GREEN：
  - `Esc` 和点击空白不会关闭
  - 右上角关闭按钮可关闭
  - 抽屉标题、输入区、会话/模型 chrome 可见
-  - 发送动作继续命中 `/api/ai-agent/run`
- 请求体继续携带当前 `documentId` 与 `pageOptions`
+  - 发送动作在历史实现中继续命中 `/api/ai-agent/run`
+- 历史请求体继续携带当前 `documentId` 与 `pageOptions`；后续应转为 Hermes run/session context

 新增证据：

@@ -306,6 +307,7 @@ GREEN：
 - 同时补了认证头显式转发，避免被 Next 侧 307 `/auth` 拦截
 - 页面 AI drawer 默认 provider 改为 `hermes`
 - 新增 `task162-wolai-page-ai-real-response-smoke.js`，并在真实后端端口 `41327` 上验证：页面 AI 不再显示 `page_ai_failed_502` / “没有返回文本结果”，而是会回填真实文本
+- 2026-05-13 口径更新：上述修复只证明历史页面 AI 抽屉可返回文本，不再作为后续 AI 长期执行面依据；新的页面 AI 应直接调用 Hermes client proxy，不再通过 `/api/ai-agent/run` 的 provider / fallback 分支模拟 Hermes

 ### 6.3 task162 页面 AI 真实返回执行记录

@@ -325,7 +327,7 @@ GREEN：
 | ID | 状态 | 任务 | 验收要点 |
 | --- | --- | --- | --- |
 | D1 | GREEN | 不新造页面设置真相 | 页面设置继续围绕 `currentPageOptions -> /api/documents/options -> page.layout.updateOptions` |
-| D2 | GREEN | 不新造 AI 执行面 | 页面 AI 继续围绕 `/api/ai-agent/run -> mnote-cli` |
+| D2 | GREEN | 不新造 AI 执行面 | 历史实现围绕 `/api/ai-agent/run -> mnote-cli` 保持单链；后续不在 mnote 内新造 AI 执行面，而是调用 Hermes 并通过 mnote plugin 写回业务事实 |
 | D3 | GREEN | 文档页 owner 行为合同固定 | `task160/task161` 已断言 owner 态页面设置和 AI 都不跳新页面、不改 URL |
 | D4 | GREEN | mobile / 窄屏退化 | `task160/task161` 已断言移动视口下 popover / drawer 不超出视口 |
 | D5 | GREEN | React compat 与 Rust SSR 边界 | 本轮实现仅落在 `mnote-web` Rust SSR 壳、脚本与样式；未再把入口回接 React compat |
@@ -355,9 +357,9 @@ GREEN：
 - 页面设置 `popover` 行为已通过本地 smoke 和 Wolai 基线复核
 - 页面 AI 抽屉行为已通过本地 smoke 和 Wolai 基线复核
 - 页面设置仍然围绕 `page.layout.updateOptions`
- 页面 AI 仍然围绕 `/api/ai-agent/run -> mnote-cli`
+- 页面 AI 历史验证仍然围绕 `/api/ai-agent/run -> mnote-cli`；后续执行主线改为 Hermes client proxy + mnote plugin
 - deferred 项没有被误报为已完成

 本轮完成后的正确口径：

-> **页面设置与页面 AI 的交互壳已开始对齐 Wolai，但评论、协作、成员、演示模式仍是后续独立任务。**
+> **页面设置与页面 AI 的交互壳已开始对齐 Wolai；AI 后续执行主线改为 Hermes 面板 + mnote plugin，评论、协作、成员、演示模式仍是后续独立任务。**
@@ -1,6 +1,6 @@
 # 5-5-1 [done] Page Aggregate Contract v1

-> 更新时间：2026-04-22
+> 更新时间：2026-05-14
 >
 > 关联文档：
 > - `/mnt/Data1T/mnote/design/05-editor-mainline/process/5-5-page-aggregate-single-truth-alignment-v1.md`
@@ -92,13 +92,13 @@
 说明：

 - 这层不是“页面设置面板 UI state”，而是页面设置的持久化真相。
- 其中只有一部分已经进入 `leptos-tiptap` island 运行时：
+- 以下字段已经进入 `leptos-tiptap` island runtime payload：
  - `wideLayout`
  - `smallText`
  - `layoutDensity`
- 下面两项当前只完成字段贯通，不可描述成“正式支持”：
  - `showHeadingNumbers`
  - `embedDefaultBlockId`
+- 其中 `showHeadingNumbers` / `embedDefaultBlockId` 已进入 runtime payload，但深层语义仍是阶段性桥接：前者还不能描述成完整 heading 编号渲染闭环，后者还不能描述成完整嵌入默认落点闭环。

 ### 2.4 `page_body`

@@ -152,6 +152,24 @@

 - 统计不是页面身份，也不是布局或正文真相，但它是 page aggregate 的附属部分。

+### 2.7 `source` / provenance
+
+作用：
+
+> **标识这份 `PageAggregateProjection` 的真实构建来源。**
+
+当前允许值：
+
+- `KernelProjection`：底层已经由 Rust kernel 原生 page aggregate projection 产出。
+- `CompatMetaContentJoin`：对外已经是 Rust `mnote.page_aggregate.v1` 契约，但底层仍由 Rust runtime adapter 消费 `documents:getMeta + documents:getContent` substrate 后聚合。
+- `Fixture`：仅允许在测试或显式 dev fixture 场景出现。
+
+说明：
+
+- 当前 `/api/page-aggregate/:id` 主读链属于 `CompatMetaContentJoin`，不是完整 `KernelProjection`。
+- `source_label()` / `x-mnote-page-aggregate-owner` 必须与实际来源一致：`KernelProjection -> rust-kernel`，`CompatMetaContentJoin -> compat-join`，`Fixture -> fixture`。
+- 前端 loader 只消费 `mnote.page_aggregate.v1` 契约，不应因为来源是 `CompatMetaContentJoin` 而恢复 TS runtime builder 主链。
+
 ## 3. 哪些字段是 aggregate truth，哪些只是 UI state

 ### 3.1 Aggregate Truth
@@ -194,7 +212,7 @@
 - 标题输入中的 debounce 缓冲态
 - 正文 host 内的未保存 dirty 态
 - 只影响单次交互的面板/菜单开关
- `showHeadingNumbers/embedDefaultBlockId` 的“字段已贯通，但深语义未完成”阶段性桥接逻辑
+- `showHeadingNumbers/embedDefaultBlockId` 的“runtime payload 已贯通，但深语义未完成”阶段性桥接逻辑

 约束：

@@ -222,11 +240,11 @@

 - 树标题与页头标题已经证明消费同一份更新后的 projection
 - AI 写入口已经完全脱离 editor bridge，正式执行 page body command
- `showHeadingNumbers` 真正进入 heading 渲染语义
- `embedDefaultBlockId` 真正进入嵌入默认落点逻辑
+- `showHeadingNumbers` 完整进入 heading 编号渲染语义
+- `embedDefaultBlockId` 完整进入嵌入默认落点逻辑

 ## 7. 当前可对外口径

 当前可以准确描述为：

-> **文档页已开始消费统一 `Page Aggregate`，标题/页面设置/正文保存也开始按 `page_head / page_layout / page_body` 收口；但树域投影统一与 AI 正式 page body 写入口仍未完全完成。**
+> **文档页已开始消费统一 `Page Aggregate`，标题/页面设置/正文保存也开始按 `page_head / page_layout / page_body` 收口；当前 Rust route 主读链已成立，但 `/api/page-aggregate/:id` 底层仍是 `CompatMetaContentJoin`，树域投影统一与 AI 正式 page body 写入口也仍未完全完成。**