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
从包验证开始
shaderpack-analyzer.exe pack validate ./MyPack --format json先查看退出码、valid 和 diagnostics。修复报告中对应的文件、JSON pointer、资源或程序 ID,再进行更具体的解释。
这些命令中的 ./MyPack 是你自己的包目录,不是网站提供的已下载示例。
按问题选择解释命令
shaderpack-analyzer.exe scene explain ./MyPack --include-inactive --format jsonshaderpack-analyzer.exe graph dump ./MyPack --contract 2 --include-inactiveshaderpack-analyzer.exe program interface ./MyPack --program "yourpack:post/present" --contract 2shaderpack-analyzer.exe data interface ./MyPack --format jsonyourpack:post/present 需要替换为自己包中真实存在的 Program ID。v5 Program interface 要显式选择合同 2;省略时仍可能使用旧接口投影。
不同的成功分别意味着什么
| 结果 | 可以说明什么 | 还需什么证据 |
|---|---|---|
| Schema 校验通过 | 结构满足对应 Schema | Loader 语义与版本化行为 |
| 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
可复现的排查顺序
- 记录宿主 commit、Manifest/ABI 版本、精确源码清单与选项。先运行 pack validate,按文件和 RFC 6901 JSON pointer 修复第一条错误。
- 用 scene explain 确认路由归属与 fallback;查看 graph 的资源、活动命令和 Program 闭包,再用合同 2 解释 v5 Program interface。
- 在创造世界加载同一份源码,导出当前已发布 generation 的报告,先匹配包/来源/选项,再解释设备证据。
- 修复后重跑原失败命令,再检查重载、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 有缺陷。