Archon 交付工作流中的评审范围分类：classify-review-scope 命令深度解析

Archon 交付工作流中的评审范围分类：classify-review-scope 命令深度解析

【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon

导读

在 Archon 的 SDLC（软件开发生命周期）交付工作流中，classify-review-scope是一个决定"这份 PR 值不值得开启可选评审透镜"的 AI 命令节点：它不评审代码，只从刚打开的 PR 本身判断errors（静默失败）与docs（文档影响）两个可选透镜是否应该被激活，并以结构化 JSON 输出唯一被下游读取的判定结论。读完本文，你将理解该命令的职责边界、每个可选透镜的狩猎目标、基于 PR 而非工作项的证据校准原则、以及它在 archon-deliver.yaml 中与resolve-review-scope、archon-review之间的完整协作链路。

命令定位：只分类，不评审

classify-review-scope.md（位于 .archon/workflows/sdlc/deliver/commands/classify-review-scope.md）开篇就划定了这条命令的边界：它决定"刚打开的 PR 是否值得开启任一可选评审透镜"，而不是替代评审本身。

在完整评审（full review）中，code、seams、simplify、tests 四个透镜每次都会运行，只有errors和docs是需要人为（或分类器）选择的可选透镜。该命令运行在无人旁观的场景下——"No one watches this run; your structured verdict is the only thing downstream nodes read"，即它的结构化判定是下游节点唯一依赖的输入，因此判定必须建立在证据之上，而非猜测。

关键的行为约束有三点：

1. 证据锚定在 PR 本身，而非工作项：需要读取当前分支的 PR 描述（description）和完整 diff（ghCLI 可用，该分支的 PR 由更早的节点打开），判断改动里"实际有什么"；
2. 不得修改任何文件：这是一个只读的判定节点；
3. 判定必须来自所见的 diff：不从工作流名称或 issue 主题推断范围。

两个可选透镜分别猎取什么

原文档对每个透镜给出了一句话式的狩猎定义，这一定义与其下游透镜命令（review-errors.md、review-docs.md）的 charter 严格对齐：

透镜	分类器眼中的目标	下游透镜的完整 charter
errors	被静默化的失败路径：新的 catch / fallback / retry / 默认值代码、错误翻译、恢复行为，以及任何"失败变得与成功无法区分"的地方	"一个真实失败穿过被改动的代码，对必须反应的调用方、操作者或用户变得与成功无法区分"
docs	diff 改变的已发布文档（shipped documentation）	"改动之后，有人按仓库文档操作会形成实质错误的预期，或缺少某个必要步骤"

从源码结构看，errors透镜的狩猎重点是失败身份的消失（suppression point），docs透镜的狩猎重点是文档与代码事实的漂移。分类器的任务不是深入分析这些缺陷，而是判断"这类缺陷是否可能存在于这个 diff 中"——它回答的是"要不要派专门透镜去查"。

校准原则：成本不是约束，浪费的注意力才是

原文档给出了整个命令最核心的设计哲学：

"Cost is not the constraint; wasted attention is."

评审成本不是约束，浪费的注意力才是。据此给出的校准规则分为两端：

• 小而不值得：一个小型、机械、很可能正确的 diff——版本号提升、单行修复、重命名、纯测试调整——通常两个可选透镜都不需要；
• 大而值得：一个实质性或高风险的 diff，其失败类别"合理地存在于其中"时，每个透镜各按其失败类别选择——diff 中确实包含新的失败路径就选errors；改动已发布文档就选docs；
• 两端都不过度：不为真实风险节省（do not economize on real risk），也不为风险的缺席凭空制造范围（do not manufacture scope for its absence）。

每个透镜的判定测试完全相同："这个 diff 是否包含其失败类别可能栖身的实质内容？"并且必须从亲眼所见的 diff 判断，而不是从工作流名称或 issue 主题推断——这条约束直接呼应了命令开篇"Ground the decision in the PR itself, not the work item"的指令。

值得注意的是，review-scope命令（.archon/workflows/sdlc/review/commands/review-scope.md）在docs自动选择上复用了同一套校准：即使 diff 触及文档，如果它是"小型、机械、很可能正确"的改动（版本号、单行修复、重命名、纯测试调整），文档邻近的一笔改动也不足以赚取该透镜。

声明格式：每个回合都必须输出的结构化判定

命令要求每个回合（every turn）声明一次，输出格式严格结构化：

• errors、docs—— 两个布尔值，每个可选透镜一个；
• reasons—— 一个对象，{errors, docs}，每个透镜一句话，引用 diff 中决定该判定的证据：判false时说明 diff 缺少什么，判true时说明 diff 包含什么。

reasons不是装饰：它让下游（以及未来的续跑）能追踪判定的证据链，避免"无理由的开关"。

结构上还有一个重要的优先级规则：操作者（operator）显式声明的errors设置会覆盖该判定；auto才采纳分类器的判断。这一规则在 deliver 工作流中被实现为一个独立的确定性脚本节点（见下节）。

源码级实现：classify → resolve-scope → review 的协作链路

classify 节点：小型模型的二元判定

在 archon-deliver.yaml 中，classify节点定义如下（约第 92–111 行）：

- id: classify command: classify-review-scope model: small depends_on: [pr] mutates_checkout: false output_type: review-scope output_format: type: object properties: errors: { type: boolean } docs: { type: boolean } reasons: type: object properties: errors: { type: string } docs: { type: string } required: [errors, docs] required: [errors, docs, reasons]

几个关键实现事实：

• 模型分级为small：工作流注释明确说明，由于工作流顶层不声明模型，"从 diff 中选择两个布尔值是小规模工作"，因此分配小模型以节省成本——这与文档"成本不是约束"的表述相互印证：这里省的是推理规模，而不是评审覆盖；
• mutates_checkout: false：与命令文档"不修改任何文件"的约束一致；
• depends_on: [pr]：分类必须发生在 PR 节点之后，因为"diff 是 PR 存在之前不存在的信息"——工作流注释直言：评审范围必须从实际 PR 判定，而不是在启动时盲目声明（"the diff is information that does not exist until the PR does"）；
• 结构化输出校验：output_format强制errors/docs为布尔、reasons为双字符串对象，任一缺失都会使节点失败而非悄悄通过。

resolve-scope 节点：操作者覆盖的确定性边界

分类器的判断不直接控制errors透镜——中间隔着 resolve-review-scope.py：

def resolve(forced: str, judged: str, lens: str) -> str: if forced in ("true", "false"): return forced if judged not in ("true", "false"): print(f"resolve-review-scope: classifier returned an invalid {lens} verdict: {judged!r}", ...) raise SystemExit(1) return judged

其逻辑完全对应命令文档的优先级规则：

• 操作者通过errors输入传入true/false时，强制值直接胜出（forced 优先）；
• 操作者传auto（默认值）时，采纳分类器对errors的判定（judged）；
• 分类器若返回非布尔值，脚本报错退出——错误的判定宁可让节点失败，也不能污染下游的评审门控。

在archon-deliver.yaml中，resolve-scope的with只接收$classify.output.errors（c_errors），输出字符串形式的{"errors":"true"/"false"}，随后作为review节点的errors输入。工作流注释对此的总结是："确定性合并发生在边界：显式的 true/false 胜过分类器，auto 采纳其判断。"

review 节点：透镜门控与 docs 的双通道

errors与docs的生效路径在 archon-review.yaml 中被分开处理：

• errors 透镜门控条件为$INPUTS.errors == 'true'——即resolve-scope合并后的值；
• docs 透镜门控条件为$INPUTS.docs == 'true' || ($INPUTS.docs == 'auto' && $scope.output.docs == true)——docs输入默认是auto，此时由review-scope命令从 diff 自动选择，而deliver工作流把docs绑定为$classify.output.docs，即分类器的原始判定（不经 resolve 覆盖），与errors形成对称的双通道：errors 走"分类器 + 操作者覆盖"通道，docs 走"分类器直通"通道。

classify的输出docs因此成为 docs 透镜门的唯一开关——这也解释了为什么命令文档强调reasons中必须引用 diff 证据：docs: true意味着下游会额外启动一个只读评审透镜。

续跑（continuation）模式下透镜如何被消费

archon-review的续跑模式（存在prior_report时）由 resolve-review-mode.py 决定，此时只用一个续跑评审者核验先前 findings 并评审修正增量，跳过所有 specialist 透镜——archon-deliver.yaml的 recheck 节点注释明确写道："Continuation mode owns coverage and skips every specialist, regardless of these conditional-lens bindings." 也就是说，分类器判定的可选透镜只作用于首轮完整评审；修正轮次不再重新 fan-out。

测试与验证：fixture 如何守护分类器绑定

SDLC 包遵循 .archon/workflows/sdlc/README.md 的守卫原则——"如果该包的 fixture 套件无法演练这个守卫，它就不是守卫，而是注释"。分类器绑定由 dry-run fixture 守护：

selective-review.stubs.yaml 展示了分类器选择docs、errors判定被 resolve 合并的场景：

classify: errors: false docs: true reasons: errors: "stub: no failure paths" docs: "stub: changed shipped docs need impact review" resolve-scope: '{"errors":"false"}' ... fixture: expect: completed reached: [review__code, review__seams, review__simplify, review__tests, review__docs]

关键验证点：

• 分类器输出errors: false、docs: true时，resolve-scope将errors合并为"false"，而docs保持true直通；
• fixture 的reached断言列出了最终运行的透镜集合：四个默认透镜全部运行，加上被分类器选中的review__docs，而errors透镜（review__errors）未在列表中——证实了分类器判定直接控制透镜是否实际执行；
• fixture 注释说明"loader test protects the classifier-binding seam itself"，即绑定接缝本身另有专门的 loader 测试覆盖。

配套的其他 fixture（如 red-introduced.stubs.yaml）则验证了相反方向的守卫：当实现引入的红（introduced red）出现时，gate-green脚本被刻意保持未 stub，真实脚本必须拒绝——这类守卫与分类无关，但共同构成了 deliver 尾部"门控必须可被 fixture 演练"的工程纪律。

设计要点回顾与最佳实践

综合命令文档与实现源码，classify-review-scope沉淀出的可复用设计原则值得单列：

1. 分类与评审解耦：分类器只做二元判定并附带一句话证据（reasons），把"查证"留给专业透镜，避免小模型承担超出规模的评审工作；
2. 证据时效性：范围必须等 PR 存在后才能判定（depends_on: [pr]），"diff 是 PR 打开前不存在的信息"——任何提前声明范围的做法都会引入猜测；
3. 人机优先级清晰：操作者的显式true/false在任何时候都覆盖分类器，auto才采纳分类器；覆盖发生在确定性脚本边界（resolve-review-scope），而不是靠提示词约束；
4. 假阳性与假阴性同样不可取：不为真实风险节省（diff 含失败路径就选 errors），也不为缺席的风险制造范围（机械性小改动不配透镜）；
5. 不可观察的判定必须结构化：无人旁观的运行中，只有结构化的布尔 + reasons 对象是下游可消费的契约，缺失字段会让节点失败而非静默通过。

在 Archon 的 SDLC 包中，classify-review-scope是一个典型的"低成本决策节点"：用一个小模型 + 结构化输出 + 确定性边界脚本，把"这个 diff 值不值得多开两个评审透镜"这件原本需要人工判断的事，变成了一条可测试、可覆盖、可续跑的自动链路。

【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon