# 将已有项目迁移到 Hypit 0.3

[English](0.3.md)

当为 0.2.x 或更早的开发版编写的项目需要在 0.3 上运行时，请使用本指南。
本文采用的具体目标版本是 `@hypit/hypit@0.3.1`。
新项目应直接使用当前的创作参考文档，不要重新采用下文中的旧写法。

| 当前项目的起点 | 需要检查的内容 |
| --- | --- |
| 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/hypit@0.3.1 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/hypit@0.3.1 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` 不是当前支持的命令。
如果确实缺少外部能力包，请使用项目的普通包管理器安装。
Ranking 等可选组件和合作 Provider 不随默认安装提供。请在项目中安装所选包，
例如 `npm install @hypit/ranking@^0.1.0` 或 `npm install @hypit/provider-hiapi`；
仓库中带 lockfile 的示例按其 README 执行 `npm ci`。

## 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 和原始作品；
报告具体缺少的能力，不要承诺文件头检查成功就代表迁移完成。