Blender 剪辑控制 Aoike123/blender-vse

Blender VSE Control

中文文档

Blender VSE Control — 可安全修订的可编辑时间线

让 AI 智能体在 Blender 里剪辑，时间线始终可见、可编辑，控制权在你手里。

Blender VSE Control 是 Blender 视频序列编辑器（VSE）的本地控制层，带类型约束，可安全修订。应用和智能体可以查看、编辑、继续处理并渲染命名的 .blend 时间线，然后验证改动确实保存下来。文件始终是唯一事实来源，人工改动始终受保护。

状态：alpha。主要验证目标是 Blender 5.1。随附的桥接层声明兼容 Blender 4.2+，但官方支持范围只覆盖发行说明里列出的版本。

搭配导演技能

Blender VSE Control 是时间线执行层，不负责创意导演。如果要跑一条自动化工作流，从概念、分镜到素材准备和最终合成，请搭配现成的导演技能或制片编排技能：

- 导演技能负责创意简报、叙事结构、镜头规划、素材需求和验收标准，然后把具体的时间线编辑交给下游。
- Blender VSE Control 把这些编辑应用到指定的 .blend，保护人工修订，按需渲染，并验证保存后的时间线确实持久化。

素材生成、采购和授权仍由上层工作流及其选用的工具负责。产出的 .blend 保持可编辑，人工随时可以介入，控制权不会丢。

安装

Linux 和 macOS：

curl -LsSf https://raw.githubusercontent.com/Aoike123/blender-vse/main/install.sh | sh

Windows（PowerShell）：

powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/Aoike123/blender-vse/main/install.ps1 | iex"

脚本会在缺少 uv 时安装它，然后在 uv 管理的 Python 3.12 上安装 blender-vse-mcp 命令，并检查 Blender 是否存在。把 blender-vse-mcp 注册成宿主里的 stdio MCP 服务器，和其他 MCP 服务器一样，不需要额外配置。

项目始终放在宿主运行目录下的 blender-vse-projects/ 里，工具接收相对于该目录的路径，例如 demo.blend。移动或重命名工作区不会影响使用。

核心保证

- 写入需先观测： 每次补丁都要求提供一次新读取返回的修订号、时间线哈希和一次性观测 ID。
- 不会静默覆盖： 对已变更的时间线打补丁会失败，报 stale_base 错误。
- 原子编辑： 一组命令要么提交为一个修订，要么整体回滚。
- 可见协作： 交互式编辑要求已验证的 GUI 可见性、项目身份，以及对 VSE 时间线和预览的访问权限。
- 持久化证据： 最终验证会重新打开规范的 .blend 在全新的 Blender 进程中运行，并检查已保存的结构事实。它不检查帧，也不判断视觉或创作上的正确性。
- 有界接口面： 调用方从目录中选择操作，永远不能提交自由形式的 Python。
- 有界上下文： 读取默认返回摘要；range/detail 页面只披露选定字段，并携带绑定修订的游标；写入、校验和错误回执同样有字节预算。
- 有界恢复： 压缩胶囊在 4 KB 内保留持久意图和近期证据，用计数和摘要替换更早的历史。

从源码开发

源码贡献者使用 Python 3.10+：

python -m venv .venv
python -m pip install -e ".[dev]"
blender-vse status

要从检出目录连接智能体宿主，安装 .[mcp] 并注册 blender-vse-mcp。参见 本地 MCP 指南。

仓库还包含一个渐进披露的 blender-vse 技能。它定义提示词层面的读取、补丁和恢复纪律，MCP 服务器负责执行。服务器还会把这个技能作为自身指令、一个 blender-vse 提示词以及 blender-vse://skill/... 资源提供出去，所以一行安装也能拿到它。两层都不存储宿主的对话历史。

本地 Codex 安装方面，仓库同时是经过校验的插件根目录，可以构建确定性的本地市场归档。参见插件指南。

创建或读取项目，然后在补丁中使用返回的 revision、timeline_hash 和 observation_id：

blender-vse read ./projects/demo.blend --create
blender-vse patch ./projects/demo.blend \
--base-revision 0 \
--base-timeline-hash HASH_FROM_READ \
--read-token TOKEN_FROM_READ \
--patch-id patch-title-001 \
--commands '[{"op":"add_text","text":"Hello","channel":3,"frame_start":1,"length":90}]'
blender-vse verify ./projects/demo.blend

每次后续补丁之前都要重新读取项目。Python 示例和安装细节参见入门指南。

长时间运行的智能体会话，从 summary 开始，只在需要时请求针对性的 range/detail 读取。仅在明确做旧版调试时使用 --view full。参见上下文模型。

测试配置档

一份清单 tests/test-plan.json 定义所有测试配置档、性能目标和硬超时：

| 配置档 | 用途 | 命令 | 目标 / 超时 |
| fast | 核心单元 + 契约；不启动 MCP/Blender 进程 | python tests/run.py fast | 3 / 10 s |
| coverage | 宿主侧分支覆盖率 | python tests/run.py coverage | 5 / 15 s |
| mcp | 四工具契约 + 一次真实 stdio 发现 | python tests/run.py mcp | 4 / 10 s |
| plugin | 插件声明的精确 stdio 启动 | python tests/run.py plugin | 60 / 180 s |
| harness | 真实 Claude 包校验 | python tests/run.py harness | 60 / 180 s |
| stateful | 场景回放 + 250 轮压缩评测 | python tests/run.py stateful | 5 / 15 s |
| blender-headless | 原生媒体解码 | python tests/run.py blender-headless | 15 / 60 s |
| blender-smoke | 一个公开的多补丁 GUI 工作流，含写后读与持久化验证 | python tests/run.py blender-smoke | 120 / 240 s |
| blender-full | 完整 Blender 回归套件 | python tests/run.py blender-full | 900 / 1200 s |

运行 python tests/run.py list 查看测试计划。详细的安全与 CI 规则见 Testing。

文档

- 文档索引
- 快速上手
- Python 与命令行 API
- 操作目录
- 架构
- 配置
- 上下文模型
- 本地 MCP 服务器
- 智能体技能
- 本地 Codex 插件
- 安装
- 测试
- 安全策略
- 贡献指南
- 发布检查清单

项目边界

本仓库负责 Blender 执行、白名单时间线操作、修订安全与持久化验证。挂载前，它会校验外部生成的代理清单。它不生成媒体，也不获取媒体来源；不下载或转码媒体；不编码或重建代理；不自动化通用 Blender 3D 工作流或任意 bpy 操作；不维护项目级资产数据库；也不提供智能体框架。挂载代理会保留原始源路径，最终渲染仍使用源媒体。

许可证

Blender VSE Control 以 MIT License 发布。内置的 Blender MCP Bridge 仍遵循其自身的 MIT 许可证；见第三方声明。