hyperframes 安装路径解析：从 `hyperframes.jsonpaths` 到 `add` 命令的目标重映射

hyperframes 安装路径解析：从hyperframes.json#paths到add命令的目标重映射

【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes

本篇技术指南聚焦 hyperframes 项目中 registry 条目的**安装位置（install locations）**机制：Block 与 Component 默认落在哪里、hyperframes.json#paths如何接管路径映射、以及hyperframes add在底层如何把registry-item.json中的target前缀重写为项目自定义目录。读完本文，你将掌握默认路径约定、路径重映射规则、配置文件结构与自定义布局的完整实操方法，并能从源码与测试层面理解这一机制的边界行为。

默认安装路径

hyperframes 的 CLI（hyperframes add）从 registry 拉取两类可安装条目：Block（整段可挂载到时间轴上的 HTML 合成）与Component（可粘贴进宿主合成的效果片段）。这两类条目的默认落盘位置由项目根目录下的hyperframes.json决定：

条目类型	默认安装路径	配置来源
Block	compositions/<name>.html	hyperframes.json#paths.blocks
Component	compositions/components/<name>.html	hyperframes.json#paths.components

以官方 registry 中的>{ "name": "data-chart", "type": "hyperframes:block", "files": [ { "path": "data-chart.html", "target": "compositions/data-chart.html", "type": "hyperframes:composition" } ] }

执行hyperframes add>export function remapTarget( item: RegistryItem, originalTarget: string, paths: { blocks: string; components: string }, ): string { if (item.type === "hyperframes:block") { const blocksDir = paths.blocks.replace(/\/+$/, ""); return originalTarget.replace(/^compositions\//, `${blocksDir}/`); } if (item.type === "hyperframes:component") { const componentsDir = paths.components.replace(/\/+$/, ""); return originalTarget.replace(/^compositions\/components\//, `${componentsDir}/`); } // Examples are installed by `init`, not `add` — no remapping. return originalTarget; }

从源码结构看，有几个值得注意的行为细节：

• 锚定默认前缀：重映射只匹配compositions/（Block）或compositions/components/（Component）这两个默认前缀。如果某个条目的target不以这些前缀开头，则原样透传（pass through unchanged）。对应测试见 packages/cli/src/commands/add.test.ts。
• 尾斜杠净化：paths.blocks/paths.components末尾的/会被剥离，避免拼接出scenes//data-chart.html这种双斜杠路径。
• Example 不参与：hyperframes:example类型由hyperframes init安装而非add，因此不做任何重映射。

target 路径的安全约束

registry-item.json schema 对target有明确限制：它必须是项目内的相对路径，不得包含..段、不得为绝对路径（含 Windows 盘符形式）。这保证了无论用户如何自定义paths，安装结果都始终留在项目目录内。

hyperframes.json 配置文件

hyperframes.json由hyperframes init自动创建。如果你在一个包含index.html的项目目录中直接运行hyperframes add而该文件尚不存在，CLI 也会以默认值创建它（见 packages/cli/src/commands/add.ts#L279-L284）。

默认配置内容如下：

{ "$schema": "https://hyperframes.heygen.com/schema/hyperframes.json", "registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry", "paths": { "blocks": "compositions", "components": "compositions/components", "assets": "assets" } }

这些默认值在源码中定义于 packages/cli/src/utils/projectConfig.ts#L79-L90 的DEFAULT_PROJECT_CONFIG，其中registry的默认 URL 定义在 packages/cli/src/registry/remote.ts#L30-L31。

各字段说明

字段	类型	默认值	说明
$schema	string	https://hyperframes.heygen.com/schema/hyperframes.json	JSON Schema 地址，供编辑器校验
registry	string（URI）	官方 registry base URL	拉取条目的基础地址；可指向私有或自建 registry
paths.blocks	string	compositions	hyperframes:block条目的落盘目录
paths.components	string	compositions/components	hyperframes:component条目的落盘目录
paths.assets	string	assets	资源文件（图片/字体/视频）的落盘目录
media.autoProxy	boolean	true	是否为浏览器不友好的视频编码（如 HEVC）自动生成 H.264 代理用于预览
authoringSkill	string	无	创作工作流 skill slug（如product-launch-video）
registryItems	array	无	hyperframes add安装过的目录条目清单

其中registry与paths是必填字段，其余均为可选。完整的字段约束见 docs/schema/hyperframes.json。

局部配置的默认补齐

配置读取采用了“部分配置补齐默认值”的策略：readProjectConfig之后会经过normalizeConfig（packages/cli/src/utils/projectConfig.ts#L139-L162），把缺失的字段逐一填回默认值。因此你可以在hyperframes.json中只写：

{ "registry": "https://your-private-host/registry" }

而paths.blocks、paths.components、paths.assets会自动回落为默认值，add照常工作。这一行为在 packages/cli/src/utils/projectConfig.test.ts 中有对应测试：只提供paths.blocks: "x"时，其余路径键保持默认。

此外，读取逻辑区分了三种状态ok | missing | unreadable（packages/cli/src/utils/projectConfig.ts#L105-L126）：文件缺失与 JSON 损坏被明确区分——配置损坏不会被当作“没有配置”而悄悄用默认值覆盖。

registryItems：安装清单的持久化

hyperframes add每次成功安装后，会把条目追加写入hyperframes.json的registryItems数组（按名称去重、仅追加），记录{ name, type, target }。由于安装下来的文件只是普通合成 HTML、不含来源标记，这份清单是判断“某个文件来自 registry”的唯一依据，渲染时也会读回它来统计成片实际用到了哪些目录条目。写入逻辑见 packages/cli/src/utils/projectConfig.ts#L309-L354 的recordProjectRegistryItems。

自定义目录布局

场景：把 Block 装进scenes/

假设你想让所有 Block 落在scenes/目录而非compositions/，在项目根目录的hyperframes.json中写入：

{ "paths": { "blocks": "scenes" } }

保存后执行：

hyperframes add><div>{ "paths": { "blocks": "src/scenes", "components": "src/fx" } }

此时add对 Block 使用src/scenes/前缀、对 Component 使用src/fx/前缀。测试 packages/cli/src/commands/add.test.ts#L214-L235 验证了compositions/my-block.html被重写为src/scenes/my-block.html、compositions/components/my-component/my-component.html被重写为src/fx/my-component/my-component.html的情形。

注意事项

• paths中未写出的键会自动使用默认值，无需全部重写。
• 重映射只针对默认前缀；若某条目 manifest 本身就把target写在其他目录（如elsewhere/），该路径不会被paths改写，会原样透传。
• 自定义路径必须是项目内的相对路径（无..、非绝对路径），受 registry-item schema 约束。

底层调用链速览

hyperframes add <name>的完整安装流程在runAdd（packages/cli/src/commands/add.ts#L275-L381）中按序执行，与路径相关的步骤为：

1. 加载配置：loadProjectConfig读取hyperframes.json，缺失且项目含index.html时自动创建默认配置；
2. 解析条目：resolveItemWithDependencies按config.registry拉取条目及其传递依赖（拓扑排序：依赖在前，目标条目在后）；
3. 兼容性门禁：安装前校验 CLI 版本与条目的minCliVersion匹配；
4. 目标重映射：对每个条目的每个files[].target调用remapTarget，按条目类型改写前缀；
5. 安装：按重映射后的目标写入磁盘（用户改过的文件默认保留，--force可覆盖）；
6. 持久化清单：recordProjectRegistryItems把安装记录追加进hyperframes.json#registryItems；
7. 输出 snippet：基于重映射后的相对路径生成挂载片段，默认复制到剪贴板（--no-clipboard跳过）。

需要特别说明的是，步骤 4 发生在所有文件写入之前：remapTarget只作用于target，registry-item.json中的path（registry 内源路径）不受影响，因此重映射不会破坏下载来源。

结语

hyperframes 的安装位置体系可以概括为三句话：registry 条目声明默认目标（target），项目配置覆盖目录前缀（paths），CLI 负责把两者合并为实际落盘路径。默认布局compositions/适合开箱即用的标准项目；通过hyperframes.json#paths的两种前缀规则，你可以把 Block 与 Component 自由安放到任何项目内目录，同时保持 snippet 与清单的一致性。理解remapTarget的“锚定默认前缀 + 尾斜杠净化 + 非匹配透传”实现，也能让你在遇到自定义布局未生效时快速定位原因——多半是条目的target前缀与默认值不一致所致。

【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes