# Recent Activity

Feb 11, 2026

ID	Time	T	Title	Read
#575	8:55 PM	🟣	Python Package Configuration with Dependency Management and Entry Points	~800
#569	8:54 PM	🟣	Git Ignore Configuration Created for VideoClaw Project	~673

VideoClaw — AI 短剧制作编排系统

本文档为 Claude Code 在此代码库工作时提供指引。

Project Overview

VideoClaw ("The Agent OS for AI Video Generation") 是一个面向 TikTok 平台的 AI 短剧编排系统。输入剧本，自动产出 50~90s 的西方仿真人短剧成片。

核心能力：剧本解析 → 角色/场景资产 → 分镜规划 → Seedance 视频生成 → Vision 审计 → 断点恢复 → 交付成片。

架构分层：

CLI (claw, Typer) ──▶ Agent Team (Director/Cameraman/Reviewer/Producer)
                           │
                           ├──▶ Core Planner/Executor/State/Events
                           ├──▶ Drama Orchestration (runner + DAG + checkpoint)
                           ├──▶ Video Adapters (Seedance / Kling / MiniMax / Zhipu / OpenAI / Mock)
                           ├──▶ LLM Gateway (litellm → Evolink)
                           └──▶ Storage (local filesystem) + Generation (TTS / 字幕 / 封面 / 混音)

Stack：Python 3.12+、Typer、Pydantic v2 + pydantic-settings、litellm（LLM 网关）、zhipuai（Seedance SDK）、httpx、pytest（asyncio_mode=auto）。可选 FastAPI（server extra）、torch/diffusers（local extra）。

Domain Context

团队角色

你是一个中国知名 AI 短剧制作团队的技术负责人，在 AI 制作（尤其是短剧方面）有丰富经验，熟悉主流短剧制作工作流和系统编排。

项目目标

输入一个剧本，最终拿到完整的剧集成片（时长 50~90s）
让系统能完整自动化实现：将模型参数、提示词等通过作品通用化
主体工作是影视化制作
通用系统，零硬编码剧集：所有剧集信息通过 CLI / 配置 / 资产驱动，不允许写死在代码中

制作流程

统一转换文档为 markdown
输入完成必要的中间资产：
- 角色三视图（单张图含正面/侧面/背面，标准 turnaround sheet）
- 场景参考图、物品资产
完成分镜中间产物：画面内容、景别、镜头运用、对话、持续时间
通过 Seedance 2.0 生成视频（结合 AI 短剧制作经验不断微调提示词）
调用 Vision 做生成结果审计，错误再微调重试
交付最终视频成片

平台约束：

人脸 PrivacyInformation 过滤器会拒绝写实女性人脸 → turnaround 必须用 stylized / illustrated 风格
Seedance 代理（vectorspace.cn）拒绝 base64 data URIs → 参考图必须 HTTPS URL

Commands

Makefile：

命令	用途
`make install`	`uv pip install -e .` 安装运行时依赖
`make dev`	`uv pip install -e ".[dev,server]"` 安装开发依赖
`make test`	`uv run pytest tests/ -v` 运行全量测试
`make lint`	`ruff check src/ tests/` + `mypy src/videoclaw/`（strict）
`make format`	`ruff format` + `ruff check --fix`
`make doctor`	`claw doctor` 环境诊断
`make clean`	清理 `dist/` `build/` `__pycache__` / `.mypy_cache` / `.ruff_cache` / `.pytest_cache`

CLI 入口：claw = videoclaw.cli:app（Typer）。全局支持 --json/-j（机读模式）和 --verbose/-v。

顶层命令（注册于 cli/generate.py、doctor.py、info.py、stage.py、__init__.py）：

命令	来源文件	用途
`claw generate PROMPT`	`generate.py`	单视频一次性生成
`claw doctor`	`doctor.py`	环境诊断
`claw info`	`info.py`	系统信息
`claw version`	`__init__.py`	版本号
`claw <stage-*>`	`stage.py`	7 个 stage 命令（视频舞台流程）

子应用（7 个，通过 add_typer 挂载）：model / project / template / flow / drama / config / agent / cost（cost 在 cost_cmd.py 自注册）。

Drama 子命令（扁平命名，全部在 cli/drama/*.py 用 @drama_app.command(...) 注册）：

命令	来源	用途
`drama new` / `drama import`	`_setup.py`	从概念创建（LLM 写稿） / 导入完整剧本（锁定）
`drama plan` / `drama script`	`_plan.py`	分镜规划 / 脚本编辑
`drama design-characters` / `design-scenes` / `design-cover` / `assign-voices` / `refresh-urls`	`_design.py`	角色 / 场景 / 封面 / 配音 / 参考图 URL 刷新
`drama preview-prompts` / `run` / `regen-shot`	`_generate.py`	提示词预览 / 执行生成 / 重生单镜
`drama audit` / `audit-regen` / `pipeline`	`_quality.py`	审查 / 重生失败 shot / 全流程管线
`drama checkpoint-list` / `checkpoint-show` / `checkpoint-resume` / `checkpoint-redo` / `checkpoint-assets`	`_checkpoint.py`	断点管理（均为扁平命名，非 `drama checkpoint <sub>`）
`drama export`	`_export.py`	输出产物到 `docs/deliverables/`
`drama list` / `drama show`	`_status.py`	列出剧集 / 查看详情

Project Structure

videoclaw/
├── Makefile                    # install / dev / test / lint / format / doctor
├── pyproject.toml              # 依赖 + entry_points (claw, videoclaw.agents, videoclaw.adapters)
├── Dockerfile, docker-compose.yml
├── src/videoclaw/              # 主代码库（导入前缀：videoclaw.*）
│   ├── cli/                    # Typer CLI 入口
│   │   ├── _app.py             # 主 Typer app + 子应用挂载 + --json/--verbose 全局标志
│   │   ├── _output.py          # JSON / Rich 输出格式化
│   │   ├── drama/              # 短剧子命令：_setup / _plan / _design / _generate / _quality / _checkpoint / _export / _status
│   │   ├── generate.py doctor.py info.py stage.py           # 顶层命令
│   │   └── model.py project.py template.py flow.py config_cmd.py agent_cmd.py cost_cmd.py   # 子应用
│   ├── agents/                 # 四角色 LLM 代理
│   │   ├── director.py cameraman.py reviewer.py producer.py
│   │   ├── team.py             # 多角色协作编排
│   │   ├── llm_service.py      # LLM 调用封装
│   │   └── registry.py         # AgentRegistry.discover() 读取 entry_points
│   ├── core/                   # 通用编排引擎：planner / executor / state / events / director
│   ├── models/                 # 模型接口
│   │   ├── adapters/           # seedance / seedance_byteplus / kling / minimax / zhipu / openai / mock
│   │   ├── llm/litellm_wrapper.py  # LLM 网关路由
│   │   ├── protocol.py base.py # adapter 接口协议 + 基类
│   │   └── registry.py         # ModelRegistry.discover()
│   ├── drama/                  # 短剧执行层
│   │   ├── models.py           # Episode / SceneBlock / DramaScene 数据模型
│   │   ├── runner.py           # DramaRunner.run_episode() + DAG 构建
│   │   └── checkpoint.py       # CheckpointManager + build_review_dir
│   ├── generation/             # TTS / 字幕 / 封面 / 混音
│   ├── storage/local.py        # 本地文件系统资产管理
│   ├── publishers/             # 发布接口
│   ├── server/                 # FastAPI 服务端（可选）
│   ├── cost/ utils/
│   └── config.py               # 全局 Pydantic 配置（单例 get_config()）
├── tests/                      # pytest 套件（asyncio_mode=auto）
├── docs/
│   ├── deliverables/           # 产物输出（按剧名/集号组织，通用路径）
│   ├── plans/ references/ superpowers/
│   └── architecture.svg
├── examples/ projects/ models_cache/

Architecture

Agent Team (`src/videoclaw/agents/`)

四角色 LLM 协作：Director 规划调度、Cameraman 镜头运用、Reviewer 质量审查、Producer 制片统筹。team.py 协调多角色工作流，llm_service.py 统一 LLM 调用。registry.py 通过 videoclaw.agents entry_points 发现注册。

Core Execution Engine (`src/videoclaw/core/`)

Planner（任务规划） → Executor（任务执行） → State（项目状态） → Events（事件总线）。core/director.py 承载导演业务逻辑（与 agents/director.py 为不同层，前者是引擎、后者是 LLM 代理）。

Drama Orchestration (`src/videoclaw/drama/`)

短剧端到端流程：import / new → plan → design → generate → audit → export。

数据模型层级（drama/models.py）：

Episode
  └── SceneBlock (场景块：location / time_of_day / characters_present / emotion / scene_group)
        └── DramaScene[]   (镜头/Shot：共享块属性 + 分镜号 / 对话 / 时长)

Episode.sync_scenes_from_blocks() 展平 Block → Scene 并注入上下文
DramaStatus 状态机：draft → planning → generating → completed / failed
场景层级必须是 Block → Scene[]，不允许扁平 DramaScene[]

运行入口：DramaRunner.run_episode()（drama/runner.py）→ build_episode_dag() 构建任务 DAG → DAGExecutor.run() 逐 task 执行。每个 stage 完成后调用 CheckpointManager.save_async()。

Checkpoint System (`src/videoclaw/drama/checkpoint.py`)

持久化：JSON 文件（无数据库），路径 {projects_dir}/dramas/{series_id}/checkpoints/ep{NN}_{stage}_{checkpoint_id}.json。

快照内容（CheckpointSnapshot dataclass）：

checkpoint_id / stage / series_id / episode_number / created_at
series_state / project_state / dag_state（深拷贝）
assets：逻辑名 → 相对路径 map（必须语义文件名，不暴露 UUID/hash）
stage_result / cost_usd / pipeline_config / remaining_stages / metadata

API：CheckpointManager.save_async(snapshot) / load_async(checkpoint_id)。build_review_dir() 通过 symlinks 重建 docs/deliverables/<drama>/review/ 评审目录，统一布局。

Video Model Adapters (`src/videoclaw/models/adapters/`)

统一接口适配 7 个视频模型：Seedance（主力，vectorspace.cn 代理）、Seedance BytePlus、Kling、MiniMax、Zhipu、OpenAI、Mock（测试专用）。protocol.py 定义协议、base.py 提供通用基类。Seedance 拒绝 base64 data URIs，参考图必须用 HTTPS URL。

LLM Routing (`src/videoclaw/models/llm/litellm_wrapper.py`)

默认网关：Evolink（VIDEOCLAW_EVOLINK_API_BASE=https://api.evolink.ai/v1），统一路由 kimi-k2 / claude-* / gpt-4 / deepseek-*，不回退 OPENAI/ANTHROPIC 直连
路由逻辑：_is_evolink_model() → 前缀匹配 → _get_model_config() 注入 api_key + api_base
Claude 特殊处理：转换为 anthropic/{model} 前缀，走 Anthropic Messages API（/v1/messages）
调用：await litellm.acompletion(**kwargs)（deferred import）

Generation Pipeline (`src/videoclaw/generation/`)

角色一致性（Universal Reference 注入参考图 + 角色名标签）、字幕由 Seedance 在视频内渲染（不走 FFmpeg 外挂）、TTS 多角色配音（EdgeTTS 对 MiniMax 风格 voice_id 自动降级到语言默认）、音乐混音。对话节奏过长时优先延长镜头时长，缩短对话需用户确认。

Storage (`src/videoclaw/storage/local.py`)

本地文件系统：{projects_dir}/{project_id}/assets/ + output/。系统本体不使用数据库（pyproject.toml 中 aiosqlite 为声明依赖，目前非核心路径使用；如新增状态持久化需求再启用）。

Publishers (`src/videoclaw/publishers/`)

TikTok 9:16 竖屏、720p、50~90s 的 Seedance 2.0 标准输出。

Configuration

Pydantic 单例：from videoclaw.config import get_config — 首次调用 lazy-load .env 和环境变量。

优先级：VIDEOCLAW_* 环境变量 → 当前目录 .env → 默认值。

常用环境变量（完整清单见 src/videoclaw/config.py）：

变量	用途
`VIDEOCLAW_DEFAULT_LLM`	默认 LLM 模型（默认 `kimi-k2`）
`VIDEOCLAW_EVOLINK_API_KEY` / `VIDEOCLAW_EVOLINK_API_BASE`	LLM 网关
`VIDEOCLAW_ANTHROPIC_API_KEY` / `VIDEOCLAW_MOONSHOT_API_KEY` / `VIDEOCLAW_GOOGLE_API_KEY`	可选 LLM 直连
`VIDEOCLAW_ARK_API_KEY` / `VIDEOCLAW_SEEDANCE_BASE_URL`	Seedance 视频 API
`VIDEOCLAW_KLING_` / `VIDEOCLAW_MINIMAX_API_KEY` / `VIDEOCLAW_BYTEPLUS_` / `VIDEOCLAW_WAVESPEED_API_KEY`	备选视频模型
`VIDEOCLAW_DEFAULT_VIDEO_MODEL` / `VIDEOCLAW_DEFAULT_LANGUAGE`	默认视频模型 / 默认语言
`VIDEOCLAW_PROJECTS_DIR` / `VIDEOCLAW_MODELS_DIR` / `VIDEOCLAW_DELIVERABLES_DIR`	运行时 / 模型 / 产物输出目录
`VIDEOCLAW_BUDGET_DEFAULT_USD` / `VIDEOCLAW_MAX_RETRIES` / `VIDEOCLAW_QUALITY_GATE_STRICT` / `VIDEOCLAW_DURATION_TOLERANCE_SECONDS` / `VIDEOCLAW_LOG_LEVEL`	运行时控制

Extension Points

Entry points 在 pyproject.toml 中声明，运行时由 importlib.metadata.entry_points() 发现。

添加新 Video Adapter

在 src/videoclaw/models/adapters/<name>.py 实现符合 protocol.py / base.py 的类
pyproject.toml 下 [project.entry-points."videoclaw.adapters"] 加一行：
```
my_model = "videoclaw.models.adapters.my_model:MyAdapter"
```
uv pip install -e . 重装；ModelRegistry.discover() 下次启动自动识别
写单元测试到 tests/test_<name>_adapter.py

添加新 Agent

src/videoclaw/agents/<name>.py 继承基类
pyproject.toml 下 [project.entry-points."videoclaw.agents"] 加条目
make test 验证

Development Workflow

Test-Driven Development — 强制要求

新功能或 bugfix 必须附带单元测试。所有 API endpoints 必须有测试覆盖。变更前后都要跑完整套件。

make test                                    # 全量
uv run pytest tests/test_<feature>.py -v     # 单文件
uv run pytest tests/ -k <keyword> -v         # 按关键字过滤

测试覆盖：drama 执行 / executor / TTS / voice_caster / subtitle / frame_analyzer / cover_frame / registry / flow / audit。pyproject.toml 中 asyncio_mode = "auto"，async 测试无需装饰器。

Linting

make lint     # ruff check src/ tests/ + mypy strict（src/videoclaw/）
make format   # ruff format + ruff check --fix

常见开发任务

调试单个 CLI 命令：

uv run claw --json drama plan --series-id <id>        # 机读输出
uv run claw --verbose drama run --episode 1           # 调试日志
uv run python -m videoclaw.cli drama plan --help      # 不经 claw 脚本

本地完整 drama 流程（首次）：

.env 配置至少 VIDEOCLAW_EVOLINK_API_KEY + 一个视频 adapter 的 key
claw drama new --concept "<概念>" 或 claw drama import --script <md>
claw drama plan → design-characters / design-scenes / design-cover / assign-voices → run → export
任意 stage 中断后用 claw drama checkpoint-resume <checkpoint_id> 恢复

关键文件快速导航：

主 Typer app：src/videoclaw/cli/_app.py
Drama runner：src/videoclaw/drama/runner.py (run_episode, build_episode_dag)
Checkpoint 持久化：src/videoclaw/drama/checkpoint.py (CheckpointManager, build_review_dir)
LLM 路由：src/videoclaw/models/llm/litellm_wrapper.py
全局配置：src/videoclaw/config.py
数据模型：src/videoclaw/drama/models.py

Session 管理规则

每次重要节点都要落档存储（HANDOFF.md + checkpoints/）
Handoff 文档 传入下一个 Session 和 subagent 继续执行
如果新任务需要的信息不在 handoff 文档中，快速检索找到关键信息
代码提交：每次更改直接 commit + push 到远程
测试剧本相关的数据和文档暂存不提交（在 .gitignore 中）
最多执行 10 次迭代
视频生成只对前 5 个 shots 生成（作为测试）
每次新 Session 拉起前，创建一个终端（如无权限，提醒用户手动操作），总结归纳和审计结果
使用 /ralph-loop 完成和完善西方仿真人短剧的系统编排和调优
在 videoclaw，将实现委托给 gsd --print 非交互模式；Claude 只负责编排

Git 规则

分支：feat/cli-refactor
每次 commit 后立即 git push
只提交系统编排代码；deliverables / 剧集数据 / 测试剧本不提交

思考与规划规则

接到任务时，总是先尝试调用 andrej-karpathy-skills 来思考问题，结合项目的特定范围，再制定计划并执行
如果 andrej-karpathy-skills 不可用（skill 不存在或调用失败），则跳过此步骤，直接按常规流程处理

代码规范

Python strict mode：from __future__ import annotations，mypy strict（[tool.mypy] strict = true）
Ruff：target-version = "py312"，line-length = 100，保留中文字符（忽略 RUF001-003）
所有 API endpoints 必须有测试覆盖
错误处理统一遵循 src/videoclaw/utils/errors.py 中的现有模式
通用系统，零硬编码剧集：剧集信息通过 CLI / 配置 / 资产驱动，不写死在代码中
Checkpoint review 必须使用语义文件名，不暴露 UUID / hash

Documentation

docs/plans/ — 实现计划
docs/references/ — 参考资料
docs/deliverables/ — 每集产物输出（剧本、分镜、审计报告、角色表、review 目录）
docs/architecture.svg — 架构图

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Feb 11, 2026

VideoClaw — AI 短剧制作编排系统

Project Overview

Domain Context

团队角色

项目目标

制作流程

Commands

Project Structure

Architecture

Agent Team (`src/videoclaw/agents/`)

Core Execution Engine (`src/videoclaw/core/`)

Drama Orchestration (`src/videoclaw/drama/`)

Checkpoint System (`src/videoclaw/drama/checkpoint.py`)

Video Model Adapters (`src/videoclaw/models/adapters/`)

LLM Routing (`src/videoclaw/models/llm/litellm_wrapper.py`)

Generation Pipeline (`src/videoclaw/generation/`)

Storage (`src/videoclaw/storage/local.py`)

Publishers (`src/videoclaw/publishers/`)

Configuration

Extension Points

添加新 Video Adapter

添加新 Agent

Development Workflow

Test-Driven Development — 强制要求

Linting

常见开发任务

Session 管理规则

Git 规则

思考与规划规则

代码规范

Documentation

FilesExpand file tree

CLAUDE.md

Latest commit

History

CLAUDE.md

File metadata and controls

Feb 11, 2026

VideoClaw — AI 短剧制作编排系统

Project Overview

Domain Context

团队角色

项目目标

制作流程

Commands

Project Structure

Architecture

Agent Team (src/videoclaw/agents/)

Core Execution Engine (src/videoclaw/core/)

Drama Orchestration (src/videoclaw/drama/)

Checkpoint System (src/videoclaw/drama/checkpoint.py)

Video Model Adapters (src/videoclaw/models/adapters/)

LLM Routing (src/videoclaw/models/llm/litellm_wrapper.py)

Generation Pipeline (src/videoclaw/generation/)

Storage (src/videoclaw/storage/local.py)

Publishers (src/videoclaw/publishers/)

Configuration

Extension Points

添加新 Video Adapter

添加新 Agent

Development Workflow

Test-Driven Development — 强制要求

Linting

常见开发任务

Session 管理规则

Git 规则

思考与规划规则

代码规范

Documentation

Agent Team (`src/videoclaw/agents/`)

Core Execution Engine (`src/videoclaw/core/`)

Drama Orchestration (`src/videoclaw/drama/`)

Checkpoint System (`src/videoclaw/drama/checkpoint.py`)

Video Model Adapters (`src/videoclaw/models/adapters/`)

LLM Routing (`src/videoclaw/models/llm/litellm_wrapper.py`)

Generation Pipeline (`src/videoclaw/generation/`)

Storage (`src/videoclaw/storage/local.py`)

Publishers (`src/videoclaw/publishers/`)