# 将已有项目升级到 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)；不需要额外的解析器包 |
| 主包原来的领域子路径不再导出 | 按下表迁移该组件的导入 |
| 找不到新的领域包 | 在实际导入它的包中声明并安装依赖 |
| 找不到 Ranking 或合作 Provider | 它们是可选包，不是默认依赖；在项目中安装所选包，例如 `npm install @hypit/ranking@^0.1.0` 或 `npm install @hypit/provider-hiapi` |
| 错误来自已安装的第三方包内部 | 选择已发布的迁移版本，或与用户明确约定源码修复 |
| 安装时报告 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`。