splicedeck

一个由 AI 代理驱动的视频编辑器，运行在您自己的机器上。

一次调用即可将剪辑套入模板：动态图形、叠加层、字幕以及用于剪辑的节拍网格。对源视频进行一次处理，即可同时获得一个经过清理的长视频母版和竖屏剪辑片段。它还会记住每个客户、频道或节目喜欢的剪辑方式，因此下一次剪辑可以从上一次结束的地方开始。

无需拖拽时间线，无需创建账户。没有任何内容被上传。

状态：流水线端到端运行，记忆已触及剪辑

源视频今天就能变成交付文件。在参考机器（Windows 11, Python 3.13, ffmpeg 8.1.2）上，针对一个真实的 223 MB .mov 文件测得：

inspect   2.6 s     draft  27 ms     splice  27 ms     verify  42 ms
deliver   157 s  ->  1920×1080 h264 + aac, -23.0 LUFS, decodes clean

python -m pytest 报告 1425 通过，2 跳过，耗时约四分钟。 三十一个动词可供 CLI 使用，其中十八个可通过 MCP 服务器使用，两者均从同一个表格生成，因此不会发生偏离。

有一个主要功能尚未实现。通过引用进行剪辑需要一个语音二进制文件，但目前没有任何清单可以获取它。在规划之前，请阅读哪些功能尚不可用。

安装

您需要 Python 3.12 或更高版本，并且 ffmpeg 8.x 已在您的 PATH 中。splicedeck 不会安装也不捆绑 ffmpeg，docs/first-run.md §4 解释了为什么这是有意为之。

安装脚本会询问工作区的位置，在显示确切的命令后提供安装 ffmpeg 的选项，搭建所有内容并写入一个 MCP 配置：

curl -fsSLO https://raw.githubusercontent.com/ihuzaifashoukat/splicedeck/main/install.sh
less install.sh && bash install.sh

irm https://raw.githubusercontent.com/ihuzaifashoukat/splicedeck/main/install.ps1 -OutFile install.ps1
notepad install.ps1; powershell -ExecutionPolicy Bypass -File install.ps1

在运行之前请先阅读它。一个 curl | bash 的一行命令对于这个 README 主要讨论威胁模型的项目来说，将是一个糟糕的广告。

如果您更愿意自己动手，或者想要运行测试：

uv tool install splicedeck                    # or: pipx install splicedeck
git clone https://github.com/ihuzaifashoukat/splicedeck.git && cd splicedeck
python -m venv .venv
.venv/Scripts/python -m pip install -e ".[dev]"   # Windows
.venv/bin/python  -m pip install -e ".[dev]"      # macOS, Linux

尚未在 PyPI 上发布。 没有发布版本，因此 uv tool install splicedeck 在第一个标签被推送之前将返回 404。在此之前，请使用脚本、克隆仓库，或运行 uv tool install "git+https://github.com/ihuzaifashoukat/splicedeck.git"。

docs/install.md 包含了所有安装路径、针对各平台的 ffmpeg 命令、环境变量，以及您可以粘贴到 AI 代理中以便自动安装和配置 splicedeck 的提示。

尝试使用

工作区根目录是您运行命令的目录，spd init 会搭建一个工作区：

mkdir my-edit && cd my-edit
spd init                                      # bookmarks/ casebook/ elements/ ledger/ media/ profiles/ templates/
mkdir -p casebook/parties/demo
spd ready                                     # what is present, and what each gap blocks

init 绝不会覆盖已有文件。在您编辑过配置文件后再次运行它，会填充缺失的内容，并保留您的编辑。它写入的文件与此仓库提供的文件字节完全相同，并且 python -m checks.starter --check 会强制执行这一点。

然后将您的素材放入 media/ 目录并剪辑：

spd inspect --path media/your-file.mov               # mints a source handle
spd draft --party demo --source s1 --bookmark baseline --profile wide-1080
spd apply --sheet c1 --template clean-master         # overlays, motion, beat grid
spd splice --sheet c1 --source a --in_ticks 0 --out_ticks 900000 \
           --source_in_ticks 0 --cause manual
spd verify --sheet c1
spd deliver --sheet c1

源素材必须位于工作区内。任何包含盘符的路径都会在读取之前被拒绝，并返回 PATH_OUTSIDE_WORKSPACE 错误。

项目（party）由人类手动、有目的地创建。draft 在 casebook/parties/<name>/ 目录存在之前会拒绝 UNKNOWN_PARTY 错误。

要通过支持 MCP 的助手驱动它，请注册服务器：

{"mcpServers": {"splicedeck": {
  "command": "C:\\src\\splicedeck\\.venv\\Scripts\\python.exe",
  "args": ["-m", "splicedeck.surface.mcp"],
  "cwd": "C:\\src\\splicedeck"}}}

cwd 必须是工作区，因为工作区根目录就是工作目录，没有其他方式可以发现它。python -m splicedeck.surface.mcp --tools 会打印生成的工具列表并退出，这有助于区分服务器配置错误和主机配置错误。完整的指南请参阅 docs/mcp.md。

模板：一次调用完成外观设计

apply 将命名的模板应用于剪辑表。它会放置叠加层，写入代理随后剪辑所依据的节拍网格，并在剪辑表中记录使用了哪个模板。

今天提供了四个模板：

模板的叠加层在安装了可选的动态层时会播放动画，否则会回退为静态图像。六个动画合成作品位于 scenes/ 中，为本项目编写并随其一起授权。

槽位（slots）是强制执行的。verify 会拒绝包含未填充槽位的剪辑表，并且落在槽位容差范围外的剪辑会被拒绝，返回 SLOT_TOO_TIGHT 错误，同时返回最近的有效边界作为可立即发送的调用。这使代理能够命中它无法看到的节奏。

您可以编写自己的模板。spd compose --kind template 会验证并写入一个手动编写的模板或元素卡片。它特意只通过 CLI 提供：MCP 服务器不得写入 templates/，docs/templates.md §4 解释了这一设计背后的理由，而不是将其视为一个疏忽。

为什么需要记忆

一次编辑由成千上万个细微判断组成，而其中几乎所有的判断都会重复出现。笑点之后停顿多久。这位演讲者的填充词是噪音还是个性。在手臂长度的距离上，手机上的字幕需要多大。无状态工具迫使您在每个会话中重新提供这些上下文，这就是为什么“AI 编辑”常常产生技术上正确但风格上错误的结果。

在这里，您做出一次的决定会被记录并重复使用：

subtitle.size_px = 74
  when {surface: vertical, frame: 1080x1920}
  set by  a render you shipped and kept, 2026-08-02
  before  66

该记录存在于您的仓库中，作为可审阅的文本。您可以查看差异，通过编辑一行来纠正错误条目，并使用 git revert 回滚使编辑变得更糟的更改。它是一个行为变更日志，与您版本控制的所有其他内容保存在同一位置。

两条规则确保其可信：

• 没有任何持久性内容是由模型写入的。记录描述了人类所做的行为：交付了一个渲染并保留它，恢复了剪辑移除的某个时刻。代理可以指向发生了什么；但它不能编写被记住的内容。

• 每次写入都经过人工审核。没有偏好设置会被静默学习。

该循环今天即可运行。spd set、ship、keep、restore 和 discard 将行为追加到项目的哈希链式账本中，并从每个行为中提出一个建议；行为不能追加到未经验证的链上。然后 spd review 会盲求值，显示边界和已交付的剪辑，但从不显示具体数字，匹配的答案会成为一个密封案例和一个重新生成的 findings.lock.txt。下一次 draft 会据此解析：书签打开设置，案例簿覆盖人类已确定的内容，剪辑表记录它读取了哪个锁文件。

本地优先且完整

一个全新的克隆，没有任何 API 密钥和云账户，就能在您自己的机器上生成一个完整的、可交付的文件。这是基准，而不是降级模式。

云服务可以在它们真正有帮助的地方开启，例如针对困难音频或说话人分离的托管语音 API，但没有任何服务成为必需，也没有任何交付依赖于此。ffmpeg 作为子进程完成工作。它从未被供应商化或链接。

该项目还拒绝猜测您的硬件配置。编码器支持通过测试编码来验证，而不是通过读取功能列表，因为功能列表可能会说谎。在开发机器上，ffmpeg -encoders 宣传了一个 NVIDIA 编码器，但该编码器在运行时失败，而实际能工作的 Intel 编码器却在所有指南中未被提及。

已实现的功能

• 一次分析处理，两个交付物。 转录和分析每个源视频只运行一次。长视频母版和竖屏剪辑片段都读取相同的结果。

• 帧精确剪辑，无音频漂移。 音频在复用前保持 PCM 格式，并仅编码一次。交付的样本与在 Python 中通过 45 次和 120 次连接构建的参考组合字节完全相同。经测量验证，而非断言。

• 一次调用完成模板和动态效果，带有代理剪辑所依据的节拍网格，以及在缺少动态层时的静态回退。

• 字幕保持可读性。 渲染器强制执行大小和对比度下限，并且会拒绝绘制位于平台自身界面下方的文本，而不是绘制它。字形由纯标准库的 TrueType 解析器进行形状处理和栅格化，因此印记是字节可重复的，并作为黄金标准提交。

• 承认不确定性的竖屏构图。 当无法自信地跟踪主体时，它会拒绝自动构图并说明原因。自信的错误裁剪比诚实的拒绝更糟糕，因为没有人会审查看起来还不错的裁剪。

• 经得起考验的版权。 音乐、特效和库存素材都带有记录，说明其来源及许可条款。如果任何资产缺少此类记录，交付将拒绝运行。

• 携带自身修正的键入式拒绝。 拒绝会附带 retry_with，这是一个可立即发送的调用列表。共有 102 个错误代码，每个代码都有对应的构建位置和证明其可达性的测试。

哪些功能尚不可用

明确说明，因为如果状态部分省略了这一点，那么它就是上一个版本毫无价值的原因。

CHANGELOG.md 包含相同的列表，并且两者应保持同步。

模型层以下的两个层级是有效的。subject: "centre" 是几何的，不需要任何东西。SPD_SIGHT_LOCATOR=reduce 选择一个无权重定位器，通过纯标准库 Python 中的时间中值背景减法来查找主体，无需 numpy 或任何编译扩展。

在参考母版上与人脸检测器进行对比检查，该定位器的中值与帧宽度相差在 0.1% 以内。在相同的素材上，它随后报告置信度为 0.26，并且根本没有拟合任何路径，因为一个在静态背景下几乎不移动的说话者不会给背景减法留下任何可依赖的信息。这两个结果都是正确的答案：算术是正确的，并且无权重层的诚实限制是一个空洞，而不是一个居中的猜测（docs/framing.md §7）。带有移动主体的素材跟踪效果良好。

如何驱动它

通过一个 MCP 服务器和技能（Skills），任何支持 MCP 的助手都可以使用它，此外还有一个 CLI 暴露完全相同的动词。两个界面都由 splicedeck/surface/verbs.py 生成，如果它们发生偏离，python -m checks.golden --check 会使构建失败。

该服务器支持五个协议修订版本，从 2024-11-05 到 2026-07-28，并响应 initialize 握手和 server/discover。

失败是有类型的。拒绝会附带其自身的修正，以可直接发送的调用形式呈现，而非需要智能体去解读的散文，因此恢复只需一个回合：

{"ok": false, "verb": "draft", "refused": "BOOKMARK_UNKNOWN",
 "plain": "No bookmark by that name is shipped.",
 "needs_human": false,
 "retry_with": [{"verb": "draft", "args": {"bookmark": "baseline", "party": "demo",
   "profile": "wide-1080", "situation": "default", "source": "s1"}}]}

技能

四项技能教会智能体动词顺序、动词之间的陷阱，以及如何将拒绝转化为下一个正确的调用。它们位于 .claude/skills/ 中，克隆后无需任何安装即可直接使用。

此仓库也是一个 Claude Code 插件及其自身的市场：

claude plugin marketplace add ihuzaifashoukat/splicedeck
claude plugin install splicedeck@splicedeck

或者将技能安装到 skills CLI 支持的任何智能体中，包括 Codex、Cursor、OpenCode、Antigravity、Cline、Gemini CLI、Zed 和 Windsurf：

npx skills add ihuzaifashoukat/splicedeck            # add --list to look first

两种方式都仅分发技能。它们不会注册 MCP 服务器，因为服务器需要绝对的解释器路径和 cwd，而插件和技能安装程序都无法获知这些信息。install.sh 会为你写入这些信息，docs/mcp.md 中也有手动操作说明。

所有其他智能体运行时请阅读 AGENTS.md。

设计

规范先于代码编写，这是有意为之。

智能体中的持久记忆是一个安全面，而不仅仅是一个功能。攻击者写入其中的任何内容都会比植入它的对话存活得更久。如果你只读一份文档，请阅读 docs/security.md。

非目标

从多个源组装影片。生成视频或音乐。时间线 GUI。实时协作。托管服务。自动选择哪些时刻成为片段，因为它会呈现候选片段并等待人工确认。

要求

Python 3.12 或更新版本，以及 PATH 上的 ffmpeg 8.x。任何默认路径上均未使用编译的 Python 扩展，因此无需构建步骤，也无需先安装平台运行时。支持 Windows、macOS 和 Linux；CI 覆盖 Ubuntu 和 Windows，macOS 未经机器测试。

运动层级额外需要 Node 和在 scenes/ 内执行 npm install。这是可选的，没有它则交付会回退到静态印记。

贡献

欢迎提交问题和设计评审。CONTRIBUTING.md 是入口：设置、需要运行的检查、如何添加动词或拒绝代码，以及无论价值如何都会被拒绝的拉取请求。请先阅读 AGENTS.md。十二条硬性规则是承重结构，违反其中任何一条的更改将仅因此被拒绝。

参与即表示你同意行为准则。

安全

请不要为漏洞公开提交 issue。SECURITY.md 中提供了报告路径和范围。

许可证

Apache-2.0。版权所有 2026 Huzaifa Shoukat。