Plotloom

AI 短剧生产 CLI | Agent-neutral Skills | Repo-first 工作流

Plotloom 是一套面向短剧生产的 CLI + Skills 工具箱。它不把创作过程藏进数据库、仪表盘或队列里，而是把每一步都落成可读、可提交、可复盘的系列仓库文件：series.md、characters.md、video-prompts.md、候选素材、selected.mp4 和最终交付物。

核心组合

环节	默认能力
系列设定	Plotloom skills 生成剧集设定、角色设定和 episode card
图片素材	本机 Codex image generation 能力，适合角色图、场景图、封面图
视频生成	Dreamina/即梦 CLI、VolcEngine Seedance 2.0、mock adapter
选择与交付	候选版本管理、`selected.*` 固化、review artifact、ffmpeg/ffprobe 拼接检查

Plotloom 的重点不是“一键黑盒生成”，而是让 Agent 和人类可以围绕同一个 repo 协作，把短剧生产过程拆成清晰、可审查、可重跑的文件边界。

概述

Plotloom 不是把一个想法直接丢给模型、等待黑盒产出成片。它把短剧生产拆成一条可审查的 repo-first 链路：先沉淀系列设定、角色关系和视觉锚点，再围绕单集生成图片与视频候选；人或 Agent 逐步选择、重跑、修 prompt，最后只把确认过的素材拼成交付物。

这条链路里的每一步都有明确文件边界：

series.md / characters.md：系列长期记忆和角色一致性锚点。
episode-card.md：单集 hook、反转、情绪目标和 cliffhanger。
video-prompts.md / video-prompts-en.md：可提交给 Dreamina、Seedance 等模型的 clip 任务。
reference-map.toml：显式记录 first/last frame、角色、场景、道具等 reference intent。
candidates/：模型生成的多版本图片或视频素材。
selected.*：经过 review 后被接受的版本。
tasks/*.toml：provider 请求、任务状态、receipt、prompt hash 和 QA checklist。
review/ / selected-note.md：候选审查材料、抽帧、媒体 facts 和选择原因。
final.mp4：由 selected clips 拼接出的最终交付视频。

安装 CLI

方式一：uvx（推荐，无需安装）

uvx plotloom --help

方式二：pip（全局安装）

pip install plotloom
plotloom --help

方式三：本地开发模式

git clone https://github.com/T0UGH/plotloom.git
cd plotloom
pip install -e .
plotloom --help

如需运行开发测试：

uv sync --extra dev
uv run pytest

安装 Skills

Plotloom skills 推荐通过 skills CLI 安装：

npx skills add T0UGH/plotloom --all

常用变体：

# 项目级安装，交互选择 Agent
npx skills add T0UGH/plotloom

# 全局安装到支持的 Agent
npx skills add T0UGH/plotloom --global --all

# 只安装一个 skill
npx skills add T0UGH/plotloom --skill plotloom-shot-prompts --all

# 只查看可安装的 skills
npx skills add T0UGH/plotloom --list

本地开发时可以从仓库根目录安装：

npx skills add . --list
npx skills add . --all

快速开始

# 1. 初始化本机配置
plotloom config init

# 2. 创建一个短剧系列 repo
plotloom init neon-heiress --title "霓虹假千金"

# 3. 进入默认创建位置
cd ~/plotloom_repo/neon-heiress

# 4. 补一段可测试的 prompt
cat > episodes/ep001/video-prompts-en.md <<'EOF'
## Clip 01

Prompt string:
A 5-second vertical short-drama opening. A young heiress walks into a neon-lit hotel lobby, calm but dangerous.
EOF

# 5. 本地 mock 生成候选视频，不调用真实 provider
plotloom --repo . video submit --episode ep001 --clip clip-01 --adapter mock

# 6. 选择候选版本
plotloom --repo . select episodes/ep001/videos/clip-01/candidates/v001.mock.mp4

# 7. 检查 repo 状态
plotloom --repo . validate --require-prompts --require-media

生成后的关键文件：

episodes/ep001/video-prompts-en.md
episodes/ep001/videos/clip-01/candidates/v001.mock.mp4
episodes/ep001/videos/clip-01/selected.mp4
episodes/ep001/videos/clip-01/tasks/mock-local.toml

通过 Skills 创作

Plotloom 的推荐用法是让 Agent 按阶段调用 skills，而不是一次性完成所有步骤。先用 series/episode/prompt skills 把创作意图收敛成稳定文件，再用 adapter/selection/delivery skills 生产、审查和交付素材。

推荐顺序：

1. plotloom-series-brainstorming       -> 先 brainstorm 对齐系列方向，再稳定角色和视觉锚点
2. plotloom-character-reference-sheet  -> 生成生产级角色设定图 brief/prompt/reference-sheet
3. plotloom-episode-card               -> 定义单集 hook、反转、cliffhanger
4. plotloom-shot-prompts               -> 生成连续视频 prompt
5. plotloom-video-adapter              -> 提交 mock / Dreamina / Seedance 候选视频，并记录 receipt
6. plotloom-asset-selection            -> accept、review、reroll 或 revise_prompt
7. plotloom-stitch-deliver             -> 拼接 selected clips 并准备交付
8. plotloom-subtitle-burnin            -> 基于最终视频补英文/中文/双语字幕并烧录验证

Skills 清单

Skill	说明
`plotloom-series-brainstorming`	用启发式讨论收敛系列方向，并创建或更新 `series.md`、`characters.md`
`plotloom-character-reference-sheet`	生成生产级角色设定图 brief/prompt：转面、色板、表情、微表情、服装、道具和手势
`plotloom-episode-card`	为单集生成轻量 episode intent card
`plotloom-shot-prompts`	生成适合 Seedance/Dreamina 的连续视频 prompt
`plotloom-video-adapter`	规划 reference map，提交或轮询 mock、Dreamina、VolcEngine 视频任务
`plotloom-asset-selection`	审查候选素材并固化为 `selected.*`，可写入选择原因和 continuity artifacts
`plotloom-stitch-deliver`	用本地媒体工具拼接 `final.mp4` 并整理交付文件
`plotloom-subtitle-burnin`	基于最终成片生成英文/中文/双语字幕、烧录字幕并做解码和抽帧验证

支持的 Provider

Adapter	类型	用途	备注
`mock`	本地视频	本地 E2E、测试和演示	不调用真实 provider
`codex-app-server`	图片	角色、场景、封面、reference 图	依赖本机 Codex 和 image generation 能力
`dreamina-cli`	视频	Dreamina/即梦视频生成	依赖本机 Dreamina CLI 登录态
`volcengine-seedance`	视频	VolcEngine Ark Seedance 2.0	通过 Ark async task API 提交和轮询
`youtube-shorts`	交付	上传最终短视频到 YouTube Shorts	依赖本机 OAuth 凭证

真实 provider 建议先跑 doctor，再做单条短 clip smoke：

plotloom doctor --adapter dreamina-cli --deep
plotloom doctor --adapter volcengine-seedance --deep
plotloom config doctor --adapter volcengine-seedance

更多 smoke 步骤见 Plotloom Provider Smoke Runbook。 Adapter and host notes are indexed in docs/README.md.

CLI 命令

命令	说明
`plotloom init`	初始化一个系列 repo
`plotloom validate`	检查系列 repo 的必要文件和媒体状态
`plotloom config`	管理 `~/.plotloom/.env.toml` 配置
`plotloom repos`	管理本机系列 repo registry
`plotloom prompt`	检查、提取、编译 episode prompt
`plotloom image`	生成并归档图片候选
`plotloom video`	规划 references，提交、轮询和比较视频生成任务
`plotloom asset`	导入和查看本地素材
`plotloom face`	检查角色 face policy，并生成 provider smoke prompt
`plotloom review`	生成图片 contact sheet、视频 review artifact 和 selected note
`plotloom select`	把候选素材复制为 `selected.*`，可记录选择原因
`plotloom media`	调用本地媒体工具 probe、check、normalize
`plotloom stitch`	规划或拼接 selected clips
`plotloom delivery`	汇总交付文件
`plotloom youtube`	OAuth 登录并上传 YouTube Shorts
`plotloom doctor`	检查本机 adapter、依赖和配置状态

查看完整参数：

plotloom --help
plotloom prompt compile --help
plotloom video plan-references --help
plotloom video submit --help
plotloom image generate --help
plotloom review media --help

Reference、Prompt 和 Review 工作流

生产场景建议显式拆开 reference intent、provider prompt、候选审查和选择结果：

# 为一个 clip 写入 reference-map.toml；路径是 repo 内相对路径或本地文件路径
plotloom --repo . video plan-references \
  --episode ep001 \
  --clip clip-01 \
  --first-frame assets/scenes/hotel-lobby/selected.png \
  --reference "character:hero=assets/cast/hero/selected.png" \
  --write

# 编译 provider prompt，写出可审计文本，并附带 source_prompt_sha256 / qa_checklist
plotloom --repo . prompt compile \
  --episode ep001 \
  --clip clip-01 \
  --adapter volcengine-seedance \
  --mode image-to-video \
  --reference-map episodes/ep001/videos/clip-01/reference-map.toml \
  --lint \
  --output episodes/ep001/videos/clip-01/compiled-prompt.txt

# 提交视频任务；reference-map 会进入请求摘要和 receipt，provider 是否支持取决于 adapter
plotloom --repo . video submit \
  --episode ep001 \
  --clip clip-01 \
  --adapter volcengine-seedance \
  --mode image-to-video \
  --reference-map episodes/ep001/videos/clip-01/reference-map.toml

# 为候选视频生成 ffprobe、volumedetect、首尾帧和 REVIEW.md
plotloom --repo . review media \
  --episode ep001 \
  --clip clip-01 \
  --candidate v001

# 接受候选，并记录人工选择原因
plotloom --repo . select \
  episodes/ep001/videos/clip-01/candidates/v001.mp4 \
  --reason "identity and story beat passed"

prompt check --strict-refs 可以把 prompt 里的 Image 1 / Image 2 / 图片 1 这类槽位和 reference-map.toml 对齐，不匹配时失败。Plotloom 不会默认自动生成大量候选版本；多候选探索需要人或上层 Agent 明确触发，避免无意消耗真实 provider 额度。

配置

Plotloom 默认配置文件是：

~/.plotloom/.env.toml

初始化：

plotloom config init
plotloom config path

默认模板会包含：

[plotloom]
repos_root = "~/plotloom_repo"
registry_path = "~/plotloom.toml"
default_image_adapter = "codex-app-server"
default_video_adapters = ["dreamina-cli", "volcengine-seedance"]

[adapters.codex-app-server]
enabled = true
codex_binary = "codex"
app_server_url = ""

[adapters.dreamina-cli]
enabled = true
binary = "dreamina"
home = "~"

[adapters.volcengine-seedance]
enabled = true
ark_api_key = ""
base_url = "https://ark.cn-beijing.volces.com/api/v3"
model = "doubao-seedance-2-0-260128"
default_resolution = "720p"

[adapters.youtube-shorts]
enabled = true
client_secrets_file = "~/.plotloom/youtube-client-secrets.json"
credentials_file = "~/.plotloom/youtube-credentials.json"
default_privacy = "public"

系列 repo 自身的 plotloom.toml 也可以打开可选的视频 continuity artifact。默认关闭；开启后，plotloom select 会为 selected 视频抽取配置指定的首帧/尾帧并写入 selected-note.md，但不会自动把上一条 clip 的尾帧提交给 provider：

[video.continuity]
enabled = true
extract_first_frame = true
extract_last_frame = true
auto_use_previous_last_frame = false

环境变量覆盖

环境变量	配置项
`PLOTLOOM_CONFIG`	指定配置文件路径
`PLOTLOOM_REPOS_ROOT`	覆盖默认系列 repo 根目录
`PLOTLOOM_REGISTRY_PATH`	覆盖 registry 路径
`CODEX_BINARY`	覆盖 Codex binary
`CODEX_APP_SERVER_URL`	覆盖 Codex app server URL
`DREAMINA_BINARY`	覆盖 Dreamina CLI binary
`DREAMINA_HOME`	覆盖 Dreamina home
`ARK_API_KEY`	VolcEngine Ark API Key
`PLOTLOOM_VOLCENGINE_BASE_URL`	覆盖 VolcEngine base URL
`PLOTLOOM_VOLCENGINE_MODEL`	覆盖 Seedance model
`YOUTUBE_CLIENT_SECRETS_FILE`	覆盖 YouTube OAuth client secrets 路径
`YOUTUBE_CREDENTIALS_FILE`	覆盖 YouTube OAuth credentials 路径
`YOUTUBE_DEFAULT_PRIVACY`	覆盖 YouTube 默认发布可见性

配置优先级：

环境变量 > ~/.plotloom/.env.toml > 内置默认值

Plotloom 的 doctor 只报告密钥是否存在，不会输出密钥内容。

系列 Repo 结构

series.md
characters.md
plotloom.toml
assets/
  cast/
  scenes/
episodes/
  ep001/
    episode-card.md
    video-prompts.md
    video-prompts-en.md
    images/
    videos/
      clip-01/
        candidates/
        tasks/
        reference-map.toml
        review/
        selected.mp4
        selected-note.md
outputs/

这个结构是 Plotloom 的主要状态边界：Agent 可以读写它，人类可以 review 它，Git 可以记录它。

设计边界

Plotloom 当前不做这些事：

不内置数据库
不维护隐藏 workflow state
不提供 dashboard
不运行后台队列 worker
不默认批量消耗真实 provider 额度
不把 Feishu/Lark 当作状态中心
不强制生成完整剧本、分镜表或导演阐述

MVP 的原则是 prompt-first、repo-first、adapter-thin。

开发

# 安装开发依赖
uv sync --extra dev

# 运行测试
uv run pytest

# 构建并检查包
rm -rf dist build plotloom.egg-info
uv build
uv publish --dry-run --check-url https://pypi.org/simple/ dist/*

发布新版本前需要先 bump pyproject.toml 里的版本号；PyPI 不允许覆盖已经发布的同名版本。

Tagline

Weave short dramas from sparks.

Name		Name	Last commit message	Last commit date
Latest commit History 100 Commits
docs		docs
examples		examples
plotloom		plotloom
skills		skills
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
LICENSE		LICENSE
README.md		README.md
README_EN.md		README_EN.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

客户端	状态
Codex	已适配 CLI + skills 协作方式
Claude Code	可通过 skills 安装使用
其他支持 skills.sh 的客户端	按各自的 skills 安装方式接入

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Plotloom

核心组合

概述

推荐客户端

安装 CLI

方式一：uvx（推荐，无需安装）

方式二：pip（全局安装）

方式三：本地开发模式

安装 Skills

快速开始

通过 Skills 创作

Skills 清单

支持的 Provider

CLI 命令

Reference、Prompt 和 Review 工作流

配置

环境变量覆盖

系列 Repo 结构

设计边界

开发

Tagline

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Plotloom

核心组合

概述

推荐客户端

安装 CLI

方式一：uvx（推荐，无需安装）

方式二：pip（全局安装）

方式三：本地开发模式

安装 Skills

快速开始

通过 Skills 创作

Skills 清单

支持的 Provider

CLI 命令

Reference、Prompt 和 Review 工作流

配置

环境变量覆盖

系列 Repo 结构

设计边界

开发

Tagline

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages