{"id":"f614585d-ed56-4b77-a557-b069b3eedc45","slug":"plotloom","kind":"skill","name":"plotloom","summary":"AI 短剧生产 CLI 工具，围绕 repo-first 工作流整合 Plotloom Skills、Codex 图片生成、Dreamina/即梦与 Seedance 2.0 视频适配器，从系列设定到候选素材、视频选择和交付全程可审查。","owner":"T0UGH","repoUrl":"https://github.com/T0UGH/plotloom","license":"MIT","licenseTier":"permissive","trust":"community","stars":6,"match":null,"fewStars":false,"format":"skill","createdAt":"2026-04-28T01:50:45.000Z","addedAt":"2026-10-22T00:58:59.626Z","logoUrl":"https://avatars.githubusercontent.com/u/33653960?u=aaafa1ee3dd714ac7e64465b04f625d946f318af&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["design-media"],"tags":["aigc","imagegen","seedance2","video"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-25T19:30:07.962Z","sample":false,"url":"https://conduits.dev/tools/plotloom","language":"Python","transports":["stdio"],"install":{"pypi":"plotloom"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Plotloom\n\n[中文](README.md) | [English](README_EN.md)\n\n[![PyPI version](https://img.shields.io/pypi/v/plotloom.svg)](https://pypi.org/project/plotloom/)\n[![Python](https://img.shields.io/badge/python-%3E%3D3.11-blue.svg)](pyproject.toml)\n[![Language](https://img.shields.io/badge/language-Python-blue.svg)](https://github.com/T0UGH/plotloom)\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n\n**AI 短剧生产 CLI | Agent-neutral Skills | Repo-first 工作流**\n\nPlotloom 是一套面向短剧生产的 CLI + Skills 工具箱。它不把创作过程藏进数据库、仪表盘或队列里，而是把每一步都落成可读、可提交、可复盘的系列仓库文件：`series.md`、`characters.md`、`video-prompts.md`、候选素材、`selected.mp4` 和最终交付物。\n\n## 核心组合\n\n| 环节 | 默认能力 |\n|------|----------|\n| 系列设定 | Plotloom skills 生成剧集设定、角色设定和 episode card |\n| 图片素材 | 本机 Codex image generation 能力，适合角色图、场景图、封面图 |\n| 视频生成 | Dreamina/即梦 CLI、VolcEngine Seedance 2.0、mock adapter |\n| 选择与交付 | 候选版本管理、`selected.*` 固化、review artifact、ffmpeg/ffprobe 拼接检查 |\n\n> Plotloom 的重点不是“一键黑盒生成”，而是让 Agent 和人类可以围绕同一个 repo 协作，把短剧生产过程拆成清晰、可审查、可重跑的文件边界。\n\n## 概述\n\n![Plotloom repo-first production flow](docs/assets/plotloom-flow.png)\n\nPlotloom 不是把一个想法直接丢给模型、等待黑盒产出成片。它把短剧生产拆成一条可审查的 repo-first 链路：先沉淀系列设定、角色关系和视觉锚点，再围绕单集生成图片与视频候选；人或 Agent 逐步选择、重跑、修 prompt，最后只把确认过的素材拼成交付物。\n\n这条链路里的每一步都有明确文件边界：\n\n- `series.md` / `characters.md`：系列长期记忆和角色一致性锚点。\n- `episode-card.md`：单集 hook、反转、情绪目标和 cliffhanger。\n- `video-prompts.md` / `video-prompts-en.md`：可提交给 Dreamina、Seedance 等模型的 clip 任务。\n- `reference-map.toml`：显式记录 first/last frame、角色、场景、道具等 reference intent。\n- `candidates/`：模型生成的多版本图片或视频素材。\n- `selected.*`：经过 review 后被接受的版本。\n- `tasks/*.toml`：provider 请求、任务状态、receipt、prompt hash 和 QA checklist。\n- `review/` / `selected-note.md`：候选审查材料、抽帧、媒体 facts 和选择原因。\n- `final.mp4`：由 selected clips 拼接出的最终交付视频。\n\n## 推荐客户端\n\n| 客户端 | 状态 |\n|--------|------|\n| Codex | 已适配 CLI + skills 协作方式 |\n| Claude Code | 可通过 skills 安装使用 |\n| 其他支持 skills.sh 的客户端 | 按各自的 skills 安装方式接入 |\n\nPlotloom 的核心约束是 agent-neutral：CLI 不绑定某一个 Agent，skills 也尽量用文件契约而不是隐藏状态传递上下文。\n\n## 安装 CLI\n\n### 方式一：uvx（推荐，无需安装）\n\n```bash\nuvx plotloom --help\n```\n\n### 方式二：pip（全局安装）\n\n```bash\npip install plotloom\nplotloom --help\n```\n\n### 方式三：本地开发模式\n\n```bash\ngit clone https://github.com/T0UGH/plotloom.git\ncd plotloom\npip install -e .\nplotloom --help\n```\n\n如需运行开发测试：\n\n```bash\nuv sync --extra dev\nuv run pytest\n```\n\n## 安装 Skills\n\nPlotloom skills 推荐通过 `skills` CLI 安装：\n\n```bash\nnpx skills add T0UGH/plotloom --all\n```\n\n常用变体：\n\n```bash\n# 项目级安装，交互选择 Agent\nnpx skills add T0UGH/plotloom\n\n# 全局安装到支持的 Agent\nnpx skills add T0UGH/plotloom --global --all\n\n# 只安装一个 skill\nnpx skills add T0UGH/plotloom --skill plotloom-shot-prompts --all\n\n# 只查看可安装的 skills\nnpx skills add T0UGH/plotloom --list\n```\n\n本地开发时可以从仓库根目录安装：\n\n```bash\nnpx skills add . --list\nnpx skills add . --all\n```\n\n## 快速开始\n\n```bash\n# 1. 初始化本机配置\nplotloom config init\n\n# 2. 创建一个短剧系列 repo\nplotloom init neon-heiress --title \"霓虹假千金\"\n\n# 3. 进入默认创建位置\ncd ~/plotloom_repo/neon-heiress\n\n# 4. 补一段可测试的 prompt\ncat > episodes/ep001/video-prompts-en.md <<'EOF'\n## Clip 01\n\nPrompt string:\nA 5-second vertical short-drama opening. A young heiress walks into a neon-lit hotel lobby, calm but dangerous.\nEOF\n\n# 5. 本地 mock 生成候选视频，不调用真实 provider\nplotloom --repo . video submit --episode ep001 --clip clip-01 --adapter mock\n\n# 6. 选择候选版本\nplotloom --repo . select episodes/ep001/videos/clip-01/candidates/v001.mock.mp4\n\n# 7. 检查 repo 状态\nplotloom --repo . validate --require-prompts --require-media\n```\n\n生成后的关键文件：\n\n```text\nepisodes/ep001/video-prompts-en.md\nepisodes/ep001/videos/clip-01/candidates/v001.mock.mp4\nepisodes/ep001/videos/clip-01/selected.mp4\nepisodes/ep001/videos/clip-01/tasks/mock-local.toml\n```\n\n## 通过 Skills 创作\n\nPlotloom 的推荐用法是让 Agent 按阶段调用 skills，而不是一次性完成所有步骤。先用 series/episode/prompt skills 把创作意图收敛成稳定文件，再用 adapter/selection/delivery skills 生产、审查和交付素材。\n\n![Plotloom skills usage guide](docs/assets/plotloom-skills-guide.png)\n\n推荐顺序：\n\n```text\n1. plotloom-series-brainstorming       -> 先 brainstorm 对齐系列方向，再稳定角色和视觉锚点\n2. plotloom-character-reference-sheet  -> 生成生产级角色设定图 brief/prompt/reference-sheet\n3. plotloom-episode-card               -> 定义单集 hook、反转、cliffhanger\n4. plotloom-shot-prompts               -> 生成连续视频 prompt\n5. plotloom-video-adapter              -> 提交 mock / Dreamina / Seedance 候选视频，并记录 receipt\n6. plotloom-asset-selection            -> accept、review、reroll 或 revise_prompt\n7. plotloom-stitch-deliver             -> 拼接 selected clips 并准备交付\n8. plotloom-subtitle-burnin            -> 基于最终视频补英文/中文/双语字幕并烧录验证\n```\n\n### Skills 清单\n\n| Skill | 说明 |\n|-------|------|\n| `plotloom-series-brainstorming` | 用启发式讨论收敛系列方向，并创建或更新 `series.md`、`characters.md` |\n| `plotloom-character-reference-sheet` | 生成生产级角色设定图 brief/prompt：转面、色板、表情、微表情、服装、道具和手势 |\n| `plotloom-episode-card` | 为单集生成轻量 episode intent card |\n| `plotloom-shot-prompts` | 生成适合 Seedance/Dreamina 的连续视频 prompt |\n| `plotloom-video-adapter` | 规划 reference map，提交或轮询 mock、Dreamina、VolcEngine 视频任务 |\n| `plotloom-asset-selection` | 审查候选素材并固化为 `selected.*`，可写入选择原因和 continuity artifacts |\n| `plotloom-stitch-deliver` | 用本地媒体工具拼接 `final.mp4` 并整理交付文件 |\n| `plotloom-subtitle-burnin` | 基于最终成片生成英文/中文/双语字幕、烧录字幕并做解码和抽帧验证 |\n\n## 支持的 Provider\n\n| Adapter | 类型 | 用途 | 备注 |\n|---------|------|------|------|\n| `mock` | 本地视频 | 本地 E2E、测试和演示 | 不调用真实 provider |\n| `codex-app-server` | 图片 | 角色、场景、封面、reference 图 | 依赖本机 Codex 和 image generation 能力 |\n| `dreamina-cli` | 视频 | Dreamina/即梦视频生成 | 依赖本机 Dreamina CLI 登录态 |\n| `volcengine-seedance` | 视频 | VolcEngine Ark Seedance 2.0 | 通过 Ark async task API 提交和轮询 |\n| `youtube-shorts` | 交付 | 上传最终短视频到 YouTube Shorts | 依赖本机 OAuth 凭证 |\n\n真实 provider 建议先跑 doctor，再做单条短 clip smoke：\n\n```bash\nplotloom doctor --adapter dreamina-cli --deep\nplotloom doctor --adapter volcengine-seedance --deep\nplotloom config doctor --adapter volcengine-seedance\n```\n\n更多 smoke 步骤见 [Plotloom Provider Smoke Runbook](docs/runbooks/plotloom-provider-smoke.md)。\nAdapter and host notes are indexed in [docs/README.md](docs/README.md).\n\n## CLI 命令\n\n| 命令 | 说明 |\n|------|------|\n| `plotloom init` | 初始化一个系列 repo |\n| `plotloom validate` | 检查系列 repo 的必要文件和媒体状态 |\n| `plotloom config` | 管理 `~/.plotloom/.env.toml` 配置 |\n| `plotloom repos` | 管理本机系列 repo registry |\n| `plotloom prompt` | 检查、提取、编译 episode prompt |\n| `plotloom image` | 生成并归档图片候选 |\n| `plotloom video` | 规划 references，提交、轮询和比较视频生成任务 |\n| `plotloom asset` | 导入和查看本地素材 |\n| `plotloom face` | 检查角色 face policy，并生成 provider smoke prompt |\n| `plotloom review` | 生成图片 contact sheet、视频 review artifact 和 selected note |\n| `plotloom select` | 把候选素材复制为 `selected.*`，可记录选择原因 |\n| `plotloom media` | 调用本地媒体工具 probe、check、normalize |\n| `plotloom stitch` | 规划或拼接 selected clips |\n| `plotloom delivery` | 汇总交付文件 |\n| `plotloom youtube` | OAuth 登录并上传 YouTube Shorts |\n| `plotloom doctor` | 检查本机 adapter、依赖和配置状态 |\n\n查看完整参数：\n\n```bash\nplotloom --help\nplotloom prompt compile --help\nplotloom video plan-references --help\nplotloom video submit --help\nplotloom image generate --help\nplotloom review media --help\n```\n\n## Reference、Prompt 和 Review 工作流\n\n生产场景建议显式拆开 reference intent、provider prompt、候选审查和选择结果：\n\n```bash\n# 为一个 clip 写入 reference-map.toml；路径是 repo 内相对路径或本地文件路径\nplotloom --repo . video plan-references \\\n  --episode ep001 \\\n  --clip clip-01 \\\n  --first-frame assets/scenes/hotel-lobby/selected.png \\\n  --reference \"character:hero=assets/cast/hero/selected.png\" \\\n  --write\n\n# 编译 provider prompt，写出可审计文本，并附带 source_prompt_sha256 / qa_checklist\nplotloom --repo . prompt compile \\\n  --episode ep001 \\\n  --clip clip-01 \\\n  --adapter volcengine-seedance \\\n  --mode image-to-video \\\n  --reference-map episodes/ep001/videos/clip-01/reference-map.toml \\\n  --lint \\\n  --output episodes/ep001/videos/clip-01/compiled-prompt.txt\n\n# 提交视频任务；reference-map 会进入请求摘要和 receipt，provider 是否支持取决于 adapter\nplotloom --repo . video submit \\\n  --episode ep001 \\\n  --clip clip-01 \\\n  --adapter volcengine-seedance \\\n  --mode image-to-video \\\n  --reference-map episodes/ep001/videos/clip-01/reference-map.toml\n\n# 为候选视频生成 ffprobe、volumedetect、首尾帧和 REVIEW.md\nplotloom --repo . review media \\\n  --episode ep001 \\\n  --clip clip-01 \\\n  --candidate v001\n\n# 接受候选，并记录人工选择原因\nplotloom --repo . select \\\n  episodes/ep001/videos/clip-01/candidates/v001.mp4 \\\n  --reason \"identity and story beat passed\"\n```\n\n`prompt check --strict-refs` 可以把 prompt 里的 `Image 1` / `Image 2` / `图片 1` 这类槽位和 `reference-map.toml` 对齐，不匹配时失败。Plotloom 不会默认自动生成大量候选版本；多候选探索需要人或上层 Agent 明确触发，避免无意消耗真实 provider 额度。\n\n## 配置\n\nPlotloom 默认配置文件是：\n\n```text\n~/.plotloom/.env.toml\n```\n\n初始化：\n\n```bash\nplotloom config init\nplotloom config path\n```\n\n默认模板会包含：\n\n```toml\n[plotloom]\nrepos_root = \"~/plotloom_repo\"\nregistry_path = \"~/plotloom.toml\"\ndefault_image_adapter = \"codex-app-server\"\ndefault_video_adapters = [\"dreamina-cli\", \"volcengine-seedance\"]\n\n[adapters.codex-app-server]\nenabled = true\ncodex_binary = \"codex\"\napp_server_url = \"\"\n\n[adapters.dreamina-cli]\nenabled = true\nbinary = \"dreamina\"\nhome = \"~\"\n\n[adapters.volcengine-seedance]\nenabled = true\nark_api_key = \"\"\nbase_url = \"https://ark.cn-beijing.volces.com/api/v3\"\nmodel = \"doubao-seedance-2-0-260128\"\ndefault_resolution = \"720p\"\n\n[adapters.youtube-shorts]\nenabled = true\nclient_secrets_file = \"~/.plotloom/youtube-client-secrets.json\"\ncredentials_file = \"~/.plotloom/youtube-credentials.json\"\ndefault_privacy = \"public\"\n```\n\n系列 repo 自身的 `plotloom.toml` 也可以打开可选的视频 continuity artifact。默认关闭；开启后，`plotloom select` 会为 selected 视频抽取配置指定的首帧/尾帧并写入 `selected-note.md`，但不会自动把上一条 clip 的尾帧提交给 provider：\n\n```toml\n[video.continuity]\nenabled = true\nextract_first_frame = true\nextract_last_frame = true\nauto_use_previous_last_frame = false\n```\n\n### 环境变量覆盖\n\n| 环境变量 | 配置项 |\n|----------|--------|\n| `PLOTLOOM_CONFIG` | 指定配置文件路径 |\n| `PLOTLOOM_REPOS_ROOT` | 覆盖默认系列 repo 根目录 |\n| `PLOTLOOM_REGISTRY_PATH` | 覆盖 registry 路径 |\n| `CODEX_BINARY` | 覆盖 Codex binary |\n| `CODEX_APP_SERVER_URL` | 覆盖 Codex app server URL |\n| `DREAMINA_BINARY` | 覆盖 Dreamina CLI binary |\n| `DREAMINA_HOME` | 覆盖 Dreamina home |\n| `ARK_API_KEY` | VolcEngine Ark API Key |\n| `PLOTLOOM_VOLCENGINE_BASE_URL` | 覆盖 VolcEngine base URL |\n| `PLOTLOOM_VOLCENGINE_MODEL` | 覆盖 Seedance model |\n| `YOUTUBE_CLIENT_SECRETS_FILE` | 覆盖 YouTube OAuth client secrets 路径 |\n| `YOUTUBE_CREDENTIALS_FILE` | 覆盖 YouTube OAuth credentials 路径 |\n| `YOUTUBE_DEFAULT_PRIVACY` | 覆盖 YouTube 默认发布可见性 |\n\n配置优先级：\n\n```text\n环境变量 > ~/.plotloom/.env.toml > 内置默认值\n```\n\nPlotloom 的 doctor 只报告密钥是否存在，不会输出密钥内容。\n\n## 系列 Repo 结构\n\n```text\nseries.md\ncharacters.md\nplotloom.toml\nassets/\n  cast/\n  scenes/\nepisodes/\n  ep001/\n    episode-card.md\n    video-prompts.md\n    video-prompts-en.md\n    images/\n    videos/\n      clip-01/\n        candidates/\n        tasks/\n        reference-map.toml\n        review/\n        selected.mp4\n        selected-note.md\noutputs/\n```\n\n这个结构是 Plotloom 的主要状态边界：Agent 可以读写它，人类可以 review 它，Git 可以记录它。\n\n## 设计边界\n\nPlotloom 当前不做这些事：\n\n- 不内置数据库\n- 不维护隐藏 workflow state\n- 不提供 dashboard\n- 不运行后台队列 worker\n- 不默认批量消耗真实 provider 额度\n- 不把 Feishu/Lark 当作状态中心\n- 不强制生成完整剧本、分镜表或导演阐述\n\nMVP 的原则是 prompt-first、repo-first、adapter-thin。\n\n## 开发\n\n```bash\n# 安装开发依赖\nuv sync --extra dev\n\n# 运行测试\nuv run pytest\n\n# 构建并检查包\nrm -rf dist build plotloom.egg-info\nuv build\nuv publish --dry-run --check-url https://pypi.org/simple/ dist/*\n```\n\n发布新版本前需要先 bump `pyproject.toml` 里的版本号；PyPI 不允许覆盖已经发布的同名版本。\n\n## Tagline\n\nWeave short dramas from sparks.\n"}