Skip to content

PR review 第一版:侧边栏的 PRs 标签页、PR 详情窗格和 diff #4

Closed
14 of 14 issues completed

Description

@lw396

Part of #1.

Problem Statement

用 Herdr 的开发者让 agent 写代码,agent 写完会开 PR。开发者必须亲自 review 这些 PR:看改了什么、在具体的行上提意见、决定通过还是要求修改、最后 merge。现在这些只能切到浏览器里的 GitHub 去做:离开了 Herdr,容易看错仓库(fork、多个 remote、远程机器上的文件夹),也看不出哪些 PR 对应自己本地的分支。GitHub mod 的侧边栏目前只有 Issues 标签页,没有任何 PR 功能。

开发者熟悉 VS Code 插件(GitHub Pull Requests 扩展)的 review 流程,希望在 Herdr 里用同样的方式 review,不必重新学。

Solution

在侧边栏加一个 PRs 标签页,按 VS Code 插件的分组列出当前仓库的 PR:本地拉取请求分支、正在等待我的审阅、由我创建、全部打开。PR 可以展开成改动文件的目录树。点 PR 在一个 Herdr 原生标签页(详情窗格)里打开它的描述页:标题和状态、右侧的 Reviewers / Assignees / Labels / Milestone / Projects、时间线、checks、merge 区域和评论框(Comment / Approve / Request Changes)。点文件在同一个标签页里显示该文件的单栏 diff,可以在某一行上 Add Comment 或 Start Review,回复和解决已有讨论,把文件标为已看过。最后在描述页提交 review、merge、删除远程分支。列表和详情窗格在看得见时用条件请求自动检测变化。

界面的布局、用词和交互照抄 VS Code 插件;功能范围由 ADR 决定(ADR 0007)。

User Stories

侧边栏的 PRs 标签页

  1. 作为开发者,我想在侧边栏切到 PRs 标签页,这样能在 Herdr 里看当前仓库的 PR。
  2. 作为开发者,我想 PR 按插件的分组排列,组名照插件的英文原文:Local Pull Request Branches(本地拉取请求分支)、Waiting For My Review、Created By Me、All Open,这样和我在 VS Code 里看到的一样。
  3. 作为开发者,我想"本地拉取请求分支"列出焦点文件夹里有对应 PR 的本地分支的 PR(不管 PR 是 open、closed 还是 merged),这样我知道本地哪些分支已经开了 PR。
  4. 作为在 fork 里工作的开发者,我想本地分支只和 head 在我这个仓库里的 PR 匹配,这样同名分支不会对错 PR。
  5. 作为开发者,我想"正在等待我的审阅"列出请求我 review 的 open PR,这样我知道该 review 什么。
  6. 作为开发者,我想"由我创建"列出我开的 open PR,这样我能看到 agent 用我的账号交来的活。
  7. 作为开发者,我想"全部打开"列出仓库所有 open 的 PR。
  8. 作为开发者,我想每组都按最近更新排序。
  9. 作为开发者,我想折叠和展开每一组,且折叠的组不发请求,这样不浪费额度。
  10. 作为开发者,我想每组先看到 30 条,并能"加载更多"。
  11. 作为开发者,我想空的分组照插件显示 "0 pull requests in this category"。
  12. 作为开发者,我想每行看到状态图标、#编号 标题 和 by @作者,这样不用点开就能认出来。
  13. 作为开发者,我想 draft PR 的标题显示为斜体,这样一眼看出它还没准备好。
  14. 作为开发者,我想悬停一行时点"复制编号"得到 #42,这样我能直接告诉 agent。
  15. 作为开发者,我想悬停一行时点"在浏览器中打开"。
  16. 作为开发者,我想点 ↻ 立即刷新列表。
  17. 作为开发者,我想像插件那样展开一个 PR,看到它改动的文件,这样不用打开就知道改了哪些地方。
  18. 作为开发者,我想改动文件默认按目录树排列,只有一个子项的文件夹合并显示,并能切换成平铺。
  19. 作为开发者,我想隐藏已看过的文件,这样大 PR 里只剩没看过的。
  20. 作为开发者,我想每个文件显示它的改动类型(新增、修改、删除、重命名)和是否已看过。
  21. 作为开发者,当仓库没有 GitHub remote、仓库不存在或我无权访问时,我想看到和 Issues 标签页一样的说明。

PR 详情窗格

  1. 作为开发者,我想点一个 PR 就在 Herdr 原生标签页里打开它的描述页,这样能在宽的地方阅读。
  2. 作为开发者,我想再点一个已经打开的 PR 时切回它的标签页,而不是再开一个。
  3. 作为开发者,我想在侧边栏点一个改动文件时,在这个 PR 的标签页里显示该文件的 diff,而不是每个文件开一个标签页,这样顶部不会被 diff 标签挤满、找不到 agent 的终端。
  4. 作为开发者,我想详情窗格只认它自己的 PR,焦点换到别的仓库时它不变;gh 在这个窗格所在 space 的机器上运行。
  5. 作为开发者,我想在描述页顶部看到标题、编号、状态(open / draft / merged / closed)和"作者 想把 X 合并到 Y"。
  6. 作为开发者,我想在描述页右侧看到 Reviewers(及其 review 状态)、Assignees、Labels、Milestone 和 Projects,只看不改。
  7. 作为开发者,我想正文用 Markdown 渲染,和 issue 详情一样(图片显示为"🖼 图片"链接)。
  8. 作为开发者,我想时间线按时间列出评论、review、commit、force-push、标签和负责人的变化、merge 和关闭事件,这样我能跟上 agent 做了什么、别人说了什么。
  9. 作为开发者,我想时间线里的 review 带上它的行内评论讨论和代码片段。
  10. 作为开发者,我想点时间线里的行内讨论时跳到文件 diff 中对应的那一行。
  11. 作为开发者,我想看到每条评论的表情回应数量。
  12. 作为开发者,我想在描述页看到每个 check 的名称、状态和耗时,这样知道 CI 是否通过。
  13. 作为开发者,我想点一个 check 时在浏览器里打开它(等 3. Actions:run 列表、run 详情窗格和日志 #5 做出 run 详情窗格后改为在 Herdr 里打开)。
  14. 作为开发者,我想点详情里指向当前仓库 PR 的链接时在 PR 详情里打开,指向 issue 的在 issue 详情里打开,并能"返回"。
  15. 作为开发者,我想其他链接用浏览器打开。
  16. 作为开发者,我想在详情窗格复制 PR 的链接、在浏览器中打开它。
  17. 作为开发者,我想详情窗格里也有改动文件的列表(目录树 / 平铺,可隐藏已看过的),可以在描述和各个文件的 diff 之间切换。

diff

  1. 作为开发者,我想看到一个文件的单栏(unified)diff,增加和删除的行用颜色区分,并显示新旧行号。
  2. 作为开发者,我想大 diff 也滚动流畅(只画屏幕上的行)。
  3. 作为开发者,当 GitHub 不给某个文件的 patch(太大或二进制)时,我想看到说明和"在浏览器中查看"。
  4. 作为开发者,我想在每个文件上方"在浏览器中查看文件",去看完整的文件。
  5. 作为开发者,我想把一个文件标为已看过或取消,并同步到 GitHub,这样换个地方 review 时进度还在。
  6. 作为开发者,我想一个已看过的文件在之后又被改动时重新显示为没看过。

行内评论和 review

  1. 作为开发者,我想在 diff 的某一行打开评论框,这样能指出 agent 写错的具体位置。
  2. 作为开发者,我想评论框像插件一样有 Add Comment 和 Start Review 两个按钮。
  3. 作为开发者,我想 Add Comment 立即发出一条单独的行内评论。
  4. 作为开发者,我想 Start Review 在 GitHub 上开始一个待提交 review,之后的行内评论都加进这个 review,这样 agent 最后读到的是一整个 review。
  5. 作为开发者,我想待提交 review 里的评论在 diff 里显示为草稿,和已发出的区分开。
  6. 作为开发者,我想打开 PR 时,如果我在 GitHub 上已经有一个待提交 review(比如之前在网页上开始的),就接着用它。
  7. 作为开发者,我想在 diff 里看到已有的评论讨论,并能回复。
  8. 作为开发者,我想把讨论标为已解决,或取消已解决。
  9. 作为开发者,我想在描述页底部的评论框里写总结,然后选 Comment、Approve 或 Request Changes 提交,这样完成一次 review。
  10. 作为开发者,我想有待提交 review 时,底部按钮提交的是这个 review(连同草稿评论)。
  11. 作为开发者,我想不开始 review、只在描述页底部发一条普通评论。
  12. 作为开发者,我想自己发的评论和 review 立刻出现在时间线和 diff 里。
  13. 作为开发者,我想自动刷新时评论框里没发出的内容保留。

merge 和其他写操作

  1. 作为开发者,我想在描述页看到能不能 merge;不能时看到 GitHub 给的原因(冲突、checks 没过、需要 review、分支保护)。
  2. 作为开发者,我想只在仓库允许的方式(merge / squash / rebase)里选,默认是允许的第一种。
  3. 作为开发者,我想点 merge 后再确认一次,这样不会误点。
  4. 作为开发者,我想 merge 失败时看到 gh 的报错。
  5. 作为开发者,我想 merge 之后可以删除远程分支。
  6. 作为开发者,我想关闭或重新打开 PR。
  7. 作为开发者,我想把 agent 开的 draft PR 标为 ready for review。
  8. 作为开发者,我想写操作成功后,侧边栏的列表和同一 PR 的详情窗格立即更新,不用手动刷新。

刷新

  1. 作为开发者,我想列表在侧边栏显示时每 60 秒检查变化,这样别人新开或关闭的 PR 大约一分钟内出现。
  2. 作为开发者,我想焦点文件夹的本地分支变化时,"本地拉取请求分支"一组重新查询。
  3. 作为开发者,我想 PR 详情窗格在它的标签页显示时每 10 秒检查变化,这样新的评论、review 和 check 结果很快出现。
  4. 作为开发者,我想看不见的侧边栏和详情窗格不轮询,重新显示时立刻刷新一次。
  5. 作为开发者,我想轮询不耗搜索额度(没有变化时用 304)。

Implementation Decisions

  • ADR:界面照抄 VS Code 插件,功能范围由 ADR 决定(ADR 0007);只做人要亲自看、亲自判断的部分(ADR 0001);不接触 agent(ADR 0002);gh 在文件夹所在的机器上运行(ADR 0003);只通过 gh(ADR 0004);只看当前仓库(ADR 0005);条件请求轮询(ADR 0006)。git 只读,不改本地仓库。
  • 和插件的差别(Herdr 做不到或违反 ADR):
    • 改动文件不各开一个标签页:一个 PR 一个原生标签页,点 PR 显示描述,点文件显示该文件的 diff。原因:Herdr 的原生标签页和终端共用顶部,也没有 VS Code 的预览标签。
    • diff 是单栏,只显示改动处附近,不做语法高亮:数据来自 pulls/{n}/files 的 patch;Herdr 的 Editor 不提供分词或行装饰,自己画的 diff 行没有高亮。
    • 不显示作者头像,先用状态图标(网络图片能否显示待在 Mac 上确认)。
    • 保留编号("复制编号"交给 agent,ADR 0002)。
    • 没有 Copilot 分组、Checkout 按钮(6. 分支:checkout PR 和 Start Working #8)、新建 PR、编辑 reviewer / 标签 / 负责人。
  • 新的 Pulls 模块(io):所有 PR 相关的 GitHub 访问都在这个模块里,经由 gh 模块;调用方传 owner/repo 和机器。接口:
    • 按分组查列表:分组、仓库、页码 → 一页 PR(编号、标题、作者、状态、是否 draft、更新时间、链接)和是否还有下一页。三个搜索分组用搜索语法,sort:updated-desc,每页 30 条:review-requested:@me is:open、author:@me is:open、is:open。
    • 本地拉取请求分支:在焦点文件夹的机器上读本地分支(git,只读),用一次 GraphQL 查询批量找每个分支对应的最新一个 PR(任意状态,head 仓库必须匹配)。
    • 读一个 PR:元数据、右侧边栏数据、正文、时间线(评论、review 及其行内讨论、commit、force-push、事件)、checks、merge 状态和原因、仓库允许的 merge 方式、我的待提交 review。
    • 读改动文件:分页;每个文件的路径、旧路径、改动类型、增删行数、patch(可能没有)和我的已看过状态(GitHub 的"改动后失效"视为没看过)。
    • 写:普通评论;单条行内评论;开始待提交 review、往里加行内评论;提交 review(Comment / Approve / Request Changes,带总结);回复讨论;解决和取消解决讨论;标为已看过和取消;merge(指定方式);删除远程分支;关闭和重新打开;标为 ready for review。成功后返回更新后的数据,供界面立即显示。
    • 变化检测:路径和上次的 ETag → "没变"或"变了 + 新 ETag"。列表用 pulls?state=all&sort=updated&per_page=1,详情窗格用这个 PR 本身。
    • 错误分类:404、无权限、merge 被拒绝等,各自给出界面能直接显示的说明。
  • core 的纯逻辑:
    • patch 解析:把一个文件的 patch 解析成 diff 行(类型、旧行号、新行号、文本),并给出每行能否评论、对应 GitHub 的哪一侧(LEFT / RIGHT)和行号。行内评论和讨论按侧和行号挂到 diff 行上。
    • 文件列表:目录树(单子项文件夹合并)和平铺;隐藏已看过的文件。
    • 分组查询拼装;PR 时间线合并排序;merge 区域的状态(可以 merge / 被什么挡住 / 可选方式和默认方式);链接指向 issue 还是 PR。
    • Markdown 预处理和相对时间沿用 Issues 第一版:侧边栏的 Issues 标签页和 issue 详情窗格 #3 的模块。
  • 侧边栏:PRs 标签页加在现有标签页条上;分组可折叠、展开时才加载、"加载更多";行悬停出现"复制编号"和"在浏览器中打开";点行打开详情窗格;PR 可展开成改动文件,展开时才读文件列表。
  • 详情窗格:新的 PR 角色,和 issue 的详情窗格共用原生标签页的管理(一个 PR 一个标签页、再点切回、页内链接替换并可"返回");标签页的管理从"只管 issue"扩展为 issue 和 PR 共用。窗格内有两种视图:描述,以及某个改动文件的 diff;侧边栏点文件时打开(或切回)这个 PR 的标签页并显示该文件。内容不随重启恢复,和 issue 详情一致。
  • 视图之间的同步:写操作成功后,通过 Herdr 的共享状态通知侧边栏和同一 PR 的详情窗格,和 Issues 第一版:侧边栏的 Issues 标签页和 issue 详情窗格 #3 一样。
  • 轮询:侧边栏 60 秒、详情窗格 10 秒,都用条件请求,只在看得见时轮询,重新显示时立刻刷新一次;焦点文件夹的本地分支变化时重查"本地拉取请求分支"。
  • 用词:GitHub mod 的界面是英文,界面文字照插件的英文原文(如 Local Pull Request Branches、Waiting For My Review、Created By Me、All Open、0 pull requests in this category、Add Comment、Start Review、Mark File As Viewed、Comment / Approve / Request Changes)。本 spec 里中文写的按钮和提示只是描述,不是界面文字。讨论和文档用术语表的"分组"、"本地拉取请求分支"、"待提交 review"、"已看过"。

Testing Decisions

  • 好的测试只看外部行为:给定 gh / git 的真实回复,模块返回什么、出错时给出什么说明;不测内部调用顺序和私有函数。期望值来自真实的 gh / GitHub 输出或文档,不由被测代码推算。
  • 主接缝:Pulls 模块(io)。用现有的 fake-herdr:机器按 "<cwd>$ <cmd>" 回答,回复从真实命令的输出复制。覆盖:三个搜索分组的参数、解析和分页;本地分支的读取和批量匹配(含 fork 里 head 仓库不匹配);读 PR 的元数据、时间线、checks、merge 状态、待提交 review;改动文件的分页、patch、没有 patch 的文件、已看过状态;所有写操作;条件请求的"没变 / 变了";各种错误;gh 在文件夹或 PR 所在的机器上运行。
  • 补充接缝:core。patch 解析(行号、能否评论、LEFT / RIGHT 映射、多段 hunk、新增 / 删除 / 重命名文件、文件末尾没有换行);目录树和平铺、合并单子项文件夹、隐藏已看过;分组查询拼装;时间线排序;merge 区域状态;链接分类。
  • 已有接缝:详情标签页的管理。扩展到 PR 后,用现有的标签页测试覆盖:一个 PR 一个原生标签页、再点切回、点文件不开新标签页。
  • 先例:test/io/issues.test.ts、issue-writes.test.ts、detail-tabs.test.ts,以及 core 里 issue 查询、Markdown、时间线的测试。
  • 录 fixture 时在 lw396/herdr-plugin-github 开测试 PR(像测试 issue 测试用,可删:#15 的评论、关闭和重新打开 #20 那样,标题注明"测试用,可删"),开发者已同意。
  • views 和入口保持精简,不写单元测试:靠 bun run verify(含 herdr-app check 和 QuickJS smoke 测试)和在 Mac 上试用检查,包括 diff 的显示、轮询的可见性判断。

Out of Scope

  • 新建 PR;编辑标题、reviewer、标签、负责人、milestone;转回 draft;请求 reviewer(ADR 0001)。
  • Copilot 分组和功能,把 review 意见交给 agent(ADR 0002)。
  • 左右并排 diff、展开更多上下文、语法高亮。
  • 多行范围的评论、suggestion、编辑或删除评论、加表情回应。
  • auto-merge、管理员绕过分支保护。
  • checkout PR、删除本地分支(6. 分支:checkout PR 和 Start Working #8)、worktree(7. worktree:在 worktree 中检出 #9)。
  • run 详情和日志、重跑(3. Actions:run 列表、run 详情窗格和日志 #5)。
  • 自定义分组查询、右键菜单、Commits 视图。
  • 把 Issues 标签页的分组改成插件的样子(另议)。
  • GitHub Enterprise。

Further Notes

  • 待实测(Fog):新的 review、行内评论、check 结果是否改变 PR 本身的 ETag;不会的话,详情窗格再加一个对 checks 的条件请求。放在第一张子票里测。
  • 以后 Herdr 开放 Editor 的分词接口或 diff 行装饰时,可以另开票做语法高亮和并排 diff。
  • center 到 api.github.com 的网络不稳定,录真实回复时可能要重试。
  • 用词按 GLOSSARY.md(GitHub mod、侧边栏、分组、详情窗格、焦点文件夹、当前仓库、本地拉取请求分支、待提交 review、已看过)。

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions