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.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
docs: add Chinese migration guides and README links
rpone568268025acf
diff --git a/README.zh-CN.md b/README.zh-CN.mdindex 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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 和原始作品;+报告具体缺少的能力,不要承诺文件头检查成功就代表迁移完成。