HyperFrames v0.7.51HeyGen 路径标记与失败分类、技能更新收敛修复详解【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframesHyperFrames v0.7.51发布于 2026-07-11是一次聚焦可观测性与收敛性的维护性版本包含两项核心改进其一media-use技能的 HeyGen 解析链路开始标记每次调用走的是免费OAuth还是付费API-key路径并把失败统一分类为稳定的原因代码同时修复了测试隔离问题——本地运行不再可能触及生产遥测端点其二hyperframes skills update命令在上游技能被退役或重命名后能够收敛不再报Skill(s) still missing after install或陷入No matching skills found的循环而是把孤儿技能一并协调清理掉。读完本文你将理解这两条修复背后的源码级原理、遥测与失败分类的具体事件形状以及skills update的完整收敛链路。版本概览v0.7.51 的两个核心改动分别落在两个模块media-use技能Features为 HeyGen 转换新增用量遥测Usage telemetry使每次解析可区分免费/付费路径并输出稳定的失败原因分类。CLIFixes让skills update在上游技能退役时收敛不再因安装后仍缺失或找不到匹配技能而失败或死循环。两项修复均有对应的测试与源码佐证下文逐一展开。media-use 遥测标记 HeyGen 免费与付费路径media-use是 HyperFrames 仓库中负责音频/图片/视频素材解析的技能SKILL.md其核心入口是 resolve.mjs。v0.7.51 之前一次 HeyGen 调用走了免费还是付费路径对维护者是不可见的现在每次解析都会附带这一信息。免费OAuth与付费API-key两条路径从源码看这两条路径的区分点是凭据形态与请求头免费路径OAuth通过heygenCLI 的heygen auth login --oauth登录OAuth 会话会获得免费额度调用时以Authorization: Bearer携带访问令牌付费路径API-key直接使用$HEYGEN_API_KEY按 API 计费调用时以X-Api-Key携带密钥。两种请求都会附带X-HeyGen-Source: cli以便后端应用 CLI OAuth 免费额度见 requirements.md。heygen-cli.mjs中的常量也印证了这一设计HEYGEN_MIN_VERSION 0.3.0——v0.3.0 是首个支持 OAuth 会话的 CLI 版本低于它无法走免费路径因此--doctor会提示更新heygen-cli.mjs。遥测的落点PostHog 事件遥测实现位于 telemetry.mjs。它复用 CLI/Studio 的同一套身份体系从~/.hyperframes/config.json读取共享的anonymousId与 packages/cli 相同的路径与字段保证同一个人在 CLI、Studio、media-use 三处是同一个 PostHog 画像若已登录 HeyGen则通过$identify将匿名 ID 与账号邮箱/用户名关联邮箱统一转小写避免大小写差异导致同一人分裂成两个画像事件属性保持粗粒度——只记录媒体类型、解析来源、胜出的提供方绝不包含意图文本、文件名或路径同时设置$ip: null不记录 IP。发送是即发即弃fire-and-forget的1.5 秒超时TIMEOUT_MS任何失败离线、被拒、超时都被catch{}吞掉遥测永远不会阻塞或中断一次 resolve。每次调用前还会检查optedOut()HYPERFRAMES_NO_TELEMETRY1、DO_NOT_TRACK1、CI 环境或NODE_ENVdevelopment时直接跳过。关键事件形状结合 meta.md 与 resolve.mjs 中的调用点主要遥测事件包括事件含义属性示例media_use_resolve_miss某类型解析未命中type如 voice/imagemedia_use_provider_error提供方调用失败provider: heygen、reason稳定原因码media_use_doctor_run--doctor自检执行检测结果摘要这类聚合数据用于维护侧的使用量看板telemetry-dashboard.md 给出了看板的可复现定义同时本地仍可用resolve --stats查看不含隐私字段的意图级统计。失败分类稳定的原因码v0.7.51 的另一半是把 HeyGen 失败统一分类为稳定原因而不是把 CLI 的原始 stderr 直接抛给用户。分类器位于 heygen-cli.mjs 的classifyHeygenErrorResult输出五种稳定代码原因码判定依据源码中的匹配规则用户提示not_found仅当 spawn 报ENOENT或 shell 报command not found刻意收窄避免把 CLI 自身的资源错误如 voice not found 误判为 CLI 缺失引导安装 heygen CLInot_authenticatedstderr/stdout 含unauthorized、unauthenticated、\b401\b用词边界正则避免请求 IDreq-401abc误伤、not logged in、no api key、missing/invalid api key、login required等heygen auth login --oauthoutdated文本中解析出首个语义化版本号且低于0.3.0heygen updaterate_limited含rate limit、quota、insufficient credit、too many requests、throttled、\b429\b展示原始细节other兜底展示原始细节分类结果同时驱动两件事reportHeygenFailure输出可操作的提示信息对not_found/outdated还会暂存 remediation供resolve.mjs在退出前消费并上报media_use_provider_error遥测事件provider: heygenreason: 原因码。这样维护者看到的失败分布是稳定的分类计数而不是一堆难以聚合的原始报错文本。测试隔离修复本地运行不再触达生产遥测端点与遥测同批交付的是一个测试隔离修复。此前测试若依赖设置了DO_NOT_TRACK就不会发遥测这一假设一旦某个未来调用点或新测试忘记设置该环境变量就可能把测试流量发到生产 PostHog 端点。v0.7.51 的修复方式是提供一个显式的拦截缝隙telemetry.mjs 中的posthogHost()读取MEDIA_USE_TELEMETRY_HOST环境变量未设置时才回落到生产主机https://us.i.posthog.com测试通过把该变量指向本地http://127.0.0.1:port即可证明track()真的把请求发到了被覆盖的地址而不是仅仅相信DO_NOT_TRACK见 resolve.test.mjs 的 U7 隔离测试组以及 telemetry.test.mjs 对非测试上下文设置该变量时打印一次性 stderr 警告的验证安全网若该变量意外泄漏进真实用户的 shelltrack()会把事件发往一个很可能已死的主机而postBatch()的catch{}会静默吞掉失败——因此代码在非测试/CI 上下文会向 stderr 输出一次警告提示取消该变量telemetry.mjs 第 48-57 行。这一设计的本质是测试必须显式选择真实 HTTP 目的地从机制上保证本地与 CI 的每次运行都不可能到达生产遥测端点。skills update收敛修复上游技能退役后不再失败或死循环问题背景HyperFrames 的 CLI 通过skills子命令skills.ts管理 AI 编码工具的技能安装其保证是hyperframes skills check || hyperframes skills update这一 CI/Agent 契约。修复前存在两类典型故障Skill(s) still missing after install当某个技能在上游被退役或重命名后旧的本地铁定 manifest比如从过期的 hyperframes checkout 里解析出的skills-manifest.json仍列出该技能isCoreSkill会把它强行纳入安装目标但skills add正确地且静默地拒绝安装一个已不存在的技能随后的verifyInstalled就会 strict-throw——一个从未真实发生的失败却让更新失败。No matching skills found循环skills remove只为磁盘上存在对应 bundle的技能清理锁条目一个在上游退役、从未向本机派发过 bundle 的技能没有可删的 bundle删除调用变成静默 no-op锁条目残留于是每次运行都被重新标记为 removedcheck || update永远无法收敛相关说明见 skillsManifest.ts。修复后的收敛链路skills update现在的执行分两步对应源码中updateSkills与updateCommand的注释第一步canonical 目标选择。更新前调用checkSkills({ cwd, canonical: true })强制从规范发布仓库解析最新清单而不是本地 checkout 的skills-manifest.json。这保证一个已在上游退役/重命名的技能从一开始就不会出现在targets/toInstall里——从根源上消除了verifyInstalled对并不存在的缺失抛错的可能。若规范清单格式损坏能连上服务器但返回了坏结构代码会打印明确的警告区分上游/CDN 问题与你的网络问题并降级到仅在场presence-only模式完全离线时带--all的裸skills会降级为安装钉死的核心技能集绝不使用上游*通配符那会横扫仓库内部技能把 26 个技能全装进来而发布集只有 20 个。第二步removed 清理与孤儿锁自愈。安装成功后更新命令会再次以canonical: true运行 removed 检测--dir/--source仅作用于本次修剪的范围不改变安装来源对锁中归属本来源、但清单已不再发布的技能调用skills remove对从未派发过 bundle、删除后锁条目仍残留的孤儿技能调用pruneOrphanedLockEntries主动修剪锁条目并在输出中打印Reconciled N orphaned lock entr(y|ies) with no on-disk bundle两条安全护栏removed只包含锁记录为从本来源安装的技能绝不触碰用户自己的或其他来源的技能清理是尽力而为best-effort清理失败不会让更新失败——因为 CI 契约所 gate 的安装已经成功。整个收敛链路被设计为幂等的一次hyperframes skills check || hyperframes skills update之后安装状态与上游清单完全一致后续运行直接输出Installed skills are already up to date。命令形态速查hyperframes skills安装/刷新清单发布的全部技能显式全集。hyperframes skills check检查已装技能是否为最新非零退出码用于 CI gate支持--json、--dir、--source。hyperframes skills update更新核心集 所有已装技能并清理不再发布的技能可附加技能名如hyperframes skills update pr-to-video按需补装指定技能不加名字则不会扩张一次有意的部分安装--json模式下失败也会以 JSON 输出到 stdout便于 Agent 解析见 skills.ts 的reportUpdateFailure。离线时清单不可达update退化为在场保证 钉死核心集带strict的裸update会明确拒绝报告成功refusing to report success. Retry when online.。小结v0.7.51 用两个小而精的改动提升了 HyperFrames 的可观测性与收敛性media-use通过遥测区分免费/付费路径、以稳定原因码分类 HeyGen 失败并通过MEDIA_USE_TELEMETRY_HOST拦截缝隙保证测试永不触达生产端点CLI 的skills update通过 canonical 清单解析 孤儿锁自愈使上游技能退役/重命名不再造成失败或死循环。若你的工作流依赖skills check || skills update契约或正在为media-use排查 HeyGen 调用问题升级到 v0.7.51 即可获得上述行为相关实现的全部细节可在 skills.ts、telemetry.mjs 与 heygen-cli.mjs 中继续深挖。【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
HyperFrames v0.7.51：HeyGen 路径标记与失败分类、技能更新收敛修复详解
HyperFrames v0.7.51HeyGen 路径标记与失败分类、技能更新收敛修复详解【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframesHyperFrames v0.7.51发布于 2026-07-11是一次聚焦可观测性与收敛性的维护性版本包含两项核心改进其一media-use技能的 HeyGen 解析链路开始标记每次调用走的是免费OAuth还是付费API-key路径并把失败统一分类为稳定的原因代码同时修复了测试隔离问题——本地运行不再可能触及生产遥测端点其二hyperframes skills update命令在上游技能被退役或重命名后能够收敛不再报Skill(s) still missing after install或陷入No matching skills found的循环而是把孤儿技能一并协调清理掉。读完本文你将理解这两条修复背后的源码级原理、遥测与失败分类的具体事件形状以及skills update的完整收敛链路。版本概览v0.7.51 的两个核心改动分别落在两个模块media-use技能Features为 HeyGen 转换新增用量遥测Usage telemetry使每次解析可区分免费/付费路径并输出稳定的失败原因分类。CLIFixes让skills update在上游技能退役时收敛不再因安装后仍缺失或找不到匹配技能而失败或死循环。两项修复均有对应的测试与源码佐证下文逐一展开。media-use 遥测标记 HeyGen 免费与付费路径media-use是 HyperFrames 仓库中负责音频/图片/视频素材解析的技能SKILL.md其核心入口是 resolve.mjs。v0.7.51 之前一次 HeyGen 调用走了免费还是付费路径对维护者是不可见的现在每次解析都会附带这一信息。免费OAuth与付费API-key两条路径从源码看这两条路径的区分点是凭据形态与请求头免费路径OAuth通过heygenCLI 的heygen auth login --oauth登录OAuth 会话会获得免费额度调用时以Authorization: Bearer携带访问令牌付费路径API-key直接使用$HEYGEN_API_KEY按 API 计费调用时以X-Api-Key携带密钥。两种请求都会附带X-HeyGen-Source: cli以便后端应用 CLI OAuth 免费额度见 requirements.md。heygen-cli.mjs中的常量也印证了这一设计HEYGEN_MIN_VERSION 0.3.0——v0.3.0 是首个支持 OAuth 会话的 CLI 版本低于它无法走免费路径因此--doctor会提示更新heygen-cli.mjs。遥测的落点PostHog 事件遥测实现位于 telemetry.mjs。它复用 CLI/Studio 的同一套身份体系从~/.hyperframes/config.json读取共享的anonymousId与 packages/cli 相同的路径与字段保证同一个人在 CLI、Studio、media-use 三处是同一个 PostHog 画像若已登录 HeyGen则通过$identify将匿名 ID 与账号邮箱/用户名关联邮箱统一转小写避免大小写差异导致同一人分裂成两个画像事件属性保持粗粒度——只记录媒体类型、解析来源、胜出的提供方绝不包含意图文本、文件名或路径同时设置$ip: null不记录 IP。发送是即发即弃fire-and-forget的1.5 秒超时TIMEOUT_MS任何失败离线、被拒、超时都被catch{}吞掉遥测永远不会阻塞或中断一次 resolve。每次调用前还会检查optedOut()HYPERFRAMES_NO_TELEMETRY1、DO_NOT_TRACK1、CI 环境或NODE_ENVdevelopment时直接跳过。关键事件形状结合 meta.md 与 resolve.mjs 中的调用点主要遥测事件包括事件含义属性示例media_use_resolve_miss某类型解析未命中type如 voice/imagemedia_use_provider_error提供方调用失败provider: heygen、reason稳定原因码media_use_doctor_run--doctor自检执行检测结果摘要这类聚合数据用于维护侧的使用量看板telemetry-dashboard.md 给出了看板的可复现定义同时本地仍可用resolve --stats查看不含隐私字段的意图级统计。失败分类稳定的原因码v0.7.51 的另一半是把 HeyGen 失败统一分类为稳定原因而不是把 CLI 的原始 stderr 直接抛给用户。分类器位于 heygen-cli.mjs 的classifyHeygenErrorResult输出五种稳定代码原因码判定依据源码中的匹配规则用户提示not_found仅当 spawn 报ENOENT或 shell 报command not found刻意收窄避免把 CLI 自身的资源错误如 voice not found 误判为 CLI 缺失引导安装 heygen CLInot_authenticatedstderr/stdout 含unauthorized、unauthenticated、\b401\b用词边界正则避免请求 IDreq-401abc误伤、not logged in、no api key、missing/invalid api key、login required等heygen auth login --oauthoutdated文本中解析出首个语义化版本号且低于0.3.0heygen updaterate_limited含rate limit、quota、insufficient credit、too many requests、throttled、\b429\b展示原始细节other兜底展示原始细节分类结果同时驱动两件事reportHeygenFailure输出可操作的提示信息对not_found/outdated还会暂存 remediation供resolve.mjs在退出前消费并上报media_use_provider_error遥测事件provider: heygenreason: 原因码。这样维护者看到的失败分布是稳定的分类计数而不是一堆难以聚合的原始报错文本。测试隔离修复本地运行不再触达生产遥测端点与遥测同批交付的是一个测试隔离修复。此前测试若依赖设置了DO_NOT_TRACK就不会发遥测这一假设一旦某个未来调用点或新测试忘记设置该环境变量就可能把测试流量发到生产 PostHog 端点。v0.7.51 的修复方式是提供一个显式的拦截缝隙telemetry.mjs 中的posthogHost()读取MEDIA_USE_TELEMETRY_HOST环境变量未设置时才回落到生产主机https://us.i.posthog.com测试通过把该变量指向本地http://127.0.0.1:port即可证明track()真的把请求发到了被覆盖的地址而不是仅仅相信DO_NOT_TRACK见 resolve.test.mjs 的 U7 隔离测试组以及 telemetry.test.mjs 对非测试上下文设置该变量时打印一次性 stderr 警告的验证安全网若该变量意外泄漏进真实用户的 shelltrack()会把事件发往一个很可能已死的主机而postBatch()的catch{}会静默吞掉失败——因此代码在非测试/CI 上下文会向 stderr 输出一次警告提示取消该变量telemetry.mjs 第 48-57 行。这一设计的本质是测试必须显式选择真实 HTTP 目的地从机制上保证本地与 CI 的每次运行都不可能到达生产遥测端点。skills update收敛修复上游技能退役后不再失败或死循环问题背景HyperFrames 的 CLI 通过skills子命令skills.ts管理 AI 编码工具的技能安装其保证是hyperframes skills check || hyperframes skills update这一 CI/Agent 契约。修复前存在两类典型故障Skill(s) still missing after install当某个技能在上游被退役或重命名后旧的本地铁定 manifest比如从过期的 hyperframes checkout 里解析出的skills-manifest.json仍列出该技能isCoreSkill会把它强行纳入安装目标但skills add正确地且静默地拒绝安装一个已不存在的技能随后的verifyInstalled就会 strict-throw——一个从未真实发生的失败却让更新失败。No matching skills found循环skills remove只为磁盘上存在对应 bundle的技能清理锁条目一个在上游退役、从未向本机派发过 bundle 的技能没有可删的 bundle删除调用变成静默 no-op锁条目残留于是每次运行都被重新标记为 removedcheck || update永远无法收敛相关说明见 skillsManifest.ts。修复后的收敛链路skills update现在的执行分两步对应源码中updateSkills与updateCommand的注释第一步canonical 目标选择。更新前调用checkSkills({ cwd, canonical: true })强制从规范发布仓库解析最新清单而不是本地 checkout 的skills-manifest.json。这保证一个已在上游退役/重命名的技能从一开始就不会出现在targets/toInstall里——从根源上消除了verifyInstalled对并不存在的缺失抛错的可能。若规范清单格式损坏能连上服务器但返回了坏结构代码会打印明确的警告区分上游/CDN 问题与你的网络问题并降级到仅在场presence-only模式完全离线时带--all的裸skills会降级为安装钉死的核心技能集绝不使用上游*通配符那会横扫仓库内部技能把 26 个技能全装进来而发布集只有 20 个。第二步removed 清理与孤儿锁自愈。安装成功后更新命令会再次以canonical: true运行 removed 检测--dir/--source仅作用于本次修剪的范围不改变安装来源对锁中归属本来源、但清单已不再发布的技能调用skills remove对从未派发过 bundle、删除后锁条目仍残留的孤儿技能调用pruneOrphanedLockEntries主动修剪锁条目并在输出中打印Reconciled N orphaned lock entr(y|ies) with no on-disk bundle两条安全护栏removed只包含锁记录为从本来源安装的技能绝不触碰用户自己的或其他来源的技能清理是尽力而为best-effort清理失败不会让更新失败——因为 CI 契约所 gate 的安装已经成功。整个收敛链路被设计为幂等的一次hyperframes skills check || hyperframes skills update之后安装状态与上游清单完全一致后续运行直接输出Installed skills are already up to date。命令形态速查hyperframes skills安装/刷新清单发布的全部技能显式全集。hyperframes skills check检查已装技能是否为最新非零退出码用于 CI gate支持--json、--dir、--source。hyperframes skills update更新核心集 所有已装技能并清理不再发布的技能可附加技能名如hyperframes skills update pr-to-video按需补装指定技能不加名字则不会扩张一次有意的部分安装--json模式下失败也会以 JSON 输出到 stdout便于 Agent 解析见 skills.ts 的reportUpdateFailure。离线时清单不可达update退化为在场保证 钉死核心集带strict的裸update会明确拒绝报告成功refusing to report success. Retry when online.。小结v0.7.51 用两个小而精的改动提升了 HyperFrames 的可观测性与收敛性media-use通过遥测区分免费/付费路径、以稳定原因码分类 HeyGen 失败并通过MEDIA_USE_TELEMETRY_HOST拦截缝隙保证测试永不触达生产端点CLI 的skills update通过 canonical 清单解析 孤儿锁自愈使上游技能退役/重命名不再造成失败或死循环。若你的工作流依赖skills check || skills update契约或正在为media-use排查 HeyGen 调用问题升级到 v0.7.51 即可获得上述行为相关实现的全部细节可在 skills.ts、telemetry.mjs 与 heygen-cli.mjs 中继续深挖。【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
