@autoaiai/aicut 0.1.7 → 0.1.11

package/skills/hyperdirector/docs/installation.md

@@ -0,0 +1,254 @@
+# 安装指南
+
+> 说明 HyperDirector 的所有依赖组件、安装顺序和验证方法。
+
+---
+
+## 组件关系
+
+```
+你的电脑
+  ├── Hermes                    ← Agent 执行环境（对话界面）
+  │     └── HyperDirector       ← Skill Pack（本项目，放这里）
+  │
+  ├── Node.js >= 22             ← HyperFrames CLI 运行要求
+  ├── HyperFrames CLI           ← HTML-to-video 渲染引擎
+  │     ├── FFmpeg              ← 视频编码（HyperFrames 依赖）
+  │     └── Chromium（自动管理） ← 逐帧渲染（HyperFrames 依赖）
+  └── GSAP                      ← 动画库（HyperFrames 内置，无需单独安装）
+```
+
+**重要区分：**
+
+- **HyperDirector** 负责上游：理解需求、生成 brief/storyboard/HTML、QA 循环、交付报告
+- **HyperFrames** 负责下游：lint 检查、preview 预览、render 输出 MP4
+
+HyperFrames CLI 未安装时，HyperDirector 仍可生成所有源文件（brief/storyboard/HTML），但无法执行 lint 和渲染。
+
+---
+
+## 第一步：安装 Node.js（需要 v22+）
+
+### 检查版本
+
+```bash
+node --version
+```
+
+输出 `v22.x.x` 或以上 → 跳过此步。
+
+### 安装或升级
+
+**推荐方式：使用 nvm（Node Version Manager）**
+
+```bash
+# macOS / Linux
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
+source ~/.bashrc   # 或 source ~/.zshrc
+nvm install 22
+nvm use 22
+nvm alias default 22
+```
+
+```powershell
+# Windows：安装 nvm-windows
+# 下载 https://github.com/coreybutler/nvm-windows/releases
+# 安装后：
+nvm install 22
+nvm use 22
+```
+
+**或直接从官网下载：** https://nodejs.org（选择 22.x LTS）
+
+### 验证
+
+```bash
+node --version   # v22.x.x 或更高
+npm --version    # 10.x.x 或更高
+```
+
+---
+
+## 第二步：安装 FFmpeg
+
+HyperFrames 渲染 MP4 必须依赖 FFmpeg。
+
+### 检查是否已安装
+
+```bash
+ffmpeg -version
+```
+
+有版本输出 → 跳过此步。
+
+### 安装
+
+```bash
+# macOS（推荐 Homebrew）
+brew install ffmpeg
+
+# Ubuntu / Debian
+sudo apt update && sudo apt install ffmpeg
+
+# CentOS / RHEL
+sudo yum install ffmpeg
+```
+
+**Windows：**
+
+1. 从 https://ffmpeg.org/download.html 下载（推荐 [gyan.dev](https://www.gyan.dev/ffmpeg/builds/) 的 release 版本）
+2. 解压到 `C:\ffmpeg\`
+3. 将 `C:\ffmpeg\bin` 添加到系统 PATH
+4. **重启终端**（PATH 修改只对新终端生效）
+5. 验证：`ffmpeg -version`
+
+---
+
+## 第三步：安装 HyperFrames CLI
+
+```bash
+npm install -g hyperframes
+```
+
+### 验证
+
+```bash
+npx hyperframes --version
+```
+
+### 运行环境诊断
+
+```bash
+npx hyperframes doctor
+```
+
+这个命令检查 Node.js、FFmpeg、Chromium 所有依赖。**Chromium 由 HyperFrames 自动管理，不需要手动安装**。若报 Chromium 问题：
+
+```bash
+npx hyperframes doctor --fix      # 尝试自动修复
+npx hyperframes doctor --verbose  # 查看详细诊断
+```
+
+---
+
+## 第四步：安装 HyperDirector Skill Pack
+
+HyperDirector 是一个 Hermes Skill Pack，安装方式取决于你的 Hermes 配置。
+
+### 方式 A：全局 skills 目录
+
+```bash
+# 克隆仓库
+git clone https://github.com/your-org/hyperdirector.git
+cd hyperdirector
+
+# 复制 skill 到 Hermes 全局 skills 目录
+cp -r hyperdirector/ ~/.hermes/skills/hyperdirector/
+```
+
+### 方式 B：项目级引用
+
+如果你在特定项目目录中工作，可以将 `hyperdirector/` 放在项目根目录下，Hermes 会从当前工作目录扫描 skills。
+
+### 方式 C：Cursor 环境
+
+在 Cursor 中，将 `hyperdirector/` 目录的绝对路径添加到 Hermes 的 skills 加载配置中。具体配置路径请查看你的 Cursor 版本文档。
+
+### 验证 Skill 加载
+
+向 Hermes 发送：
+
+```
+HyperDirector 支持哪些视频模板？
+```
+
+Hermes 能列出三个模板并解释 → 安装成功。
+
+---
+
+## 完整验证清单
+
+```bash
+# 1. Node.js 版本
+node --version           # v22.x.x 或更高
+
+# 2. npm
+npm --version            # 10.x.x 或更高
+
+# 3. FFmpeg
+ffmpeg -version          # 显示版本信息
+
+# 4. HyperFrames CLI
+npx hyperframes --version     # 显示版本号
+npx hyperframes doctor        # 所有项通过
+
+# 5. HyperDirector 脚本验证
+node hyperdirector/scripts/check-env.js
+
+# 6. 校验示例项目（验证 Node 脚本正常工作）
+node hyperdirector/scripts/validate-brief.js \
+  hyperdirector/examples/zh-CN/demo-article-to-video/output/brief.json
+```
+
+全部通过 → 可以开始使用。
+
+---
+
+## 常见安装问题
+
+### `npx hyperframes` 报"找不到命令"
+
+```bash
+npm install -g hyperframes
+# 若仍失败：
+npx --yes hyperframes --version   # 强制临时安装
+```
+
+### Windows 上 FFmpeg 配置了 PATH 但仍不可用
+
+重启终端或 VS Code / Cursor。PATH 修改只对新打开的窗口生效。
+
+### `npx hyperframes doctor` 报 Chromium 缺失
+
+```bash
+npx hyperframes doctor --fix
+```
+
+若失败，查阅：https://hyperframes.heygen.com/guides/troubleshooting
+
+### HyperDirector Skill 没有被 Hermes 识别
+
+1. 确认 `hyperdirector/SKILL.md` 文件存在
+2. 确认 `hyperdirector/` 目录在 Hermes 的 skills 扫描路径中
+3. 重启 Hermes 会话（部分 Agent 框架需要重启才能加载新 skill）
+
+### Node.js 版本低于 22 但无法升级
+
+```bash
+# 用 nvm 切换（不影响系统全局版本）
+nvm install 22
+nvm use 22
+```
+
+---
+
+## 离线环境说明
+
+HyperDirector 和 HyperFrames 的渲染是完全本地化的：
+
+| 功能 | 是否需要网络 |
+|------|------------|
+| 生成 brief / storyboard / HTML | 否 |
+| HyperFrames render | 否 |
+| Kokoro TTS 配音 | 否 |
+| Google Fonts 字体加载 | 是（首次，可本地化）|
+| 安装 / 更新依赖 | 是（仅安装时）|
+
+**离线字体处理：** 将 `.woff2` 字体文件放入 `assets/fonts/` 并在 `index.html` 中用 `@font-face` 声明，替换 Google Fonts CDN 链接。
+
+---
+
+## 下一步
+
+- [快速开始 →](./quickstart.md)
+- [第一个视频完整教程 →](./first-video.md)

package/skills/hyperdirector/docs/installation.zh-CN.md

@@ -0,0 +1,222 @@
+# 安装指南
+
+> 本文说明 HyperDirector 的所有依赖组件、安装顺序和验证方法。
+
+---
+
+## 组件关系
+
+理解各组件的关系有助于排障：
+
+```
+你的电脑
+  ├── Hermes                    ← Agent 执行环境（对话界面）
+  │     └── HyperDirector       ← Skill Pack（本项目）
+  │
+  ├── Node.js >= 22             ← HyperFrames CLI 运行要求
+  ├── HyperFrames CLI           ← HTML-to-video 渲染引擎
+  ├── FFmpeg                    ← 视频编码（HyperFrames 依赖）
+  └── Chromium（自动管理）       ← 页面渲染（HyperFrames 依赖）
+```
+
+**重要：** HyperDirector 本身不是视频渲染引擎。它生成的 HTML 文件需要 HyperFrames CLI 来渲染成 MP4。如果 HyperFrames CLI 未安装，HyperDirector 仍然可以生成脚本、分镜、HTML 源码，但不能输出 MP4。
+
+---
+
+## 第一步：安装 Node.js
+
+HyperFrames CLI 要求 Node.js **版本 22 或以上**。
+
+### 检查当前版本
+
+```bash
+node --version
+```
+
+如果输出是 `v22.x.x` 或更高，跳过此步骤。
+
+### 安装或升级 Node.js
+
+推荐使用 nvm（Node Version Manager）管理 Node.js 版本：
+
+**macOS / Linux：**
+```bash
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
+nvm install 22
+nvm use 22
+```
+
+**Windows：**
+使用 [nvm-windows](https://github.com/coreybutler/nvm-windows)，或直接从 https://nodejs.org 下载 LTS 版本安装包（选择 22.x 或更高）。
+
+**验证：**
+```bash
+node --version   # 应显示 v22.x.x 或更高
+npm --version    # 应显示 10.x.x 或更高
+```
+
+---
+
+## 第二步：安装 FFmpeg
+
+FFmpeg 是 HyperFrames 渲染 MP4 的必要依赖。
+
+### 检查是否已安装
+
+```bash
+ffmpeg -version
+```
+
+如果有输出版本信息，跳过此步骤。
+
+### 安装 FFmpeg
+
+**macOS（推荐使用 Homebrew）：**
+```bash
+brew install ffmpeg
+```
+
+**Ubuntu / Debian：**
+```bash
+sudo apt update && sudo apt install ffmpeg
+```
+
+**Windows：**
+1. 从 https://ffmpeg.org/download.html 下载 Windows 构建包（推荐 BtbN 或 gyan.dev 的构建）
+2. 解压到 `C:\ffmpeg`
+3. 将 `C:\ffmpeg\bin` 添加到系统环境变量 `PATH`
+4. 重启终端后验证：`ffmpeg -version`
+
+---
+
+## 第三步：安装 HyperFrames CLI
+
+```bash
+npm install -g hyperframes
+```
+
+### 验证安装
+
+```bash
+npx hyperframes --version
+```
+
+应该输出类似 `hyperframes/0.x.x` 的版本信息。
+
+### 运行环境检查
+
+```bash
+npx hyperframes doctor
+```
+
+这个命令会检查 Node.js、FFmpeg、Chromium 等所有依赖是否就绪。如有缺失，它会给出具体的安装提示。
+
+**关于 Chromium：** HyperFrames 使用 Chromium 进行页面逐帧渲染。Chromium 由 HyperFrames 自动管理，不需要手动安装。如果遇到 Chromium 相关问题，运行 `npx hyperframes doctor` 会给出诊断。
+
+---
+
+## 第四步：安装 HyperDirector Skill Pack
+
+### 方法 A：放置到 Hermes skills 目录
+
+1. 下载或克隆 HyperDirector 仓库
+2. 将 `hyperdirector/` 目录复制到 Hermes 的 skills 加载目录
+
+Hermes skills 目录位置（以常见配置为例）：
+- `~/.hermes/skills/` （全局）
+- `<你的项目目录>/skills/hyperdirector/` （项目级）
+
+具体目录位置请查看你的 Hermes 文档。
+
+### 方法 B：项目内直接引用
+
+如果你的工作项目就是一个 Hermes 对话会话，可以直接在会话的工作目录下放置 `hyperdirector/`，然后在对话中告知 Hermes skill 位置。
+
+### 验证 Skill 加载
+
+向 Hermes 提问：
+
+```
+HyperDirector 支持哪些视频模板？
+```
+
+如果 Hermes 能列出 `tiktok-vertical-kit`、`saas-demo-kit`、`ai-knowledge-explainer-kit` 并解释各自用途，表示安装成功。
+
+---
+
+## 完整验证清单
+
+安装完成后，运行以下命令，每一条都应该成功：
+
+```bash
+# Node.js 版本
+node --version          # v22.x.x 或更高
+
+# npm 包管理器
+npm --version           # 10.x.x 或更高
+
+# FFmpeg
+ffmpeg -version         # 显示版本信息
+
+# HyperFrames CLI
+npx hyperframes --version    # 显示版本
+npx hyperframes doctor       # 所有检查通过
+
+# 创建测试项目（可选）
+npx hyperframes init test-video
+cd test-video
+npx hyperframes preview      # 浏览器打开预览
+```
+
+---
+
+## 常见安装问题
+
+### `npx hyperframes` 报找不到命令
+
+```bash
+npm install -g hyperframes   # 全局安装
+# 如果仍然失败，尝试：
+npx --yes hyperframes --version   # 强制安装最新版
+```
+
+### FFmpeg 在 Windows 上配置了 PATH 但仍不可用
+
+重启终端（或重启 VS Code）。PATH 修改只对新打开的终端生效。
+
+### `npx hyperframes doctor` 报 Chromium 问题
+
+```bash
+npx hyperframes doctor --fix    # 尝试自动修复
+# 或者
+npx hyperframes doctor --verbose   # 查看详细诊断
+```
+
+如果仍有问题，查看 HyperFrames 官方 troubleshooting 文档：
+https://hyperframes.heygen.com/guides/troubleshooting
+
+### HyperDirector Skill 没有被 Hermes 识别
+
+1. 确认 `SKILL.md` 文件存在于 `hyperdirector/` 目录下
+2. 确认目录路径在 Hermes skills 加载范围内
+3. 重启 Hermes 会话（有些 Agent 框架需要重启才能加载新 skill）
+
+---
+
+## 离线环境说明
+
+如果你的渲染环境没有互联网访问：
+
+1. HyperDirector 生成的 HTML 文件可以离线运行（GSAP 通过 HyperFrames 本地提供）
+2. TTS 功能使用 Kokoro 本地模型，不需要联网
+3. HyperFrames 渲染也是完全本地化的，不需要联网
+4. 素材（图片、音频）需要提前下载放到 `assets/` 目录
+
+---
+
+## 下一步
+
+安装完成后，继续：
+
+- [快速开始 →](./quickstart.zh-CN.md)
+- [生成第一个视频 →](./first-video.zh-CN.md)

package/skills/hyperdirector/docs/quickstart.md

@@ -0,0 +1,203 @@
+# 快速开始
+
+> 最短路径：从零到生成你的第一个视频项目。  
+> 预计耗时：10–20 分钟（含安装）。
+
+---
+
+## 前置条件
+
+运行以下命令确认环境就绪：
+
+```bash
+node --version        # 需要 v22 或以上
+ffmpeg -version       # 需要能执行
+npx hyperframes --version   # 需要能执行
+```
+
+| 组件 | 要求 | 安装方式 |
+|------|------|---------|
+| Node.js | >= 22 | https://nodejs.org |
+| FFmpeg | 任意近期版本 | https://ffmpeg.org/download.html |
+| HyperFrames CLI | latest | `npm install -g hyperframes` |
+| Hermes | 能正常对话 | 见你的 Hermes 配置文档 |
+
+全部就绪后，运行一键检查：
+
+```bash
+node hyperdirector/scripts/check-env.js
+```
+
+详细安装步骤 → [installation.md](./installation.md)
+
+---
+
+## 第一步：安装 Skill Pack
+
+1. 克隆或下载此仓库
+2. 将 `hyperdirector/` 目录复制到你的 Hermes skills 加载目录
+
+```bash
+# 示例：全局 skills 目录
+cp -r hyperdirector/ ~/.hermes/skills/hyperdirector/
+```
+
+3. 向 Hermes 发送以下消息验证安装：
+
+```
+HyperDirector 支持哪些视频模板？
+```
+
+如果 Hermes 能列出 `tiktok-vertical-kit`、`saas-demo-kit`、`ai-knowledge-explainer-kit` 并说明各自用途，表示安装成功。
+
+---
+
+## 第二步：配置 Brand Kit
+
+复制示例配置并填写你的品牌信息：
+
+```bash
+cp hyperdirector/brand/brand-kit.example.json ./brand-kit.json
+```
+
+最小可用配置（其余字段使用默认值）：
+
+```json
+{
+  "brand_name": "你的品牌名称",
+  "locale": "zh-CN",
+  "default_output_language": "zh-CN",
+  "colors": {
+    "primary": "#111827",
+    "accent": "#6366F1"
+  },
+  "fonts": {
+    "headline": "Inter",
+    "body": "Noto Sans SC"
+  },
+  "cta": {
+    "default": "关注 [你的品牌名]，持续更新"
+  }
+}
+```
+
+Brand Kit 完整说明 → [brand-kit-setup.md](./brand-kit-setup.md)
+
+---
+
+## 第三步：运行第一个 Demo
+
+最快的验证方式是直接运行示例项目：
+
+```bash
+# 校验 demo-article-to-video 的分镜
+node hyperdirector/scripts/validate-storyboard.js \
+  hyperdirector/examples/zh-CN/demo-article-to-video/output/storyboard.json \
+  hyperdirector/examples/zh-CN/demo-article-to-video/output/brief.json
+
+# 打开浏览器预览示例视频
+open hyperdirector/examples/zh-CN/demo-article-to-video/output/preview.html
+# Windows: start hyperdirector/examples/zh-CN/demo-article-to-video/output/preview.html
+```
+
+---
+
+## 第四步：生成你的第一个视频
+
+在 Hermes 中输入：
+
+```
+使用 HyperDirector，把下面这篇文章做成 30 秒视频号竖屏短视频。
+使用我的 brand-kit，前 3 秒强 hook，中间 3 个核心观点，结尾引导关注。
+
+[粘贴你的文章或任何文字内容]
+```
+
+HyperDirector 会依次完成：
+
+```
+1. 能力判断 → 确认请求适合 HyperDirector
+2. Brief 生成 → brief.json（结构化需求）
+3. 分镜生成 → storyboard.json（场景/时长/字幕）
+4. 视觉设计 → DESIGN.md（颜色/字体/动效决策）
+5. HTML 合成 → index.html（HyperFrames 源码）
+6. QA 质检 → npx hyperframes lint + validate
+7. 渲染报告 → render-report.md
+```
+
+整个过程约 1–3 分钟。
+
+---
+
+## 第五步：查看输出文件
+
+生成完成后，检查 `output/` 目录：
+
+```bash
+node hyperdirector/scripts/check-output-contract.js output/你的项目名/
+```
+
+标准输出结构：
+
+```
+output/你的项目名/
+├── brief.json             ← 结构化需求
+├── storyboard.json        ← 分镜（可直接编辑）
+├── script.md              ← 旁白文稿
+├── DESIGN.md              ← 视觉设计说明
+├── brand-used.json        ← 本次品牌配置快照
+├── index.html             ← 视频源码（浏览器可打开）
+├── preview.html           ← 预览入口
+├── edit-instructions.md   ← 二次编辑指南
+├── render-report.md       ← QA 报告
+└── assets/                ← 素材目录
+```
+
+**浏览器预览：**
+
+```bash
+open output/你的项目名/preview.html
+```
+
+**渲染 MP4：**
+
+```bash
+cd output/你的项目名/
+npx hyperframes preview        # 先看效果
+npx hyperframes render --quality high --output final.mp4
+```
+
+---
+
+## 常见第一次问题
+
+**Q：Hermes 没有识别 HyperDirector？**
+
+确认 `SKILL.md` 文件存在于 `hyperdirector/` 目录下，且目录在 Hermes skills 加载路径中。重启 Hermes 会话后重试。
+
+**Q：生成结果和我想的不一样？**
+
+这很正常。直接告诉 Hermes 需要修改的地方：
+
+```
+把 hook 改成"AI Agent 终于能当视频导演了"，字幕大一号，CTA 改成"前往你的落地页订阅"
+```
+
+HyperDirector 会局部修改，不会重写整个项目。
+
+**Q：render 报错了？**
+
+```bash
+npx hyperframes lint     # 查看具体错误
+```
+
+也可以把错误信息发给 Hermes，HyperDirector 会进入自动修复流程（最多 3 次）。
+
+---
+
+## 下一步
+
+- [第一个视频完整教程 →](./first-video.md)
+- [Brand Kit 配置指南 →](./brand-kit-setup.md)
+- [模板选择指南 →](./template-guide.md)
+- [示例项目 →](../examples/zh-CN/)