跳转到正文

Analyzer 与证据边界 ​

ShaderPackAnalyzer 使用生产 Loader 进行包验证,并提供 Schema、资源图、场景路由和公开接口解释。它能帮助你在运行游戏之前发现一批结构与语义问题。

获取当前工具 ​

本轮锁定工具身份为 docs-tools-f8aaa5c4-w1.1,平台为 Windows x64,自包含 .NET 运行时。当前二进制资产位于需要读取权限的 GitHub Release,尚不是匿名下载入口。

上游源码可通过 Gitea 公开仓库 取得。需要自行构建时,请检出本基线 commit,并按上游 Analyzer README 使用 .NET 10 SDK 构建。本文中的命令假定你已有经过版本核对的 shaderpack-analyzer.exe。

来源:Analyzer 构建、发布与命令说明 · f8aaa5c4

从包验证开始 ​

powershell
shaderpack-analyzer.exe pack validate ./MyPack --format json

先查看退出码、valid 和 diagnostics。修复报告中对应的文件、JSON pointer、资源或程序 ID,再进行更具体的解释。

这些命令中的 ./MyPack 是你自己的包目录,不是网站提供的已下载示例。

按问题选择解释命令 ​

powershell
shaderpack-analyzer.exe scene explain ./MyPack --include-inactive --format json
powershell
shaderpack-analyzer.exe graph dump ./MyPack --contract 2 --include-inactive
powershell
shaderpack-analyzer.exe program interface ./MyPack --program "yourpack:post/present" --contract 2
powershell
shaderpack-analyzer.exe data interface ./MyPack --format json

yourpack:post/present 需要替换为自己包中真实存在的 Program ID。v5 Program interface 要显式选择合同 2;省略时仍可能使用旧接口投影。

不同的成功分别意味着什么 ​

结果可以说明什么还需什么证据
Schema 校验通过结构满足对应 SchemaLoader 语义与版本化行为
Loader 验证通过指定包通过当前加载与语义检查驱动编译、链接和资源创建
离线 graph / interface 成功能解释所选输入的活动关系和接口实际设备与游戏上下文
驱动报告有效对应身份下有设备端观察场景、生命周期和画面验收
游戏画面与性能验收特定设备和场景下的观察其他设备与配置的覆盖

当前网站基线的检查保留 driverStatus=notProvided、mappingStatus=deferred、runtimeEvaluated=false 与 liveWorldVerified=false。单次离线成功不能将这些字段改写成已经实机验证。

一个真实诊断:DLTOOL2001 ​

原始 v5 指南的 docs verify-v5 会报告 DLTOOL2001:可重建指南中的三反引号代码块需要语言标记与 file=<relative-path>。该指南包含一段普通说明性 JSON 块,未满足这个提取合同。

网站保留原始失败,并另建有独立身份的 dawnlight-v5-guide-site-v1 变体。变体仅改变说明块的围栏并添加身份说明;七个文件块保持不变,抽取结果与锁定示例精确一致。

遇到这类诊断时,应检查输入文档的用途与代码块合同,避免将某个派生版本的成功当成原始输入已经成功。

来源:诊断代码参考 · f8aaa5c4

可复现的排查顺序 ​

  1. 记录宿主 commit、Manifest/ABI 版本、精确源码清单与选项。先运行 pack validate,按文件和 RFC 6901 JSON pointer 修复第一条错误。
  2. 用 scene explain 确认路由归属与 fallback;查看 graph 的资源、活动命令和 Program 闭包,再用合同 2 解释 v5 Program interface。
  3. 在创造世界加载同一份源码,导出当前已发布 generation 的报告,先匹配包/来源/选项,再解释设备证据。
  4. 修复后重跑原失败命令,再检查重载、resize 和返回 BuiltIn;保留旧报告作为历史。

配置修复实验提供三份完整的预期拒绝 ZIP,记录实际 DLMAN0001、file/pointer、失败 graph/interface 查询与修复成功。症状索引提供七条排查路线。

退出码与选项传输 ​

退出码 0 表示请求的检查成功;1 表示合同或输入失败;2 表示命令用法错误。即使退出 0 也要阅读 diagnostics。联合阅读 code、file 和 jsonPointer;空 pointer 可能指整个请求。fragment 诊断应保留实际来源,不能把所有位置都理解为根 Manifest。不要仅凭“未知 Provider”猜成 DLABI1002:实验中实际返回 DLMAN0001。

选项文件是以完整 option ID 为键的 JSON 对象,boolean/integer/number 应与声明一致。固定解析器区分整数与浮点 JSON token,number 端点应保留 1.0,而非整数 1。Scene、Program interface 和 Data 命令接受 --options;此基线 graph CLI 不消费该覆盖,应通过 JSON-RPC dawnlight/dumpGraph、合同 2、显式 inputs.options 请求分支图。不能把默认 CLI 图标成选定分支。

Schema 与编辑器关联、WorldFinal 快照、Scene/Data 报告形成完整工具路径。Program interface 合同 2 接收 Data report;driver-report inspect 接收 Scene report。报告种类传错属于合同错误,不能据此判定 shader 有缺陷。

作者文档 · Manifest v5 / Scene ABI v2