HomeResumePostsNotesLeetcodesAboutgithub

ai-ui-issue-pack：把 UI 问题「说给 AI 听」

04/20/2026

背景

AI coding 这两年最大的变化，不是“AI 会不会写代码”，而是“你能不能把问题描述清楚”。
尤其是前端 UI 问题：它发生在浏览器里，但要改的是代码仓库里的一坨组件/样式/状态/路由。

我们日常提 UI 问题，通常是这样：

  • 截图圈一下：这里不对
  • 说一句：在某某页面右上角
  • 再补一句：按钮样式怪怪的

然后就开始了经典流程：

  • AI/同事追问：哪个路由？哪个环境？哪个元素？有没有多个同名按钮？
  • 你补充 DOM、补充 className、补充样式、补充复现路径
  • 来回几轮之后，终于能开始改

说白了：痛点不在“怎么改”，而在“改哪儿”。

主要目标

既然人类描述 UI 位置这么痛苦，那就别描述了——直接引用它。

ai-ui-issue-pack 做的事情很简单：

  • 在浏览器里做一个插件（实现思路可以参考我之前的 frontend-e2e-test：同样是“在页面上交互 → 生成可消费的数据/脚本”）
  • 让用户在页面上选择某个/些 element，给它们加注释
  • 最后生成一个结构化的数据包，让 AI 可以直接定位并改代码

为什么要做（why）

AI 现在的能力其实够用了，缺的是“上下文输入的颗粒度”。

UI 问题如果只用自然语言描述，会天然丢失三类关键信息：

  • 位置上下文：到底是哪个页面、哪个路由、哪个模块、哪个状态下出现
  • 结构上下文：这个元素在 DOM tree 里是谁的孩子、附近有哪些兄弟节点、它的选择器是什么
  • 样式上下文（可选但很关键）：你看到的样式来自哪里（组件自身、CSS Module、全局样式、主题变量、覆盖顺序）

而这三类信息，如果靠人手工写出来……那不就是在写一个半吊子的测试用例/调试日志吗？

所以我干脆让插件帮我把这些信息采出来。

工作流

1）选择元素

进入页面后，打开插件，进入“选择模式”。

  • hover 高亮当前元素
  • 点击选中元素（支持多选）
  • 支持一些快捷操作（比如切到父节点）来避免选到 icon/text 这种不稳定目标

2）添加注释

对每个选中的元素写注释。

注释建议写三件事就够了：

  • 现状是什么（现在看起来怎样）
  • 期望是什么（改成怎样）
  • 约束是什么（不能影响哪些地方/哪些状态）

3）生成 issue pack

插件会打包出一份结构化数据，大致包含：

  • 页面路由（route / url）
  • 完整的 document tree（用于还原上下文与定位）
  • 选中的 element 列表（定位信息 + 注释）
  • element 的样式信息（可选，按需采集）

示意结构如下（仅示意，字段可按你们项目实际调整）：

{
  "route": "/settings/profile",
  "url": "https://example.com/settings/profile",
  "documentTree": { "type": "document", "children": [] },
  "elements": [
    {
      "locator": {
        "testid": "profile-page--save-btn",
        "cssPath": "div.xxx > button.yyy",
        "text": "保存"
      },
      "annotation": "按钮在禁用态仍然是主色，期望禁用态变浅灰，并且 hover 不要变色。",
      "styles": {
        "computed": { "color": "rgb(255, 255, 255)", "backgroundColor": "rgb(22, 119, 255)" }
      }
    }
  ]
}

两种使用方式：本地开发 / 线上测试

本地开发

本地开发最爽的点是：这份数据可以直接作为 AI 的输入。

你不用再去手工解释：

  • 在哪个页面
  • 点哪个按钮
  • DOM 在哪里
  • 样式为什么长这样

AI 拿到 pack 以后，基本就可以直接进入“修改代码”阶段。

线上测试

线上测试的典型场景是：发现问题的人不是修问题的人。

所以插件支持“提交”：

  • 通知到前端群里（第一时间让相关人看到）
  • 生成飞书任务（多维表格 item）（把问题任务化、可追踪）

这一步的关键不是“又多了个提 bug 的入口”，而是：

提交的不再是“模糊描述 + 一张截图”，而是“可以被 AI/工程师复现与定位的结构化上下文”。

AI 为什么能因此直接改代码

如果只给 AI 一句“这里不对”，AI 就只能用问答把缺失的信息补齐。
而 issue pack 把关键上下文一次性给够之后，AI 的行为会明显变化：

  • 定位更快：通过 route + tree + locator，迅速缩小到具体组件/样式入口
  • 推理更稳：有 DOM 上下文，不容易改错“同名元素/相似按钮”
  • 样式修改更靠谱：有 computed style（可选），更容易判断覆盖来源与优先级

最终效果就是：从“来回描述定位”变成“直接进入修改”。

小结

ai-ui-issue-pack 本质上是在做一件事：把 UI 问题的沟通对象从“人类语言”切换成“机器可消费的数据”。

以前我们和 AI 的主要摩擦是：

  • 你：帮我改一下这个按钮
  • AI：哪个按钮？

现在是：

  • 你：给你这个 pack，里面已经包含 route、tree、element、（可选）样式和注释
  • AI：OK，我直接去改代码

这就是它解决的核心痛点：要去和 AI 描述“在哪个地方”的成本，几乎被降到了 0。