HotClip — 本地 AI 切片流水线
HotClip（AGPL-3.0 开源）把几小时的直播回放/播客/课程切成可直接发布的竖屏短视频，全程本地运行。你可以通过无头 CLI（或内置的 MCP 服务器）驱动与桌面应用相同的处理流程。所有环节——ASR、亮点检测、裁剪、字幕烧录——都在本机运行，素材绝不会被上传。
安装配置（一次性）
获取仓库与依赖（已存在的可跳过）：
git clone https://github.com/xixihhhh/hotclip.git && cd hotclip pnpm install # ffmpeg/ffprobe 是捆绑的 npm 二进制文件——无需安装其他东西
通过环境变量配置用于亮点检测的 LLM（任何兼容 OpenAI 的端点）：
export HOTCLIP_LLM_BASE_URL=http://localhost:11434/v1 # 本地 Ollama（无需密钥） export HOTCLIP_LLM_MODEL=qwen3:8b
云端端点还需要：export HOTCLIP_LLM_API_KEY=sk-...
若缺少这些配置，应询问用户使用哪个 LLM 端点——不要猜测密钥。
首次转写/切片运行时会自动下载 ASR 模型（约 1GB，优先使用国内镜像）。请提醒用户首次可能需等待几分钟。
命令（在仓库根目录运行）
pnpm cli transcribe <video> # 本地词级 ASR（带缓存；重复运行瞬时完成） pnpm cli highlights <video> [--max-clips N] [--reference REF] [--json] # AI 亮点候选——切片前先审核 pnpm cli clip <video> [--max-clips N] [--reference REF] [--no-vertical] [--no-captions] [--out DIR] [--json] # 全流程托管：转写 → 检测 → 导出 + 渲染 QA
--reference <video>：传入一个爆款切片作为模仿对象——其节奏（时长/语速/镜头切换频率/钩子形态）会在本地被测量，并作为偏好引导候选选择（绝非硬性规则）。当用户说“切得像这条”/“学习这个片段”时使用。
输入格式：MP4 / MKV / MOV / FLV / TS，或纯音频（播客会自动生成波形视频）。含空格的路径需要加引号。
推荐工作流
审核优先（交互式会话的默认方式）：运行 highlights --json，向用户展示候选（标题/评分/钩子/是否推荐），让其挑选，然后运行 clip——流水线会从缓存重新检测，因此成本很低。对于“直接做”的请求，可直接运行 clip。
阅读输出回执：导出文件夹中每个切片包含一个 mp4 + 封面 JPG + .post.txt（发布文案），外加 clips.json——每个切片的证据链（render：流水线做了什么）和 qa：渲染 QA 报告（status: pass|warn，带有黑帧、长静音、响度偏差、时长不符、句中截断等问题，以及通过本地规则检查标题/文案/字幕中的平台风险词——qa.contentHits 列出每个词及其出现位置）。
自动自修复：可修复的警告（首尾静音或黑帧 → 边缘裁剪；响度偏差 → 二次归一化）会在一次处理中修复并重新检查；qa.repair 记录所做操作（actions、applied）。只有当重新检查严格改善时，修复才会被保留。
提示 QA 警告：若任何切片仍有 qa.status === "warn"，请告知用户是哪个切片及原因；内容检查命中意味着文案/字幕可能被抖音/小红书/视频号限流或拒绝——建议发布前修改措辞。切勿在未告知的情况下发布带警告的切片。
硬性规则
不要猜测时间戳。切点来自词级对齐转写（highlights 输出）；不要凭空编造起止秒数，也不要在流水线已覆盖时手工用 ffmpeg 裁剪。
本地优先：除了用户配置的 LLM 端点（它只接收转写文本，绝不接收媒体）外，不要把素材或转写上传到任何服务。
若不指定 --out，导出结果会放在源视频旁边的 <name>-hotclip/ 目录；完成后告知用户绝对路径。
MCP 替代方案
同一流水线也以本地 stdio MCP 服务器形式暴露（pnpm mcp，工具：clip_video / detect_highlights / transcribe_video）——当宿主支持 MCP 注册时优先使用；否则 CLI 是等效的。