ZenFG

@zenfg/snapshot ​

@zenfg/snapshot 负责定义可移植、带版本的诊断约定，以便 在数据生成方和查看器之间传递已编译的 FrameGraph 帧。它提供 Snapshot 1.2 线协议类型、编解码器、验证器、JSON Schema、测试夹具、迁移工具和 一致性测试集，且不依赖 DOM、WebGPU 或 FrameGraph 运行时。

Snapshot 文件包含图结构和诊断信息，不包含 GPU 命令或 资源内容，因此无法重放帧。Snapshot 线协议版本与 此包的 API 版本相互独立。

Snapshot 1.1 输入会在迁移到 1.2 前先通过验证；其 CPU 计时 会标记为 not-collected。写入方和独立验证器只接受规范版 1.2。已有的 Legacy 来源信息和扩展字段会予以保留。

安装 ​

sh
npm install @zenfg/snapshot@0.1.1

Agent Skills ​

此开发版本随附英文 zenfg-snapshot Skill，用于指导 Snapshot 解码、验证、迁移以及生产者职责边界。 Skills 支持尚未发布：已发布的 0.1.1 包不包含此能力。 请使用明确随包提供 Skills 的发布版本，或从此分支构建的 tarball。

使用 pnpm 12.11.0 或更高版本（已验证 12.11.2），先将上述包安装为应用的直接依赖，然后运行：

sh
pnpm approve
pnpm install

在交互提示中批准此包的 Skills；构建脚本权限单独控制。pnpm 会将已批准的 Skills 链接到受支持的项目代理目录。如果没有合适的目录，请在安装前配置 skills.dirs。 目录选择和批准细节见 pnpm Agent Skills。 编程助手会读取链接的 Skill 及其引用的包内资料。

使用 @zenfg/snapshot 解析或验证不可信的 FrameGraph 捕获数据、规范化受支持的历史输入、完成生产者草稿的校验与分离，或序列化规范 Snapshot JSON。

快速入门 ​

请使用目标为 ES2022 或更高版本的 ESM TypeScript 项目。此包不需要 DOM 或 GPU 对象。将捕获的 Snapshot JSON 传给 normalizeSnapshot(jsonText)； 输入有效时会返回格式化后的规范 JSON，输入无效时会报告相应问题。

处理不可信的 JSON 文本时，请使用 parseFrameGraphSnapshot()。受支持的旧 格式会迁移为独立的规范 Snapshot 1.2 值：

ts
import {
	parseFrameGraphSnapshot,
	stringifyFrameGraphSnapshot,
} from '@zenfg/snapshot';

export function normalizeSnapshot(jsonText: string): string {
	const decoded = parseFrameGraphSnapshot(jsonText);
	if (!decoded.ok) {
		throw new Error(decoded.issues.map((issue) => issue.message).join('\n'));
	}
	return stringifyFrameGraphSnapshot(decoded.snapshot, { pretty: true });
}

解码和验证遇到不可信输入时会返回结构化问题，而不是 抛出原生 JSON 或克隆错误。序列化和生成方 收尾操作会在调用方试图写入无效规范数据时抛出 FrameGraphSnapshotValidationError，以拒绝 该数据。

解码、解析和收尾后的 Snapshot 中，对象均使用 null 原型， 包括扩展对象；数组仍是普通数组。继承的字段 和 getter 会被忽略。请使用 Object.hasOwn(object, key)，不要使用 object.hasOwnProperty(key)。这一变化只影响 JavaScript 对象原型，不会改变 Snapshot 字段或 JSON 线协议格式。

常见任务 ​

任务公共 API
解析不可信 JSON 文本parseFrameGraphSnapshot()
解码已解析但类型未知的值decodeFrameGraphSnapshot()
验证程序构造的规范数据validateFrameGraphSnapshot()
完成生产者草稿校验并返回独立副本finalizeFrameGraphSnapshot()
序列化规范 Snapshot 数据stringifyFrameGraphSnapshot()
处理生产者侧验证失败FrameGraphSnapshotValidationError
读取规范格式和版本FRAME_GRAPH_SNAPSHOT_FORMAT, FRAME_GRAPH_SNAPSHOT_VERSION
读取扩展深度上限FRAME_GRAPH_SNAPSHOT_MAX_EXTENSION_DEPTH
导入 JSON Schema@zenfg/snapshot/schema/v1.json

准确的返回联合类型、问题类型、线协议字段、默认值和失败条件 见随包源代码及类型声明保留的 TSDoc。

消费方与生成方的职责边界 ​

  • 消费方应使用 parseFrameGraphSnapshot() 处理文本，或使用 decodeFrameGraphSnapshot() 处理未知类型的值。两者都接受规范版 1.2 和 受支持的历史格式，会执行迁移并返回带判别字段的 结果。
  • 在内存中组装草稿的生成方应使用 finalizeFrameGraphSnapshot()。 它会移除值为 undefined 的可选属性， 验证 JSON 安全性和 Snapshot 语义，并返回独立的规范 数据。
  • validateFrameGraphSnapshot() 只检查规范数据，不会迁移 历史输入。
  • 未知格式和版本会被拒绝，直到实现明确的迁移逻辑。 读取方不得猜测其他线协议版本兼容。
  • 程序传入的输入按只读处理。解码、迁移和 收尾操作都不会修改调用方拥有的值。

完整的结构及跨字段约定见 SPEC.md 。JSON Schema 规定结构约束； 规范文档和一致性测试集则定义 引用关系、跨字段语义、迁移规则及稳定的问题报告行为。

Schema 与测试夹具 ​

通过 import attribute 导入已发布的 Draft 2020-12 Schema：

ts
import schema from '@zenfg/snapshot/schema/v1.json' with { type: 'json' };

消费方需要配置 JSON 模块解析，并使用支持 import attributes 的模块模式。已发布的测试夹具和一致性用例覆盖规范文档、 旧格式迁移、无效结构、无效语义、稳定键、分配、 计时及扩展深度边界。

Snapshot 文件通常使用 .fgsnapshot.json 扩展名。实体 ID 是带类型前缀的字符串；计数、大小和帧索引均为非负的 JavaScript 安全整数。

常见错误 ​

现象解决方法
将解析后的 JSON 当作可信 Snapshot 数据先通过 parseFrameGraphSnapshot() 或 decodeFrameGraphSnapshot() 处理。
旧格式输入未通过规范数据验证先解码以执行显式迁移；单独进行规范验证不会触发迁移。
生成方写入 undefined、非有限数或不受支持的值序列化前先收尾草稿，并处理 FrameGraphSnapshotValidationError 。
未知版本的字段看起来似乎兼容在读取方实现并测试显式迁移前拒绝该版本。
期望线协议模型中存在反向关系在消费方本地构建索引；协议只存储规范的单向引用。
期望通过 Snapshot 重放 GPU 工作改用应用负责的机制捕获命令或资源内容。

延伸阅读 ​

文档与版本 ​

包清单声明 @zenfg/snapshot 0.1.1. 注册表徽章显示当前发布渠道，并非已安装版本。

使用参考 ​

开源 / MIT 许可