ui2v

ui2v Skill

UI2V は AI ワークフロー向けの 動画モーション素材ライブラリ です。ユーザーが HyperFrames のモーションパッケージを見つけ、インストールし、再利用し、共有できるようにします。実際の動画制作、プレビュー、レンダリングは HyperFrames が行います。

プロジェクトの位置づけ、README の文章、npm の紹介文、ウェブサイトの文章、ローンチやプロモーション用のテキストについては、references/positioning.md を参照してください。

メンタルモデル

HyperFrames authoring -> package folder -> ui2v login -> ui2v motion publish -> ui2v.com

レイヤー	ツール
作成／プレビュー／レンダリング	HyperFrames（/hyperframes および関連スキル）
検索／インストール／公開／同期	ui2v CLI（npm パッケージ @ui2v/cli、bin ui2v）

廃止された @ui2v/[email protected] の JSON レンダリング／プレビュースタック（doctor、validate、preview、render、animation.json、@ui2v/core、@ui2v/engine、@ui2v/producer）は使用しないでください。現在の @ui2v/cli パッケージはレジストリクライアントです。

タスクの振り分け

レジストリ関連の作業と CLI／パッケージのメンテナンスには、このスキルを使用してください。

• ui2v.com でモーションを公開／共有／インストール／検索する → このスキルと ui2v CLI を使用してください。
• UI2V CLI を修正または拡張する → packages/ui2v/src/cli を調べ、対象を絞ったテストを更新してから、以下のリポジトリ検証コマンドを実行してください。
• レジストリパッケージのメタデータを修正する、または公開に失敗した場合 → references/package-format.md と references/publish.md を参照してください。
• ウェブサイト、README、npm、プロモーション用の文章を更新する → references/positioning.md を参照し、パッケージは npm @ui2v/cli、bin コマンドは ui2v、npx コマンドは npx @ui2v/cli@latest ... として記載してください。
• プロジェクト構成を整理する → references/cleanup.md を参照し、従来の JSON レンダラーの例やスクリプトを削除するか、適切な移行先へ誘導してください。現在の UI2V の機能として紹介しないでください。
• リリースを準備または説明する → references/release.md を参照し、バージョン、テスト、ビルド、npm の紹介文を確認してください。

ユーザーがレジストリ関連の作業をしていない場合は、このスキル以外に振り分けてください。

• 動画コンポジションを作成／編集／プレビュー／レンダリングする → この CLI ではなく、HyperFrames のスキルを使用してください。
• 古い JSON 形式の ui2v プロジェクト → 古い JSON ツールチェーンを復活させないでください。HyperFrames パッケージに移行してから、ui2v で公開してください。

CLI バージョンの確認

現在の CLI の動作に依存する公開／インストール／同期を行う前に、次を実行してください。

ui2v --cli-version
npm view @ui2v/cli version

• CLI が見つからない場合 → インストールします：npm install -g @ui2v/cli@latest（または bun install -g @ui2v/cli）
• 最新版より古い場合 → ui2v upgrade（エイリアスは self-update）を実行するか、npm install -g @ui2v/cli@latest を実行してください。
• --no-input の場合、古い CLI が検出されると ui2v upgrade はインストールコマンドのみを表示し、ゼロ以外の終了コードで終了します。

npm view で確認できるのはメタデータのみです。CLI が見つからない、タスクに対して古すぎる、壊れている、またはユーザーから最新版を求められた場合を除き、定例の最初の手順としてアップグレードしないでください。

公開前に、このモノレポから次を実行してください。

cd packages/ui2v && bun run build && node bin/ui2v.js --cli-version

モノレポの開発ワークフロー

このリポジトリで CLI のソースを変更する場合：

bun install
bun run build
bun run test
bun run --filter "@ui2v/cli" verify
node packages/ui2v/bin/ui2v.js --help
node packages/ui2v/bin/ui2v.js --cli-version

作業中は、まず有用な範囲で最も絞り込んだテストを優先してください。

cd packages/ui2v
bun run test:src
bun run verify:build
bun run test:artifact

パッケージの構成

モーションフォルダーには、次のものが必要です。

• type: "hyperframes:block" を含む registry-item.json
• エントリーとなるコンポジション HTML（index.html または一覧に記載されたコンポジションファイル）
• 任意の assets/、README.md、サムネイル

詳細は references/package-format.md を参照してください。

プロジェクトの位置づけ

プロジェクトを紹介する際は、次のメッセージを基本として使用してください。

让 AI 帮你发现、安装和分享 UI2V 视频动效资源：
搜索并安装现成动效，发布原创作品，让动画像依赖一样轻松复用。

UI2V をレンダラーと呼ばないでください。役割の境界を明確にしてください。

• HyperFrames はモーションを作成、プレビュー、レンダリングします。
• UI2V は検索、インストール、公開、同期、確認のワークフローを通じて、完成したモーションパッケージを配布します。

公開の流れ

ui2v login
ui2v motion publish ./my-motion --version 1.0.0
# optional: ui2v sync

エイリアス：ui2v skill publish、旧コマンド ui2v publish。

チェックリストの全文は references/publish.md を参照してください。

リリースの流れ

npm リリースの準備には references/release.md を使用してください。依頼されたバージョンを先に確認し、ローカルで検証してから、公開またはバージョンの更新を行ってください。安易に公開やバージョン更新をしないでください。

よく使うレジストリコマンド

ui2v search "logo sting"
ui2v install <slug>
ui2v list
ui2v update --all
ui2v explore
ui2v inspect <slug>
ui2v upgrade

サイトに表示されるインストールコマンド：npx @ui2v/cli@latest install <slug>。

トラブルシューティングの手引き

• CLI が見つからない → @ui2v/cli をインストールし、ui2v --cli-version で確認します。
• CLI が古い → ui2v upgrade または npm install -g @ui2v/cli@latest を実行します。
• 認証に失敗する → ui2v login を実行します。自動化の場合は、ユーザーがトークンを提供した場合に限り ui2v login --token clh_... を使用します。
• 公開時にバージョンが拒否される → --version が有効なセマンティックバージョンであり、公開済みのリリースより新しいことを確認します。
• エントリー HTML が見つからない → index.html、最初の files[] 構成パス、または {name}.html を確認します。
• マニフェストの検証に失敗する → references/package-format.md を参照して、type: "hyperframes:block"、寸法、長さ、files[] を確認します。
• レンダリング／プレビューのリクエストがあった → UI2V コマンドの使用を中止し、HyperFrames に振り分けます。