Slang 项目文档锚定测试束的 Agent 审阅流程：_review.md审阅提示词深度解析
【免费下载链接】slangMaking it easier to work with shaders项目地址: https://gitcode.com/GitHub_Trending/sl/slang
本篇技术指南围绕 Slang（shader-slang）仓库中docs/generated/tests智能体化测试套件的审阅环节展开，核心文献为 docs/generated/tests/_meta/prompts/_review.md。该提示词定义了一个由"非生成方模型家族"执行的测试束审阅契约：逐条核验测试是否真正锚定文档声明、CHECK 断言是否稳健、元数据是否合规，并产出结构化的审阅报告。读完本文，你将掌握 Slang 项目中"文档声明 → 测试生成 → 交叉审阅 → 修复与反馈"全链路的运作方式，以及审阅报告 YAML 格式、严重度分级与 FileCheck 模式卫生学（pattern hygiene）的具体实践。
一、背景：Slang 仓库中的智能体化测试套件
Slang 编译器仓库（项目主页见 README.md，定位为 "Making it easier to work with shaders"）在 docs/generated/tests/ 下维护了一套**文档锚定（doc-anchored）**的智能体化测试套件。其核心思想是：每一个测试都必须追溯到某一条文档声明，而不是为了"打中某一行源码"而编写。
根据 docs/generated/tests/_meta/PIPELINE.md 的说明，测试套件由两棵并行目录树构成，各自承担不同职责：
| 测试树 | 锚定的文档 | 角色 |
|---|---|---|
docs/generated/tests/conformance/ | docs/language-reference/（人工编写的规范） | 规范符合性：测试失败即"规范 vs 编译器"漂移信号 |
docs/generated/tests/design/<area>/ | docs/generated/design/（LLM 反推的设计文档） | 回归覆盖：测试失败即已知行为的回归 |
两棵树被刻意允许在同一编译器表面上重叠——它们验证的是不同性质（规范符合性 vs 行为回归）。当conformance/测试失败而对应的design/测试通过时，这正是套件设计要暴露的"规范与编译器漂移"信号。
每个测试束（bundle）由 docs/generated/tests/_meta/manifest.yaml 登记，包含source_doc（声明来源文档）、watched_paths（变更会使束失效的编译器源码）、depends_on与coverage_targets等元信息。束内的每个.slang测试文件必须以//META块开头，声明doc_ref（指向真实锚点）、purpose、intent、doc_section_digest等字段。
二、审阅环节在流水线中的定位
整个流水线（生成 → 审阅 → 修复 → 反馈）由 docs/generated/tests/_meta/CAMPAIGN.md 编排。审阅是其中承上启下的关键关卡：
生成（另一模型家族）→ 审阅（本提示词，不同模型家族）→ 修复（remediate）→ lint/verify → CI 夜间回归_review.md开篇的拒绝横幅（Refusal banner）揭示了本环节最独特的机制：如果执行者自我识别为 Claude / Anthropic 模型，必须输出REFUSED: Claude model detected; the review step requires a different model family并停止。审阅环节刻意由与生成束不同的模型家族执行，目的是让"幻觉与契约违背"能被具有不同盲区的模型捕获——生成者与审阅者同族会产生系统性盲区，交叉验证才能形成有效的质量闸门。
与之对称，修复环节的提示词 docs/generated/tests/_meta/prompts/_remediate.md 则要求执行者必须是生成束的同一模型家族（Claude/Anthropic），因为修复动作（改写测试以匹配引用的声明、调整元数据）与原始生成时对提示词的解释紧密耦合。
审阅者的输入包括：束的README.md与全部.slang文件、束的source_doc、分节提示词与 docs/generated/tests/_meta/prompts/_common.md、以及束记录的source_commit处已解析的受监视源码（仅用于核验，不得用于寻找新测试思路）。输出则是一份报告，落在docs/generated/tests/_meta/reviews/<bundle-key>.review.md。
三、审阅契约：逐测试检查（The Contract）
审阅者对照一份九条契约逐测试核验。这些条目从"测试是否真在验证文档声明"到"断言是否稳健"层层递进：
1. 文档锚定（Doc-anchored）
检查//META: doc_ref是否解析到source_doc中的真实锚点，且被引用章节的文本是否确实包含该测试要验证的声明。这一条直接对应 docs/generated/tests/_meta/prompts/_common.md 中"最重要的规则"：每个测试必须锚定到文档声明，doc_ref是形如docs/language-reference/expressions-literal.md#integer-literal-expressions的单一path#anchor。锚点必须按 GitHub 的规则从标题推导（小写、删除标点、空格转连字符），例如标题### MemberExpr / StaticMemberExpr的锚点是#memberexpr--staticmemberexpr（双连字符）。
2. 声明得到验证（Claim verified）
检查测试的purpose是否复述了被引用章节，且测试主体实际验证了purpose声称的内容。这堵住了"目的写得好、断言却测了别的东西"的伪测试。
3. 非源码定向（Not source-targeted）
检查测试是为了验证文档化声明而写，还是为了打中slangc的特定行/分支而写——后者必须标记。束内不得包含任何源码定向测试。这与 docs/generated/tests/_meta/prompts/_expand.md 的"硬性规则"一致：展开束时操作者不得提供任何未覆盖源码行信息，测试永远只能源于文档。
4. 可编译性（Compiles）
检查指令行语法是否合法、着色器主体在声明目标下是否应该能通过slangc编译。注意审阅者实际不运行slangc——这是纯阅读式审阅（reading review），由后续的regenerate.py verify承担真实执行。
4b. CHECK 模式稳健性（CHECK patterns are robust）
这是审阅中最容易发现问题、也是最常导致"过 lint 却在 FileCheck 下失败"的环节，参照_common.md的 "FileCheck / CHECK pattern hygiene" 一节，需标记以下六类问题：
- 钉死了生成式 ID/名字：字面量
%29、_S3、main_0，或对操作数使用纯数字捕获%{{[0-9]+}}。SPIR-V 反汇编在部分运行模式使用友好名（%f_0），在另一些模式使用数字——钉死其中一种形式会在另一种模式下失败。正确写法是%{{[A-Za-z0-9_]+}}。 - 未转义的
[[...]]或{{字面量：Metal/HLSL 属性会原样发射[[...]]，而 FileCheck 把[[...]]当作变量引用、把{{...}}当作正则。必须写成{{\[\[}}unroll{{\]\]}}。 - 短而未锚定的 CHECK/CHECK-NOT 成为真实 token 的子串：
OpFunction会命中OpFunctionEnd，StructuredBuffer会命中RWStructuredBuffer——应使用最具体的 token 并用{{^}}锚定。 - 顺序 CHECK 假设了错误的发射顺序：被调者先于入口点发射、IR 转储按 pass 自上而下——不确定顺序时应改用
CHECK-DAG。 - 依赖优化的断言：slang-test 默认
-O0，若声明是"助手被内联/调用消失"，指令上必须加-O1，否则应断言未优化的形态。 - 钉死了声明并不依赖的 token：典型是紧邻被测对象的声明限定符（
__device__、__noinline__、inline、static）或声明从未提及的 decoration。判断标准：如果该 token 变了，锚定的声明会变假吗？不会——就应通配或省略（规则 8）。 - 在目标不支持的特性上做断言：如
String在cpp（kernel）目标上不可用（发射 E55213）却在host-cpp上可用。目标无法表达声明时，应写负向/诊断指令钉住诊断，或记入## Untested claims，绝不可放宽 CHECK 来凑绿。 - DIAGNOSTIC_TEST 问题：编造消息字符串、错位 caret、
non-exhaustive使用错误（所有诊断都已标注时出现、或仍有次要 note 未标注时缺失）。
5. 意图分类正确（Intent classified correctly）
functional（主声明）、expansion（重读文档派生的边角情况）、negative（诊断/失败测试）、regression（仅当引用了已修复的问题）。分类错误即视为问题。
6. 无重复（No duplicates）
同一束内两个测试不应以相同形态锻炼同一锚点。
四、束级检查（For the bundle as a whole）
7. 前置元数据有效（Front-matter valid）
README.md与每个//META块中的每个必需键都必须存在。参照_common.md：束 README 必须以 YAML 前置块开头（generated: true、model、generated_at、source_commit、watched_paths_digest、source_doc、source_doc_digest、warning），正文固定四个章节（## Intent、## Functional coverage、## Untested claims、## Doc gaps observed）。
8. 覆盖表一致（Coverage table consistent）
束内每个.slang文件必须在## Functional coverage表的 Tests 列恰好出现一次；Claim 单元格必须与对应测试的//META: purpose=...逐字一致；Anchor 列匹配//META: doc_ref=...；Intent 列匹配//META: intent=...（混合意图的声明行用逗号分隔）。
9. 文档缺口已记录（Doc gaps recorded）
若文档存在束未覆盖的可见声明，生成方应将其记录为## Doc gaps observed表的行。审阅者需检查是否有未列出的未覆盖声明，并核对每行的Kind是否与描述吻合——例如"文档列出了 X 但未给出 Slang 表层"应归类为missing-surface而非undocumented-behavior。_common.md定义了完整的 Kind 受控词表（missing-example、missing-surface、undocumented-behavior、cascading-only-mention、ambiguous-claim、drift-from-source），该表是文档再生成的反馈通道。
五、审阅报告格式
审阅者将结果保存为docs/generated/tests/_meta/reviews/<bundle-key>.review.md，结构由 docs/generated/tests/_meta/schema/review-report.schema.json 约束。报告的 YAML 前置块字段如下：
| 字段 | 含义 |
|---|---|
review_report | 固定为true |
reviewer_model | 审阅者模型标识，不得包含 "claude" 或 "anthropic"（软性强制） |
reviewed_at | ISO 8601 UTC 时间戳 |
target_bundle | 束键 |
target_bundle_source_commit/watched_paths_digest/source_doc_digest | 从束 README 复制（分别要求 7–64 位十六进制、64 位十六进制） |
source_commit | 审阅时的 git HEAD |
checklist | 六个检查项（doc_anchored、claims_verified、test_compiles、no_source_targeting、intent_classification、front_matter_validity），每项取值pass/partial/fail |
finding_count | 发现总数（整数，≥0） |
severity_breakdown | critical/major/minor/nit四个计数 |
正文的## Findings部分使用固定列的表格式：ID | Severity | File | Description | Evidence | Recommendation。每条发现附上证据（如source_doc lines 412–438 do not mention "specialized"）与可执行的建议（如 "Either change doc_ref to #generic-substitution, or remove the test."）。若没有任何发现，写作(no findings)并把finding_count与全部严重度设为 0。
六、严重度分级（Severity scale）
- critical——束不可安全使用：幻觉声明、摘要不匹配、测试永远不会通过。
- major——意图错误、doc_ref 断裂、源码定向测试。
- minor——重复覆盖、误导性的 purpose 文本。
- nit——命名、措辞、排序。
该分级与修复环节的响应动作直接挂钩：major及以上的发现通常要求fixed（改写或删除测试）；"文档从未作出该声明、但该测试应该测"属于rejected-out-of-scope，指向文档改进任务而非新增测试。
七、审阅者必须不做的事（What you must NOT do）
三条红线构成了"文档锚定审阅"的伦理边界：
- 不得编辑束。只有修复环节（下一阶段）可以修改测试文件。
- 不得提出需要读取未覆盖源码行号的建议。审阅是文档锚定的，不是源码锚定的——这与整个套件的"非源码定向"原则一脉相承。
- 不得虚构声明。文档没说的，就标记测试待移除，而不是为它编造引文。
这三条与 docs/generated/tests/_meta/prompts/_claims.md 的"声明驱动"方法论呼应：束的完备度以"每条枚举声明要么有测试、要么有分类原因"为准，测试数量是过程产出而非目标。
八、反馈闭环：审阅如何反哺文档与编译器
审阅报告并非终点。根据 PIPELINE.md 的说明，套件被设计为改善自身输入：
- 文档缺口 → 文档：
regenerate.py doc-gaps聚合所有束的## Doc gaps observed行，按锚定文档分组并生成gap_id，作为下一轮设计文档生成的输入。锚定在人工规范（docs/language-reference/）上的缺口则进入人工分诊队列，因为任何 Agent 都不得编辑该规范。 - 发现 → 编译器：分诊后的发现（docs/generated/tests/_meta/findings/ 下的结构化 YAML）被
regenerate.py findings file归档为追踪问题，修复后移除 docs/generated/tests/_meta/expected-failures.txt 中的对应条目。 - 漂移检测 → 再生成：
source_doc_digest与watched_paths_digest使束在文档或受监视源码变更时变"陈旧"（stale），regenerate.py list-stale列出、mark-fresh在再生成后清除标记。
审阅者的每一条major/minor发现，都会经由修复报告（docs/generated/tests/_meta/remediations/）转化为对束的编辑或对文档/提示词/清单的改进任务，从而持续收紧"文档声明 — 测试断言 — 编译器行为"三者之间的一致性。
九、实战要点速览
- 审阅目标是让束内每个测试同时满足"锚点真实、目的复述声明、断言验证目的、非源码定向、可编译、CHECK 稳健、意图正确、无重复"，让束整体满足"元数据有效、覆盖表一致、缺口已记录"。
- CHECK 模式稳健性是失败高发区，审阅时应优先核查：生成 ID 钉死、
[[...]]未转义、短 token 子串碰撞、顺序 CHECK 与发射顺序不符、无-O1的优化依赖断言、与声明无关的钉死 token。 - 审阅报告是机器可读的结构化文档（schema 见 review-report.schema.json），
checklist六项与finding_count/severity_breakdown是后续修复环节（_remediate.md）逐条回应的依据。 - 实际运行验证由
regenerate.py lint/verify完成（用法见 PIPELINE.md 的驱动命令参考表），审阅阶段只做静态阅读式核验；verify的三类结果passed/ignored/FAILED中，只有FAILED需要修复后才可提交。
【免费下载链接】slangMaking it easier to work with shaders项目地址: https://gitcode.com/GitHub_Trending/sl/slang
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
