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 the 0.3 project migration guide
kashorin03dc6a5eb250
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 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.1For 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 packagediff --git a/CONTRIBUTING.zh-CN.md b/CONTRIBUTING.zh-CN.mdindex 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.mdindex dc798363..8db48c41 100644--- a/README.md+++ b/README.md@@ -65,8 +65,9 @@ npx skills add hypit-ai/hypit -gThis installs the Skill. On first use, your agent checks for the Hypit executable and helps prepareit 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.mdindex 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.mdindex 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 infoinstall 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 extensiondiff --git a/docs/zh/guide/packages.md b/docs/zh/guide/packages.mdindex 113d44f1..fe603be4 100644--- a/docs/zh/guide/packages.md+++ b/docs/zh/guide/packages.md@@ -35,8 +35,8 @@ Skill、可执行 Distribution 和视频项目分别安装与更新。`@hypit/hySource 使用 `@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.mdindex 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 afterselecting 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 SVMLModule 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.mdnew file mode 100644index 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.