Slang 文档审查流水线实战以 visibility.md 审查报告为例的文档-源码一致性核对方法【免费下载链接】slangMaking it easier to work with shaders项目地址: https://gitcode.com/GitHub_Trending/sl/slang本文基于 Slang 仓库中的生成式文档审查报告 visibility.md.review.md拆解 Slang 的 LLM 生成文档流水线如何对docs/generated/design下的设计文档做逐行号、逐断言的事实核对并完整复盘该报告针对可见性visibility一页文档记录下的 6 项发现F-001 至 F-006。读完后你将掌握如何阅读一份 review report 的 front matter 与 findings 表格、如何用regenerate.py复算 watched-paths digest 来验证文档新鲜度以及 Slang 编译器中public/internal/private可见性规则在源码层面的关键落点slang-compile-request.cpp、slang-parser.cpp、slang-check-decl.cpp、slang-check-expr.cpp、slang-check-modifier.cpp等。1. 审查报告是什么生成文档流水线的一个环节这份报告位于 Slang 文档审查流水线的产物目录_meta/reviews/name-resolution/下与同族的index.md.review.md、lookup.md.review.md、scopes.md.review.md、overload-resolution.md.review.md并列。它的审查对象是生成文档 docs/generated/design/name-resolution/visibility.md —— 该页文档专门描述 Slang 声明可见性规则每个声明携带哪个public/private/internal关键字、各语言版本下的默认值以及可见性过滤在语义检查管线中发生的位置。整条流水线由 regenerate.py 驱动。从其模块头注释可以看到完整的子命令集合list/list-stale [--include-review]列出 manifest 中的文档或列出 watched-paths digest 与记录值不一致即过期的文档digest doc打印某文档当前 watched paths 的 digestshow doc打印 manifest 条目及其解析后的文件列表mark-fresh doc以当前 digest、HEAD 提交和当前时间戳写入freshness.jsonlint [doc...]结构性 lintfront matter 存在性、路径可解析、表格合法、体积上限并连带 lint 所有 review / remediation 报告review-status [doc...]打印每个文档的unreviewed/review-stale/reviewed-pending-remediation/remediated状态mark-reviewed doc [--report path]从指定报告文件向review-state.json写入审查记录默认报告路径即_meta/reviews/doc.review.md—— 本文的审查报告正是这个默认位置的产物mark-remediated doc [--report path]从补救报告写入修复记录。注释还明确了两条治理规则生成、审查、补救均由操作员在带外out-of-band用 agent 完成脚本本身不调用任何模型reviewer 模型不得自称 Claude/Anthropic 家族见_CLAUDE_FAMILY_TOKENS软拒绝逻辑remediator 则必须来自 Claude/Anthropic 家族——生成与审查刻意由不同模型家族交叉完成。2. 报告 Front Matter六个字段定下核对基准报告头部的 YAML front matter 记录了整个审查的锚点review_report: true reviewer_model: gpt-5.6-sol reviewed_at: 2026-08-04T12:06:3000:00 target_doc: name-resolution/visibility.md target_doc_source_commit: 53b76e6d3009b8e6434d41573524c7ce5c499d23 target_doc_watched_paths_digest: 94e3bb442f068e23a07ff33e9536a9fc2e08c2fa82513f4ca6488832ebf31946 source_commit: 53b76e6d3009b8e6434d41573524c7ce5c499d23 checklist: factual_accuracy: partial cross_references: pass completeness: pass style_consistency: pass source_alignment: partial front_matter_validity: partial finding_count: 6 severity_breakdown: critical: 0 major: 0 minor: 6 nit: 0几个关键点target_doc_source_commit与source_commit相同均为53b76e6d3009b8e6434d41573524c7ce5c499d23意味着报告核对的是目标文档记录的那个源码提交target_doc_watched_paths_digest94e3bb...是 F-001 发现的对象它与 manifest 当前解析出的 watched 文件集合重算出的 digest 不一致checklist 中factual_accuracy、source_alignment、front_matter_validity三项为partial与 6 个 minor 发现一一对应3 项内容性偏差 digest 失效 相关字段问题而cross_references、completeness、style_consistency为passseverity 全为 minor6 个无 critical/major说明文档整体质量可靠问题属于表述精度层面而非结构性错误。3. 审查方法报告实际执行了哪些核验动作报告 Items checked 一节列出了六项核验动作这也是理解该流水线审查深度的核心全量读取读取目标文档、_common.md流水线通用规则、本页面的专属 promptprompts/name-resolution-visibility.md、manifest 解析出的全部 12 个 watched 文件以及全部 3 个依赖文档提交一致性确认目标文档记录的 source commit 是当前HEAD且 watched 源文件相对该提交没有 worktree 差异行号重推导对正文中每一条行号引用做重新推导re-derive并抽查了 30 多个事实与行为断言——这正是后面 6 项发现全部能精确到文件 行号 期望代码形状的原因链接解析在记录的提交上解析每个相对链接确认每个 generated 同级文档都在 manifest 中并成功运行 generated-doc linterfront matter 校验验证全部必需 front-matter 字段并重算 watched-path digest——这一条直接产生了 F-001。值得注意的是专属 prompt 本身就是验收合同name-resolution-visibility.md 规定了页面必须覆盖的 ConceptsVisibilityModifier家族、DeclVisibility枚举、ModuleDecl::defaultVisibility、IgnoreForLookupModifier、Rules 的六个小节顺序每关键字语义、按语言版本的默认值、过滤发生位置、容器级规则、extern/export交互、泛型参数与合成成员、一个 mermaid 流程图以及 Edge cases 必列的六个场景。审查报告 No-issues notes 确认目标页满足该合同所有 modifier 声明、枚举值、源码行范围、诊断名和诊断代码都与记录的提交一致lookup 与 overload 两条可见性路径被正确呈现为共享isDeclVisibleFromScope的独立分支。4. 发现清单逐条复盘digest 失效与五处源码级偏差报告 findings 表格列出 6 项 minor 发现。下面逐条说明其问题本质、证据位置与修复建议——这 6 条恰好覆盖了生成文档最容易出错的几类断言。4.1 F-001记录的 watched-paths digest 已失效位置front matter 第 6 行问题文档记录的watched_paths_digest是94e3bb...而按 manifest 当前条目解析出的 watched 文件集合重算digest 应为e44865f09117c2ed040c2745cf741834f8cd6ea84e74a6d06b92d05d67002439证据manifest.yaml 中name-resolution/visibility.md条目第 689–709 行定义了 18 个 watched 路径slang-ast-modifier.h、slang-ast-decl.h、slang-ast-support-types.h、slang-check-decl.cpp、slang-check-modifier.cpp、slang-check-expr.cpp、slang-check-impl.h、slang-check-overload.cpp、slang-check-shader.cpp、slang-lookup.cpp、slang-diagnostics.lua、include/slang.h、slang-compile-request.cpp、slang-parser.cpp、core.meta.slang、hlsl.meta.slang、slang-ast-decl.cpp、slang-check-stmt.cpp执行python3 docs/generated/design/_meta/regenerate.py digest name-resolution/visibility.md返回的正是e44865f0...建议用当前 manifest 重新生成 front matter使 digest 记录为e44865f0...。这个发现解释了为什么报告摘要称最重要的工作流问题是 digest 不一致在regenerate.py list-stale的口径下digest 不一致即意味着文档对 watched 源文件而言过期是整条新鲜度链的入口信号。4.2 F-002languageVersion的初始化生命周期描述错误位置目标文档## Concepts第 64–82 行问题文档曾称ModuleDecl::languageVersion取自 module 声明上的版本或 linkage 默认值。实际上module声明本身不携带版本编译请求compile request从CompilerOptionName::LanguageVersion选项初始化该字段解析器parser随后在文件使用了需要现代版本的语法时把 legacy 值升级为 2025证据slang-compile-request.cpp 中从optionSet.getLanguageVersion()取值并赋给翻译单元的languageVersion报告中记录的旧行号为 324–339当前仓库中对应translationUnit-compileRequest-optionSet.getLanguageVersion()的读取点slang-parser.cpp 中定义静态函数maybeUpgradeLanguageVersionFromLegacy(SlangLanguageVersion)当前仓库第 1235 行并在第 1274、1406、1445 行对currentModule-languageVersion调用实现 legacy 到 2025 的按需升级建议准确描述选项集初始化 解析器升级两步若保留该生命周期细节还应把这两个文件加入watched_paths。这条发现的修复在补救报告 visibility.md.remediation.md 中确认完成slang-compile-request.cpp读取选项集语言版本并赋值给translationUnitSyntax-languageVersionslang-parser.cpp的maybeUpgradeLanguageVersionFromLegacy定义了 legacy→2025 升级且不被module声明解析路径触发。与之一致的现状是visibility.md 现文本已把该 bullet 改写为字段从编译请求的LanguageVersion编译器选项初始化parser 在文件使用现代构造时把 legacy 升级为 2025两步均位于本页 watched 路径之外并补充了SLANG_LANGUAGE_VERSION_LEGACY 2018、SLANG_LANGUAGE_VERSION_2025、SLANG_LANGUAGE_VERSION_2026、SLANG_LANGUAGE_VERSION_LATEST2026 的别名、SLANG_LANGUAGE_VERSION_DEFAULT为 legacy2018等常量事实。4.3 F-003GenericTypeConstraintDecl可见性规则的适用边界被过度概括位置### Per-keyword semantics第 118–120 行问题文档暗示所有GenericTypeConstraintDecl都继承其泛型内层声明的可见性。实际上getDeclVisibility只在约束声明的父节点是GenericDecl时才这样处理其他情况下返回Default证据slang-check-decl.cpp 中该函数先做asGenericDecl(decl-parentDecl)判断失败即返回DeclVisibility::Default报告行号 21258–21265建议把规则限定为属于GenericDecl的泛型参数与约束并明确其他父节点回落到Default。目标文档现文本已按此修正对一个GenericDecl父节点的泛型参数isGenericParam/GenericTypeConstraintDecl可见性取该泛型 inner 声明的可见性父节点为其他形状的GenericTypeConstraintDecl回落到Default。4.4 F-004_getTypeVisibility递归范围被夸大位置### Container-level cap第 241–256 行问题any generic type arguments任意泛型实参的表述夸大了_getTypeVisibility的行为它只对能asDeclRefType的实参递归而非对每个类型实参都递归证据slang-check-expr.cpp 中_getTypeVisibility的实参循环里确有if (auto typeArg asDeclRefType(arg))守卫当前仓库第 1110–1130 行附近与报告行号 1114–1120 对应——只有声明引用类型的实参才参与可见性最小值递归建议把any generic type arguments改为declaration-reference type arguments或精确说明该辅助函数遍历的操作数形状。这一点在当前目标文档中已体现为取底层声明可见性与其声明引用泛型实参可见性的最小值——递归只下沉到自身是DeclRefType的实参。4.5 F-005容器级上限规则对聚合声明的适用对象不精确位置### Container-level cap第 258–266 行问题文档称checkVisibility强制任何声明的可见性不得超过其父容器。但对聚合声明aggregate本身父节点查找从声明自身开始第一次比较就是自己 vs 自己所述父容器上限实际约束的是非聚合成员证据slang-check-modifier.cpp 中parentDecl decl初始化并在遇到第一个AggTypeDeclBase时停止报告行号 2375–2388当前仓库中对应// Next, we check that the decl does not have higher visiblity than its parent.之后的查找逻辑slang-check-decl.cpp 对 struct/class 调用该函数行号 3100–3109建议把断言收窄到非聚合成员不要承诺聚合声明也存在父容器检查除非实现变更。目标文档现文本已改为该函数同时强制一个声明的可见性不得超过最近的AggTypeDeclBase聚合。查找从声明自身开始因此聚合声明与自身比较上限实际作用于非聚合成员违例产生decl-cannot-have-higher-visibility代码 30601。4.6 F-006using声明接受的目标类型比namespace更宽位置## Edge cases and failure modes第 444–451 行问题文档说using声明只把 namespace 引入作用域但 checker 接受任意NamespaceDeclBase——包括 modulemodule 是namespace-like的证据slang-check-decl.cpp 中源码注释明确写着 namespace (or a module, since modules are namespace-like)且判定处测试的是NamespaceDeclBase行号 17332–17338、17360–17376建议改述为 using接受 namespace-like 目标含 module同时仍然拒绝单个声明。这一修正在目标文档现文本中可以看到Slang 中using声明只把一个namespace-like容器引入作用域——namespace 或 module因为 module 是 namespace-like 的并保留using SomeStruct;会被ExpectedANamespace30061拒绝的事实。5. 补救阶段哪些发现被修哪些被越界拒绝配套的补救报告 remediations/name-resolution/visibility.md.remediation.md 给出了最终处置5 fixed / 0 rejected-bogus / 1 rejected-out-of-scope / 0 deferred / 0 escalated前后 source commit 不变53b76e6d...即修复纯为措辞修正没有触碰源码。两条值得注意的治理细节F-001 被rejected-out-of-scope补救提示词 prompts/_remediate.md第 97–100 行规定watched_paths_digest的更新保留给操作员的mark-fresh运行remediator 不得编辑该字段。这形成了清晰的职责边界——内容性偏差由模型修新鲜度元数据由流水线 owner 修F-002 附带了一个后续动作把slang-compile-request.cpp与slang-parser.cpp加入watched_paths属于 manifest 变更超出补救阶段权限被显式标注为留给操作员处理注当前 manifest 中这两个文件实际已在 watched 列表里说明该后续动作已在后续 manifest 演进中落实。6. 可见性机制速览报告所守护的文档内容本身为了让你理解这 6 项发现守护的是什么这里给出 visibility.md 所描述的 Slang 可见性规则骨架完整细节以该文档为准三个关键字映射三个级别public任何 import 方模块可见、internal仅声明模块内可见、private仅声明所在的聚合类型内可见namespace 成员不算类型成员private会被invalid-use-of-private-visibility30603拒绝内部枚举DeclVisibilityslang-ast-support-types.h取值Private/Internal/Public及别名Default InternalMath::Min用于合成有效可见性按语言版本定默认值legacy 版本未标注声明一律public现代版本默认internal除非模块头部标注public module M;由checkModule把ModuleDecl::defaultVisibility翻转为publicnamespace 无条件Public两个过滤点lookup 边界filterLookupResultByVisibilityAndDiagnose全部候选被滤除时报decl-is-not-visible30600language-server 模式有意返回未过滤结果以维持补全与重载决议TryCheckOverloadCandidateVisibilityJustTrying静默丢弃、ForReal报同一诊断。两者共用同一谓词SemanticsVisitor::isDeclVisibleFromScope容器级上限getTypeVisibility取类型声明与声明引用泛型实参可见性的最小值带DictionaryType*, DeclVisibility记忆化仅缓存完成结果checkVisibility反向强制声明不得引用比自身可见性更低的类型use-of-less-visible-type30604并强制声明不超过最近的AggTypeDeclBasedecl-cannot-have-higher-visibility30601——F-004 与 F-005 修正的正是这两处表述与extern/export的区分ExternModifier成员被DeclPassesLookupMaskslang-lookup.cpp直接从 lookup 中剔除表现为找不到而非不可见ExportedModifier__exported import控制传递性跨模块可达性isModuleReachableViaExportedImports合成成员需求满足合成器用Math::Min(parentVisibility, requirementVisibility)赋可见性自动微分导数、微分类型等按getSynthesizedExtensionVisibility双字段规则处理——private目标映射为extension 为Internal、成员保持Private因为 extension 被提升到模块作用域后private非法。这 6 项 minor 发现全部落在上述断言的精度边界上生命周期归属F-002、适用条件F-003/F-005、递归守卫F-004、类型判定口径F-006外加新鲜度元数据F-001。它们没有任何一条动摇文档的规则骨架——这正是报告 Summary 一句 the page is complete, well structured, and link-clean, and most claims match the recorded source commit 的含义。7. 可复制的验证流程从 digest 到逐行号复核综合报告与 regenerate.py 的能力一条对任意 generated 设计文档做一致性核验的可复制流程如下路径均相对仓库根目录查看 manifest 条目与 watched 集合docs/generated/design/_meta/manifest.yaml中name-resolution/visibility.md条目给出 prompt、18 个 watched paths 与 depends_on重算 digestpython3 docs/generated/design/_meta/regenerate.py digest name-resolution/visibility.md与文档 front matter 的watched_paths_digest比对查看新鲜度与审查状态list-stale判定 digest 是否漂移review-status --show-counts读取 review-state.json 与 freshness.json 中记录的状态和严重度分布按 findings 表格逐条复核每条发现都有 Location文档内小节与行号、Evidence源文件与行号、Recommendation改法三列复核即打开 Evidence 指向的代码确认行为与描述一致本文第 4 节给出的当前仓库抽查结果与报告 Evidence 相符运行 linterlint子命令覆盖 front-matter 有效性、路径解析、表格合法性与体积上限本条目size_cap_bytes为 90112 字节。8. 局限与适用前提报告记录的source_commit53b76e6d...早于当前目标文档 front matter 中记录的更新提交文中所有行号引用均为报告在该提交上记录的行号当前仓库中函数位置已有平移如maybeUpgradeLanguageVersionFromLegacy现为第 1235 行报告中为 1221–1226 一带_getTypeVisibility的DeclRefType守卫现约在第 1110–1130 行区间。结论的形状函数名、守卫条件、控制流经当前仓库抽查仍然成立但精确行号以source_commit为准F-001 的 digest 不一致在报告产出时是当前 manifest 相对记录值的漂移信号manifest 与mark-fresh的运行会随仓库演进再次刷新该值因此digest 是否一致是一个随时间变化的检查项而非一次性结论本文所述流程仅适用于docs/generated/design/这套带_meta治理文件的生成文档家族仓库其他手写文档如docs/design/、docs/user-guide/不在这条 digest/审查/补救流水线内。【免费下载链接】slangMaking it easier to work with shaders项目地址: https://gitcode.com/GitHub_Trending/sl/slang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考