feat(UI): 显示布局边界（Android 风格）+ 工具栏设置菜单（齿轮）+ 三处可见收益优化

## 1. 新功能：齿轮按钮 -> 应用设置菜单 -> 显示布局边界 - ToolbarAction::SETTINGS 位于「导入文件」左侧；工具栏布局改为「左侧固定簇（kLeftClusterCount = 2：齿轮 + 导入文件）+ 右侧按钮组」。 - 齿轮是矢量化绘制（8 齿 + 外环 + 轴孔，全部按 half 的比例推导），不用字体字符「⚙」——该字符在不同回退字体里大小与基线不一致，会忽大忽小、垂直不居中。 UiButtonWidget 新增 UiButtonIcon（NONE / GEAR）与 SetIcon。 - MenuScope::APP_SETTINGS（新增）+ 设置菜单：HEADER「调试」+ 勾选切换项「显示布局边界」（keepOpen：点击后菜单保持打开，勾选态由 UpdateItemLabel 回写）。锚点取 Toolbar::ButtonRect(SETTINGS) 的控件实测矩形，宿主不再自己推算按钮几何。 ## 2. 布局边界：基类给协议，组件自己上报 - UiComponent 新增 virtual PaintDebugBounds(g, scale)，默认只画 Area()。 - Toolbar / TabBar 覆盖：跳过与区域重合的根控件，遍历 m_root->Children()（层级 1）； TabBar 另上报每个 ✕（层级 2）。 - SignalPanel 覆盖：表头 / 筛选框 / 列表 / 样式区（1）+ 滚动条、样式行、当前可见列表行（2）。 - PlotView 覆盖：每个 LaneVisual::rect（1）；不上报随数据变化的瞬态几何（曲线/胶囊/提示）。 - UiWidget 新增 PaintDebugBounds(g, scale, depth) 递归整棵控件树 —— 已上树的控件零成本获得边界。 - 宿主 PaintLayoutBounds 补客户区外框、分隔条、打开的菜单/拾色器。视觉与实现约束（Android「Show layout bounds」风）： - 只描边、不填充（几十个嵌套矩形叠加填充会把内容糊住）； - 层级配色青蓝(2px) / 品红 / 琥珀 / 绿(1px)； - 线宽按设备像素固定（不乘 scale），临时 PixelOffsetModeNone + 关抗锯齿 + 整像素对齐，保证 1px 就是 1px； - ⚠️ 只在 Render 最后一步叠加，绝不进入任何位图缓存（PlotView 4 层缓存 / SignalPanel 行位图缓存），否则关掉开关后线条会残留； - ⚠️ fullFrame 并入 m_showLayoutBounds：开启时必须整帧回送，否则「只回送绘图区」的快路径会让装饰区边界停在旧帧上。 ## 3. 可见收益优化（行为不变） - Toolbar::Layout：控件树改为按需重建（m_treeDirty），只在规格/字体/主题/缩放/动态文本变化时重建。拖动面板分隔条时 Relayout 每帧调用一次 -> 不再每帧 10 次堆分配 + 8 次测量缓存失效。 - Toolbar::SetActionLabel：只写 m_labelOverrides（唯一权威）+ 置树脏，消除「覆盖表与控件文本双写」可能不同步的问题。 - UiWidget::DispatchRedraw(event)：新增；收敛 Toolbar / TabBar 里重复的 Dispatch(); return UiRectHasArea(TakeDirty());（TakeDirty 会清零，漏一次就把下一次真实变化误判成「无变化」）。 ## 4. 验证 - make release / make debug：零 error 零 warning；TargetCheck.exe 897,024 B（< 900 KB）。 - 新增离屏探针 .preflight/lbcheck：21 / 21 PASS （齿轮在导入文件左侧/同高/更窄；开启后青蓝 24,930 px、品红 19,734 px；关闭后逐像素还原；菜单 scope、锚定贴合按钮、宽度未被撑大、条目初始未勾选、点击翻转开关、菜单保持打开）。 - Tools/rendercheck：8 个场景的「工具栏带以下区域」哈希与改造前**逐一相同** （证明改动像素被完全限制在工具栏带内）；整帧哈希因新增按钮整体变化，属预期。 FUNC 断言 7 / 7 PASS。 - Tools/uicheck：69 passed / 0 failed。 ## 5. 文档 Documents/UI_Refactor_Plan.md / UI_Refactor_Progress.md / UI_Refactor_Report.md 追加第六阶段； Documents/agent_mem.md 同步变更日志与「2026-10-28 第八轮」硬约束与验证坑。
2026-10-28 15:46:45 +08:00
1 parent 0ec8055e95
commit ab19a6e72e
@@ -356,3 +356,89 @@ protected:
 * `Tools/uicheck` 69/69；
 * `TargetCheck.exe` < 900 KB；
 * `git ls-files Tools` 返回空、`git status` 干净、`main` / `dev` 未被触碰。
+
+---
+
+# 第六阶段（2026-10-28）：「显示布局边界」调试开关 + 三处可见收益优化
+
+> 用户要求：先做可见收益的优化，然后在「导入文件」左侧加一个齿轮按钮，点击展开二级菜单，
+> 菜单里放「显示布局边界」勾选项，风格参考 Android 调试功能；先落地，后续再改进。
+
+## 1. 可见收益的优化（3 项，均为纯收益、行为不变）
+
+| # | 位置 | 改前 | 改后 | 收益 |
+| --- | --- | --- | --- | --- |
+| O1 | `Toolbar::Layout` | **每次**都 `RebuildWidgets()`（销毁 + 重建整棵树） | 新增 `m_treeDirty`，只在规格/字体/主题/缩放/动态文本变化时重建 | 拖动面板分隔条时 `Relayout` 每帧调用一次 ⇒ 每帧省 10 次堆分配 + 8 次测量缓存失效 |
+| O2 | `Toolbar::SetActionLabel` | 同时写「覆盖表」和「控件文本」两处 | 只写覆盖表 + 置树脏 | 消除双写可能不同步（旧实现下次重建会把文本退回默认值） |
+| O3 | `Toolbar` / `TabBar` 的 `OnMouseMove` | 各自手写 `Dispatch(); return UiRectHasArea(TakeDirty());` | 新增 `UiWidget::DispatchRedraw(event)` | 两处重复收敛成一处；`TakeDirty()` 会清零，漏掉一次就把下一次真实变化误判为"无变化" |
+
+## 2. 新功能：齿轮按钮 → 应用设置菜单 → 显示布局边界
+
+### 2.1 入口
+
+* `ToolbarAction::SETTINGS` + `kButtonSpecs[0]`（`UiButtonIcon::GEAR`）。
+* 工具栏布局从"首按钮靠左 + 其余靠右"改为**左侧固定簇**（`kLeftClusterCount = 2`：齿轮 + 导入文件）+ 右侧按钮组。
+* 齿轮是**矢量绘制**（`PaintGearIcon`：8 齿 + 外环 + 轴孔，全部按 `half` 的比例推导），
+  不用字体里的 `⚙` —— 该字符在不同回退字体里的大小与基线不一致，会"忽大忽小、垂直不居中"。
+* `UiButtonWidget` 新增 `UiButtonIcon`（`NONE`/`GEAR`）与 `SetIcon`；图标按钮宽度固定 40 逻辑像素。
+* `Application::OpenSettingsMenu()` 用 `Toolbar::ButtonRect(SETTINGS, …)` 取**控件实测矩形**做锚点
+  （宿主不自己推算按钮几何），菜单在按钮下沿 +4 逻辑像素处右下展开。
+
+### 2.2 菜单
+
+`MenuScope::APP_SETTINGS`（新增）→ 宿主自己处理，不下发到组件。
+条目：`HEADER "调试"` + `NORMAL "显示布局边界"`（`keepOpen = true`，点击后菜单保持打开，
+勾选态由 `PopupMenu::UpdateItemLabel` 回写）。
+
+### 2.3 布局边界：为什么放在共同基类
+
+`UiComponent` 新增 **`virtual void PaintDebugBounds(gd::Graphics&, float scale)`**，默认只画 `Area()`。
+四个组件各自覆盖：先调基类（自己的区域），再补画**层级更深的**矩形。
+
+这正是上一轮回答里"是不是只需要在共同基类内实现"的答案：
+**能覆盖顶层 4 块区域，覆盖不了组件内部的手绘结构**。所以采用"基类给出协议 + 组件自己上报"：
+
+| 组件 | 上报内容 |
+| --- | --- |
+| 全部 | `Area()`（层级 0） |
+| `Toolbar` / `TabBar` | 跳过与区域重合的根控件，直接遍历 `m_root->Children()`（层级 1）；TabBar 另加每个 ✕（层级 2） |
+| `SignalPanel` | 表头 / 筛选框 / 列表 / 样式区（1）＋ 滚动条、样式行、**当前可见**的列表行（2） |
+| `PlotView` | 每个 `LaneVisual::rect`（1）；**不**上报曲线/胶囊/提示这类随数据变化的瞬态几何 |
+| 宿主 | 客户区外框、分隔条、打开的菜单 / 拾色器（层级 0） |
+
+`UiWidget::PaintDebugBounds(g, scale, depth)` 递归整棵控件树 —— 凡已上树的控件**零成本**获得边界。
+
+### 2.4 视觉与实现约束
+
+* **只描边、不填充**（与 Android 一致）：填充会在几十个嵌套矩形上层层叠加把内容糊住。
+* 层级配色：0 青蓝 `#29B6F6`（2px）/ 1 品红 `#E040FB` / 2 琥珀 `#FFB300` / ≥3 绿 `#66BB6A`（1px）。
+* 线宽按**设备像素**固定（不乘 `scale`），并临时 `PixelOffsetModeNone` + 关抗锯齿 + 矩形对齐整像素，
+  保证 1px 就是 1px。
+* 绘制位置：`Render` 的**最后一步**（加载遮罩之后）。⚠️ **绝不进入任何位图缓存**
+  （`PlotView` 4 层缓存、`SignalPanel` 行位图缓存）—— 否则关掉开关后线条会残留。
+* `fullFrame` 追加 `m_showLayoutBounds`：开启时必须整帧回送，否则"只回送绘图区"的快路径会让
+  装饰区的边界停在旧帧上。
+
+## 3. 验证
+
+| 项 | 结果 |
+| --- | --- |
+| `make release` / `make debug` | 零 error / 零 warning |
+| **新增离屏探针 `.preflight/lbcheck`** | **21 / 21 PASS** |
+| `Tools/rendercheck` 8 场景**工具栏以下区域**哈希 | 与改造前**逐一相同**（改动只落在工具栏带内） |
+| `Tools/rendercheck` 7 条功能断言 | 7 / 7 PASS |
+| `Tools/uicheck` | 69 / 69 |
+| `TargetCheck.exe` | 897 024 B（< 900 KB） |
+
+新增断言覆盖：齿轮存在 / 在「导入文件」左侧 / 同高 / 更窄；开机后无调试色；
+开启后青蓝 24 930 px、品红 19 734 px；**关闭后逐像素回到开启前**；菜单 scope、锚定贴合按钮、
+宽度未被撑大、条目初始未勾选、点击翻转开关、菜单保持打开。
+
+## 4. 后续可改进（用户："先落地实现然后再进一步改进"）
+
+1. 边界左上角标短 tag（`row#12` / `lane3`）—— 需要处理 GDI 文本不受 GDI+ 裁剪约束的问题。
+2. `PlotView` 的浮动面板（`EdgePanelLayout` 里的 `panel/title/close/…`）目前未上报；
+   它们已经是集中结构，插入一个循环即可。
+3. `SignalPanel` 的复选框 / 徽标 / ✕ 等行内子块（现在只到"行"这一层）。
+4. 开关状态目前**不持久化**（重启恢复为关闭）；若要持久化需要引入配置存储。
+5. 菜单只有一项；后续设置项按 `HEADER` 分组追加即可。
@@ -342,3 +342,62 @@ rendercheck:  A 2166933039626F66  B C444ECFEB18FD73D  C 7984446D8E7A4418  D BF85
 uicheck:      69 passed, 0 failed
 体积:         Build/Release/TargetCheck.exe = 891,392 B (< 900 KB)
 ```
+
+---
+
+## 第八轮（2026-10-28）：显示布局边界 + 三处可见收益优化
+
+### 进度总览
+
+| # | 任务 | 状态 | 验证 |
+| --- | --- | --- | --- |
+| 1 | `Toolbar` 控件树按需重建（`m_treeDirty`） | ✅ | 8 场景区域哈希不变 |
+| 2 | `Toolbar::SetActionLabel` 单一真值来源 | ✅ | 光标按钮文本仍随模式变化 |
+| 3 | `UiWidget::DispatchRedraw` 收敛重复判断 | ✅ | `uicheck` 69/69 |
+| 4 | `UiButtonWidget` 支持矢量图标（GEAR） | ✅ | 放大 4 倍核对形状 |
+| 5 | `ToolbarAction::SETTINGS` + 左侧固定簇布局 | ✅ | 4 条几何断言 |
+| 6 | `MenuScope::APP_SETTINGS` + 设置菜单 | ✅ | 5 条菜单断言 |
+| 7 | `UiComponent::PaintDebugBounds` 协议 + 四组件上报 | ✅ | 无开关时零像素影响 |
+| 8 | `UiWidget::PaintDebugBounds` 递归控件树 | ✅ | 品红描边 19 734 px |
+| 9 | `Application::PaintLayoutBounds` + 整帧回送 | ✅ | 关闭后逐像素还原 |
+| 10 | 文档更新 | ✅ | — |
+
+### 关键文件
+
+**新增**
+* `Components/Shared/Inc/UiDebugBounds.hpp` / `Src/UiDebugBounds.cpp` —— 调试边界描边原语
+  （层级配色、只描边不填充、整像素锐利对齐）。
+* `Components/Shared/Src/UiComponent.cpp` —— `PaintDebugBounds` 默认实现（只画 `Area()`）。
+
+**修改**
+* `Shared/Inc/UiComponent.hpp`、`Shared/Inc|Src/UiWidget.hpp/.cpp`、`Shared/Inc|Src/UiButtonWidget.hpp/.cpp`
+* `Toolbar/Inc|Src/*`、`TabBar/Inc|Src/*`、`SignalPanel/Inc/SignalPanel.hpp` + `Src/SignalPanel.cpp`
+* `PlotView/Inc/PlotView.hpp` + `Src/PlotViewPaint.cpp`
+* `Shared/Inc/PopupMenu.hpp`（`MenuScope::APP_SETTINGS`、`Rect()`）、`Shared/Inc/ColorPickerPopup.hpp`（`Rect()`）
+* `Application/Inc/Application.hpp`、`Inc/ApplicationInternal.hpp`、
+  `Src/Application.cpp`（Render 末尾叠加 + `fullFrame`）、`Src/ApplicationCommands.cpp`（菜单/派发/边界绘制）
+
+### 验证数据
+
+```
+make release (TargetCheck) -> 零 error / 零 warning, 897,024 B
+.preflight/lbcheck        -> 21 passed, 0 failed
+INFO area-pixels=24930 node-pixels=19734
+INFO gear=(15.0,55.0 50.0x37.5) menu=(15.0,97.0 185.0x73.8)
+rendercheck 工具栏以下区域哈希（改造前 == 改造后）：
+  AB AABF558F499583EA   BB 1B8B2D389D41B988   CB CAC17AA78C515079   DB 154617738CD9C422
+  EB DA484B02EEEC778A   FB B3CE740F60CF3688   GB 4DD14C0C2EC4CE91   HB D84400B723089F43
+rendercheck FUNC  7/7 PASS
+uicheck           69 passed, 0 failed
+```
+
+> 说明：整帧哈希 A–H 因为工具栏左侧多了一个齿轮按钮而整体变化（预期），
+> 因此给探针加了「工具栏带以下」的区域哈希用于**证明改动范围被完全限制在工具栏内**。
+
+### 验证坑（本轮新增）
+
+* PS 5.1 读中文 `.ps1` 会乱码 ⇒ 探针/脚本里只写 ASCII，中文注释另存 UTF-8 无 BOM 数据文件。
+* 想拿"改造前"的区域基线必须 `git stash push -u`（**含未跟踪文件**），否则新增的
+  `UiDebugBounds.cpp` / `UiComponent.cpp` 仍会被 Makefile 的 `Src/*.cpp` 通配扫到而编译失败。
+* 「工具栏带以下」的起点必须用**运行时** `m_toolbarRect.Y + Height`；写死 70 会切进工具栏，
+  齿轮正好落在被统计的区间里，导致本应相同的哈希全都不同。
@@ -280,3 +280,73 @@ UiComponent（纯接口，无状态）           UiWidget（有状态的树节
   若以后浮层数量增加，可给它们一个"浮层表"，但两个成员值不值得抽象——存疑。
 3. `Tools/` 已剥离；若将来要把它作为**对外可复现的验证资产**，建议单独开一个
   `qa/` 目录并显式加入版本控制（同时更新 `.gitignore` 的例外规则）。
+
+---
+
+# 第六阶段报告：让"布局边界"变成可以随时打开的一面镜子
+
+## 1. 这一阶段解决了什么问题
+
+前几阶段把代码结构理顺了，但**没有工具**去验证"我算出来的矩形到底是不是我画的那个矩形"。
+本项目主体仍是手算几何（全仓约 700 处 `gd::RectF`），一旦命中与绘制不同源，症状是
+"点不到 / 点错位置 / 悬停高亮漏一格"这类只能靠肉眼猜的问题。
+「显示布局边界」把这些不可见的矩形变成可见的一层叠图。
+
+## 2. 设计取舍：基类给协议，组件自己上报
+
+上一轮的结论是"只在共同基类里实现只能覆盖 4 个顶层区域"。本轮把它落实为分层协议：
+
+```
+UiComponent::PaintDebugBounds()      默认只画 Area()        ← 宿主遍历一次覆盖 4 大区
+  └─ Toolbar/TabBar   覆盖：跳过根控件，遍历控件树子节点    ← 已上树的部分零成本
+  └─ SignalPanel      覆盖：表头/筛选框/列表/样式区 + 可见行
+  └─ PlotView         覆盖：每个网格区域
+UiWidget::PaintDebugBounds(depth)    递归整棵控件树          ← 将来上树的控件自动获得
+```
+
+**为什么不放在 `UiWidget` 一处就够**：`PlotView` / `SignalPanel` 的主体几何还没上树，
+把边界做成"只有树节点才有"就等于只覆盖了 20% 的矩形。
+
+## 3. 三个必须守住的工程约束
+
+1. **不进缓存**。`PlotView` 有 4 层位图缓存、`SignalPanel` 有 192 槽行位图缓存。
+   调试层只画在 `Render` 的最后一步；探针用"关掉后逐像素回到开启前"这条断言把它钉住。
+2. **整帧回送**。`Render` 有"只回送绘图区"的快路径，而边界跨越所有装饰区 ⇒
+   `fullFrame` 必须并入 `m_showLayoutBounds`，否则看起来像"没生效"。
+3. **锐利**。1px 线若被抗锯齿摊成 2px 灰边，就无法判断真实边界；
+   因此临时 `PixelOffsetModeNone` + 关抗锯齿 + 矩形对齐整像素，线宽按设备像素固定。
+
+## 4. 顺带做掉的可见收益优化
+
+`Toolbar` 原先每次 `Layout` 都重建整棵控件树（拖动面板分隔条时每帧一次）。
+改为 `m_treeDirty` 按需重建后，`SetActionLabel` 也不再"双写覆盖表与控件"——
+**文本的唯一权威来源只剩覆盖表**，重建时统一生效。
+
+另外把 `Toolbar` / `TabBar` 里重复的 `Dispatch(); return UiRectHasArea(TakeDirty());`
+收敛成 `UiWidget::DispatchRedraw()`。`TakeDirty()` 会清零，漏掉一次就把下一次真实变化
+误判成"无变化"——这类"静默不重绘"的坑在项目历史上出现过多次。
+
+## 5. 验证策略的变化
+
+过去每轮都用"8 个场景的**整帧**哈希"证明零差异。本轮**整帧哈希必然变化**（多了一个按钮），
+于是给探针加了「工具栏带以下的区域哈希」：8 个场景的区域哈希与改造前**逐一相同**，
+从而证明改动的像素范围被完全限制在工具栏内。
+
+另外新增了一个独立的离屏探针 `.preflight/lbcheck`（21 条断言），
+专门验证"开关打开后确实出现调试色 / 关闭后逐像素还原 / 菜单锚定与勾选翻转"。
+
+## 6. 数据
+
+```
+make release: 零 error 零 warning；TargetCheck.exe 897,024 B（< 900 KB）
+lbcheck 21/21 · rendercheck FUNC 7/7 · 区域哈希 8/8 相同 · uicheck 69/69
+```
+
+## 7. 遗留与后续
+
+1. 边界没有文字标签（哪个框是 `row#12` 还是 `lane3` 需要靠层级配色猜）。
+   加标签要解决"GDI 文本不受 GDI+ 裁剪约束"，建议直接用 `UiTextClipped`。
+2. `PlotView` 的 5 类浮动面板内部矩形、`SignalPanel` 的行内子块（复选框/徽标/✕）尚未上报。
+   两者的几何都已经集中，属于"再插一个循环"的量级。
+3. 开关状态不持久化 —— 重启回到关闭。
+4. 设置菜单目前只有一项，但分组结构（`HEADER`）已经就位，后续按组追加即可。
@@ -3025,9 +3025,10 @@ else if (panelOnly) { /* 只回送“本帧重绘过的区域并集” */ }

 | 2026-10-28 | DeepSeek-V4.1-Flash（**UI_Refactor 分支**） | **UI 重构第一阶段（P0/P1/P2，全部只提交到本地 `UI_Refactor` 分支，不影响 `main`）**：① 新增 `Components/Shared/{Inc,Src}/UiLayout.*`（矩形原语 / 对齐 / 设备像素内侧对齐 / Stack / Flow / 布局缓存）与 `UiWidget.*`（控件树基类：两段式布局、脏区下探绘制、只沿命中链派发、capture/modal/hover/focus 仲裁、光标认领链、统一动画 tick、内容指纹入口）。② 新增入库离屏回归网 `Tools/uicheck`（62 项断言，链接 `Build/<Config>/*.o` 排除 `Main.o`）。③ `PlotView` 实现按关注点重分为七个分片：`PlotViewPaint.cpp` 9 080 → **4 913** 行（−46%），新增 `PlotViewRaster.cpp`(1 876)、`PlotViewCacheKey.cpp`(474)、`PlotViewPanels.cpp`(1 359)；搬移**逐像素 0 差异**（三场景渲染哈希 `A 2166933039626F66 / B C444ECFEB18FD73D / C 7984446D8E7A4418` 迁移前后完全一致）。详见 §11.2 第 235–240 条与 `Documents/UI_Refactor_Plan.md` / `UI_Refactor_Progress.md` / `UI_Refactor_Report.md`。 |

-
 | 2026-10-28 | DeepSeek-V4.1-Flash（**UI_Refactor 分支**） | **UI 重构第五阶段：统一组件协议 + 去手写链路 + 大文件按职责拆分 + 代码审查 + `Tools/` 剥离（详见 §12 末尾「2026-10-28 第七轮」）**。① 新增 `Components/Shared/Inc/UiComponent.hpp`（纯接口、无状态）：`SetScale / Layout / Area / Paint / HitTest / OnMouseLeave / IsEditing / QueryCursor`；`Toolbar` / `TabBar` / `SignalPanel` / `PlotView` 各自 `: public UiComponent`，**只加 `override` + 补 `Area()`，实现零改动**。② `Application` 新增 `ComponentEntry { UiComponent*; Target; bool chrome; }` 表 + `BuildComponentTable()`，把 `ApplyDpi` / `Relayout` / `WM_MOUSELEAVE` / `WM_SETCURSOR` 四条手写链改成循环；按下/松开/移动三条链**有意保留显式分支**（带组件专属后置动作）。③ `UiLayout::UiStackRects` 首次用于生产代码（内容区三列切分）。④ `SignalPanelInteraction.cpp` 2 329 → **831** 行（拆出 `SignalPanelEdit/Scroll/Menu.cpp`），`Shared/PopupMenu.cpp` 1 901 → **706** 行（拆出 `PopupMenuLayout.cpp` / `PopupMenuPaint.cpp` + 新增 `Inc/PopupMenuInternal.hpp`）。⑤ 代码审查修 5 处（过期头注释、重复构造函数、include 落进 namespace、缺 include、残留符号全仓零命中）。⑥ `Tools/` 从提交树剥离 + `.gitignore`，并对 `UI_Refactor` 做 `filter-branch` 清除历史。验证：`make release` 零错误零警告；`rendercheck` **8 场景哈希与基线逐一相同**、7 条 FUNC 全 PASS；`uicheck` **69 passed / 0 failed**；`TargetCheck.exe` **891,392 字节**。 |

+| 2026-10-28 | DeepSeek-V4.1-Flash（**UI_Refactor 分支**） | **「显示布局边界」调试开关（Android 风格）+ 工具栏设置菜单（齿轮）+ 三处可见收益优化（详见 §12 末尾「2026-10-28 第八轮」）**。① **齿轮按钮**：`ToolbarAction::SETTINGS` 位于「导入文件」左侧（工具栏布局改为「左侧固定簇 `kLeftClusterCount=2` + 右侧组」），矢量化绘制（8 齿 + 外环 + 轴孔，按 `half` 比例推导；不用字体字符 `⚙`，因为不同回退字体大小/基线不一致）。② **设置菜单**：`MenuScope::APP_SETTINGS` + `HEADER "调试"` + 勾选切换项「显示布局边界」（`keepOpen`，点击后菜单保持打开、勾选态回写）；锚点取 `Toolbar::ButtonRect(SETTINGS)` 的**控件实测矩形**。③ **布局边界**：`UiComponent::PaintDebugBounds(g,scale)` 虚函数（默认只画 `Area()`），`Toolbar`/`TabBar` 跳过根控件上报控件树子节点、`SignalPanel` 上报表头/筛选框/列表/样式区 + 可见行、`PlotView` 上报每个网格区域，宿主补客户区外框/分隔条/浮层；`UiWidget::PaintDebugBounds(g,scale,depth)` 递归整棵树。**只描边不填充**、线宽按设备像素固定、临时 `PixelOffsetModeNone` + 关抗锯齿 + 整像素对齐；层级配色 青蓝/品红/琥珀/绿。⚠️ 调试层**绝不进任何位图缓存**（只在 `Render` 最后一步叠加），且开启时 `fullFrame` 必须并入开关（否则只回送绘图区会让装饰区边界留在旧帧）。④ **可见收益优化**：`Toolbar::Layout` 控件树改按需重建（`m_treeDirty`，拖分隔条每帧不再重建）；`SetActionLabel` 只写覆盖表（消除双写不同步）；新增 `UiWidget::DispatchRedraw` 收敛 `Dispatch()+TakeDirty()` 重复写法。验证：新增离屏探针 `.preflight/lbcheck` **21/21**（含"关闭后逐像素还原""菜单锚定/勾选翻转"）；`rendercheck` **工具栏带以下区域哈希 8/8 与改造前逐一相同**（整帧哈希因新增按钮整体变化，属预期）+ FUNC 7/7；`uicheck` 69/69；`make release/debug` 零警告；`TargetCheck.exe` **897,024 字节（< 900KB）**。 |
+
 ## 11. 跨设备协作须知（起源设备视角）

 > **本文件是唯一权威记忆**。所有设备 / Agent 共用它，**不要再新建 `agent_mem_origin.md` 等旁支记忆文件**。
@@ -7998,3 +7999,60 @@ DG3  data=0       cycle=0     （空组，一个字符串通道）

 `Tools/`（`uicheck` / `rendercheck`）已从**提交树**剥离并写入 `.gitignore`
 （历史提交里也不含它 —— 见台账的「分支操作取证」）。本地文件保留，仍可随时复跑。
+
+---
+
+## 本轮（2026-10-28 第八轮，本机）：显示布局边界（Android 风格）+ 工具栏设置菜单（齿轮）+ 三处可见收益优化
+
+### 1. 交付的功能
+
+* **齿轮按钮**（`ToolbarAction::SETTINGS`，位于「导入文件」**左侧**）→ 展开应用设置菜单。
+  工具栏布局改为「左侧固定簇（`kLeftClusterCount = 2`：齿轮 + 导入文件）+ 右侧按钮组」。
+* **设置菜单**：`MenuScope::APP_SETTINGS`（新增枚举值，宿主自己处理、不下发组件）；
+  条目 = `HEADER "调试"` + `NORMAL "显示布局边界"`（`keepOpen = true`，点击保持菜单打开）。
+* **显示布局边界**：`UiComponent::PaintDebugBounds(g, scale)` 新增虚函数（默认只画 `Area()`），
+  四组件覆盖上报内部结构；`UiWidget::PaintDebugBounds(g, scale, depth)` 递归整棵控件树。
+
+### 2. 硬约束（再改时必须守住）
+
+1. **调试层绝不进任何位图缓存**（`PlotView` 4 层缓存 / `SignalPanel` 行位图缓存）。
+   只在 `Render` 最后一步叠加 ⇒ 关掉开关后逐像素还原（探针 `bounds-off-restores-pixels` 钉住）。
+2. **开启时必须整帧回送**：`fullFrame` 已并入 `m_showLayoutBounds`。
+   否则"只回送绘图区"的快路径会让装饰区边界停在旧帧上，看起来像没生效。
+3. **只描边、不填充**（Android 一致）：几十个嵌套矩形叠加填充会把内容糊住。
+4. **线宽按设备像素固定**（不乘 `scale`）+ 临时 `PixelOffsetModeNone` + 关抗锯齿 + 整像素对齐，
+   否则 1px 线会被摊成 2px 灰边，无法判断真实边界。
+5. 层级配色：`0` 青蓝 `#29B6F6`(2px) / `1` 品红 `#E040FB` / `2` 琥珀 `#FFB300` / `≥3` 绿 `#66BB6A`(1px)。
+6. `Toolbar`/`TabBar` 上报时**跳过根控件**（它与组件区域完全重合，重复画会压住自己的按钮）。
+
+### 3. 可见收益优化
+
+| 位置 | 内容 |
+| --- | --- |
+| `Toolbar::Layout` | 控件树改为**按需重建**（`m_treeDirty`）：只在规格/字体/主题/缩放/动态文本变化时重建。拖动分隔条每帧 `Relayout` 不再重建。 |
+| `Toolbar::SetActionLabel` | 只写 `m_labelOverrides`（唯一权威）+ 置树脏，不再双写控件文本。 |
+| `UiWidget::DispatchRedraw` | 新增；`Toolbar`/`TabBar::OnMouseMove` 的 `Dispatch(); return UiRectHasArea(TakeDirty());` 收敛到这里（`TakeDirty()` 会清零，漏一次就误判"无变化"）。 |
+
+### 4. 验证
+
+```
+make release -> 零 error 零 warning；TargetCheck.exe 897,024 B (< 900KB)
+.preflight/lbcheck (新增离屏探针)  -> 21 passed, 0 failed
+   INFO area-pixels=24930 node-pixels=19734
+   INFO gear=(15,55 50x37.5) menu=(15,97 185x73.8)
+rendercheck 工具栏带以下区域哈希（改前 == 改后，8/8 相同）
+   AB AABF558F499583EA  BB 1B8B2D389D41B988  CB CAC17AA78C515079  DB 154617738CD9C422
+   EB DA484B02EEEC778A  FB B3CE740F60CF3688  GB 4DD14C0C2EC4CE91  HB D84400B723089F43
+rendercheck FUNC 7/7 PASS; uicheck 69 passed
+```
+
+> 整帧哈希 A–H 因为多了齿轮按钮而整体变化（预期）。要证明"改动只落在工具栏内"，
+> 必须用**工具栏带以下的区域哈希**。
+
+### 5. 验证坑（踩过的）
+
+* 取"改造前"基线要 `git stash push -u`（**含未跟踪文件**）；否则新增的 `UiDebugBounds.cpp` /
+  `UiComponent.cpp` 仍被 Makefile 的 `Src/*.cpp` 通配扫到 → 引用不存在的成员而编译失败。
+* 区域哈希起点必须用**运行时** `m_toolbarRect.Y + Height`；写死 `70` 会切进工具栏，
+  齿轮正好落在统计区间内，导致本应相同的哈希全都不同。
+* 图标不要用字体字符 `⚙`（不同回退字体大小/基线不一致）；用 GDI+ 矢量按 `half` 比例画。