# JackAICut 通用 Agent 接入协议 (MCP & Skill)

本协议专为运行在用户本地电脑上的 AI Agent（包括 WorkBuddy、DeepSeek Harness、Claude Code、ChatGPT 桌面端、Cursor、Windsurf 以及任意支持本地 MCP / Agent Skill 的智能体）设计，用于连接本机 JackAICut 视频剪辑工具并载入口播剪辑与字幕整理技能。

不要使用 Codex plugin marketplace、`plugin add` 或 `jackaicut@followjack`。只注册本机 MCP，并读取标准 Skill。

---

## 1. 运行原则与安全边界

- **全本地处理**：所有剪辑分析与文字处理均在用户本机完成。**严禁向外部服务器或云端大模型上传用户的原始视频或媒体文件**。
- **保护原时间线与原任务**：
  - 严禁覆盖或破坏用户在 DaVinci Resolve Studio 中的现有时间线；
  - 若用户希望保留当前剪辑稿再试验新版本，先调用 `duplicate_task` 创建任务副本，后续只改返回的新 `taskId`；
  - Agent 负责分析口播稿、挑选精彩段落、去重以及纠正字幕错词；**最终时间线的生成由创作者在 JackAICut 桌面端把关确认后一键创建**。

---

## 2. 第一步：自动探测本地 JackAICut（三级自愈检索）

请 Agent 优先全自动探测本地操作系统路径，**严禁在首轮直接向用户索要路径**：

### 级别 1：标准规范安装路径检查
- **macOS 标准路径**：
  - `/Applications/JackAICut.app/Contents/MacOS/jackaicut-mcp`
  - `~/Applications/JackAICut.app/Contents/MacOS/jackaicut-mcp`
- **Windows 标准路径**：
  - `%LOCALAPPDATA%\Programs\JackAICut\jackaicut-mcp.exe`
  - `C:\Program Files\JackAICut\jackaicut-mcp.exe`

### 级别 2：后台静默搜盘（解决用户安装在自定义目录）
若标准路径不存在，请 Agent 在后台静默执行快速系统查询：
- **macOS**：执行 `mdfind "kMDItemFSName == 'JackAICut.app'"` 定位应用包，可执行文件位于其 `Contents/MacOS/jackaicut-mcp`；
- **Windows**：查询注册表卸载项或检查常见磁盘位置是否存在 `jackaicut-mcp.exe`。

### 级别 3：确定未安装时的智能引导与下载闭环
若以上两级均未检测到该程序，说明用户尚未安装客户端。**请勿直接抛出技术错误**，请自动识别用户系统并以极度友好的口吻主动提供官方直链：
- “在你的电脑上暂未检测到 JackAICut 客户端。使用前需要先安装该软件：
  - 如果你尚未安装，可直接点击下载官方客户端：
    - macOS 版：https://jackaicut.com/download/mac
    - Windows 版：https://jackaicut.com/download/windows
    - 安装完成后告诉我‘继续’，我将立即为你连接并检查口播任务；
  - 如果你已将软件安装在特殊自定义目录，也可以直接把它的路径发给我。”

---

## 3. 第二步：以通用方式将该程序载入为本地 MCP 工具

一旦定位到 `jackaicut-mcp` 可执行文件：
- 先运行 `"<JACKAICUT_MCP>" --version` 和 `"<JACKAICUT_MCP>" --health-check`。
- **请使用你当前 Agent 宿主平台的标准机制**，将该程序注册为名为 `jackaicut` 的本地 MCP 服务（传输模式为本地 STDIO 管道）。
- *（宿主参考：若你的环境提供 CLI 注册，可调用对应 mcp add 命令；若通过配置文件加载，可写入对应 mcpServers 配置；若为内置 MCP 机制，直接载入该二进制路径即可。）*
- 不要调用 `codex plugin add`，也不要寻找旧的 Codex Marketplace 目录。

---

## 4. 第三步：载入剪辑技能

若当前宿主支持 Agent Skills，请载入：

- `jackaicut-smart-cut`
- `jackaicut-smart-subtitles`

本地 Skill 文件随 JackAICut 客户端提供：

- macOS：`/Applications/JackAICut.app/Contents/Resources/agent-skills/smart-cut/SKILL.md`
- macOS：`/Applications/JackAICut.app/Contents/Resources/agent-skills/smart-subtitles/SKILL.md`
- Windows：在应用资源目录中的 `agent-skills/smart-cut/SKILL.md` 与 `agent-skills/smart-subtitles/SKILL.md`

如果宿主暂时读不到 Skill 文件，仍可按下面的工作流使用 MCP 工具。

`jackaicut` 本地 MCP 服务暴露以下核心能力：
- `get_status`：检查本地任务存储与连接状态。
- `list_tasks`：列出最近含口播稿的剪辑任务（默认前 20 个）。
- `get_transcript`：分页读取口播稿字词与毫秒级时间戳（生成剪辑稿时优先使用返回的 `matchText`）。
- `duplicate_task`：创建指定任务的独立副本（保留原任务，重新生成副本 ID）。
- `validate_cut_script`：只读验证拟保留的段落是否与口播稿 100% 连续精确对齐。
- `save_cut_draft`：将验证通过的剪辑稿保存回当前任务。
- `save_smart_subtitles`：保存 AI 智能整理的字幕结果（每行锚定到真实词索引，顺手纠正同音字和专有名词识别错误）。

### 锁定操作对象

若用户消息已给出剪辑任务 `taskId`，后续全部工具都只用这个 ID，禁止改去读取「最近任务」或凭任务名猜测。仅当用户未指定任务时，才调用 `list_tasks` 并与用户确认要用哪一个。

### 工作流 A：与 AI 商量打磨剪辑稿（jackaicut-smart-cut）
1. 调用 `get_status`。已有 `taskId` 则直接使用。
2. 若用户希望保留当前剪辑稿再试验新版本，先调用 `duplicate_task`，后续针对新副本 `taskId` 与 `taskUpdatedAtMs` 进行操作。
3. 调用 `get_transcript` 读取口播稿全文。
4. **剪辑提炼**：
   - 剔除重复口误、啰嗦废话、卡顿和跑题内容；
   - 保留高信息密度、逻辑连贯的精彩观点；
   - 严禁凭空捏造口播，每一段必须是口播稿中一段连续的原文（优先使用 `matchText`）。
5. 调用 `validate_cut_script` 验证全部保留段落。
6. 确认 `allMatched` 为 true 后，调用 `save_cut_draft` 保存剪辑稿。
7. 告知用户已保留的段落数与精简比例，并提示用户：“已保存为剪辑稿，请在 JackAICut 桌面端审阅，确认无误后点击‘创建剪辑时间线’即可在达芬奇中生成新时间线。”

### 工作流 B：整理智能字幕（jackaicut-smart-subtitles）
1. 调用 `get_status`。已有 `taskId` 则直接使用。
2. 调用 `get_transcript` 获取带词级索引（`words`）的口播稿。
3. 根据目标每行字数（通常建议 10~25 字，按完整词意自然断句）。
4. 根据上下文顺手修正 ASR 识别错误的同音字、专有名词、模型名或行业术语。
5. 每行字幕使用 `startWordIndex` 和 `endWordIndex` 锚定真实词首词尾（严禁借词、漏词或乱序）。
6. 调用 `save_smart_subtitles` 保存整理后的字幕。

---

## 5. 第四步：自检与主动开场（Verification & Handoff）

完成连接后，请立即调用 `get_status`。若用户已指定 `taskId`，直接读取该任务；否则再调用 `list_tasks`，并根据实际情况主动向用户汇报：

- **情况 1：本地已存在口播任务**  
  主动向用户汇报：  
  *“已成功连接本地 JackAICut！检测到你最近的口播任务：[列出 1~3 个最新任务名称]。我可以为你提供：1. 智能挑出精彩段落并生成剪辑稿；2. 整理短视频智能字幕并纠正错别字。你想先处理哪个任务？”*

- **情况 2：本地暂无已完成的口播任务**  
  主动向用户汇报：  
  *“已成功连接本地 JackAICut！目前本地暂无转写完成的口播任务。你可以先打开 JackAICut 导入视频生成口播稿，完成后随时告诉我‘开始剪辑’！”*