HyperFrames v0.7.48 版本解析浏览器安装锁串行化与 TTS 文本文件兼容性修复【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframesHyperFrames v0.7.48发布于 2026-07-10是一次聚焦 CLI 稳定性的小版本迭代核心解决两个实际问题一是慢速 Chrome 下载不再因丢失安装锁而与另一个 HyperFrames 进程发生冲突二是恢复了hyperframes tts --text-file对既有 skills 与脚本的兼容性。本文以该版本发布说明为主体结合 packages/cli 下的源码实现与测试用例逐项拆解这两个修复背后的设计动机、底层机制与验证方式帮助读者理解 HyperFrames CLI 在浏览器运行时管理与文本配音工作流上的工程细节。版本概览一次针对 CLI 可靠性的定向修复v0.7.48 是 HyperFrames 在 v0.7.47 与 v0.7.48 之间的增量发布变更集中在packages/cli包内不涉及引擎、SDK 等其它模块。两条 Fixes 都属于「回归修复 并发安全加固」类型CLI恢复tts --text-file兼容性服务于基于文件的旁白narration工作流PR #2117CLI让慢速浏览器安装通过活跃锁心跳与可见等待进度保持串行化PR #2116。从源码结构看两个修复分别落在 packages/cli/src/commands/tts.ts 与 packages/cli/src/browser/manager.ts并有对应的测试文件 packages/cli/src/commands/tts.test.ts 与 packages/cli/src/browser/manager.test.ts 予以覆盖。下面分别深入。修复一恢复hyperframes tts --text-file兼容性问题背景文件式旁白工作流为何会断裂HyperFrames 的 TTSText-To-Speech命令基于本地 AI 模型 Kokoro-82M 生成语音是「HTML 写片、脚本配音」工作流中从文本到音频的关键一环。历史版本的 skills 与自动化脚本通过--text-file参数传入.txt文件路径来批量生成旁白在某个中间版本中该参数发生变化或被移除导致既有脚本直接报「未知参数」错误而中断。v0.7.48 以「兼容性别名compatibility alias」的形式将其恢复使旧脚本无需改动即可继续运行。参数解析--text-file与位置参数的协同在 packages/cli/src/commands/tts.ts 中命令定义了两个输入入口位置参数input直接传入要朗读的文本或一个.txt文件路径字符串参数--text-file显式指定.txt文件路径描述为 Read text from a .txt file (compatibility alias)。运行时的输入解析逻辑如下tts.ts#L93-L110const input args[text-file] ?? args.input; if (!input) { console.error(c.error(Provide text to speak, or use --list to see available voices.)); failCommand(); } let text: string; const maybeFile resolve(input); if (existsSync(maybeFile) extname(maybeFile).toLowerCase() .txt) { text readFileSync(maybeFile, utf-8).trim(); if (!text) { console.error(c.error(File is empty.)); failCommand(); } } else { text input; }关键点有三--text-file优先级高于位置参数??短路旧脚本把路径塞进--text-file的行为仍然成立输入统一走「先resolve成绝对路径 → 判断文件存在且扩展名为.txt→ 读取并trim()」的流程因此位置参数传文件路径同样有效读取到的文件为空时会明确报错并终止避免生成静音音频。测试验证兼容性别名被显式保护packages/cli/src/commands/tts.test.ts 中有一个专门针对该回归的用例它验证了两件事--text-file能通过assertKnownFlags的未知参数检查即它确实是命令声明的合法参数传入--text-file与--json后synthesize收到的是文件内容字符串如Legacy file input而非路径本身且默认语言回落到en-us。该测试通过vi.mock(../tts/synthesize.js)隔离真实模型推理只验证命令层的参数路由因此运行快且稳定适合作为兼容性契约的长期守护。完整参数速查让文件式配音真正可用结合 tts.ts 的参数定义与 packages/cli/src/tts/manager.ts 的实现hyperframes tts的完整用法如下参数类型说明默认值input位置参数要朗读的文本或.txt文件路径无与--text-file二选一--text-filestring从.txt文件读取文本兼容性别名无-o, --out, --outputstring输出文件路径speech.wav当前目录-v, --voicestring声音 IDaf_heart-s, --speedstring语速倍率合法范围 0.13.01.0-l, --langstring音素器语言省略时按声音 ID 前缀自动推断推断值--listboolean列出可用声音后退出false--jsonboolean以 JSON 输出结果false声音 ID 遵循 Kokoro 的语言性别_名字编码首字母表语言a美式英语、b英式英语、e西班牙语、f法语、h印地语、i意大利语、j日语、p巴西葡萄牙语、z中文次字母表性别f女声、m男声。inferLangFromVoiceId正是按该前缀映射推断音素器语言未知前缀回落到en-us见 manager.ts#L37-L59。--lang支持的值由SUPPORTED_LANGS限定en-us, en-gb, es, fr-fr, hi, it, pt-br, ja, zh。文件式旁白工作流的典型用法# 从脚本文件生成旁白v0.7.48 恢复的兼容写法 hyperframes tts --text-file narration.txt --voice bf_emma --output narration.wav # 等价的位置参数写法 hyperframes tts narration.txt --voice bf_emma --output narration.wav # 以 JSON 输出便于脚本解析结果时长、实际语言、输出路径 hyperframes tts --text-file narration.txt --json值得一提的是声音与--lang不一致例如用英语声音配法语音素化制造口音在实现中被视为合法的风格化手段只会打印一行提示而非报错tts.ts#L138-L146--speed若不在 0.13.0 区间或解析失败会直接报错退出tts.ts#L122-L125。模型与音色数据按需下载并缓存在~/.cache/hyperframes/tts/见 manager.ts#L6-L8。修复二浏览器安装的锁心跳串行化与等待进度反馈问题背景并发安装同一目录的竞态HyperFrames 的渲染依赖 Chrome Headless Shell。首次运行时 CLI 会通过puppeteer/browsers下载并解压固定的CHROME_VERSION构建当前源码中锁定为152.0.7977.30见 manager.ts#L38。但puppeteer/browsers的install()自带没有任何并发保护当两个 CLI 进程同时未命中缓存时它们会在同一目标目录同时解压。若其中一个解压被中断Ctrl-C、Windows 杀毒软件锁定、睡眠唤醒会留下一个「目录存在但二进制不完整」的安装——而doctor、lint、validate等检查只看文件是否exists会误报健康实际渲染时却可能静默产出全黑帧。v0.7.48 用「活动锁心跳」把慢速安装真正串行化并让等待方看到进度而不是死等。实现机制零依赖的跨进程互斥锁packages/cli/src/browser/manager.ts 中锁的实现刻意避开锁文件库利用mkdirSync(lockDir, { recursive: false })的原子性——目录已存在时抛EEXIST天然充当互斥量。关键常量与计时参数manager.ts#L58-L65const INSTALL_LOCK_DIR join(CACHE_ROOT_DIR, .chrome.install.lock); const INSTALL_RECLAIM_LOCK_DIR join(CACHE_ROOT_DIR, .chrome.install.reclaim.lock); const INSTALL_LOCK_TIMINGS { staleMs: 120_000, // 锁判定为过期的时间阈值 pollMs: 200, // 轮询间隔 heartbeatMs: 15_000, // 持锁方心跳刷新周期 waitNoticeMs: 10_000, // 等待方首次打印提示的间隔 };withInstallLock的完整流程manager.ts#L137-L189可拆为四段等待获取锁循环尝试tryAcquireDirLock失败则检查回收门锁、按pollMs休眠重试可见等待进度每waitNoticeMs打印一次[browser] Waiting for another hyperframes process to finish installing chrome-headless-shell (Ns elapsed)...让用户明白 CLI 并非卡死过期锁回收当锁的mtime超过staleMs或等待超过 deadline 时通过reclaimStaleInstallLock删除过期锁并重置 deadline继续竞争持锁心跳拿到锁后启动setInterval(touchInstallLock, heartbeatMs)定时刷新锁目录 mtimeunref()避免阻塞进程退出在finally中清除定时器并删除锁目录保证锁不泄漏。为什么需要「心跳」和「回收门」心跳解决的是「慢速下载被误判为死锁」的问题v0.7.48 之前的实现只凭持锁时长判断过期网络慢时下载可能超过阈值新进程会把还在正常下载的锁误删并重复下载、重复解压。加入每 15 秒一次的心跳后只要持锁进程活着锁的 mtime 就一直新鲜等待方会继续等待而不是抢锁。回收门.chrome.install.reclaim.lock解决的是多个等待方同时越过超时阈值的竞态如果没有门锁等待方 A 删掉过期锁并拿到新锁后等待方 B其旧 deadline 也已过期可能把 A 的新锁当过期锁删掉。实现上回收前先抢门锁串行化回收者且删除前再次检查 mtime避免误删他人刚赢得的锁注释见 manager.ts#L170-L177。另外还有reclaimAbandonedReclaimLock兜底进程可能死在持有门锁但尚未清理的窗口期若不老化门锁所有后续安装者会永远休眠。测试保障并发与超时行为被逐条锁定packages/cli/src/browser/manager.test.ts 用 mock 文件系统 假定时器精确验证了这些行为代表性用例包括并发 force 下载串行化两个ensureBrowser({ force: true })并发执行时断言maxActiveInstalls 1即同一时刻只有一个安装进程在跑且结束后锁目录被清理paths.has(HF_LOCK) false不泄漏锁成功下载后锁目录必须被删除否则会永久卡死后续所有渲染过期锁回收持锁超过staleMs时withInstallLock能回收并继续执行而不是无限等待不误删新鲜锁等待方 B 在旧 deadline 过期后不得删除等待方 A 刚获得的新锁慢而活跃的持锁者不被抢占第一个调用者持锁 120ms 期间第二个调用者必须等待最终maxConcurrent 1可见等待提示等待超过waitNoticeMs时控制台确实打印了包含 Waiting for another hyperframes process 的提示心跳失败不致命utimesSync抛 EACCES 时持锁进程继续运行心跳尽力而为过期回收作为兜底。这些测试把「并发竞态」「超时回收」「心跳保活」「提示可见性」四类行为固化为回归守护正是 v0.7.48 这次修复的验收标准。用户侧hyperframes browser子命令锁机制对外体现在 packages/cli/src/commands/browser.ts 的hyperframes browser命令族上# 查找或下载渲染所需 Chrome内部走 ensureBrowser withInstallLock npx hyperframes browser ensure # 清除陈旧/不完整的下载并重新下载force 会先清空受管缓存 npx hyperframes browser ensure --force # 打印浏览器可执行文件路径便于脚本化 npx hyperframes browser path # 删除缓存的 Chrome 下载 npx hyperframes browser clear浏览器解析的优先级为环境变量HYPERFRAMES_BROWSER_PATH/ 兼容别名PRODUCER_HEADLESS_SHELL_PATH→ 缓存下载puppeteer 缓存优先其次 HyperFrames 受管缓存→ 系统 Chrome → 自动下载manager.ts#L596-L646。ensure --force在withInstallLock内先清空~/.cache/hyperframes/chrome再下载避免两个并发--force互相删除对方在途的锁或未解压完的安装测试见 manager.test.ts#L351-L378。Linux ARM64如 DGX Spark、GB10、Jetson没有 Chrome Headless Shell 构建browser ensure会走apt-get install -y chromium-browser自动安装系统 Chromium 的专用流程manager.ts#L545-L588。总结v0.7.48 用两个小而准的修复诠释了 HyperFrames CLI 的稳定性取向tts --text-file的恢复以「兼容性别名 明确测试」的方式保护了既有配音脚本的资产价值浏览器安装锁则以「原子 mkdir 互斥 心跳保活 回收门 可见等待提示」的组合在不引入任何第三方锁依赖的前提下解决了慢速下载场景下的并发竞态。两者的共同点是都在用户最容易踩坑的边界旧脚本升级、慢网络并发上加固并且都配有对应测试用例作为长期契约。对于使用 packages/cli 构建自动化渲染管线的团队这两个修复直接降低了「文件式旁白脚本断裂」与「并发渲染互相踩踏」两类线上故障的概率。【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 HyperFrames v0.7.48 版本解析浏览器安装锁串行化与 TTS 文本文件兼容性修复【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframesHyperFrames v0.7.48发布于 2026-07-10是一次聚焦 CLI 稳定性的小版本迭代核心解决两个实际问题一是慢速 Chrome 下载不再因丢失安装锁而与另一个 HyperFrames 进程发生冲突二是恢复了hyperframes tts --text-file对既有 skills 与脚本的兼容性。本文以该版本发布说明为主体结合 packages/cli 下的源码实现与测试用例逐项拆解这两个修复背后的设计动机、底层机制与验证方式帮助读者理解 HyperFrames CLI 在浏览器运行时管理与文本配音工作流上的工程细节。版本概览一次针对 CLI 可靠性的定向修复v0.7.48 是 HyperFrames 在 v0.7.47 与 v0.7.48 之间的增量发布变更集中在packages/cli包内不涉及引擎、SDK 等其它模块。两条 Fixes 都属于「回归修复 并发安全加固」类型CLI恢复tts --text-file兼容性服务于基于文件的旁白narration工作流PR #2117CLI让慢速浏览器安装通过活跃锁心跳与可见等待进度保持串行化PR #2116。从源码结构看两个修复分别落在 packages/cli/src/commands/tts.ts 与 packages/cli/src/browser/manager.ts并有对应的测试文件 packages/cli/src/commands/tts.test.ts 与 packages/cli/src/browser/manager.test.ts 予以覆盖。下面分别深入。修复一恢复hyperframes tts --text-file兼容性问题背景文件式旁白工作流为何会断裂HyperFrames 的 TTSText-To-Speech命令基于本地 AI 模型 Kokoro-82M 生成语音是「HTML 写片、脚本配音」工作流中从文本到音频的关键一环。历史版本的 skills 与自动化脚本通过--text-file参数传入.txt文件路径来批量生成旁白在某个中间版本中该参数发生变化或被移除导致既有脚本直接报「未知参数」错误而中断。v0.7.48 以「兼容性别名compatibility alias」的形式将其恢复使旧脚本无需改动即可继续运行。参数解析--text-file与位置参数的协同在 packages/cli/src/commands/tts.ts 中命令定义了两个输入入口位置参数input直接传入要朗读的文本或一个.txt文件路径字符串参数--text-file显式指定.txt文件路径描述为 Read text from a .txt file (compatibility alias)。运行时的输入解析逻辑如下tts.ts#L93-L110const input args[text-file] ?? args.input; if (!input) { console.error(c.error(Provide text to speak, or use --list to see available voices.)); failCommand(); } let text: string; const maybeFile resolve(input); if (existsSync(maybeFile) extname(maybeFile).toLowerCase() .txt) { text readFileSync(maybeFile, utf-8).trim(); if (!text) { console.error(c.error(File is empty.)); failCommand(); } } else { text input; }关键点有三--text-file优先级高于位置参数??短路旧脚本把路径塞进--text-file的行为仍然成立输入统一走「先resolve成绝对路径 → 判断文件存在且扩展名为.txt→ 读取并trim()」的流程因此位置参数传文件路径同样有效读取到的文件为空时会明确报错并终止避免生成静音音频。测试验证兼容性别名被显式保护packages/cli/src/commands/tts.test.ts 中有一个专门针对该回归的用例它验证了两件事--text-file能通过assertKnownFlags的未知参数检查即它确实是命令声明的合法参数传入--text-file与--json后synthesize收到的是文件内容字符串如Legacy file input而非路径本身且默认语言回落到en-us。该测试通过vi.mock(../tts/synthesize.js)隔离真实模型推理只验证命令层的参数路由因此运行快且稳定适合作为兼容性契约的长期守护。完整参数速查让文件式配音真正可用结合 tts.ts 的参数定义与 packages/cli/src/tts/manager.ts 的实现hyperframes tts的完整用法如下参数类型说明默认值input位置参数要朗读的文本或.txt文件路径无与--text-file二选一--text-filestring从.txt文件读取文本兼容性别名无-o, --out, --outputstring输出文件路径speech.wav当前目录-v, --voicestring声音 IDaf_heart-s, --speedstring语速倍率合法范围 0.13.01.0-l, --langstring音素器语言省略时按声音 ID 前缀自动推断推断值--listboolean列出可用声音后退出false--jsonboolean以 JSON 输出结果false声音 ID 遵循 Kokoro 的语言性别_名字编码首字母表语言a美式英语、b英式英语、e西班牙语、f法语、h印地语、i意大利语、j日语、p巴西葡萄牙语、z中文次字母表性别f女声、m男声。inferLangFromVoiceId正是按该前缀映射推断音素器语言未知前缀回落到en-us见 manager.ts#L37-L59。--lang支持的值由SUPPORTED_LANGS限定en-us, en-gb, es, fr-fr, hi, it, pt-br, ja, zh。文件式旁白工作流的典型用法# 从脚本文件生成旁白v0.7.48 恢复的兼容写法 hyperframes tts --text-file narration.txt --voice bf_emma --output narration.wav # 等价的位置参数写法 hyperframes tts narration.txt --voice bf_emma --output narration.wav # 以 JSON 输出便于脚本解析结果时长、实际语言、输出路径 hyperframes tts --text-file narration.txt --json值得一提的是声音与--lang不一致例如用英语声音配法语音素化制造口音在实现中被视为合法的风格化手段只会打印一行提示而非报错tts.ts#L138-L146--speed若不在 0.13.0 区间或解析失败会直接报错退出tts.ts#L122-L125。模型与音色数据按需下载并缓存在~/.cache/hyperframes/tts/见 manager.ts#L6-L8。修复二浏览器安装的锁心跳串行化与等待进度反馈问题背景并发安装同一目录的竞态HyperFrames 的渲染依赖 Chrome Headless Shell。首次运行时 CLI 会通过puppeteer/browsers下载并解压固定的CHROME_VERSION构建当前源码中锁定为152.0.7977.30见 manager.ts#L38。但puppeteer/browsers的install()自带没有任何并发保护当两个 CLI 进程同时未命中缓存时它们会在同一目标目录同时解压。若其中一个解压被中断Ctrl-C、Windows 杀毒软件锁定、睡眠唤醒会留下一个「目录存在但二进制不完整」的安装——而doctor、lint、validate等检查只看文件是否exists会误报健康实际渲染时却可能静默产出全黑帧。v0.7.48 用「活动锁心跳」把慢速安装真正串行化并让等待方看到进度而不是死等。实现机制零依赖的跨进程互斥锁packages/cli/src/browser/manager.ts 中锁的实现刻意避开锁文件库利用mkdirSync(lockDir, { recursive: false })的原子性——目录已存在时抛EEXIST天然充当互斥量。关键常量与计时参数manager.ts#L58-L65const INSTALL_LOCK_DIR join(CACHE_ROOT_DIR, .chrome.install.lock); const INSTALL_RECLAIM_LOCK_DIR join(CACHE_ROOT_DIR, .chrome.install.reclaim.lock); const INSTALL_LOCK_TIMINGS { staleMs: 120_000, // 锁判定为过期的时间阈值 pollMs: 200, // 轮询间隔 heartbeatMs: 15_000, // 持锁方心跳刷新周期 waitNoticeMs: 10_000, // 等待方首次打印提示的间隔 };withInstallLock的完整流程manager.ts#L137-L189可拆为四段等待获取锁循环尝试tryAcquireDirLock失败则检查回收门锁、按pollMs休眠重试可见等待进度每waitNoticeMs打印一次[browser] Waiting for another hyperframes process to finish installing chrome-headless-shell (Ns elapsed)...让用户明白 CLI 并非卡死过期锁回收当锁的mtime超过staleMs或等待超过 deadline 时通过reclaimStaleInstallLock删除过期锁并重置 deadline继续竞争持锁心跳拿到锁后启动setInterval(touchInstallLock, heartbeatMs)定时刷新锁目录 mtimeunref()避免阻塞进程退出在finally中清除定时器并删除锁目录保证锁不泄漏。为什么需要「心跳」和「回收门」心跳解决的是「慢速下载被误判为死锁」的问题v0.7.48 之前的实现只凭持锁时长判断过期网络慢时下载可能超过阈值新进程会把还在正常下载的锁误删并重复下载、重复解压。加入每 15 秒一次的心跳后只要持锁进程活着锁的 mtime 就一直新鲜等待方会继续等待而不是抢锁。回收门.chrome.install.reclaim.lock解决的是多个等待方同时越过超时阈值的竞态如果没有门锁等待方 A 删掉过期锁并拿到新锁后等待方 B其旧 deadline 也已过期可能把 A 的新锁当过期锁删掉。实现上回收前先抢门锁串行化回收者且删除前再次检查 mtime避免误删他人刚赢得的锁注释见 manager.ts#L170-L177。另外还有reclaimAbandonedReclaimLock兜底进程可能死在持有门锁但尚未清理的窗口期若不老化门锁所有后续安装者会永远休眠。测试保障并发与超时行为被逐条锁定packages/cli/src/browser/manager.test.ts 用 mock 文件系统 假定时器精确验证了这些行为代表性用例包括并发 force 下载串行化两个ensureBrowser({ force: true })并发执行时断言maxActiveInstalls 1即同一时刻只有一个安装进程在跑且结束后锁目录被清理paths.has(HF_LOCK) false不泄漏锁成功下载后锁目录必须被删除否则会永久卡死后续所有渲染过期锁回收持锁超过staleMs时withInstallLock能回收并继续执行而不是无限等待不误删新鲜锁等待方 B 在旧 deadline 过期后不得删除等待方 A 刚获得的新锁慢而活跃的持锁者不被抢占第一个调用者持锁 120ms 期间第二个调用者必须等待最终maxConcurrent 1可见等待提示等待超过waitNoticeMs时控制台确实打印了包含 Waiting for another hyperframes process 的提示心跳失败不致命utimesSync抛 EACCES 时持锁进程继续运行心跳尽力而为过期回收作为兜底。这些测试把「并发竞态」「超时回收」「心跳保活」「提示可见性」四类行为固化为回归守护正是 v0.7.48 这次修复的验收标准。用户侧hyperframes browser子命令锁机制对外体现在 packages/cli/src/commands/browser.ts 的hyperframes browser命令族上# 查找或下载渲染所需 Chrome内部走 ensureBrowser withInstallLock npx hyperframes browser ensure # 清除陈旧/不完整的下载并重新下载force 会先清空受管缓存 npx hyperframes browser ensure --force # 打印浏览器可执行文件路径便于脚本化 npx hyperframes browser path # 删除缓存的 Chrome 下载 npx hyperframes browser clear浏览器解析的优先级为环境变量HYPERFRAMES_BROWSER_PATH/ 兼容别名PRODUCER_HEADLESS_SHELL_PATH→ 缓存下载puppeteer 缓存优先其次 HyperFrames 受管缓存→ 系统 Chrome → 自动下载manager.ts#L596-L646。ensure --force在withInstallLock内先清空~/.cache/hyperframes/chrome再下载避免两个并发--force互相删除对方在途的锁或未解压完的安装测试见 manager.test.ts#L351-L378。Linux ARM64如 DGX Spark、GB10、Jetson没有 Chrome Headless Shell 构建browser ensure会走apt-get install -y chromium-browser自动安装系统 Chromium 的专用流程manager.ts#L545-L588。总结v0.7.48 用两个小而准的修复诠释了 HyperFrames CLI 的稳定性取向tts --text-file的恢复以「兼容性别名 明确测试」的方式保护了既有配音脚本的资产价值浏览器安装锁则以「原子 mkdir 互斥 心跳保活 回收门 可见等待提示」的组合在不引入任何第三方锁依赖的前提下解决了慢速下载场景下的并发竞态。两者的共同点是都在用户最容易踩坑的边界旧脚本升级、慢网络并发上加固并且都配有对应测试用例作为长期契约。对于使用 packages/cli 构建自动化渲染管线的团队这两个修复直接降低了「文件式旁白脚本断裂」与「并发渲染互相踩踏」两类线上故障的概率。【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考