产品需求与范围
1. 背景
开发者在 GitLab Merge Request 中评审代码时，经常需要离开页面去询问模型，再手工把结论复制回来。现有 AI Review 工具多以 CLI、CI Bot 或 IDE 插件存在，缺少一个直接嵌入 GitLab 页面、既能划词提问又能发起 Review 的轻量入口。
本项目以油猴脚本作为前端载体，目标是在不接管 GitLab UI 的前提下增加一个 Review Agent 侧栏。
2. 目标用户
- 在 GitLab.com 或自部署 GitLab 上进行日常 MR 评审的开发者。
- 需要快速解释陌生代码、检查风险并生成评论草稿的 Reviewer。
- 希望模型访问本地仓库上下文，但不希望把 GitLab token 和源码交给第三方服务的技术团队。
- 需要按团队规则进行标准化 Review 的平台 / 工程效率团队。
3. 产品目标
G1. 在页面内完成“选中 -> 询问 / Review -> 复核 -> 评论”闭环
- 划词后显示紧凑悬浮操作栏。
- 问题和 Review 自动携带代码片段、文件、MR、Diff Ref 等上下文。
- 生成内容可定位回代码行，并转换为 GitLab 评论草稿。
G2. 同时支持浅层与深度 Review
- 浏览器模式覆盖当前页面可见上下文和 GitLab API 可获取的 MR 数据。
- Agent 工具循环可主动读取仓库文件、搜索代码、查看提交历史。
- UI 必须明确展示当前能力来源，不能假装拥有本地上下文。
G3. 可控、可解释、低噪声
- Finding 使用固定结构：位置、类别、严重度、证据、建议、置信度。
- 默认只展示可信度较高的问题，低置信结果折叠或汇总。
- 评论发布必须经用户确认，并支持逐条忽略、编辑、复制。
G4. 兼容 GitLab 与自部署站点
- 优先支持 GitLab CE / EE 常见版本。
- 对“GitLab 类”站点通过适配器和能力探测降级，不承诺所有派生产品完整兼容。
- 页面 DOM 变化不应导致核心数据链路完全失效，GitLab API 是首选事实来源。
4. 用户场景
US-1 划词解释
Reviewer 选中一段并发代码，点击“问一下”，询问潜在竞态。Chatbox 显示文件、行范围和 MR 背景，模型解释风险并给出验证建议。
US-2 划词 Review
Reviewer 选中一个输入处理函数，点击“Review 这段”。Agent 只针对该片段生成 0-N 条 Finding，并给出可编辑评论草稿。
US-3 整个 MR Review
Reviewer 在 MR 页面点击“开始 Review”。系统读取 Diff、变更文件和 MR 描述，按文件组分析，最终输出按严重度排序的问题列表。
US-4 评论发布
Reviewer 展开一条 Finding，核对证据与建议，点击“发布到 GitLab”。系统弹出目标行与评论预览，确认后创建 MR Discussion。
US-5 深度上下文
Agent 发现问题涉及其他文件，调用 file_read / search_code 工具获取上下文。工具轨迹在 UI 中可见，最终 Finding 引用实际证据。
5. 功能范围
P0（首个可用版本）
- GitLab MR URL / 项目 / MR IID 解析。
- MR 描述、Diff、Diff Refs、变更文件读取。
- 划词悬浮工具栏、Chatbox、局部 Review。
- 单一 OpenAI-compatible 流式模型连接。
- Finding 结构、评论草稿、复制与手工发布。
- 设置、连接诊断、数据发送预览。
P1（GitLab 完整体验）
- 精确行 Discussion 创建和错误回退。
- 全 MR Review、文件组、预算、取消与重试。
- 自部署站点适配器、能力探测、版本差异处理。
- 历史会话、Finding 状态、幂等指纹。
P2（Agent 能力）
- Agent 工具循环、MCP 扩展工具、多 Provider 适配。
- 仓库镜像 / checkout、文件读取、搜索、规则包。
- 工具调用轨迹、上下文预算、并发与缓存。
- 可选受限命令执行，默认关闭。
P3（团队化）
- 团队规则、模板、策略路由。
- CI Bot、审计日志、SaaS / 私有化部署选项。
- MCP 工具接入和多 Agent 委托。
6. 非目标
- 不在浏览器中执行任意本地代码。
- 不自动合并、自动修复或绕过人工确认直接写 MR。
- 不保证对所有 GitLab fork / Gitea / Gogs / Codeup 等平台开箱即用。
- 不把完整 Git 仓库、构建系统或测试运行时塞进油猴脚本。
- 不默认上传源码、密钥或完整仓库到第三方模型。
7. 成功指标
| 指标 | 目标 | 说明 |
|---|---|---|
| 划词到首个回答时间 | P50 < 3 秒 | 不含模型首 token 网络抖动 |
| MR 页面注入稳定性 | > 99% 页面加载 | URL / DOM 变化有降级入口 |
| Finding 可定位率 | > 95% | 能映射到有效 Diff 行或明确标记不可定位 |
| 评论发布成功率 | > 99% | 不含权限不足、Diff 版本过期等可解释错误 |
| 无效 / 重复评论率 | < 10% | 结合人工确认前数据统计 |
| 浏览器主线程阻塞 | 无 > 100ms 长任务 | 大 Diff 解析放 Web Worker 或分片 |
8. 产品原则
- 用户在环：写操作默认可预览、可撤销、需确认。
- 能力诚实：清楚展示数据来源、工具是否可用、结果为什么降级。
- 确定性优先：定位、过滤、预算、去重由代码完成，模型只做判断。
- 最小上下文：先发 Diff 和必要上下文，工具按需扩展。
- 站点适配隔离：页面解析、API 访问、渲染互不耦合。
9. 待确认问题
首要模型接入方式是本地 Gateway，还是浏览器直连 OpenAI-compatible API？已确定：浏览器直连。- 是否要求支持只能通过网页会话认证、禁止 PAT 的自部署 GitLab？
- 第一阶段是否需要发布 GitLab Discussion，还是只需要复制评论草稿？
- 团队是否有统一 Review 规则、严重度定义和禁用检查项？
- 目标浏览器与 Tampermonkey / Violentmonkey 的最低版本是什么？