asset-audit

资源审计

测量文件大小和格式需要使用 Bash

此技能的报告要求提供文件大小与预算对比、纹理尺寸 （2 的幂）、音频采样率以及用于检测孤立资源的最后修改时间。 这些信息无法通过 Read/Glob/Grep 获取——需要使用 stat 或读取二进制文件头，因此上述只读测量命令（stat、 file、od、wc、du）已获预先批准；使用 Glob 列出文件。其他任何操作都需要先征求许可。

如果无法进行测量，该单元格必须填写 NOT ASSESSED，绝不能填写估算值。 用猜测填满的大小预算表比空表更糟： 它看起来像是有证据支持的结果。即使项目里确实有大量资源，这也是一种真实存在的伪造风险：如果模板要求填写工具允许列表无法得出数值的表格，完成报告的唯一办法就是编造数据。

---

输入不足——生成任何报告前先检查

如果此技能所需的输入不存在，答案应为“无法运行”，而不是填好的报告。 先检查；如果检查未通过，就停止。

1. 列出此技能会读取的输入（数据文件、先前的报告、性能分析器输出、测试结果、注册表、源代码）。
2. 为每项记录 FOUND 或 ABSENT，不要写“假定存在”。
3. 如果某一部分所需的任何输入为 ABSENT，该部分必须标记为 NOT ASSESSED — NO DATA。不要估算，不要从相邻的产物推断，也不要把必须填写的单元格留给下一个阅读模板的人。
4. 如果所有必需输入均为 ABSENT，停止并将整个结论标记为 NOT ASSESSED — NO DATA，同时说明缺少哪些内容，以及由哪个技能生成这些内容。

结论为 NOT ASSESSED 也算成功。 当没有数据时，这是对“数据说明了什么？”这一问题正确且有用的回答。此项规则要防止一种具体的失败模式：结论枚举中没有“无法运行”状态的报告会产生虚假的通过结果——例如，在没有资源且没有标准的项目上进行资源审计，却返回 COMPLIANT；或者在没有任何性能分析器数据、也从未设定预算的情况下，性能分析报告却称“相对于 16.67ms 预算，余量超过 99%”。

没有证据不等于证明不存在。 如果没有文件可供扫描，扫描结果中没有匹配项并不代表验证过任何内容。应说明实际发生的是哪一种情况——读者无法从绿色结果中判断。

---

阶段 1：阅读标准

阅读美术圣经的 Asset Standards 部分（design/art/art-bible.md）以及相关设计文档中的任何资源标准——大小预算和格式规则都来自这些文档。除非美术圣经另有说明，否则命名模式采用下文阶段 3 中的模式。按部分阅读美术圣经：使用 Grep 工具（模式 ^#，内容模式）查找标题，再使用带有 offset 和 limit 的 Read 工具读取该范围。

如果这两处都没有规定大小预算，或者不存在美术圣经，则 Size 部分应标记为 NOT ASSESSED — no size budget set，并在报告中列出 /art-bible，该文档的 Asset Standards 部分负责设定预算、格式和命名约定。

---

阶段 2：扫描资源目录

资源位于引擎的资源根目录下：Godot 为 assets/，Unity 为 Assets/，Unreal 为 Content/。根据 .claude/docs/code-root-resolution.md 确定引擎和代码根目录；阶段 3 中用于查找孤立资源和缺失资源的搜索将读取该代码根目录。如果无法确定，则停止： NOT ASSESSED — engine unresolved，并列出 /setup-engine。

使用 Glob 扫描资源根目录：

• Godot — assets/art/**/*、assets/audio/**/*、assets/vfx/**/*、 assets/shaders/**/*、assets/data/**/*
• Unity — Assets/**/*，排除脚本（*.cs、*.asmdef）和 *.meta 文件
• Unreal — Content/**/*.uasset 和 Content/**/*.umap

匹配到的文件数即为 Total assets scanned。如果没有匹配项，则针对已扫描文件的检查——Naming、Size、Format、Orphaned——均应标记为 NOT ASSESSED — no assets under <asset root>；缺失资源搜索仍需运行。

---

阶段 3：运行合规性检查

命名约定：

• 美术资源：[category]_[name]_[variant]_[size].[ext]
• 音频：[category]_[context]_[name]_[variant].[ext]
• 所有文件名都必须使用小写字母和下划线

这是 Godot 的约定。Unity 和 Unreal 使用 PascalCase 命名资源，因此在这些引擎中，只按美术圣经中规定的命名规则检查名称；如果没有规则，则 Naming 为 NOT ASSESSED — no naming rule for <engine>（命名为 /art-bible）。

文件标准：

• 纹理：尺寸为 2 的幂次方，格式正确（UI 使用 PNG，3D 使用压缩格式），且不超出大小预算
• 音频：采样率和格式正确（音效使用 OGG，音乐使用 OGG/MP3），且时长不超出限制。 file 可报告音频文件的格式和采样率，但无法报告其时长，而这里也没有预先批准的工具可用于此操作；因此，时长预算为 NOT ASSESSED — duration not measurable here，并注明其涵盖的文件。
• 数据：JSON/YAML 有效且符合架构要求

在 Unreal 中，资源文件（.uasset、.umap）不会保留其源文件的格式或尺寸，因此 Format 在此为 NOT ASSESSED；但仍会测量其大小。

**孤立资源：**在代码根目录中搜索对每个资源文件的引用。标记所有未被引用的文件。

**缺失资源：**在代码根目录中搜索资源引用，并确认对应文件存在。

两项搜索都需要代码：如果代码根目录中没有源文件，则 Orphaned 和 Missing 均为 NOT ASSESSED — no code to search。在 Unity 和 Unreal 中，大多数资源引用位于场景、预制件和其他资源中，而非代码中，因此代码中未提及的资源仍可能正在使用：在这两种引擎中，Orphaned 为 NOT ASSESSED。

---

阶段 4：输出审计报告

# Asset Audit Report -- [Category] -- [Date]

## Summary
- **Total assets scanned**: [N]
- **Naming violations**: [N]
- **Size violations**: [N]
- **Format violations**: [N]
- **Orphaned assets**: [N]
- **Missing assets**: [N]
- **Sections not assessed**: [none | each section and why]

## Naming Violations
| File | Expected Pattern | Issue |
|------|-----------------|-------|

## Size Violations
| File | Budget | Actual | Overage |
|------|--------|--------|---------|

## Format Violations
| File | Expected Format | Actual Format |
|------|----------------|---------------|

## Orphaned Assets (no code references found)
| File | Last Modified | Size | Recommendation |
|------|-------------|------|---------------|

## Missing Assets (referenced but not found)
| Reference Location | Expected Path |
|-------------------|---------------|

## Recommendations
[Prioritized list of fixes, one per violation, each naming the change — the
target resolution or compression for a size violation, the corrected name for a
naming violation, the target format for a format violation]

## Verdict: [NOT ASSESSED / COMPLIANT / WARNINGS / NON-COMPLIANT]

根据审计结果选择判定，按顺序匹配，命中首项即止：

• NON-COMPLIANT — 存在任何大小违规，或代码引用的资源不存在
• WARNINGS — 仅存在命名、格式或孤立资源相关问题
• NOT ASSESSED — 审计未覆盖其范围：完全没有数据（上述路径）、扫描的资源数为 0，或任何部分为 NOT ASSESSED — 注明具体部分。其优先级低于两个问题判定，因为已测出的违规比缺口更具可操作性；但高于 COMPLIANT
• COMPLIANT — 至少扫描了一个资源，所有部分均已评估，且没有发现问题

此技能为只读技能 — 仅生成报告，不会写入文件。

---

阶段 5：后续步骤

• 使用阶段 3 的模式（或美术圣经自行规定的模式）修复命名违规。
• 如果缺少标准，运行 /art-bible 以编写其 Asset Standards 部分。
• 经人工审核后，删除已确认的孤立资源。
• 运行 /content-audit，根据 GDD 指定的要求交叉核对资源数量。