@baimingtao/lbs-agent 1.0.0

package/extensions/skills/optional/creative/kanban-video-orchestrator/references/kanban-setup.md

@@ -0,0 +1,271 @@
+# Kanban 配置 — Project Bootstrap 与 Profile 配置
+
+Once the brief is locked and the team is designed, the next step is producing
+the actual `setup.sh` that creates the project workspace, configures Hermes
+profiles, and fires the initial kanban task.
+
+This file documents the patterns. The companion script
+`scripts/bootstrap_pipeline.py` automates most of it from a structured input
+JSON.
+
+> **Credit:** the single-project-workspace layout, profile-config patching
+> approach, SOUL.md-per-profile convention, and `--workspace dir:<path>` rule
+> are adapted from alt-glitch's original multi-agent video pipeline:
+> [NousResearch/kanban-video-pipeline](https://github.com/NousResearch/kanban-video-pipeline).
+> 这个 skill generalizes those patterns across video styles and replaces the
+> string-replacement config patcher with a PyYAML-based one.
+
+## Project workspace structure
+
+Every video project gets one workspace under `~/projects/video-pipeline/<slug>/`:
+
+```
+~/projects/video-pipeline/<slug>/
+├── brief.md                       ← the contract; all tasks reference
+├── TEAM.md                        ← team composition + task graph (director reads this)
+├── taste/
+│   ├── brand-guide.md             ← color, typography, motion rules
+│   ├── emotional-dna.md           ← what the piece should FEEL like
+│   └── style-frames/              ← optional: visual references
+├── audio/
+│   ├── track.mp3                  ← provided music (if any)
+│   ├── voiceover/                 ← per-line TTS clips
+│   └── sfx/                       ← sound effects
+├── assets/
+│   ├── logos/
+│   ├── fonts/
+│   └── existing-footage/          ← reusable provided clips
+├── scenes/
+│   ├── scene-01/
+│   │   ├── VISUAL_SPEC.md         ← cinematographer's per-scene spec
+│   │   ├── render.py              ← renderer's code (or sketch.html, etc.)
+│   │   ├── checkpoints/           ← preview frames for QA
+│   │   └── clip.mp4               ← the deliverable for this scene
+│   ├── scene-02/...
+│   └── ...
+├── checkpoints/                   ← global review frames
+├── tools/                         ← optional project-local helpers
+└── output/
+    ├── final.mp4                  ← stitched + audio
+    ├── final-noaudio.mp4
+    ├── final-9x16.mp4             ← optional: vertical alternate
+    └── captions.srt               ← optional: subtitle file
+```
+
+**The slug** is derived from the brief title: lowercase, hyphen-separated.
+示例: `q3-product-teaser`, `ascii-mood-loop`, `interview-cut-2026-q1`.
+
+## The setup.sh script
+
+The setup script does six things in order:
+
+1. **Create workspace tree** — all directories above
+2. **Create profiles** — `hermes profile create <name> --clone`
+3. **Configure profiles** — patch each profile's
+   `~/.hermes/profiles/<name>/config.yaml` to set toolsets, always_load skills,
+   and `cwd`
+4. **Write SOUL.md per profile** — the personality + role definition
+5. **Copy any provided assets + write `brief.md`, `TEAM.md`, and `taste/`**
+6. **Fire the initial kanban task** — `hermes kanban create` assigned to the director
+
+See `assets/setup.sh.tmpl` for the skeleton.
+
+### Profile creation pattern
+
+```bash
+hermes profile create director --clone 2>/dev/null || true
+```
+
+The `--clone` flag clones from the active profile (preserving model, base
+config). The `|  | true` makes the script idempotent — re-running won't error if
+the profile already exists.
+
+### Profile config patching
+
+Each profile has a YAML config at `~/.hermes/profiles/<name>/config.yaml`. The
+setup script edits exactly two keys:
+
+1. `toolsets:` — replace the default with the role's required toolsets
+2. `skills.always_load:` — list the role's must-load skills (may be empty)
+
+**Do NOT** modify `approvals.mode` (controls user-confirmation of tool calls
+— a security setting that must stay as the user configured it). **Do NOT**
+modify `terminal.cwd` — the kanban dispatcher overrides cwd per-task via
+`--workspace dir:<path>`, so the profile's cwd is irrelevant to the kanban
+work and changing it could break the user's interactive use of the profile.
+
+Use **PyYAML**, not string replacement, so the patch is robust against
+default-config schema drift:
+
+```bash
+configure_profile() {
+    local profile="$1"
+    local toolsets_json="$2"     # JSON array, e.g. '["kanban","terminal","file"]'
+    local skills_json="$3"       # JSON array, e.g. '["ascii-video"]'
+    python3 - "$profile" "$toolsets_json" "$skills_json" <<'PY'
+import json, os, sys, yaml
+profile, ts_json, sk_json = sys.argv[1:4]
+p = os.path.expanduser(f"~/.hermes/profiles/{profile}/config.yaml")
+with open(p) as f:
+    cfg = yaml.safe_load(f) or {}
+cfg["toolsets"] = json.loads(ts_json)
+cfg.setdefault("skills", {})["always_load"] = json.loads(sk_json)
+with open(p, "w") as f:
+    yaml.safe_dump(cfg, f, sort_keys=False)
+PY
+}
+```
+
+PyYAML must be installed in the user's Python (it ships with most Hermes
+installs). If absent: `pip install pyyaml`.
+
+The setup script should also **validate** the patch by re-reading the file
+and comparing — see `assets/setup.sh.tmpl` for the validation pattern.
+
+### SOUL.md per profile
+
+Each profile gets a `SOUL.md` at `~/.hermes/profiles/<name>/SOUL.md` that
+defines its role, voice, and rules. See `assets/soul.md.tmpl` for the
+template. Customize per role and per project.
+
+The director's SOUL.md should be the most opinionated — its voice flavors
+the entire production. **Critical content for the director's SOUL.md:**
+
+- **Anti-temptation rules:** "Do not execute the work yourself. For every
+  concrete task, create a kanban task and assign it. Decompose, route, comment,
+  approve — that's the whole job." (The kanban orchestration guidance is
+  auto-injected into every kanban worker's system prompt — no skill to load.)
+- **Decomposition steps:** Read `brief.md`, `TEAM.md`, `taste/`. Use the team
+  graph in `TEAM.md` to fan out tasks.
+- **The workspace_path rule** (see below).
+
+Other profiles' SOUL.md is briefer; mostly mechanical: who you are, what you
+read, what you produce, what skills/tools to use, where to write outputs.
+The kanban lifecycle guidance is auto-injected into every kanban worker's
+system prompt, so no profile needs to load a kanban skill.
+
+### Initial kanban task
+
+The final action of setup.sh is firing the kanban:
+
+```bash
+hermes kanban create "Direct production of <video title>" \
+    --assignee director \
+    --workspace dir:"$HOME/projects/video-pipeline/${PROJECT_SLUG}" \
+    --tenant ${PROJECT_SLUG} \
+    --priority 2 \
+    --max-runtime 4h \
+    --body "$(cat <<EOF
+Read brief.md, TEAM.md, and taste/.
+Decompose into the team graph defined in TEAM.md.
+All child tasks MUST use:
+  workspace_kind="dir"
+  workspace_path="$HOME/projects/video-pipeline/${PROJECT_SLUG}"
+  tenant="${PROJECT_SLUG}"
+EOF
+)"
+```
+
+The `--workspace dir:<path>` flag is **critical** — it tells the kanban that
+all child tasks share this workspace. Skipping or using `worktree` will
+isolate profiles and break artifact sharing.
+
+## The TEAM.md file
+
+Alongside `brief.md`, write a `TEAM.md` that the director reads. It documents
+the team composition + task graph the orchestrator should follow. This
+removes ambiguity and prevents the director from inventing extra steps.
+
+示例 structure (for an ASCII video with a music supervisor and editor):
+
+```markdown
+# Team & Task Graph — <video title>
+
+## Team
+
+- `director` (this profile) — vision, decomposition, approval
+- `cinematographer` — visual spec, quality review (loads `ascii-video`)
+- `renderer-ascii` — ASCII scenes (loads `ascii-video`)
+- `music-supervisor` — track analysis (loads `songsee`)
+- `voice-talent` — narration (uses ElevenLabs API)
+- `audio-mixer` — final mix (ffmpeg)
+- `editor` — assembly (ffmpeg)
+- `reviewer` — final QA gate
+
+## Task Graph
+
+T0: this task — decompose
+ │
+ ├── T1: cinematographer  "Design visual language"            (parent: T0)
+ │    │
+ │    ├── T2a: renderer-ascii   "Scene 1 — title card"        (parent: T1)
+ │    ├── T2b: renderer-ascii   "Scene 2 — main beat"         (parent: T1)
+ │    ├── T2c: renderer-ascii   "Scene 3 — outro"             (parent: T1)
+ │
+ ├── T3: music-supervisor "Analyze track + emit beats.json"   (parent: T0)
+ │
+ ├── T4: voice-talent     "Generate narration"                (parent: T0)
+ │
+ ├── T5: audio-mixer      "Mix VO + bg music"                 (parents: T3, T4)
+ │
+ ├── T6: editor           "Assemble cut + mux audio"          (parents: T2*, T5)
+ │
+ └── T7: reviewer         "Final QA"                          (parent: T6)
+```
+
+The director turns this into actual `kanban_create` calls.
+
+## API-key prerequisites check
+
+Before firing the kanban, verify required keys are available. Check both
+the Hermes `.env` (`${HERMES_HOME:-$HOME/.hermes}/.env`) and macOS Keychain
+(if on macOS):
+
+```bash
+check_key() {
+    local var="$1"
+    local kc_account="$2"
+    local kc_service="$3"
+    local _hermes_env="${HERMES_HOME:-$HOME/.hermes}/.env"
+    if grep -q "^${var}=" "$_hermes_env" 2>/dev/null && \
+       [ -n "$(grep "^${var}=" "$_hermes_env" | cut -d= -f2-)" ]; then
+        return 0
+    fi
+    if command -v security >/dev/null 2>&1 && \
+       security find-generic-password -a "${kc_account}" -s "${kc_service}" -w >/dev/null 2>&1; then
+        return 0
+    fi
+    echo "ERROR: ${var} not set in ${_hermes_env} or Keychain (${kc_account}/${kc_service})"
+    return 1
+}
+
+check_key ELEVENLABS_API_KEY hermes ELEVENLABS_API_KEY || exit 1
+check_key OPENROUTER_API_KEY hermes OPENROUTER_API_KEY || exit 1
+# ...
+```
+
+If a key is missing, the script aborts with a clear message rather than
+firing a kanban that will hit credential errors mid-execution.
+
+## Critical rules
+
+1. **`workspace_kind="dir"` + `workspace_path="<absolute>"` on every kanban_create.** 否则 profile 将无法共享产物。
+
+2. **Tenant every task.** `--tenant <project-slug>` 保持 dashboard 范围隔离，防止与其他正在进行的 kanban 任务交叉污染。
+
+3. **Idempotency keys.** 对于重跑时不应重复创建的任务（例如，setup 创建 profiles 时），请使用 `idempotency_key` 参数或先检查其是否存在。
+
+4. **`max_runtime_seconds` per task.** 卡住的 Renderer 会消耗计算资源。
+   标准默认值：
+   - Renderer task: 1800s (30分钟)
+   - Editor task: 600s (10分钟)
+   - Voice-talent task: 300s (5分钟)
+   - Image-generator task: 600s (10分钟)
+   - Image-to-video-generator task: 900s (15分钟)
+
+5. **Heartbeats for long renders.** 预计运行时间超过 5 分钟的任务应定期触发 `kanban_heartbeat` 汇报进度。Renderer 应汇报帧数；Editor 应汇报剪辑进度。
+
+6. **The `audio/` and `taste/` dirs are populated BEFORE firing the kanban.**
+   不要让 director 的 pipeline 去获取这些内容——应在 setup 阶段完成复制。
+
+7. **`brief.md` is read-only after setup.** 如果在执行期间需求简介发生变化，那将是一次重大的调整——请重新触发 kanban，而不是在运行中直接修改。

package/extensions/skills/optional/creative/kanban-video-orchestrator/references/monitoring.md

@@ -0,0 +1,155 @@
+# 监控 —— 关注流水线并进行干预
+
+在 `setup.sh` 触发看板之后，工作将自动运行。在执行阶段，这项技能的作用是帮助用户（以及监督会话的 AI）及早发现问题并进行有效干预。
+
+## 实时监控命令
+
+```bash
+# Live event stream — task spawns, status changes, heartbeats, completions
+hermes kanban watch --tenant <project-slug>
+
+# Snapshot of the board
+hermes kanban list --tenant <project-slug>
+hermes kanban list --tenant <project-slug> --json     # machine-readable
+
+# Per-status counts + oldest-ready age
+hermes kanban stats --tenant <project-slug>
+
+# Visual dashboard (browser)
+hermes dashboard
+
+# Inspect a specific task (includes comments + events)
+hermes kanban show <task-id>
+
+# Follow a single task's event stream
+hermes kanban tail <task-id>
+```
+
+使用 `hermes kanban --help` 验证可用的子命令 —— kanban CLI 自带了 `init / create / list / show / assign / link / unlink / claim / comment / complete / block / unblock / archive / tail / dispatch / watch / stats / heartbeat / log / runs / context / gc`。
+
+配套的 `scripts/monitor.py` 会通过 CLI 轮询看板，并暴露出常见问题（任务卡住、缺少心跳、反复重试、依赖死锁）。
+
+## 关注点
+
+### 健康的流水线指标
+
+- 任务大致按预期顺序经历 `READY → RUNNING → DONE` 的状态转换
+- 渲染器定期发出带有进度的 `kanban_heartbeat` 事件（例如 "frame 240/720"）
+- 每个任务的运行时间远低于其 `max_runtime_seconds` 上限
+- 没有任务累积超过 1 次重试
+- 依赖箭头能正常解除（随着父任务完成，子任务随之解除阻塞）
+
+### 警告迹象
+
+| 症状 | 可能原因 | 操作 |
+| --------- | -------------- | -------- |
+| 任务处于 RUNNING 状态但超过 2 分钟没有心跳 | Worker 卡住、无限循环、等待输入阻塞 | `hermes kanban show <id>` —— 阅读 worker 的最后事件。调度器会向超过其 `max-runtime` 的任务发送 SIGTERM；如果你需要提前停止某个任务，执行 `hermes kanban block <id>` 然后 `hermes kanban archive <id>`，并创建一个重新运行的任务。 |
+| 同一任务重试 2 次以上 | 可复现的失败（缺少密钥、规范错误、工具损坏） | 执行 `hermes kanban show <id>` 读取失败事件。在重新运行之前修复根本原因。 |
+| RUNNING 状态超过 max_runtime | 任务很慢但仍在进展，或者真的卡住了 | 使用 `hermes kanban tail <id>` 检查心跳。如果在进展中，调度器最终无论如何都会发送 SIGTERM —— 在重建任务时调大 `max-runtime`。 |
+| 子任务处于 READY 状态，但父任务处于 RUNNING 状态的时间超过预期的 2 倍 | 级联变慢，依赖配置错误 | 检查依赖图。检查父任务：有时它已完成，但其交接字段（摘要、元数据）为空，导致子任务无法获取内容。 |
+| 未出现新任务 | Director 在分解过程中挂起 | 使用 `kanban show` 检查 director 任务。通常是由于格式错误的 `kanban_create` 调用引起的。 |
+| Specialist 任务瞬间完成 | 分解创建的任务没有正文 | Director 没有传递足够的 context。使用明确的正文内容重新创建。 |
+| 任务已创建但从未被接收 | Profile 未运行、或 tenant 不匹配、或调度器未运行 | 检查 `hermes profile list`（profile 是否存在？）、`hermes status`（gateway/dispatcher 是否启动？）并验证 tenant。 |
+| 特定的 renderer 任务失败 → 审查记录 → renderer 重做 → 再次失败 | 需求简报在强人所难 | 调整需求简报，而不是 renderer。 |
+
+## 干预方案
+
+### 拒绝错误的输出
+
+当 renderer 交付了一个未通过审查的片段时：
+
+```bash
+# 1. Comment on the renderer's task with specific feedback
+hermes kanban comment <renderer-task-id> "Scene 3 looks too sparse \
+— increase visual density. Tighten color palette to brand spec."
+
+# 2. Create a re-render task with the original as parent
+hermes kanban create "Scene 3 — re-render with feedback" \
+    --assignee renderer-ascii \
+    --parent <renderer-task-id> \
+    --workspace dir:"$HOME/projects/video-pipeline/<slug>" \
+    --tenant <slug> \
+    --skill ascii-video \
+    --max-runtime 30m
+```
+
+### 在执行过程中添加新依赖
+
+当编辑器需要一个最初未计划的资产（例如，字幕文件）时：
+
+```bash
+# 1. Create the new task and capture its id
+NEW_TASK_ID=$(hermes kanban create "Generate SRT captions from voiceover" \
+    --assignee captioner \
+    --workspace dir:"$HOME/projects/video-pipeline/<slug>" \
+    --tenant <slug> \
+    --json | python3 -c "import json,sys;print(json.load(sys.stdin)['id'])")
+
+# 2. Wire it as a parent of the editor's task with `kanban link`
+hermes kanban link "$NEW_TASK_ID" <editor-task-id>
+```
+
+`kanban link` 接收参数 `parent_id child_id`（父任务在前）。使用 `kanban unlink` 移除依赖。
+
+### 停止卡住的 worker
+
+如果任务超过其 `--max-runtime`，kanban 调度器会自动发送 SIGTERM（随后是 SIGKILL）。要提前停止任务：
+
+```bash
+# Mark blocked so the dispatcher leaves it alone, then archive
+hermes kanban block <task-id>
+hermes kanban archive <task-id>
+
+# Diagnose what happened
+hermes kanban show <task-id>      # task body, comments, recent events
+hermes kanban tail <task-id>      # follow the live event stream
+hermes kanban log <task-id>       # worker process log
+```
+
+停止后，决定：是修复根本原因并重新创建任务，还是跳过并调整依赖任务。
+
+### 调整需求简报
+
+如果在执行过程中，用户想要从根本上改变需求：
+
+1. 取消处于活跃状态的 director 任务及其所有处于 RUNNING 状态的子任务
+2. 编辑 `brief.md` 和 `TEAM.md`
+3. 重新触发 director 的初始命令 `hermes kanban create`
+
+不要尝试在“运行中编辑” —— 看板的审计记录使得一次干净的调整比中途修改更加清晰易读。
+
+## 定期检查脚本
+
+一种用于脱手监控的简单轮询模式：
+
+```bash
+while true; do
+    clear
+    hermes kanban list --tenant <slug>
+    echo "---"
+    hermes kanban stats --tenant <slug>
+    sleep 30
+done
+```
+
+要获取实时事件流，请在单独的终端中运行 `hermes kanban watch --tenant <slug>` —— 它会在任务生命周期事件发生时进行流式传输。
+
+有关自动干预（自动重启卡住的任务、在审查失败时自动创建重新渲染任务），请参阅 `scripts/monitor.py` 中的模式。
+
+## 何时宣告完成
+
+当满足以下条件时，流水线即告完成：
+
+1. 所有 RENDER 任务完成并通过审查
+2. 编辑器的 `output/final.mp4` 存在，且 `ffprobe` 确认其时长和流符合预期
+3. 审查者（如果存在）已批准
+4. 存在可选的 masterer 变体
+
+此时，向用户展示 final.mp4 的路径以及任何审查记录。不要删除工作区 —— 用户可能希望在不重新运行整个流水线的情况下对单个场景进行迭代。
+
+## 常见陷阱
+
+- **Tenant 不匹配。** 使用错误的 tenant 创建的任务将不会出现在监控中。请始终保持一致地使用 `--tenant <slug>`。
+- **Profile 进程未运行。** 如果该 profile 没有在线的 worker，任务将在 READY 状态下无限排队。检查 `hermes profile list` 并启动任何缺失的 profile。
+- **工作区权限。** 所有 profile 都需要对工作区目录具有读+写权限。如果任何 worker 报告权限错误，请执行 `chmod -R u+rw <workspace>`。
+- **音视频同步。** 编辑器的片段拼接必须匹配 renderer 的实际输出时长。不要在编辑器中硬编码场景时长 —— 应从 renderer 的交接元数据中读取。

package/extensions/skills/optional/creative/kanban-video-orchestrator/references/role-archetypes.md

@@ -0,0 +1,234 @@
+# 角色原型
+
+用于视频制作的角色原型库。**请从此列表中组建团队，而不是克隆固定的名册。**大多数视频需要 4-7 个配置。director 始终存在；其他角色则视 brief（需求简报）而定。
+
+按照惯例，每个角色的配置名称使用 `kebab-case`（例如 `creative-director`、`image-generator`）。同一角色的多个实例在需要侧重点不同时，会加上描述性后缀（例如 `renderer-ascii`、`renderer-3d`）。
+
+有关每个角色的工具集和技能映射，请参阅 [tool-matrix.md](tool-matrix.md)。
+
+## 始终存在
+
+### director
+
+愿景把控者。阅读 brief（需求简报）和品牌指南，将其分解为任务图，发表评论以引导创意方向，并批准最终剪辑。
+
+- **Toolsets：** kanban, terminal, file
+- **Skills：** 无需额外技能——kanban 编排指南（分解剧本、“只分解，不执行”的纪律）会自动注入到每个 kanban 工作节点的系统提示词中。如果 brief 非常开放且需要框架辅助，请添加 `creative-ideation`。
+- **Personality：** 与品牌声音绑定——参见 `assets/soul.md.tmpl`
+
+director 拥有与其他人相同的工具集，但它的 `SOUL.md` 规则**禁止**执行。“只分解，不执行”的纪律是由 personality 加上自动注入的 kanban 编排指南来执行的，而不是通过隐藏工具来实现的。
+
+## 前期制作角色
+
+根据 brief 的需求进行选择。
+
+### writer / screenwriter
+
+撰写剧本、对话、画外音文案和解说词。适用于任何包含标语以外的口头或书面文字的视频。
+
+- **Toolsets：** kanban, file
+- **Skills：** `humanizer`（进行后处理以消除 AI 痕迹）
+- **Outputs：** `script.md`, `narration.md`, `dialogue/scene-NN.md`
+
+### copywriter
+
+类似于 `writer`，但专门用于营销文案：标语、CTA（行动呼吁）、产品视频的画外音脚本。
+
+- **Toolsets：** kanban, file
+- **Skills：** `humanizer`
+- **Outputs：** `copy.md`
+
+### concept-artist / visual-designer
+
+开发视觉识别系统：情绪板、风格帧、调色板依据和排版选择。生成所有生成器都会遵循的 `visual-spec.md`。通常使用图像生成 API 或本地技能制作静态参考帧。
+
+- **Toolsets：** kanban, terminal, file
+- **Skills：** 任何特定于项目的设计技能 ——
+  `claude-design` (UI/web), `sketch` (快速模型变体),
+  `popular-web-designs` (匹配已知的 web 美学), `pixel-art` (复古),
+  `ascii-art` (终端/复古), `excalidraw` (手绘帧),
+  `design-md` (基于文本的设计文档)
+- **Outputs：** `visual-spec.md`, `taste/style-frames/*.png`
+
+### storyboarder
+
+将 brief 映射为带有时间安排的分镜头脚本。对于叙事电影和音乐视频至关重要。通常与图表工具搭配使用。
+
+- **Toolsets：** kanban, file
+- **Skills：** 一种图表技能 —— `excalidraw` (草图),
+  `architecture-diagram` (技术/系统), `concept-diagrams` (教育/
+  科学)
+- **Outputs：** `storyboard.md`，每个场景/镜头一行，以及可选的分镜头草图
+
+### cinematographer / dp
+
+设计视觉语言：构图、色彩、运动、转场。审查生成器的输出以确保视觉一致性。交接每个场景的 `VISUAL_SPEC.md`。
+
+- **Toolsets：** kanban, terminal, file, video, vision
+- **Skills：** 与项目匹配的视觉技能
+  (例如：`ascii-video` 用于 ASCII 作品，`manim-video` 用于解说视频，
+  `touchdesigner-mcp` 用于实时视觉等)
+- **Outputs：** `scenes/scene-NN/VISUAL_SPEC.md`，对渲染任务的审查评论
+- **Reviews via：** `video_analyze` (将完整片段发送给多模态 LLM 进行原生审查)，`vision_analyze` 用于抽查帧，ffprobe 摘要
+
+## 制作阶段角色
+
+### renderer (generic)
+
+为一个或多个场景制作视觉内容的工作节点。加载适合该场景风格的创意技能。多个 renderer 可以并行运行，每个通过其配置中的 `always_load` 或任务中的 `--skill` 绑定到不同的技能。
+
+- **Toolsets：** kanban, terminal, file
+- **Skills：** 一种创意技能（参见下文的专业化变体）
+- **Outputs：** `scenes/scene-NN/clip.mp4`
+
+### 专业化渲染器变体
+
+当场景需要截然不同的工具时，请创建专业化的 renderer 配置，而不是让一个配置超载工作。每个配置加载不同的创意技能。
+
+| Variant | Skill | 最适合 |
+|---------|-------|----------|
+| `renderer-ascii` | `ascii-video` | 终端美学、复古像素、音频反应网格、视频转 ASCII |
+| `renderer-manim` | `manim-video` | 数学、算法、3Blue1Brown 风格的解说视频、方程推导 |
+| `renderer-p5js` | `p5js` | 生成艺术、粒子、shaders、有机运动、web-canvas 内容 |
+| `renderer-comfyui` | `comfyui` | 使用本地 ComfyUI 工作流的 AI 生成静态图像 + 视频 (img-to-img, img-to-video 等) |
+| `renderer-touchdesigner` | `touchdesigner-mcp` | 实时、音频反应、装置艺术、VJ 风格内容 |
+| `renderer-3d` | `blender-mcp` *(可选)* | 3D 建模、动画、照片级真实环境、角色动画 |
+| `renderer-pixel` | `pixel-art` | 带有符合时代调色板的复古游戏美学 |
+| `renderer-comic` | `baoyu-comic` | 知识漫画风格的叙事场景 |
+| `renderer-meme` | `meme-generation` *(可选)* | 用于讽刺/社交内容的 Meme 风格静态图 |
+| `renderer-procedural` | (无 —— 直接使用带 PIL + ffmpeg 的 Python) | 当没有技能适用时的自定义程序化内容 |
+| `renderer-video` | (外部图生视频 API：Runway / Kling / Luma) | 在叙事电影中为静态图像制作动画 |
+| `renderer-motion-graphics` | (外部 —— Remotion CLI) | 动态图形、动态排版、UI 动画 |
+
+对于基于外部 API 的渲染器，配置中包含 API 客户端逻辑；不加载额外技能（kanban 指南会自动注入到每个 kanban 工作节点中），并附带 terminal 工具集和 API key。
+
+### image-generator
+
+专门用于 text-to-image（文生图）生成。通常生成静态图像，交由 `renderer-video` 制作成动画。
+
+- **Toolsets：** kanban, terminal, file
+- **Skills：** 可选 `comfyui` (驱动本地 ComfyUI 安装进行图像生成)
+- **External APIs（本地 ComfyUI 的替代方案）：** FAL, Replicate, OpenAI Images, Midjourney
+- **Outputs：** `scenes/scene-NN/stills/*.png`
+
+### image-to-video-generator
+
+通过 Runway/Kling/Luma API 或通过本地 ComfyUI 的图生视频工作流获取静态图像并将其制作成动画。在叙事电影流程中，几乎总是跟在 `image-generator` 之后。
+
+- **Toolsets：** kanban, terminal, file
+- **Skills：** 可选 `comfyui` (用于本地图生视频工作流，如 AnimateDiff 或 WAN)
+- **External APIs：** Runway, Kling, Luma, Pika
+- **Outputs：** `scenes/scene-NN/clip.mp4`
+
+### music-supervisor
+
+寻找、分析和准备音乐曲目。对于音乐视频，还会生成节拍/BPM 映射和关键时刻时间戳。当编辑器或渲染器需要音频能量的视觉参考时，使用 `songsee` 生成频谱图。
+
+- **Toolsets：** kanban, terminal, file
+- **Skills：** `songsee` (音频可视化)，加上以下其中之一：
+  - `songwriting-and-ai-music` —— 委托创作歌词 + Suno prompts 时
+  - `heartmula` —— 使用开源本地模型生成音乐时
+  - `spotify` —— 寻找现有曲目时
+- **Outputs：** `audio/track.mp3`, `audio/beats.json`, 可选 `audio/track-spectrogram.png`
+
+### voice-talent / narrator
+
+生成画外音音频。直接调用 TTS API；不需要 Hermes 技能（kanban 指南会自动注入到每个 kanban 工作节点中）。用户也可以提供预录制的 VO 来代替生成。
+
+- **Toolsets：** kanban, terminal, file
+- **Skills：** 无 —— kanban 指南会自动注入到每个 kanban 工作节点中
+- **External APIs：** ElevenLabs, OpenAI TTS 等
+- **Outputs：** `audio/voiceover/line-NN.mp3`, `audio/voiceover/timeline.mp3`
+
+### foley / sfx-designer
+
+音效和环境设计。通常是可选的，除非 brief 特别要求声音设计。
+
+- **Toolsets：** kanban, terminal, file
+- **Skills：** `songsee` 用于在针对特定曲目进行设计时的音频特征可视化
+- **Outputs：** `audio/sfx/*.mp3`
+
+## 后期制作角色
+
+### editor
+
+从片段中组装最终剪辑。使用 ffmpeg 进行拼接、淡入淡出和转场。在组装之前审查每个片段的节奏和质量。
+
+- **Toolsets：** kanban, terminal, file
+- **Skills：** 无 —— kanban 指南会自动注入到每个 kanban 工作节点中
+- **External tools：** ffmpeg, ffprobe
+- **Outputs：** `output/final.mp4`, `output/final-noaudio.mp4`
+
+### colorist
+
+调色。通常是可选的——如果渲染器已经产生了符合品牌基调的输出，而编辑器只是进行拼接，那么 colorist 就显得多余了。对于带有主要镜头的叙事电影，值得加入。
+
+- **Toolsets：** kanban, terminal, file
+- **Skills：** 无 —— kanban 指南会自动注入到每个 kanban 工作节点中
+- **Outputs：** `output/final-graded.mp4`
+
+### audio-mixer
+
+将画外音 + 音乐 + SFX（音效）混合成最终的音轨。设置音量级别，在 VO（画外音）播放时压低音乐，并标准化响度（LUFS）。
+
+- **Toolsets：** kanban, terminal, file
+- **Skills：** 无 —— kanban 指南会自动注入到每个 kanban 工作节点中
+- **External tools：** 带有 `loudnorm` 过滤器的 ffmpeg，可选的 `sox`
+- **Outputs：** `audio/final-mix.mp3`
+
+### captioner
+
+将字幕刻录（硬编码）到视频中，生成 SRT，并处理无障碍访问。还可以通过 Whisper 从音频生成字幕。
+
+- **Toolsets：** kanban, terminal, file
+- **Skills：** 无 —— kanban 指南会自动注入到每个 kanban 工作节点中
+- **External tools：** Whisper (CLI 或 API)，ffmpeg 字幕过滤器
+- **Outputs：** `output/captions.srt`, `output/final-captioned.mp4`
+
+### masterer
+
+最终编码 + 格式变体。为每个平台目标生成交付物（例如：正方形用于 IG，垂直用于 TikTok，全高清用于 YouTube 等）。
+
+- **Toolsets：** kanban, terminal, file
+- **Skills：** 无 —— kanban 指南会自动注入到每个 kanban 工作节点中
+- **Outputs：** `output/final-1080.mp4`, `output/final-9x16.mp4`, 等
+
+## QA（质量保证）角色
+
+### reviewer
+
+中立的质检关卡。阅读 brief，观看剪辑，专门针对有偏差的地方（节奏、同步、品牌一致性、技术质量）进行评论。不同于 cinematographer（在制作过程中审查视觉效果）和 editor（审查拼装）。
+
+- **Toolsets：** kanban, terminal, file, video, vision
+- **Skills：** 无 —— kanban 指南会自动注入到每个 kanban 工作节点中
+- **Review tools：** `video_analyze` (通过多模态 LLM 进行原生片段审查)，`vision_analyze` (帧/缩略图审查)，ffprobe
+- **Outputs：** `review-notes.md`，对任务的评论
+
+### brand-cop
+
+专门针对品牌合规性进行审查——颜色、排版、语气。适用于品牌指南非常详细且通用的 reviewer 可能会漏看违规项的情况。
+
+- **Toolsets：** kanban, file
+- **Skills：** 无 —— kanban 指南会自动注入到每个 kanban 工作节点中
+- **Outputs：** 评论 + `brand-review.md`
+
+## 组建团队——启发式规则
+
+- **始终需要：** director + 至少一个 renderer + editor。
+- **添加 writer** 如果有脚本的对话 / 旁白 / 屏幕文本超过了简短的标语。
+- **添加 storyboarder** 如果 brief 包含超过 5 个不同的节拍，并且 director 尚未列出节拍清单。
+- **添加 cinematographer** 如果多个 renderer 实例需要一致的视觉语言。（对于单工具视频，renderer 自己的技能规范就足够了。）
+- **添加 image-generator + image-to-video-generator 组合** 用于带有逼真视觉效果的叙事电影。
+- **添加 music-supervisor** 当提供了音乐并且节奏很重要时（总是用于音乐视频；有时用于解说视频）。
+- **添加 voice-talent** 用于任何画外音 / 叙事对话。
+- **添加 audio-mixer** 当有 2 个或更多音频源时（VO + 音乐，音乐 + SFX）。
+- **添加 captioner** 用于无障碍优先的项目（解说视频、教程、任何默认静音播放的平台）。
+- **添加 reviewer** 用于高风险项目。在快速实验迭代中可跳过。
+- **添加 masterer** 当需要多平台的交付物时。
+
+## 反模式
+
+- **一个 renderer 做所有事情。** 如果场景使用截然不同的工具（ASCII + 3D + 动态图形），请使用专业化的 renderer 变体。renderer 一次只加载一种创意技能；在单个 renderer 中混合风格会导致任务动荡。
+- **每个场景一个单独的配置。** 不。配置是按角色划分的，而不是按场景划分的。八个场景使用一个或两个 renderer 配置，而不是八个。
+- **一个包揽一切的“通用”配置。** 比没有专业化更糟糕。如果每个任务都适合每个配置，kanban 路由就会崩溃。
+- **对于重要的交付物没有 reviewer。** 虽然节省了一个小时的流程时间，但会交付带有瑕疵的作品。