feat: wire page options through aggregate AI flow

design/05-editor-mainline/process/5-6-page-aggregate-alignment-checklist-v1.md

@@ -30,7 +30,7 @@
 ### 2.1 已经成立的事实
 
 - [x] `leptos-tiptap` 已经成为页面内正式主编辑区，不再是 iframe bridge。
-- [x] `/api/documents/page` 已优先消费 Rust `mnote.page_aggregate.v1` snapshot，TS builder 退为 fallback。
+- [x] 文档页正式读链已固定消费 Rust `mnote.page_aggregate.v1` snapshot，TS builder 已退出 runtime 主链。
 - [x] 正文保存已经能按 `workspaceId/documentId` 正确落到对应页面。
 - [x] 当前主编辑区已具备可继续推进的基础交互能力。
 - [x] 当前问题已经不再是“能不能接入主编辑器”，而是“接入后如何收口为单一真源”。
@@ -79,7 +79,7 @@
 - [x] 不再继续给 `DocumentPageProps`、`DocumentContentProps` 零散加字段来扩页面真相。
 - [x] 文档页加载入口能明确区分“聚合读取结果”和“局部 UI 临时态”。
 
-补充：当前已新增 `page-aggregate-builder.ts`、`page-aggregate-loader.ts` 与 `/api/documents/page`，文档页 SSR 入口和 `DocumentContent` 的内容重试补拉都已改为消费同一份 `PageAggregateProjection`，不再由 `page.tsx` 手工拼 `meta + content`。Rust 侧当前已直接暴露 `/api/page-aggregate/:id` 与 `mnote.page_aggregate.v1` snapshot；`page-aggregate-loader.ts` 会先校验并消费这条 Rust 读链，只有 snapshot 不可用或不可信时才回退到 TS builder。与此同时，`storage-convex-bridge` 与 `bridge-runtime` 已开始接受 `page.head.updateTitle / page.layout.updateOptions / page.body.save` 这组 page command family 的命名口径，因此这里按“读取契约已进入 Rust-first，写入命令面已开始收口”勾选完成。
+补充：当前 `page-aggregate-loader.ts`、文档页 SSR 入口与 `DocumentContent` 的内容重试补拉都已经直接消费 Rust `/api/page-aggregate/:id` 返回的 `PageAggregateProjection`，不再由 `page.tsx` 手工拼 `meta + content`。Next `/api/documents/page` 已降级为显式 `410` 的 compat 边界；`page-aggregate-loader.ts` 现在只校验并消费这条 Rust 正式读链，不再在 runtime 中回退到 TS builder。与此同时，`storage-convex-bridge` 与 `bridge-runtime` 已开始接受 `page.head.updateTitle / page.layout.updateOptions / page.body.save` 这组 page command family 的命名口径，因此这里按“读取契约已进入 Rust-first，写入命令面已开始收口”勾选完成。
 
 ### 4.3 退出标准
 
@@ -111,9 +111,9 @@
 - [x] 页面加载时不再能明显看出“这是几份子结果拼出来的页面”。
 - [ ] 后续页面新增字段时，不再需要继续向外层 props 链同时塞多种局部真相。
 
-补充：当前首屏 SSR 与客户端内容重试补拉都已经走 `/api/documents/page -> page aggregate loader -> PageAggregateProjection`，因此“页面明显由 `meta + content` 两次查询拼起来”的入口级痕迹已经消失；但新增字段仍可能需要继续补 loader / route / island 消费链，所以第二项继续保留未完成。
+补充：当前首屏 SSR 与客户端内容重试补拉都已经直接走 `/api/page-aggregate/:id -> PageAggregateProjection`，因此“页面明显由 `meta + content` 两次查询拼起来”的入口级痕迹已经消失；但新增字段仍可能需要继续补 loader / route / island 消费链，所以第二项继续保留未完成。
 
-补充：本轮已新增 `page-aggregate-client-state.ts`，并让 `DocumentContent` 把原先分散维护的 `options / content / serverContentSnapshot / serverPageSubtreeSnapshot / serverPageSubtreeTitle / contentRevision / conflictDetectionKey` 开始收口为同一份 client aggregate state reducer。这里代表“页面本地 `body/layout/tree` 真相已经开始统一”，不等于标题链、页面设置运行时分类、AI 对页面设置面的正式入口都已闭环，因此本阶段不提前宣称聚合完成。对应最小回归测试为 `page-aggregate-client-state.test.ts`。
+补充：本轮已新增 `page-aggregate-client-state.ts`，并让 `DocumentContent` 把原先分散维护的 `title / options / content / serverContentSnapshot / serverPageSubtreeSnapshot / contentRevision / conflictDetectionKey` 继续收口为同一份 client aggregate state reducer；标题的 draft / committed / persisted 语义也已并入这份 reducer，不再额外维护独立 `usePageHeadTitle` hook 或 `serverPageSubtreeTitle` 双轨状态。这里代表“页面本地 `head/body/layout/tree` 真相已经开始统一”，不等于页面设置运行时分类、AI 对页面设置面的正式入口都已闭环，因此本阶段不提前宣称聚合完成。对应最小回归测试为 `page-aggregate-client-state.test.ts`、`document-content.test.ts`。
 
 ---
 
@@ -138,6 +138,14 @@
 
 对应最小回归测试为 `page-option-semantics.test.ts`、`leptos-tiptap-island-editor-host.test.tsx`、`page-options-sidebar.test.tsx`。第二项继续保留未完成，因为“哪些项应降级/隐藏/保留”的产品面纠偏还没完全落到 inspector 与 AI tool surface。
 
+补充：当前统一口径已经开始落到代码级 `PAGE_OPTION_PANEL_POLICY`，最小分类如下：
+
+- 保留在页面设置面板且继续作为正式项：`wideLayout / smallText / showHeadingNumbers / showToc / showWordCount / collapseBacklinks / pageFont / layoutDensity / hideChildPages / embedDefaultBlockId`
+- 保留但降级展示、不再冒充正式完成项：`protectEditing / showBlockRefCount`
+- 不再作为页面级正式项，继续留在全局偏好：`showStructure`
+
+这里的“保留 / 降级 / 全局”是当前 Inspector、AI 页面设置写回白名单与后续 smoke 验收都必须共用的同一份产品口径，不允许再由单个 UI 文件私自重写说明。
+
 ### 6.2 最小接入优先级
 
 - [x] `wideLayout` 真正进入 island 布局语义，而不是只改外层壳宽度。
@@ -150,12 +158,23 @@
 
 - [x] 没有真正接入 island 的编辑器语义项，不再继续以“已开启/已关闭”假装正式完成。
 - [x] 对未支持项给出显式降级说明，而不是仅保存字段。
-- [ ] 让“页面设置有值但编辑器内部没变化”这类状态在产品上消失。
+- [x] 让“页面设置有值但编辑器内部没变化”这类状态在产品上消失。
+
+补充：本轮已把 AI 页面设置结构化结果接入 `DocumentContent` 现有的 `patch_page_options + page.layout.updateOptions` 正式链路，页面设置不再只能靠人类点击 inspector 才能进入同一条页面命令面。同时，AI 正式写回白名单已限制为 `page-option-semantics.ts` 中 `runtimeSupport === "wired"` 的字段，`protectEditing / showStructure / showBlockRefCount` 继续排除在正式写回外，避免把 planned / ui_only 选项误描述为稳定能力。`mnote-cli host` 侧也已新增最小服务端分支：命中页面设置 patch 时，直接执行 `page.layout.updateOptions` 并产出结构化 `tool_result(action=update_page_options)`，不再只把整段结果退化成 assistant 文本。对应最小回归测试为 `DocumentAiAgentPanel.runtime.test.tsx`、`mnote-cli-agent-host.test.ts`。
+补充：本轮继续把 Inspector 产品态与这份分类对齐：`showHeadingNumbers / embedDefaultBlockId` 已按“正式接通项”更新文案，不再继续显示“已保存字段但未接通”；`showBlockRefCount` 作为纯占位项也不再继续暴露可点击的假开关，而是明确显示 `待接线`。对应最小回归测试为 `page-options-sidebar.test.tsx`、`page-option-semantics.test.ts`。
 
 ### 6.4 退出标准
 
-- [ ] inspector 中至少最小优先级项修改后，主编辑区可见结果真实变化。
-- [ ] 用户不再需要猜“这个设置到底有没有真正作用到编辑器”。
+- [x] inspector 中至少最小优先级项修改后，主编辑区可见结果真实变化。
+- [x] 用户不再需要猜“这个设置到底有没有真正作用到编辑器”。
+
+补充：本轮已新增 `scripts/task164-page-options-visible-effect-smoke.js`，并在 `http://127.0.0.1:3000` 实跑确认：
+
+- `wideLayout` 从 `false -> true` 后，页面根属性 `data-page-wide-layout` 立即切到 `true`，主内容列最大宽度从默认态切到 `980px`
+- `smallText` 从 `false -> true` 后，编辑器字号从 `16px` 变为 `15px`
+- `layoutDensity` 从 `normal -> compact` 后，段落底部间距从 `8px` 变为 `4px`
+
+同时，Inspector 文案与状态也已经按“正式接通 / 待接线 / 全局项”统一，不再让用户靠猜测判断设置是否真正生效。
 
 ---
 
@@ -185,7 +204,7 @@
 
 补充：已新增 `AppLayoutShell`，把 layout 顶栏 `Breadcrumb` 从 SSR 注入的静态 `documents` 挪到与 `Sidebar` 共享的同一条 live sidebar snapshot 管线；并且 layout shell 会把“已选中的 preferred snapshot”同一对象同时透传给 `Sidebar` 与 `Breadcrumb`，不再各自独立选择。对应回归测试为 `app-layout-shell.test.tsx`。这意味着 breadcrumb / sidebar 现在至少共享同一份工作区树 canonical snapshot，不再是 layout 一条静态链、sidebar 一条 live 链并行。页头 `page.head.title` 与这条工作区树链之间的最终统一验收仍待补齐，因此本阶段继续不提前打满。
 
-补充：已新增 `PreferredSidebarSnapshotProvider` 与 `usePageHeadTitle`，把文档页头标题从 `DocumentContent` 内部长期持有的 `pageTitle` 本地真相，改为“同一份 preferred sidebar snapshot 的 committed title + 短暂 draft”。同时修正 `useSidebarData.refetch()`，在 Convex live 模式下收到 `documents-changed` 也会主动拉取一份新的 `/api/sidebar` snapshot，再与 tree stream 做 freshness 选择，避免“页头草稿是新的，但 breadcrumb / sidebar / page tree / file tree 还卡在旧快照”。对应单测为 `use-page-head-title.test.tsx`、`use-sidebar-data.test.tsx`。浏览器烟测 `scripts/task110-page-title-single-truth-smoke.js` 已验证：页头重命名后，breadcrumb、默认 sidebar、page tree、file tree、切页往返、刷新均保持一致，因此本阶段与“标题来自同一份更新后的 projection”相关的勾选正式保留。
+补充：已新增 `PreferredSidebarSnapshotProvider`，并把文档页头标题的本地 draft / committed / persisted 语义直接并入 `page-aggregate-client-state`；`DocumentContent` 现在只从同一份 preferred sidebar snapshot 读取 live committed title，再与聚合 reducer 内的短暂 draft / persisted title 做合成，不再额外维护独立标题 hook。与此同时，`useSidebarData.refetch()` 在 Convex live 模式下收到 `documents-changed` 也会主动拉取一份新的 `/api/sidebar` snapshot，再与 tree stream 做 freshness 选择，避免“页头草稿是新的，但 breadcrumb / sidebar / page tree / file tree 还卡在旧快照”。对应单测为 `page-aggregate-client-state.test.ts`、`use-sidebar-data.test.tsx`。浏览器烟测 `scripts/task110-page-title-single-truth-smoke.js` 已验证：页头重命名后，breadcrumb、默认 sidebar、page tree、file tree、切页往返、刷新均保持一致，因此本阶段与“标题来自同一份更新后的 projection”相关的勾选正式保留。
 
 ### 7.3 退出标准
 
@@ -219,6 +238,18 @@
 - [x] AI 改写结果能通过主编辑区 island 正式回显。
 - [ ] AI 改写后树标题 / 页面头部 / 页面设置不再走各自独立副作用链。
 
+补充：进入这一步后，当前最大的真实 blocker 已经明确下来，不再继续靠口头描述模糊处理：
+
+- `/api/ai-agent/run` 当前默认主路仍是 `mnote-cli host`
+- `mnote-cli host` 目前没有真正的模型/tool 执行环，而是 `cargo ... tool run --tool-name doc_get --mode explain-plan` 的说明型入口
+- 因此，当前新增的 `page_options_patch -> page.layout.updateOptions -> structured tool_result` 仍然只是“主路内的最小结构化兼容分支”，不是完整正式 tool surface
+
+这意味着 `8.2` 后续完成标准必须至少包含：
+
+1. 页面设置进入真正的 agent/tool 执行环，而不是继续靠 host 内部的自然语言/最小规则分支识别
+2. 页面设置结构化结果由正式 tool 调用产出，而不是只由 host 自己补一条兼容 `tool_result`
+3. 树标题 / 页头 / 页面设置三条 AI 写回链在同一条正式 page aggregate command family 中闭环，并补 smoke 验证
+
 ### 8.3 退出标准
 
 - [x] AI 写入口已经可以被明确描述为“操作 page aggregate command family”，而不是“绕过系统写编辑器”。 
@@ -227,7 +258,9 @@
 
 - `doc_insert_blocks / doc_replace_range` 继续按 `page.body.save` 语义落到 `/api/documents/save`，再正式回显主编辑区 island。
 - `slash_run(rename current page)` 会把结构化结果回接到当前页 `DocumentContent` 的同一条标题提交链，并继续广播 `emitDocumentsChanged(documentId)`，因此页头标题与树标题不再靠 AI 面板内部本地状态各自漂移。
-- 当前 `pageOptions` 仍没有进入 Hermes 正式 tool surface，因此“页面设置类 AI 命令”尚未收口；`8.2` 的最后一项继续保留未完成，避免误判为整条线已经闭环。
+- 当前 AI 面板已经能消费结构化 `update_page_options` 结果，并把 `pageOptionsPatch` 回接到当前页 `DocumentContent` 的同一条 `patch_page_options + page.layout.updateOptions` 提交链；同时只允许 `runtimeSupport === "wired"` 的字段进入正式写回，避免 planned / ui_only 页面设置混入主链。对应最小回归测试为 `DocumentAiAgentPanel.runtime.test.tsx`、`document-content.test.ts`。
+- `mnote-cli host` 现已能在命中页面设置 patch 时直接执行 `page.layout.updateOptions`，并向前端回放结构化 `tool_call/tool_result` 事件；这意味着“服务端完全没有页面设置结构化写回结果”的状态已经结束。
+- 但 `pageOptions` 仍没有进入 Hermes 正式 tool surface，当前服务端 patch 识别也仍是最小规则分支而不是完整模型工具编排，因此“页面设置类 AI 命令”仍不能算整条线已闭环；`8.2` 的最后一项继续保留未完成，避免误判为整条线已经闭环。
 
 ---