Vfp.inspect()

asset.inspect() -> dict[str, object]

返回面向列表、日志和调度的轻量资产库存。它读取目录、META、PAL0 和必要的结构信息，但不恢复全部 VOX0、不重算 source hash，也不验证所有缓存内容。

返回结构

常用键包括：

键	类型	含义
gridSize / chunkSize	int	META 声明的立方网格和 chunk 边长。
solidVoxelCount	int	META 声明的非空体素数量，尚未从 VOX0 重算。
paletteCount	int	PAL0 条目数。
chunkCount	int	由网格和 chunk 尺寸推导的总 chunk 数。
fileBytes	int	文件长度。
sourceHash / generation	str / int	Header 声明的身份和活动目录代际。
sections	dict[str, dict[str, int]]	每种 tag 的数量、storedBytes、rawBytes。
caches	dict[str, bool]	THMB、PRVW、VBUF、PMSH、RND0、ANM0 等存在性。

示例：构建资产列表行

from voxelkit import Vfp

asset = Vfp.parse("library/tree.vfp")
info = asset.inspect()

thumb = "有缩略图" if info["caches"]["hasThumbnail"] else "无缩略图"
print(f"{info['gridSize']}³ · {info['solidVoxelCount']} voxels · {thumb}")
print(info["sections"].get("VOX0"))

示例：按缓存选择加载策略

info = asset.inspect()
if info["caches"]["hasPreviewMesh"]:
    print("可优先走 PMSH 预览路径")
else:
    print("需要从权威数据或其它缓存准备预览")

“存在”不等于“可用”：缓存可能与 source hash 不匹配或内容损坏。实际消费缓存前请用 validate()，并由对应运行时再次验证适配性。

异常与选择

META/PAL0 缺失、CRC 错误或结构无法解析会抛出 VfpError。若只要目录 tag，请用更轻的 section_tags()；若要可信的体素数、hash 或导出权限，请用 validate()。