DeepSeek Harness 插件开发实战：用自然语言检查、修改并渲染 Timeline Studio 视频工程

大模型已经可以理解复杂的视频剪辑需求，但"知道应该怎么剪"和"真正安全地修改视频工程"是两件不同的事情。

如果直接让模型修改工程文件，可能出现字段错误、重复执行、覆盖原文件、访问越界等问题；如果通过鼠标模拟操作编辑器，流程又容易受到界面布局和运行状态影响。

为了解决这个问题，我们开源了一个 DeepSeek Harness 插件：

dsh-timeline-studio-plugin

插件仓库：https://github.com/MartinDelophy/dsh-timeline-studio-plugin
Timeline Studio 主仓库：https://github.com/MartinDelophy/ai-video-editor

它把 DeepSeek Harness 接入 Timeline Studio 的确定性 .timeline 命令层，使智能体能够检查视频工程、预演修改、安全写入新工程，并渲染验证 MP4。

1. 项目解决了什么问题？

这个插件并不是一个新的视频编辑器界面。

它是 DeepSeek Harness 和 Timeline Studio 之间的"智能体操作层"。

两部分的职责分别是：

Timeline Studio：提供可视化时间线、媒体管理、浏览器本地 AI 能力、工程保存和视频创作体验。
dsh-timeline-studio-plugin：把 Timeline Studio 的确定性工程能力封装成 Harness 可以调用的模型工具。

完整流程如下：

text 复制代码

自然语言需求
    ↓
DeepSeek Harness 理解任务
    ↓
检查 Timeline Studio 工程
    ↓
生成结构化编辑计划
    ↓
预演修改 Diff
    ↓
事务式 Apply
    ↓
生成新的 .timeline 工程
    ↓
渲染并验证 MP4

这套设计的重点并不是让模型直接"猜"工程文件应该怎么写，而是让模型调用经过约束的确定性命令。

2. 玩家看到的效果是什么？

首先在 DeepSeek Harness 中添加一个工作区。该目录应当包含 .timeline 工程以及视频、音频、图片等素材。

添加工作区后，可以直接在会话中输入：

检查工作区里的 Timeline Studio 工程，告诉我工程时长、画幅、轨道和素材情况。先不要修改文件。

智能体会调用插件检查工程，而不是直接修改文件。

确认工程信息后，可以继续输入：

把工程改成 9:16。先预演修改，确认没有错误后保存为新工程，再渲染一份 MP4，不要覆盖原文件。

插件没有额外的视频编辑面板。执行过程显示在 Harness 会话中，最终效果则保存在新的 .timeline 工程和视频文件里。

复杂的视频预览、WebGPU AI 能力以及后续手动调整，仍然在 Timeline Studio 编辑器中完成。

3. 如何确认插件加载成功？

进入 DeepSeek Harness：

text 复制代码

设置 → 插件 → 插件列表

搜索 timeline。

如果可以看到：

text 复制代码

配置状态：已启用
Cordis 状态：已挂载

说明插件已经成功加载。

界面中的：

text 复制代码

include:timeline-studio

是插件在当前 Harness 配置中的挂载标识。用户不需要手动执行它，在会话中提出任务即可。

4. 插件提供的 7 个模型工具

项目目前注册了 7 个 Timeline Studio 工具。

工具名称	作用
`timeline_studio_project_inspect`	检查工程版本、时长、画幅、轨道数量和媒体清单
`timeline_studio_track_inspect`	查看指定轨道中的片段
`timeline_studio_clip_inspect`	查看片段时间、素材映射、变换与关联信息
`timeline_studio_transcript_inspect`	检查字幕、词级时间、说话人和音频关联
`timeline_studio_project_diff`	语义预演编辑计划，不写入工程
`timeline_studio_project_apply`	校验后事务式应用编辑计划
`timeline_studio_project_render`	渲染并验证 H.264/AAC MP4

从使用者角度，可以把这些能力分为三部分。

工程理解

智能体可以逐层检查：

text 复制代码

工程
  ├── 轨道
  ├── 片段
  ├── 素材映射
  └── 字幕和音频关联

模型不需要一次读取完整工程，只获取完成当前任务需要的信息。

安全编辑

所有修改先转化为结构化计划，再通过真实命令注册表进行语义预演。

只有预演成功，计划才允许写入。

渲染交付

修改完成后，插件可以调用 Timeline Studio 的本地渲染能力生成 MP4，并检查分辨率、时长、音轨和容器信息。

5. 安装插件

5.1 环境要求

当前已经验证的环境包括：

DeepSeek Harness 0.1.0-rc.6 Developer Preview；
Node.js 22.20+ 或 24+；
已安装依赖的 Timeline Studio 本地仓库；
FFmpeg；
ffprobe。

5.2 通过 GitHub 安装 DSH Bundle

执行：

bash 复制代码

dsh plugin --profile web add \
  "github:MartinDelophy/dsh-timeline-studio-plugin#main"

启动 Harness 时传入 Timeline Studio 和工程工作区路径：

bash 复制代码

TIMELINE_STUDIO_ROOT=/绝对路径/web_player \
TIMELINE_PROJECTS_ROOT=/绝对路径/projects \
dsh --profile web

其中：

text 复制代码

TIMELINE_STUDIO_ROOT

指向 Timeline Studio 主仓库。

text 复制代码

TIMELINE_PROJECTS_ROOT

指向允许插件读取和写入的工程目录。

当没有设置 TIMELINE_STUDIO_ROOT 时，Bundle 默认保持禁用，避免未完成配置的插件影响现有 Harness profile。

5.3 本地插件开发

如果需要调试插件，可以使用 npm link：

bash 复制代码

cd /绝对路径/dsh-timeline-studio-plugin
npm install
npm link

然后进入 DeepSeek Harness：

bash 复制代码

cd /绝对路径/deepseek-harness
npm link dsh-timeline-studio-plugin

也可以手动把插件加入 Harness preset 使用的 Cordis 配置：

yaml 复制代码

- name: 'dsh-timeline-studio-plugin'
  config:
    timelineStudioRoot: /绝对路径/web_player
    allowedRoots:
      - /绝对路径/projects

6. 为什么必须先执行 Diff？

模型生成的 JSON 格式正确，并不代表其中的编辑操作一定能被视频工程正确执行。

例如：

目标片段可能已经被删除；
工程 revision 可能已经发生变化；
操作类型可能不受支持；
输入或输出路径可能超出允许目录；
当前本地渲染器可能无法表达某项效果。

因此，插件把预演和写入拆成两个工具：

text 复制代码

timeline_studio_project_diff
        ↓
timeline_studio_project_apply

一个调整工程画幅的计划如下：

json 复制代码

{
  "schemaVersion": 1,
  "project": "/projects/input.timeline",
  "baseRevision": 0,
  "dryRun": false,
  "operations": [
    {
      "id": "set-ratio-001",
      "type": "project.set_ratio",
      "ratio": "9:16"
    }
  ],
  "output": {
    "project": "/projects/output.timeline"
  }
}

执行 diff 时，插件使用 Timeline Studio 的真实命令注册表检查计划，但不会写入输出工程。

只有 diff 成功，才能执行 apply。

可以把它理解成一次数据库事务：

text 复制代码

生成计划 → 校验计划 → 提交修改

7. 如何避免智能体重复修改工程？

Agent 工具调用可能因为网络问题、取消、重试或任务重新规划而重复执行。

如果没有幂等保护，同一个"添加片段"操作可能被执行两次。

插件使用了两种机制解决这个问题。

7.1 revision 校验

检查工程时，工具会返回当前 revision。

编辑计划必须携带：

json 复制代码

{
  "baseRevision": 0
}

如果工程在此期间已经发生改变，旧 revision 下的新操作会被拒绝，避免使用过期状态覆盖新工程。

7.2 operation ID

每个操作都有唯一 ID：

json 复制代码

{
  "id": "set-ratio-001",
  "type": "project.set_ratio",
  "ratio": "9:16"
}

同一个 operation ID 再次提交时，会被识别为已经执行过的操作，从而避免重复写入。

8. allowedRoots：真正的文件访问边界

视频编辑工具通常需要访问大量本地文件，因此仅靠提示词告诉模型"不要读取其他目录"是不够的。

插件要求配置 allowedRoots：

yaml 复制代码

allowedRoots:
  - /绝对路径/projects

工程、素材、编辑计划和渲染输出，都必须解析到允许的目录中。

如果用户或模型传入：

text 复制代码

/其他目录/private-video.mp4

插件会直接拒绝。

同时，插件还会检查符号链接，避免通过软链接从允许目录跳转到其他文件系统位置。

所以 allowedRoots 是代码强制执行的安全边界，不是一条提示词建议。

9. 渲染请求示例

编辑完成后，可以提交渲染请求：

json 复制代码

{
  "schemaVersion": 1,
  "project": "/projects/output.timeline",
  "output": {
    "video": "/projects/renders/output.mp4"
  },
  "render": {
    "width": 1080,
    "height": 1920,
    "frameRate": 30,
    "crf": 18,
    "preset": "medium"
  }
}

当前便携渲染子集输出 H.264/AAC MP4。

插件会在渲染完成后继续验证：

文件是否真实生成；
视频容器是否正确；
输出尺寸是否符合要求；
视频时长是否合理；
音轨状态是否正常。

如果工程包含当前渲染器无法表达的可见特性，插件会明确返回工具错误，不会在不告知用户的情况下删除效果。

10. 推荐的 Agent 工作流

完整工作流建议保持下面的顺序：

text 复制代码

1. 加载 edit-timeline-studio Agent Skill
2. 检查工程
3. 检查需要处理的轨道、片段或字幕
4. 生成编辑计划
5. 执行 project_diff
6. diff 成功后执行 project_apply
7. 重新检查输出工程
8. 执行 project_render
9. 验证 MP4

其中最重要的原则是：

text 复制代码

Inspect → Plan → Diff → Apply → Inspect → Render

不要跳过 diff，也不要默认覆盖原始工程。

11. 测试与端到端验证

项目不仅测试了单个函数，也对真实 DeepSeek Harness/Cordis 工具链进行了端到端验证。

已经覆盖：

DSH Bundle 安装；
Cordis 自动挂载；
工具注册；
.timeline 工程检查；
diff 只读预演；
apply 事务写入；
revision 校验；
operation ID 幂等；
allowedRoots 文件边界；
符号链接逃逸防护；
取消信号传递；
输出工程重新检查；
MP4 渲染和验证。

开发检查命令：

bash 复制代码

npm run check

真实 Timeline Studio 端到端测试：

bash 复制代码

TIMELINE_STUDIO_ROOT=/绝对路径/web_player \
npm run test:e2e

DeepSeek Harness 当前仍处于 Developer Preview，接口后续可能变化。因此，这个插件把 Harness 相关代码控制在较薄的适配层中，将真正的编辑逻辑继续保留在 Timeline Studio。

12. Timeline Studio 与插件的关系

这里需要再次说明：插件不能替代 Timeline Studio。

Timeline Studio 是完整的视频编辑器，包含：

多轨道时间线；
媒体和素材管理；
字幕与语音能力；
浏览器本地 AI 能力；
视频编辑与预览；
.timeline 工程管理。

dsh-timeline-studio-plugin 则负责：

把确定性工程命令注册为 Harness 工具；
为 Agent 提供编辑工作流规范；
校验工程版本与操作幂等性；
限制文件访问范围；
预演、执行和验证编辑结果。

完整编辑器项目：

https://github.com/MartinDelophy/ai-video-editor

DeepSeek Harness 插件：

https://github.com/MartinDelophy/dsh-timeline-studio-plugin

13. 总结

这次插件实践的核心，不只是"给视频编辑器增加几个 AI 工具"，而是尝试建立一种可控的 Agent 工程执行模式：

text 复制代码

模型负责理解目标和制定计划
程序负责权限、校验和确定性执行
编辑器负责可视化创作和最终调整

当下面这些机制组合起来后：

结构化模型工具；
工程检查；
语义 Diff；
事务式 Apply；
revision 并发保护；
operation ID 幂等；
文件访问边界；
渲染结果验证；

大模型才不再只是告诉用户"这个视频应该怎么剪"，而是能够真正生成一个可以继续打开、检查和调整的视频工程。

项目已经开源，欢迎 Star、提交 Issue 或参与开发。