做长视频剪辑时，我们经常需要记住一些具体位置：这一秒进入新章节，这个节拍适合切镜头，这段采访需要复查，结尾还要补一个修改意见。
这些信息如果只留在聊天记录里，后续就需要不断对照时间、寻找片段。换一个人接手，或者让 AI Agent 继续处理项目，沟通成本会进一步增加。
最近，我给自己维护的开源项目 Timeline Studio 增加了完整的时间线标记能力，并将它接入 CLI、MCP 和 Agent Skill。人可以在浏览器里拖动标记，Agent 也可以通过结构化命令读取和修改同一份项目数据。
这篇文章分享其中的数据建模、吸附交互、命令架构，以及实现过程中遇到的几个边界问题。
想先看看实际效果，可以直接打开 Timeline Studio 在线编辑器。完整源码在 GitHub 仓库，下面的实现可以结合代码一起阅读。
Timeline Studio 是一个使用 React 和 Vite 构建的本地优先浏览器视频编辑器。这次新增的标记支持四种类型：
| 类型 | 适用场景 |
|---|---|
| Marker | 音乐节拍、动作发生点、镜头切换提示 |
| Chapter | 长视频章节、课程小节、访谈主题 |
| Range | 待复查片段、需要重点处理的时间区间 |
| Note | 修改意见、剪辑理由、待确认事项 |
四种类型使用统一的数据模型。例如，一个待复查区间可以保存为：
{
"id": "review-product",
"type": "range",
"time": 5,
"endTime": 8,
"title": "产品展示",
"notes": "检查这一段的字幕与画面是否同步",
"color": "violet"
}
其中，时间统一使用项目时间轴上的秒数，区间才需要 endTime。标题和备注支持 Unicode，可以直接保存中文。
这里有一个影响后续架构的重要决定：标记作为项目注释保存，不参与媒体时长计算。
例如，项目里的视频只有 60 秒，即使在 90 秒处添加一个规划标记，也不应该把导出视频延长到 90 秒。章节标记同样不会自动变成画面中的标题或 MP4 容器章节。
这样，Agent 只需要整理章节或添加修改意见时，可以直接输出新的 .timeline 项目，无需重新编码一段内容没有变化的视频。
浏览器界面也围绕这个使用方式做了调整。
最初，将所有标记放在单独一行里，虽然信息完整，却会持续占用时间线高度。尤其是笔记本屏幕，多一行辅助信息，就意味着少一部分素材轨道。
现在默认将标记折叠成刻度轴上的紧凑旗标。需要查看标题和区间时，点击工具栏旁的展开按钮，再显示独立标记行。按 M 可以在播放头位置快速添加标记，按 Shift + M 打开管理面板。
这个设计让快速定位和详细编辑分别使用合适的信息密度。
拖动体验中，另一个关键点是吸附。
如果标记只是跟随鼠标自由移动，用户很难准确地对齐镜头边界。因此，我让标记复用时间线已有的吸附机制，对齐播放头、素材边界以及其他标记，并显示共同的对齐辅助线。按住 Alt 可以临时绕过吸附。
吸附阈值使用屏幕距离定义，再换算成时间：
const thresholdSeconds =
10 / railWidth * timelineDuration;
这里的 railWidth 是当前时间轨道的像素宽度，timelineDuration 是它对应的时间跨度。这样在不同缩放级别下，用户感受到的吸附距离仍然接近 10 像素。
区间整体移动还需要同时检查两端。
假设一个区间原本是 5–8 秒，长度为 3 秒。如果它的结束端吸附到 12 秒，新的起点就应该是 9 秒：
const snappedStart =
movingEdge === "end"
? targetTime - duration
: targetTime;
不能只修正其中一个端点，否则“移动区间”就会意外变成“改变区间长度”。当前实现会比较两端的吸附候选，选择距离更近的结果，再整体平移区间。
当浏览器交互完成后，下一个问题是：Agent 应该怎样使用这些能力？
这次采用的架构是：
Agent Skill：描述任务流程、时间依据和验证要求
↓
CLI / MCP：接收结构化操作
↓
共享命令引擎：校验、执行、生成语义差异
↓
新的 .timeline 项目文件
Skill 负责告诉 Agent 怎样完成工作，例如先检查已有标记、保留用户备注、根据实际时间定位，再检查执行结果。
CLI 和 MCP 提供可调用的接口。MCP 适配层调用现有命令运行器，不再复制一套标记增删改逻辑。
现在可以通过 CLI 查看项目和标记：
npm run agent -- project.inspect /projects/input.timeline
npm run agent -- marker.inspect /projects/input.timeline
写入操作则包括：
marker.add
marker.update
marker.delete
例如，假设检查结果显示项目版本为 0，并且“产品展示”的标记 ID 是 review-product，可以准备下面的计划：
{
"schemaVersion": 1,
"project": "/projects/input.timeline",
"baseRevision": 0,
"operations": [
{
"id": "move-product-range-v1",
"type": "marker.update",
"markerId": "review-product",
"time": 9
},
{
"id": "add-ending-note-v1",
"type": "marker.add",
"markerId": "ending-note",
"markerType": "note",
"time": 11,
"title": "结尾节奏",
"notes": "用户意见：结尾多留一点呼吸",
"color": "rose"
}
],
"output": {
"project": "/projects/output-marked.timeline"
}
}
实际使用时，需要将路径、版本号和标记 ID 替换为检查得到的值；备注内容应来自真实需求。
这里有两组字段需要区分：
id标识一次操作，用于识别重复执行；markerId标识项目中的具体标记。type表示命令，例如marker.add；markerType表示标记类型，例如note。
只更新区间的 time，会保留原有长度。上面的操作会把 5–8 秒移动到 9–12 秒。
执行前，先做结构校验和语义差异预览：
node skills/edit-timeline-studio/scripts/validate_edit_plan.mjs \
/projects/markers-plan.json
npm run agent -- project.diff /projects/markers-plan.json
确认差异符合预期后，再写出新项目：
npm run agent -- project.run /projects/markers-plan.json
npm run agent -- marker.inspect /projects/output-marked.timeline
语义差异会列出新增、删除和修改的标记，以及修改前后的内容。版本不匹配时，命令返回 REVISION_CONFLICT；某个操作失败时，整批修改不会部分写入项目。输出路径也不能覆盖输入文件或已有文件。
“先检查、再预览差异、最后应用”由 Skill 工作流明确要求；版本检查、事务处理和文件保护则由代码落实。
实现过程中，最值得记录的一个问题来自旧项目中的重复 ID。
假设导入数据里有三个标记都叫 x，读取时将它们规范化为 x、x-2、x-3。如果每执行一个操作都重新生成 ID，那么删除第一个标记后，后面的身份可能发生变化，接着更新 x-2 就可能选错对象。
修复方法是在事务开始时，对项目副本统一规范化一次，并固定标记身份。后续操作始终使用这组 ID 查找目标。生成重复 ID 的后缀时，也需要预留长度，避免生成结果超过字段限制。
另一个问题是浮点精度。一个位于 1000 秒附近、长度为 1 毫秒的区间，经过减法计算后，可能得到略小于 0.001 的结果。如果直接比较，就会把合法移动误判为区间过短。这里需要区分浮点误差和真正无效的输入，同时避免扩大正常区间的长度。
这些问题说明，面向 Agent 的接口需要认真处理连续操作、重复执行和旧数据兼容。
时间定位也必须有明确依据。
浏览器拖动可以使用像素吸附，CLI 和 MCP 则直接接收精确秒数。Agent 应从项目检查结果、素材边界或已经验证的音频时间点得到这些数值。
如果一个事件使用的是源视频时间，还需要换算到项目时间。恒定倍速下，关系是：
项目时间 = 片段起点 +（源时间 - 源裁剪起点）/ 播放倍速
启用速度曲线后，则需要使用对应的源时间映射，不能简单除以平均速度。
音乐节拍也是一样：标记命令负责保存时间点，本身不提供自动节拍检测。生成节拍标记之前，仍然需要可靠的节拍起点、速度信息或分析结果。
这次验证除了 lint、类型检查和生产构建，还覆盖了实际 CLI/MCP 调用及项目文件往返。一个具体场景是：将“产品展示”从 5–8 秒移到 9–12 秒，在 11 秒新增中文备注，并检查其他标记、媒体字节和原文件哈希保持不变。
对于只修改标记的项目，验证结果还要求媒体时长和渲染计划保持不变。
现在，这套能力已经随 Timeline Studio Skill v1.0.7 发布。它让章节、节拍和修改意见成为可以保存、检查、继续编辑的项目内容，也让人和 Agent 能围绕同一组时间位置协作。
如果你想实际体验标记、区间拖动和吸附，可以打开 Timeline Studio 在线编辑器。
如果你正在开发浏览器编辑器、设计 MCP 工具，或者研究 Agent 如何操作可编辑文件，可以从 GitHub 源码仓库 查看实现。欢迎 Star 关注后续更新，也欢迎通过 Issue 提交实际剪辑场景和边界问题。
需要给 Codex 安装这一版 Skill，可以使用：
gh skill install MartinDelophy/ai-video-editor edit-timeline-studio \
--pin v1.0.7 --agent codex --scope user
安装 Skill 后，使用本地命令仍需要准备 Timeline Studio 仓库及其 Node 依赖。具体能力和调用流程可以查看 v1.0.7 发布说明及时间线标记工作流文档。
