Review Agent for GitLab

简体中文

English

简体中文

English

Appearance

UX 流程与原型说明 ​

1. 原型目标 ​

当前原型用于确认交互、状态和信息架构，不连接真实 GitLab、不读取真实仓库、不调用模型。原型中的代码、Finding、工具轨迹和发布结果均为模拟数据。

原型覆盖四条关键流程：

  1. 划词提问。
  2. 划词 Review。
  3. 整个 MR Review。
  4. Finding 复核并确认发布。

2. 页面布局 ​

text
┌────────────────────────────────────────────────────────────────────┐
│ GitLab 顶部导航                                                     │
├──────────┬─────────────────────────────────────┬───────────────────┤
│ GitLab   │ MR 信息 / Diff                      │ Review Agent      │
│ 导航     │                                     │ 会话 / Review / 设置│
│          │  code rows                          │                   │
│          │  [划词悬浮工具栏]                    │  Chatbox          │
│          │                                     │  Findings         │
└──────────┴─────────────────────────────────────┴───────────────────┘
  • >= 1100px：Agent 侧栏常驻右侧，MR 内容保留主要阅读宽度。
  • 760-1099px：Agent 侧栏覆盖在 MR 上，可关闭。
  • < 760px：底部抽屉式 Agent，划词工具栏改为贴选区下方。

3. 划词提问流程 ​

触发 ​

用户在代码区选择 1-200 行文本，且选区不与 Review Agent UI 重叠。

行为 ​

  1. 显示悬浮工具栏：问一下、Review 这段、复制。
  2. 工具栏不超过选区宽度上方可用空间，必要时翻转到选区下方。
  3. 点击 问一下 打开 Chatbox，自动添加代码附件。
  4. Composer 显示当前上下文：文件、行范围、选中字符数。
  5. 发送后先显示用户消息，再显示流式回答。

异常状态 ​

  • 无法识别文件 / 行号：仍允许提问，附件标记为 页面选区。
  • 选区过长：提示裁剪到 200 行，允许用户选择前 200 行或取消。
  • 模型未配置：打开设置并保留待发送问题。

4. 划词 Review 流程 ​

触发 ​

点击悬浮工具栏 Review 这段，或侧栏 Review 页选择 仅选中代码。

状态 ​

text
准备上下文 → 分析选中代码 → 校验证据 → 定位评论 → 完成
  • 阶段进度是离散状态，不用无意义的无限动画。
  • 工具调用显示折叠摘要，例如 file_search · CheckoutService。
  • 无问题时显示 未发现高置信问题，不生成空评论。

5. MR Review 流程 ​

范围选择 ​

  • 全部变更：当前 MR 所有可分析文件。
  • 当前文件：只分析当前 Diff 文件。
  • 自定义文件：从变更文件列表勾选。

运行页 ​

显示：

  • 已处理文件 / 总文件。
  • 当前阶段和最近工具调用。
  • token / 时间预算（有 Gateway 时）。
  • 取消 按钮。

结果页 ​

  • 顶部只保留严重度计数和过滤器，不堆叠 KPI 卡片。
  • Finding 默认按 critical → high → medium → low 排序。
  • 低置信结果默认折叠，并显示原因。
  • 每条 Finding 显示：位置、类别、严重度、标题、证据、建议。

6. Finding 交互 ​

每条 Finding 的主操作：

  • 定位：滚动并高亮对应 Diff 行。
  • 编辑草稿：编辑发送到 GitLab 的 Markdown。
  • 复制：复制评论，不写 GitLab。
  • 发布到 GitLab：打开二次确认。
  • 忽略：记录状态，不删除原结果。

发布确认对话框 ​

必须展示：

  • 项目、MR IID。
  • 文件路径与目标行。
  • 完整评论 Markdown。
  • 当前 Diff SHA / version 摘要。
  • 确认发布 与 返回修改。

发布成功后更新为 已发布，允许点击 discussion 链接。失败时保留草稿和错误原因。

7. Chatbox 状态 ​

空状态 ​

显示 3 个基于当前上下文的建议，不展示营销内容。

有代码附件 ​

附件条显示：文件、行范围、selection / hunk / file 类型、移除按钮。

流式状态 ​

  • 回答区域保留稳定宽度，避免每 token 重排。
  • 工具调用在回答前显示可折叠轨迹。
  • 停止 可取消当前请求，已生成内容保留。

错误状态 ​

  • 模型未连接：主操作是打开设置。
  • 请求超时：允许重试，保留问题和附件。
  • 上下文超预算：允许移除附件或切到 Gateway。

8. 设置与诊断 ​

设置分为四组：

  1. 运行模式：浏览器直连 / 本地 Gateway。
  2. 模型连接：Base URL、模型、密钥、连接测试。
  3. GitLab：认证模式、站点白名单、发布确认策略。
  4. Review：严重度过滤、语言、规则、数据发送预览。

诊断页展示：

  • 当前站点适配级别：full / read-only / dom-only / unsupported。
  • GitLab API、模型、Gateway 连接状态。
  • 当前页面可提取的 PageContext。
  • 能力矩阵与降级原因。

9. 视觉规范 ​

  • 参考 GitLab 的浅色中性界面，Agent 侧栏用清晰的深色标题区做产品识别，不模仿 GitLab 品牌。
  • 颜色只用于状态：严重度、连接状态、Diff 增删、焦点。
  • 图标按钮必须有 aria-label 或 tooltip。
  • 禁止大面积渐变、装饰性圆球和无信息仪表盘。
  • 代码区使用等宽字体，Markdown 正文使用产品 UI 字体。

10. 可访问性 ​

  • 全部操作可用键盘完成；悬浮工具栏进入 role="toolbar"。
  • Esc 关闭工具栏 / 对话框，焦点返回触发按钮。
  • 严重度不只靠颜色，显示文字标签。
  • 流式回答使用 aria-live="polite"，错误使用 role="alert"。
  • 支持 prefers-reduced-motion。
  • 文本对比度满足 WCAG AA。

11. 原型交互路径 ​

路径 A：划词提问 ​

  1. 在模拟代码区拖动选择 checkoutInventory 调用附近代码。
  2. 点击浮动工具栏 问一下。
  3. 在右侧输入问题并发送。
  4. 查看模拟流式回答。

路径 B：Review 与发布 ​

  1. 点击右上角 开始 Review。
  2. 观察准备、分析、定位阶段。
  3. 展开一个高严重度 Finding。
  4. 点击 发布到 GitLab。
  5. 在确认框中查看目标行和评论。
  6. 确认后查看 已发布 状态。

路径 C：能力边界 ​

  1. 打开右侧 设置。
  2. 查看浏览器、GitLab API、Gateway 状态。
  3. 切换“浏览器直连 / 本地 Gateway”运行模式。
  4. 观察能力矩阵变化。

12. 原型与生产实现差异 ​

原型生产实现
固定模拟 GitLab 页面注入真实 GitLab Shadow DOM
点击后固定延时模拟阶段消费真实 AgentEvent 流
Finding 为固定样例Schema 校验 + 定位 + 反思生成
发布只更新本地状态调用 GitLab Discussions API
设置状态为演示值执行真实 probe / connectivity test
普通 React DOMShadow DOM + 用户脚本生命周期

13. 原型截图 ​

构建并运行 pnpm dev 后，应为以下状态保留截图并纳入 PR：

  • docs/assets/prototype-mr-overview.png
  • docs/assets/prototype-selection-toolbar.png
  • docs/assets/prototype-review-running.png
  • docs/assets/prototype-finding-publish.png
  • docs/assets/prototype-capability-settings.png

截图要求使用固定 1440x1000 视口，无开发工具和无关桌面内容。