rtk repo-recap 技能：用 Claude Code Skill 一键生成 PR/Issue/Release 团队简报的完整流水线

本文围绕 rtk 仓库内置的 .claude/skills/repo-recap/SKILL.md 技能文件展开，完整拆解其"前置检查 → 数据采集 → 分类分析 → 格式化输出 → 复制到剪贴板"七步工作流，并结合仓库中 release-please 配置、GitHub Actions 工作流与 rtk gh 过滤器的源码实现，说明该技能如何与 rtk 项目的日常维护自动化协同工作。读完本文，你可以复用这套流程为自己的仓库构建可分享的 Repo Recap 简报，并理解技能文件中每条规则背后的工程动机。

技能定位：rtk 维护工作流中的一个自动化环节

repo-recap 是 rtk 项目 .claude/skills/ 目录下的一个 Claude Code 技能（Skill），与同目录的 pr-triage、issue-triage、ship、security-guardian 等技能共同构成维护者工作流。它的职责单一而明确：

Generate a structured recap of the repository state: open PRs, open issues, recent releases, and executive summary. Output is formatted as Markdown with clickable GitHub links, ready to share.

技能文件头部的 frontmatter 声明了它的元信息（见 SKILL.md）：

字段	值	含义
description	Generate a comprehensive repo recap (PRs, issues, releases) for sharing with team. Pass "en" or "fr" as argument for language (default fr).	技能用途描述，同时约定了语言参数
allowed-tools	Bash Read Grep	技能被允许调用的工具集，即只允许执行命令与读取文件，不修改仓库内容

从 allowed-tools 限制可以看出，这是一个"只读采集 + 只写剪贴板"型技能：它的全部副作用就是产出一份 Markdown 简报并复制到剪贴板，不会触碰仓库本身。这也契合 rtk 项目对 AI 代理行为收敛的一贯取向——CLAUDE.md 中专门用 "Avoiding Rabbit Holes" 章节约束了探索性命令数量，repo-recap 则把采集步骤固化为固定的 5 条命令，避免 Agent 自由发挥。

语言参数：双语输出（默认法语）

技能约定通过调用参数选择输出语言：

• 传入 en 或 english → 用英文生成简报；
• 传入 fr、french 或不传参 → 用法语生成简报（默认）。

这个默认值并非偶然：从技能模板中的 "Récap"、"Nos PRs"、"Contributeurs externes" 等表头可以看出，该仓库的维护团队以法语为主要工作语言。技能同时维护 FR 与 EN 两套完整输出模板，两套模板的表格结构完全一致，仅表头文案与空数据提示语不同（例如 "Aucune PR ouverte." vs "No open PRs."），保证同一份数据在两种语言下呈现相同的可读结构。

前置条件检查：先验证环境再采集

技能要求在任何数据采集之前先执行两条检查命令：

# 必须位于 git 仓库内
git rev-parse --is-inside-work-tree

# 必须已认证 gh CLI
gh auth status

规则是：任一条失败就立即停止并告知用户缺少什么，而不是继续执行后续步骤。这一设计避免了两类典型故障——在非仓库目录执行 gh 导致 nameWithOwner 取不到值而生成错误链接；以及未认证时 gh pr list 报 401 后 Agent 误以为"仓库没有 open PR"而输出误导性的空表格。

第一步：数据采集（5 条并行 gh 命令）

技能将采集固化为 5 条 gh CLI 命令，并通过 --json 参数获取结构化数据以便后续分析：

# 仓库标识（用于生成链接）
gh repo view --json nameWithOwner -q .nameWithOwner

# Open PRs 及元数据
gh pr list --state open --limit 50 --json number,title,author,createdAt,changedFiles,additions,deletions,reviewDecision,isDraft

# Open Issues 及元数据
gh issue list --state open --limit 50 --json number,title,author,createdAt,labels,assignees

# 最近 Release（版本历史）
gh release list --limit 5

# 最近已合并 PR（贡献者活跃度）
gh pr list --state merged --limit 10 --json number,title,author,mergedAt

各命令的字段选择与后续步骤一一对应，这是理解整个技能数据流的关键：

• changedFiles / additions / deletions → 支撑第三步的 PR 尺寸分级与重叠检测；
• reviewDecision → 判断 CI 是否被要求修改（CHANGES_REQUESTED）；
• isDraft → 区分草稿 PR 与待评审 PR；
• labels / assignees（issue）→ 支撑 issue 分类；
• merged PR 的 author / mergedAt → 作为权限不足时推断维护者的回退依据。

技能还特别标注了一个 gh JSON 结果的易错点：

author in JSON results is an object {login: "..."} — always extract .author.login when processing.

即 author 是一个对象而非字符串，处理时必须取 .author.login，否则后续所有"按作者分组"的逻辑（维护者判定、cluster 检测）都会失败。

第二步：确定维护者，区分"我们的 PR"与外部贡献

为了把 PR 分为 "Our PRs" 和外部贡献两类，技能通过 GitHub REST API 拉取协作者列表：

gh api repos/{owner}/{repo}/collaborators --jq '.[].login'

其中 {owner}/{repo} 来自第一步的 gh repo view 结果，不允许硬编码。若该请求因权限失败，回退策略是：将"最近合并过 PR 的作者"视为拥有 write/admin 权限的人。技能要求在此情况下拿不准时直接向用户确认，而不是猜测——这是"宁可问一句，不可输出错误简报"的取舍。

第三步：分析与分类（技能的核心算法）

PR 三分类

1. Our PRs（作者为仓库协作者） 列出 PR 号（带链接）、标题、尺寸（+additions、files 数）与状态。

2. External — Reviewable（外部贡献、可正常评审） 必须同时满足：

• additions ≤ 1000 且 files ≤ 10；
• 无合并冲突，CI 未失败。

输出包含：PR 链接、作者、标题、尺寸、评审状态、建议动作。

3. External — Problematic（满足任一即入列）

• additions > 1000 或 files > 10；
• CI 失败（reviewDecision = "CHANGES_REQUESTED" 或 checks 失败）；
• 与另一个 open PR 修改了相同文件（重叠）。

输出额外要求写明具体问题和已采取/需采取的动作，例如 "Rebase requested"、"Split requested"、"Trim requested"、"CI broken"、"Waiting on author"。

尺寸标签（快速视觉分诊）

标签	Additions
XS	< 50
S	50-200
M	200-500
L	500-1000
XL	> 1000

统一格式为 +{additions}, {files} files ({label})，例如 +245, 2 files (S)。这套 XS–XL 分档让维护者扫一眼表格就能定位"XS/S 可直接合并"的 quick wins 与 "XL 需要拆分"的高风险项。

重叠检测（overlap）

两个 PR 若修改了相同文件即视为重叠。技能利用第一步采集的 changedFiles 做比对：若两个 PR 的文件重叠度超过 50%，双方都标记为 overlapping 并互相交叉引用。这直接对应"Problematic"分类中的第三类条件，也解释了为何采集命令要显式请求 changedFiles 字段。

贡献者 cluster 标记

若同一作者有 3 个及以上 open PR，在简报中记为一个 "cluster"，并给出建议的评审顺序——最小的先评，或按依赖链排序。这避免了维护者被同一人的批量 PR 淹没时失去优先级感。

Issue 四分类

• In progress：存在关联的 open PR（通过 PR body 中的 fixes #N、closes #N 或同主题匹配）；
• Quick fix：范围小、可立即执行（bug 报告、小型增强）；
• Feature request：范围大、需要设计讨论；
• Covered by PR：已有 PR 覆盖该 issue（需在简报中链接该 PR）。

第四步：近期 Release 推导（含 release-please 回退）

从 gh release list 输出提取 version、date、name，列出最近 5 个。

关键的回退路径：若仓库没有 GitHub Release，则检查已合并 PR 中标题匹配 chore(*): release * 的 release-please 提交作为替代版本来源。这一规则与本仓库的实际发布机制严格对应，仓库中存在完整的 release-please 证据链：

• release-please-config.json 声明了 release-type: rust、package-name: rtk，以及 bump-minor-pre-major / bump-patch-for-minor-pre-major 两条版本递增策略；
• .release-please-manifest.json 记录当前版本（"." : "0.42.4"）；
• CHANGELOG.md 由 release-please 自动生成，条目中可见 **cicd:** set release-please target-branch to master 等发布相关提交；
• .github/workflows/release.yml 定义了 tag 触发的多平台构建发布流程；
• .github/workflows/next-release.yml 在 PR 合入后按 feat/fix 前缀自动更新"下一个 release"条目——与 issue 分类中 fixes #N/closes #N 的关联逻辑使用同一套语义。

因此对该仓库执行 repo-recap 时，Release 表格通常直接来自 gh release list；而对没有 Release 页的仓库，release-please 提交回退正好适用。

第五步：执行摘要（Executive Summary）

技能要求产出 5–6 条要点，覆盖固定维度：

• open PRs 与 issues 的总数；
• 活跃贡献者（谁的 PR/issue 最多）；
• 主要风险（超大 PR、CI 失败、合并冲突）；
• Quick wins（XS/S 尺寸、无阻塞、可直接合并的小 PR）；
• 需要的 bug 修复（hook 缺陷、回归）；
• 本方（Our）PR 的状态。

注意"Bug fixes needed (hook bugs, regressions)"这一条是明确针对 rtk 项目语境写的：rtk 的核心功能就是 hook 与过滤器（参见 hooks/ 目录及 src/hooks/ 模块），hook 回归是该仓库最高优先级的缺陷类型，因此被直接写进了摘要模板。

第六步：输出格式规范

完整简报的 Markdown 结构约束如下：

• 标题：# {Repo Name} — Récap au {date}（FR）或 # {Repo Name} — Recap {date}（EN）；
• 各章节之间用 --- 分隔；
• 所有 PR/issue 号必须是可点击链接：PR 用 [#123](https://github.com/{owner}/{repo}/pull/123)，issue 用 .../issues/123；
• 所有清单一律使用 Markdown 管道表格；
• 关键动作与风险用加粗；
• 相关 PR 与 issue 之间交叉引用（如 "Covered by #131"）。

空数据处理（避免输出空表格）：

• 0 个 open PR → 显示 "Aucune PR ouverte."（FR）/ "No open PRs."（EN）；
• 0 个 open issue → "Aucune issue ouverte." / "No open issues."；
• 0 个 release → "Aucune release récente." / "No recent releases."。

技能提供了完整的 FR 输出模板，章节依次为 "Releases récentes"、"PRs ouvertes（含 Nos PRs / Contributeurs externes — Reviewables / Contributeurs externes — Problématiques 三个子表）"、"Issues ouvertes"、"Résumé exécutif"；EN 模板结构相同，表头替换为 "Recent Releases"、"Open PRs"、"Our PRs"、"External — Reviewable"、"External — Problematic"、"Open Issues"、"Executive Summary"，动作标签统一为 "To review"、"Rebase requested"、"Split requested"、"Trim requested"、"CI broken"、"Waiting on author"、"Feature request"、"Quick fix"、"Covered by PR"。

第七步：自动复制到剪贴板

简报展示后自动复制到系统剪贴板，采用跨平台降级策略：

# Cross-platform clipboard
clip() {
  if command -v pbcopy &>/dev/null; then pbcopy
  elif command -v xclip &>/dev/null; then xclip -selection clipboard
  elif command -v wl-copy &>/dev/null; then wl-copy
  else cat
  fi
}

cat << 'EOF' | clip
{formatted recap content}
EOF

依次探测 macOS 的 pbcopy、X11 的 xclip、Wayland 的 wl-copy，全部缺失时降级为 cat 直接输出（保证不中断流程）。最后以 "Copié dans le presse-papier."（FR）或 "Copied to clipboard."（EN）确认。

源码纵深：rtk gh 与 --json 透传机制的契合点

理解 repo-recap 如何嵌入 rtk 项目的维护日常，需要看一个源码细节。rtk 自身就是 gh 命令的输出压缩代理，src/cmds/git/gh_cmd.rs 中实现了 pr、issue、run、repo、api 等子命令的过滤器，把 gh 的 JSON 输出压缩成紧凑文本（docs/usage/FEATURES.md 中给出 rtk gh pr list 约 80% 的输出压缩率）。

但技能里所有采集命令都显式带了 --json 参数。这不是巧合，而是与 rtk gh 过滤器的一条透传规则精确对应——gh_cmd.rs 定义了检测函数：

/// Check if args contain --json flag (user wants specific JSON fields, not RTK filtering)
fn has_json_flag(args: &[String]) -> bool {
    args.iter().any(|a| a == "--json")
}

并在 run 入口 中：

pub fn run(subcommand: &str, args: &[String], verbose: u8, ultra_compact: bool) -> Result<i32> {
    // When user explicitly passes --json, they want raw gh JSON output, not RTK filtering
    if has_json_flag(args) {
        return run_passthrough("gh", subcommand, args);
    }
    ...
}

也就是说：只要参数里出现 --json，rtk 就完全透传原始 JSON，不做任何压缩。repo-recap 的采集步骤依赖完整的结构化 JSON 来做尺寸分级、重叠比对和作者分组，任何压缩都会破坏分析；而日常人工巡检时用 rtk gh pr list 拿紧凑视图省 token。同一套工具链在"机器消费"与"人眼消费"两种场景下各走一条路径，--json 是两者之间的开关。

从源码结构看，这种"代理优先、显式逃逸"的模式正是 rtk 设计哲学的缩影：CLAUDE.md 建议日常开发中优先使用 rtk <cmd> 获得 token 优化输出，同时保留 rtk proxy <command> 与透传机制保证"永远能拿到原始输出"。repo-recap 作为维护者技能，恰好示范了如何在使用 rtk 的环境中正确地绕过过滤器（带 --json）与使用过滤器（人工浏览）之间的边界。

顺带一提，该仓库 .github/workflows/stale.yml 每周一运行 stale 机器人，其注释里直接提到 "51 open PRs" 的 triage 压力——这正是 repo-recap 类技能的现实背景：当 open PR/issue 数量超过人工记忆容量时，需要周期性机器化简报来维持分诊节奏。

使用守则（技能 Notes 全量继承）

技能末尾的四条 Notes 是对执行质量的最终约束：

1. 始终使用 gh CLI（唯一例外是拉取 collaborators 列表走 gh api），不直接调 GitHub REST API；
2. 仓库 owner/name 必须从 gh repo view 推导，不得硬编码——保证技能可复用到任意仓库；
3. 保持表格紧凑：长标题截断，最长约 60 字符；
4. 尽可能交叉引用重叠的 PR/issue；并再次强调 author 是对象、必须取 .author.login。

小结：一套可移植的仓库简报流水线

repo-recap 的完整链路可以概括为：git/gh 双前置检查 → 5 条 --json 采集命令 → 协作者列表界定"我方"边界 → PR 三分类 + XS–XL 分档 + 50% 重叠阈值 + 3-PR cluster 规则 → issue 四分类 → Release 推导（release-please 提交回退）→ 5–6 条执行摘要 → 双语 Markdown 模板 + 空数据兜底 → 跨平台剪贴板复制。其中每个阈值（1000 additions、10 files、50% 重叠、3+ PR）都是显式可调的参数，意味着把该 SKILL.md 拷入其他项目后，只需按团队偏好调整阈值即可复用。对 rtk 仓库本身而言，它与 stale 机器人、release-please 流水线、next-release 自动更新共同构成了"机器做采集与分诊、人做决策"的维护自动化闭环。