/byted-mediakit-voiceover-editing

name: byted-mediakit-voiceover-editing
display_name: 口播视频智能精剪工具
version: 1.0.9
description: |
  Volcano Engine AI MediaKit talking-head video editing Skill: a one-stop workflow from environment setup through media management, audio processing, talking-head cuts, video export, review UI, and iterative refinement. You MUST invoke this Skill when the user mentions talking-head editing, cutting talking video, video editing, removing pauses, processing audio, exporting talking video, automatic editing, removing verbal slips, or similar. Also invoke when the user uploads video or audio and asks for editing.
category: 音视频处理
env:
  - name: ARK_SKILL_API_BASE
    description: SkillHub VOD 网关 OpenAPI 根 URL（与 ARK_SKILL_API_KEY 同时存在时启用 apig）；通常由宿主/容器注入进程环境，不必写入 .env
    required: false
    secret: false
    default: ''
  - name: ARK_SKILL_API_KEY
    description: SkillHub 网关 Bearer Token；与 ARK_SKILL_API_BASE 同时存在时启用 apig；通常由宿主/容器注入，不必写入 .env
    required: false
    secret: true
    default: ''
  - name: VOLC_ACCESS_KEY_ID
    description: 火山引擎访问密钥ID（直连 OpenAPI 时必填；若进程环境中已有 ARK_SKILL_API_BASE 与 ARK_SKILL_API_KEY 则可不填）
    required: false
    secret: true
    default: ''
  - name: VOLC_ACCESS_KEY_SECRET
    description: 火山引擎访问密钥 Secret（直连 OpenAPI 时必填；若进程环境中已有 ARK_SKILL_API_BASE 与 ARK_SKILL_API_KEY 则可不填）
    required: false
    secret: true
    default: ''
  - name: VOLC_SPACE_NAME
    description: 火山引擎VOD存储空间名称
    required: true
    secret: false
    default: ''
  - name: ASR_API_KEY
    description: 语音识别服务API密钥
    required: true
    secret: true
    default: ''
  - name: ASR_BASE_URL
    description: 语音识别服务接口地址
    required: true
    secret: false
    default: 'https://openspeech.bytedance.com/api/v3/auc/bigmodel'
  - name: VOD_EXPORT_SKIP_SUBTITLE
    description: 导出时是否跳过字幕压制（默认跳过；0/false/no 表示启用字幕压制）
    required: false
    secret: false
    default: '1'
  - name: TALKING_VIDEO_AUTO_EDIT_REVIEW_AUTO_OPEN
    description: 审核页启动时是否自动打开浏览器（默认不打开；1/true/yes 表示打开）
    required: false
    secret: false
    default: '0'
  - name: TALKING_VIDEO_AUTO_EDIT_VIDEO_CUT
    description: 是否开启视频裁剪功能：1 进行（默认）；0 不进行。仅当有字幕或音频静音时生效。
    required: false
    secret: false
    default: '1'
  - name: EXECUTION_MODE
    description: |
      执行模式选择（可选），优先级 apig > cloud > local：
      - apig: 使用 SkillHub 网关（需 ARK_SKILL_API_BASE + ARK_SKILL_API_KEY）
      - cloud: 直连火山引擎 OpenAPI（需 VOLC_ACCESS_KEY_* + VOLC_SPACE_NAME + ASR_*）
      - local: 完全本地执行，使用 Qwen3-ASR / Demucs / ffmpeg，无需任何云端环境变量和 VOD 空间
      留空则自动检测：按 apig > cloud > local 优先级尝试，缺参时打印提示并自动降级。
    required: false
    secret: false
    default: ''
permissions:
  - network
  - file_read
  - file_write
  - temp_storage
triggers:
  - 口播剪辑
  - 剪口播
  - 剪视频
  - 去掉停顿
  - 处理音频
  - 导出口播
  - 自动剪辑
  - 去除口误
  - 视频剪辑

一、模式与凭据

1.1 三种执行模式

| 模式 | 说明 | 所需环境变量 | ASR 方式 | | --------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ------------------ | | **apig** | SkillHub 网关代理，Bearer Token 认证 | `ARK_SKILL_API_BASE` + `ARK_SKILL_API_KEY`（容器注入）+ `VOLC_SPACE_NAME` + `ASR_API_KEY` + `ASR_BASE_URL` | 豆包语音大模型 | | **cloud** | 直连火山引擎 OpenAPI，HMAC 签算 | `VOLC_ACCESS_KEY_ID` + `VOLC_ACCESS_KEY_SECRET` + `VOLC_SPACE_NAME` + `ASR_API_KEY` + `ASR_BASE_URL` | 豆包语音大模型 | | **local** | 完全本地执行，无需云端服务 | 无（可选 `EXECUTION_MODE=local`） | Qwen3-ASR 本地推理 |

**优先级**：`apig > cloud > local`。自动检测按此顺序依次检查环境变量，缺参时打印 `.env` 路径与缺失变量列表并自动降级。

1.2 凭据配置

• **`.env` 文件位置**：`<SKILL_DIR>/.env`
• 脚本先读**进程环境变量**，再用 `.env` **补全未设置的项**（不覆盖容器注入）
• `ARK_SKILL_*` 通常由部署容器注入，**不必**手写到 `.env`
• **缺参不阻塞**：不使用终端 `input()` 交互，缺参时打印提示信息并自动降级到可用模式
• Agent 推荐用户通过**编辑 `.env` 文件**或**Agent 文件写入工具**来配置变量，避免终端粘贴问题
• **安全**：控制台创建**仅含所需权限**的密钥；测试请用**独立点播空间**；`.env` 勿提交仓库

1.3 模式意图识别（Agent 必读）

当用户在对话中表达模式切换意图时，Agent 应识别并执行：

| 用户表达 | 识别为 | 操作 | | -------------------------------------- | ---------------------- | ------------------------------- | | "用本地模式" / "不走云端" / "离线处理" | `EXECUTION_MODE=local` | 写入 `.env` 或传 `--mode local` | | "用云端" / "用火山引擎" / "走 AK/SK" | `EXECUTION_MODE=cloud` | 写入 `.env` 或传 `--mode cloud` | | "走网关" / "用 apig" / "用 SkillHub" | `EXECUTION_MODE=apig` | 写入 `.env` 或传 `--mode apig` |

**隔离要求**：各任务的模式选择相互独立。一个任务中切换到 local 不应影响另一个任务的模式。Agent 应在每次任务开始时重新检测或遵循用户当次指定。

---

二、执行约束（STRICT — NO EXCEPTIONS）

1. **仅使用以下脚本**，禁止创建新脚本 2. **按顺序执行所有步骤**，跳步即任务失败 3. 执行任何脚本前必须先 `cd <SKILL_DIR>/scripts` 4. 每个 CHECKPOINT 必须验证产物后再继续 5. 任何步骤失败必须**立即停止并报告**，不得继续 6. Step 4/5/6 输出**禁止**简化版、占位符、示例或省略内容 7. **最终输出必须保持原样，不能做任何修改** 8. 审核页是否自动打开由 `TALKING_VIDEO_AUTO_EDIT_REVIEW_AUTO_OPEN` 决定（**强制**）：Agent 不得额外执行 `open`/`start`/`xdg-open` 等命令 9. **超时设置**：音视频处理时长较长，宿主超时时间应设置为 **60 分钟**

职责分工

| 组件 | 职责 | 不做 | | -------------------- | --------------------------------------------------- | --------------------- | | **脚本（规则引擎）** | ASR 优化、候选生成（标记位置+规则置信度+删除建议） | 不做最终删除/保留决策 | | **宿主 Agent（你）** | 语义断句、口癖识别确认、候选复核、最终删除/保留决策 | 不修改脚本 |

**核心原则：脚本提供候选（含 deleted_parts + cleaned_text），Agent 做最终决策。**

---

三、路径规则

3.1 SKILL_DIR 与 Output-dir

• **SKILL_DIR**：`byted-mediakit-voiceover-editing` 目录路径
• **PROJECT_ROOT**：由 `scripts/project_paths.py` 推导：

1. 环境变量 `VOICEOVER_EDITING_PROJECT_ROOT` 若设置则用之 2. 否则为 `<SKILL_DIR>` 的 `parents[2]`（沿父链上移 3 级，不依赖中间目录命名）

• **Output-dir**：`<PROJECT_ROOT>/output/<素材名>/`；若目录已存在则自动递增为 `<素材名>_01`、`<素材名>_02`...
• 脚本启动时会打印路径推导日志，便于调试确认

3.2 素材名推导

| 来源 | 推导规则 | 示例 | | --------- | -------------------- | -------------------------------------