Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

docs: add Chinese migration guides and README links

rpone568268025acf
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 8cc57339..aa54ae9c 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -206,7 +206,7 @@ Agent 会检查环境,索要这条视频需要的凭据,生成素材并构
</tr>
<tr>
<td>旧项目升级</td>
- <td><a href="./migrations/0.3.md">迁移指南</a></td>
+ <td><a href="./migrations/0.3.zh-CN.md">0.3 迁移指南</a> · <a href="./migrations/0.3.1.zh-CN.md">0.3.1 SDK 迁移指南</a></td>
</tr>
</table>
diff --git a/migrations/0.3.1.zh-CN.md b/migrations/0.3.1.zh-CN.md
new file mode 100644
index 00000000..92666cbe
--- /dev/null
+++ b/migrations/0.3.1.zh-CN.md
@@ -0,0 +1,86 @@
+# 将已有项目升级到 0.3.1
+
+[English](0.3.1.md)
+
+当项目需要从 0.3.0 SDK 升级,或选择 0.3.1 后出现组件导入错误时,请阅读本指南。
+新项目直接使用当前创作参考文档。
+对于 0.2.x Source 或更早的开发版项目,请先阅读 [0.3 项目迁移指南](0.3.zh-CN.md)。
+[安装参考](../skills/hypit/references/environment/distribution.md)说明安装范围与更新方式。
+
+此版本将视频领域 SDK 导入迁移到独立的 npm 包,保留 `@hypit/composition@1` 等逻辑 SVML Module 地址,
+并不转换项目的创作意图。已有 TypeScript 组件可能需要修改导入与依赖。
+升级已有作品前,应先说明这些修改;补丁版本号并不意味着这次 SDK 迁移与旧源码兼容。
+
+## 定位不匹配之处
+
+通过 `hypit version` 和 `hypit paths` 确认作品使用的可执行程序。
+对于项目本地安装,使用其包管理器的启动方式;npm 对应的命令是 `npm exec --no -- hypit version`。
+检查项目的 manifest、lockfile 和已安装依赖,包括 `packages/` 内各包的 manifest。
+例如,从项目根目录执行:
+
+```sh
+npm ls @hypit/hypit @hypit/video @hypit/studio @hypit/visual-track @hypit/script --all
+rg -n '@hypit/hypit/' packages --glob '*.{ts,tsx,js,mjs,cjs,json}' --glob '!node_modules/**' --glob '!dist/**'
+```
+
+这些包名是检查示例,不是安装清单。应根据报错中实际指向的包排查。
+项目选择的包优先于 Distribution 的默认包;更新全局可执行程序,不会更新项目显式声明的组件依赖。
+
+| 观察到的情况 | 应检查的修复方向 |
+| --- | --- |
+| 找不到 `@hypit/run-markup` | 使用[当前 Run 文件头](0.3.zh-CN.md#cannot-locate-installed-package-hypitrun-markup);不需要额外的解析器包 |
+| 主包原来的领域子路径不再导出 | 按下表迁移该组件的导入 |
+| 找不到新的领域包 | 在实际导入它的包中声明并安装依赖 |
+| 错误来自已安装的第三方包内部 | 选择已发布的迁移版本,或与用户明确约定源码修复 |
+| 安装时报告 peer 版本冲突 | 同时检查主包与报错包的要求,选择兼容的版本组合 |
+| 文件已更新,但运行中的 Studio 或 Worker 仍使用旧代码 | 检查当前进程和安装;在不影响正在进行的工作时重启该进程 |
+
+## 仅迁移领域 SDK 导入
+
+在 import、重新导出、动态 import 和类型 import 中,匹配完整的模块说明符:
+
+| 修改前 | 修改后 |
+| --- | --- |
+| `@hypit/hypit/caption` | `@hypit/caption` |
+| `@hypit/hypit/composition` | `@hypit/composition` |
+| `@hypit/hypit/generation` | `@hypit/generation` |
+| `@hypit/hypit/generation/model` | `@hypit/generation/model` |
+| `@hypit/hypit/html-program` | `@hypit/html-program` |
+| `@hypit/hypit/media` | `@hypit/media` |
+| `@hypit/hypit/narrative` | `@hypit/narrative` |
+| `@hypit/hypit/narrative-caption` | `@hypit/narrative-caption` |
+| `@hypit/hypit/narrative-temporal` | `@hypit/narrative-temporal` |
+| `@hypit/hypit/region-evidence` | `@hypit/region-evidence` |
+| `@hypit/hypit/spatial` | `@hypit/spatial` |
+| `@hypit/hypit/speech-evidence` | `@hypit/speech-evidence` |
+| `@hypit/hypit/temporal` | `@hypit/temporal` |
+| `@hypit/hypit/temporal/markup` | `@hypit/temporal/markup` |
+| `@hypit/hypit/timeline` | `@hypit/timeline` |
+
+通用宿主导入保持不变,例如 `@hypit/hypit/author`、`@hypit/hypit/producer` 和 `@hypit/hypit/protocol`。
+这张表只用于实际 SDK 导入路径,不用于 SVML 或 manifest 中的逻辑 `@1` 地址。
+修改组件源码,并重新构建它声明的 JavaScript 入口;修改生成的 `dist` 文件或已安装的 `node_modules`
+不能作为持久的源码修复。
+
+将每个新导入的领域包声明在该组件普通的 `dependencies` 中,包括其公开类型引用的包。
+这些包首次独立发布的版本是 `0.1.0`,因此可使用兼容范围 `^0.1.0`。
+使用新 SDK 的组件应将 Hypit 宿主兼容范围声明为从 `^0.3.1` 开始。
+保留项目的包管理器、依赖角色和 workspace 布局;把所有包都装到全局,不能满足组件自身的依赖。
+
+对于项目显式选择的已有官方领域包,检查各自发行版的要求。
+迁移后的 Track、Script、Model、Video 和 Studio 包使用 `0.2.0` 版本系列;原来的 `^0.1.1` 范围不会选中它。
+将受影响的显式依赖声明与主包一起更新。
+未变化的 Runtime、Credential Store、Kit 和 Speech Estimate 可以继续使用 `0.1.1`。
+使用包管理器更新现有 lockfile,并审查变化。
+`--force` 或 `--legacy-peer-deps` 等绕过 peer 依赖解析的选项,不能证明版本兼容。
+
+## 验证项目并保留已有产物
+
+遵循通用的[结果保留与验证步骤](0.3.zh-CN.md#6-保留可用结果并验证实际作品):
+重新构建修改过的组件,检查实际 Source/Run,审查 plan 和复用选择,
+然后在授权 Build 之前于 Studio 中检查作品。
+仅仅迁移 SDK 导入位置,并不是重新生成已接受媒体素材的理由。
+
+如果必需的第三方组件尚未发布迁移版本,且源码修复不在当前工作范围内,
+请让作品继续使用已知可用的 0.3.0 安装和 lockfile,直到可以迁移。
+保留这套配置时,明确固定可执行程序版本;`^0.3.0` 也允许安装 `0.3.1`。
diff --git a/migrations/0.3.zh-CN.md b/migrations/0.3.zh-CN.md
new file mode 100644
index 00000000..56c57b72
--- /dev/null
+++ b/migrations/0.3.zh-CN.md
@@ -0,0 +1,194 @@
+# 将已有项目迁移到 Hypit 0.3
+
+[English](0.3.md)
+
+当为 0.2.x 或更早的开发版编写的项目需要在 0.3 上运行时,请使用本指南。
+本文采用的具体目标版本是 `@hypit/[email protected]`。
+新项目应直接使用当前的创作参考文档,不要重新采用下文中的旧写法。
+
+| 当前项目的起点 | 需要检查的内容 |
+| --- | --- |
+| 0.2.x 或更早的源码检出版本 | 本指南中的文件头、创作关系、项目组件、Runtime 选择和可复用 Output;随后检查 0.3.1 的 SDK 变化 |
+| 正式发布的 0.3.0 | [0.3.1 的导入与依赖变化](0.3.1.zh-CN.md);不要默认整份作品都需要重写 |
+| 版本或来源不明 | 确认实际使用的可执行程序,检查报错指向的具体文件或导入 |
+
+本指南说明主要的迁移边界,并不是适用于所有历史包的自动转换器。
+有些变化只是精确替换标识符,有些则需要根据具体作品保留原有含义。只迁移作品实际使用的功能。
+
+## 1. 确认并保留作品
+
+修改正常工作的安装之前,保留 Sources、Recipes、Runs、项目包、`package.json`、lockfile、
+Runtime Profile、素材和 Results。为即将编辑的文件保留可恢复的副本。
+不要仅仅为了升级就覆盖凭据或替换已经接受的媒体素材。
+
+从项目目录确认实际使用的可执行程序:
+
+```sh
+hypit version
+hypit paths
+```
+
+如果已有项目本地的 npm 安装,使用 `npm exec --no -- hypit version`。
+如果采用本指南中的 npx 安装方式,使用 `npx @hypit/[email protected] version`。
+这些是不同的启动方式,不是三个安装步骤。同时检查项目显式声明的依赖:
+选择新的可执行程序,并不会更新项目中的旧组件包或 lockfile。
+
+[安装参考](../skills/hypit/references/environment/distribution.md)说明可执行程序、Skill 和项目各自独立的生命周期。
+如果 Agent 从旧 Skill 学到了过时语法,请通过该 Skill 自己的安装渠道更新它,并阅读当前说明。
+
+## 2. 安装缺失包之前,先检查文档的语法入口
+
+文件第一行选择语言解析器。文件后缀仍然是 `.svml`、`.svs` 或 `.svrun`。
+
+| 文档 | 旧文件头 | 0.3.0 和 0.3.1 的文件头 |
+| --- | --- | --- |
+| SVML Author | `<?svml using="@hypit/markup@1"?>` | 不变 |
+| SVRun | `<?svml using="@hypit/run-markup@1"?>` | `<?svml using="@hypit/markup/run@1"?>` |
+| 普通 SVS Recipe sheet | `<?svml using="@hypit/svs@1"?>` | `<?svml using="@hypit/recipe@1"?>` |
+| 文字模板 SVS | `<?svml using="@hypit/text/svs@1"?>` | 不变;TextTemplate sheet 继续使用 Text 的解析器 |
+
+这些是解析器的逻辑身份,不是 npm 包名与版本声明。官方 Distribution 已包含这些解析器。
+不要尝试安装旧解析器名称来解决解析问题。修改 sheet 的文件头只是选择解析器;
+还需要根据接收组件的当前接口检查 Recipe 属性。
+
+### `cannot locate installed package @hypit/run-markup`
+
+遇到此错误时,先只修改 Run 的文件头。例如,以 `take.video` 为目标的 Run 应写成:
+
+```xml
+<?svml using="@hypit/markup/run@1"?>
+<svrun version="1">
+ <author source="./swap8.svml"/>
+ <target output="take.video"/>
+</svrun>
+```
+
+保留实际的 Author 路径、Targets,以及已有的 Candidate 和复用声明。然后检查:
+
+```sh
+npx @hypit/[email protected] check swap8.svrun
+```
+
+这里 `npx` 选择可执行程序,`@0.3.1` 固定 npm 发行版本,`check` 检查 Source 和依赖图,不提交生成请求。
+Run 文件头解析成功,并不代表其 Author、所选包或 Targets 都有效;如果出现下一条具体诊断,请继续处理。
+
+这次解析器变更发生在正式发布 0.3.0 之前,并不是仅在 0.3.1 中漏发了一个包。
+API 凭据不影响解析器的查找。`hypit cli use` 选择已安装的命令贡献,不选择文档解析器;
+`hypit packages install` 不是当前支持的命令。
+如果确实缺少外部能力包,请使用项目的普通包管理器安装。
+
+## 3. 迁移作品中的关系,而不只是标签名称
+
+较大的 0.2 作品可能在修复文件头后成功解析,随后才暴露过时的 Surface 或输入。
+使用下表定位作品中负责相应功能的部分。这些条目不是全局查找替换规则。
+
+| 项目中的旧写法 | 现在需要表达的关系 | 当前用法 |
+| --- | --- | --- |
+| Program Space 声明或导入 | 显式声明 Clock、Timeline 和 Canvas;在选定的空间边界内构造 Frame | [Timeline](../skills/hypit/references/production/timeline.md)、[空间](../skills/hypit/references/production/spatial.md) |
+| 用语义 `Take` 条目装配 Timeline | 构造带有可解析 `end` 的 Timeline;规范化媒体的 Extent 可以决定具名 Window 的时长 | [Timeline 构造](../skills/hypit/references/production/timeline.md) |
+| 组件直接消费 Script Selection/Moment | 选择 Projection,发布具名绝对 Window/Instant,再把该值传给组件 | [时间](../skills/hypit/references/production/timing.md) |
+| Performance/Sound Track 隐式呈现 Timeline 中的素材 | 在 Visual Clip 和 Audio Clip 中显式放置规范化媒体,保留原有的画面与声音选择 | [Visual Clip](../skills/hypit/references/production/visual-clips.md)、[Audio Clip](../skills/hypit/references/production/audio-clips.md) |
+| Media Track 的 `Item`、呈现或播放预设 | 使用 Visual Track 的 Clip、Frame 和源时间采样重新表达这次素材呈现;检查原本想要的适配、裁切、截取、重复或停帧行为 | [Visual Clip](../skills/hypit/references/production/visual-clips.md) |
+| Media Pipeline 导入 | 使用 Media Operations 完成规范化和处理;检查每个 Surface 的输入和导出值 | [媒体](../skills/hypit/references/production/media.md) |
+| Caption 只接收 Script 内容和 Timeline | 通过显式绑定与 Projection 产生绝对 CaptionTiming,再向 Caption 组件提供文档和时间 | [字幕呈现](../skills/hypit/references/production/caption-presentation.md) |
+| Typography Track 及其旧 Recipe | 使用 Fine Text 或项目自己的文字组件;保留原有文字、Frame、样式和具名时间输入 | [字体与文字](../skills/hypit/references/production/fonts-and-text.md) |
+| Fonts Open 内置的字体家族名称 | 选择实际的 npm 字体依赖或本地字体文件,保留字体、字重、样式和所需字符覆盖 | [字体](../skills/hypit/references/production/fonts-and-text.md) |
+| Render Hyperframes | 通过 `@hypit/html-video@1` 将 Film 装配为 HtmlProgram/视频,并选择本地 HTML Provider 执行 | [渲染](../skills/hypit/references/production/rendering.md) |
+
+例如,语义段落不再是组件隐式解释的时间输入:
+
+```xml
+<semantic:Window id="proof-window" projection={story-time}
+ during={story.selection.proof}/>
+```
+
+消费者随后使用 `during={proof-window}`。这里 `semantic` 导入 `@hypit/narrative-temporal@1`,
+`story-time` 是显式 Projection,`story` 是拥有该 Selection 的 Script。
+Projection Map 将已对齐的局部时间域连接到等长的 Timeline Window;这些 Map 不放置画面或声音,
+画面和声音分别由 Visual Clip 与 Audio Clip 放置。
+如果原有意图就是直接编写时间,请继续将其保留为直接声明的具名时间值。
+
+对于从 Script 派生的字幕,时间适配器使用 Script 已经产生的数据:
+
+```xml
+<narrative-caption:Timing id="story-captions"
+ document={story.caption}
+ binding={story.caption-binding}
+ projection={story-time}/>
+```
+
+这里 `narrative-caption` 导入 `@hypit/narrative-caption@1`。
+将 `{story.caption}` 和 `{story-captions}` 分别传给当前 Caption 组件的 `document` 和 `timing`。
+不要把 Script 再抄写成第二份字幕文档。保留作者写出的 `||` Cue 边界和显示文字与口播文字的对应关系;
+所需的 Unit 时间必须能通过所选 Projection 获取。
+
+[小型作品示例](../skills/hypit/references/production/examples/production.svml)展示了当前素材、Clock/Canvas、
+规范化、Timeline、Projection、Visual/Audio、Film 和视频输出的完整连接。
+用它理解连接方式,不要用它替换已有作品的创作结构或重新生成已经接受的素材。
+通过 `hypit vocabulary <package>` 和所属包的 README 查看实际安装版本中精确的 Surface 与输出名称。
+
+## 4. 更新项目组件及其导入
+
+有些 0.2 SDK 不仅改了名称,也调整了职责。
+如果组件导入了 `author-kit`、`component-kit`、`endpoint-kit`、`runtime-kit`、`visual-ir`、
+`program-space` 或 `studio-adapter`,不能假定只替换前缀就能完成迁移。
+
+- 作者组件使用[组件创作](../skills/hypit/references/production/track-authoring.md)中说明的窄公共 API:
+ Author、Producer、Admission 和 Markup。
+- 视觉和音频值使用 Composition 及相关领域包。HTML 组件使用当前的 HtmlVisual/HtmlProgram 接口,
+ 不再使用旧 Hyperframes API。
+- Provider 使用 [Endpoint SDK](../packages/endpoint/README.md)及其实际的领域依赖。
+- 编辑器行为属于组件自己的 Companion,使用 [Studio Companion](../packages/studio-companion/README.md)。
+ 历史上的独立 `*-studio` 导入需要对照当前所属包的导出检查,不要猜测包名并安装。
+
+如果目标是 0.3.1,请应用精确的[领域 SDK 导入映射](0.3.1.zh-CN.md#仅迁移领域-sdk-导入)和依赖说明。
+修改组件所属的源码与 manifest,再重新构建它声明的 JavaScript 入口。
+保留现有包管理器,并审查 lockfile 的更新。
+对于第三方组件,选择已发布的迁移版本,或与用户明确约定源码修复;
+不要悄悄修改已安装的副本,就宣称项目已完成迁移。
+
+## 5. 分清项目选择、已安装代码与执行配置
+
+项目通过显式指定,或通过祖先目录中带有 `hypit.project: true` 的 `package.json` 选择。
+Run 的位置不会选择另一个项目。`hypit paths` 会报告当前使用的路径。
+
+通过 `hypit runtime use <profile>` 或命令的 `--runtime <profile>` 使用原本打算采用的 Profile。
+如果项目没有 Profile,`hypit runtime init` 可以创建起始配置;
+不要仅仅为了升级就用起始配置替换作品正常工作的配置。
+[Profile 参考](../skills/hypit/references/environment/profile.md)说明当前配置。
+
+检查旧 Profile 中的包名和适配器专属选项。本地执行使用 Runtime Local;
+HTML 渲染使用 `@hypit/provider-html-local`;本地媒体执行使用 `@hypit/media-local`;
+凭据选择使用本地或环境变量 Credential Store。
+在适用的情况下保留所选服务、账号和存储位置。
+历史上将存储与传输拆开的配置,不能直接当作当前本地 Profile 的配置使用。
+
+只有所选 Store/Provider 读取对应环境变量时,它们才会提供凭据。
+`.env` 文件或某个 API key 变量不能解决过时的 Source 导入。
+先处理语法和包错误,再根据所选 Provider 的实际配置诊断服务访问。
+
+## 6. 保留可用结果并验证实际作品
+
+不要重写旧 Result 文档,让它们看起来像是新类型。
+已有媒体文件通常可以复用,但旧的结构化媒体、对齐、字幕或编排值可能需要从保留的输入重新计算。
+决定如何处理之前,先检查它们的实际类型和数据。
+
+使用当前的 [Run Candidate](../skills/hypit/references/production/runs.md)选择兼容的已完成 Output。
+如果只能保留原始视频、音频或图片,就通过当前媒体路径接入实际文件,
+并执行新消费者所需的规范化或对齐。
+保留原始 Result 及其资源文件;不要复制 manifest 后就丢弃它们。
+不要因为名称相似,就假定所有旧 Blob 类型或结构化 `@1` 值都兼容。
+付费重新生成是单独的决定,不是迁移的默认步骤。
+
+使用作品选定的启动方式,逐步扩大验证范围:
+
+1. 使用各组件自己的构建命令,构建修改过的项目组件。
+2. 对实际 Source 和 Run 执行 `hypit check`,解决具体的包、Surface、引用和类型错误。
+3. 执行 `hypit plan <run> --runtime <profile>`,检查剩余请求和显式复用选择。
+4. 在 Studio 中打开实际 Run,检查时长、画面、声音、字幕和一个有代表性的片段。
+5. 只构建或导出用户指令授权的工作,并检查生成的视频。
+
+修改依赖或 Profile 后,留意[进程生命周期](../skills/hypit/references/environment/profile.md#know-when-a-change-takes-effect)。
+不要为了重启所有助手而打断正在进行的制作。
+如果迁移受阻,保留已知可用的可执行程序、依赖、lockfile 和原始作品;
+报告具体缺少的能力,不要承诺文件头检查成功就代表迁移完成。