ARTICLE DETAIL

建站实战干货

来自一线的建站与推广经验沉淀，每一条都经过真实交付验证。

首页 / 资讯中心 / 正文

Ubuntu 部署 Drama Skills 详细教程

2026/9/6 8:05:02 拓冰建站 浏览量
Ubuntu 部署 Drama Skills 详细教程 Ubuntu 部署 Drama Skills 详细教程从零开始在 Ubuntu 服务器 / 桌面环境中安装、配置并运行 Drama Skills AI 短剧创作工作流Ubuntu 20.04 / 22.04 / 24.04Python 3.910 个独立技能 教程目录环境准备与系统检查安装 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 git2安装 Python 与依赖工具2.1 安装 Python 3Ubuntu 20.04 自带 Python 3.8需要升级Ubuntu 22.04 / 24.04 自带 3.10 / 3.12通常满足要求。推荐安装最新的 Python 3Ubuntu 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.jsDashboard 校验需要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.md4安装 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_DIR4.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 ruff0.15.11 mypy2.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 方案 AClaude 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_KEYsk-ant-xxxxx你的密钥xxxxx # 写入 shell 配置文件持久化 $ echo export ANTHROPIC_API_KEYsk-ant-xxxxx你的密钥xxxxx ~/.bashrc $ source ~/.bashrc验证$ claude --version6.2 方案 BCodex CLI安装$ npm install -g openai/codex配置$ export OPENAI_API_KEYsk-xxxxx你的密钥xxxxx $ echo export OPENAI_API_KEYsk-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启动本地创作台 Dashboard8.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 CtrlC 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 usernameyour-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_KEYyour-seedance-key $ export SEEDANCE_ENDPOINT_IDyour-endpoint-id # GPT Image 2 $ export OPENAI_API_KEYsk-xxxxx # MiniMax Music $ export MINIMAX_API_KEYyour-minimax-key # 持久化到 bashrc $ cat ~/.bashrc EOF export SEEDANCE_API_KEYyour-seedance-key export SEEDANCE_ENDPOINT_IDyour-endpoint-id export OPENAI_API_KEYsk-xxxxx export MINIMAX_API_KEYyour-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-environmentUbuntu 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 21 | head -5010.5 中文文件名显示乱码# 设置 locale $ sudo apt install -y language-pack-zh-hans $ sudo locale-gen zh_CN.UTF-8 $ echo export LANGzh_CN.UTF-8 ~/.bashrc $ echo export LC_ALLzh_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] DescriptionDrama Skills Dashboard Afternetwork.target [Service] Typesimple 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 Restarton-failure RestartSec10 EnvironmentPYTHONUNBUFFERED1 [Install] WantedBymulti-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 upgradeDrama 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