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 the 0.3 project migration guide

kashorin03dc6a5eb250
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index cc4e1125..9ca610a7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -62,7 +62,8 @@ pnpm test # package and service-adapter tests
### SDK imports in 0.3.1
For an existing video project, follow the [Agent migration guide](migrations/0.3.1.md)
-for the exact import mapping, dependency update and verification steps.
+for the exact import mapping, dependency update and verification steps. Projects from 0.2.x or an
+older checkout should first use the [0.3 project migration](migrations/0.3.md).
Video-domain SDKs are independently installed packages. Component code using a former root subpath,
such as `@hypit/hypit/composition`, must import from `@hypit/composition` and declare that package
diff --git a/CONTRIBUTING.zh-CN.md b/CONTRIBUTING.zh-CN.md
index 724854dc..0e2832d9 100644
--- a/CONTRIBUTING.zh-CN.md
+++ b/CONTRIBUTING.zh-CN.md
@@ -56,7 +56,8 @@ pnpm test # 包与服务适配器测试
### 0.3.1 的 SDK 导入迁移
已有视频项目的准确导入映射、依赖调整与验证方法见
-[Agent 迁移指南](migrations/0.3.1.md)。
+[Agent 迁移指南](migrations/0.3.1.md)。从 0.2.x 或更早开发版本迁移的项目,先阅读
+[0.3 项目迁移指南](migrations/0.3.md)。
视频领域 SDK 改为独立安装的包。组件代码使用 `@hypit/hypit/composition` 等旧根子路径时,
需要改为从 `@hypit/composition` 导入,并在组件自己的 `dependencies` 中声明该包。
diff --git a/README.md b/README.md
index dc798363..8db48c41 100644
--- a/README.md
+++ b/README.md
@@ -65,8 +65,9 @@ npx skills add hypit-ai/hypit -g
This installs the Skill. On first use, your agent checks for the Hypit executable and helps prepare
it if needed. Your video project can live anywhere.
-Upgrading an existing project to 0.3.1? Give your agent the
-[migration guide](./migrations/0.3.1.md) before updating its installation and component dependencies.
+Upgrading an existing project to 0.3? Give your agent the
+[migration guide](./migrations/0.3.md) before updating its installation and project files.
+It also links to the specific 0.3.0 → 0.3.1 dependency changes.
Hypit is free to use; your Coding Agent and model services have their own accounts and charges.
HypiHub is our recommended hosted model service. You can also use your own API or local models;
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 87c52354..6346e751 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -65,8 +65,8 @@ npx skills add hypit-ai/hypit -g
这条命令安装 Skill。首次使用时,Agent 会检查 Hypit 可执行程序,并按需协助安装。
视频项目可以放在任意位置。
-已有项目要升级到 0.3.1?先把[迁移指南](./migrations/0.3.1.md)
-交给 Agent,再一起调整安装版本和组件依赖。
+已有项目要升级到 0.3?先把[迁移指南](./migrations/0.3.md)
+交给 Agent,再一起调整安装版本和项目文件。指南也包含 0.3.0 → 0.3.1 依赖调整的专门入口。
Hypit 本身免费使用;Coding Agent 和模型服务各有自己的账号与费用。
HypiHub 是我们推荐的托管模型服务,也可以使用你自己的 API 或本地模型。
diff --git a/docs/guide/packages.md b/docs/guide/packages.md
index 689ca6d7..2ce4b214 100644
--- a/docs/guide/packages.md
+++ b/docs/guide/packages.md
@@ -54,8 +54,9 @@ video uses those installed versions. Missing packages are reported with the info
install them.
When upgrading an existing production, read the selected release's migration notes before changing
-its executable or component dependencies. The [0.3.1 project migration guide](https://github.com/hypit-ai/hypit/blob/main/migrations/0.3.1.md)
-covers SDK import changes and verification while preserving existing material and Results.
+its executable or component dependencies. The [0.3 project migration guide](https://github.com/hypit-ai/hypit/blob/main/migrations/0.3.md)
+covers older project syntax and usage, and links to the 0.3.1 SDK import changes. Keep existing
+material and Results while verifying the migrated work.
## Write and share an extension
diff --git a/docs/zh/guide/packages.md b/docs/zh/guide/packages.md
index 113d44f1..fe603be4 100644
--- a/docs/zh/guide/packages.md
+++ b/docs/zh/guide/packages.md
@@ -35,8 +35,8 @@ Skill、可执行 Distribution 和视频项目分别安装与更新。`@hypit/hy
Source 使用 `@your-studio/scoreboard@1` 这样的逻辑 Module 地址。npm 安装的包版本决定实际实现,逻辑 `@1` 标识作者接口。视频 Build 使用这些已安装的版本;缺包时会报告安装所需的信息。
升级已有作品前,先阅读目标发行版的迁移说明,再调整可执行程序和组件依赖。
-[0.3.1 项目迁移指南](https://github.com/hypit-ai/hypit/blob/main/migrations/0.3.1.md)
-说明 SDK 导入调整与验证方法,保留已有素材和 Results。
+[0.3 项目迁移指南](https://github.com/hypit-ai/hypit/blob/main/migrations/0.3.md)
+说明旧项目语法与用法的迁移,并链接到 0.3.1 的 SDK 导入调整。迁移与验证时保留已有素材和 Results。
## 编写与分享扩展
diff --git a/migrations/0.3.1.md b/migrations/0.3.1.md
index 8470fd8b..782a6477 100644
--- a/migrations/0.3.1.md
+++ b/migrations/0.3.1.md
@@ -2,9 +2,9 @@
Read this when upgrading a project from the 0.3.0 SDK, or when its component imports fail after
selecting 0.3.1. Fresh projects use the current authoring references directly.
-Confirm that the selected release is available from the chosen registry or supplied release
-candidate before installing it. The [installation and update reference](../skills/hypit/references/environment/distribution.md)
-explains installation scope and updates.
+For 0.2.x Sources or older development projects, start with the [0.3 project migration](0.3.md).
+The [installation reference](../skills/hypit/references/environment/distribution.md) explains
+installation scope and updates.
This release moves video-domain SDK imports into independent npm packages. It retains logical SVML
Module addresses such as `@hypit/composition@1`; it does not translate the project's creative intent.
@@ -30,6 +30,7 @@ a global executable does not update the project's explicit component dependencie
| Observation | Likely repair to investigate |
| --- | --- |
+| `@hypit/run-markup` cannot be found | Use the [current Run header](0.3.md#cannot-locate-installed-package-hypitrun-markup); no extra reader package is needed |
| A former root domain subpath is not exported | Migrate that component's import using the table below |
| A new domain package cannot be found | Declare and install it in the package that imports it |
| The error originates inside an installed third-party package | Select an available migrated release, or explicitly arrange a source-level repair with the user |
@@ -78,17 +79,10 @@ Peer-resolution overrides such as `--force` or `--legacy-peer-deps` do not estab
## Verify the project, preserving produced work
-Build each changed component with its own build command, run `hypit check` on the production's
-Source and Run, then inspect `hypit plan <run>` with its selected Runtime. Confirm that existing
-Run Candidates still reuse the intended Outputs before any paid Build. Open the actual Run in
-Studio and check its tracks, captions and a representative passage. Compilation alone does not
-establish that the intended picture and sound are intact.
-
-Keep Sources, assets, Profiles, credentials, Results and accepted Run selections. SDK package
-relocation is not a reason to regenerate media. If an Output cannot be reused, inspect the specific
-type or selection error; regeneration is a separate production decision. After installation changes,
-follow [process lifetimes](../skills/hypit/references/environment/profile.md#know-when-a-change-takes-effect)
-for Studio and Runtime restarts.
+Follow the shared [result preservation and verification steps](0.3.md#6-preserve-usable-results-and-verify-the-real-production):
+rebuild changed components, check the actual Source/Run, inspect the plan and reuse selections,
+then review the work in Studio before an authorized Build. SDK import relocation alone is not a
+reason to regenerate accepted media.
If a required third-party component has no migrated release and a source repair is not in scope,
keep the production on its known-working 0.3.0 installation and lockfile until it can be migrated.
diff --git a/migrations/0.3.md b/migrations/0.3.md
new file mode 100644
index 00000000..0f63a346
--- /dev/null
+++ b/migrations/0.3.md
@@ -0,0 +1,200 @@
+# Move an existing project to Hypit 0.3
+
+Use this guide when a project written for 0.2.x or an earlier development checkout needs to run on
+0.3. The concrete target used here is `@hypit/[email protected]`.
+New projects should use the current authoring references, not recreate the old forms below.
+
+| Starting point | What to inspect |
+| --- | --- |
+| 0.2.x or an older checkout | Headers, authoring relationships, project components, Runtime selection and reusable Outputs in this guide; then the 0.3.1 SDK changes |
+| Published 0.3.0 | The [0.3.1 import and dependency changes](0.3.1.md); do not assume the whole work needs rewriting |
+| Version or origin unknown | Identify the active executable and inspect the actual file or import named in the error |
+
+This is a guide to the main migration boundaries, not an automatic converter for every historical
+package. Some changes are exact identifier replacements; others require preserving the meaning of
+the particular work. Migrate only the features that production uses.
+
+## 1. Identify and preserve the production
+
+Before changing a working installation, keep its Sources, Recipes, Runs, project packages,
+`package.json`, lockfile, Runtime Profile, assets and Results. Preserve a recoverable copy of the
+files being edited. Do not overwrite credentials or replace accepted media merely to upgrade.
+
+From the project directory, identify the executable actually used:
+
+```sh
+hypit version
+hypit paths
+```
+
+For an existing project-local npm installation, use `npm exec --no -- hypit version`.
+For the npx installation in this guide, use `npx @hypit/[email protected] version`. These are alternative
+launchers, not three installation steps. Inspect explicit project dependencies as well: choosing a
+new executable does not update a project's older component packages or its lockfile.
+
+The [installation reference](../skills/hypit/references/environment/distribution.md) explains the
+separate executable, Skill and project lifecycles. If the Agent learned obsolete syntax from an old
+Skill, update that Skill through its own installation channel and read its current instructions.
+
+## 2. Check the document's syntax entry before installing a missing package
+
+The first line selects the language reader. The suffix remains `.svml`, `.svs` or `.svrun`.
+
+| Document | Earlier header | Header in 0.3.0 and 0.3.1 |
+| --- | --- | --- |
+| SVML Author | `<?svml using="@hypit/markup@1"?>` | Unchanged |
+| SVRun | `<?svml using="@hypit/run-markup@1"?>` | `<?svml using="@hypit/markup/run@1"?>` |
+| Ordinary SVS Recipe sheet | `<?svml using="@hypit/svs@1"?>` | `<?svml using="@hypit/recipe@1"?>` |
+| Text-template SVS | `<?svml using="@hypit/text/svs@1"?>` | Unchanged; keep Text's reader for TextTemplate sheets |
+
+These are logical reader identities, not npm package/version specifications. The official
+Distribution includes these readers. Do not try to install the old reader name to make it resolve.
+Changing a sheet's header selects its reader; the receiving component's Recipe properties still
+need checking against its current interface.
+
+### `cannot locate installed package @hypit/run-markup`
+
+For this error, first change only the Run header. For example, a Run targeting `take.video` becomes:
+
+```xml
+<?svml using="@hypit/markup/run@1"?>
+<svrun version="1">
+ <author source="./swap8.svml"/>
+ <target output="take.video"/>
+</svrun>
+```
+
+Preserve the real Author path, Targets and any existing Candidate/reuse declarations. Then check it:
+
+```sh
+npx @hypit/[email protected] check swap8.svrun
+```
+
+Here `npx` selects an executable, `@0.3.1` fixes its npm release, and `check` checks the Source and
+graph without submitting generation. Successful Run-header parsing does not establish that its
+Author, selected packages or Targets are valid; address the next specific diagnostic if one appears.
+
+This reader change predates the published 0.3.0 release. It is not a 0.3.1-only package omission.
+API credentials do not affect reader resolution. `hypit cli use` selects installed command
+contributions, not document readers; `hypit packages install` is not a current command.
+For a genuinely missing external capability package, use the project's ordinary package manager.
+
+## 3. Migrate the work's relationships, not just tag names
+
+A larger 0.2 production may parse after the header repair and then expose obsolete Surfaces or
+inputs. Use the following table to locate the owning part of the work. These rows are not global
+search-and-replace rules.
+
+| Earlier form in the project | What to express now | Current usage |
+| --- | --- | --- |
+| Program Space declarations or imports | Declare the Clock, Timeline and Canvas explicitly; construct Frames within the chosen spatial bounds | [Timeline](../skills/hypit/references/production/timeline.md), [space](../skills/hypit/references/production/spatial.md) |
+| Timeline assembled from semantic `Take` entries | Construct a Timeline with a resolvable `end`; normalized media Extents can determine named Windows | [Timeline construction](../skills/hypit/references/production/timeline.md) |
+| Components consuming Script Selection/Moment directly | Choose a Projection, publish a named absolute Window/Instant, and pass that value to the component | [Timing](../skills/hypit/references/production/timing.md) |
+| Performance/Sound Tracks implicitly presenting Timeline material | Place normalized media explicitly in Visual Clips and Audio Clips, preserving the original picture and sound choices | [Visual Clips](../skills/hypit/references/production/visual-clips.md), [Audio Clips](../skills/hypit/references/production/audio-clips.md) |
+| Media Track `Item`, presentation or playback presets | Re-express the occurrence using Visual Track's Clip, Frame and source-time sampling; inspect the intended fit, crop, trim, repeat or hold behavior | [Visual Clips](../skills/hypit/references/production/visual-clips.md) |
+| Media Pipeline imports | Use Media Operations for normalization and processing; check each Surface's inputs and exported values | [Media](../skills/hypit/references/production/media.md) |
+| Caption supplied only with Script content and Timeline | Produce absolute CaptionTiming through an explicit binding and Projection, then supply document and timing to the Caption component | [Caption presentation](../skills/hypit/references/production/caption-presentation.md) |
+| Typography Track and its former recipes | Use Fine Text or the project's own text component; retain the intended text, Frame, style and named time inputs | [Fonts and text](../skills/hypit/references/production/fonts-and-text.md) |
+| Fonts Open's bundled family names | Select the actual npm font dependency or local font files, preserving face, weight, style and required glyph coverage | [Fonts](../skills/hypit/references/production/fonts-and-text.md) |
+| Render Hyperframes | Assemble the Film as an HtmlProgram/video through `@hypit/html-video@1`, with the local HTML Provider selected for execution | [Rendering](../skills/hypit/references/production/rendering.md) |
+
+For example, a semantic passage is no longer a component's implicit time input:
+
+```xml
+<semantic:Window id="proof-window" projection={story-time}
+ during={story.selection.proof}/>
+```
+
+The consumer then uses `during={proof-window}`. Here `semantic` imports
+`@hypit/narrative-temporal@1`, `story-time` is an explicit Projection, and `story` is the Script
+owning the Selection. Projection Maps connect aligned local domains to equal-length Timeline
+Windows; those Maps do not place the picture or sound. Visual and Audio Clips do that separately.
+Keep directly authored times as direct named time values when they express the original intention.
+
+For Script-derived captions, the timing adapter uses data already produced from the Script:
+
+```xml
+<narrative-caption:Timing id="story-captions"
+ document={story.caption}
+ binding={story.caption-binding}
+ projection={story-time}/>
+```
+
+Here `narrative-caption` imports `@hypit/narrative-caption@1`. Pass `{story.caption}` and
+`{story-captions}` as the current Caption component's `document` and `timing`. Do not retype the
+Script as a second subtitle document. Preserve authored `||` Cue boundaries and display/speech
+relationships; the required Unit timings must be available through the selected Projection.
+
+The [small production example](../skills/hypit/references/production/examples/production.svml)
+shows current materials, Clock/Canvas, normalization, Timeline, Projection, Visual/Audio, Film and
+video output together. Use it to understand wiring, not to replace the existing work's creative
+structure or regenerate its accepted material. Inspect `hypit vocabulary <package>` and the owning
+package's README for the exact installed Surface and output names.
+
+## 4. Update project components and their imports
+
+Some 0.2 SDKs changed responsibility as well as name. A component importing `author-kit`,
+`component-kit`, `endpoint-kit`, `runtime-kit`, `visual-ir`, `program-space` or `studio-adapter`
+cannot be assumed to migrate through a prefix replacement alone.
+
+- Author components use the narrow Author, Producer, Admission and Markup APIs described in
+ [component authoring](../skills/hypit/references/production/track-authoring.md).
+- Visual and audio values use Composition and the relevant domain packages. HTML components use
+ the current HtmlVisual/HtmlProgram interfaces, not the former Hyperframes API.
+- Providers use the [Endpoint SDK](../packages/endpoint/README.md) and their real domain dependencies.
+- Editor behavior belongs to the component's Companion, using
+ [Studio Companion](../packages/studio-companion/README.md). Separate historical `*-studio`
+ imports need checking against the current owner's exports, not installation by guessed names.
+
+For the 0.3.1 target, apply the exact [domain SDK import mapping](0.3.1.md#move-only-the-domain-imports)
+and dependency guidance. Fix the component's owning source and manifest, then rebuild its declared
+JavaScript entry. Keep the package manager and review its lockfile update. For third-party components,
+select an available migrated release or agree on a source repair; do not silently patch an installed
+copy and call the project migrated.
+
+## 5. Keep project selection, installed code and execution configuration separate
+
+The project is selected explicitly or through an ancestor `package.json` with `hypit.project: true`.
+The Run's location does not choose another project. `hypit paths` reports the active locations.
+
+Use an existing intended Profile through `hypit runtime use <profile>` or a command's
+`--runtime <profile>`. If the project has no Profile, `hypit runtime init` creates a starter;
+do not replace a production's working configuration with a starter merely to upgrade.
+The [Profile reference](../skills/hypit/references/environment/profile.md) owns current configuration.
+
+Review old Profile package names and adapter-specific options. Local execution uses Runtime Local;
+HTML rendering uses `@hypit/provider-html-local`; local media execution uses `@hypit/media-local`;
+credential selection uses the local or environment Credential Store. Preserve the chosen service,
+account and storage location where applicable. Historical split storage/transport configurations
+are not interchangeable with the current local Profile schema.
+
+Environment variables supply credentials only when the selected Store/Provider reads them. A
+`.env` file or a particular API key variable does not resolve an obsolete Source import. Resolve
+syntax/package errors first; diagnose service access against the selected Provider's actual setup.
+
+## 6. Preserve usable results and verify the real production
+
+Do not rewrite old Result documents to pretend they have new types. Existing media files can often
+be reused, while old structured media, alignment, caption or composition values may require
+recomputation from retained inputs. Inspect their actual types and data before deciding.
+
+Use current [Run Candidates](../skills/hypit/references/production/runs.md) to select compatible
+completed Outputs. If only a raw video/audio/image can be carried forward, admit that actual file
+through the current media path and perform the normalization or alignment the new consumers need.
+Preserve the original Result and its resource files; do not discard them after copying a manifest.
+Do not assume every old Blob type or structured `@1` value is compatible merely because its label
+looks similar. Paid regeneration is a separate decision, not a migration default.
+
+Verify in increasing scope using the production's selected launcher:
+
+1. Build changed project components with their own build command.
+2. Run `hypit check` on the actual Source and Run; resolve exact package, Surface, reference and type errors.
+3. Run `hypit plan <run> --runtime <profile>` and inspect the remaining requests and explicit reuse choices.
+4. Open the actual Run in Studio; check duration, picture, sound, captions and a representative passage.
+5. Build/export only the work covered by the user's instructions and inspect the resulting video.
+
+After dependency or Profile changes, account for
+[process lifetimes](../skills/hypit/references/environment/profile.md#know-when-a-change-takes-effect).
+Do not interrupt active production just to restart every helper. If migration is blocked, retain the
+known-working executable, dependencies, lockfile and original work; report the specific missing
+capability rather than promising that a successful header check completes the migration.