Slang 生成式设计文档的评审与修复流程以 pipeline/06-emit.md 评审报告为例【免费下载链接】slangMaking it easier to work with shaders项目地址: https://gitcode.com/GitHub_Trending/sl/slangSlang 仓库的docs/generated/design/目录下有一整套由 LLM 生成、由人工/Agent 驱动的“生成—评审—修复”文档质量流水线。本文以 pipeline/06-emit.md 的评审报告 为具体样本完整解读一份评审报告的字段结构、四条发现项的证据链与修复方式并说明如何用regenerate.py复现同样的校验流程。读完本文你能理解这份“评审报告即数据”的文档质量机制以及它如何与 slang-emit.cpp 等编译器源码逐行对账。评审报告在生成式文档体系中的位置Slang 的设计文档不是纯手写而是“从源码反演”reverse-engineered from compiler source出来的每篇文档在 manifest.yaml 中注册一个条目指明它的生成提示词模板和一组watched_paths被监视的源文件集合。文档与其监视的源码共同构成“新鲜度”状态源码一旦变化文档就被标记为stale需要重新生成。围绕这个机制regenerate.md 描述的驱动脚本 regenerate.py 提供了一组子命令list-stale、digest、show、lint、mark-fresh、review-status、mark-reviewed、mark-remediated等把“文档—源码”的对账变成可重复的操作。在“生成并 lint 通过”之后还有两个质量环节评审review由一个 Agent 针对记录在案的source_commit重读目标文档及其依赖逐条核对事实性陈述、行号引用、相对链接和标识符是否真实存在产出形如本文样本的评审报告修复remediation由另一个 Agent 复核每条发现项判定“修复 / 驳回为无据 / 驳回为超范围 / 搁置 / 升级”并写出修复报告。两者分别把状态写入 review-state.json 与 freshness.json报告本身有 review-report.schema.json 与 remediation-report.schema.json 约束结构。本文样本对应的完整四元组是角色文件目标文档pipeline/06-emit.md讲解 Slang 代码发射阶段IR 如何变成 HLSL/GLSL/SPIR-V/Metal/WGSL/C/CUDA/LLVM IR/VM 字节码生成提示词prompts/pipeline-06-emit.md、prompts/_common.md评审报告reviews/pipeline/06-emit.md.review.md本文主角修复报告remediations/pipeline/06-emit.md.remediation.md目标文档的直接上游依赖是 pipeline/05-ir-passes.mdIR 通道manifest 中depends_on字段记录了这一点评审时也会把该依赖文档一并读入上下文。报告结构front matter 与检查清单评审报告是一份带 YAML front matter 的 Markdown 文档字段含义如下对照 报告原文review_report: true文档类型标记供 lint 与 schema 识别reviewer_model: gpt-5.6-sol执行评审的模型reviewed_at: 2026-08-04T12:07:1800:00评审时间戳target_doc: pipeline/06-emit.md被评审文档的 manifest 键target_doc_source_commit: 53b76e6d3009b8e6434d41573524c7ce5c499d23目标文档 front matter 中记录的生成时源码提交——评审是“针对该提交”的而不是针对评审时刻的 HEADtarget_doc_watched_paths_digest: 8de686...目标文档记录的监视路径摘要文档自带的“我基于哪批源码生成”的指纹source_commit: 53b76e6d...评审实际使用的源码提交checklist六个维度的结论本例为factual_accuracy: partial、cross_references: pass、completeness: pass、style_consistency: pass、source_alignment: partial、front_matter_validity: partialfinding_count: 4与severity_breakdown: {critical: 0, major: 1, minor: 3, nit: 0}发现项总量与严重度分布。正文部分依次为## Summary一句话定性页面大体准确但 front matter 摘要过期、有一处过时论断与 manifest 矛盾、两处概括过宽、## Items checked评审实际做过的校验工作、## Findings发现项表格每条含 ID、严重度、位置、描述、证据、修复建议、## No-issues notes确认无误的要点清单。这种结构让报告可以直接被机器消费regenerate.py mark-reviewed会把报告的元数据登记进 review-state.json后续review-status命令就能逐文档展示“评审是否仍然有效”。评审过程做了哪些校验Items checked报告的## Items checked一节是理解该评审深度上限的关键。评审 Agent 在记录的提交53b76e6d上完成了上下文齐备性读入目标文档、prompts/_common.md、单文档提示词、regenerate.py show pipeline/06-emit.md解析出的监视文件全集以及依赖文档 pipeline/05-ir-passes.md行号引用全量核验正文中 6 处带行号的引用共 9 个行号——slang-emit.cpp 的 970、2746、2993、3292、3500、3544、3587以及 slang-emit-hlsl-prelude.cpp 的 553、586——全部逐一验证事实性抽验跨外部派发、发射器选择、行号指令默认值、直接 SPIR-V 合法化与下游门槛、HLSL 符号化 flag、Metal 扩展追踪、WGSL switch 处理、类继承、VM 诊断、Slang 回环 stub、LLVM 输出形态、source map、依赖文件输出、prelude、优先级处理等主题抽验了 10 项以上的事实陈述链接与体积解析全部 58 个唯一相对链接目标在记录提交上全部可解析并确认文档 22,089 字节低于 manifest 规定的 32,768 字节上限size_cap_bytes: 32768见 manifest.yaml 第 331 行标识符与文件名反虚构扫描把 150 个文档中出现的标识符、48 个源文件名与记录时的源码树逐一比对确认“没有虚构任何源标识符或文件名”摘要重算用 digest 命令重算监视路径摘要得到d41c93eaac05bae9ae158e44147f1873e1923b6c15a3d4d962ed724c292eb0ac与 front matter 中记录的8de686...不一致——这就是 major 级发现 F-001 的直接来源。## No-issues notes则记录了反向结论每个必需后端都有三级小节并声明其输出形态直接 SPIR-V 的合法化与下游优化/链接/校验/调试门槛和源码一致HLSL 命名 flag、Metal tracker 保活、WGSL switch 处理、VM 诊断、Slang 回环 stub 的描述均准确。四条发现项详解以下按报告原表逐条展开。每条给出“位置、问题、证据、建议”并补充当前仓库 HEAD 上的验证情况方便读者自行复核。F-001majorwatched_paths_digest 过期位置front matter 第 6 行问题文档记录的watched_paths_digest为8de686...但当前 manifest 为本文档扩展了监视集合新增了 slang-code-gen.cpp 与 slang-global-session.cpp用regenerate.py digest pipeline/06-emit.md重算得到d41c93eaac05bae9ae158e44147f1873e1923b6c15a3d4d962ed724c292eb0ac。这份“强制的新鲜度元数据”因此已经过期证据manifest.yaml 在记录提交上的第 212–225 行定义了扩展后的监视集评审时执行 digest 命令得到上述值建议按当前 manifest 重新生成 front matter使watched_paths_digest等于计算值d41c93...。digest 机制的作用是把“文档基于哪一批源码”量化成一个可重算的指纹监视路径内容一变list-stale就会把文档判为stale。当前 HEAD 上 06-emit.md 的 front matter 已是generated_at: 2026-09-11、source_commit: 48c746dc...、watched_paths_digest: 09826ab3...——与记录提交不同说明该文档其后又经历过一轮重新生成并mark-freshF-001 反映的旧指纹已不再存在于当前文档中。F-002minor过时监视集论断与 manifest 矛盾位置## Emit dispatcher41–44 行与## Paths outside the watched set420–437 行问题文档当时声称slang-code-gen.cpp不在监视路径内、manifest 只监视slang-emit.cpp加slang-emit-*通配符——两处论断都过时了它还建议“把slang-code-gen.cpp加入监视”而该文件与slang-global-session.cpp早已被监视证据记录提交上的 manifest214–222 行同时列出了这两个文件与regenerate.py show pipeline/06-emit.md打印的解析结果一致。当前 HEAD 的 manifest.yaml 第 303–331 行仍然可见同一监视集slang-code-gen.cpp、slang-global-session.cpp、slang-emit.cpp、slang-emit-*.h、slang-emit-*.cpp以及prelude/slang-hlsl-prelude.h、source/core/slang-test-tool-util.cpp、source/slangc/main.cpp 等 19 条记录建议删掉派发器一节里“不在监视路径中”的限定语把最后一节改写为只讨论真正未被监视的依赖如prelude/*.h内容。这条发现展示了评审机制的一个核心价值文档里“关于文档自身机制”的元陈述也会漂移评审会把它当作普通事实去对账。F-003minorpost-emit metadata 归属被过度概括位置## Inputs and outputs28–33 行问题“发射产物携带……post-emit 元数据”这句话跨发射路径过度泛化。实际上只有源文本产物和直接 SPIR-V 产物会挂接linkedIR.metadataHostVM 路径创建的 artifact 只包含序列化字节码LLVM 派发函数也原样返回后端创建的产物、不挂接linkedIR.metadata证据记录提交上 slang-emit.cpp 的 2972–2986 行源产物与 3520–3531 行直接 SPIR-V执行挂接而 3581–3582HostVM与 3607–3636LLVM不执行建议按发射路径限定该陈述。在当前 HEAD 上可以直接复核对应的三个直连入口emitSPIRVForEntryPointsDirectly位于 slang-emit.cpp#L3699、emitHostVMCode位于 slang-emit.cpp#L3743、emitLLVMForEntryPoints位于 slang-emit.cpp#L3786源文本路径emitEntryPointsSourceFromIR则在 slang-emit.cpp#L2918。当前版本文档的对应小节已经把 metadata 陈述改写为“源与直接-SPIR-V 产物关联linkedIR.metadataHostVM 与 LLVM 派发函数不挂接”与 F-003 的修复方向一致依赖文件输出slang-emit-dependency-file.cpp 的writeDependencyFile明确不挂在 artifact 上而是写入单独配置的依赖输出路径这一点也仍保留在文档中。F-004minor“每个文本目标都带 prelude 头文件”不成立位置## Preludes336–367 行问题“每个文本目标都随附一个 prelude 头文件”与文档后文“GLSL、Metal、WGSL 没有 prelude/ 头文件”的陈述自相矛盾。全局会话只为CUDA、C、HLSL注册了随附的 prelude 字符串Torch 与非同质 host 输出是另行特判的证据slang-global-session.cpp#L125-L128 中三行注册调用get_slang_cuda_prelude()/get_slang_cpp_prelude()/get_slang_hlsl_prelude()slang-emit.cpp#L2937-L2951 在查询会话 prelude 之前对 Torch/host C 做了特判同一段代码还包含 GLSL 默认行号指令、WGSL 禁用行号指令的目标特判建议把首句改写为“只有表中所列目标使用随附 prelude 头文件GLSL、Metal、WGSL 依赖后端自身发射的词汇表”。当前 HEAD 上 slang-global-session.cpp 第 125–128 行的注册逻辑与评审记录完全一致当前版本文档## Preludes一节开头已限定为“表中列出的目标才随附 prelude 头文件其余文本目标依赖其后端自身发射的词汇表”prelude/slang-hlsl-prelude.h 等随附头文件与kMetalBuiltinPrelude*内联片段的区别也按建议写明。从评审到修复状态记录与闭环评审报告只是流水线的中间产物修复报告 记录了本例的收尾。其 front matter 显示修复模型为claude-opus-5、remediated_at: 2026-08-04T15:00:00Z动作为fixed: 3、rejected_out_of_scope: 1其余为 0。逐条处理如下发现项处理理由摘要F-001rejected-out-of-scopeprompts/_remediate.md 第 97–100 行规定generated_at、source_commit、watched_paths_digest三个字段保留给操作员的regenerate.py mark-fresh运行修复 Agent 不得自行编辑digest 在文档修正后由操作员mark-fresh时刷新F-002fixedmanifest 现监视slang-code-gen.cpp与slang-global-session.cpp两条过时论断均错误删去“不在监视路径中”限定语末节重写为只保留prelude/*.h内容这一真正的监视盲区F-003fixed在 HEAD 上逐行验证源产物与直接 SPIR-V 挂接 metadataHostVM 与 LLVM 不挂接且linkedIR.metadata在该文件再无其他出现点F-004fixed确认会话只为 CUDA/C/HLSL 注册 preludeTorch 与非同质 host 另行处理文档后段本就自证 GLSL/Metal/WGSL 无 prelude 头文件这套闭环体现了几条可复用的规则字段所有权分离正文错误由修复 Agent 改新鲜度元数据只由操作员命令刷新防止“修复报告”与“新鲜度账本”互相污染证据优先于建议修复前要在源码上逐行复核F-003 的验证记录就是例子_remediate.md的约束使得“驳回”必须给出可引用的条款而非口头理由状态可查询regenerate.py review-status [--show-counts]能按文档汇总评审/修复的新鲜度review-state.json 为每篇文档保存last_reviewed含报告路径、严重度分布、记录提交与文档摘要与last_remediated含动作计数与报告引用两组字段与新鲜度、gap 队列解耦按 regenerate.md 的说明评审新鲜度由监视源码的 digest 计算与文档自身文字无关测试套件报告的 doc gap 走另一条gap-intake通道推荐的逐文档顺序是 gap intake → review → remediation让评审者读到的是已被修正过的文字。如何复现这份评审的校验若你拿到同一仓库可以在仓库根目录用驱动脚本复现评审中的关键步骤命令见 regenerate.md 的子命令表# 查看本文档的 manifest 条目与解析后的监视文件 python3 docs/generated/design/_meta/regenerate.py show pipeline/06-emit.md # 重算当前监视路径摘要F-001 的对照手段 python3 docs/generated/design/_meta/regenerate.py digest pipeline/06-emit.md # 查看文档新鲜度与评审/修复状态 python3 docs/generated/design/_meta/regenerate.py list-stale --include-review python3 docs/generated/design/_meta/regenerate.py review-status pipeline/06-emit.md # 结构校验front matter 键、链接可解析、体积上限 python3 docs/generated/design/_meta/regenerate.py lint pipeline/06-emit.md需要注意两个前提一是该流水线由操作员驱动operator-drivenmark-fresh/mark-reviewed/mark-remediated都是显式记账动作不会静默发生二是文档在 regenerate.md 中明确标注“从源码反演而来”评审与测试套件的 doc gap 共同存在的意义就是防止“生成者与被评审者读了同一份源码而一起错”。本例报告正是这种设计的产物它不评价文档的写法偏好style、completeness 均 pass而是把“事实对不上源码”的每一处钉到具体行号与具体命令输出上——这正是 Agent 与 LLM 检索该文档时可以直接引用、可复验的证据形态。【免费下载链接】slangMaking it easier to work with shaders项目地址: https://gitcode.com/GitHub_Trending/sl/slang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考