Skip to content

Issues 第一版:侧边栏的 Issues 标签页和 issue 详情窗格 #3

Closed
10 of 10 issues completed
Closed

Description

@lw396

Part of #1.

Problem Statement

用 Herdr 的开发者主要让 agent 写代码。要指挥 agent,开发者得先弄清楚一个 issue 要做的是什么,再把编号告诉 agent,并且在 agent 做的过程中跟上 issue 下的讨论。现在只能切到浏览器里看 GitHub:离开了 Herdr,也容易看错仓库(fork、多个 remote、远程机器上的文件夹)。GitHub mod 的侧边栏目前只显示焦点文件夹、机器、gh 登录状态和仓库名,没有任何 issue 功能。

另外,GitHub mod 现在优先用本机的 gh,即使文件夹在远程机器上;于是用的 GitHub 账号不一定是那台机器上登录的账号,也看不清用的是哪个。

Solution

在侧边栏里加一个 Issues 标签页,列出当前仓库的 issue(三组:指派给我的、Open、Closed);点一行就在主区域的详情窗格里看这个 issue 的全部内容:元数据、正文和评论(Markdown)。开发者可以复制编号告诉 agent,可以评论、关闭或重新打开 issue。列表和详情窗格在看得见时自动检测变化并更新。

同时,gh 改为在文件夹所在的机器上运行(ADR 0003):本机文件夹用本机的 gh,远程文件夹用那台机器的 gh,不互相退回;那台机器没装 gh 或没登录时,侧边栏明确说在哪台机器上运行 gh auth login。

User Stories

  1. 作为开发者,我想让 GitHub mod 用文件夹所在机器上的 gh,这样访问 GitHub 用的就是那台机器上登录的账号。
  2. 作为开发者,当焦点文件夹所在的机器没装 gh 时,我想看到"<机器> 上没有 gh",这样我知道去哪台机器上装。
  3. 作为开发者,当那台机器的 gh 没登录时,我想看到"在 <机器> 上运行 gh auth login",这样我能马上修好。
  4. 作为开发者,我想在侧边栏标题栏看到当前仓库的 owner/repo,这样我知道看的是哪个仓库。
  5. 作为在 fork 里工作的开发者,我想看到上游仓库的 issue(有 upstream remote 时),这样我看的是真正讨论需求的地方。
  6. 作为开发者,当我把焦点移到详情窗格或 Files 等 mod 窗格上时,我想侧边栏保持原来的仓库,这样点开详情不会让列表跳走。
  7. 作为开发者,当焦点回到另一个仓库的终端时,我想侧边栏切到那个仓库。
  8. 作为开发者,当焦点文件夹不是 git 仓库或没有 GitHub remote 时,我想看到说明,而不是空列表。
  9. 作为开发者,当 remote 指向的仓库不存在或我无权访问(404)时,我想看到说明并提示检查 git remote -v。
  10. 作为开发者,当仓库关闭了 Issues 时,我想看到"这个仓库没有开启 Issues"。
  11. 作为开发者,我想在侧边栏切到 Issues 标签页。
  12. 作为开发者,我想看到"指派给我的"open issue,这样我知道自己该推进哪些事。
  13. 作为开发者,我想看到仓库所有 open 的 issue,这样我能挑下一个交给 agent 的。
  14. 作为开发者,我想看到已关闭的 issue,这样我能回头确认某件事是怎么结束的。
  15. 作为开发者,我想三组都按最近更新排序,这样最活跃的在最上面。
  16. 作为开发者,我想折叠和展开每一组,且折叠的组不发请求,这样不浪费额度。
  17. 作为开发者,我想每组先看到 30 条,并能"加载更多",这样大仓库也能浏览。
  18. 作为开发者,我想每行看到编号、标题、负责人和更新时间,这样不用点开就能判断。
  19. 作为开发者,我想悬停一行时点"复制编号"得到 #42,这样我能直接告诉 agent。
  20. 作为开发者,我想悬停一行时点"在浏览器中打开"。
  21. 作为开发者,我想点 ↻ 立即刷新列表。
  22. 作为开发者,我想点一行就在主区域打开这个 issue 的详情窗格,这样能在宽的地方阅读。
  23. 作为开发者,我想第一次打开时详情窗格分在焦点窗格右边,之后点别的 issue 替换它的内容,这样屏幕不会被切碎。
  24. 作为开发者,我想在详情窗格看到标题、状态、作者、标签、负责人和 milestone。
  25. 作为开发者,我想正文和评论按时间线排列,用 Markdown 渲染,这样读起来和网页一样。
  26. 作为开发者,我想看到每条评论的表情回应数量。
  27. 作为开发者,我想正文里的图片显示成"🖼 图片"链接、点了在浏览器里打开,这样至少能看到截图。
  28. 作为开发者,我想点正文里指向当前仓库 issue 的链接(#123 或完整网址)时在详情窗格里打开它,这样能顺着引用读下去。
  29. 作为开发者,我想详情窗格有"返回",回到上一个 issue。
  30. 作为开发者,我想点其他链接时用浏览器打开。
  31. 作为开发者,我想在详情窗格复制 issue 的链接。
  32. 作为开发者,我想在详情窗格里"在浏览器中打开",去做 GitHub mod 不做的编辑。
  33. 作为开发者,我想在详情窗格里发评论,这样能给 agent 和团队补充需求、划定范围。
  34. 作为开发者,我想自己发的评论立刻出现在时间线里。
  35. 作为开发者,我想关闭或重新打开 issue,这样我能判断一件事做完没有。
  36. 作为开发者,我想关闭 issue 后,侧边栏的列表立刻反映出来,不用手动刷新。
  37. 作为开发者,我想详情窗格在 Herdr 重启后还显示同一个 issue。
  38. 作为开发者,我想详情窗格只认它自己的 issue,焦点换到别的仓库时它不变。
  39. 作为开发者,我想详情窗格在它所在的标签页显示时每 10 秒检查变化,这样别人的新评论很快出现。
  40. 作为开发者,我想自动刷新时评论框里没发出的内容保留。
  41. 作为开发者,我想列表在侧边栏显示时每 60 秒检查变化,这样别人新开或关闭的 issue 大约一分钟内出现。
  42. 作为开发者,我想看不见的侧边栏和详情窗格不轮询,重新显示时立刻刷新一次,这样不白白占用资源。
  43. 作为开发者,我想轮询不耗搜索额度(没有变化时用 304),这样我在终端和 agent 里用的 gh 不会被限流。

Implementation Decisions

  • gh 的位置(ADR 0003):gh 模块的"选账号"改为只看文件夹所在的那台机器:返回那台机器上的 gh 状态(已登录及用户名 / 没装 / 没登录 / 其他错误),不再先查本机。调用方仍然只传 owner/repo。README 和 AGENTS.md 里"远程机器只需要 git"的说法改掉。
  • 当前仓库:位置规则(焦点终端的文件夹和机器;焦点在没有自己文件夹的窗格上时沿用上一个位置)从 context 模块抽成 core 里的纯函数:输入 Herdr 的 spaces、panes、focused 和上一次的位置,输出新的位置。remote 的选择沿用现有规则(upstream、github、origin、第一个;只认 github.com)。
  • 新的 Issues 模块(io):GitHub mod 里所有 issue 相关的 GitHub 访问都在这一个模块里,经由 gh 模块(ADR 0004)。接口:
    • 按分组查列表:分组(指派给我的 / Open / Closed)、仓库、页码 → 一页 issue(编号、标题、负责人、更新时间、milestone)和是否还有下一页。查询用搜索语法,sort:updated-desc,每页 30 条。
    • 读一个 issue:仓库、编号 → 元数据、正文、按时间排序的评论(作者、时间、正文、表情回应计数)。
    • 发评论、关闭、重新打开:仓库、编号(和正文)→ 成功后返回更新后的数据,供界面立即显示。
    • 变化检测:路径和上次的 ETag → "没变"或"变了 + 新 ETag"。列表用仓库的 issue 列表(state=all&sort=updated&per_page=1),详情窗格用这个 issue 本身。
    • 仓库是否开启 Issues。
    • 错误分类:404、仓库关闭 Issues、未登录、没装 gh,各自给出界面能直接显示的说明。
  • core 的纯逻辑:搜索查询的拼装;正文 Markdown 预处理(图片换成"🖼 图片"链接;识别指向当前仓库 issue 的链接);相对时间显示。
  • 新角色:issue 详情窗格。props 只有 repo、number(随标签页保存,重启后照样加载);gh 在这个窗格所在 space 的机器上运行。每个 Herdr 标签页最多一个详情窗格:已有就替换它显示的 issue,没有就在焦点窗格右边分出来。
  • 侧边栏:保持一个角色,加标签页条(这一版只有 Issues);三组可折叠,展开时才加载,"加载更多";行悬停出现"复制编号"和"在浏览器中打开";点击行打开详情窗格。
  • 视图之间的同步:写操作成功后,通过 Herdr 的共享状态通知其他视图(侧边栏的列表、同一 issue 的详情窗格),它们立即更新。
  • 轮询:侧边栏 60 秒、详情窗格 10 秒,都用条件请求(ADR 0006);只在看得见时轮询(详情窗格:它所在的标签页是当前显示的;侧边栏:它正在显示),重新显示时立刻刷新一次。
  • 剪贴板和浏览器:用 gpui 的 write_to_clipboard、open_url。

Testing Decisions

  • 好的测试只看外部行为:给定 gh / git 的真实回复,模块返回什么、出错时给出什么说明;不测内部调用顺序和私有函数。期望值来自真实的 gh / GitHub 输出或文档,不由被测代码推算。
  • 主接缝:io 模块(gh、新的 Issues 模块)。用现有的 fake-herdr:机器按 "<cwd>$ <cmd>" 回答,回复从真实命令的输出复制(stdout、stderr、退出码)。覆盖:每种查询的参数和解析、分页、读 issue 和评论、写操作、条件请求的"没变 / 变了"、各种错误(404、关闭 Issues、未登录、没装 gh)、gh 在文件夹所在机器上运行。
  • 补充接缝:core。位置规则(含"焦点在 mod 窗格上时沿用上一个位置")、查询拼装、Markdown 预处理、相对时间。
  • 先例:现有的 gh 模块测试(account、status、api)和 core 里 remote 选择、gh 参数的测试。
  • views 和入口保持精简,不写单元测试:靠 bun run verify(含 herdr-app check)和在 app 里试用检查,包括轮询的可见性判断。

Out of Scope

Further Notes

  • 待实测(Fog):gh 遇到 304 时的退出码和输出(不行就退回每 60 秒重新搜索已展开的组、每 10 秒重新读 issue);新评论是否改变 issue 的 ETag;mod 窗格怎么拿到自己的 pane id;侧边栏怎么知道自己在显示;TextView.markdown 能否直接显示公开的网络图片。
  • center 到 api.github.com 的网络不稳定,录真实回复时可能要重试。
  • 用词按 GLOSSARY.md(GitHub mod、侧边栏、详情窗格、焦点文件夹、当前仓库)。

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions