@autoaiai/aicut 0.1.7 → 0.1.11

package/skills/hyperdirector/docs/cursor-development-notes.md

@@ -0,0 +1,474 @@
+# Cursor Development Notes
+
+> 面向后续开发者的技术说明。说明 v0.1 的边界、核心文件的职责、以及如何安全地扩展功能。
+
+---
+
+## v0.1 边界说明
+
+### 已完成（v0.1 In Scope）
+
+| 功能模块 | 状态 | 位置 |
+|---------|------|------|
+| 能力判断（Capability Judge）| ✅ 完整 | `prompts/01-capability-judge.md` |
+| Brief 生成 | ✅ 完整 | `prompts/02-intake-brief.md` |
+| Storyboard 生成 | ✅ 完整 | `prompts/03-storyboard-generator.md` |
+| 视觉设计（DESIGN.md 生成）| ✅ 完整 | `prompts/04-visual-design.md` |
+| HTML 合成（HyperFrames）| ✅ 完整 | `prompts/05-compose-hyperframes.md` |
+| QA Fix Loop | ✅ 完整 | `prompts/06-qa-fixer.md` |
+| Render Report 生成 | ✅ 完整 | `prompts/07-render-report.md` |
+| 迭代修改（Warm Iteration）| ✅ 完整 | `prompts/08-warm-iteration.md` |
+| Brand Kit Schema | ✅ 完整 | `schemas/brand-kit.schema.json` |
+| Brief Schema | ✅ 完整 | `schemas/brief.schema.json` |
+| Storyboard Schema | ✅ 完整 | `schemas/storyboard.schema.json` |
+| 3 个内置模板 | ✅ 完整结构 | `templates/` |
+| 7 个 workflow 文档 | ✅ 完整 | `workflows/` |
+| 5 个 QA 文档 | ✅ 完整 | `qa/` |
+| 4 个校验脚本 | ✅ 完整 | `scripts/` |
+| 3 个示例项目 | ✅ 完整 | `examples/zh-CN/` |
+| 用户文档（zh-CN）| ✅ 完整 | `docs/` |
+
+### 未完成 / 规划中（Not in v0.1）
+
+| 功能 | 状态 | 规划版本 |
+|------|------|---------|
+| 批量视频生成 | 🔴 未实现 | v0.2 |
+| 多模板 Composite | 🔴 未实现 | v0.2 |
+| TTS 音频同步 | 🔴 未实现 | v0.2 |
+| 云端渲染队列 | 🔴 未实现 | v0.3 |
+| 模板市场 | 🔴 未实现 | v0.3+ |
+| 英文文档 | 🟡 部分（en/ 目录有 README）| v0.2 |
+
+---
+
+## 核心文件职责（不要随便改这些）
+
+### 绝对不要改
+
+| 文件 | 原因 |
+|------|------|
+| `SKILL.md` | Hermes skill 入口，改动会导致 skill 无法加载或行为异常 |
+| `AGENTS.md` | Agent 协作规则，改动可能破坏 Hermes 的任务分配逻辑 |
+| `schemas/brief.schema.json` | Brief 字段约定，与所有 prompt 和脚本强耦合 |
+| `schemas/storyboard.schema.json` | Storyboard 约定，与 compose-hyperframes prompt 强耦合 |
+| `schemas/brand-kit.schema.json` | Brand Kit 约定，与 validate-brand-kit.js 强耦合 |
+| `CAPABILITY_BOUNDARY.md` | 能力边界文件，改动影响能力判断和拒绝逻辑 |
+
+### 可以谨慎修改
+
+| 文件 | 注意事项 |
+|------|---------|
+| `prompts/*.md` | 修改 prompt 前先理解其在工作流中的位置；阶段 1–8 有顺序依赖 |
+| `rules/*.md` | QA 规则修改后需重新测试示例项目的 lint 结果 |
+| `upstream/*.md` | 这是 HyperFrames 知识库参考，轻易修改可能导致 HTML 生成出错 |
+| `scripts/check-env.js` | 修改前确认测试通过，它是用户安装验证的第一道门 |
+
+### 可以自由修改 / 新增
+
+| 位置 | 内容类型 |
+|------|---------|
+| `docs/` | 用户文档 |
+| `examples/` | 示例项目 |
+| `qa/` | QA 清单和模板 |
+| `brand/` | 示例 Brand Kit |
+| `templates/*/customization-guide.md` | 模板自定义说明 |
+| `scripts/validate-*.js` | 校验脚本（新增或扩展） |
+
+---
+
+## 如何新增模板
+
+新增一个模板需要完成以下步骤：
+
+### Step 1：创建模板目录
+
+```
+hyperdirector/templates/你的模板名/
+├── README.md
+├── prompt.md
+├── DESIGN.md
+├── customization-guide.md
+├── variants/
+│   ├── 15s.md
+│   ├── 30s.md
+│   └── 60s.md
+└── assets/
+    └── README.md
+```
+
+命名规范：`{目标场景}-kit`，例如 `education-course-kit`、`podcast-clips-kit`。
+
+### Step 2：定义场景结构（`README.md`）
+
+```markdown
+# {模板名}
+
+## 适用场景
+...
+
+## 默认场景结构
+
+| 场景 | 时长建议 | Purpose | 目标 |
+|------|---------|---------|------|
+| Hook | 3–5s | hook | ... |
+| ... | ... | ... | ... |
+
+## 推荐时长
+...
+```
+
+### Step 3：编写生成 Prompt（`prompt.md`）
+
+```markdown
+# {模板名} 生成 Prompt
+
+你正在使用 {模板名} 模板生成视频。
+
+## 场景规则
+...
+
+## 视觉约束
+...
+
+## 禁止事项
+...
+```
+
+Prompt 必须遵循 `prompts/05-compose-hyperframes.md` 中定义的 HTML 结构规范：
+- 每个 scene 有 `data-duration`、`data-purpose`、`data-transition` 属性
+- GSAP timeline 注册到 `window.__hf_timeline`
+- CSS 使用品牌颜色变量
+
+### Step 4：注册到 Schema
+
+在 `schemas/brief.schema.json` 的 `template` 枚举中添加新模板名：
+
+```json
+"template": {
+  "enum": [
+    "tiktok-vertical-kit",
+    "saas-demo-kit",
+    "ai-knowledge-explainer-kit",
+    "你的新模板名"  // 添加这里
+  ]
+}
+```
+
+在 `schemas/storyboard.schema.json` 同样添加。
+
+**注意：** Schema 修改是破坏性变更，会影响所有现有校验脚本。确保新模板名格式符合 `kebab-case`，且不与现有模板冲突。
+
+### Step 5：更新 SKILL.md 和文档
+
+在 `SKILL.md` 的"支持的模板"部分添加新模板描述。在 `docs/template-guide.md` 中添加新模板的选择指南和示例。
+
+### Step 6：创建示例项目
+
+```
+examples/zh-CN/demo-{你的模板}-/
+├── README.md
+├── input/
+│   └── {输入文件}
+└── output/
+    ├── brief.json
+    ├── storyboard.json
+    ├── ...（完整输出文件）
+    └── assets/README.md
+```
+
+运行校验确认示例通过：
+
+```bash
+node scripts/validate-storyboard.js examples/zh-CN/demo-{模板名}/output/storyboard.json
+```
+
+---
+
+## 如何新增 Workflow
+
+Workflow 是特定输入类型到视频的端到端流程文档，存储在 `workflows/` 目录。
+
+### 现有 Workflow 列表
+
+| 文件 | 场景 |
+|------|------|
+| `article-to-video.md` | 文章转视频 |
+| `product-page-to-demo.md` | 产品页转 demo |
+| `github-repo-to-video.md` | GitHub README 转视频 |
+| `prd-to-product-video.md` | PRD 转产品视频 |
+| `data-chart-to-video.md` | 数据图表转视频 |
+| `batch-video-production.md` | 批量视频制作 |
+| `warm-iteration.md` | 迭代修改工作流 |
+
+### Workflow 文件结构
+
+```markdown
+# {输入类型} → 视频 工作流
+
+## 适用场景
+...
+
+## 前置要求
+...
+
+## 工作流步骤
+
+### Step 1：输入分析
+...
+
+### Step 2：Brief 配置建议
+- 推荐模板：...
+- 推荐时长：...
+...
+
+### Step 3：特殊处理说明
+...
+
+## 示例 Prompt
+...
+
+## 已知限制
+...
+```
+
+新增 workflow 只需按此格式创建 `.md` 文件，不需要修改 Schema 或 SKILL.md（除非有新的触发词需要注册）。
+
+---
+
+## 如何新增 QA 规则
+
+QA 规则存储在 `rules/` 目录，分两类：
+
+1. **运行时规则**（`rules/*.md`）：Hermes 在 QA Fix Loop 阶段读取，指导修复逻辑
+2. **校验脚本**（`scripts/validate-*.js`）：Node.js 脚本，本地运行检查文件合规性
+
+### 新增运行时规则
+
+在 `rules/` 目录创建新 `.md` 文件：
+
+```markdown
+# {规则名称}
+
+## 适用阶段
+QA / Compose / Design
+
+## 规则描述
+...
+
+## 检查项
+
+| 检查项 | 正确示例 | 错误示例 |
+|--------|---------|---------|
+| ... | ... | ... |
+
+## 自动修复方法
+...
+
+## 无法自动修复的情况
+...
+```
+
+将新规则文件路径添加到 `prompts/06-qa-fixer.md` 的规则引用列表中，确保 Hermes 在 QA 阶段会读取它。
+
+### 新增校验脚本
+
+在 `scripts/` 目录创建 `validate-{名称}.js`。遵循现有脚本的规范：
+
+```javascript
+#!/usr/bin/env node
+/**
+ * HyperDirector {名称} Validator
+ *
+ * Usage:
+ *   node hyperdirector/scripts/validate-{名称}.js <path-to-file.json>
+ *
+ * Exit codes:
+ *   0 — passed
+ *   1 — failed
+ */
+
+'use strict';
+const fs   = require('fs');
+const path = require('path');
+
+// 使用与现有脚本相同的颜色常量
+const RESET = '\x1b[0m';
+const GREEN = '\x1b[32m';
+const RED   = '\x1b[31m';
+const YELLOW= '\x1b[33m';
+const BOLD  = '\x1b[1m';
+
+// 实现 pass() / fail() / warn() 函数（参考 validate-brief.js）
+
+const filePath = process.argv[2];
+// ... 检查逻辑 ...
+
+// 退出时使用 process.exit(0) 或 process.exit(1)
+```
+
+**规范要求：**
+- 只使用 Node.js 内置模块（`fs`、`path`），不引入 npm 依赖
+- 支持命令行参数（`process.argv[2]`）
+- 通过时输出明确的成功信息并 `exit(0)`
+- 失败时输出明确的错误原因并 `exit(1)`
+- 遵循现有脚本的颜色输出风格
+
+---
+
+## 如何贡献 Demo
+
+每个 demo 演示一个真实用户场景，结构必须完整。
+
+### Demo 目录结构
+
+```
+examples/zh-CN/demo-{场景名}/
+├── README.md                    ← 说明场景、预览方式、渲染方式
+├── input/
+│   └── {输入文件.md}             ← 用户提供的原始内容
+└── output/
+    ├── brief.json               ← 必须通过 validate-brief.js
+    ├── storyboard.json          ← 必须通过 validate-storyboard.js
+    ├── script.md                ← 逐场景旁白文稿
+    ├── DESIGN.md                ← 视觉设计说明
+    ├── brand-used.json          ← 必须通过 validate-brand-kit.js
+    ├── index.html               ← HyperFrames 合成（必须可以在浏览器打开）
+    ├── preview.html             ← 预览入口（iframe 包装 index.html）
+    ├── edit-instructions.md     ← 二次编辑指南
+    ├── render-report.sample.md  ← 模拟渲染报告（标注 NOT EXECUTED）
+    └── assets/
+        └── README.md
+```
+
+### 贡献 Checklist
+
+贡献 demo 前，运行完整校验：
+
+```bash
+# 校验所有 JSON 文件
+node hyperdirector/scripts/validate-brief.js \
+  examples/zh-CN/demo-你的示例/output/brief.json
+
+node hyperdirector/scripts/validate-storyboard.js \
+  examples/zh-CN/demo-你的示例/output/storyboard.json \
+  examples/zh-CN/demo-你的示例/output/brief.json
+
+node hyperdirector/scripts/validate-brand-kit.js \
+  examples/zh-CN/demo-你的示例/output/brand-used.json
+
+# 检查输出完整性
+node hyperdirector/scripts/check-output-contract.js \
+  examples/zh-CN/demo-你的示例/output/
+
+# 在浏览器中打开 index.html，确认动画正常播放
+```
+
+**必须通过：**
+- ✅ `validate-brief.js` 零错误
+- ✅ `validate-storyboard.js` 零错误，时长无偏差
+- ✅ `validate-brand-kit.js` 零错误
+- ✅ `index.html` 在浏览器中能播放动画（点击画面）
+- ✅ `preview.html` 能正常加载
+- ✅ `render-report.sample.md` 标注 "NOT EXECUTED"（不要声称已渲染）
+
+**render-report.sample.md 注意：**
+
+```markdown
+> ⚠️ 声明：本报告为模拟样本，未实际执行渲染。
+```
+
+这一行必须出现在报告顶部，避免误导用户。
+
+### Demo 命名规范
+
+- 目录名：`demo-{内容类型}-{场景特征}`（全小写 kebab-case）
+- 示例：`demo-article-to-video`、`demo-saas-product`、`demo-github-repo`
+- 不要用真实客户品牌名作为目录名（`demo-acme-corp-real-client` ❌）
+
+---
+
+## 工作流阶段依赖关系
+
+以下是 8 个 prompt 阶段的执行顺序和依赖：
+
+```
+01-capability-judge.md
+  ↓（通过 → 继续，拒绝 → 停止）
+02-intake-brief.md
+  ↓（输出 brief.json）
+03-storyboard-generator.md
+  ↓（输出 storyboard.json）
+04-visual-design.md
+  ↓（输出 DESIGN.md）
+05-compose-hyperframes.md
+  ↓（输出 index.html）
+06-qa-fixer.md
+  ↓（循环最多 3 次，输出 qa-report.md）
+07-render-report.md
+  ↓（输出 render-report.md）
+08-warm-iteration.md ← 二次迭代时从这里开始
+```
+
+**修改 prompt 的注意事项：**
+- 每个 prompt 依赖前一阶段的输出（brief.json → storyboard.json → ...）
+- 不要在某个阶段 prompt 中假设后续阶段的文件已存在
+- `06-qa-fixer.md` 会循环执行，确保修复指令幂等（重复执行不产生副作用）
+
+---
+
+## 本地开发和测试
+
+### 运行所有示例的完整校验
+
+```bash
+# 校验 demo-article-to-video
+node hyperdirector/scripts/validate-brief.js \
+  hyperdirector/examples/zh-CN/demo-article-to-video/output/brief.json
+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
+
+# 校验 demo-saas-product
+node hyperdirector/scripts/validate-storyboard.js \
+  hyperdirector/examples/zh-CN/demo-saas-product/output/storyboard.json \
+  hyperdirector/examples/zh-CN/demo-saas-product/output/brief.json
+
+# 校验 demo-github-repo
+node hyperdirector/scripts/validate-storyboard.js \
+  hyperdirector/examples/zh-CN/demo-github-repo/output/storyboard.json \
+  hyperdirector/examples/zh-CN/demo-github-repo/output/brief.json
+```
+
+### 验证 Schema 一致性
+
+当修改 Schema 文件时，手动确认现有示例仍能通过校验脚本。Schema 是向后兼容的——新增字段时设置为 optional，不要删除已有字段。
+
+---
+
+## 版本管理建议
+
+- `hyperdirector/` 内的所有文件都应该进入版本控制
+- `output/` 目录（生成的视频项目）不应进入版本控制（`.gitignore`）
+- `brand-kit.json`（用户配置）不应进入版本控制
+
+`.gitignore` 建议：
+
+```
+output/
+brand-kit.json
+*.mp4
+```
+
+---
+
+## 已知技术债务（v0.1）
+
+| 问题 | 影响 | 计划修复时间 |
+|------|------|------------|
+| `storyboard.schema.json` 中 `purpose` 枚举不含所有模板的 purpose 值（如 `big_claim`、`action`）| validate-storyboard.js 对 demo-github-repo 的 `big_claim` 和 `action` 会报警告 | v0.2 |
+| `index.html` 中 GSAP CDN 使用 integrity hash，但 hash 可能随 CDN 版本更新失效 | 离线或 CDN 切换时 GSAP 加载失败 | v0.2（改为本地 bundle）|
+| Emoji 图标在无头渲染环境中渲染不一致 | demo-github-repo 的用户类型图标 | v0.2（改为 SVG）|
+
+---
+
+*本文档最后更新：2026-05-07 · HyperDirector v0.1*