Ubuntu 部署 Drama Skills 详细教程
从零开始在 Ubuntu 服务器 / 桌面环境中安装、配置并运行 Drama Skills AI 短剧创作工作流
Ubuntu 20.04 / 22.04 / 24.04Python 3.9+10 个独立技能
📋 教程目录
- 环境准备与系统检查
- 安装 Python 与依赖工具
- 安装 Git 并克隆仓库
- 安装 Drama Skills 技能
- 验证安装
- 安装并配置 AI 运行环境
- 创建第一个短剧项目
- 启动本地创作台 Dashboard
- 配置生产 Adapter（可选）
- 常见问题排查
- 设置开机自启（进阶）
- 部署检查清单
1环境准备与系统检查
1.1 确认 Ubuntu 版本
首先确认你的系统版本。Drama Skills 支持 Ubuntu 20.04 及以上版本。
$ lsb_release -a # 示例输出： # No LSB modules are available. # Distributor ID: Ubuntu # Description: Ubuntu 22.04.4 LTS # Release: 22.04 # Codename: jammy1.2 更新系统包
$ sudo apt update && sudo apt upgrade -y1.3 检查已安装的基础工具
$ python3 --version # 需要 3.9 或更高 $ git --version # 用于克隆仓库 $ curl --version # 用于下载工具 $ node --version 2>/dev/null || echo "Node.js 未安装" # Dashboard 校验需要提示：如果没有安装curl或git，执行sudo apt install -y curl git
2安装 Python 与依赖工具
2.1 安装 Python 3
Ubuntu 20.04 自带 Python 3.8，需要升级；Ubuntu 22.04 / 24.04 自带 3.10 / 3.12，通常满足要求。推荐安装最新的 Python 3：
Ubuntu 22.04 / 24.04（自带满足要求）
$ sudo apt install -y python3 python3-pip python3-venv python3-dev # 确认版本 $ python3 --version # Python 3.10.12 或更高Ubuntu 20.04（需要从 PPA 安装更高版本）
$ sudo apt install -y software-properties-common $ sudo add-apt-repository -y ppa:deadsnakes/ppa $ sudo apt update $ sudo apt install -y python3.11 python3.11-venv python3.11-dev python3-pip # 设置 python3 指向新版本（可选） $ sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 1 $ python3 --version # Python 3.11.x2.2 安装 Node.js（Dashboard 校验需要）
CI 流程会使用 Node.js 20 来校验 Dashboard 脚本语法，建议安装：
$ curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - $ sudo apt install -y nodejs $ node --version # v20.x.x2.3 安装其他工具
$ sudo apt install -y build-essential jqbuild-essential：编译部分 Python 包可能需要jq：命令行处理 JSON 文件（查看项目状态时有用）
3安装 Git 并克隆仓库
3.1 安装 Git
$ sudo apt install -y git $ git --version3.2 选择安装目录
推荐放在用户主目录下的专用文件夹：
$ mkdir -p ~/drama-workspace $ cd ~/drama-workspace3.3 克隆 Drama Skills 仓库
$ cd ~/drama-workspace $ git clone https://github.com/worldwonderer/drama-skills.git $ cd drama-skills # 查看仓库结构 $ ls -la3.4 确认仓库完整性
$ git log --oneline -5 # 确认能看到最近的 commit 记录 $ ls skills/ # 应看到 10 个技能目录： # short-drama short-drama-assets short-drama-develop short-drama-image-prompts # short-drama-novel-analyze short-drama-produce short-drama-review # short-drama-storyboard short-drama-video-prompts short-drama-write仓库目录结构概览：
drama-skills/
├── skills/ # 10 个技能目录（核心）
│ ├── short-drama/ # 入口路由 + Dashboard
│ ├── short-drama-novel-analyze/
│ ├── short-drama-develop/
│ ├── short-drama-write/
│ ├── short-drama-assets/
│ ├── short-drama-image-prompts/
│ ├── short-drama-storyboard/
│ ├── short-drama-video-prompts/
│ ├── short-drama-produce/
│ └── short-drama-review/
├── examples/ # 示例项目
│ ├── golden-project/ # 八集完整样例《善意不结账》
│ ├── excerpt-chain/ # 单集摘录链条
│ └── creator-first/
├── docs/ # 文档
├── tests/ # 测试
├── .github/workflows/ # CI 配置
└── README.md
4安装 Drama Skills 技能
Drama Skills 的安装方式取决于你使用的 AI 运行环境。下面提供两种方式。
4.1 方式一：通过 AI 智能体一键安装（推荐）
如果你已经在使用 Claude Code 或 Codex，直接在智能体对话中输入：
安装这些技能 https://github.com/worldwonderer/drama-skills智能体会自动完成仓库克隆和技能链接，无需手动操作。
4.2 方式二：手动链接安装（适合自定义环境）
4.2.1 确定技能目录路径
# 记录仓库路径 $ cd ~/drama-workspace/drama-skills $ DRAMA_SKILLS_DIR="$PWD" $ echo "技能目录: $DRAMA_SKILLS_DIR"4.2.2 Claude Code 用户
# 创建技能目录（如果不存在） $ mkdir -p "$HOME/.claude/skills" # 链接全部 10 个技能 $ cd ~/drama-workspace/drama-skills $ for skill in skills/*; do ln -s "$PWD/$skill" "$HOME/.claude/skills/$(basename "$skill")" done # 验证链接 $ ls -la "$HOME/.claude/skills/"4.2.3 Codex 用户
# 创建技能目录 $ mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills" # 链接全部技能 $ cd ~/drama-workspace/drama-skills $ for skill in skills/*; do ln -s "$PWD/$skill" "${CODEX_HOME:-$HOME/.codex}/skills/$(basename "$skill")" done # 验证 $ ls -la "${CODEX_HOME:-$HOME/.codex}/skills/"4.2.4 按需安装（只链接需要的技能）
每个技能都是独立安装单元。如果只需要部分能力，可以只链接对应目录：
# 例如：只安装入口路由 + 剧本写作 + 资产设定 $ mkdir -p "$HOME/.claude/skills" $ cd ~/drama-workspace/drama-skills $ ln -s "$PWD/skills/short-drama" "$HOME/.claude/skills/short-drama" $ ln -s "$PWD/skills/short-drama-write" "$HOME/.claude/skills/short-drama-write" $ ln -s "$PWD/skills/short-drama-assets" "$HOME/.claude/skills/short-drama-assets"关于路径：符号链接使用绝对路径（$PWD已展开为绝对路径），所以即使后续移动终端工作目录，链接依然有效。但不要移动drama-skills仓库目录本身，否则链接会失效。
4.3 方式三：直接使用（无需链接，适合临时使用）
如果只是想试用，可以直接在仓库目录中运行脚本，不需要创建符号链接：
$ cd ~/drama-workspace/drama-skills $ python3 skills/short-drama/scripts/project_tool.py init ./my-test-drama --title "测试短剧"5验证安装
5.1 运行入口技能自检
$ cd ~/drama-workspace/drama-skills $ python3 skills/short-drama/scripts/selftest.py如果输出中没有报错，说明入口技能的脚本可以正常运行。
5.2 测试项目初始化
$ cd ~/drama-workspace $ python3 ~/drama-workspace/drama-skills/skills/short-drama/scripts/project_tool.py init ./test-drama --title "测试短剧" # 查看生成的项目结构 $ ls -la test-drama/ $ cat test-drama/short-drama.json5.3 运行生产技能离线自检
$ python3 skills/short-drama-produce/scripts/selftest.py $ python3 skills/short-drama-produce/scripts/provider_adapters.py --selftest说明：生产技能的自检是离线的，不会发起任何远端请求，也不会产生费用。它只验证确认闸门、fixture adapter 和供应商 payload 编译。
5.4 运行完整测试套件
$ cd ~/drama-workspace/drama-skills $ python3 -B -m unittest discover -s tests -v5.5 运行 lint 和类型检查（可选）
# 安装工具 $ pip3 install ruff==0.15.11 mypy==2.3.0 --break-system-packages # 运行 ruff 检查 $ ruff check . # 运行 mypy 类型检查 $ mypy skills/short-drama/scripts/project_tool.py \ skills/short-drama/scripts/dashboard_server.py \ --ignore-missing-imports # 校验 Dashboard 脚本语法 $ node --check skills/short-drama/assets/dashboard/app.js5.6 校验 Golden Sample 示例项目
$ cd ~/drama-workspace/drama-skills # 资产校验 $ python3 skills/short-drama-assets/scripts/asset_check.py \ --characters examples/golden-project/设定集/characters.jsonl \ --looks examples/golden-project/设定集/looks.jsonl # 图片提示词校验 $ python3 skills/short-drama-image-prompts/scripts/image_prompt_check.py \ examples/golden-project/剧集/EP001/assets/image-prompt-specs.jsonl # 分镜校验 $ python3 skills/short-drama-storyboard/scripts/storyboard_check.py \ examples/golden-project/剧集/EP001/storyboard/coverage.json \ --shots examples/golden-project/剧集/EP001/storyboard/shots.jsonl \ --keyframes examples/golden-project/剧集/EP001/storyboard/keyframes.jsonl \ --project examples/golden-project/short-drama.json # 审查校验 $ python3 skills/short-drama-review/scripts/review_check.py \ --findings examples/golden-project/审查/findings.jsonl \ --verdict examples/golden-project/审查/verdict.json验证通过标志：以上所有命令都不报错退出，说明安装完整，可以开始使用了。
6安装并配置 AI 运行环境
Drama Skills 本身只是技能文件和 Python 脚本，需要一个支持 Agent Skill 规范的 AI 运行环境来驱动。以下是两种常用方案：
6.1 方案 A：Claude Code（推荐）
安装 Node.js 和 npm
$ sudo apt install -y nodejs npm安装 Claude Code CLI
$ npm install -g @anthropic-ai/claude-code配置 API Key
$ export ANTHROPIC_API_KEY="sk-ant-xxxxx你的密钥xxxxx" # 写入 shell 配置文件持久化 $ echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxx你的密钥xxxxx"' >> ~/.bashrc $ source ~/.bashrc验证
$ claude --version6.2 方案 B：Codex CLI
安装
$ npm install -g @openai/codex配置
$ export OPENAI_API_KEY="sk-xxxxx你的密钥xxxxx" $ echo 'export OPENAI_API_KEY="sk-xxxxx你的密钥xxxxx"' >> ~/.bashrc $ source ~/.bashrc验证
$ codex --version安全提醒：API Key 是敏感凭据。不要把含密钥的命令写入项目文件或 Git 仓库。Drama Skills 的设计原则就是"凭据只在运行环境，不进入项目文件"。
6.3 调用方式
| 环境 | 调用前缀 | 示例 |
|---|---|---|
| Claude Code | /short-drama | /short-drama 初始化一个短剧项目 |
| Codex | $short-drama | $short-drama 初始化一个短剧项目 |
| 通用 | 自然语言 | 直接描述你想做什么 |
7创建第一个短剧项目
7.1 用 AI 智能体创建（推荐方式）
在 Claude Code 或 Codex 对话中输入：
$short-drama 初始化一个都市打脸题材的短剧项目，竖屏 9:167.2 用命令行手动创建
$ cd ~/drama-workspace $ python3 ~/drama-workspace/drama-skills/skills/short-drama/scripts/project_tool.py init ./my-first-drama --title "我的第一部短剧"7.3 查看项目状态
$ python3 ~/drama-workspace/drama-skills/skills/short-drama/scripts/project_tool.py status ./my-first-drama7.4 生成的项目结构
my-first-drama/
├── short-drama.json # 项目配置（标题、语言、画幅等）
├── 输入/ # 放置原著/剧本等输入材料
├── 项目开发/ # 故事引擎、分集地图等
├── 剧集/ # 每集的剧本、资产、分镜等
│ └── EP001/
│ ├── 剧本.md
│ ├── 视觉设定.md
│ ├── 分镜.md
│ ├── 图片提示词.md
│ ├── 视频提示词.md
│ └── 制作成果/ # 生成的媒体文件
├── 设定集/ # 跨集共享的资产
├── 创作者决策/ # 确认与接受记录
└── 审查/ # 审查结论
7.5 查看项目配置
$ cat my-first-drama/short-drama.json | jq .关键字段：
language：创作者可读内容的语言（中文/英文）format.prompt_language：交给图片/视频生成器的提示词语言format.aspect_ratio：画幅（如 9:16 竖屏）
8启动本地创作台 Dashboard
8.1 通过 AI 智能体启动
$short-drama dashboard8.2 手动启动 Dashboard 服务器
$ cd ~/drama-workspace/my-first-drama $ python3 ~/drama-workspace/drama-skills/skills/short-drama/scripts/dashboard_server.py \ --workspace . --port 8765 --open启动后会打印回环地址，例如：
Dashboard running at http://127.0.0.1:8765 Press Ctrl+C to stop.8.3 远程访问（如果 Ubuntu 是服务器）
如果 Ubuntu 是远程服务器，需要绑定到所有网络接口：
$ python3 ~/drama-workspace/drama-skills/skills/short-drama/scripts/dashboard_server.py \ --workspace ~/drama-workspace/my-first-drama --port 8765 --host 0.0.0.0然后通过 SSH 端口转发在本地浏览器访问：
# 在你的本地机器上执行 ssh -L 8765:localhost:8765 username@your-server-ip打开浏览器访问http://localhost:8765
安全提醒：Dashboard 只读取 workspace 内的文件，密钥、生产 adapter 与工作流编排都在它之外。不要用 Dashboard 直接配置 API Key。
8.4 防火墙放行（如果需要远程访问）
# 使用 ufw 放行端口 $ sudo ufw allow 8765/tcp # 或者只允许特定 IP $ sudo ufw allow from 你的IP to any port 87659配置生产 Adapter（可选）
如果需要实际生成图片、视频、TTS 或音乐，需要配置外部 Adapter。Adapter 配置必须在项目外。
9.1 创建 Adapter 配置文件
# 配置文件放在项目外，例如 ~/drama-workspace/adapter-configs/ $ mkdir -p ~/drama-workspace/adapter-configsSeedance 视频生成 Adapter 配置示例
$ cat > ~/drama-workspace/adapter-configs/seedance.json << 'EOF' { "argv": [ "python3", "/path/to/drama-skills/skills/short-drama-produce/references/providers/seedance.py" ], "timeout": 300 } EOFGPT Image 2 图片生成 Adapter 配置示例
$ cat > ~/drama-workspace/adapter-configs/gpt-image-2.json << 'EOF' { "argv": [ "python3", "/path/to/drama-skills/skills/short-drama-produce/references/providers/gpt-image-2.py" ], "timeout": 120 } EOFMiniMax Music 音乐生成 Adapter 配置示例
$ cat > ~/drama-workspace/adapter-configs/minimax-music.json << 'EOF' { "argv": [ "python3", "/path/to/drama-skills/skills/short-drama-produce/references/providers/minimax-music.py" ], "timeout": 180 } EOF9.2 配置供应商凭据
凭据从进程环境变量读取，不写入任何配置文件：
# Seedance $ export SEEDANCE_API_KEY="your-seedance-key" $ export SEEDANCE_ENDPOINT_ID="your-endpoint-id" # GPT Image 2 $ export OPENAI_API_KEY="sk-xxxxx" # MiniMax Music $ export MINIMAX_API_KEY="your-minimax-key" # 持久化到 bashrc $ cat >> ~/.bashrc << 'EOF' export SEEDANCE_API_KEY="your-seedance-key" export SEEDANCE_ENDPOINT_ID="your-endpoint-id" export OPENAI_API_KEY="sk-xxxxx" export MINIMAX_API_KEY="your-minimax-key" EOF $ source ~/.bashrc9.3 执行生产任务
# 1. 准备并预览任务（不实际生成） $ python3 skills/short-drama-produce/scripts/production_tool.py \ prepare ~/drama-workspace/my-first-drama \ --job ~/drama-workspace/adapter-configs/my-job.json # 2. 确认任务（在看到预览后） $ python3 skills/short-drama-produce/scripts/production_tool.py \ confirm ~/drama-workspace/my-first-drama \ --job-id \ --confirmation "CONFIRM" # 3. 执行生成 $ python3 skills/short-drama-produce/scripts/production_tool.py \ run ~/drama-workspace/my-first-drama \ --job-id \ --adapter-config ~/drama-workspace/adapter-configs/gpt-image-2.json # 4. 查看状态 $ python3 skills/short-drama-produce/scripts/production_tool.py \ status ~/drama-workspace/my-first-drama --job-id # 5. 审计对账 $ python3 skills/short-drama-produce/scripts/production_tool.py \ audit ~/drama-workspace/my-first-drama生产硬闸门：每次生产必须严格经过 prepare（预览）→ confirm（明确确认）→ run（执行）三步。Job、prompt、参数、输出路径任一变化，旧确认立即失效。失败后重试也必须重新确认。
10常见问题排查
10.1 Python 版本不够
# 问题：python3 --version 显示 3.8 # 解决：从 deadsnakes PPA 安装更高版本 $ sudo add-apt-repository -y ppa:deadsnakes/ppa $ sudo apt update $ sudo apt install -y python3.11 python3.11-venv python3.11-dev # 使用 python3.11 替代 python3 $ python3.11 skills/short-drama/scripts/selftest.py10.2 pip 安装包失败（externally-managed-environment）
Ubuntu 23.04+ 默认阻止 pip 全局安装包，有两个解决方案：
# 方案一：使用 --break-system-packages 标志 $ pip3 install ruff --break-system-packages # 方案二：使用虚拟环境（推荐） $ python3 -m venv ~/drama-venv $ source ~/drama-venv/bin/activate (drama-venv)$ pip install ruff mypy10.3 符号链接失效
# 问题：移动了 drama-skills 目录后链接失效 # 解决：删除旧链接，重新创建 $ rm -f ~/.claude/skills/short-drama* $ cd /new/path/drama-skills $ for skill in skills/*; do ln -s "$PWD/$skill" "$HOME/.claude/skills/$(basename "$skill")" done10.4 Dashboard 无法访问
# 检查端口是否被占用 $ sudo lsof -i :8765 # 检查防火墙 $ sudo ufw status # 查看服务器日志 $ python3 skills/short-drama/scripts/dashboard_server.py \ --workspace ~/drama-workspace/my-first-drama --port 8765 2>&1 | head -5010.5 中文文件名显示乱码
# 设置 locale $ sudo apt install -y language-pack-zh-hans $ sudo locale-gen zh_CN.UTF-8 $ echo 'export LANG=zh_CN.UTF-8' >> ~/.bashrc $ echo 'export LC_ALL=zh_CN.UTF-8' >> ~/.bashrc $ source ~/.bashrc10.6 Git 克隆速度慢
# 使用浅克隆 $ git clone --depth 1 https://github.com/worldwonderer/drama-skills.git # 或使用镜像 $ git clone https://ghproxy.com/https://github.com/worldwonderer/drama-skills.git10.7 测试失败
# 运行单个测试看详细输出 $ python3 -B -m unittest tests.test_simple_lifecycle -v # 运行 Golden Project 测试 $ python3 -B -m unittest tests.test_golden_project -v11设置开机自启 Dashboard（进阶）
如果需要在服务器上保持 Dashboard 长期运行，可以使用 systemd 管理进程。
11.1 创建 systemd 服务
$ sudo tee /etc/systemd/system/drama-dashboard.service << 'EOF' [Unit] Description=Drama Skills Dashboard After=network.target [Service] Type=simple User=你的用户名 WorkingDirectory=/home/你的用户名/drama-workspace/my-first-drama ExecStart=/usr/bin/python3 /home/你的用户名/drama-workspace/drama-skills/skills/short-drama/scripts/dashboard_server.py --workspace /home/你的用户名/drama-workspace/my-first-drama --port 8765 --host 0.0.0.0 Restart=on-failure RestartSec=10 Environment=PYTHONUNBUFFERED=1 [Install] WantedBy=multi-user.target EOF把你的用户名替换为你的实际用户名，路径也要对应修改。
11.2 启动并设置开机自启
$ sudo systemctl daemon-reload $ sudo systemctl enable drama-dashboard $ sudo systemctl start drama-dashboard # 查看状态 $ sudo systemctl status drama-dashboard # 查看日志 $ sudo journalctl -u drama-dashboard -f11.3 管理命令
# 停止 $ sudo systemctl stop drama-dashboard # 重启 $ sudo systemctl restart drama-dashboard # 禁用开机自启 $ sudo systemctl disable drama-dashboard11.4 使用 Nginx 反向代理（可选）
$ sudo apt install -y nginx $ sudo tee /etc/nginx/sites-available/drama-dashboard << 'EOF' server { listen 80; server_name your-domain.com; location / { proxy_pass http://127.0.0.1:8765; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } } EOF $ sudo ln -s /etc/nginx/sites-available/drama-dashboard /etc/nginx/sites-enabled/ $ sudo nginx -t $ sudo systemctl restart nginx12部署检查清单
基础环境检查
Ubuntu 20.04 / 22.04 / 24.04 系统Python 3.9 或更高版本已安装Git 已安装且可用Node.js 20 已安装（Dashboard 校验需要）系统包已更新（sudo apt update && sudo apt upgrade）
Drama Skills 安装检查
仓库已克隆到~/drama-workspace/drama-skills技能符号链接已创建（~/.claude/skills/或~/.codex/skills/）selftest.py运行无报错项目初始化测试成功生产技能离线自检通过Golden Sample 校验全部通过
AI 运行环境检查
Claude Code 或 Codex CLI 已安装API Key 已配置到环境变量并持久化智能体可以识别$short-drama或/short-drama命令
生产 Adapter 检查（如需）
Adapter 配置文件已创建（项目外）供应商凭据已设置到环境变量凭据未写入任何项目文件或 Git 仓库生产自检provider_adapters.py --selftest通过
Dashboard 检查
Dashboard 服务器可以启动浏览器可以正常访问能查看项目概览和分集进度
安全检查
API Key 和供应商凭据未提交到 Git防火墙已配置（如需远程访问）Dashboard 不包含任何密钥配置入口
部署完成！现在你可以开始用 Drama Skills 创作 AI 短剧了。建议先通读examples/golden-project/八集完整样例，理解各产物的格式和引用链，然后从一个小项目开始实践。
项目地址：github.com/worldwonderer/drama-skills
