easyCut

easyCut 是一个面向 Agent 的动漫季度视频整理 Skill。它由具备本地图片查看能力的 Agent 判断视频截图中的内容边界，再通过确定性的 Python 与 FFmpeg 工具完成裁剪、分段 拼接和结果校验。

• 默认使用流复制（stream copy），尽量保持源视频的编码参数和画质。
• 支持将同一集的多个 MP4 片段按顺序拼接。
• 不确定的内容会进入人工复核清单，不会靠猜测生成结果。
• 源视频只读，已有输出不会被覆盖。

README.md 面向使用者和开发者；Agent 的完整执行规则以 SKILL.md 为准。

阅读入口

你的目标	阅读位置	使用的内容
安装并使用 easyCut	使用指南	GitHub Release 中的 Skill 包
修改、测试或调试 easyCut	开发指南	完整开发仓库

使用指南

本部分面向 Skill 使用者。使用者从 Release 安装 easyCut，不需要开发仓库中的测试和 设计文档。

确认适用场景 -> 安装 Release -> 配置持久根目录 -> 提供 input/output/task -> 查看结果

能做什么

easyCut 适合处理一个动漫季度对应的一组 MP4 文件，例如：

• 从混有平台提示、广告或其他无关内容的视频中保留完整单集内容；
• 找出较大的正片起止边界；
• 将被拆成上下篇或多个文件的同一集重新拼接；
• 对边界不明确的视频生成复核说明。

easyCut 会保留冷开场、OP、正片、ED、演职员表、片尾彩蛋和预告。它不是面向逐帧精剪 或创作型剪辑的工具。

开始之前

1. 使用 easyCut 的 Agent 必须能够直接查看本地截图。没有该能力时不能启动此 Skill。
2. 使用的 Agent 支持加载本地 Skill，并能读取 Skill 目录中的 SKILL.md 和脚本。
3. 系统中存在 ffmpeg 和 ffprobe。
4. 安装阶段需要 Python 3.11。
5. 一个输入目录只放一部动漫的一个季度，源文件使用 MP4 格式。

可以先检查本地依赖：

python3.11 --version
ffmpeg -version
ffprobe -version

安装

从 GitHub Releases 下载目标版本的 easycut-skill.zip。将压缩包解压到当前 Agent 能够发现的 Skill 目录；不同 Agent 的用户级、项目级 Skill 路径和刷新方式不同，请以对应 Agent 的文档 为准。

以下命令使用通用占位路径，不代表某个特定 Agent 的固定目录：

SKILL_DIR="/path/to/your-agent/skills/easycut"
mkdir -p "$SKILL_DIR"
unzip easycut-skill.zip -d "$SKILL_DIR"
python3.11 -m venv "$SKILL_DIR/.venv"
"$SKILL_DIR/.venv/bin/pip" install "$SKILL_DIR"

安装后重新加载 Skill 或新开 Agent 会话，并通过当前 Agent 提供的 Skill 查看方式确认 easycut 已生效。Release 压缩包不包含 .venv，因此安装后需要执行上面的环境创建和 依赖安装步骤。不要用开发目录的文件清单推断 Release 内容，应以所下载版本的 ZIP 为 准。

配置输入、输出与 Workspace

按照 SKILL.md 的约定，用户提供：

• input：输入目录；
• output：输出目录；
• task：可读的任务名，例如 Anime-S01。

easyCut 还必须有一个持久存储根目录。这个根目录来自以下二者之一：

1. Agent 调用命令时显式传入的 --work；
2. 未传 --work 时使用的环境变量 EASYCUT_HOME。

如果两者都没有配置，easyCut 会停止并要求配置持久存储。 该根目录必须是持久、可写的位置，不能使用系统临时目录或 Skill 安装目录。

三类目录的关系

输入目录 input
  └── 一部动漫、一个季度的源 MP4
          │
          │ 只读
          ▼
        easyCut ───────────────► 输出目录 output
          │                       └── 仅最终 MP4
          │
          ▼
持久根目录 root
├── knowledge.md
└── work/
    └── <task>/
        └── 任务状态和过程文件

• 输入目录代表一部动漫的一个季度。源视频只读，easyCut 不修改源文件。
• 输出目录只用于最终 MP4。截图、计划、日志、报告和临时文件不能放在输出目录。
• 持久根目录用于 easyCut 的共享经验和任务数据，不是输入目录或输出目录。
• SKILL.md 没有要求持久根目录是输入、输出目录的共同父目录。三者按职责分别指定 即可。
• --work 中的 “work” 表示 easyCut 的持久存储根目录，不是最终任务目录。

持久根目录与任务目录

无论根目录来自显式 --work 还是 EASYCUT_HOME，路径计算规则都相同：

共享经验 = <root>/knowledge.md
任务目录 = <root>/work/<task>

例如：

root = /Users/me/easycut-workspace
task = Anime-S01

共享经验 = /Users/me/easycut-workspace/knowledge.md
任务目录 = /Users/me/easycut-workspace/work/Anime-S01

任务目录由 easyCut 根据根目录和任务名生成，不应把 /Users/me/easycut-workspace/work/Anime-S01 当作 --work 再次传入。

完整结构如下：

/Users/me/easycut-workspace/
├── knowledge.md
└── work/
    ├── Anime-S01/
    │   ├── inventory.json
    │   ├── cuts.json
    │   ├── execution.json
    │   ├── report.md
    │   ├── frames/
    │   ├── analysis/
    │   │   ├── contact-sheets/
    │   │   └── boundary-checks/
    │   ├── logs/
    │   └── temp/
    └── Another-Anime-S02/

--work 和 EASYCUT_HOME 都是可供多个 easyCut 任务使用的根目录。每个任务通过 <root>/work/<task> 隔离，knowledge.md 则位于根目录并供这些任务共享。

推荐配置

推荐为 easyCut 保持一个长期不变的持久根目录，并为不同动漫或季度使用不同的任务名。 这样可以持续复用 knowledge.md，同一任务也能继续使用已有截图、计划、执行状态和 报告。

可以固定配置：

export EASYCUT_HOME="/Users/me/easycut-workspace"

配置 EASYCUT_HOME 后，用户每次只需提供 input、output 和 task。需要临时使用另一个 根目录时，再显式传入 --work；对于 knowledge.md，显式 --work 优先于 EASYCUT_HOME。

发起任务

在已经配置 EASYCUT_HOME 的情况下，在提示词中明确要求使用 easyCut Skill，并提供 输入目录、输出目录和任务名即可。不要替 Agent 提供裁剪时间点，截图选择和边界判断属于 easyCut 的工作。

示例：

使用 easycut Skill 整理 /Users/me/Videos/Anime-S01-input 中的第一季视频，
输出到 /Users/me/Videos/Anime-S01-output，
任务名使用 Anime-S01。

Skill 的显式调用语法由当前 Agent 决定；easyCut 不要求使用某一种固定命令或前缀。

如果未配置 EASYCUT_HOME，还需要请 Agent 将一个持久根目录作为 --work 传入：

使用 easycut Skill 整理 /Users/me/Videos/Anime-S01-input 中的第一季视频，
输出到 /Users/me/Videos/Anime-S01-output，
任务名使用 Anime-S01，
并使用 /Users/me/easycut-workspace 作为 --work。

两种配置最终使用相同的路径关系：

input  = /Users/me/Videos/Anime-S01-input
output = /Users/me/Videos/Anime-S01-output
task   = Anime-S01
root   = EASYCUT_HOME 或显式 --work

共享经验 = <root>/knowledge.md
任务目录 = <root>/work/<task>

当根目录为 /Users/me/easycut-workspace 时：

共享经验 = /Users/me/easycut-workspace/knowledge.md
任务目录 = /Users/me/easycut-workspace/work/Anime-S01

Agent 会按以下阶段执行：

inspect -> capture -> validate -> execute -> verify

1. 扫描文件名和媒体参数；
2. 选择少量代表性时间点并直接查看截图；
3. 逐步缩小不明确的边界，形成 cuts.json；
4. 校验计划后，以流复制方式裁剪或拼接；
5. 检查输出文件、媒体参数和时长，并生成报告；
6. 显式说明是否向 knowledge.md 增加了可复用经验。

查看结果

最终视频写入输出目录，并按季度和集数命名：

Anime-S01-output/
├── S01E01.mp4
├── S01E02.mp4
└── S01E03.mp4

过程文件保存在 easyCut 根据“持久根目录 + 任务名”生成的任务目录：

<work-root>/
├── knowledge.md
└── work/
    └── Anime-S01/
        ├── inventory.json
        ├── cuts.json
        ├── execution.json
        ├── report.md
        ├── frames/
        ├── analysis/
        ├── logs/
        └── temp/

report.md 汇总成功、已存在、待复核和失败的项目。输出目录中只保留最终 MP4。

使用限制

• easyCut 只在当前 Agent 能直接查看本地图片时使用，不会把截图识别转交给其他模型或 外部视觉 API。
• 首次执行只允许流复制。流复制可能受关键帧影响产生轻微时长偏差。
• 多段视频的编码、分辨率、帧率、像素格式或音频参数不兼容时，拼接可能失败。
• easyCut 不会自动改用重编码。只有流复制已经失败，且使用者明确确认全部输出参数后， 才能对指定集数进行重编码重试。
• 无法可靠确认的边界会进入 review，不会阻塞其他已确认集数。

---

开发指南

本部分面向维护者和贡献者，介绍完整开发仓库。开发仓库与已经发布的 Release Skill 包不是同一份内容。

获取开发仓库 -> 搭建环境 -> 修改代码或 Skill -> 运行测试与静态检查

开发仓库与 Release

形态	面向对象	包含内容	不包含或不保证包含
开发仓库	开发者、贡献者	当前源代码、测试、开发文档、验证记录和本地修改	不保证已经测试完毕或正式发布
Release Skill 包	Skill 使用者	指定版本安装、使用和运行所需的说明、Skill 规则、元数据、脚本、Python 包和依赖声明	测试、设计文档、验证记录、Git 历史、缓存和虚拟环境

开发仓库通常包括：

README.md
SKILL.md
agents/
scripts/
easycut/
tests/
docs/
pyproject.toml

Release 中的 easycut-skill.zip 只保留安装和运行对应版本所需的内容。当前已经发布的 v0.1.0 包包括：

SKILL.md
agents/
scripts/
easycut/
pyproject.toml

两者的关系：

• 开发仓库会继续变化，Release 是发布时生成的固定版本快照。
• 开发仓库中的修改不会自动进入已经发布的 ZIP。
• 即使对应同一个 Git 版本，Release ZIP 也只是开发仓库内容的发布子集。
• 当前开发仓库与最新 Release 可能存在功能、规则或文档差异。
• 已发布的 v0.1.0 早于本 README，因此其 ZIP 中没有 README.md。

搭建开发环境

获取完整开发内容后创建开发环境：

git clone https://github.com/Removel/easycut.git
cd easycut
python3.11 -m venv .venv
.venv/bin/pip install -e ".[dev]"

开发和媒体测试依赖系统中的 ffmpeg 与 ffprobe。

了解项目结构

easycut/
├── README.md
├── SKILL.md
├── agents/
│   └── openai.yaml
├── scripts/
│   └── easycut.py
├── references/
│   └── reencoding.md
├── easycut/
│   ├── cli.py
│   ├── inspect.py
│   ├── capture.py
│   ├── validate.py
│   ├── execute.py
│   ├── verify.py
│   └── ...
├── tests/
├── docs/
└── pyproject.toml

• SKILL.md：Agent 工作流、能力边界和安全规则。
• agents/openai.yaml：Skill 的界面展示信息和默认提示词。
• scripts/easycut.py：Skill 使用的统一命令入口。
• references/reencoding.md：仅在流复制失败后按需读取的重编码兜底说明。
• easycut/：可测试的媒体处理与工作区实现。
• tests/：CLI、模型、工作区、执行和验证测试。

这份结构用于开发，不代表 Release ZIP 会包含 tests/、docs/ 或开发期验证产物。

调试 CLI

查看所有子命令：

.venv/bin/python scripts/easycut.py --help
.venv/bin/python scripts/easycut.py inspect --help

命令	职责
inspect	扫描 MP4、调用 ffprobe 并写入媒体清单
capture	在 Agent 选择的时间点提取截图
validate	校验裁剪计划、路径、时长、顺序和输出冲突
execute	流复制裁剪、兼容片段拼接和原子写入
verify	校验输出媒体并生成 report.md
knowledge	查看或合并少量跨任务可复用经验

CLI 输出 JSON，正常情况下返回码为 0。其他主要返回码如下：

返回码	含义
1	参数之外的运行异常
2	validate 发现无效计划
3	verify 发现校验失败
4	execute 至少有一集执行失败

了解裁剪计划

默认计划文件位于 <work-root>/work/<task>/cuts.json：

{
  "cuts": [
    {
      "episode": 1,
      "source": "E01.mp4",
      "start": 12.5,
      "end": 1455
    },
    {
      "episode": 2,
      "source": "E02-part1.mp4",
      "start": 0,
      "end": 720
    },
    {
      "episode": 2,
      "source": "E02-part2.mp4",
      "start": 8,
      "end": 738
    }
  ],
  "review": [
    {
      "source": "E03.mp4",
      "reason": "ending remains unclear"
    }
  ]
}

相同 episode 的片段按 JSON 中的顺序拼接。执行前必须先通过 validate。

运行测试与检查

运行完整测试：

.venv/bin/pytest

运行静态检查：

.venv/bin/ruff check .

媒体相关测试会实际调用 ffmpeg 和 ffprobe。修改执行或验证逻辑时，至少应覆盖：

• 单片段流复制；
• 多片段兼容性检查和拼接；
• 已有输出保护；
• 单集失败不影响其他成功结果；
• 中断后的执行状态持久化；
• 媒体参数和时长偏差校验。

开发约束

• 不修改源视频，不覆盖已有输出。
• 所有执行都必须经过 validate。
• 默认保持流复制，不把重编码作为普通恢复手段。
• 每集完成或失败后都要原子保存执行状态，保证批任务可恢复。
• 截图判断由具备视觉能力的当前 Agent 完成，Python 代码只负责确定性媒体操作。
• 行为或安全边界发生变化时，同步更新 SKILL.md、测试和本 README。