- 编译器
- 图形学
- 编程语言
【免费下载链接】slang
Making it easier to work with shaders
本篇技术指南以仓库中docs/generated/design/_meta/remediations/ir-reference/types.md.remediation.md这份修复报告为主线，解析 Slang 项目如何通过"生成 → 独立评审 → 修复"两阶段闭环，维护一份覆盖 170 个 IR Type 指令（opcode）的逐指令参考文档。读者将了解这份报告所依据的生成契约、评审发现的五类问题及其修复方式，并从修复细节中掌握 Slang IR 类型系统的命名规则、wrapper 生成机制与 AST 降低（lowering）路径。
背景：Slang 的生成式设计文档管线
docs/generated/design/下的设计文档并非手写，而是由 LLM 依据 manifest.yaml 中每个文档声明的watched_paths（受监控源码路径）生成的。生成契约统一写在 prompts/_common.md 中，规定每个文档必须携带完整的 YAML front-matter（generated、model、generated_at、source_commit、watched_paths_digest、warning六键），并遵守链接解析、行号引用、标识符扫描等硬性规则。
该管线的核心设计是两阶段独立评审（见 regenerate.md 的 "Review and remediation workflow" 一节）：
- Review（评审）——由与生成模型不同模型家族的 agent 执行（参考流程使用 GPT 系模型），对目标文档逐条核对源码事实与契约合规性，产出结构化评审报告；
- Remediation（修复）——由与生成模型同家族的 agent（Anthropic Claude 系）执行，对评审报告中的每条 finding 决定"修复 / 拒绝 / 延期 / 升级"，并实际编辑目标文档，产出修复报告。
本文所分析的 remediation 报告正是这一闭环针对ir-reference/types.md的产物。该报告引用的评审报告位于 reviews/ir-reference/types.md.review.md，对应的被修复目标文档位于 docs/generated/design/ir-reference/types.md。
remediation 报告的结构与定位
报告的 front-matter 记录了执行元数据：
remediator_model: claude-opus-5与reviewed_at时间戳，标识执行修复的模型与时间；target_doc: ir-reference/types.md与review_report相对链接，建立"评审 → 修复"的追踪链；target_doc_source_commit_before/target_doc_source_commit_after均为53b76e6d...，说明本次修复没有改动受监控的源码，只改了文档本身；actions字段统计五类处置数量：fixed: 4、rejected_bogus: 0、rejected_out_of_scope: 0、deferred: 1、escalated: 0。
正文由## Summary（摘要）与## Actions（处置表）构成。Actions 表每行对应评审报告的一条 finding，列含Finding ID、Action、Rationale（理由，含源码证据与行号）、Fix summary（修复摘要）。这份结构化的"问题 → 证据 → 处置"记录本身也会被regenerate.py lint校验（front-matter 与## Actions表必须通过 remediation-report.schema.json 的字段、计数与交叉一致性检查）。
评审发现的五个问题
评审报告（reviews/ir-reference/types.md.review.md）对该文档做了四项核查：逐条核对 56 处行号引用、抽查 10 余项事实断言、对照slang-ir-insts.lua全量比对 170 行 opcode（无遗漏、无重复）、解析全部 62 处相对链接（31 个唯一目标，全部有效）。在此基础上提出五个 finding，其中 3 个 major、2 个 minor：
| Finding | 严重度 | 问题 | 证据 |
|---|---|---|---|
| F-001 | major | 全部 170 行C++ wrapper列缺少IR前缀，例如写了VectorType而实际符号是IRVectorType | 契约要求IRFoo符号名（_common.md）；FIDDLE 生成模板struct IR$(inst.struct_name)位于source/slang/slang-ir-insts.h |
| F-002 | major | 操作数列用†标记推断出的 C++ 布局，而契约要求(see Lua)；变参使用了types...而非(variadic) | 页面自己的图例（167-175 行）承认†表示来自 C++ accessor 的真实操作数 |
| F-003 | major | 20 个子表中 11 个没有任何行级 producer（降低访问器/构建器）引用 | 逐文档提示要求每个子表至少一行引用visit*或IRBuilder::getXType |
| F-004 | minor | "fourEmpty*variants" 应为 "three" | slang-ir-insts.lua中Empty*条目只有 252、277、278 三行 |
| F-005 | minor | 首段未同时声明覆盖范围与目标读者，读者句在独立段落 | _common.md要求首段同时给出两者 |
修复动作详解：从 finding 到落地
F-001：为全部 170 行补上IR前缀
修复确认了评审的判断：表格此前给出的是 Luastruct_name值，而_common.md契约要求精确的 C++ wrapper 符号IRFoo。修复将全部 170 行 opcode 的 wrapper 单元格加上IR前缀，并逐个与struct IR...声明交叉核对——核对对象包括 FIDDLE 生成的 slang-ir-insts.h.fiddle、slang-ir-insts.h 与 slang-ir.h，零缺失（含哨兵类型IRAfterBaseType）。手写的‡标记保持不变。
这条修复背后是两条命名约定（详见目标文档 types.md 的## Source一节）：
- 枚举器命名：生成的
IROp枚举器是kIROp_加上条目的struct_name，而非 Lua key——instEnums在 slang-ir.h.lua 第 276 行发出kIROp_$(value.struct_name)。因此 Lua keyVec对应kIROp_VectorType，Array对应kIROp_ArrayType，而TextureShapeCubeDType变成kIROp_TextureShapeCubeType（注意去掉了D）。Lua key 仅作为-dump-ir打印的助记符存活。 - wrapper 命名：C++ wrapper 是
IR加上同一struct_name；当struct_name省略时，process（slang-ir-insts.lua 第 3452 行）用to_pascal_case从 key 推导。
之所以容易写错，是因为并非所有 wrapper 都是 FIDDLE 生成的：16 个叶子 wrapper 是手写的——IRSubpassInputType、IRFuncType、IRStructType、IRInterfaceType、IRWitnessTableType、IRBoundInterfaceType等位于 slang-ir.h，而IRSetTagType、IRTaggedUnionType、IRElementOfSetType、IRUntaggedUnionType位于 slang-ir-insts.h 第 3050-3081 行；其余 154 个叶子由 FIDDLE 模板（同文件 3113-3154 行）生成，每个获得一个isaImpl、一个kOp常量，以及每个命名 Lua 操作数对应的 accessor（getElementType()、getElementCount()等）。
F-003：为 11 个子表补充 producer 引用
逐文档提示（ir-reference-types.md84-85 行）要求每个子表至少有一行引用对应的 producer。修复在 slang-lower-to-ir.cpp 中核实了以下真实 producer 并逐个子表补上引用：
visitBasicExpressionType（2839 行）——标量类型子表；visitArrayExpressionType（2861 行）——数组子表；visitFuncType（2718 行）——函数子表；lowerSimpleIntrinsicType（2879 行）——核心模块标量、字符串、裸指针、采样器、张量、work-graph 等子表的__intrinsic_type路径；getWitnessTableType（2395 行）——witness-table 子表；getRateQualifiedType（4556 行）——rate 限定类型子表。
同时诚实标注了两个例外：SPIR-V literals and kinds与Set-theoretic types两个子表中的 opcode 全部由 IR pass 综合（synthesized）产生、在 HEAD 上不存在 AST 降低 producer，因此该检查项对它们"不适用"而非"未满足"。
F-004：修正Empty*变体计数
报告确认 slang-ir-insts.lua 中WorkGraphRecordTypeBase子组（252、277、278 行）恰好有三个Empty*条目：EmptyNodeInput、EmptyNodeOutput、EmptyNodeOutputArray，与子表的三行一一对应。第 665 行原文 "fourEmpty*variants" 改为 "three"。
这三个 nullary 类型是 D3D12 work-graph 节点输入/输出记录类型家族的一部分——该家族十个 opcode 全部只以__intrinsic_type(...)形式声明于 workgraph.slang（如NodeOutputArray在 223-226 行、EmptyNodeOutputArray在 261-264 行），在 AST 层只是普通DeclRefType，唯一的编译器侧身份就是本表的 opcode，由lowerSimpleIntrinsicType首次物化。
F-005：合并首段读者声明
_common.md65-66 行要求正文第一段以通俗语言同时声明"文档覆盖什么"与"目标读者是谁"。修复删除了段落分隔，使读者句并入开头段，即现在的：
"The intended reader is a compiler engineer reading IR and needing to identify a type opcode, or writing an IR pass or backend that manipulates types."
F-002：合理延期（deferred）
唯一被延期的 finding 是关于操作数词汇的契约偏差：约 30 行使用†标记（页面图例 167-175 行已说明其操作数取自 C++ accessor，是权威来源），而契约ir-reference-types.md:37-39要求这些位置写(see Lua)——照做会删除已验证的真实信息；另有 11 行使用name...，而_common.md:238要求(variadic)。修复方认为该问题是全页范围的契约修订，需要先在ir-reference-types.md:35-39与_common.md:238之间做出契约决策，故记为deferred并建议"修订契约以认可†/...标记，或将行级改写排入下一个周期"。这体现了该管线"宁可延期也不删减已验证事实"的处置原则。
从修复看 IR Type 家族的技术内核
被修复的 types.md 远不止是一张表，它是 Slang IR 类型系统的逐指令权威参考。理解这份文档，才能理解修复中每一项核对的含义。
170 个 opcode 与 hoistable 去重
Type家族条目在 slang-ir-insts.lua 中从第 19-20 行开始、第 881 行结束，在source_commit处含170 个具体 opcode，占全部 857 个指令的近五分之一，是最大的单一家族。绝大多数叶子类型 opcode 是hoistable（可提升）的：相同类型会去重为同一个 IR 值，从而让"类型相等"退化为指针比较。例外是 parent/container 与 global 条目（Enum、struct、class为 parent，interface为 global）以及三个无 flag 的辅助条目（AfterBaseType、MakeTensorAddressingTensorLayout、MakeTensorAddressingTensorView）。
dump 输出中的类型形态
shouldFoldInstIntoUses（slang-ir.cpp 7822-7859 行）会把所有类型折叠进使用点，dumpInstExpr（8337 行）将折叠指令打印为"助记符(操作数列表)"，如Enum(Int)、StructuredBuffer(Float, Std140Layout, ...)，nullary 类型则打印裸助记符Float。四个名义（nominal）类型struct、class、GLSLShaderStorageBuffer、interface不参与折叠，各自拥有顶层定义行，使用点以%id引用。
AST 降低路径
类型从 AST 到 IR 的降低集中在 slang-lower-to-ir.cpp：少量手写 case（visitBasicExpressionType2852 行、visitVectorExpressionType2857 行、visitArrayExpressionType2874 行、visitPtrType2773 行、visitTupleType2830 行等），以及覆盖其余大部分的统一机制——visitDeclRefType（2809 行）检查IntrinsicTypeModifier（核心模块源码中的__intrinsic_type(...)属性），将类型路由到lowerSimpleIntrinsicType（2892 行），后者直接从修饰符取 opcode，并按声明顺序把DeclRef的每个泛型实参变成 IR 类型的操作数。visitResourceType、visitSamplerStateType、visitBuiltinGenericType、visitMeshOutputType等（2917-2921 行）都只是委托给它。
张成内容的几个要点
Vec/Mat：Mat的layout操作数是 int 字面量（0 未知、1 行主序、2 列主序），与core.meta.slang中kRowMajorMatrixLayout/kColumnMajorMatrixLayout对应；specializeMatrixLayout会在 emit 前把存留的0改写为目标设置（默认行主序）。Func：结果类型是首操作数，参数按声明顺序排列，末尾可带一个 trailing 属性（通常记录throws子句的IRFuncThrowTypeAttr）；getParamCount()等 accessor 会跳过它，切勿把最后一个操作数当参数读。ArrayvsUnsizedArray：stride可选操作数位置不同（Array 在索引 2，UnsizedArray 在索引 1），因此应调用IRArrayTypeBase::getArrayStride()而非手工索引。Enum：P标志只表示"可以"有子项，createEnumType实际只带 tag 类型操作数创建，case 是普通常量（其类型是Enum），不是成员。Ptr：至多三个可选IRIntLit操作数（accessQualifier / addressSpace / dataLayout），IRPtrTypeBase在缺省时默认AccessQualifier::ReadWrite与AddressSpace::Generic，所以判断"是否真的记录了地址空间"要用hasAddressSpace()。TextureType：九个操作数位置是命名常量（kCoreModule_TextureShapeParameterIndex= 1 到kCoreModule_TextureFormatParameterIndex= 8），由IRResourceTypeBase封装为getShapeInst()、isMultisample()、getAccess()等 accessor。TaggedUnionType操作数顺序：Lua 注释写的是(typeSet, witnessTableSet)，实际顺序相反——getTaggedUnionType把 witness-table set 放在操作数 0、type set 放在操作数 1，必须用 accessor 读取。UntypedResourceHandle/UntypedSamplerHandle：nullary 且不抵达任何后端，堆索引存在于值而非类型中，由四个Cast*Untyped{Resource,Sampler}Handle*转换指令搬运，lowerUntypedResourceHandleToUInt（slang-ir-lower-dynamic-resource-heap.cpp，由 slang-emit.cpp 1950 行调用）会在 emit 前移除它们。
闭环的操作流程：从 review-status 到 mark-remediated
这套评审-修复机制是可复现的操作流程（regenerate.md 的 "Example session" 一节给出了完整命令序列）：
# 0. 查看哪些文档需要评审 python3 docs/generated/design/_meta/regenerate.py review-status # 1. 运行评审 agent（非 Claude 家族），报告存至 # _meta/reviews/<doc>.review.md 后： python3 docs/generated/design/_meta/regenerate.py lint <doc> python3 docs/generated/design/_meta/regenerate.py mark-reviewed <doc> # 2. 运行修复 agent（Claude 家族），它可能编辑目标文档， # 报告存至 _meta/remediations/<doc>.remediation.md 后： python3 docs/generated/design/_meta/regenerate.py mark-fresh <doc> --model <model-id> python3 docs/generated/design/_meta/regenerate.py lint <doc> python3 docs/generated/design/_meta/regenerate.py mark-remediated <doc>几个关键机制：
- 软拒绝三层：评审提示横幅要求 Claude 系模型输出
REFUSED，修复提示横幅要求非 Claude 系模型输出REFUSED；账本门mark-reviewed拒绝reviewer_model含claude/anthropic的记录，mark-remediated则要求remediator_model必须含之。这是刻意设计为软门——驱动脚本不调用模型 API，无法验证身份。 mark-fresh的时序：文档被编辑后必须先mark-fresh刷新watched_paths_digest；若全部 finding 均为拒绝/延期/升级（文档未改）则跳过。文档的评审新鲜度以freshness.json中的 digest 为准，而不是文档 front-matter 中的拷贝。- lint 是硬门：front-matter 缺失键、链接无法解析、报告表与 schema 不符、finding ID 与 action ID 交叉不一致，都会导致
lint非零退出；报告解析失败时mark-gap-intake/mark-remediated拒绝写入，防止畸形报告污染账本。 - 生命周期：
fresh →(评审)→ reviewed →(修复)→ remediated →(源码变更后 mark-fresh)→ stale →(再评审)→ reviewed，由review-status实时推导。
一个操作教训：manifest 变更要先于记账。若先mark-reviewed再扩宽watched_paths，digest 变化会让所有受影响文档瞬间翻转为review-stale——一次周期曾因此无效化了 31 份评审中的 21 份。
结语
ir-reference/types.md.remediation.md这份报告展示了 Slang 文档管线对抗"文档漂移与幻觉"的具体方法：评审用不同模型家族独立复核源码事实，修复用同家族模型在契约约束下落地修改，每一条 finding 都留下可追溯的源码证据链，无法在契约层面解决的问题（F-002）宁可延期也不删减已验证信息。对读者而言，它同时是一份难得的实践样本——既能照搬这套"生成-评审-修复"的文档质量闭环，也能借由修复中逐行核对的细节，快速掌握 Slang IR 类型系统（170 个 opcode、hoistable 去重、FIDDLE wrapper 生成、__intrinsic_type降低）的底层运作方式。
See also
- ir-reference/types.md —— 被修复的目标文档，IR Type 家族完整逐指令参考；
- reviews/ir-reference/types.md.review.md —— 本次修复依据的评审报告；
- prompts/_common.md —— 所有生成文档的公共契约（front-matter、表格列、软拒绝、Liquid 安全）；
- regenerate.md —— 生成、评审、修复的完整操作手册；
- manifest.yaml —— 每份文档的 prompt、watched_paths、size cap 映射；
- slang-ir-insts.lua —— Type 家族 170 个 opcode 的权威 Lua 声明；
- slang-lower-to-ir.cpp —— AST 类型到 IR 类型的降低实现；
- design/ir.md —— IR 值类型化、指针相等、hoistable 层级的设计动机。
- 编译器
- 图形学
- 编程语言
【免费下载链接】slang
Making it easier to work with shaders
相关推荐
深入解读 Slang 的 AST-to-IR 文档评审报告：LLM 生成设计文档的独立审查与修复闭环
深入解读 Slang 的 AST to IR 文档评审报告：LLM 生成设计文档的独立审查与修复闭环 Slang 仓库在 docs/generated/desi
编译器图形学编程语言Slang 生成式设计文档的评审闭环：从一份真实的 Layout IR 评审报告说起
Slang 生成式设计文档的评审闭环：从一份真实的 Layout IR 评审报告说起 在 Slang 编译器仓库的 docs/generated/design/
编译器图形学编程语言基于评审报告的质量审计：Slang IR Type 家族逐操作码参考文档的准确性校验
基于评审报告的质量审计：Slang IR Type 家族逐操作码参考文档的准确性校验 导读 本文以 docs/generated/design/_meta/re
编译器图形学编程语言
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
