kinema-setup · 前置配置向导

把「拿到这个仓库」到「能出片」之间的所有配置一次问清、配好、验通。 六道节点，逐节点确认后再往下；每道节点都以一条可复验的命令收尾。

产出：一张就绪度总表（每项 ✓/✗ + 处置）＋ 下一步该调哪个 skill。

原生生图能力的判断、询问和会话级路由声明遵循 原生生图能力握手；不要把 ARK_API_KEY 是否存在当作唯一判断。

---

铁律（Agent 纪律，先读）

1. 绝不跑交互式 setup（不带 --check）——它 input() 等 stdin，在 agent 会话里会把整个 命令挂死。自检一律用 python3 -m kinema setup --check 与 doctor。
2. 绝不擅自装系统包、绝不 sudo。探测缺什么 → 先认平台（uname/os-release）→ 给出 该平台的确切命令 → 让用户自己在会话里用 ! <命令> 跑（输出会直接回到对话），或明确点头 后由你执行。装 pip 包属可逆操作，征得同意后可直接跑；brew/apt/dnf/pacman/winget 这类 改系统的一律请用户执行。
3. 服务端一概不装、不启、不改：MySQL 与对象存储都由用户自己准备（自建/公司的/云托管）， 本 skill 只收集连接信息并验证连通性——不跑 apt install mysql-server、不 docker run mysql、不改 my.cnf、不建库建用户改权限、不代开通 OSS/代建桶。要建库就把 SQL 交给用户执行。 唯一会装的是客户端驱动（PyMySQL / oss2 等 pip 包）。
4. 密钥只报状态，不回显值。永远只说「env 已设 / secrets.yaml 已设 / 未设」；不 cat secrets.yaml、不把 key 写进对话、不写进任何 md/log。
5. 优先用环境变量固化，别动仓库里的配置默认值。config/storage.yaml 提交的是 backend: local（零依赖开箱即用），把它改成 mysql 会产生 git 改动并影响别的机器； 本机启用走 KINEMA_STORAGE_BACKEND=mysql。用户明确说「改文件」才改文件。
6. 一次只推进一道节点，每道跑完复验命令并把结果原样贴给用户；失败就地处置，不往下滚。
7. 不做内容生产。配完就把用户交给 kinema（或对应 kn-* 风格 skill）。

---

配置面全景（决策 → 落在哪 → 怎么验）

决策	落点	复验
系统依赖	系统包管理器（ffmpeg/ffprobe 是唯一硬依赖）	python3 -m kinema doctor
引擎与可选依赖	engine/ 下 pip install -e ".[…]"	python3 -m kinema --version
数据存储 local/mysql	config/storage.yaml 顶层 backend 或 env KINEMA_STORAGE_BACKEND（数据库服务端用户自备，这里只填连接）	db status
媒体存放 local/oss	config/storage.yaml 的 media 段（桶用户自己开通，这里只填连接）	oss status
云能力密钥	config/secrets.yaml（setup 自动生成，不用手建）或 config secret 写本机密钥文件；优先级 env > secrets.local.json > secrets.yaml	setup --check
音频库（BGM/音效）	music/（媒体不入 git）	sfx list · doctor 的「音乐库: N 首」
字体	无需配置——字幕/水印/封面字体全部工程内置（engine/kinema/assets/fonts/）	—

---

节点① 系统依赖体检

先跑探测，一次问全：

python3 -V                       # 需 ≥ 3.10
which ffmpeg ffprobe             # 唯一硬依赖，两个都要有
python3 -c "import sys, importlib.util as u; print(sys.executable,
  '| yaml', bool(u.find_spec('yaml')), '| kinema', bool(u.find_spec('kinema')))"

⚠️ 多解释器陷阱（最容易漏、后果最隐蔽）：机器上常有好几个 python（系统自带 / homebrew 3.12 / 3.13 / venv），extras 装在哪一个里就只有那一个能用。必须查「实际跑引擎的那个 解释器」有没有 yaml——缺 PyYAML 时引擎会显式告警并回退内置默认配置， 同一 profile 可能换 provider、丢字幕样式，真跑非 mock 时才看得出差异。 （密钥不受影响：config_overlay.read_yaml_secrets_flat 用标准库读 secrets.yaml， 装没装 PyYAML 都读得到。） 真实案例：本仓库开发机 python3→3.13 无 PyYAML、python3.12 有， 同一条命令换个解释器结论完全相反。处置：给那个解释器补 pip install -e ".[yaml]"， 或统一固定用装好的那个（写进说明/别名）。

①-a 先认平台，再给命令

不要凭印象猜平台——同一条 apt 在 Fedora 上白费，brew 在 Linux 上路径也不同。先探：

uname -s -m                                  # Darwin arm64 / Linux x86_64 …
cat /etc/os-release 2>/dev/null | head -3    # Linux 发行版与版本（ID/VERSION_ID）
echo $SHELL                                  # 后面写环境变量要按 shell 给语法

Windows（PowerShell）：$PSVersionTable.PSVersion、winget -v、where.exe python ffmpeg。 WSL 里一律按其发行版（多为 Ubuntu）处理，不要给 Windows 的命令。

①-b ffmpeg / ffprobe（唯一硬依赖）

平台	安装命令	备注
macOS	brew install ffmpeg	没有 brew：先装 https://brew.sh；Apple Silicon 装在 /opt/homebrew/bin、Intel 在 /usr/local/bin，装完确认在 PATH
Debian / Ubuntu / WSL	sudo apt update && sudo apt install -y ffmpeg	—
Fedora	sudo dnf install -y ffmpeg	需先启 RPM Fusion（sudo dnf install -y https://mirrors.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm）
RHEL / Rocky / CentOS	sudo dnf install -y ffmpeg	同样需 RPM Fusion + EPEL；企业机常无权限 → 走下面「无 root」
Arch / Manjaro	sudo pacman -S ffmpeg	—
openSUSE	sudo zypper install ffmpeg	可能需加 Packman 源
Alpine	sudo apk add ffmpeg	—
Windows	winget install Gyan.FFmpeg ｜ scoop install ffmpeg ｜ choco install ffmpeg	装完重开终端（winget 不刷新当前会话 PATH；choco 可 refreshenv）
无 root / 不想动系统	静态构建解包到 ~/bin 并加 PATH：Linux https://johnvansickle.com/ffmpeg/ ｜ macOS https://evermeet.cx/ffmpeg/ ｜ 或 conda install -c conda-forge ffmpeg	静态包自带 ffmpeg + ffprobe 两个可执行，两个都要放进 PATH

复验（两个都必须有输出，只有 ffmpeg 没 ffprobe 也不行）：

ffmpeg -version | head -1 && ffprobe -version | head -1

①-c python ≥ 3.10

平台	安装/升级	备注
macOS	brew install python@3.12	系统自带 /usr/bin/python3 版本旧且不好装包，别用它
Debian / Ubuntu	sudo apt install -y python3 python3-pip python3-venv	20.04 等老 LTS 只有 3.8 → 上 deadsnakes PPA 装 python3.12
Fedora / RHEL	sudo dnf install -y python3 python3-pip	—
Arch	sudo pacman -S python python-pip	—
Windows	winget install Python.Python.3.12	命令是 python 不是 python3；勾/确认「Add to PATH」
跨平台版本管理	pyenv install 3.12 ｜ uv python install 3.12 ｜ conda create -n av python=3.12	多版本共存首选，避免污染系统 python

①-d 引擎与可选依赖

装在哪个解释器里，就只有那个解释器能用——建议直接用「要跑引擎的那个 python」调 pip：

cd engine
python3 -m pip install -e ".[cloud,yaml]"     # 用 python3 -m pip，避免 pip 指向别的解释器
# Windows: python -m pip install -e ".[cloud,yaml]"

想彻底隔离（推荐给洁癖/多项目机器）：

python3 -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
python -m pip install -e "engine[cloud,yaml]"        # 之后所有 kinema 命令都在这个 venv 里跑

extras 按需装，别一上来全装：cloud（真实 provider 走 HTTP）· yaml（读 config/*.yaml， 强烈建议装，见上方陷阱）· mysql（PyMySQL 驱动，节点②要）· oss-aliyun/oss-tencent/ oss-volc/oss（节点③要）· asr（本地语音转写：verify 的 native 人声文字核对与字幕 逐句划界，CPU 推理零 API 成本，权重首跑自动下载）· control（深度捕捉的感知栈；装完 再跑一行 pip install --no-deps rtmlib，再 control fetch 显式拉约 115MB 权重—— 不自动下载，就绪只看 doctor 的「可选依赖 control」一行，setup --check 不包含它）。vision/vision-clip 是登记位、 一期不启用，装了也不会被调用——别装（后者是 GB 级 torch）。

收尾复验：

python3 -m kinema doctor

doctor 会一次报出：ffmpeg 版本 · 配置源 · 存储后端 · 默认 profile · providers ready/planned · 音乐库首数 · 孤儿 ffmpeg 进程。把输出贴给用户，逐行解释哪项还没配。

---

节点② 数据存储：本地 JSON vs MySQL

先问，别替用户默认：

你的情况	选
单机单人、就想快点出片	local（默认，零依赖：project.json 即数据库）
多台机器/换机继续、要跨项目 SQL 直查看板、要正式落库	mysql

• 选 local：什么都不用做（仓库默认就是）。跳到节点③。
• 选 mysql：只配置连接，绝不代装数据库。

🚫 本节点不装、不启、不改任何 MySQL 服务端——不跑 brew install mysql / apt install mysql-server / docker run mysql，不改 my.cnf，不建用户、不改权限、不动别的库。 数据库该由用户自己准备好（自建、公司的、云 RDS 都行），这里只要四样东西： 地址 host · 端口 port · 账号 user · 密码（外加库名，默认 kinema）。 唯一会装的是 PyMySQL —— Python 客户端驱动（可逆 pip 包，不是数据库本体）。

问用户拿到四要素后：

# 1) 客户端驱动（唯一的安装动作）
python3 -m pip install -e "engine[mysql]"

# 2) 连接参数：编辑 config/storage.yaml 的 mysql 段
#      host / port / user / database / charset / table_prefix
#    ⚠ 密码不写这里 —— 放 config/secrets.yaml 的 KINEMA_MYSQL_PASSWORD
#      （env 同名变量优先级更高；你不要代读、代打印密码）

# 3) 本机启用（推荐 env：不产生 git 改动、不影响别人的机器）
export KINEMA_STORAGE_BACKEND=mysql          # bash / zsh 当次会话
set -Ux KINEMA_STORAGE_BACKEND mysql         # fish 通用变量（永久固化）
$env:KINEMA_STORAGE_BACKEND = "mysql"        # PowerShell 当次会话
[Environment]::SetEnvironmentVariable("KINEMA_STORAGE_BACKEND","mysql","User")  # PowerShell 永久

# 4) 通、再建表、再登记
python3 -m kinema db status                   # 先过连通性这关，报错就地看错在哪
python3 -m kinema db init                     # 在**用户给的那个库里**建 8 张 kn_* 表
python3 -m kinema db sync                     # 本地已有项目 JSON → 库（换机恢复反向用 db pull）

库不存在时不要代跑 DDL，把语句给用户，让他用自己的客户端/DBA 执行（建库通常需要更高权限）：

CREATE DATABASE IF NOT EXISTS kinema DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;
-- 只给这个库的权限即可，不需要 root：
-- GRANT ALL PRIVILEGES ON kinema.* TO '你的账号'@'%';

要交给 DBA 审的完整建表脚本：python3 -m kinema db schema --out docs/sql/kinema.sql（生成物，别手改）。

⚠️ 三条经验：① mysql 模式下本地 JSON 仍是渲染工作副本，媒体文件永远在磁盘，库里只存路径与元数据； ② db init 只在指定库里建 av_ 前缀的表，不碰同库里别的表——但仍建议给它一个专用库； ③ 连不上就先 db status 定位（多是端口/账号/远程访问未放开），临时回退 KINEMA_STORAGE_BACKEND=local 立刻能继续干活，数据不会丢。

---

节点③ 媒体存放：本地 vs 对象存储

默认 local，别劝用户上云。只有两种情况真需要 OSS：

1. 参考视频 V2V（gen-video --previz）——视频参考必须是公网 URL，本地路径与 data-url 一律被拒；
2. 多机/协作要共享媒体，或成片要给外部直链。

同节点②的纪律：桶由用户自己在云控制台开通/创建，你只填连接信息（不代开服务、不代建桶、 不代改跨域/公读策略——那都是要计费和授权的动作）。

桶名与区域写进 config/secrets.yaml，不写 storage.yaml——后者随仓库分发， 填进去的桶名会跟着提交：

# config/secrets.yaml（gitignore 内）
KINEMA_OSS_BUCKET: "你的桶"
KINEMA_OSS_REGION: "cn-hangzhou"      # 腾讯 ap-guangzhou / 火山 cn-beijing
KINEMA_OSS_ACCESS_KEY: "…"
KINEMA_OSS_SECRET_KEY: "…"

config/storage.yaml 的 media 段只留不涉密的那几项：

media:
  backend: oss                  # local | oss
  provider: aliyun              # aliyun(OSS) | tencent(COS) | volcengine(TOS) | mock(离线测试)
  prefix: av                    # 对象 Key 前缀（Key = 前缀/工作区相对路径）
  public_base: ""               # 可选，自定义域名/CDN

依赖按家装：pip install -e "engine[oss-aliyun]"（或 oss-tencent / oss-volc / oss 全装）。 桶名、区域与 AK/SK 一并进 secrets（env > secrets.local.json > secrets.yaml）。

python3 -m kinema oss status                      # 媒体后端与连通性自检
python3 -m kinema oss sync --project <项目id>      # 确认后上传并把路径改写成 URL
python3 -m kinema oss pull                        # 换机：按 URL 拉回本地继续渲染

⚠️ 第三方参考片（project/<pid>/study/）绝不上云——那是版权红线，护栏靠「契约里路径恒为 工作区相对」这一条，别手工把它改成绝对路径。

---

节点④ 云能力密钥（按需，取最小集）

先讲清三档，让用户自己选起点：

档	需要的 key	能干什么
零成本彩排	不需要任何 key	run --mock 端到端跑通全链路（占位素材，验证环境）
正式出片（第三方图像链）	ARK_API_KEY + ARK_TTS_API_KEY	图（Seedream）+ 视频（Seedance）+ 配音（火山语音）——两把 key 就够
正式出片（Agent 原生生图）	ARK_TTS_API_KEY；若用 Seedance 再加 ARK_API_KEY	图片由当前 Agent 生成，不需要生图 key；配音和视频仍按实际节点配置
加配乐	ELEVENLABS_API_KEY	AI 生成 BGM；不填会自动降级本地免费曲库（节点⑤），多数场景不必配

备选 provider（都是「填 key 即用」，不填不影响）：GEMINI_API_KEY（Nano Banana 图 / Veo 视频）· DASHSCOPE_API_KEY（通义万相）· MINIMAX_API_KEY+MINIMAX_GROUP_ID。

如果当前会话实际暴露了原生图像生成工具（例如 Codex ImageGen），按 原生生图能力握手自动或询问后声明 KINEMA_AGENT_IMAGEGEN=1。此时生图不需要 ARK_API_KEY；ARK_API_KEY 只在后续使用 Seedance 等视频 API 时需要。用户或机器已显式激活的第三方 image provider 优先于该声明， setup --check --json 的 image_route 是最终判据。

配置方式：

不要让用户手抄这个文件，也不要自己 cp——setup（含 --check）在缺文件时 已经从 secrets.example.yaml 自动生成一份全空的 config/secrets.yaml， 每把 key 的申请地址就写在对应条目上方的注释里（Studio 模型页各服务商抽屉里也有 「打开控制台」直达）。请用户自己编辑填值，你不要代读、代打印文件内容。

不想编辑文件的用户走命令写本机密钥文件（同样不用手建文件）：

cd engine && python3 -m kinema config secret ARK_API_KEY <值>

三层优先级 env > secrets.local.json > secrets.yaml，临时试可以 export ARK_API_KEY=…。两份密钥文件都已在 .gitignore，绝不提交。

复验（只输出「已设/未设」，不泄漏值）：

python3 -m kinema setup --check

---

节点⑤ 音频库：免费商用 BGM + 音效

问一句「要不要拉免费商用音频库？」——默认建议拉，理由讲清：

• 不配 ELEVENLABS_API_KEY 时，BGM 走本地曲库；库为空会退化成合成正弦氛围床（就是那种 嗡嗡声，doctor 会警告）。用户听到「BGM 怎么是嗡嗡声」十有八九是这一条。
• 拉下来是 103 首 BGM（四情绪目录）+ 18 枚音效，全部 CC0 / 公共领域：免费商用、免署名、 可改编、可随成片分发。媒体不入 git，换机重跑即重建。

python music/download.py            # 一键两套；单文件失败不致命，重跑会跳过已存在的

复验：

python3 -m kinema sfx list        # 18 枚应全为「✓ 外置」
python3 -m kinema doctor          # 应出现「音乐库: 103 首」

要再加曲子/音效：脚本收尾会打印 Pixabay 手动下载指路（授权达标但站方禁脚本抓取）。 收音频进库的四条硬标准（缺一条别进库）：① 免费商用 ② 免署名 ③ 允许作背景音嵌入并 随成片分发 ④ 不限平台。原因是引擎按情绪目录确定性选曲——库里混进一首要署名的， 就会随机被某一集选中，那一集便默默背上署名义务。授权登记见 music/ATTRIBUTION.md。

---

节点⑥ 端到端验收 + 起大屏

python3 -m kinema setup --check     # 非交互验收：有未就绪项会非零退出并列出来
python3 -m kinema doctor            # 完整体检

零成本 mock 彩排（这是"环境真的通了"的唯一凭据——生图/配音/字幕/合成全跑一遍）：

python3 -m kinema project new --title "环境自检" --id setup_demo
python3 -m kinema chapter new setup_demo --title "链路自检"
# 编辑 project/setup_demo/chapters/ch01.json，填两镜最简 shots（narration + image_prompt 即可）
python3 -m kinema run --chapter setup_demo/ch01 --mock

跑通后起大屏（单例纪律：本工作区已在跑就复用并把 URL 打给用户，绝不新起进程； 换端口/重启用 --restart、停用 --stop、查实例用 --status）：

python3 -m kinema studio --port 8787      # → http://127.0.0.1:8787

如果后续节点需要用户点选、上传或审阅，不要只把上面的命令转给用户；先按 Studio 交互交接协议 自动查状态、启动并给出具体入口。

最后给用户一张总表，例如：

就绪度总表
  ✓ python3 3.13 / ffmpeg 7.1
  ✓ 引擎 pip -e 已装（extras: cloud, yaml）
  ✓ 数据存储 local（JSON 即数据库）
  ✓ 媒体存放 local
  ✓ 密钥 ARK_API_KEY 已设 · ARK_TTS_API_KEY 已设 · ELEVENLABS 未设（走本地曲库，无需配）
  ✓ 音频库 103 首 BGM + 18 枚音效（CC0 免署名）
  ✓ mock 全链路跑通 setup_demo/ch01 · 大屏 http://127.0.0.1:8787
下一步：说「做一条 XX 主题的视频」→ 走 /kinema（未点画风会按题材自动定档），
        或点名风格 /kn-anime、/kn-explainer…；要做多集系列先走 /kinema-project。

自检工程 setup_demo 可留着当回归样本，也可 python3 -m kinema project rm setup_demo 收进回收站。

---

故障速查（症状 → 根因 → 处置）

症状	根因	处置
No module named kinema	不在 engine/ 下跑，或没 pip install -e	cd engine && pip install -e ".[cloud,yaml]"
⚠ 找到配置 config/models.yaml 但缺 PyYAML，已回退内置默认配置	跑引擎的那个解释器没装 yaml extra——静默用内置默认，provider/字幕样式可能与文件不一致	给该解释器 pip install -e ".[yaml]"
密钥填在 secrets.yaml 里，setup --check 却报「未设」	不是 PyYAML 的锅（密钥走标准库读，与 extras 无关）：多半是值没加引号/写在注释行/写错变量名，或另有一份 secrets.local.json 同名键把它压住了（本机那份优先级更高）	config secret <KEY> <值> 写到高优先级那层；或临时 export ARK_API_KEY=… 验证
单测本地报 ConfigError: 缺少密钥 ARK_TTS_API_KEY	同一个根因——换成装了 PyYAML 的解释器即全绿	python3.12 -m unittest discover -s tests（或补 extras）
BGM 是正弦嗡嗡声	音乐库为空且没配 ElevenLabs	python music/download.py
合成/抽帧报 ffmpeg 相关错	ffmpeg/ffprobe 不在 PATH	见节点① 安装表，装完重开终端
MySQL 连不上、命令直接报错	密码/端口/库不对，或没装 PyMySQL	db status 看具体错；临时 KINEMA_STORAGE_BACKEND=local 先干活
明明说了用 local，却连上了 MySQL	环境里固化了 KINEMA_STORAGE_BACKEND=mysql（fish 通用变量常见）	命令前显式加 KINEMA_STORAGE_BACKEND=local，或 set -e KINEMA_STORAGE_BACKEND
Studio 打不开 / 端口被占 / 一堆残留进程	重复启动	studio --status 查 → --restart 换端口重起 → --stop 停；清残留 pkill -f 'kinema studio'
改了 Studio 的 Python 层没生效	scanner/actions/server 是进程启动时载入内存	studio --restart（前端静态资源每次请求读盘，总是新的）
CPU 一直高、风扇狂转	孤儿 ffmpeg（父进程被杀后无人认领）	doctor 会列 pid → kill -9 <pid>，或起 studio 自动收割
视频 V2V 报「参考视频必须公网 URL」	媒体后端还是 local	见节点③ 配 OSS，或先不用 --previz
Windows 上 python3 找不到	Windows 用 python	用 python -m kinema …；ffmpeg 走 winget/scoop 并确认 PATH

---

边界

• 本 skill 只管配置与验收，不写文案、不拆分镜、不生图。
• 配完的下一步：kinema（通用直达，未点画风按题材定档）· kn-*（点名画风）· kinema-project（多集系列/强规划）。
• 花钱的操作一概不在本 skill 里触发（生图/生视频/配音/音色复刻/AI 音效）—— 验收只用 --mock 与本地零成本命令。