mnote/design/05-editor-mainline/process/5-10-wolai-page-settings-and-ai-surface-alignment-v1.md

# 5-10 [process] Wolai 页面设置与 AI 交互壳对齐方案 v1

> 更新时间：2026-05-06
>
> 关联文档：
> - `/mnt/Data1T/mnote/ARCHITECTURE.md`
> - `/mnt/Data1T/mnote/design/01-05-current-priority-overview.md`
> - `/mnt/Data1T/mnote/design/05-editor-mainline/process/5-5-page-aggregate-single-truth-alignment-v1.md`
> - `/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/08-wolai-aline-test-flow/process/wolai-aline-test-flow-v1.md`

## 1. 文档目的

这份文档只回答一个问题：

> **在不制造第二份页面真相、不重开一条 AI 执行面的前提下，如何把 `3000` 文档页的“页面设置”和“AI 界面”收口成更接近 Wolai 的交互壳。**

这次不处理整条文档页体验复刻，也不把评论、协作、演示模式一起打包推进。

本轮优先级固定为：

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

一句话收口：

> **先把“入口和容器”做对，再逐项把内部动作接到现有正式命令链。**

---

## 2. 当前判断

### 2.1 当前 `3000` 的问题不是“没有能力”，而是“能力挂错了壳”

当前仓库里已经有可复用能力：

- 页面设置 UI 已存在：`PageOptionsSidebar`
- 页面设置写链已存在：`page.layout.updateOptions`
- 页面 AI host 已存在：`DocumentAiAgentPanel`
- AI 执行面已收口到 `mnote-cli` host / client
- 评论 drawer、历史 drawer、分享 dialog 都已有各自最小实现

但当前现网文档页仍然存在两个明显错位：

- 页面设置还是“右侧整块 inspector”思路，不是 Wolai 的右上角 `...` 贴边 popover
- 页面 AI 主要还是顶栏“页面AI”按钮思路，不是 Wolai 的右下角浮动入口 + 右侧抽屉

因此本轮不应重写一套新产品，而应优先做：

> **现有能力重新编排到正确交互壳。**

### 2.2 当前不该做的事

本轮明确不做：

- 不新造第二套页面设置数据结构
- 不新造第二套页面 AI runtime
- 不把 Web AI 面板重新升格成独立 AI 编排主线
- 不为了像 Wolai 而把评论、协作、成员、演示模式一并拉进首批实现
- 不在 Rust SSR 和 React compat 层同时各做一套相同按钮逻辑

---

## 3. Wolai 基线

2026-05-06 已通过 `wolai-aline` 基线取证得到当前 Wolai 行为证据，截图目录：

- `/mnt/Data1T/mnote/tmp/wolai-editor-parity/page-settings-ai-baseline/`

关键结论如下。

### 3.1 页面设置

- 入口位于右上角 `...`
- hover tooltip 为“页面选项和全局选项”
- 点击后打开右侧贴边 `popover`，不是 modal，也不是新页面
- URL 保持不变
- 没有遮罩，不压暗背景
- 关闭方式为：
  - `Esc`
  - 点击页面空白处
  - 再次点击同一入口
- 顶部为 `页面选项 / 自定义页面 / 全局选项` 三个 tab
- 可见开关为 checkbox 形态
- 当前主 tab 内有：
  - `自适应宽度`
  - `小字体`
  - `标题目录`
  - `标题自动编号`
  - `编辑保护`
- 下方还有动作项：
  - `删除页面`
  - `移动到...`
  - `嵌入到...`
  - `页面历史...`
  - `公开分享页面...`

### 3.2 AI 界面

- 入口位于右下角浮动 `AI` 按钮
- 点击后打开右侧抽屉，不改 URL
- 抽屉没有遮罩，不压暗背景
- 当前关闭方式只有右上角 `X`
- `Esc` 无效
- 点击页面空白处无效
- 入口按钮在抽屉打开后被覆盖，不承担 toggle 关闭语义
- 抽屉标题为“智能问答”
- 中部存在推荐问题/快捷入口
- 底部存在会话区、模型入口、输入框和发送按钮

这说明本轮对齐的最小行为合同已经足够明确：

> **页面设置是“顶栏入口 + 贴边 popover”；页面 AI 是“右下角入口 + 右侧抽屉”。**

---

## 4. 设计原则

### 4.1 页面设置继续服从 `Page Aggregate`

页面设置只能是：

- `pageOptions`
- `editorRuntimePageOptions`
- 对应的 `page.layout.updateOptions`

不能变成：

- 某个单独 UI 组件内部维护的临时配置真相
- 一套只在文档页壳层生效、却不进入主编辑器 runtime 的新设置体系

因此，页面设置改造的重点不是多做几个开关，而是：

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

### 4.2 页面 AI 继续服从 `CLI-first`

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

当前长期方向已经明确：

- `mnote-cli` 是唯一长期 agent 执行面
- Web AI 面板只是 host / client

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

- 入口位置
- 抽屉壳形态
- 页面级上下文绑定
- 与现有 `DocumentAiAgentPanel` 的挂载方式

本轮不处理：

- AI runtime 重写
- 新模型编排
- 新工具协议
- 第二套全局 AI 路由

### 4.3 先对齐容器语义，再推进动作项

Wolai 里页面设置和 AI 的第一感受，首先是：

- 从哪里打开
- 打开成什么容器
- URL 是否变化
- 如何关闭

这四项比内部是否一开始就全部可用更重要。

因此本轮优先级必须是：

1. 入口位置和按钮密度对齐
2. 容器形态和开关语义对齐
3. 内部动作项逐项复用现有能力

---

## 5. 本轮范围

### 5.1 范围内

- 文档页 owner 态右上角 `...` 页面设置入口
- 页面设置 `popover` 容器
- 页面设置 `tablist` 和最小项分组
- 页面设置最小动作项接线策略
- 文档页右下角浮动 `AI` 入口
- 页面 AI 右侧抽屉容器
- 页面 AI 与现有 `DocumentAiAgentPanel` 的页面级绑定
- 相应 smoke、截图和差异矩阵

### 5.2 暂不进入本轮

- 演示模式
- 页面评论
- 页面协作
- 成员邀请
- 完整公开分享体验重做
- 全局 AI 面板收口
- 帮助中心浮动入口的完整 Wolai 化
- AI 内部推荐内容、模型文案、提示词体系大改

补充：

- `页面历史...` 和 `公开分享页面...` 因为当前已有最小能力，可以作为本轮页面设置动作项的优先复用对象
- 评论、协作、成员这类能力虽然在 Wolai 顶栏可见，但当前不进入首批实现

---

## 6. 目标交互合同

## 6.1 页面设置

### 6.1.1 入口

- 入口继续位于文档页右上角操作区
- 视觉上以 `...` 弱按钮承载
- tooltip 调整为“页面选项和全局选项”
- 不再把“页面设置”理解成常驻右侧栏

### 6.1.2 容器

- 使用右侧贴边 `popover`
- 不使用全屏 modal
- 不使用带遮罩的 `Sheet`
- 打开后 URL 不变
- 面板宽度以 Wolai 的紧凑设置面板为准，不沿用当前宽侧栏比例

### 6.1.3 关闭语义

- `Esc` 关闭
- 点击空白关闭
- 再次点击入口关闭

### 6.1.4 内容结构

顶部固定三 tab：

- `页面选项`
- `自定义页面`
- `全局选项`

页面选项首批保留并对齐的设置项：

- `wideLayout`
- `smallText`
- `showToc`
- `showHeadingNumbers`
- `protectEditing`

自定义页面首批保留：

- `pageFont`
- `layoutDensity`
- `collapseBacklinks`
- `hideChildPages`
- `showBlockRefCount`
- `embedDefaultBlockId`

全局选项首批只保留当前已有全局偏好中与文档体验直接相关的最小项，不在本轮扩面。

### 6.1.5 动作项

页面设置面板中的动作项分三类：

1. 本轮直接接线
   - `页面历史...`
   - `公开分享页面...`

2. 本轮保留入口但延后落地
   - `移动到...`
   - `嵌入到...`
   - `删除页面`

3. 本轮不放入页面设置面板
   - 评论
   - 协作
   - 成员邀请
   - 演示模式

设计原因：

- `历史` 和 `分享` 当前已有组件可复用
- `移动到 / 嵌入到 / 删除` 与树命令、确认流和 picker 交互更深，应拆成后续小任务
- 评论/协作不在本轮优先级内

## 6.2 页面 AI

### 6.2.1 入口

- 文档页主入口改为右下角浮动 `AI` 按钮
- 顶栏“页面AI”不再作为主入口
- 首批可以先去掉顶栏 `页面AI`，或把它降为 debug/临时入口，不再作为默认视觉路径

### 6.2.2 容器

- 使用右侧抽屉
- 不使用遮罩
- 打开后 URL 不变
- 抽屉属于“页面级 AI”，不是全局 AI

### 6.2.3 关闭语义

- 右上角 `X` 关闭
- `Esc` 不关闭
- 点击页面空白不关闭
- 不要求入口按钮承担 toggle 关闭

### 6.2.4 内容结构

抽屉内部继续复用现有 `DocumentAiAgentPanel` 与其 runtime。

本轮只改：

- 外层 chrome
- 标题区与关闭按钮
- 页面级容器布局
- 文档页入口位置和打开方式

本轮不改：

- `mnote-cli` 执行链
- 工具注册表
- 页面 AI 读写命令族
- AI 输出协议

### 6.2.5 页面级与全局级边界

页面文档内优先展示“页面级 AI”。

全局 AI 继续保留其现有能力，但不在本轮文档页里抢主入口。长期关系应为：

- 文档页浮动 AI：页面上下文优先
- 全局 AI：跨页面/全局工作区能力

---

## 7. 实现落点

## 7.1 顶栏与入口层

当前文档页右上角操作主入口仍由：

- `wolai-frontend/src/components/breadcrumb.tsx`

负责。

因此本轮入口层优先落在 React compat 主路径，而不是先去大改 Rust SSR 占位按钮。

首批调整建议：

- `Breadcrumb` 负责右上角 `...` 入口
- `Breadcrumb` 不再突出“页面AI”主按钮
- 浮动 AI 入口改由文档页内容壳或页面级 host 提供

理由：

- 当前现网入口真正在这里
- 直接改这里可以最小改动验证体验
- 先把交互壳对齐，再决定 Rust SSR 侧是否同步收口

## 7.2 页面设置面板组件

当前 `PageOptionsSidebar` 是一个“常驻侧栏”组件，形态上不适合直接复用为 Wolai popover。

建议拆成两层：

1. `PageOptionsPanelContent`
   - 只负责 tab、设置项、动作项内容
   - 不假设自己是 `aside`

2. `PageOptionsPopover`
   - 负责定位、宽度、开关语义、关闭语义
   - 作为文档页 owner 态页面设置入口的正式容器

同时保留：

- `PageOptionsSidebar`

作为兼容/开发容器，避免 dev playground 与旧测试全部失效。

### 7.2.1 页面设置状态

当前 `usePageLayoutStore.showInspector` 语义过于偏“右侧常驻 inspector”。

本轮建议把它改造成更接近“页面 chrome 状态”的命名，例如：

- `pageSettingsOpen`

或等价 surface state，但不要把 AI 和页面设置混成一个大 store。

最小原则：

- 页面设置开关状态独立
- 不影响 AI drawer store
- 不重新发明 `pageOptions` 数据真相

## 7.3 页面设置动作项接线

动作项接线优先复用现有能力：

- `页面历史...` -> `DocumentHistoryDrawer`
- `公开分享页面...` -> `DocumentShareDialog`

本轮延后：

- `移动到...`
- `嵌入到...`
- `删除页面`

这些项可以先作为 disabled/coming soon，或只在 checklist 中保留为后续项，但不要假装完成。

## 7.4 页面 AI host

页面 AI 的正式 runtime 继续使用：

- `DocumentAiAgentPanel`
- `DocumentAiAgentPanel.runtime`

本轮只需要把“谁来打开它、以什么容器打开它”改对。

建议：

- 页面级浮动 AI 入口挂在 `DocumentContent` 这一层
- 页面 AI 打开状态继续用 `useAiAgentUiStore.documentAgentOpen`
- 页面 AI 可用态继续由 `DocumentAiAgentPanel` mount 生命周期维护

需要避免：

- 再新增一份 `PageAiDrawer` 独立 runtime
- 把页面 AI 又接回 `GlobalAiAgentHost`

## 7.5 与 Rust SSR 的关系

Rust `mnote-web` 当前在文档壳中已有顶栏占位按钮与右下角浮动按钮。

本轮不把 Rust SSR 作为首批真实交互 owner，原因是：

- 当前现网文档页真实入口仍由 React compat 壳主导
- 先在 React compat 层做对入口与容器，风险更低
- 等行为稳定后，再决定是否把 Rust SSR 占位按钮收口到同一 contract

这意味着本轮的正确做法是：

> **先统一产品行为合同，再决定是否让 Rust SSR 与 React compat 共用同一套入口渲染。**

---

## 8. 分阶段实施建议

## 8.1 Phase A：设计与基线冻结

- 固定 Wolai 页面设置和 AI 抽屉的动作链基线
- 新增专属 checklist
- 明确哪些页面设置项本轮保留、隐藏、降级
- 明确页面 AI 与全局 AI 的入口边界

## 8.2 Phase B：页面设置交互壳

- 把 `PageOptionsSidebar` 抽成可复用内容组件
- 文档页顶栏 `...` 接入 `PageOptionsPopover`
- 对齐关闭语义、URL 不变、无遮罩
- 最小接线 `历史` 与 `分享`

## 8.3 Phase C：页面 AI 交互壳

- 增加右下角浮动 `AI` 入口
- 让页面 AI 通过右侧抽屉打开
- 去掉顶栏“页面AI”主入口地位
- 对齐 AI drawer 的关闭语义

## 8.4 Phase D：动作项与回归补齐

- 页面设置中逐步接通 `移动到 / 嵌入到 / 删除`
- 评估是否追加帮助浮动入口对齐
- 为 owner/published 两种状态补差异 smoke

---

## 9. 风险与约束

### 9.1 双 owner 风险

当前 `3000` 仍有：

- Rust SSR 产品壳
- React compat 真正交互壳

如果同时在两边各自补交互，容易再次分裂。

本轮约束：

> **入口行为先只认一套真实 owner。**

### 9.2 页面设置“看起来能改，实际没生效”的风险

这仍是页面设置线的核心风险。

本轮约束：

- 未接通项继续显式降级
- 不因为换成 Wolai 容器就把所有项都宣称正式可用

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

如果为了像 Wolai 而新做一层 AI drawer runtime，会直接偏离 `CLI-first`。

本轮约束：

> **页面 AI 只换壳，不换执行面。**

### 9.4 范围失控风险

页面设置一旦带上评论、成员、协作、演示模式，很容易从“交互壳对齐”膨胀成“整页顶栏重做”。

本轮约束：

- 优先做页面设置
- 优先做页面 AI
- 其他项延后

---

## 10. 验收标准

只有同时满足以下条件，才可以说这条线进入实现阶段：

- 页面设置入口、容器、关闭语义已和 Wolai 基线一致
- 页面 AI 入口、容器、关闭语义已和 Wolai 基线一致
- 页面设置仍继续走 `page.layout.updateOptions`
- 页面 AI 仍继续走 `DocumentAiAgentPanel -> mnote-cli`
- 没有新增第二套页面设置真相
- 没有新增第二套页面 AI 执行面
- 评论、协作、成员、演示模式没有被混入首批范围

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

> **文档页“页面设置”和“AI 界面”的交互壳开始按 Wolai 收口，但页面域单一真源与 CLI-first AI 的主线保持不变。**