从审查到修复Slang 自动微分 IR 参考文档的 Remediation 全解析【免费下载链接】slangMaking it easier to work with shaders项目地址: https://gitcode.com/GitHub_Trending/sl/slangdocs/generated/design/_meta/remediations/ir-reference/differentiation.md.remediation.md是 Slang 编译器中「自动生成 IR 参考文档」质量闭环的一环它记录了一轮针对 docs/generated/design/ir-reference/differentiation.md自动微分相关 IR 操作码参考页的审查review结果被逐条核验与修复的过程。本文以这份修复报告为主体结合目标文档与source/slang/下的真实实现逐项拆解 6 个发现其中 5 个已修复、1 个判定超范围并借此完整梳理 Slang 自动微分 IR 操作码族的语义、声明位置、产生方与消费方。读完本文你将同时掌握「这类文档是怎么被自动审查和修复的」以及「Slang 自动微分 IR 到底由哪些操作码构成、各自语义如何」两方面的知识。文档修复工作流review → remediation → mark-freshdocs/generated/design/ir-reference/目录下的参考页是由脚本自动生成的front matter 中generated: true、model: claude-opus-5[1m]等字段表明生成来源。为了让这些页面的事实与源码保持一致仓库维护了一套质量闭环review审查由审查模型对照源码逐条核对页面内容产出 docs/generated/design/_meta/reviews/ir-reference/differentiation.md.review.md包含清单checklist与带严重级别的发现finding列表。remediation修复由修复模型逐条核验发现是否属实、决定接受或拒绝产出本报告remediation report并在目标文档上执行修改。mark-fresh标记新鲜页面被编辑后由操作者运行regenerate.py mark-fresh重新记录当前 watched-path 摘要digest。本报告 front matter 记录了这次修复的元信息remediated_at时间戳、目标文档target_doc、审查报告路径review_report、修复前后目标文档的源码提交均为53b76e6d3009b8e6434d41573524c7ce5c499d23、以及动作统计——fixed: 5、rejected_out_of_scope: 1其余rejected_bogus、deferred、escalated均为 0。Summary 中的一句总结点明了本轮最重要的结论The critical error was real: theTrivialForwardDifferentiatesummary said the derivative leaves differentials alone when the implementation forces them to zero, and that row now states the zeroing behaviour.下面逐条解析 6 个发现。背景differentiation.md 是一份什么样的文档在进入发现细节之前有必要先理解被修复的目标文档。 docs/generated/design/ir-reference/differentiation.md 是 Slang IR 的按操作码per-opcode参考页面向的是工作在自动微分 passslang-ir-autodiff*.cpp、翻译 passsource/slang/slang-ir-translate.cpp或需要识别「部分微分后 IR 模块」的发射路径上的编译器工程师。文档覆盖的操作码族包括构建与投影微分对differential pair的操作码、请求函数值前向/反向导数的操作码、把遗留的「合并式反向函数」表示桥接到当前分裂形式的操作码以及支持检查点checkpointing与重物化rematerialization的操作码。表格中有两条贯穿全页的约定C wrapper 列的‡表示IRFoo结构体是手工写在头文件里而非从 Lua 条目生成详见 source/slang/slang-ir-insts.h 中的相关实现Operands 列的†表示 Lua 条目只声明了min_operands生成的 wrapper 不带具名访问器消费者需要直接调用getOperand(i)。文档将操作码按 9 个组别展开微分对构造、微分对投影、微分算子前向/反向/遗留桥接/合成导数 witness、自动微分占位符、微分类型信息、内建需求键、检查点与重物化。并在末尾用「Notable opcodes」小节深入剖析MakeDiffPair、GetDifferential/GetPrimal、翻译字典与五元组、ForwardDifferentiate、BackwardDifferentiate等关键操作码。F-001 至 F-006 正是对这一页内容的六处质疑。F-001criticalTrivialForwardDifferentiate 的语义被写反了这是本轮审查中最严重critical的发现也是整个修复报告的核心。问题文档把「置零」写成了「保留」修复前TrivialForwardDifferentiate那一行的摘要写着「导数会保留leave微分不变」但实现恰恰相反平凡前向导数会丢弃传入的切向量tangent并把所有输出微分强制置零。「保留微分」与「强制置零」在微分语义上是互斥的两种行为写反会导致阅读者以及据此实现/修改 pass 的工程师对操作码产生根本性误解。源码证据修复报告引用了 source/slang/slang-ir-autodiff-fwd.cpp 的三处位置来证明事实第 191-193 行emitInOutParamWriteBacks的参数zeroDifferentials的注释明确写道For a trivial derivative pass zeroDifferentials true: the call contributes no tangent, so every output differential is forced to zero rather than threading the incoming one平凡导数 pass 中该调用不贡献任何切向量因此每个输出微分都被强制置零而不是把传入的微分穿通过去第 203-205 行实现正是zeroDifferentials ? getDifferentialZeroOfType(builder, ...) : builder.emitLoad(...)即平凡情形直接取该类型的零微分第 219 行generateTrivialFwdDiffFunc构造平凡前向导数函数把真实的前向调用primalCall与零微分配对——第 237 行调用emitInOutParamWriteBacks(builder, /* zeroDifferentials */ true)第 247-249 行通过getDifferentialZeroOfType生成零微分并用emitMakeDifferentialPair打包返回。也就是说[TreatAsDifferentiable]/[HasTrivialForwardDerivative]语义下的平凡前向导数 执行原始前向函数同时返回零输出微分。真实的前向调用必须被求值第 226-228 行注释强调如果用一个默认构造的零 primal 顶替会毒化链式法则静默杀掉经过该调用的所有导数。修复结果该行的摘要被修正为Asks for a derivative that runs the primal and returns zero output differentials, ignoring incoming tangents.请求一个导数运行 primal 并返回零输出微分忽略传入的切向量。这个案例也展示了修复报告的典型工作方式先引用带行号的源码作为证据再说明文档如何改写而不是凭印象下结论。F-002minorbuiltinRequirementKey 其实能「活」到发射阶段问题原文档断言过强修复前的## Source小节说「该操作码族没有任何成员存活到发射survives to emit」。审查发现这句话过强builtinRequirementKey是 hoistable 的特化specialization之后可能作为未被引用的全局 inst存活下来一直走到 C-like 发射器。源码证据修复报告确认了 source/slang/slang-emit-c-like.cpp 第 5287-5292 行的处理逻辑当前源码中该逻辑位于CLikeSourceEmitter::ensureGlobalInst内函数在第 5326 行开始case 分支位于第 5338-5343 行case kIROp_BuiltinRequirementKey: // A built-in interface requirement key is metadata (like an interface // requirement entry); it never corresponds to emitted code. Unlike an // ordinary StructKey, this key is hoistable and so may survive as an // (unreferenced) global inst after specialization, so skip it explicitly. return;注意这里的方法名细节处理逻辑在ensureGlobalInst第 5326 行声明中而不是emitGlobalInst第 5087 行——修复报告特意纠正了这一函数归属说明这类自动生成的参考页连「哪个函数负责什么」都要求精确到行。修复结果## Source段的首句改为「本操作码族没有操作码会产生目标代码No opcode in this family produces target code」并在段落末尾补充了两句话builtinRequirementKey可以存活到ensureGlobalInst而发射器显式跳过它——它到达发射器、但不产生任何代码。这样既纠正了「完全到不了发射器」的错误又保留了「不产生目标代码」这一本质事实。F-003majorwatched_paths_digest 过期——这属于 mark-fresh而不是修复者的职责问题审查报告指出 front matter 中的watched_paths_digest与当前 watch 集合不匹配记录值是64be22...而regenerate.py digest ir-reference/differentiation.md在 watch 集合扩展到本页用到的 autodiff、翻译、DCE 与 checker 文件后返回的是57ecc66...。为什么被判定为超范围修复报告查证了 docs/generated/design/_meta/prompts/_remediate.md第 97-100 行generated_at、source_commit、watched_paths_digest这些字段被保留给操作者的regenerate.py mark-fresh步骤并明确指示修复者不要触碰它们。本页既然被编辑过mark-fresh会负责记录当前 digest。因此该项的正确动作是rejected-out-of-scope——发现本身正确但修复不该由 remediation 步骤完成。这体现了流水线的职责边界remediator 只修文档内容front matter 的元数据同步交给后续的 mark-fresh 环节避免两个环节互相踩踏。F-004minorDiffTypeInfo 是真正的空操作数应写 —问题修复前DiffTypeInfo一行的 Operands 列写的是† (none declared)并因†而指向「该条目只声明了min_operands」的解释。但审查发现这不准确DiffTypeInfo是真正的一元nullary操作码†的语义描述不了它。源码证据source/slang/slang-ir-insts.lua 第 1123-1127 行的声明只有-- Holds witness tables for differential type info (this type witness, return type witness, param witnesses). -- This is lowered to MakeTuple after specialization. { DiffTypeInfo { hoistable true, }, },既没有operands也没有min_operands——确实是一元操作码。而文档生成规范docs/generated/design/_meta/prompts/_common.md 第 238 行要求一元操作码的 Operands 列必须写—。修复结果Operands 列由† (none declared)改为—。顺带说明DiffTypeInfo本身的语义这也解释了为什么它没有任何操作数它本应持有描述函数可微类型的 witness 表类型 witness、返回类型 witness、参数 witness特化后被lowerDiffTypeInfoInsts重写为makeTuple——但目前仓库中没有任何代码产生它详见下文「没有产生方的操作码」段落。F-005 与 F-006nit首段读者句与 diff.meta.slang 链接化两个 nit 级发现都源于文档生成规范_common.md对格式的硬性要求修复成本低但体现了「机器可校验」的文档工程理念。F-005首段必须同时说明「讲什么」与「给谁看」_common.md 第 65-66 行要求正文第一段必须同时说明文档覆盖范围与目标读者。修复前目标读者句The intended reader is a compiler engineer...孤立在第二段。修复方式是把读者句并入开头段末尾措辞不变只做句子拼接。现在 differentiation.md 的开头段以「intended reader is a compiler engineer working on the autodiff passes...」收尾一段之内同时给出主题per-opcode reference for autodiff IR opcodes与受众。F-006源码引用必须是指向工作区相对路径的 Markdown 链接_common.md 第 43-45 行要求源码文件引用必须是带工作区相对路径的 Markdown 链接。修复前BackwardDifferentiatecallout 里用了裸反引号文件名diff.meta.slang而页面顶部已经链接过同一文件。修复方式是把该处替换为指向 source/slang/diff.meta.slang 的链接。这个文件是自动微分相关核心/标准模块元代码的所在地——diffPair(primal, diff)第 1329 行与detachT(T x)第 2081 行分别定义了MakeDiffPair与detachDerivative的源码拼写[PrimalSubstitute]/[PrimalSubstituteOf]也是在这里声明的 AST 级属性。被修复文档的核心内容Slang 自动微分 IR 操作码全景修复报告中的每一项都指向目标文档的具体行因此要真正读懂这份报告需要掌握被修复文档的核心内容。以下是在理解 6 个发现时最关键的几块知识。操作码从哪来三个产生方differentiation.md 的## Source小节指出这些操作码由三个不同的产生方注入 IR 模块核心模块core module微分对构造/投影类操作码与detachDerivative的源头。source/slang/core.meta.slang 中DifferentialPairT的__init以__intrinsic_op($(kIROp_MakeDifferentialPair))声明第 786 行其p/v/d属性分别对应DifferentialPairGetPrimal/DifferentialPairGetDifferential第 791、797、803 行DifferentialPtrPairT声明对应的指针风味四件套第 877-894 行。语义检查semantic checking大部分TranslateBase操作码的源头。SynthesizedFuncDeclsource/slang/slang-ast-decl.h 第 760 行携带uint32_t irOp字段与ListVal* operandssource/slang/slang-check-decl.cpp 在检查可微可调用对象时合成此类 decl 并把目标操作码存入irOpsource/slang/slang-lower-to-ir.cpp 第 13858 行在 lowering 时读取该字段、逐个 lowering 操作数、以(IROp)synFuncDecl-irOp调用emitIntrinsicInst并替换占位IRFunc。同类机制SynthesizedStructDecl第 12454 行负责反向模式的上下文类型。autodiff pass 自身剩余操作码由翻译/前向/反向/解包/转置/primal-hoist 等 pass 产生。翻译字典与「五元组」TranslateBase操作码是请求而非结果。每个请求都由 source/slang/slang-ir-translate.cpp 第 40 行的TranslationContext::maybeTranslateInst解析先查模块的翻译字典IRCompilerDictionary由第 16 行的initializeTranslationDictionary创建产出的结果被记忆化因此每个模块中同一请求最多翻译一次。反向模式只有一个根请求BackwardDifferentiate翻译成一个makeTuple五元组——primal 函数、remat 函数、propagate 函数、完整中间上下文类型、最小上下文类型。BackwardDifferentiatePrimal、BackwardRemat、BackwardDifferentiatePropagate、BackwardDiffIntermediateContextType、BackwardDiffMinimalContextType各自通过合成一个单操作数BackwardDifferentiate再翻译、按元组下标取元素 0-4 得到第 164-198 行Trivial*家族第 199-237 行与*FromLegacyBwdDiffFunc家族第 244-287 行以TrivialBackwardDifferentiate与BackwardFromLegacyBwdDiffFunc为根走同样的形状。这就是为什么各阶段操作码除基函数外不需要更多操作数——阶段信息由元组下标携带。生成的名字从 IR 到源码级文本目标这些操作码本身不产生目标代码但反向模式 pass 基于它们构建的函数与类型会出现在每个源码级文本目标HLSL、GLSL、Metal、WGSL、CUDA、C中。命名规则在 source/slang/slang-ir-autodiff-rev.cpp 中generateName给 propagate 函数加前缀s_bwdProp_第 405、726 行给完整中间上下文结构体加前缀s_bwdCallableCtx_第 314、727 行因此f会得到s_bwdProp_f与承载被提升 primal 状态的s_bwdCallableCtx_f。前向模式在 source/slang/slang-ir-autodiff-fwd.cpp 第 2271 行构建s_fwd_orig。SPIR-V 是例外其输出不携带导数函数的OpName读者只能按结构而非名字匹配。发射阶段的下调finalizeAutoDiffPass 与 lowerDiffTypeInfoInstsfinalizeAutoDiffPasssource/slang/slang-ir-autodiff.cpp 第 1174 行运行processPairTypes把MakeDiffPair重写为makeStruct、把两个投影重写为字段访问再运行removeDetachInsts与removeTypeAnnotationssource/slang/slang-emit.cpp 第 882 行的lowerDiffTypeInfoInsts会把DiffTypeInfo重写为makeTuple如果存在的话。两者都受requiredLoweringPassSet.autodiff门控而calcRequiredLoweringPassSet同文件第 405 行只要看到任何IRTranslateBase/IRTranslatedTypeBase/IRDifferentialPairTypeBase/IRMakeDifferentialPairBase就会置位——这正是「用户只写DifferentialPairfloat(x, dx)也会触发 autodiff 收尾 pass」的原因。六项修复的工程启示事实准确性优先文档与实现必须逐行对齐F-001 说明最严重的问题往往出现在「摘要」这类最显眼、最容易被读者当作行为契约的句子上。修复流程要求每个结论都给出带行号的源码证据并在修复后再次回到文档确认表述与实现一致。这是「文档即接口」理念的体现——IR 参考页是 pass 工程师改代码时的第一手依据一个写反的语义会直接误导下游实现。提示词契约驱动一致性可机器校验的格式规范F-004、F-005、F-006 全部由 docs/generated/design/_meta/prompts/_common.md 与 _remediate.md 中的硬性约定驱动一元操作码写—、首段双要素、源码引用必须链接化、front matter 字段归属。这类规范让「风格一致性」从主观品味变成可校验规则是自动生成文档体系得以长期维护的基础。人机分工什么该修、什么不该修F-003 展示了流水线的边界意识即使发现真实存在的问题digest 过期只要它属于另一个环节mark-fresh的职责就应标记为超范围而非越俎代庖。同理F-002 的修复也不是简单删掉一句错话而是精确到「把断言收窄到产生方/发射器职责」的粒度。修复报告本身因此成为一份可审计的记录谁在何时、依据什么证据、做了哪个改动、为什么拒绝另一个改动。延伸阅读目标文档docs/generated/design/ir-reference/differentiation.md本轮修复的实际对象审查报告docs/generated/design/_meta/reviews/ir-reference/differentiation.md.review.md操作码声明source/slang/slang-ir-insts.luaMakeDifferentialPairBase第 1016-1027 行、DifferentialPairGetDifferentialBase第 1029-1038 行、DifferentialPairGetPrimalBase第 1040-1046 行、TranslateBase第 2820-2855 行、DiffTypeInfo第 1123-1127 行C wrappersource/slang/slang-ir-insts.h手写与 FIDDLE 生成并存FIDDLE 模板位于第 3125 行核心 passsource/slang/slang-ir-autodiff-fwd.cpp、source/slang/slang-ir-autodiff-rev.cpp、source/slang/slang-ir-autodiff-unzip.cpp、source/slang/slang-ir-autodiff-primal-hoist.cpp、source/slang/slang-ir-translate.cpp相关类型参考docs/generated/design/ir-reference/types.mdDifferentialPairTypeBase/TranslatedTypeBase类型族、docs/generated/design/ir-reference/misc.md可微类型注解操作码自动微分设计文档docs/design/autodiff.mdprimal / propagate / remat 分裂与检查点模型的设计依据【免费下载链接】slangMaking it easier to work with shaders项目地址: https://gitcode.com/GitHub_Trending/sl/slang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 从审查到修复：Slang 自动微分 IR 参考文档的 Remediation 全解析
从审查到修复Slang 自动微分 IR 参考文档的 Remediation 全解析【免费下载链接】slangMaking it easier to work with shaders项目地址: https://gitcode.com/GitHub_Trending/sl/slangdocs/generated/design/_meta/remediations/ir-reference/differentiation.md.remediation.md是 Slang 编译器中「自动生成 IR 参考文档」质量闭环的一环它记录了一轮针对 docs/generated/design/ir-reference/differentiation.md自动微分相关 IR 操作码参考页的审查review结果被逐条核验与修复的过程。本文以这份修复报告为主体结合目标文档与source/slang/下的真实实现逐项拆解 6 个发现其中 5 个已修复、1 个判定超范围并借此完整梳理 Slang 自动微分 IR 操作码族的语义、声明位置、产生方与消费方。读完本文你将同时掌握「这类文档是怎么被自动审查和修复的」以及「Slang 自动微分 IR 到底由哪些操作码构成、各自语义如何」两方面的知识。文档修复工作流review → remediation → mark-freshdocs/generated/design/ir-reference/目录下的参考页是由脚本自动生成的front matter 中generated: true、model: claude-opus-5[1m]等字段表明生成来源。为了让这些页面的事实与源码保持一致仓库维护了一套质量闭环review审查由审查模型对照源码逐条核对页面内容产出 docs/generated/design/_meta/reviews/ir-reference/differentiation.md.review.md包含清单checklist与带严重级别的发现finding列表。remediation修复由修复模型逐条核验发现是否属实、决定接受或拒绝产出本报告remediation report并在目标文档上执行修改。mark-fresh标记新鲜页面被编辑后由操作者运行regenerate.py mark-fresh重新记录当前 watched-path 摘要digest。本报告 front matter 记录了这次修复的元信息remediated_at时间戳、目标文档target_doc、审查报告路径review_report、修复前后目标文档的源码提交均为53b76e6d3009b8e6434d41573524c7ce5c499d23、以及动作统计——fixed: 5、rejected_out_of_scope: 1其余rejected_bogus、deferred、escalated均为 0。Summary 中的一句总结点明了本轮最重要的结论The critical error was real: theTrivialForwardDifferentiatesummary said the derivative leaves differentials alone when the implementation forces them to zero, and that row now states the zeroing behaviour.下面逐条解析 6 个发现。背景differentiation.md 是一份什么样的文档在进入发现细节之前有必要先理解被修复的目标文档。 docs/generated/design/ir-reference/differentiation.md 是 Slang IR 的按操作码per-opcode参考页面向的是工作在自动微分 passslang-ir-autodiff*.cpp、翻译 passsource/slang/slang-ir-translate.cpp或需要识别「部分微分后 IR 模块」的发射路径上的编译器工程师。文档覆盖的操作码族包括构建与投影微分对differential pair的操作码、请求函数值前向/反向导数的操作码、把遗留的「合并式反向函数」表示桥接到当前分裂形式的操作码以及支持检查点checkpointing与重物化rematerialization的操作码。表格中有两条贯穿全页的约定C wrapper 列的‡表示IRFoo结构体是手工写在头文件里而非从 Lua 条目生成详见 source/slang/slang-ir-insts.h 中的相关实现Operands 列的†表示 Lua 条目只声明了min_operands生成的 wrapper 不带具名访问器消费者需要直接调用getOperand(i)。文档将操作码按 9 个组别展开微分对构造、微分对投影、微分算子前向/反向/遗留桥接/合成导数 witness、自动微分占位符、微分类型信息、内建需求键、检查点与重物化。并在末尾用「Notable opcodes」小节深入剖析MakeDiffPair、GetDifferential/GetPrimal、翻译字典与五元组、ForwardDifferentiate、BackwardDifferentiate等关键操作码。F-001 至 F-006 正是对这一页内容的六处质疑。F-001criticalTrivialForwardDifferentiate 的语义被写反了这是本轮审查中最严重critical的发现也是整个修复报告的核心。问题文档把「置零」写成了「保留」修复前TrivialForwardDifferentiate那一行的摘要写着「导数会保留leave微分不变」但实现恰恰相反平凡前向导数会丢弃传入的切向量tangent并把所有输出微分强制置零。「保留微分」与「强制置零」在微分语义上是互斥的两种行为写反会导致阅读者以及据此实现/修改 pass 的工程师对操作码产生根本性误解。源码证据修复报告引用了 source/slang/slang-ir-autodiff-fwd.cpp 的三处位置来证明事实第 191-193 行emitInOutParamWriteBacks的参数zeroDifferentials的注释明确写道For a trivial derivative pass zeroDifferentials true: the call contributes no tangent, so every output differential is forced to zero rather than threading the incoming one平凡导数 pass 中该调用不贡献任何切向量因此每个输出微分都被强制置零而不是把传入的微分穿通过去第 203-205 行实现正是zeroDifferentials ? getDifferentialZeroOfType(builder, ...) : builder.emitLoad(...)即平凡情形直接取该类型的零微分第 219 行generateTrivialFwdDiffFunc构造平凡前向导数函数把真实的前向调用primalCall与零微分配对——第 237 行调用emitInOutParamWriteBacks(builder, /* zeroDifferentials */ true)第 247-249 行通过getDifferentialZeroOfType生成零微分并用emitMakeDifferentialPair打包返回。也就是说[TreatAsDifferentiable]/[HasTrivialForwardDerivative]语义下的平凡前向导数 执行原始前向函数同时返回零输出微分。真实的前向调用必须被求值第 226-228 行注释强调如果用一个默认构造的零 primal 顶替会毒化链式法则静默杀掉经过该调用的所有导数。修复结果该行的摘要被修正为Asks for a derivative that runs the primal and returns zero output differentials, ignoring incoming tangents.请求一个导数运行 primal 并返回零输出微分忽略传入的切向量。这个案例也展示了修复报告的典型工作方式先引用带行号的源码作为证据再说明文档如何改写而不是凭印象下结论。F-002minorbuiltinRequirementKey 其实能「活」到发射阶段问题原文档断言过强修复前的## Source小节说「该操作码族没有任何成员存活到发射survives to emit」。审查发现这句话过强builtinRequirementKey是 hoistable 的特化specialization之后可能作为未被引用的全局 inst存活下来一直走到 C-like 发射器。源码证据修复报告确认了 source/slang/slang-emit-c-like.cpp 第 5287-5292 行的处理逻辑当前源码中该逻辑位于CLikeSourceEmitter::ensureGlobalInst内函数在第 5326 行开始case 分支位于第 5338-5343 行case kIROp_BuiltinRequirementKey: // A built-in interface requirement key is metadata (like an interface // requirement entry); it never corresponds to emitted code. Unlike an // ordinary StructKey, this key is hoistable and so may survive as an // (unreferenced) global inst after specialization, so skip it explicitly. return;注意这里的方法名细节处理逻辑在ensureGlobalInst第 5326 行声明中而不是emitGlobalInst第 5087 行——修复报告特意纠正了这一函数归属说明这类自动生成的参考页连「哪个函数负责什么」都要求精确到行。修复结果## Source段的首句改为「本操作码族没有操作码会产生目标代码No opcode in this family produces target code」并在段落末尾补充了两句话builtinRequirementKey可以存活到ensureGlobalInst而发射器显式跳过它——它到达发射器、但不产生任何代码。这样既纠正了「完全到不了发射器」的错误又保留了「不产生目标代码」这一本质事实。F-003majorwatched_paths_digest 过期——这属于 mark-fresh而不是修复者的职责问题审查报告指出 front matter 中的watched_paths_digest与当前 watch 集合不匹配记录值是64be22...而regenerate.py digest ir-reference/differentiation.md在 watch 集合扩展到本页用到的 autodiff、翻译、DCE 与 checker 文件后返回的是57ecc66...。为什么被判定为超范围修复报告查证了 docs/generated/design/_meta/prompts/_remediate.md第 97-100 行generated_at、source_commit、watched_paths_digest这些字段被保留给操作者的regenerate.py mark-fresh步骤并明确指示修复者不要触碰它们。本页既然被编辑过mark-fresh会负责记录当前 digest。因此该项的正确动作是rejected-out-of-scope——发现本身正确但修复不该由 remediation 步骤完成。这体现了流水线的职责边界remediator 只修文档内容front matter 的元数据同步交给后续的 mark-fresh 环节避免两个环节互相踩踏。F-004minorDiffTypeInfo 是真正的空操作数应写 —问题修复前DiffTypeInfo一行的 Operands 列写的是† (none declared)并因†而指向「该条目只声明了min_operands」的解释。但审查发现这不准确DiffTypeInfo是真正的一元nullary操作码†的语义描述不了它。源码证据source/slang/slang-ir-insts.lua 第 1123-1127 行的声明只有-- Holds witness tables for differential type info (this type witness, return type witness, param witnesses). -- This is lowered to MakeTuple after specialization. { DiffTypeInfo { hoistable true, }, },既没有operands也没有min_operands——确实是一元操作码。而文档生成规范docs/generated/design/_meta/prompts/_common.md 第 238 行要求一元操作码的 Operands 列必须写—。修复结果Operands 列由† (none declared)改为—。顺带说明DiffTypeInfo本身的语义这也解释了为什么它没有任何操作数它本应持有描述函数可微类型的 witness 表类型 witness、返回类型 witness、参数 witness特化后被lowerDiffTypeInfoInsts重写为makeTuple——但目前仓库中没有任何代码产生它详见下文「没有产生方的操作码」段落。F-005 与 F-006nit首段读者句与 diff.meta.slang 链接化两个 nit 级发现都源于文档生成规范_common.md对格式的硬性要求修复成本低但体现了「机器可校验」的文档工程理念。F-005首段必须同时说明「讲什么」与「给谁看」_common.md 第 65-66 行要求正文第一段必须同时说明文档覆盖范围与目标读者。修复前目标读者句The intended reader is a compiler engineer...孤立在第二段。修复方式是把读者句并入开头段末尾措辞不变只做句子拼接。现在 differentiation.md 的开头段以「intended reader is a compiler engineer working on the autodiff passes...」收尾一段之内同时给出主题per-opcode reference for autodiff IR opcodes与受众。F-006源码引用必须是指向工作区相对路径的 Markdown 链接_common.md 第 43-45 行要求源码文件引用必须是带工作区相对路径的 Markdown 链接。修复前BackwardDifferentiatecallout 里用了裸反引号文件名diff.meta.slang而页面顶部已经链接过同一文件。修复方式是把该处替换为指向 source/slang/diff.meta.slang 的链接。这个文件是自动微分相关核心/标准模块元代码的所在地——diffPair(primal, diff)第 1329 行与detachT(T x)第 2081 行分别定义了MakeDiffPair与detachDerivative的源码拼写[PrimalSubstitute]/[PrimalSubstituteOf]也是在这里声明的 AST 级属性。被修复文档的核心内容Slang 自动微分 IR 操作码全景修复报告中的每一项都指向目标文档的具体行因此要真正读懂这份报告需要掌握被修复文档的核心内容。以下是在理解 6 个发现时最关键的几块知识。操作码从哪来三个产生方differentiation.md 的## Source小节指出这些操作码由三个不同的产生方注入 IR 模块核心模块core module微分对构造/投影类操作码与detachDerivative的源头。source/slang/core.meta.slang 中DifferentialPairT的__init以__intrinsic_op($(kIROp_MakeDifferentialPair))声明第 786 行其p/v/d属性分别对应DifferentialPairGetPrimal/DifferentialPairGetDifferential第 791、797、803 行DifferentialPtrPairT声明对应的指针风味四件套第 877-894 行。语义检查semantic checking大部分TranslateBase操作码的源头。SynthesizedFuncDeclsource/slang/slang-ast-decl.h 第 760 行携带uint32_t irOp字段与ListVal* operandssource/slang/slang-check-decl.cpp 在检查可微可调用对象时合成此类 decl 并把目标操作码存入irOpsource/slang/slang-lower-to-ir.cpp 第 13858 行在 lowering 时读取该字段、逐个 lowering 操作数、以(IROp)synFuncDecl-irOp调用emitIntrinsicInst并替换占位IRFunc。同类机制SynthesizedStructDecl第 12454 行负责反向模式的上下文类型。autodiff pass 自身剩余操作码由翻译/前向/反向/解包/转置/primal-hoist 等 pass 产生。翻译字典与「五元组」TranslateBase操作码是请求而非结果。每个请求都由 source/slang/slang-ir-translate.cpp 第 40 行的TranslationContext::maybeTranslateInst解析先查模块的翻译字典IRCompilerDictionary由第 16 行的initializeTranslationDictionary创建产出的结果被记忆化因此每个模块中同一请求最多翻译一次。反向模式只有一个根请求BackwardDifferentiate翻译成一个makeTuple五元组——primal 函数、remat 函数、propagate 函数、完整中间上下文类型、最小上下文类型。BackwardDifferentiatePrimal、BackwardRemat、BackwardDifferentiatePropagate、BackwardDiffIntermediateContextType、BackwardDiffMinimalContextType各自通过合成一个单操作数BackwardDifferentiate再翻译、按元组下标取元素 0-4 得到第 164-198 行Trivial*家族第 199-237 行与*FromLegacyBwdDiffFunc家族第 244-287 行以TrivialBackwardDifferentiate与BackwardFromLegacyBwdDiffFunc为根走同样的形状。这就是为什么各阶段操作码除基函数外不需要更多操作数——阶段信息由元组下标携带。生成的名字从 IR 到源码级文本目标这些操作码本身不产生目标代码但反向模式 pass 基于它们构建的函数与类型会出现在每个源码级文本目标HLSL、GLSL、Metal、WGSL、CUDA、C中。命名规则在 source/slang/slang-ir-autodiff-rev.cpp 中generateName给 propagate 函数加前缀s_bwdProp_第 405、726 行给完整中间上下文结构体加前缀s_bwdCallableCtx_第 314、727 行因此f会得到s_bwdProp_f与承载被提升 primal 状态的s_bwdCallableCtx_f。前向模式在 source/slang/slang-ir-autodiff-fwd.cpp 第 2271 行构建s_fwd_orig。SPIR-V 是例外其输出不携带导数函数的OpName读者只能按结构而非名字匹配。发射阶段的下调finalizeAutoDiffPass 与 lowerDiffTypeInfoInstsfinalizeAutoDiffPasssource/slang/slang-ir-autodiff.cpp 第 1174 行运行processPairTypes把MakeDiffPair重写为makeStruct、把两个投影重写为字段访问再运行removeDetachInsts与removeTypeAnnotationssource/slang/slang-emit.cpp 第 882 行的lowerDiffTypeInfoInsts会把DiffTypeInfo重写为makeTuple如果存在的话。两者都受requiredLoweringPassSet.autodiff门控而calcRequiredLoweringPassSet同文件第 405 行只要看到任何IRTranslateBase/IRTranslatedTypeBase/IRDifferentialPairTypeBase/IRMakeDifferentialPairBase就会置位——这正是「用户只写DifferentialPairfloat(x, dx)也会触发 autodiff 收尾 pass」的原因。六项修复的工程启示事实准确性优先文档与实现必须逐行对齐F-001 说明最严重的问题往往出现在「摘要」这类最显眼、最容易被读者当作行为契约的句子上。修复流程要求每个结论都给出带行号的源码证据并在修复后再次回到文档确认表述与实现一致。这是「文档即接口」理念的体现——IR 参考页是 pass 工程师改代码时的第一手依据一个写反的语义会直接误导下游实现。提示词契约驱动一致性可机器校验的格式规范F-004、F-005、F-006 全部由 docs/generated/design/_meta/prompts/_common.md 与 _remediate.md 中的硬性约定驱动一元操作码写—、首段双要素、源码引用必须链接化、front matter 字段归属。这类规范让「风格一致性」从主观品味变成可校验规则是自动生成文档体系得以长期维护的基础。人机分工什么该修、什么不该修F-003 展示了流水线的边界意识即使发现真实存在的问题digest 过期只要它属于另一个环节mark-fresh的职责就应标记为超范围而非越俎代庖。同理F-002 的修复也不是简单删掉一句错话而是精确到「把断言收窄到产生方/发射器职责」的粒度。修复报告本身因此成为一份可审计的记录谁在何时、依据什么证据、做了哪个改动、为什么拒绝另一个改动。延伸阅读目标文档docs/generated/design/ir-reference/differentiation.md本轮修复的实际对象审查报告docs/generated/design/_meta/reviews/ir-reference/differentiation.md.review.md操作码声明source/slang/slang-ir-insts.luaMakeDifferentialPairBase第 1016-1027 行、DifferentialPairGetDifferentialBase第 1029-1038 行、DifferentialPairGetPrimalBase第 1040-1046 行、TranslateBase第 2820-2855 行、DiffTypeInfo第 1123-1127 行C wrappersource/slang/slang-ir-insts.h手写与 FIDDLE 生成并存FIDDLE 模板位于第 3125 行核心 passsource/slang/slang-ir-autodiff-fwd.cpp、source/slang/slang-ir-autodiff-rev.cpp、source/slang/slang-ir-autodiff-unzip.cpp、source/slang/slang-ir-autodiff-primal-hoist.cpp、source/slang/slang-ir-translate.cpp相关类型参考docs/generated/design/ir-reference/types.mdDifferentialPairTypeBase/TranslatedTypeBase类型族、docs/generated/design/ir-reference/misc.md可微类型注解操作码自动微分设计文档docs/design/autodiff.mdprimal / propagate / remat 分裂与检查点模型的设计依据【免费下载链接】slangMaking it easier to work with shaders项目地址: https://gitcode.com/GitHub_Trending/sl/slang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考