HyperFrames v0.8.0 发布解读Plan v2 成为分布式云渲染默认传输协议【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframesHyperFrames v0.8.0发布于 2026-08-17正式确立了 Plan v2 内容寻址传输协议作为分布式云渲染默认传输的版本边界从该版本起AWS Lambda 与 GCP Cloud Run 上的分布式渲染默认走 Plan v2同时为旧任务保留显式的v1兼容选项。阅读本文后你将掌握 Plan v1/v2 两种分布式传输协议的本质差异、v0.8.0 的完整升级迁移步骤以及planProtocol参数在 SDK 层与云适配器层的真实语义。版本边界为什么是 v0.8.0v0.8.0 是 HyperFrames 为 Plan v2 划定的受支持版本边界supported version boundary。需要特别注意的是Plan v2 作为默认传输的行为并非在 v0.8.0 首次引入——v0.7.111 已经包含这一行为该版本发布说明明确记录分布式云渲染现在默认使用内容寻址的 Plan v2 传输并在升级期间保留显式 Plan v1 兼容见 releases/v0.7.111.md。v0.8.0 自身没有在 v0.7.111 基础上增加任何新的云运行时变更它的意义在于把经过验证的行为固化为可长期支持的协议边界让升级方有明确的版本锚点。从源码结构看这一先落地、后定型的节奏是刻意的v0.7.111 属于 canary 通道验证而 v0.8.0 正式对外宣告 Plan v2 为默认传输后续的新集成尤其是新接入云适配器的用户应以 v0.8.0 为起点。两种分布式传输协议的本质差异Plan v1 与 Plan v2 是 HyperFrames 分布式渲染流水线plan → renderChunk → assemble的两种传输载体两者的协议描述符定义在 packages/producer/src/services/distributed/planProtocol.ts属性Plan v1legacyPlan v2默认schemaVersion1PLAN_SCHEMA_VERSION2PLAN_V2_SCHEMA_VERSIONartifactLayoutplan-dir-v1整体执行目录content-addressed-plan-v2内容寻址布局hashSchemahyperframes-plan-hash-v1hyperframes-plan-manifest-hash-v2v1 是整体执行目录传输planner 把编译产物、视频帧、音频、元数据打包成一个完整的planDir/目录含plan.json、compiled/、video-frames/、audio.m4a、meta/整体搬运给所有 chunk worker 和 assembler。v2 则将传输与执行彻底分离传输根是一个小型不可变plan.json清单加上按 sha256 内容寻址的 blob 对象worker 只选择和物化自己角色真正需要的依赖子集再在验证过的本地布局上调用共享执行函数。值得注意的兼容性设计缺失协议描述符即视为 v1 布局。readPlanProtocol在plan.json没有protocol字段时会退回PLAN_PROTOCOL_V1前提是调用方能力声明acceptsLegacyV1WithoutDescriptor为true见DISTRIBUTED_RENDER_CAPABILITIES从而保留对描述符出现之前产生的 plan 目录的回放兼容。但一旦描述符存在就必须完整且被识别——静默猜测部分写入或更新版本的布局可能渲染出错误像素或让 assemble 消费错误工件因此readPlanProtocol会对缺失字段、未知描述符抛出类型化的PlanProtocolUnsupportedError错误码PLAN_PROTOCOL_UNSUPPORTED且该错误被明确标注为在同一 worker 上重试无法自愈的确定性失败。Plan v2 内容寻址传输的底层原理核心实现位于 packages/producer/src/services/distributed/planV2.ts其设计要点可以从源码直接读出清单 blob 两层结构PlanV2Manifest记录protocol描述符、planHashv2 清单摘要与本地执行计划哈希刻意区分、chunkCount、totalFrames、fps仅支持 24/30/60、width、height、format、ffmpegVersion、producerVersion以及带sha256/sizeBytes/chunks/assembler的artifacts数组。每个 artifact 通过assertSafeRelativePath拒绝绝对路径与..穿越manifest 通过hyperframes-plan-manifest-hash-v2\0前缀的规范 JSON 摘要做完整性校验。角色化依赖裁剪artifactTargets是 fail-safe 策略表——plan.json、meta/chunks.json、meta/encoder.json归所有 chunk 和 assemblermeta/composition.json、meta/videos.json、compiled/归所有 chunk音频只给 assemblervideo-frames/按 chunk 精确裁剪未知的未来执行文件默认同时发给两种角色多包含是安全的静默遗漏新执行依赖则不安全。listPlanV2ArtifactsForTarget据此过滤materializePlanV2Target先逐个verifyBlob校验大小与 sha256再原子发布物化目录并写入.hyperframes-plan-v2.json物化标记供执行前重校验。视频帧依赖的精确推导v2 通过引擎自身的FrameLookupTable在每个捕获的全局帧上求值推导出哪些帧属于哪些 chunkbuildVideoChunkDependencies实现exact-rendered-frames模式若缺失旧版视频元数据则显式回退到full-source-pack整源打包模式该模式记录在 manifest 的limitations.videoDependencyMode中。突破 2 GiB 单体上限v1 有PLAN_DIR_SIZE_LIMIT_BYTES默认 2 GB为适配 Lambda 10 GB/tmp预算并抛出PLAN_TOO_LARGEplanV2()通过buildLocalExecutionPlan(..., { executionPlanSizeLimitBytes: Number.MAX_SAFE_INTEGER })禁用该传输上限因为 v2 不再发射单体归档见 packages/producer/src/services/distributed/plan.ts 的PlanTooLargeError与PLAN_DIR_SIZE_LIMIT_BYTES定义。大视频源文件正是 v2 的主要受益场景。存储无关的发布接口planV2WithPublisher接受PlanV2ArtifactPublisher可写本地目录、S3、GCS 或其他持久 CAS以 16 并发批量putBlob成功后再commitManifest失败时abort()做 best-effort 清理。本地planV2()则用LocalPlanV2ArtifactPublisher直接落到目录。v0.8.0 升级迁移指南迁移的首要原则在发布说明中表述得很清楚先升级基础设施再升级 SDK 调用者期间保持各包版本一致。具体分为四步1. 先重新部署 AWS Lambda / SAM / CDK 基础设施从 0.8.0 开始先重新部署 AWS Lambda、SAM 或 CDK 基础设施到 0.8.0再升级 SDK 调用者到 0.8.0。这是因为 planner、chunk worker、assembler 三者的能力声明DISTRIBUTED_RENDER_CAPABILITIESplanner 生产 v1v2chunk/assembler 同时接受 v1v2 并接受无描述符的 legacy v1需要基础设施侧先就位旧基础设施搭配新 SDK 会产生能力错配。2. 重新部署 GCP Cloud Run 服务与工作流与 AWS 侧同理GCP Cloud Run 的服务与工作流也需先从 0.8.0 重新部署再升级 SDK 调用者。GCP 侧的planProtocol默认值与处理逻辑与 AWS 完全对称见下文。3. 理解planProtocol参数语义planProtocol是升级期间的核心开关其语义在 SDK 层表现为省略即默认 v2无论 AWS 还是 GCPSDK 未传planProtocol时均默认v2。在 packages/aws-lambda/src/sdk/renderToLambda.ts 中PlanProtocol: opts.planProtocol ?? v2被写入 Step Functions 执行输入packages/gcp-cloud-run/src/sdk/renderToCloudRun.ts 同样PlanProtocol: opts.planProtocol ?? v2。显式v1仍可用renderToLambda的planProtocol?: LambdaPlanProtocol注释明确写着默认为v2仅为兼容旧版单体计划传输才显式选择v1用于在旧工作排空期间维持兼容。服务端同样默认 v2AWS Lambda handler 的日志摘要packages/aws-lambda/src/handler.ts在plan、renderChunk、assemble三个分支均以event.PlanProtocol ?? v2归约事件renderChunk/assemble还会根据协议选择PlanV2ManifestS3Uriv2或PlanS3Uriv1作为工件定位字段GCP 的 packages/gcp-cloud-run/src/server.ts 逻辑完全一致。这也意味着事件输入中显式传递PlanProtocol: v1可以绕过 SDK 默认值这是升级窗口期回退到 v1 传输的兼容通道。4. 保持 producer、SDK 与云适配器包版本一致升级期间producer、SDKhyperframes/aws-lambda/hyperframes/gcp-cloud-run适配器必须保持在同一版本。原因在于 plan 协议描述符、manifest 摘要算法hyperframes-plan-manifest-hash-v2、以及planHash的规范 JSON 序列化都随包版本演进——混用版本会导致 chunk worker 上的PlanProtocolUnsupportedError或清单完整性校验失败PlanV2IntegrityError。v0.8.0 的 Catalog 变更除云运行时边界外v0.8.0 还包含一项目录Catalog变更移除了两个 AI UI 条目。这是纯内容性清理不影响分布式渲染协议与迁移路径但如果你在 Catalog 检索中依赖过被移除的条目需在升级时一并确认。升级验证建议小范围先行先在单条渲染上显式传planProtocol: v1保持旧路径再切换默认 v2 观察 S3/GCS 中是否出现plan.json清单 sha256 blob 布局而非整体 plan 目录这是最直观的传输切换信号。关注日志字段CloudWatch / Cloud Logging 中summarizeEvent输出的planProtocol字段会如实反映每次执行实际使用的协议可用于灰度期间的协议审计。版本一致性检查确认 producer、SDK、cloud adapter 的package.json版本号一致避免混用导致的能力/摘要不匹配。总体而言HyperFrames v0.8.0 是一次零运行时新代码的版本定型它将 v0.7.111 已验证的内容寻址 Plan v2 传输正式确立为默认并给出清晰的迁移顺序基础设施先行、SDK 后随、包版本对齐、v1作为排空期逃生舱。对从旧版本升级或新接入 AWS Lambda / GCP Cloud Run 的团队来说按上述顺序执行即可平滑落地。【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考