Ubuntu 部署 Drama Skills 详细教程

玛卡叭咔

180人浏览 · 2026-09-05 11:44:37

玛卡叭咔 · 2026-09-05 11:44:37 发布

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:       jammy

1.2 更新系统包

$ sudo apt update && sudo apt upgrade -y

1.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.x

2.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.x

2.3 安装其他工具

$ sudo apt install -y build-essential jq

build-essential：编译部分 Python 包可能需要
jq：命令行处理 JSON 文件（查看项目状态时有用）

3安装 Git 并克隆仓库

3.1 安装 Git

$ sudo apt install -y git
$ git --version

3.2 选择安装目录

推荐放在用户主目录下的专用文件夹：

$ mkdir -p ~/drama-workspace
$ cd ~/drama-workspace

3.3 克隆 Drama Skills 仓库

$ cd ~/drama-workspace
$ git clone https://github.com/worldwonderer/drama-skills.git
$ cd drama-skills

# 查看仓库结构
$ ls -la

3.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.json

5.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 -v

5.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.js

5.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 --version

6.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:16

7.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-drama

7.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 dashboard

8.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 8765

9配置生产 Adapter（可选）

如果需要实际生成图片、视频、TTS 或音乐，需要配置外部 Adapter。Adapter 配置必须在项目外。

9.1 创建 Adapter 配置文件

# 配置文件放在项目外，例如 ~/drama-workspace/adapter-configs/
$ mkdir -p ~/drama-workspace/adapter-configs

Seedance 视频生成 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
}
EOF

GPT 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
}
EOF

MiniMax 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
}
EOF

9.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 ~/.bashrc

9.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.py

`10.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 mypy

`10.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")"
done

`10.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 -50

`10.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 ~/.bashrc

`10.6 Git 克隆速度慢`

# 使用浅克隆
$ git clone --depth 1 https://github.com/worldwonderer/drama-skills.git

# 或使用镜像
$ git clone https://ghproxy.com/https://github.com/worldwonderer/drama-skills.git

`10.7 测试失败`

# 运行单个测试看详细输出
$ python3 -B -m unittest tests.test_simple_lifecycle -v

# 运行 Golden Project 测试
$ python3 -B -m unittest tests.test_golden_project -v

`11设置开机自启 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 -f

`11.3 管理命令`

# 停止
$ sudo systemctl stop drama-dashboard

# 重启
$ sudo systemctl restart drama-dashboard

# 禁用开机自启
$ sudo systemctl disable drama-dashboard

`11.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 nginx