AI 音视频创作模板系统
模块概述
版本: v1.0.0 状态: ✅ 已实现 最后更新: 2026-03-17
cc init --template ai-media-creator 在项目初始化时自动生成一套 AI 音视频创作 工作区配置，包含 Persona、rules.md、以及 3 个 workspace 层技能（comfyui-image / comfyui-video / audio-gen），并创建 workflows/ 示例目录。
核心特性
- 8 种 init 模板之一: 继承 Persona 系统（config.json + persona 字段 + auto 激活技能）
- 3 个媒体 workspace 技能: 自动生成到
.chainlesschain/skills/，直接可用 - ComfyUI REST API 集成: comfyui-image/comfyui-video 直接调用 http://localhost:8188
- 4后端 TTS 降级链: edge-tts → piper-tts → ElevenLabs API → OpenAI TTS
- cli-anything 设计边界: 明确说明 REST-first 工具（ComfyUI）不适合 cli-anything，CLI 工具（FFmpeg、yt-dlp）适合
- 114 个测试: 40 单元 + 33 集成 + 41 E2E，全部通过
1. 架构设计
1.1 整体架构图
init --template ai-media-creator
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ init.js TEMPLATES["ai-media-creator"] │
│ - persona: "AI创作助手" │
│ - rules: ComfyUI配置 + cli-anything边界说明 │
│ - generateSkills: ["comfyui-image","comfyui-video","audio-gen"]│
└──────────────────────────────┬──────────────────────────────────┘
│ 遍历 tmpl.generateSkills
▼
┌─────────────────────────────────────────────────────────────────┐
│ SKILL_TEMPLATES (init.js 顶部常量) │
│ comfyui-image: { md, handler } │
│ comfyui-video: { md, handler } │
│ audio-gen: { md, handler } │
└──────────────────────────────┬──────────────────────────────────┘
│ 写入 workspace 层
▼
┌─────────────────────────────────────────────────────────────────┐
│ .chainlesschain/skills/ │
│ comfyui-image/ SKILL.md + handler.js │
│ comfyui-video/ SKILL.md + handler.js │
│ audio-gen/ SKILL.md + handler.js │
│ ai-media-creator-persona/ SKILL.md (activation: auto) │
│ workflows/ │
│ README.md (工作流导出指南) │
└──────────────────────────────┬──────────────────────────────────┘
│ skill-loader 四层加载
▼
┌─────────────────────────────────────────────────────────────────┐
│ chainlesschain skill run comfyui-image "prompt" │
│ chainlesschain skill run comfyui-video "prompt" --workflow ... │
│ chainlesschain skill run audio-gen "text" │
└─────────────────────────────────────────────────────────────────┘1.2 与 CLI-Anything 的设计边界
| 工具类型 | 接口形式 | 推荐集成方式 |
|---|---|---|
| ComfyUI | REST API（POST /prompt, GET /history） | workspace 技能（handler.js 直接 HTTP） |
| FFmpeg | CLI 命令 | chainlesschain cli-anything register ffmpeg |
| yt-dlp | CLI 命令 | chainlesschain cli-anything register yt-dlp |
| 第三方 ComfyUI CLI 包装 | CLI 命令 | chainlesschain cli-anything register <wrapper> |
| edge-tts | Python 模块 + CLI | audio-gen handler 直接调用 python -m edge_tts |
2. 三个媒体技能详解
2.1 comfyui-image（文生图/图生图）
执行流程：
handler(params)
│
├─ 参数校验: prompt 必填
│
├─ GET /system_stats → 检查 ComfyUI 连接
│ └─ 失败 → 返回连接错误 + 启动提示
│
├─ 加载工作流: params.workflow 指定文件 OR 使用内置默认工作流
│ 默认工作流: CheckpointLoader → EmptyLatentImage → CLIPTextEncode(×2)
│ → KSampler → VAEDecode → SaveImage
│
├─ POST /prompt { prompt: workflowJson }
│ └─ 获取 prompt_id
│
└─ 轮询 GET /history/{prompt_id} 每 2s 一次，超时 120s
└─ completed → 收集 outputs[*].images → 返回 URL 列表默认工作流参数：
| 参数 | 默认值 | 说明 |
|---|---|---|
| width | 512 | 图像宽度 |
| height | 512 | 图像高度 |
| steps | 20 | 采样步数 |
| cfg | 7 | 引导系数 |
| sampler | euler | 采样器 |
| checkpoint | v1-5-pruned-emaonly.ckpt | 模型（需与本地匹配） |
2.2 comfyui-video（AnimateDiff 视频）
AnimateDiff 工作流高度依赖具体模型配置，必须提供工作流 JSON 文件。
handler(params)
│
├─ 参数校验: prompt 必填
├─ 工作流校验: workflow 必填 → 不提供直接返回 AnimateDiff 安装指南
│
├─ GET /system_stats → 检查 ComfyUI 连接
│
├─ 读取 workflow JSON 文件（相对路径从 cwd 解析）
│ └─ 文件不存在/JSON 格式错误 → 返回具体错误
│
├─ POST /prompt { prompt: workflowJson }
│
└─ 轮询 GET /history/{prompt_id} 每 3s 一次，超时 300s
└─ 收集 videos + gifs + images 三类输出 → 返回 URL 列表2.3 audio-gen（TTS 语音合成）
4 后端按优先级依次尝试：
handler({ text, voice, output })
│
├─ 参数校验: text 必填
├─ 创建 outputDir (如不存在)
│
├─ 优先级 1: commandExists("edge-tts") || checkPythonModule("edge_tts")
│ └─ python -m edge_tts --voice <voice> --text <text> --write-media <output>
│
├─ 优先级 2: commandExists("piper")
│ └─ echo "<text>" | piper --output_file <output>
│
├─ 优先级 3: process.env.ELEVENLABS_API_KEY
│ └─ HTTPS POST api.elevenlabs.io/v1/text-to-speech/<voiceId>
│
├─ 优先级 4: process.env.OPENAI_API_KEY
│ └─ HTTPS POST api.openai.com/v1/audio/speech
│
└─ 全部失败 → 返回安装指引3. SKILL.md 字段规范
ai-media-creator 技能使用标准 SKILL.md 字段，新增 category: media（此前已有的类别包括 productivity、code、analysis 等）：
yaml
---
name: comfyui-image
display-name: ComfyUI 图像生成
category: media # 新增类别
description: 通过 ComfyUI REST API 生成图像...
version: 1.0.0
author: ChainlessChain
parameters:
- name: prompt
type: string
required: true
description: 图像生成提示词
execution-mode: direct # 与 CLI 技能包同字段
---4. rules.md 设计原则
ai-media-creator 的 rules.md 重点说明两件事：
- 工具接入方式选择: ComfyUI 是 REST API → workspace 技能；有 CLI 的工具 → cli-anything
- 工作流管理规范: workflows/ 目录、命名规范、API Format 导出要求
这使 AI 助手在项目内能正确决策"用哪种方式集成新工具"。
5. 文件结构
packages/cli/
├── src/commands/init.js
│ ├── SKILL_TEMPLATES # comfyui-image / comfyui-video / audio-gen 模板字符串
│ ├── WORKFLOW_README # workflows/README.md 模板字符串
│ └── TEMPLATES["ai-media-creator"]
│ ├── description
│ ├── rules
│ ├── skills: [...]
│ ├── persona: {...}
│ └── generateSkills: ["comfyui-image","comfyui-video","audio-gen"]
└── __tests__/
├── unit/
│ └── init-ai-media-creator.test.js # 40 tests: 模板结构/YAML/JS语法验证
├── integration/
│ └── ai-media-creator-handlers.test.js # 33 tests: 生成文件加载/handler错误路径
└── e2e/
└── init-and-cowork-commands.test.js # 7 新增 ai-media-creator 测试 (共41)6. 测试覆盖
| 测试层 | 文件 | 测试数 | 覆盖内容 |
|---|---|---|---|
| 单元 | init-ai-media-creator.test.js | 40 | SKILL_TEMPLATES 结构/YAML 字段/JS 语法/WORKFLOW_README/TEMPLATES 对象 |
| 集成 | ai-media-creator-handlers.test.js | 33 | 生成文件加载/comfyui-image错误路径/comfyui-video workflow缺失/audio-gen no-backends/编码检查 |
| E2E | init-and-cowork-commands.test.js | 7（新增） | 模板创建/3个技能文件/workflows目录/persona/rules内容 |
| 合计 | 80（新增） | 全部通过 |
7. 设计决策
为什么 SKILL_TEMPLATES 定义在 init.js 而非独立文件？
技能模板是初始化命令的一部分——它们只在 cc init 时使用一次。将其内联于 init.js 避免了引入额外的依赖文件，保持 CLI 包的轻量性（~2MB）。如果将来有更多生成型模板，可以抽取为 src/lib/init-skill-templates/ 目录。
为什么 ComfyUI 不通过 cli-anything 注册？
cli-anything 的设计目标是包装已有 CLI 接口的工具（命令行参数 → Agent 工具调用）。ComfyUI 的主要接口是 REST API（POST /prompt、GET /history/{id}），不提供等价的 CLI 接口。将其强行包装为 CLI 需要额外的 Python 中间层，维护成本高，而直接 HTTP 调用更简洁。
为什么 AnimateDiff 要求用户提供工作流文件？
AnimateDiff 工作流需要针对具体的检查点模型、AnimateDiff 模型版本和用户偏好参数高度定制。内置一个"通用工作流"会因用户环境差异而频繁报错。要求用户从 ComfyUI UI 中导出 API 格式 JSON 是 ComfyUI 生态的标准实践。
为什么 audio-gen 支持 4 个 TTS 后端？
不同用户环境差异很大：
- 中国用户通常可以使用 edge-tts（微软服务，无需 API Key）
- 离线/本地优先用户使用 piper-tts
- 高质量需求用户使用 ElevenLabs 或 OpenAI TTS
降级链确保在任何环境下都能工作，同时用户可以通过环境变量精确控制使用哪个后端。