@autoaiai/aicut 0.1.7 → 0.1.11

package/skills/hyperdirector/docs/audio-workflow.zh-CN.md

@@ -0,0 +1,244 @@
+# Audio Director 工作流
+
+> 版本：v0.1.3-preview  
+> 适用：HyperDirector + Hermes（Cursor Agent）  
+> 规则参考：`rules/audio-director-rules.md`  
+> Schemas：`schemas/audio-manifest.schema.json` / `schemas/caption-timeline.schema.json`  
+> QA 检查：`qa/audio-qa-checklist.md`
+
+---
+
+## 什么是 Audio Director
+
+Audio Director 是 HyperDirector 的**音频导演层**，不是 TTS 工具。
+
+它的职责是：
+
+> 把脚本、旁白、字幕、声音角色、语速、停顿、TTS Provider、音频文件、字幕时间轴与视频 scene/shot 的关系，组织成可复核的音频管线。
+
+Audio Director **不做**：
+
+- 直接调用 TTS Provider 生成音频
+- 声音克隆（除非用户明确授权）
+- 音频波形分析或压缩
+- 搜索互联网获取旁白素材（需要研究内容时，使用 Hermes 官方内置的 web_search / web_extract 能力）
+- 替代 HyperFrames 的渲染引擎
+
+---
+
+## Audio Director 与其他管线的关系
+
+```
+Storyboard (scene_id / shot_id 主索引)
+       │
+       ├─→ Source Image Pipeline → asset-manifest.json
+       │
+       ├─→ Audio Director Pipeline
+       │       │
+       │       ├─→ audio-manifest.json   (音频段声明)
+       │       └─→ caption-timeline.json (字幕时间轴)
+       │
+       └─→ Render Planning (同时读取 image + audio + caption)
+```
+
+三条索引：
+- 图片资产进入 `asset-manifest.json`（按 scene_id / slot 绑定）
+- 音频段进入 `audio-manifest.json`（按 scene_id / shot_id 绑定）
+- 字幕进入 `caption-timeline.json`（按 scene_id / segment_id 关联）
+
+分镜表（`storyboard.json`）始终是 `scene_id` / `shot_id` 的唯一主索引。
+
+---
+
+## 核心链路
+
+```
+script.md / storyboard.json
+     │
+     ▼ [Step 1] 提取 Audio Intent（每个 scene 需要什么声音？）
+     │
+     ▼ [Step 2] 拆分 Voice Segments（每段旁白文本、归属 scene）
+     │
+     ▼ [Step 3] 定义 Voice Profile（声音角色、语速、情绪标签）
+     │
+     ▼ [Step 4] Provider-Neutral TTS 规划（选 Provider、voice_name）
+     │
+     ▼ [Step 5] 生成 audio-manifest.json（render_safe = false 先占位）
+     │
+     ▼ [Step 6] 生成 caption-timeline.json（与 segment 对齐）
+     │
+     ▼ [Step 7] TTS 生成 / 人工录制 → 音频文件落地本地
+     │
+     ▼ [Step 8] 音画 sync QA（时长校验、字幕对齐、render_safe = true）
+     │
+     ▼ [Step 9] Render Planning（index.html 引用本地音频）
+     │
+     ▼ [Step 10] 渲染输出 + 交付包
+```
+
+---
+
+## 阶段详解
+
+### Step 1 · 提取 Audio Intent
+
+从 `storyboard.json` 的每个 scene 读取：
+- `purpose`（场景叙事目的）
+- `caption`（现有字幕文本）
+- `duration`（场景秒数）
+- `notes`（导演意图）
+
+结合 `script.md`（如已存在）确定每个场景是否需要旁白以及旁白的大致内容和语气。
+
+**Hermes 示例指令：**
+```
+Hermes，请根据 output/storyboard.json 和 output/script.md，
+为每个 scene 提取 audio intent：
+1. 是否需要旁白（还是纯字幕或静音）
+2. 大致旁白内容
+3. 建议语速（slow / normal / fast）
+4. 情绪风格（professional / warm / energetic / calm）
+
+只输出规划建议，不生成音频，不调用 TTS。
+```
+
+### Step 2 · 拆分 Voice Segments
+
+将完整旁白拆分成以 scene / shot 为单位的段落：
+- 每个 `segment_id` 对应一个 `scene_id`（可选 `shot_id`）
+- 拆分原则：一个 scene 内的旁白作为一个或多个 segment
+- 每段文本长度建议：中文 30～80 字，英文 20～60 词（以配合 scene 时长）
+
+### Step 3 · 定义 Voice Profile
+
+为项目声明声音角色。Public 侧只记录 `voice_profile_id` 引用；详细的 Voice Profile（含 provider_preferences、cloning 配置）定义在 Pro 模板中。
+
+最简单的做法：在 `audio-manifest.json` 的 segment 中直接写 `speaker_id` 和 `provider` / `voice_name`，不需要单独的 voice profile 文件（适合简单项目）。
+
+### Step 4 · Provider-Neutral TTS 规划
+
+选择 TTS Provider 时遵循 R-AUD-09 Provider-Neutral 原则：
+- 在 `audio-manifest.json` 的 `provider` 字段记录选定的 provider
+- 确保 `text` 和 `language` 字段足够完整，以支持 provider 切换后重新生成
+- 配置 fallback：推荐 `edge-tts` 作为 fallback（无需 API key）
+
+可选 Provider 方向（均非默认依赖，需用户选择并手动配置）：
+
+| Provider | 类型 | 适用场景 |
+|----------|------|----------|
+| `edge-tts` | 系统级 TTS，免费，可离线 | Fallback，快速验证 |
+| `cosyvoice` | 本地高质量中文 TTS | 中文旁白，需本地安装 |
+| `chattts` | 本地对话式 TTS | 对话场景，实验性 |
+| `fish_audio` | 商业 API | 高质量多语言，需 API key |
+| `minimax` | 商业 API | 高质量中文，需 API key |
+
+**重要**：这些 Provider 均为可选方向，不是 HyperDirector 的默认依赖。不要提交 API key。
+
+### Step 5 · 生成 audio-manifest.json
+
+初始状态：所有 segment 的 `render_safe = false`，`local_path` 填写规划路径（文件尚未生成）。
+
+```json
+{
+  "project_id": "my-project",
+  "audio_root": "assets/audio",
+  "caption_timeline_path": "caption-timeline.json",
+  "default_language": "zh-CN",
+  "segments": [
+    {
+      "segment_id": "seg_scene01_hook",
+      "scene_id": "scene_01",
+      "text": "旁白文本...",
+      "provider": "edge-tts",
+      "voice_name": "zh-CN-XiaoxiaoNeural",
+      "local_path": "assets/audio/seg_scene01_hook.mp3",
+      "format": "mp3",
+      "render_safe": false,
+      "consent_status": "tts_only"
+    }
+  ]
+}
+```
+
+### Step 6 · 生成 caption-timeline.json
+
+字幕时间轴与音频段关联：
+
+```json
+{
+  "project_id": "my-project",
+  "default_language": "zh-CN",
+  "captions": [
+    {
+      "caption_id": "cap_scene01_01",
+      "segment_id": "seg_scene01_hook",
+      "scene_id": "scene_01",
+      "start_ms": 500,
+      "end_ms": 4200,
+      "text": "旁白文本...",
+      "max_chars_per_line": 20,
+      "line_count": 2
+    }
+  ]
+}
+```
+
+**字幕可以独立于音频存在**：没有 `segment_id` 的 caption 条目是纯文字字幕，不依赖 TTS。
+
+### Step 7 · 音频文件落地
+
+用户使用选定的 TTS Provider 生成音频文件，或人工录制后保存为指定格式，放入 `output/assets/audio/`。
+
+更新 `audio-manifest.json`：
+- 填写实际的 `duration_ms`（从文件属性获取）
+- 填写实际的 `start_ms` / `end_ms`（根据时间轴规划）
+- 填写 `transcript`（TTS 实际输出文本或人工记录）
+
+### Step 8 · 音画 Sync QA
+
+```bash
+# 辅助扫描（告警，不阻断）
+node hyperdirector/scripts/check-composition-hazards.js output/index.html
+```
+
+然后逐项完成 `qa/audio-qa-checklist.md`，全部通过后将 `render_safe` 置为 `true`。
+
+### Step 9 · Render Planning
+
+在 `output/index.html` 中引用本地音频：
+
+```html
+<!-- 推荐：本地路径，受 render_safe = true 保护 -->
+<audio id="narration_scene01" src="assets/audio/seg_scene01_hook.mp3" preload="auto"></audio>
+
+<!-- 禁止（生产渲染中）：远程 URL -->
+<!-- <audio src="https://..."></audio> -->
+```
+
+字幕元素应与 `caption-timeline.json` 的 `start_ms` / `end_ms` 对应，由 GSAP timeline 控制显隐。
+
+---
+
+## 安全与授权边界
+
+| 允许 | 禁止 |
+|------|------|
+| 标准 TTS Provider 合成（tts_only） | 未授权声音克隆 |
+| 声音克隆（有书面授权 + consent_obtained） | API key 写入 manifest |
+| Provider 元数据（无凭证参数） | 真实音频样本提交到 git |
+| edge-tts 作为 fallback | 模型权重提交到 git |
+| 规划音频管线（不调用 API） | 默认调用商业 TTS API |
+
+---
+
+## 相关文件
+
+| 文件 | 说明 |
+|------|------|
+| `rules/audio-director-rules.md` | R-AUD-01 ～ R-AUD-11 规则定义 |
+| `schemas/audio-manifest.schema.json` | Audio Manifest JSON Schema |
+| `schemas/caption-timeline.schema.json` | Caption Timeline JSON Schema |
+| `qa/audio-qa-checklist.md` | 渲染前逐项检查清单 |
+| `scripts/check-composition-hazards.js` | 启发式告警扫描（含音频检查） |
+| `docs/audio-workflow.md` | 英文版工作流文档 |
+| `docs/source-image-workflow.zh-CN.md` | Source Image Pipeline 工作流 |

package/skills/hyperdirector/docs/brand-kit-setup.md

@@ -0,0 +1,322 @@
+# Brand Kit 配置指南
+
+> Brand Kit 是 HyperDirector 的品牌记忆系统。配置一次，所有视频自动套用。
+
+---
+
+## 为什么需要 Brand Kit？
+
+没有 Brand Kit 时，每次生成视频都要重新描述你的颜色、字体和风格。配置后：
+
+- 品牌色在每条视频中保持一致
+- 字幕字体无需每次指定
+- 动效节奏匹配你的品牌风格
+- CTA 自动填入，不再手动写
+- 多语言视频统一输出语言策略
+
+---
+
+## 文件位置
+
+将 `brand-kit.json` 放在工作目录根目录（与 `output/` 同级）：
+
+```
+你的工作目录/
+├── brand-kit.json     ← 品牌配置
+├── output/            ← 视频输出
+└── ...
+```
+
+快速创建：
+
+```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": "关注 [你的品牌名]，持续更新"
+  }
+}
+```
+
+其余字段使用默认值，视频可以正常生成。
+
+---
+
+## 完整字段参考
+
+```json
+{
+  "brand_name": "你的品牌名称",
+
+  "locale": "zh-CN",
+  "default_output_language": "zh-CN",
+
+  "language_policy": {
+    "script_language": "zh-CN",
+    "subtitle_language": "zh-CN",
+    "ui_copy_language": "zh-CN",
+    "technical_terms": "keep_english_with_chinese_explanation"
+  },
+
+  "colors": {
+    "primary": "#111827",
+    "accent": "#6366F1",
+    "background": "#FFFFFF",
+    "text_primary": "#1F2937",
+    "text_secondary": "#6B7280"
+  },
+
+  "fonts": {
+    "headline": "Inter",
+    "body": "Noto Sans SC",
+    "code": "JetBrains Mono"
+  },
+
+  "motion_language": {
+    "pace": "medium",
+    "style": "clean_tech",
+    "transitions": ["slide_up", "scale_in", "fade"],
+    "entrance_default": "fade_slide_up",
+    "exit_default": "fade_out"
+  },
+
+  "voice": {
+    "tone": "专业、直给、有工程感",
+    "avoid": ["过度夸张", "空泛口号", "廉价图标"],
+    "tts_voice": "af_heart",
+    "tts_speed": 1.0
+  },
+
+  "cta": {
+    "default": "关注 [品牌名]，持续更新",
+    "subscription": "前往你的课程或会员落地页",
+    "follow_wechat": "关注公众号 [公众号名称]"
+  },
+
+  "assets": {
+    "logo": "assets/logo.png",
+    "watermark": "assets/watermark.png",
+    "background_default": "assets/bg-default.png",
+    "music_default": "assets/bgm-default.mp3"
+  },
+
+  "safe_zone": {
+    "top_percent": 10,
+    "bottom_percent": 22,
+    "left_percent": 5,
+    "right_percent": 5
+  }
+}
+```
+
+---
+
+## 字段详解
+
+### 语言设置
+
+| 字段 | 说明 | 可选值 |
+|------|------|--------|
+| `locale` | 品牌区域 | `zh-CN`、`en-US`、`ja-JP` |
+| `default_output_language` | 视频默认输出语言 | `zh-CN`、`en-US` |
+| `language_policy.script_language` | 旁白脚本语言 | `zh-CN`、`en-US` |
+| `language_policy.subtitle_language` | 字幕语言 | `zh-CN`、`en-US` |
+| `language_policy.ui_copy_language` | CTA 和按钮语言 | `zh-CN`、`en-US` |
+| `language_policy.technical_terms` | 技术词汇处理 | 见下表 |
+
+`technical_terms` 可选值：
+
+| 值 | 效果 |
+|----|------|
+| `keep_english` | 技术词保持英文（API、GSAP、HTML） |
+| `keep_english_with_chinese_explanation` | 英文 + 括号注释（默认推荐） |
+| `translate_all` | 全部翻译为目标语言 |
+
+---
+
+### 颜色设置
+
+颜色值格式必须为 `#RRGGBB`（6 位十六进制）。
+
+| 字段 | 用途 |
+|------|------|
+| `colors.primary` | 标题、重点文字、深色背景 |
+| `colors.accent` | 高亮、按钮、CTA 背景 |
+| `colors.background` | 浅色场景背景 |
+| `colors.text_primary` | 浅色背景上的主体文字 |
+| `colors.text_secondary` | 说明文字、标注、次要信息 |
+
+从品牌 Logo 或网站 CSS 提取颜色值，确保与已有视觉系统一致。
+
+校验颜色格式是否正确：
+
+```bash
+node hyperdirector/scripts/validate-brand-kit.js brand-kit.json
+```
+
+---
+
+### 字体设置
+
+| 字段 | 用途 | 中文视频推荐 |
+|------|------|------------|
+| `fonts.headline` | 大标题、场景标题 | Inter、Space Grotesk |
+| `fonts.body` | 字幕、说明文字 | Noto Sans SC、PingFang SC |
+| `fonts.code` | 代码块（技术视频）| JetBrains Mono、Consolas |
+
+推荐字体搭配：
+
+| 风格 | 标题 | 正文 |
+|------|------|------|
+| 简洁科技 | Inter | Noto Sans SC |
+| 温暖人文 | Lora | PingFang SC |
+| 强烈个性 | Space Grotesk | Noto Sans SC |
+| 企业商务 | Source Sans 3 | Noto Sans SC |
+
+**注意：** 字体必须在渲染环境中可用。Google Fonts 在渲染时需要联网。离线环境建议将 `.woff2` 文件放入 `assets/fonts/` 并用 `@font-face` 本地加载。
+
+---
+
+### 动效设置
+
+| 字段 | 可选值 | 说明 |
+|------|--------|------|
+| `motion_language.pace` | `fast` / `medium` / `slow` | 元素出现速度（0.2s / 0.4s / 0.6s） |
+| `motion_language.style` | `clean_tech` / `warm_social` / `corporate` / `editorial` / `playful` | 整体视觉风格 |
+| `motion_language.transitions` | `slide_up`、`scale_in`、`wipe`、`fade`、`push`、`blur_crossfade` | 偏好转场效果列表 |
+
+风格选择建议：
+
+| 场景 | 推荐配置 |
+|------|---------|
+| 技术博主 | `clean_tech` + `fast` |
+| 知识型创作者 | `editorial` + `medium` |
+| 企业/商务 | `corporate` + `medium` |
+| 生活/情感类 | `warm_social` + `medium` |
+
+---
+
+### 语气设置
+
+```json
+"voice": {
+  "tone": "专业但不刻板，信息密度高，干货感强",
+  "avoid": ["过于销售腔", "廉价鸡汤", "故作神秘", "过多感叹号"]
+}
+```
+
+`tone` 用正面描述，`avoid` 用负面列表。两者共同引导 HyperDirector 生成脚本的措辞风格。
+
+---
+
+### CTA 设置
+
+```json
+"cta": {
+  "default": "关注示例创作者，继续拆解能干活的 AI Agent",
+  "subscription": "前往你的课程或会员落地页（示例：https://example.com/join）",
+  "follow_wechat": "关注公众号「示例创作者」，回复「视频」获取说明",
+  "trial": "立即预约 Demo → your-product.com"
+}
+```
+
+在视频中使用特定 CTA：
+
+```
+使用 HyperDirector 生成视频，结尾 CTA 使用 cta.subscription
+```
+
+或在 brief.json 中通过 `cta_override` 字段临时覆盖：
+
+```json
+"cta_override": "本期特别推荐：扫码加入学习群"
+```
+
+---
+
+### 安全区设置
+
+安全区决定字幕和主要内容的显示范围，避免被平台 UI 遮挡：
+
+```json
+"safe_zone": {
+  "top_percent": 10,
+  "bottom_percent": 22,
+  "left_percent": 5,
+  "right_percent": 5
+}
+```
+
+| 平台 | 建议 bottom_percent |
+|------|-------------------|
+| 视频号 / TikTok（9:16） | 22%（有进度条+头像遮挡） |
+| YouTube（16:9） | 12% |
+| B 站 | 15% |
+
+---
+
+## 校验 Brand Kit
+
+```bash
+node hyperdirector/scripts/validate-brand-kit.js brand-kit.json
+```
+
+通过示例：
+
+```
+✓ brand_name
+✓ colors.primary (#111827)
+✓ colors.accent (#6366F1)
+✓ fonts.headline
+✓ fonts.body
+✓ cta.default
+✓ Brand Kit validation passed
+```
+
+---
+
+## 多 Brand Kit 切换
+
+当你管理多个品牌时，可以使用多个配置文件：
+
+```
+brand-kit-brand-a.json
+brand-kit-brand-b.json
+```
+
+在生成时指定：
+
+```
+使用 HyperDirector 生成视频，使用 brand-kit-brand-b.json 的品牌配置
+```
+
+---
+
+## 参考示例
+
+- `hyperdirector/brand/brand-kit.example.json` — 通用示例
+- `hyperdirector/brand/brand-kit.persona-zh.example.json` — 中文人设风格示例（开源占位，非真实品牌）
+
+---
+
+下一步：[模板选择指南 →](./template-guide.md)