repo-radar

repo-radar 是做什么的？

仪表盘是一个单一的 HTML 文件，由 scripts/dashboard.py 从 GitHub 生成。它需要 Python 3.10+、PyYAML 和已登录的 GitHub CLI (gh)。它不调用任何 AI，因此可以每天在 GitHub Action 中免费重建。

其标签页：

标签页	显示内容
计划	仅当仓库有计划文件时显示。系统的每一部分以框的形式呈现，显示每个框的负责人，以及哪些项已构建、正在审查或缺失。标记其 PR 已合并或已关闭的项，以及没有任何项指向的开放 PR。
拉取请求	按所需操作排序的开放 PR：准备合并、需要审查、等待作者、检查失败、草稿。“从这里开始”最多选取五个。
问题	开放问题：尚无人负责、已分配人员、有开放的 PR。
关系图	开放工作如何关联：计划框 → 问题 → PR、子问题、“被阻塞”、基于其他 PR 分支构建的 PR。
已完成	最近 90 天内关闭的 PR 和问题，按发布的版本分组。

有两种设置方式。如果不清楚，请询问用户想要哪一种：

方式	适用对象	添加的内容和位置
在单个仓库中 (init)	正在处理该仓库的人	在该仓库中添加每日 Action，构建该仓库的页面
观察列表 (init --watch)	需要关注多个仓库的人，例如经理或教师	在用户自己的一个仓库中添加每日 Action，为每个被观察的仓库构建一个页面，外加一个概览页。不向被观察的仓库添加任何内容

下文中的 SCRIPT 指本技能文件夹中的 scripts/dashboard.py，或已运行 init 的仓库中的 .github/dashboard/dashboard.py。

计划文件（可选）

计划列出了系统需要但 GitHub 无法知晓的内容：尚未有人为此创建问题或 PR 的部分。完整格式位于 scripts/dashboard_plan.py 顶部，templates/plan.yaml 是一个入门模板。简而言之：若干组框，每个框包含一个项列表，每个项的状态为 built（已构建）、simulated（模拟）、pr（有 PR，需附带 PR 编号）或 missing（缺失）。框可以有 owner（负责人），否则继承其组的负责人。默认位置是 docs/plan.yaml；可通过 --plan 指定其他路径。

规则

1. 先报告，仅在用户要求时才编辑。 脚本从不编辑计划。仅在用户要求你将他们的拉取请求放入计划时才编辑它。
2. 仅编辑用户自己的项。 不要改动其他人的项以及 as_of 行。同时打开多个拉取请求时，不要都编辑同一行。
3. 除非用户运行每周刷新，否则不要将项标记为 built。 每周由一个人执行一次，在拉取请求合并之后。应说“已合并，准备好进行每周刷新”。
4. 绝不编造状态。 只有当一个开放的拉取请求执行了该项工作时，项的状态才是 pr。当你无法判断一个拉取请求属于哪个框时，请询问用户。
5. 绝不将 HTML 页面提交到主分支。 每日 Action 将其保留在独立的 dashboard 分支上。手动构建的页面应放在仓库外的临时文件夹中（下文称为 <scratch dir>）。

在仓库中设置

在写入任何内容之前，一次性询问：

• 团队是否需要计划？如果需要，放在哪里（默认 docs/plan.yaml），是否已存在？任何符合上述格式的文件都可以，因此已有的文件可以保留。
• 希望什么时间重建？Action 使用 UTC；默认每天 11:00 UTC。

然后，在仓库的顶层文件夹中运行：

python SCRIPT init                                   # 脚本 + 每日 Action
python SCRIPT init --with-plan                       # ... 以及一个入门 docs/plan.yaml
python SCRIPT init --plan path/to/plan.yaml          # ... 使用已有的计划

init 会创建 .github/dashboard/（脚本）和 .github/workflows/dashboard.yml，如果文件已存在则拒绝替换。接着：

1. 在本地构建一次页面（见下一节）并展示它，以便用户看到它能工作。
2. 如果你创建了入门计划，请与用户一起填写：组、框、负责人，以及一个将每个负责人姓名映射到其 GitHub 登录名的 people 列表。
3. 告知用户需要提交哪些文件（init 创建的文件以及计划），并说明一旦其到达默认分支，他们可以立即从 Actions 标签页（“Dashboard”，然后“Run workflow”）运行。
4. 告知用户每天如何查看： git fetch origin dashboard && git show origin/dashboard:index.html > dashboard.html， 然后打开 dashboard.html。对于公开仓库，他们也可以为 dashboard 分支启用 GitHub Pages 以获得一个网址。

如果 Action 因“权限被拒绝”（Permission denied）而推送失败，说明仓库或组织限制了 Action 的权限：设置 → Actions → General → 工作流权限，选择“读写权限”。请由用户本人而不是你来更改该设置。

设置观察列表（多个仓库）

一次性询问：要观察哪些仓库（格式为 owner/name），其中是否有仓库的 docs/plan.yaml 之外的其他位置存放计划文件，要用哪个仓库来保存观察列表（可以是一个新的空仓库），以及希望什么时间重建（UTC）。

在写入任何内容之前，先构建一次页面以便用户查看：

python SCRIPT watch --list <scratch dir>/watchlist.yaml --out <scratch dir>/radar

打开该文件夹中的 index.html。无法读取的仓库会在其行上显示错误，而不会影响其他仓库：通常是仓库名拼写错误，或者是私有仓库。

然后，在将保存观察列表的仓库中：

python SCRIPT init --watch            # 脚本、watchlist.yaml 和 .github/workflows/radar.yml

将用户的仓库写入 watchlist.yaml，然后告知他们：

1. 需要提交哪些文件（init --watch 创建的文件），并且一旦其到达默认分支，他们可以立即从 Actions 标签页（“Radar”，然后“Run workflow”）运行。
2. 私有仓库需要令牌。 Action 可以读取公开仓库及其自身仓库，但无法读取其他仓库。要观察私有仓库，用户需要创建一个有权读取这些仓库的 GitHub 令牌，并将其保存为观察仓库中的一个名为 RADAR_TOKEN 的密钥（设置 → Secrets and variables → Actions）。此操作应由用户本人完成；绝不要询问用户的令牌或将令牌粘贴到任何地方。
3. 如何每天查看： mkdir -p radar && git fetch origin dashboard && git archive origin/dashboard | tar -x -C radar， 然后打开 radar/index.html。

稍后如需添加或移除仓库，只需编辑 watchlist.yaml；无需更改其他内容。

更新仓库中的脚本副本

init 会将脚本复制到仓库中，因此仓库会一直使用当时获取到的版本，直到有人更新它。当用户要求在一个仓库中更新 repo-radar，或者本技能的脚本比仓库中的更新时，在仓库的顶层文件夹中运行：

python scripts/dashboard.py update        # 使用本技能的副本，而不是 .github/dashboard/ 中的

它仅替换 .github/dashboard/ 中的脚本，并显示哪些文件发生了变化。Action、观察列表和计划保持不变。然后告知用户提交 .github/dashboard/。

立即查看

python SCRIPT build --out <scratch dir>/dashboard.html

在仓库内运行（或通过 --repo owner/name 指定）。将页面写入仓库外的临时文件夹，这样它就不会被意外提交，然后将其展示给用户。用通俗的语言解释其内容，从“从这里开始”卡片和“计划”标签页上的任何黄色标签开始。每个计数都应带有具体含义：“16 个开放拉取请求中有 12 个需要审查”，而不是“12 个需要审查”。

我在哪里（单人，对照计划）

你需要两个名称：计划中使用的负责人名称和GitHub 登录名。如果计划的 people 列表中包含当前 gh 已登录的登录名，脚本会自动找到名称。否则请询问，并通过 --owner "<Name>" 参数传入。仅当用户询问关于其他人的情况时，才需要传入 --login。

当用户位于一个拉取请求分支上时，运行两次。主分支显示团队今天看到的情况；分支显示此拉取请求将改变的内容：

git fetch origin
python SCRIPT me --ref origin/main
python SCRIPT me

报告包含四个表格：

表格	告知用户的信息
你的框	对于每个用户负责或有 PR 的框：有多少项已构建、模拟、有 PR、缺失
仍然缺失的项	用户的下一个任务，按框列出
标记为 pr 的项，与 GitHub 核对	开放的 PR 无需操作。已合并的 PR 准备好进行每周刷新。已关闭但未合并的 PR 意味着该项应恢复为 missing
你的开放 PR 未在计划中	计划尚未显示的工作

按以下顺序解释：已完成和正在审查的内容；计划中缺失哪些 PR，以及每个 PR 可能属于哪个框；任何 PR 已关闭但未合并的项；第一项缺失内容作为可能的下一项任务。

将拉取请求放入计划（仅在用户要求时）

在用户的拉取请求分支上工作，而不是在主分支上。

1. 找到拉取请求编号：gh pr view --json number,title。
2. 找到该拉取请求构建的项。阅读计划中用户的框。
   • 如果已有项描述了该工作，将其状态改为 pr 并添加 pr: <number>。
   • 如果没有项描述，则在正确的框中添加一个：{status: pr, pr: <number>, text: "<它所构建的内容>"}。text 保持简短明了。如果不清楚属于哪个框，请询问用户。
3. 检查计划仍能加载：python SCRIPT build --out <scratch dir>/check.html。如果不能，它会停止并显示一条信息来指出错误。
4. 再次运行 me。该拉取请求现在应出现在“标记为 pr 的项”下，而不是“未在计划中”。
5. 在用户的拉取请求中提交计划文件。

每周刷新（仅限执行此操作的人）

在主分支上构建页面，或为每个负责人运行一次 me --ref origin/main。然后，在一个拉取请求中：

• 将 PR 已合并的每个项标记为 built，如果合并的工作只是一个存根、模拟或骨架，则标记为 simulated。计划标签页会将这些标记为“已合并”。
• 将 PR 已关闭但未合并的每个项恢复为 missing。
• 在拉取请求描述中列出没有对应项（计划标签页的最后一个部分）的开放 PR，供其负责人放置。不要猜测它们的框。
• 将 as_of 设置为你检查时使用的主分支提交 ID 和日期。

无网络访问时

python SCRIPT fetch --out data.json 会保存 GitHub 返回的数据；之后 build --data data.json 和 me --data data.json 可以在离线状态下工作。测试也使用此功能。