plotloom

KO | EN

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #deepseek-harness #dsh-plugin #open-source #ai #cli #claude-code #windows #codex #developer-tools #dsh

★ 7 Open GitHub ↗

AI 短剧生产 CLI 工具，围绕 repo-first 工作流整合 Plotloom Skills、Codex 图片生成、Dreamina/即梦与 Seedance 2.0 视频适配器，从系列设定到候选素材、视频选择和交付全程可审查。

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Plotloom

[中文](README.md) | [English](README_EN.md)

[![PyPI version](https://img.shields.io/pypi/v/plotloom.svg)](https://pypi.org/project/plotloom/)
[![Python](https://img.shields.io/badge/python-%3E%3D3.11-blue.svg)](https://raw.githubusercontent.com/T0UGH/plotloom/main/pyproject.toml)
[![Language](https://img.shields.io/badge/language-Python-blue.svg)](https://github.com/T0UGH/plotloom)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://raw.githubusercontent.com/T0UGH/plotloom/main/LICENSE)

**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 production flow](https://raw.githubusercontent.com/T0UGH/plotloom/main/docs/assets/plotloom-flow.png)

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 拼接出的最终交付视频。

## 推荐客户端

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

Plotloom 的核心约束是 agent-neutral：CLI 不绑定某一个 Agent，skills 也尽量用文件契约而不是隐藏状态传递上下文。

## 安装 CLI

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

```bash
uvx plotloom --help
```

### 方式二：pip（全局安装）

```bash
pip install plotloom
plotloom --help
```

### 方式三：本地开发模式

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

如需运行开发测试：

```bash
uv sync --extra dev
uv run pytest
```

## 安装 Skills

Plotloom skills 推荐通过 `skills` CLI 安装：

```bash
npx skills add T0UGH/plotloom --all
```

常用变体：

```bash
# 项目级安装，交互选择 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
```

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

```bash
npx skills add . --list
npx skills add . --all
```

## 快速开始

```bash
# 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
```

生成后的关键文件：

```text
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 生产、审查和交付素材。

![Plotloom skills usage guide](https://raw.githubusercontent.com/T0UGH/plotloom/main/docs/assets/plotloom-skills-guide.png)

推荐顺序：

```text
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：

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

更多 smoke 步骤见 [Plotloom Provider Smoke Runbook](docs/runbooks/plotloom-provider-smoke.md)。
Adapter and host notes are indexed in [docs/README.md](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、依赖和配置状态 |

查看完整参数：

```bash
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、候选审查和选择结果：

```bash
# 为一个 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 默认配置文件是：

```text
~/.plotloom/.env.toml
```

初始化：

```bash
plotloom config init
plotloom config path
```

默认模板会包含：

```toml
[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：

```toml
[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 默认发布可见性 |

配置优先级：

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

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

## 系列 Repo 结构

```text
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。

## 开发

```bash
# 安装开发依赖
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.

plotloom

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README