Aoike123/blender-vse

Blender VSE Control

中文文档

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

让 AI 智能体在 Blender 中编辑，同时时间线保持可见、可编辑，
并由你掌控。

Blender VSE Control 是 Blender 视频序列编辑器（VSE）的本地、类型化、修订安全的控制层。应用程序和智能体可以检查、编辑、继续处理并渲染命名的 .blend 时间线，然后验证其更改是否持久化。文件仍然是唯一事实来源，人工更改仍然受到保护。

状态：alpha。Blender 5.1 是主要验证目标。捆绑的桥接声明兼容 Blender 4.2+，但官方支持声明仅涵盖发行说明中列出的版本。

与导演 Skill 配对

Blender VSE Control 是时间线执行层，而不是创意导演。对于从概念和故事板到源媒体准备和最终组装的自动化工作流，请将其与可用的导演或制作编排 Skill 配对：

- 导演 Skill 负责创意简报、叙事结构、镜头计划、资产需求和验收标准，然后委派具体的时间线编辑。
- Blender VSE Control 将这些编辑应用到命名的 .blend，保护人工修订，在请求时渲染，并验证保存的时间线是否持久化。

媒体生成、获取和许可仍由上层工作流及其所选工具负责。生成的 .blend 保持可编辑，因此人工可以在不放弃控制权的情况下介入。

从 GitHub 安装

将仓库链接发送给 Codex、Claude Code 或 DeepSeek Harness (DSH)，并要求它安装插件：

Install this plugin: https://github.com/Aoike123/blender-vse-control

这就是预期的安装流程。在复制 Skill 和 MCP 集成后，安装智能体必须询问在哪里存储可编辑的 .blend 项目，并获取绝对目录路径。在用户确认目录并将其作为 BLENDER_VSE_PROJECTS_DIR 提供之前，安装不会达到 ready 状态。推荐位置是 /blender-vse-projects。如果没有工作区或用户选择外部目录，智能体必须清楚解释其影响并请求确认。

安装指南涵盖了通过 Codex 市场、Claude 市场和 DSH Skill/Cordis 进行安装，以及配置和验证。用户不应需要手动编辑客户端清单。

核心保证

- 可观察写入： 每个补丁都需要新读取返回的修订、时间线哈希和一次性观察 ID。
- 无静默覆盖： 对已更改的时间线打补丁会失败并返回 stale_base 错误。
- 原子编辑： 命令列表提交一个修订或回滚。
- 可见协作： 交互式编辑需要经过验证的 GUI 可见性、项目身份，以及对 VSE 时间线和预览的访问权限。
- 持久化证据： 最终验证会在全新的 Blender 进程中重新打开规范 .blend 文件，并检查已保存的结构性事实。它不会检查帧，也不会评判视觉或创意方面的正确性。
- 有界表面： 调用方从目录中选择操作；他们永远无法提交自由形式的 Python。
- 有界上下文： 读取默认返回摘要；范围/详情页面仅披露选定的字段，并携带绑定修订版本的游标；写入、验证和错误回执也有字节预算。
- 有界恢复： 压缩胶囊将持久意图和近期证据保持在 4 KB 以内，用计数和摘要替换较旧的历史记录。

安装并试用

最终用户无需预装 Python。如果缺少 uv，安装 Agent 会在引导安装它之前请求许可；随后 uv 会配置一个受管理的 Python 3.12 运行时。Blender 需单独安装。仅当代理或媒体夹具功能需要时，安装程序才会引导用户完成 FFmpeg 设置。源码贡献者仍使用 Python 3.10+。

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

要连接 Agent 主机，请安装 .[mcp]，授权项目根目录，并配置主机以启动 blender-vse-mcp。请参阅本地 MCP 指南。

该仓库还包含一个渐进式披露的
blender-vse Skill。它定义了提示词层面的读取、补丁和恢复纪律，而 MCP 服务器负责执行。这两层都不存储主机的对话历史。

对于本地 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 示例和设置细节，请参阅入门指南。

对于长时间运行的 Agent 会话，请从 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 + DSH 包/配置验证 | 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 和 CLI API
- 操作目录
- 架构
- 配置
- 上下文模型
- 本地 MCP 服务器
- Agent Skill
- 本地 Codex 插件
- Codex、Claude Code 和 DSH 安装
- 客户端兼容性
- 测试
- 安全策略
- 贡献指南
- 发布检查清单

项目边界

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

许可证

Blender VSE Control 是自由软件，采用
GNU Affero 通用公共许可证 v3.0。内置的 Blender MCP
Bridge 仍为 MIT 许可；参见 第三方声明。