Repository navigation
Closed
10 / 1010 of 10 issues completedDescription
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
- 作为开发者,我想让 GitHub mod 用文件夹所在机器上的 gh,这样访问 GitHub 用的就是那台机器上登录的账号。
- 作为开发者,当焦点文件夹所在的机器没装 gh 时,我想看到"<机器> 上没有 gh",这样我知道去哪台机器上装。
- 作为开发者,当那台机器的 gh 没登录时,我想看到"在 <机器> 上运行 gh auth login",这样我能马上修好。
- 作为开发者,我想在侧边栏标题栏看到当前仓库的
owner/repo,这样我知道看的是哪个仓库。 - 作为在 fork 里工作的开发者,我想看到上游仓库的 issue(有 upstream remote 时),这样我看的是真正讨论需求的地方。
- 作为开发者,当我把焦点移到详情窗格或 Files 等 mod 窗格上时,我想侧边栏保持原来的仓库,这样点开详情不会让列表跳走。
- 作为开发者,当焦点回到另一个仓库的终端时,我想侧边栏切到那个仓库。
- 作为开发者,当焦点文件夹不是 git 仓库或没有 GitHub remote 时,我想看到说明,而不是空列表。
- 作为开发者,当 remote 指向的仓库不存在或我无权访问(404)时,我想看到说明并提示检查
git remote -v。 - 作为开发者,当仓库关闭了 Issues 时,我想看到"这个仓库没有开启 Issues"。
- 作为开发者,我想在侧边栏切到 Issues 标签页。
- 作为开发者,我想看到"指派给我的"open issue,这样我知道自己该推进哪些事。
- 作为开发者,我想看到仓库所有 open 的 issue,这样我能挑下一个交给 agent 的。
- 作为开发者,我想看到已关闭的 issue,这样我能回头确认某件事是怎么结束的。
- 作为开发者,我想三组都按最近更新排序,这样最活跃的在最上面。
- 作为开发者,我想折叠和展开每一组,且折叠的组不发请求,这样不浪费额度。
- 作为开发者,我想每组先看到 30 条,并能"加载更多",这样大仓库也能浏览。
- 作为开发者,我想每行看到编号、标题、负责人和更新时间,这样不用点开就能判断。
- 作为开发者,我想悬停一行时点"复制编号"得到
#42,这样我能直接告诉 agent。 - 作为开发者,我想悬停一行时点"在浏览器中打开"。
- 作为开发者,我想点 ↻ 立即刷新列表。
- 作为开发者,我想点一行就在主区域打开这个 issue 的详情窗格,这样能在宽的地方阅读。
- 作为开发者,我想第一次打开时详情窗格分在焦点窗格右边,之后点别的 issue 替换它的内容,这样屏幕不会被切碎。
- 作为开发者,我想在详情窗格看到标题、状态、作者、标签、负责人和 milestone。
- 作为开发者,我想正文和评论按时间线排列,用 Markdown 渲染,这样读起来和网页一样。
- 作为开发者,我想看到每条评论的表情回应数量。
- 作为开发者,我想正文里的图片显示成"🖼 图片"链接、点了在浏览器里打开,这样至少能看到截图。
- 作为开发者,我想点正文里指向当前仓库 issue 的链接(
#123或完整网址)时在详情窗格里打开它,这样能顺着引用读下去。 - 作为开发者,我想详情窗格有"返回",回到上一个 issue。
- 作为开发者,我想点其他链接时用浏览器打开。
- 作为开发者,我想在详情窗格复制 issue 的链接。
- 作为开发者,我想在详情窗格里"在浏览器中打开",去做 GitHub mod 不做的编辑。
- 作为开发者,我想在详情窗格里发评论,这样能给 agent 和团队补充需求、划定范围。
- 作为开发者,我想自己发的评论立刻出现在时间线里。
- 作为开发者,我想关闭或重新打开 issue,这样我能判断一件事做完没有。
- 作为开发者,我想关闭 issue 后,侧边栏的列表立刻反映出来,不用手动刷新。
- 作为开发者,我想详情窗格在 Herdr 重启后还显示同一个 issue。
- 作为开发者,我想详情窗格只认它自己的 issue,焦点换到别的仓库时它不变。
- 作为开发者,我想详情窗格在它所在的标签页显示时每 10 秒检查变化,这样别人的新评论很快出现。
- 作为开发者,我想自动刷新时评论框里没发出的内容保留。
- 作为开发者,我想列表在侧边栏显示时每 60 秒检查变化,这样别人新开或关闭的 issue 大约一分钟内出现。
- 作为开发者,我想看不见的侧边栏和详情窗格不轮询,重新显示时立刻刷新一次,这样不白白占用资源。
- 作为开发者,我想轮询不耗搜索额度(没有变化时用 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,各自给出界面能直接显示的说明。
- 按分组查列表:分组(指派给我的 / Open / Closed)、仓库、页码 → 一页 issue(编号、标题、负责人、更新时间、milestone)和是否还有下一页。查询用搜索语法,
- 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
- 新建 issue(ADR 0001),编辑标题 / 标签 / 负责人 / milestone,编辑或删除评论,加表情回应:去浏览器。
- 把 issue 交给 agent、给 agent 发消息(ADR 0002)。
- 自定义查询、按 milestone 分组、右键菜单、详情窗格的"固定"和"在新窗格打开"。
- 下载和缓存图片。
- Start Working(建分支)和 worktree(6. 分支:checkout PR 和 Start Working #8、7. worktree:在 worktree 中检出 #9)。
- PR、Actions、通知、底部当前分支卡片的 PR / run 部分(PR review 第一版:侧边栏的 PRs 标签页、PR 详情窗格和 diff #4–5. 通知:当前仓库的通知 #7)。
- GitHub Enterprise。
Further Notes
- 待实测(Fog):gh 遇到 304 时的退出码和输出(不行就退回每 60 秒重新搜索已展开的组、每 10 秒重新读 issue);新评论是否改变 issue 的 ETag;mod 窗格怎么拿到自己的 pane id;侧边栏怎么知道自己在显示;
TextView.markdown能否直接显示公开的网络图片。 center到 api.github.com 的网络不稳定,录真实回复时可能要重试。- 用词按
GLOSSARY.md(GitHub mod、侧边栏、详情窗格、焦点文件夹、当前仓库)。
Activity
[-]1. Issues:侧边栏标签页和详情窗格[/-][+]Issues 第一版:侧边栏的 Issues 标签页和 issue 详情窗格[/+]docs: plan moves to GitHub issues; ADRs 0001-0006 and GLOSSARY.md rep…