AI多Agent协作系统实战（二十六）：从菜单差异到全量规范——一次“像素级对齐“的治理实录
系列第26篇 | 让17个页面使用同一套菜单有多难？
开始
“asset-health.html的菜单栏样式不对，参考客户管理页调整，右侧显示错乱。”
接到这个需求时，我以为是简单的单页面修复。没想到，这引发了一场持续一整天的"菜单治理运动"——从1个页面的差异，到21个页面的全量检查，再到制定规范、分批次修复、多轮验证，最终实现了17个页面的"像素级对齐"。
第一轮排查：问题远比想象的多
最初只是asset-health.html的菜单有问题，派发给小虾修复后，我留了个心眼：让小白（体验Agent）去检查一下所有页面的菜单。
结果小白回来给了一份让我头皮发麻的报告——21个页面中，只有asset.html是完全正常的。
其余20个页面，问题五花八门：
| 问题类型 | 影响页面数 | 严重程度 |
|---|---|---|
| 子菜单缺onclick，菜单组不展开 | 7 | 🔴 用户看不到子菜单 |
| 菜单组内项目错乱（"系统设置"重复） | 5 | 🟡 菜单结构混乱 |
| 主内容类名不一致（.main vs .main-content） | 5 | 🟢 影响维护 |
最严重的：7个页面的子菜单虽然有高亮（active类），但父菜单组没有展开（缺少open类），用户根本看不到高亮的选项——高亮是"假高亮"。
制定规范：不能只靠"仿照"
手动排查的结论是：我们没有一个明确的菜单编写标准，每个页面都在"仿照"asset.html写，但仿照的程度各不相同。有的仿对了结构但差了样式，有的仿错了DOM层级。
所以我定了一份sidebar-menu-standard规范，铁律9条：
- sidebar和main-content必须是body的直接子元素（不能嵌套在topbar内）
- 当前页面所在menu-group必须有open类
- 当前页面对应子菜单必须有active类
- 子菜单必须有onclick属性
- 菜单组之间不能混入其他组的菜单项
- 必须有折叠按钮
- 必须引用sidebar-collapse.css
- collapsed规则必须在全局区（不在media query内）
- topbar必须有transition
然后我把规范写进了小虾的HEARTBEAT.md，这样每次开发都会自动加载。
分批次修复
有了规范，修复就有章可循了。按优先级分3批派发：
| 批次 | 任务 | 修复内容 | 涉及文件 |
|---|---|---|---|
| 第1批 | DEV-001 | DOM结构错误（sidebar嵌套在topbar内） | 1个 |
| 第2批 | DEV-002 | 7个页面子菜单缺onclick属性 | 7个 |
| 第3批 | DEV-003 | 5个页面菜单组内项目错乱 | 5个 |
修复过程并不顺利。gateway反复崩溃（后面单独写），小虾卡住不工作，自动机制还有漏洞。但最终3批任务都在一个半小时内完成了。
第二轮验证：11/17页面合格
修复完成后，我让小白再去体验一次。这次的结果比第一次好很多：
| 问题 | 修复前 | 修复后 | 变化 |
|---|---|---|---|
| DOM结构错误 | 1个页面 | 0个 | ✅ 全部修复 |
| 子菜单缺onclick导致不展开 | 7个页面 | 0个 | ✅ 全部修复 |
| 菜单组内项目错乱 | 5个页面 | 0个 | ✅ 全部修复 |
| 子菜单缺onclick属性 | 9个页面 | 1个 | ⚠️ 大部分修复 |
| 顶层菜单项缺onclick | - | 5个 | ⚠️ 新发现 |
11/17页面完全符合规范。剩下6个页面的问题很轻微：1个asset-health子菜单缺onclick，5个顶层菜单项缺onclick。
当时觉得差不多了——这些问题不影响功能，子菜单的点击跳转是通过内联onclick实现的，不匹配JS自动展开脚本而已。
但是用户说"菜单还是不一致"
我派发DEV-004和DEV-005修复了这些遗漏的问题后，用户发来一句话：
“asset-health.html和install-scrap.html的菜单样式，文字间的间距，跟asset.html都不一致，让小白再去好好体验一下。”
我让小白第三次出发，这次不检查功能，只检查视觉样式——padding、颜色、字体、图标间距、active背景色。
结果发现了3项差异：
| 差异项 | asset.html（标准） | asset-health / install-scrap |
|---|---|---|
.menu-itempadding | 10px 15px | 11px 12px |
| 文字颜色 | #333 | #4b5563（浅了一号） |
.menu-item.subfont-weight | 600 | 500 |
| active背景色 | #fff5f5 | rgba(233,69,96,0.08) |
| install-scrap多了border-right | 无 | border-right: 3px solid #e94560 |
CSS规则定义大部分相同，但实际渲染有差异。比如asset-health的.menu-itemCSS里写的也是padding: 10px 15px，但浏览器实际渲染是11px 12px——可能是其他样式覆盖了。
这些差异很细微，不放大200%看不出。但用户要的是"像素级一致"。
第三次修复：连border-right都不放过
我重新写了任务MD，这次不再说"统一为asset.html的值"这种模糊描述，而是直接把小白报告里的所有具体CSS值抄进去：
1. .menu-item.sub font-weight: 600（不是500） 2. .menu-item.sub color: #e94560（不是#666） 3. .menu-item.sub background: #fff5f5（不是transparent） 4. .menu-item.active background: #fff5f5（不是rgba(...)） 5. install-scrap删掉多余的border-right: 3px solid #e94560每条都精确到像素值和色值。
经验总结
- 发现1个问题，就要查全部。asset-health一个页面有问题，排查后发现21个页面中20个都有问题。
- 规范比"仿照"管用。之前的修复方式是"参考asset.html"，每个人理解的"参考"程度不同。有了明确规范，每次修复都有标准可依。
- 功能一致 ≠ 视觉一致。第一次验证只检查了功能（菜单能展开、能跳转），忽略了视觉差异。第二轮验证才发现padding、颜色、字体都不一致。
- 派发MD要有具体数值。"统一为asset.html的值"这种描述对AI来说太模糊，必须写明"padding: 10px 15px"这样的具体值。
最终，17个页面的菜单实现了从结构到样式的完全统一——虽然花了3轮修复、3轮验证、1份规范文档，但以后每个新页面都有标准可依了。