GitNexus PR Swarm Review 深度解析：事实收集角色"PR Facts Historian"子代理的设计与实践

本篇技术指南围绕 GitNexus 仓库中的 Claude Code 子代理定义文件 gitnexus-pr-facts-historian.md 展开，讲清楚它在七角色 PR 审查蜂群（PR Swarm Review）中担任的"事实与历史调查员"职责。读完后，你将掌握：该子代理的 frontmatter 配置与"薄包装 + 规范 persona"分层设计、它必须收集的 PR 事实清单、GitHub CLI（gh）取证命令的完整用法、仓库历史搜索方法论、九段式强制输出结构，以及它如何为后续风险、测试、安全等审查 lane 提供证据基线。

1. 这个文件是什么：Claude Code 子代理的"薄包装"设计

.claude/agents/gitnexus-pr-facts-historian.md 是 GitNexus 跨 CLI PR 审查体系在 Claude Code 下的入口适配器。它的整体篇幅很短，核心思想是：角色逻辑不写在适配器里，而是集中在一份 CLI 中立的规范文件中。文件正文只做了三件事：

1. 声明完整操作规范位于规范 persona 文件 01-pr-facts-historian.md，要求子代理"用 Read 工具立即读取该文件并严格遵循"；
2. 声明编排契约（lane 顺序、Swarm 与 Solo 执行模式、输出结构）位于 orchestration.md；
3. 复述一组"始终强制"的规则（只读约束与 Bash 白名单）。

文件头部是标准的 Claude Code agent frontmatter，这是该适配器唯一"本地化"的部分：

---
name: gitnexus-pr-facts-historian
description: "GitNexus PR facts and repository-history investigator. Use to gather PR identity, visible GitHub state, changed files, commits, linked issues, related PRs, historical fixes, regressions, stale follow-ups, and missing visibility."
tools:
  - Read
  - Grep
  - Glob
  - Bash
model: claude-sonnet-4-6
maxTurns: 40
---

各字段的含义：

• tools：工具面被收敛到 Read/Grep/Glob/Bash 四项——恰好覆盖"读文件、搜代码、跑只读命令"三类调查动作，与规范 persona 的"只读"定位一一对应。
• model: claude-sonnet-4-6：模型档位选择与规范 persona 头部的标注一致——该 lane 推荐 sonnet 档。因为事实收集需要跨文件、跨 commit 的归纳推理能力；作为对比，仓库中偏机械校验的 lane（如 gitnexus-test-ci-verifier.md）则运行在 Haiku 档。README-gitnexus-reviewer-swarm.md 中对此的概括是："机械校验 lane 用 Haiku，分析型 lane 用 Sonnet"。
• maxTurns: 40：为子代理设置的最大轮次上限。事实收集是七个 lane 中调查面最宽的（PR 元数据 + diff + CI + 关联 issue + 仓库历史），因此轮次预算高于机械校验类 lane（如 35 轮的 gitnexus-security-boundary-reviewer.md）。

这种"薄包装"设计的收益在 pr-swarm-review/README.md 中写得很明确：所有审查逻辑只存在于 pr-swarm-review/ 下，各 CLI 入口（Claude Code、Gemini CLI、Copilot、Cursor、Codex）都是运行时读取同一批规范文件的薄适配器；修改审查行为只需改规范文件，"永远不要在 per-CLI 包装器里改"。规范 persona 文件顶部的 HTML 注释也重复了这一点："Edit this file, not the per-CLI wrappers (.claude/agents, .gemini, .github, .cursor)"。

2. 角色定位：Lane 1 事实与历史调查员

规范 persona 01-pr-facts-historian.md 对角色的定义只有一句话，但信息量很大：

You are a facts-gathering investigator for GitNexus pull request reviews. Your job is to collect visible PR facts and repository history before any risk claims are made by other agents.

即：你是 PR 审查中的"事实收集调查员"，职责是在其他任何代理做出风险判断之前，把可见的 PR 事实与仓库历史收集齐。这一定位带来三个设计特征：

1. 依赖图为零：在 orchestration.md 的 lane 依赖表中，Lane 1 的 "Depends on" 为 —（无依赖），因此它总是最先执行；
2. 输出是下游的输入：Lane 2（分支卫生）、Lane 3（风险架构师）、Lane 4（测试/CI 验证）都声明依赖 Lane 1 的产出——风险结论必须建立在事实基线之上，而不是建立在假设之上；
3. 只报告、不裁决：它不做 production-ready 之类的最终判定，那是 Lane 7 综合批判者的职责。

2.1 四条铁律（Rules）

规范 persona 为角色设定了四条不可违反的规则，Claude Code 适配器在"Rules (always enforced)"一节逐字复述：

• 不编辑文件。你是只读的（review, never mutate）。
• Bash 也是只读的。白名单与黑名单见下文第 5 节。
• 永不编造事实。在适当处使用 "visible state shows"（可见状态显示）、"appears to"（看起来）、"verify directly"（直接核实）这类措辞。
• 缺失数据必须转化为强制验证任务，而不是假设（"Missing data must become mandatory verification tasks, not assumptions"）。

第四条是整个 swarm 的证据观基石，与 orchestration.md 的 Visibility disclaimer 机制联动：当可见性不完整时，最终审查必须原样附上一句声明——"Current visible state is incomplete. I could verify A, B, and C, but not X, Y, and Z..."，把缺失项显式降级为"待验证点"而非"确认事实"。Lane 1 的输出第 8、9 节（Visibility gaps、Mandatory verification points）正是为这个机制供料。

3. 事实收集清单：What to Gather

规范 persona 的 "What to Gather" 一节列出了一份完整的取证清单，覆盖 PR 的元数据、变更、状态与历史四个维度。完整继承如下：

• PR 标题、状态、draft/WIP 标记（title, state, draft/WIP status）
• base 与 head 分支（Base and head branches）
• 可合并性与 merge state 状态（若可见）（Mergeability and merge state status）
• Head SHA（若可见）
• PR 内的提交列表（Commits in the PR）
• 变更文件（文件名与 diff）（Changed files, names and diff）
• CI 检查与状态（CI checks and status）
• GitHub 或机器人发出的警告（Warnings from GitHub or bots）
• 审查评论与机器人评论（Review comments and bot comments）
• 关联 issue 与 closing 引用（Linked issues and closing issue references）
• 相关 PR、提交与 release notes
• 邻近仓库历史（针对同一文件或符号的近期变更）（Nearby repository history: recent changes to the same files or symbols）

从清单结构看，它恰好对应输出结构中前 5 节的取材范围（PR identity / Visible GitHub state / Changed files / Commits and checks / Linked issues），第 11、12 项（相关 PR 与邻近历史）则对应第 6 节（Repository history found）。值得注意的是清单中多处出现 "if visible" 的限定语——这呼应了铁律第 4 条：凡不可见，一律如实报告缺失，而不是去猜。

4. GitHub CLI 取证命令

规范 persona 给出的首选取证工具是 GitHub CLI（gh），并给出了可直接复制的命令集：

gh pr view <PR> --json title,state,isDraft,baseRefName,headRefName,headRefOid,mergeable,mergeStateStatus,commits,files,reviews,comments,checks,statusCheckRollup,closingIssuesReferences
gh pr diff <PR> --name-only
gh pr diff <PR>
gh issue view <issue>
gh pr list --search "<term> repo:abhigyanpatwari/GitNexus"

逐条说明各命令对应清单中的哪类事实：

命令	采集事实	对应输出节
gh pr view <PR> --json ...	一条命令拉全 PR 元数据：标题、状态、草稿标记、base/head 分支、head OID、mergeable、mergeStateStatus、提交、变更文件、审查、评论、CI 检查与状态汇总（statusCheckRollup）、closing issue 引用	PR identity、Visible GitHub state、Changed files、Commits and checks、Linked issues
gh pr diff <PR> --name-only	仅列出变更文件清单，用于快速建立"哪些文件被碰过"的索引	Changed files
gh pr diff <PR>	完整 diff，用于提取符号名、错误消息等后续历史搜索词	Changed files / 历史搜索取材
gh issue view <issue>	关联 issue 的问题陈述（problem statement），提取其中的报错信息、堆栈作为搜索词	Linked issues and problem context
gh pr list --search "<term> repo:..."	在仓库内按关键词检索历史 PR，定位相关 PR 与历史修复	Repository history found

persona 对 --json 字段列表的取舍值得注意：它特意包含 mergeable 与 mergeStateStatus（供 Lane 2 的 merge-state 分类使用）、statusCheckRollup（CI 结果汇总）、closingIssuesReferences（closing 引用）。这些字段正是下游 lane 的硬依赖，而 Lane 1 一次性取齐后，后续 lane 无需重复拉取。

降级路径：若 gh 不可用或未认证，persona 明确要求改用本地 git 状态（git log、git diff、git show 等），并且"清楚地报告可见性缺失"（clearly report the missing visibility）——这直接落位到输出结构第 8 节 Visibility gaps。

5. 只读 Bash 契约：白名单与黑名单

这是该子代理安全边界的核心，.claude/agents/gitnexus-pr-facts-historian.md 与规范 persona 双处定义、双处强制：

允许的命令（Permitted）：

• 本地 git 只读命令：git log、git diff、git show、git grep、git ls-files
• GitHub 只读命令：gh pr view、gh pr diff、gh pr checks、gh issue view
• 检视工具：grep、cat、find、ls

禁止的命令（Prohibited）：

• 任何写文件的命令
• 任何修改 git 状态的命令（git commit、git add、git checkout -- <path>）
• 任何向 GitHub 发帖的命令（gh pr comment、gh pr review、gh issue comment）
• 安装依赖包、运行任意脚本

这套白名单让"Bash 只读"从一句口号变成了可审计的枚举清单：审查代理既能跑 git log 追历史，又没有任何途径在调查过程中污染工作区或影响 GitHub 上的 PR 状态。pr-swarm-review/README.md 将这一属性列为 swarm 的关键性质之一："每个 persona 都强制一份显式的 Bash 允许/禁止清单"。

6. 仓库历史搜索方法论

"邻近仓库历史"是 Lane 1 最有价值的产出之一：在 PR 改动发生之前，这些文件与符号的演化轨迹里往往藏着历史修复、回归与遗留跟进项。规范 persona 给出了八类应搜索的术语：

1. 变更的文件名与目录名
2. diff 中被修改的符号名（函数、类、类型）
3. 功能名与领域术语
4. 关联 issue 中提到的错误消息与堆栈
5. 提交或评论中引用的 issue/PR 编号
6. 分支名
7. 测试名与测试文件名
8. 文档术语

结合第 4 节的命令，实际操作链是：先用 gh pr diff <PR> 提取第 1、2、7 类词，用 gh issue view <issue> 提取第 4、5 类词，再交给 git grep / gh pr list --search / git log 做全仓库扫描，最后把命中结果归纳为"相关 PR、历史修复、回归、陈旧的跟进项"（对应 description 中的 historical fixes, regressions, stale follow-ups）。所有实际使用过的搜索词必须在输出第 7 节 "Search terms used" 中登记——搜了什么、在哪搜的，让历史搜索本身也成为可复查的证据。

7. 九段式强制输出结构

Lane 1 的输出不是自由文本，而是固定九节的结构化报告。任何下游 lane 都可以按节号定位信息：

1. PR identity — 标题、编号、作者、base/head 分支
2. Visible GitHub state — 状态、草稿标记、可合并性、merge state 状态、head SHA
3. Changed files — 变更文件列表及修改摘要
4. Commits and checks — 提交列表、CI 检查结果、状态汇总
5. Linked issues and problem context — closing issue、被引用 issue、问题陈述
6. Repository history found — 同文件的近期变更、相关 PR、历史修复、回归
7. Search terms used — 搜索过哪些词、在哪些位置搜的
8. Visibility gaps — 哪些信息无法确定、为什么
9. Mandatory verification points for other agents — 其他代理在依赖这些事实之前必须独立核实的事项

第 8、9 两节是整个 swarm "缺失可见性转化为验证工作"哲学的落地装置：第 8 节记录盲区，第 9 节把盲区升级为带责任人的行动项。orchestration.md 要求最终审查必须包含 "Back-and-forth avoided by verifying"（通过直接核实而避免的来回拉扯）与 "Open questions" 两节，其素材源头正是这里的第 8、9 节。

8. 编排位置：在七 lane 管线中如何流转

orchestration.md 定义了完整的 lane 依赖表，Lane 1 的位置是"起点"：

Lane	Persona	职责	依赖
1	01-pr-facts-historian.md	PR 身份、可见状态、变更文件、关联 issue、相关 PR/提交、仓库历史、可见性缺口	—
2	02-branch-hygiene-reviewer.md	Merge-state + 分支卫生分类	1
3	03-risk-architect.md	生产故障模式、领域特定阻塞项	1, 2
4	04-test-ci-verifier.md	测试覆盖、CI 接线、验证缺口	1
5	05-security-boundary-reviewer.md	信任边界、密钥、注入、权限、隐藏 Unicode	1
6	06-docs-dod-reviewer.md	PR 专属 Definition of Done、文档/release note 义务	1
7	07-synthesis-critic.md	在发布前批判草稿审查	1–6 + 草稿

执行顺序为：Lane 1–2 先行（其输出喂给其余 lane），Lane 3–6 在 1–2 完成后并行，Lane 7 最后基于草稿运行。编排契约定义了两种执行模式且输出契约完全一致：

• Swarm 模式（具备并行子代理的运行时，如 Claude Code）：每个 lane 派发为独立子代理（即七个 .claude/agents/gitnexus-*.md 文件）；
• Solo 模式（Codex、Gemini CLI、Cursor、Copilot 等单代理运行时）：一个代理按依赖顺序依次"扮演"每个 persona，读取对应的 pr-swarm-review/personas/0N-*.md 完成该 lane 的调查，并把所有 lane 的发现保持在上下文中供 Lane 7 自批判。

Lane 1 的产出不直接出现在最终审查里，而是通过两条通道注入：一是为 Lane 2 的 merge-state 分类（mergeable / blocked by conflicts / checks failing 等九选一）提供原始证据；二是在最终审查的 "Current PR state"、"Repository history considered"、"Open questions" 等固定小节中作为已核实事实被引用。

9. 如何运行这套审查

该 swarm 是手动触发的（无 hook、无自动触发器），入口由 pr-swarm-review/README.md 统一登记：

CLI	调用方式	适配器
Claude Code	/gitnexus-pr-swarm-review <PR>（Swarm 模式，派发七个 gitnexus-* 子代理）	SKILL.md + .claude/agents/gitnexus-*.md
Gemini CLI	/gitnexus-pr-swarm-review <PR>	.gemini/commands/gitnexus-pr-swarm-review.toml
GitHub Copilot	/gitnexus-pr-swarm-review（随后粘贴 PR）	.github/prompts/gitnexus-pr-swarm-review.prompt.md
Cursor	/gitnexus-pr-swarm-review（随后粘贴 PR）	.cursor/commands/gitnexus-pr-swarm-review.md
Codex CLI / 任意 AGENTS.md 代理	请其"按 pr-swarm-review/orchestration.md 对 执行"	AGENTS.md § PR Swarm Review

以 Claude Code 为例，协调器 skill gitnexus-pr-swarm-review/SKILL.md 被 /gitnexus-pr-swarm-review <PR URL or PR number> 触发后，读取 orchestration.md 并派发子代理——Lane 1 对应的就是本文主角 gitnexus-pr-facts-historian.md。注意 AGENTS.md 的提醒：在 .claude/agents/ 下新增或修改代理文件后，需重启 Claude Code 才能重新加载代理定义。

另外，这套交互式 swarm 与仓库中另一个 gitnexus-review skill 并存且分工不同：后者是基于 GitNexus 知识图谱的审查（PR、分支、区间或本地变更，使用 MCP 图查询工具），其 ci-personas/ lane 由 CI 审查代理在单次工作流内自动派发；而 /gitnexus-pr-swarm-review 是按需手动触发的固定七角色 production-readiness 深度审查。两者都运行审查蜂群，区别在"运行器"而非"角色名册"（见 README-gitnexus-reviewer-swarm.md）。

10. 设计要点总结

从这一份不到 25 行的适配器文件和它背后的规范 persona 中，可以提炼出 GitNexus PR 审查体系的几个值得借鉴的工程决策：

1. 单一事实源 + 薄适配器：角色规范（职责、清单、命令、输出结构）集中在 pr-swarm-review/personas/ 与 orchestration.md，每个 CLI 的适配文件只做"读取规范文件 + 声明本 CLI 特有的 frontmatter"。跨五个 CLI 的行为一致性由文件结构保证，而非靠人肉同步。
2. 先事实、后风险：通过依赖图强制"风险声明必须晚于事实收集"，Lane 1 无依赖且阻塞后续 lane，从编排层面杜绝了"先下结论再找证据"的审查反模式。
3. 可见性缺口的一等公民化：if visible 措辞、Visibility gaps 节、Mandatory verification points 节、orchestration 层的声明句式，构成了一条从 persona 到最终输出的完整机制链——缺失数据永远变成待办验证项，绝不变成假设。
4. 只读契约可枚举、可审计：Bash 白名单/黑名单逐条列出，"只读"不是信任声明而是命令枚举；工具面（Read/Grep/Glob/Bash）与之一致，任何写操作在两个层面都被排除。
5. 输出契约与执行模式解耦：Swarm 与 Solo 两种模式产出同构的九节报告，使"用哪个 CLI 跑"不影响审查结果的可比较性与可引用性。

如需进一步深入，建议按序阅读：pr-swarm-review/README.md（体系总览）→ pr-swarm-review/orchestration.md（编排契约与最终审查结构）→ 其余六个 persona 文件（各 lane 完整规范）→ DoD.md（Lane 6 与最终 "Review bar" 所依据的仓库级完成标准）。