1仕組みと動作原理
CLIライフサイクル全体を9ステップのループ（scaffold → catalogでブロック検索 → author → lint高速フィードバック → check最終ゲート → サブコンポジションのスナップショット → preview → 承認後render → 出力検証）として定義し、checkにはlintが含まれるため冗長な追加lintの実行を禁止する。
skills/hyperframes-cli/SKILL.md
run `npx hyperframes check`; it reruns lint before opening the browser.
目的：「いつどのゲートを使用するか」を明確に定め、エージェントがlintとcheckを重複実行する無駄なオーバーヘッドを防ぐ。checkが唯一維持管理される最終ゲートである。
catalog検索はローカル処理（ホスト層なし、アカウント不要、クエリテキストは外部送信されない）として明記し、「英語で検索する」「結果の有無で推測せずtierフィールドを確認する」ことをルールとして徹底する。
skills/hyperframes-cli/SKILL.md
Search is entirely local: there is no hosted tier, no account, and the query text is never sent anywhere.
目的：検索におけるプライバシー保証を指示に組み込み、2つのランキング方式（字面words / オンデバイスセマンティック）の違いとスコアの読み方（top_scoreはエビデンスであり閾値ではない）を明確にする。
checkの判定セマンティクスを明確に定義：恒常的な検出のみが終了コードを決定し、イン/アウトのアニメーション過渡期の検出は情報提供に留める。より厳密な判定が必要な場合は--strictを使用する。
skills/hyperframes-cli/SKILL.md
Persistent findings gate the exit code; transient entrance or exit findings are informational.
目的：エージェントが単一のインアニメーションのちらつきをブロッキング不具合と誤認したり、本物の欠陥を一時的な現象として見落としたりするのを防ぐ。ゲートの基準を推測に頼らず固定化する。
レンダリングを4つのパス（ローカル / HeyGenホスト型クラウド / セルフホストAWS Lambda / セルフホストGCP Cloud Run）に分類し、選定基準と「実行前にreferenceを読む」強制要件を提示する。
skills/hyperframes-cli/SKILL.md
Use cloud rendering when the user wants hosted rendering without local Chrome, FFmpeg, or AWS.
目的：「クラウド」をホスト型とセルフホスト型の責任モデルに分解する。LambdaはユーザーがすでにAWS環境を保有している場合にのみ適しており（cloud.mdに記載）、Cloud Runは明示的にGCPを必要とする場合にのみ使用する。
タイムラインの確認にはHTMLを1つずつ読むのではなく`timeline --json`を優先する。ネストされた行にはメインタイムラインに対する絶対時間（absStart/absEnd）と所属ファイルが含まれており、index.htmlを手作業で読むよりもトークン効率が高く高精度である。
skills/hyperframes-cli/SKILL.md
run `npx hyperframes timeline --json` instead of reading `index.html` and every sub-composition file
目的：「エビデンス収集」をファイル読み込みから構造化出力の照会へと切り替える。referenceには5つのjq/nodeワンライナー（絶対時間による再生中クリップの取得、IDによるファイル特定、ギャップや重複の検出など）も提供されている。
フィードバックをワークフローのファーストクラスとし倫理規定を設ける：成功後に1件送信、公開チャネル向けは必ずマスキング、評価に応じてCOMPOSITION_STRUCTUREプライバシーパックを添付、`--file-issue`はユーザーの同意を得た最小限の再現手順のみを公開する。
skills/hyperframes-cli/references/preview-render.md
**Feedback is submitted to a public channel — anonymize before sending.**
目的：「報告」の運用手順を厳密に定義し（絶対パスの削除、HF_*/PRODUCER_*変数の保持、再現できない場合でも最後の失敗コマンドを添付）、Issueが決して自動送信されないことを明確にする。
doctorのJSONモードは常にexit 0（「診断が完了した」ことを意味し、「環境に問題がない」ことではない）となるため、ペイロードの検証を必須ゲートとする。
skills/hyperframes-cli/SKILL.md
`doctor --json` always exits zero. Gate on its payload:
目的：「終了コード＝正常」という誤認を排除する。doctorはNode ≥22、CPU/メモリ/ディスク、FFmpeg/FFprobe、Chrome、Dockerなどをチェックし、npm latestとのバージョン比較を提供する。
ドキュメント自体に「実行すべきでないコマンド」を明記する：eventsはスキル自己申告用のテレメトリエンドポイント（テレメトリ読み取り用ではない）、validate/inspect/layoutは非推奨エイリアスであり、checkのみが保守される。
skills/hyperframes-cli/SKILL.md
Two entries in `hyperframes --help` are not part of the authoring loop, and reaching for them wastes a turn
目的：エージェントの無駄な試行錯誤を削減する。あわせてeventsはどのような引数を渡してもexit 0となり、機能面を持たないことを説明する。
「コマンド実行前に対応するreferenceを読む」ことを背景知識の参照ではなく必須の契約とする：11のコマンド領域それぞれに対応ファイルが存在し、スキル横断の必須参照（sub-composition/motion/keyframes/audio/media-use）も設ける。
skills/hyperframes-cli/SKILL.md
The following references and owning skills are mandatory command contracts, not optional background reading.
目的：SKILL.mdを「ループ＋規律」に凝縮し、詳細をreferenceに委ねることで、read-before-runを通じてパラメータやエラーコードが記憶から捏造されるのを防ぐ。
2コア機能
01プロジェクトのスキャフォールディングとサイトキャプチャ：initによるプロジェクト作成（解像度/サンプル/動画・音声テンプレート/Tailwind/非インタラクティブ対応）、captureによるWebサイトURLからの直接プロジェクト構築（Whisper自動文字起こし含む）
02ビルディングブロックの検索とインストール：catalogによる自然言語でのローカル/公式カタログ検索、addによる選択したブロック/コンポーネントのプロジェクトへの追加と直接カスタマイズ
03検証ゲート：lintによる高速フィードバック＋check最終ゲート（単一ブラウザセッション＋単一シークでランタイムエラー、リクエスト失敗、レイアウト、motion.jsonアサーション、WCAGコントラストを監査）＋snapshotによるフレーム抽出/クロップエビデンス取得
04プレビューとプレゼンテーション：preview（--backgroundによるローカルサーバー起動含む）/ play / present（スライドデッキ＋スピーカー同期）/ beats（Studioビートグリッド）/ keyframes（モーション軌跡診断）
05レンダリング品質とバッチ処理：draft/looks/deliveryの3段階品質、--dockerによる再現可能なコンテナレンダリング、--batch rows.jsonによる変数駆動の一括出力
06クラウドおよびセルフホスト分散レンダリング：HeyGenホスト型クラウド（インフラ不要）、AWS Lambda、GCP Cloud Runの3つのパス。それぞれ専用のreferenceとデプロイ/破棄ライフサイクルを完備
07パブリッシュとクラウドアセット管理：publishによるプロジェクトソースのアップロードと永続ホスティングURLの発行（デフォルト非公開、--publicで公開）、cloud list/get/deleteによるレンダリング履歴管理（短期限り署名付きURL含む）
08環境診断と自己修復：doctorによるバージョン/Node/CPU/メモリ/ディスク/環境変数/FFmpeg/Chrome/Dockerの診断、browserコマンドによるバンドルChromeの管理
09透明性と保守：telemetry status/enable/disable、feedback報告、upgrade --check/--project、skills自己更新、info/compositions/docs/benchmark、tts/transcribe/remove-backgroundによるメディア前処理
3外部依存関係
| Kind | Dependency / Endpoint |
|---|---|
| cli | 官方 npx hyperframes CLI（本 skill 覆盖的全部子命令面；要求 Node 22+ 与 FFmpeg） |
| api | HeyGen 托管云渲染 API（zip 直传 S3 → 提交渲染 → 轮询 → 下载签名 URL；按 credit 计费） |
| cli | AWS（Lambda 自管分布式渲染：SAM 部署 Lambda + Step Functions + S3 + IAM） |
| cli | GCP（Cloud Run + Workflows + Cloud Storage，靠 gcloud 与 Terraform 部署） |
| api | npm registry（upgrade --check 比对已装版本与 npm latest；npx 首次拉取官方包） |
| network | 官方站点/文档（catalog 搜索说明页；SKILL.md 直接引用） |
| network | GitHub（init 时对着 GitHub 检查并更新已装 skill；registry 条目与 skills 自刷新） |
| package | 可选的 on-device 语义检索索引（量化 ONNX 模型 + catalog 向量，需用户同意后下载并缓存在本机） |
| cli | ffprobe（渲染后对账：时长/帧率 vs 根 data-duration） |
4推奨統制措置と判定根拠
安全運用のための推奨統制措置
Agent 向け
段階的・都度認可、サンドボックス推奨
管理者向け
承認フロー、ロールバック可能、全履歴監査
判定根拠（ファイルパスと抜粋）
- scripts/: ローカルスクリプトまたはコマンドの実行: スキルディレクトリ内にスクリプトは付属していません（11ファイルすべてがMarkdown: SKILL.md + 10個のreferenceファイル）。記載のコマンドはhyperframes CLIバイナリを指します。
- 外部 API: 外部プラットフォームに対する投稿、リソース作成、または変更書き込みの実行。
- 环境变量 / API Key: ベンダーサービス認証情報の読み取り: HeyGen認証情報の解決順序（cloud.mdに明記）: HEYGEN_API_KEY → HYPERFRAMES_API_KEY → ~/.heygen。
- 本地工作目录: ファイルの読み書きと成果物の出力: プロジェクト内: hyperframes.json、index.html、compositions/、renders/、snapshots/、beats/<au
監査ノート： 評価対象はスキルディレクトリ自体です。11ファイルすべてがMarkdownであり、スクリプトなし、組み込みエンドポイントなし、コードレベルでの認証情報読み取りもゼロです。しかしSKILL.mdおよび10個のreferenceは本スキルの宣言的インターフェースであり、この宣言面は認証情報を伴う外部通信・アップロード系コマンドを管轄しています。具体的には、HeyGen認証情報の読み取り（HEYGEN_API_KEY → HYPERFRAMES_API_KEY → ~/.heygen/credentials）とユーザープロジェクトのzipをHeyGenクラウドレンダリングバックエンドへアップロードする処理（クレジット課金対象）、AWS/GCPのセルフホストレンダリングデプロイ、publishによるプロジェクトソースのアップロード、公開チャネルへのfeedback、--file-issueによる最小限の再現手順の公開が含まれます。「自身が宣言した用途のために認証情報を読み取る／ユーザー素材を外部サービスバックエンドに送信する（アカウントクレジット消費を含む）」という基準に基づきAmber（橙）と判定されます。類似の先行例であるmedia-useやproduct-launch-video（~/.heygenを読み取り）も同様にAmberです。トリガー条件は明確であり、cloud / lambda / cloudrun / publish / auth / feedbackのパスを実行した場合にのみ成立し、デフォルトのローカルループ（init / add / catalog / lint / check / preview / render）は外部通信を行いません。ダウングレード理由：ディレクトリ内でのスクリプト実行がないこと、テレメトリは無効化可能かつ存在確認プローブのみであること、フィードバックにマスキングおよび同意規定があること、ローカルとセルフホストの責任境界が明確に記載されていることが挙げられます。TLSダウングレード、修復・自動化の迂回、任意コード実行は認められないため、Red（赤）には至りません。
5二重目の独立検証
- [ok] 凭证读取是否真发生在该 skill 目录内（橙档判定关键） — 目录内无任何代码（11 个文件全 md），故严格意义上「读取」由官方 CLI 执行；橙档依据是**声明面**：cloud.md 明写凭证解析顺序 HEYGEN_API_KEY → HYPERFRAMES_API_KEY → ~/.heygen/credentials，SKILL.md 又把 auth/cloud/lambda/cloudrun/publish/feedback 列为本 skill 统领的命令。与同批 hyperframes-cli 之外的 figma（FIGMA_TOKEN）保持同一口径，并在 reason 里注明执行主体。
- [ok] SKILL.md 里的 hyperframes.heygen.com 链接是不是被当作端点调用 — 该 URL 出自「Search the catalog before writing motion by hand」段落，是 catalog 搜索的**说明页引用**（句末带句点，形如文档链接），不是命令参数；同段明确写搜索本身 entirely local、查询文本 never sent anywhere。故按范式归为文档引用，不计入外发面。
- [ok] 云上传是否真是「用户素材出网 + 消耗额度」，且是否有幂等风险提示 — cloud.md 的渲染流水线写明 zip → 直传 S3 → POST /v3/hyperframes/renders → 轮询 → 下载，并直说「you pay per credit」；同文另给安全重试条款：zip 上传非幂等，盲重试会重复计费，故须 --idempotency-key。声明与风险提示齐备，未夸大。
- [ok] feedback / telemetry 的隐私表述是否有反例 — preview-render.md 有专门的脱敏段落（剥离绝对路径、机器标识、密钥，保留 HF_*/PRODUCER_* 变量原名），并给 COMPOSITION_STRUCTURE 的「无路径/无 src URL/无用户文本」定义；upgrade-info-misc.md 说明 telemetry 指纹只做存在性探测、从不读环境变量取值，且提供 telemetry disable 与 HYPERFRAMES_NO_TELEMETRY。未发现与声明矛盾之处。
- [unlocatable] 是否漏网的高危行为（关沙箱/TLS 降级/绕过检测） — 对 keywords（sandbox / danger / no-verify / AutomationControlled / NODE_TLS / rejectUnauthorized）做全目录扫描均无命中；但本 skill 不含代码，真实执行细节在 packages/cli 内、不属于本 skill 目录，故只能声明「本目录未出现」，不能替 CLI 整体背书。
6結論
最適な用途： HyperFramesプロジェクトをゼロから納品まで進めるユーザー/エージェントに最適：スキャフォールディングとサイトキャプチャ、自然言語による既存ブロックの検索、lint/check/snapshotのリズムによる反復開発とエビデンス取得、必要に応じたコンテナやクラウドレンダリング（HeyGenホスト型またはセルフホストAWS/GCP）への切り替え、パブリッシュやバージョン更新、Studio内でのhistoryを用いたターンごとの他者変更の引き継ぎ。また、`timeline --json`を用いて現在のタイムライン状態を正確に把握したい場合にも適しています。
不向きな用途： 非推奨環境・ユースケース：① プロジェクトの外部通信を禁止したい、またはクラウドクレジットを消費したくない場合（ローカルのrenderのみを使用すべき）；② Node 22+/FFmpeg/ブラウザ環境がなく、クラウド環境の構築も望まない場合；③ 単一のアニメーション効果のみを作成し、エンジニアリングループ全体を必要としない場合（/motion-graphicsや/product-launch-videoなどの専用ワークフロースキルを直接参照すべき）；④ レンダリング出力に対して緻密なアートディレクションを行いたい場合（本スキルはツール面を担当し、デザインやストーリー構成のルールはhyperframes-core / hyperframes-creativeに存在）；⑤ 制限されたCI環境で「終了コード＝正常」を前提としている場合（doctor --jsonは常に0を返すため、ペイロードの検証が必須）。
Install Agent-Ready
① Verified Mirror 2026-09-28
Option A · Direct DownloadDownload hyperframes-cli.tar.gz
sha256:
Option B · Copy Guide for Agent9d841064257cece2…Agent はこの JSON ガイドから自動的にダウンロードして検証します。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit d2f0bc7f34.