AI多Agent协作系统实战（二十六）：从菜单差异到全量规范——一次“像素级对齐“的治理实录

2026/7/30 4:30:32

系列第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-item`padding	`10px 15px`	`11px 12px`
文字颜色	`#333`	`#4b5563`（浅了一号）
`.menu-item.sub`font-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

每条都精确到像素值和色值。