Repository navigation
Description
GitHub mod 的整体规划(原 docs/product.md)。用词见 GLOSSARY.md,范围决定见 docs/adr/。
Notes
- 定位:帮开发者指挥 agent,不让 agent 脱离自己的控制。只做人要亲自看、亲自判断的部分(ADR 0001);GitHub mod 不直接接触 agent(ADR 0002)。
- 只看当前仓库(ADR 0005);访问 GitHub 一律通过 gh(ADR 0004);gh 在文件夹所在的机器上运行(ADR 0003);用条件请求轮询(ADR 0006)。
- 功能参照 VS Code 插件(GitHub Pull Requests 扩展);依赖代码编辑器的功能不做。
Decisions so far
-
描述页的普通评论、关闭和重新打开、Ready for review #32 已完成(按用户要求关闭):描述页普通评论沿用 Start Review、待提交 review 和提交 review #31 的即时显示与失败草稿保留;新增关闭/重开、Ready for Review 及侧边栏/同 PR 窗格刷新。按用户 Mac 截图调整为时间线后统一 Checks/merge 卡片、输入框下左 Close/右 Comment;移除弹出菜单,Change method… 原地展开,主按钮 Merge Pull Request 旁显示 using method,默认 Create Merge Commit,修正真实 GitHub 字段 allow_merge_commit。历史整理为 b723bdd、e89444c(本地未推送),构建产物已提交。最终 350 项测试及完整 verify、check:built 通过,双轴复审无阻塞。最后一轮文字/三种方式与完整写入同步组合仍待 Mac 人工验证;非管理员 REST 隐藏合并设置的现存边界未在本票处理。见 #32。
-
Start Review、待提交 review 和提交 review #31 已完成(按用户要求关闭):Start Review 创建/接续当前账号的待提交 review,后续行内评论及回复加入其中并显示 Pending;描述页底部 Comment / Approve / Request Changes 提交,无待提交 review 时 Comment 发布普通讨论。实现 c14772f、ef72e01、31485a2;最后一项为合并后的运行时/UI 修复:状态在 render 外创建,diff 在同一 snapshot 内做可视区窗口化,修复跨 native virtual-list arena 复用交互节点引起的空白/行号无反应;讨论按内容实测高度排版并补 Cancel。322 项测试及完整 verify、check:built 通过,构建产物已提交;双轴审查已完成,Mac 已确认 diff/评论功能恢复,完整多账号、提交事件、失败恢复及跨窗格同步组合仍未逐项人工验证。见 #31。
-
Add Comment:单条行内评论 #30 已完成(按用户要求关闭):可在 LEFT/RIGHT 的可评论 diff 行打开评论框,Add Comment 立即发布独立行内评论;失败保留内容,防止快速双击重复提交,diff 与时间线分别保留已确认评论直到 GitHub 回读收敛,断线重读但不自动重发。实现 7b49277、a9fed3e;真实写入 fixture、292 项测试及完整 verify、check:built 通过,构建产物已提交;双轴复审完成,无阻塞发现。Mac 双击、失败保留、双端点占位替换及大 diff 滚动仍待人工验证。见 #30。
-
diff 里的已有讨论:回复和解决 #29 已完成(按用户要求关闭):已有 diff 讨论按 LEFT/RIGHT 与当前行号定位,可回复、解决/取消解决,时间线可跳到同一 PR 标签页内的文件讨论;按用户提供的 VS Code 截图,描述页改为紧凑事件行和 review 内分组讨论,代码片段可原地 Show/Hide,回复与解决无需离开时间线。实现 2fcdd00、fcfc9f0、15e3c16、9bb89b8;285 项测试和完整 verify、check:built 通过。前轮审查问题已修复,最新布局优化的双轴复审已完成(均 OK with notes,无 P0/P1;事件正文链接/选择、重复加载提示及连续 Show/Hide 状态已由 78bebfd 修复,290 项测试和完整 verify、check:built 通过,小补丁双轴复审已完成(均 OK with notes,无新增已证实功能性阻塞问题);其他重构建议见票内记录);Mac 页面截图已用于迭代,完整写操作、跳转、草稿保留及 diff 讨论布局交互仍待人工验证。见 #29。
-
Mark File As Viewed 和隐藏已看过的文件 #28 已完成(用户要求关闭):侧边栏及详情 diff 支持标记/取消已看过并同步 GitHub,GitHub 的 DISMISSED 按没看过处理;目录树和平铺可隐藏已看过文件。沿用 改动文件和单栏 diff(只读) #27 的侧边栏单一文件列表;写入断线后重读状态、不重试写入,写入前仅查询 PR ID。实现 841f524、9634a29;双轴审查无阻塞问题,最终 285 项测试及完整 verify、check:built 通过。Mac 视觉与交互仍待人工验证。见 #28。
-
改动文件和单栏 diff(只读) #27 已完成(用户要求关闭):侧边栏 PR 可展开紧凑目录树或平铺文件列表,显示改动类型;点击文件在同一个 PR 原生标签页显示虚拟化只读单栏 diff,支持新旧行号、增删配色、缺少 patch 说明和浏览器入口。按用户最新选择,文件树仅放在 GitHub 侧边栏,详情不再重复文件列表,保留 Description 返回。实现 41b142d、3c2f7a5、8e1a042;258 项测试及完整 verify、check:built 通过,双轴审查无阻塞问题。Mac 侧边栏截图已用于布局迭代,完整 diff 和大 diff 滚动仍待人工验证。见 #27。
-
PR 详情窗格:描述页基础 #25 已完成(用户要求关闭):PR 描述页显示状态、分支、只读元数据、Markdown 正文与评论及表情计数;同仓库 issue/PR 在同一原生标签页跳转并支持返回,内容仅保留在会话中。实现 5415909、ccb68ea;251 项测试及完整 verify、check:built 通过,双轴审查完成;Mac 界面与链接交互未在本会话中取得验证证据。见 #25。
-
PRs 标签页:Local Pull Request Branches 分组 #24 已完成(用户要求关闭,Mac 基本显示已确认):Local Pull Request Branches 排在最前,在焦点文件夹机器上只读 git,以一次 GraphQL 批量匹配每个本地分支最新的任意状态 PR,按 head 仓库过滤;每页 30 条,快照未变不重发查询。实现 e90139d、1d7cfc6;239 项测试及完整 verify、check:built 通过。无 origin 且多仓库 remote 的歧义为非阻塞边界,PR 状态自动检测由 PR 的轮询:侧边栏和详情窗格 #34 继续。见 #24。
-
PRs 标签页:Waiting For My Review 和 Created By Me 分组 #23 已完成(按用户要求关闭):Waiting For My Review、Created By Me 用插件的默认搜索查询(gh 账号的用户名代替 ${user});搜索只在展开、过期(一分钟)或 ↻ 时发(ADR 0006)。默认照插件只展开 All Open。Issues 和 PRs 共用一个折叠分组组件。实现 d3ac6c7,见 #23。
-
PRs 标签页:All Open 分组 #22 已完成(按用户要求关闭):PRs 标签页的 All Open 分组用 repository.pullRequests(不走搜索,ADR 0006),行的写法照插件;PR 列表按机器、仓库、gh 账号缓存。测试 PR 测试用,可删:PR fixture #35(ready)、测试用,可删:draft PR fixture #36(draft)留作后续子票的 fixture,不合并。实现 2d9af5c,见 #22。
-
预先重构:详情标签页和视图同步支持 PR #21 已完成(PR review 第一版:侧边栏的 PRs 标签页、PR 详情窗格和 diff #4 的第一张子票,按用户要求关闭):详情标签页和视图同步同时认 issue 和 PR,issue 标签页的 key 不变,同号 issue 与 PR 各有标签页;侧边栏可在 Issues 和 Pull Requests 之间切换(PR 内容由后续子票加)。PR review 第一版:侧边栏的 PRs 标签页、PR 详情窗格和 diff #4 已写成 spec 并拆为 预先重构:详情标签页和视图同步支持 PR #21–PR 的轮询:侧边栏和详情窗格 #34;界面照抄 VS Code 插件、范围由 ADR 决定(ADR 0007)。实现 816358b,见 #21。
-
底部卡片改为 gh 状态,4. 侧边栏底部的当前分支卡片 #6 关闭:分支与 Herdr 原生显示重复,PR/CI 卡片试过后撤回(未推送,已从历史中去掉)。底部固定显示文件夹所在机器上的 gh 账号(
lw396 · center);只有列表变化检查失败时才多一行;gh 未安装/未登录/出错时红点加一句话,具体做法仍在列表里说。不增加请求。PR 和 run 只在 PRs、Actions 标签页里看。实现 fdcb504,见 #6。 -
侧边栏底部的当前分支卡片(只显示分支) #18 已完成(已被 4. 侧边栏底部的当前分支卡片 #6 的 gh 状态卡片取代):侧边栏固定底部分支卡片,分支来自 Herdr panes(),无需额外 git;匹配当前文件夹与机器,焦点到 mod 时沿用当前仓库规则。实现 f4bb334,用户已在 Mac 重启 Herdr 后确认显示,见 #18。
-
详情窗格的变化检测轮询 #17 已完成(按用户要求关闭):详情页可见时每 10 秒对 issue 本身发条件 GET;实测新增评论改变 issue ETag,因此一次检测请求足够。窗格身份来自 tab.new 的 tab/pane 回执;可见性按自身 space/tab,刷新保留草稿。实现 9d2123b 与 Mac 验证说明见 #17。
-
侧边栏列表的变化检测轮询 #16 已完成(按用户要求关闭):侧边栏使用 gh 条件 GET,每 60 秒检测列表,仅变化时刷新展开组;gh 2.96 的 304 为 exit 1,但 stdout 保留响应头,可可靠识别。可见性按实时 layout 的 hidden/stack.active 判断。实现与检查见 #16;Mac 显示/隐藏交互仍按 ticket 留作人工验证。
当前仓库
- 侧边栏跟随焦点文件夹。有多个 remote 时按 gh 的规则选:upstream、github、origin、第一个(在 fork 里看的是上游仓库)。
- 焦点落在没有自己文件夹的窗格上(详情窗格、Files 等 mod 窗格)时,侧边栏保持上一个仓库不变。
- 只支持 github.com;GitHub Enterprise 以后再说。
放在哪
- 侧边栏:标签栏里 Files、Changes 旁边的 GitHub 按钮打开,宽约 300–400 px,只用来导航,只放列表。
- 详情窗格:主区域里显示一个 issue / PR / run(
pane.split,props 如{ role: "issue", repo, number }),每种是views/里的一个角色。- 每个 Herdr 标签页最多一个:第一次在焦点窗格右边分出来,之后点别的条目就替换内容。第一版不做"固定""在新窗格打开"。
- 随标签页保存,只靠 props 里的
repo、number找内容,不跟随焦点文件夹;gh 在这个窗格所在 space 的机器上运行。
- 终端(
terminal.open):内容长的或需要交互的,比如完整的 Actions 日志(gh run view --log)、gh run watch。
侧边栏
┌ GitHub owner/repo ↻┐ 标题栏:仓库名、刷新
│ Issues PRs Actions 通知3 │ 标签页(通知带未读数)
│ ▾ 指派给我的 │ 列表(可滚动)
│ #42 Login fails 2h │
│ 加载更多… │
│ ▸ Open │
│ ▸ Closed │
│─────────────────────────│
│ ● lw396 · center │ gh 状态(固定在底部):账号 · 机器;
│ │ 检查失败时多一行
└─────────────────────────┘
- 标题栏:仓库名和刷新。出错时(没有 remote、没有 gh、404)在列表的位置显示错误。
- 标签页:Issues · PRs · Actions · 通知,随功能一个个出现。
- gh 状态卡片始终固定在底部,上方列表单独滚动;只显示,不可点击。不显示分支(Herdr 自己显示),也不显示 PR/CI。
- 列表的行:点击打开详情窗格;悬停时右侧出现"复制编号"(
#42)和"在浏览器中打开"。第一版不做右键菜单。
刷新
- 侧边栏打开时、当前仓库变化时、点 ↻ 时、自己做了写操作之后,立即刷新。
- Issues / PR 列表:每 60 秒对
repos/{owner}/{repo}/issues?state=all&sort=updated&per_page=1(PR 用pulls)发带 ETag 的条件请求;304 就不动,有变化才重新搜索已展开的组。 - 详情窗格:每 10 秒对它显示的对象发一次条件请求,有变化就重新加载;评论框里没发出的内容保留,自己发的评论立刻显示。
- 通知:按
X-Poll-Interval(通常 60 秒)轮询,同样用条件请求。 - run:只在排队或运行中时每 10–20 秒轮询。
- 只在看得见时轮询:详情窗格只在它所在的标签页显示时,侧边栏只在显示时;重新显示时立刻刷新一次。
写操作
- 只做少量写操作,每个都是一条 gh 命令,在显示该对象的详情窗格或侧边栏里执行;需要编辑器或很多字段的交给终端里的 gh。
- 写操作成功后,所有受影响的视图(侧边栏、详情窗格)立即更新(Herdr 的
shared()/setShared())。 - 第 1–5 步只写 GitHub,不改本地仓库;git 只用来读(remote、当前分支)。分支和 worktree 在第 6、7 步。
Fog
- gh 遇到 304 时的退出码和输出;不行就退回每 60 秒重新搜索已展开的组。
- 新评论是否让 issue 的 ETag 变化(一个请求就够)。
- mod 窗格怎么拿到自己的 pane id;侧边栏怎么知道自己在显示。
TextView.markdown能不能直接显示公开的网络图片。
顺序
子 issue 按顺序:#2(第 0 步)→ #3 → #4 → #5 → #6(已关闭,底部改为 gh 状态卡片)→ #7 → #8 → #9。
Activity
docs: plan moves to GitHub issues; ADRs 0001-0006 and GLOSSARY.md rep…