13 KiB
AutoClip 命令行、MCP 与本地模型
面向开发者的三种用法，全部复用桌面应用同一条流水线、同一个数据目录：
| 形态 | 一句话 | 入口 |
|---|---|---|
| CLI | autoclip produce video.mp4 --platform douyin 一键出片；run 保留旧切片入口 |
backend/cli.py |
| MCP server | 让 opencode / Cursor / Claude Code / 任何 MCP 客户端直接调 AutoClip | backend/mcp_server.py |
| 本地模型预设 | 设置页 / CLI 直接选 Ollama、LM Studio，不用填 key | backend/core/local_presets.py |
1.5 一键出片共用 backend/services/quick_output_runner.py 与桌面 Studio；旧切片入口的共享逻辑在 backend/services/local_runner.py：不起 FastAPI / Celery，在当前进程里跑 SimplePipelineAdapter，
产物目录、metadata、SQLite 记录与桌面端一致——CLI 出的片，打开桌面应用首页就能看到。
1.5 一键出片（推荐）
CLI / MCP 与桌面统一为 1.5.0。先核对 autoclip --version；MCP 可调用 get_version。
本轮验收及同事测试步骤见 1.5 验收与测试包。
# 使用桌面已经保存的 AI 模型配置；本地文件和 HTTPS 的 B站 / YouTube 链接均可。
autoclip produce talk.mp4 --srt talk.srt --platform douyin --platform youtube_shorts --json
autoclip produce talk.mp4 --platform douyin --portrait-style podcast --json
autoclip outputs PROJECT_ID --export-kits
produce 等待制作及自动封面任务完成，返回各版本的 video_path、cover_path、post、kit_path。
partial 表示有部分版本失败，已完成的版本仍保留；failed 的退出码为 1，输入无效为 2。
outputs 不调用模型；--export-kits 在磁盘写 ZIP，文案或封面变化后生成新的包。
--timeout 只停止进度等待，不取消渲染，CLI 会等待后台线程安全收尾；需要后台轮询时优先使用 MCP。
MCP 使用 start_quick_output（立即返回 ID）和 get_quick_output_status（轮询）：
{"source":"/absolute/path/talk.mp4","srt_path":"/absolute/path/talk.srt","platforms":["douyin","youtube_shorts"],"portrait_style":"podcast"}
然后调用 get_quick_output_status，参数为 {"project_id":"返回的ID","export_kits":true}。
终态为 completed / partial / failed。MCP 握手版本和 get_version 都为 1.5.0。
保持 MCP 服务运行至制作完成；制作进程提前退出时查询会显示 interrupted，已完成的视频仍可取回。
竖版版式参数为 auto / interview / podcast。默认抖音、小红书用访谈式，TikTok、Reels、Shorts 用播客式；
手动选择只改变竖版布局，中文平台仍用中文，英文平台仍用英文，横版保持 16:9。中文满屏字幕按两行分页。
完整来源保留和人物取景的降级规则仍适用：没有可用的人物轨迹、或原片字幕不能裁切时，会保留完整画面。
支持平台 ID：douyin、xiaohongshu、bilibili、tiktok、instagram_reels、youtube_shorts、youtube_long。
reels、shorts 是别名；youtube_long 当前只生成至少 180 秒的完整片段，较短素材请先选 Shorts 或 B站。
模型、AI 封面和自动片尾共用桌面设置。制作时保持一个入口运行；新 CLI / MCP demo 建议用独立数据目录，
通过 autoclip --data-dir /path/to/demo-data produce ... 或 MCP 环境变量 AUTOCLIP_DATA_DIR 指定。
独立目录需要自己的模型配置，不会读取另一个数据目录的密钥；新入口不使用旧 run --provider 的临时覆盖。
旧 run / clip_video / start_clip_job 继续提供原始切片与合集。
1. 安装
git clone https://github.com/zhouxiaoka/autoclip.git && cd autoclip
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
pip install -e . # 得到 autoclip / autoclip-mcp 两个命令
不装包也能用：python -m backend.cli ...（在仓库根目录）。
需要 ffmpeg 在 PATH（brew install ffmpeg）。没有字幕的视频要本地 Whisper：pip install faster-whisper，
或在桌面应用「设置 → 转写」一键安装（两者共用模型目录）。
先体检：
autoclip doctor
# 数据目录 ~/Library/Application Support/AutoClip · Python 3.11.9
# ✓ ffmpeg /opt/homebrew/bin/ffmpeg
# ✓ whisper faster-whisper 已安装
# ✓ 模型 ollama · qwen2.5:7b · http://localhost:11434/v1
2. CLI
autoclip run talk.mp4 # 用桌面应用设置页里配好的模型
autoclip run talk.mp4 --provider ollama # 本地 Ollama（默认 qwen2.5:7b，无需 key）
autoclip run talk.mp4 --provider lmstudio --model qwen2.5-7b-instruct
autoclip run talk.mp4 --provider openai --base-url https://api.deepseek.com/v1 --model deepseek-chat --api-key sk-...
autoclip run talk.mp4 --srt talk.srt --category knowledge --min-score 0.6
autoclip run talk.mp4 --json # 给脚本 / agent：stdout 只有一个 JSON
autoclip list # 最近项目
autoclip show <project_id> # 切片、合集、文件路径
autoclip providers # 提供商与本地预设，标出当前用的
autoclip doctor --provider ollama # 按指定 provider 体检
autoclip mcp # 以 MCP server 运行（见下）
autoclip export <project_id> --preset douyin # 渲成 9:16 + 字幕 + 标题卡
autoclip export <project_id> --clip 2 --clip 5 --preset shorts --no-title
autoclip publish <project_id> --clip 2 --platform tiktok --platform youtube --wait # 经 Upload-Post 发到海外平台
autoclip publish --list-profiles # 已配置的 Upload-Post profile 与已连接平台
约定：
- 进度、说明走 stderr；stdout 只放
project_id（或--json时的 JSON），方便管道。 - 退出码：
0成功 ·1流水线失败 ·2参数 / 环境错误。 --provider等模型参数不改用户的正式设置，只在数据目录写一份cli-settings.json。- 视频默认硬链接进项目目录（不占双份空间），跨盘时自动复制；
--copy强制复制。 --no-db不写 SQLite（桌面应用里就看不到这个项目）。- 数据目录：默认与桌面应用一致（mac
~/Library/Application Support/AutoClip、Windows%APPDATA%\AutoClip、Linux~/.local/share/AutoClip），--data-dir或AUTOCLIP_DATA_DIR可换。日志在<数据目录>/logs/cli.log，-v同时打到终端。 --min-score覆盖 step3 的阈值（0–1，默认 0.7）；切片为 0 先试 0.5。
--json 输出（节选）：
{
"ok": true,
"project_id": "3f9c…",
"name": "talk",
"clips_dir": "…/projects/3f9c…/output/clips",
"clips": [
{"id": "2", "title": "为什么要做本地优先", "start_time": "00:12:03,000", "end_time": "00:14:40,000",
"score": 0.91, "score_100": 91, "reason": "…", "file": "…/2_为什么要做本地优先.mp4"}
],
"collections": [{"id": "1", "title": "产品哲学", "clip_ids": ["2", "5"], "file": "…/产品哲学.mp4"}],
"counts": {"clips": 6, "collections": 2},
"elapsed_sec": 412.3,
"llm": {"provider": "ollama", "model": "qwen2.5:7b", "base_url": "http://localhost:11434/v1"}
}
3. MCP server
stdio 传输，依赖 mcp Python SDK（requirements.txt 已锁定；兼容 1.x FastMCP 与 2.x MCPServer）。
Cursor（~/.cursor/mcp.json）或 Claude Desktop（claude_desktop_config.json）：
{
"mcpServers": {
"autoclip": { "command": "/path/to/autoclip/venv/bin/autoclip", "args": ["mcp"] }
}
}
Claude Code：
claude mcp add autoclip -- /path/to/autoclip/venv/bin/autoclip mcp
没装包时把 command 换成 /path/to/autoclip/venv/bin/python，args 为 ["-m", "backend.mcp_server"]，
并加 "env": {"PYTHONPATH": "/path/to/autoclip"}。
OpenCode（~/.config/opencode/opencode.json，或项目里的 opencode.json；带注释的 .jsonc 也支持）：
{
"mcp": {
"autoclip": { "type": "local", "command": ["/path/to/autoclip/venv/bin/autoclip", "mcp"], "enabled": true }
}
}
也可以让 AutoClip 自己写：autoclip mcp install opencode（--scope project --dir . 写项目配置、--print 只打印片段、
--force 在现有配置带注释时先备份再重写）。重装会保留同名条目里的 environment / timeout 等自定义字段；存在
opencode.jsonc 时优先写它，两份配置冲突会在写入前直接拒绝。接入后在 opencode 里给一个视频路径即可出片，详见 docs/OPENCODE.md。
工具：
| 工具 | 说明 |
|---|---|
clip_video(video_path, srt_path?, name?, category?, min_score?, provider?, model?, base_url?, api_key?) |
同步出片，期间通过 MCP progress 通知推进度；返回切片 / 合集 / 文件路径 |
start_clip_job(同上) |
后台出片，立刻返回 project_id（客户端对单次调用有超时时用） |
get_job_status(project_id) |
status queued / running / completed / failed，percent / stage / message，完成后带 result |
get_project(project_id) |
读已处理项目（含桌面应用建的） |
list_projects(limit=20) |
最近项目 |
list_providers() |
云端 provider + 本地预设 + 当前配置 |
check_environment(provider?, …) |
ffmpeg / Whisper / 模型连接体检 |
export_clip(project_id, clip_id, preset?, subtitles?, title_card?) |
渲可发布成片（douyin / xiaohongshu / shorts / bilibili / original） |
publish_clip(project_id, clip_id, platforms, user?, preset?, title?, description?, scheduled_date?, extra?) |
经 Upload-Post 发到 TikTok / Instagram / YouTube Shorts / X / LinkedIn 等；返回 request_id |
get_publish_status(request_id) / list_publish_profiles() |
各平台发布结果 / 可用 profile。配置与用法见 docs/PUBLISH_UPLOAD_POST.md |
实现要点：
- 流水线里散落着
print()，会污染 stdout 协议通道；server 启动时把sys.stdout指到 stderr，真正的 stdout 只交给 MCP 传输层。 - 全局 LLM 配置是进程级的，任务用
threading.Lock串行；start_clip_job连发会排队。 - 任务状态在内存里；server 重启后
get_job_status会退回从磁盘读项目结果。
Agent skill：skills/autoclip/SKILL.md 教 agent 何时用哪个工具、参数怎么选、结果怎么呈现、切片为 0 怎么办。
复制到 ~/.cursor/skills/autoclip/、~/.claude/skills/autoclip/ 或 ~/.config/opencode/skills/autoclip/ 即生效。
4. 本地模型预设（Ollama / LM Studio）
底层就是 OpenAI 兼容接口 + base_url，预设只是把地址和默认模型填好、把 key 变成可选：
| 预设 | 地址 | 默认模型 | 备注 |
|---|---|---|---|
ollama |
http://localhost:11434/v1 |
qwen2.5:7b |
ollama pull qwen2.5:7b；中文字幕分析效果稳定 |
lmstudio |
http://localhost:1234/v1 |
（以服务端列出的为准） | LM Studio 里加载模型并启动 Local Server |
设置页：模型提供商下拉多了「Ollama（本地）」「LM Studio（本地）」；选中后显示服务地址（可改端口 / 局域网机器）、
自动拉取 /v1/models 列出可选模型，隐藏 API Key。切回云端 provider 时模型名自动恢复为该 provider 的默认值。
后端：settings.json 里 llm_provider 存 ollama / lmstudio，LLMManager._apply_local_preset 在加载时解析成
openai + base_url，API key 用占位符 EMPTY（不会把用户的 OpenAI key 发给本地服务）。
get_current_provider_info() 同时返回展示用的 provider（预设名）和 backend_provider（openai）。
Docker / CLI 环境变量同样可用：LLM_PROVIDER=ollama LLM_MODEL=qwen2.5:7b（容器内访问宿主机用
OPENAI_BASE_URL=http://host.docker.internal:11434/v1）。
代理问题：macOS 上开着 Clash 等系统代理时，httpx 会把 localhost 请求也送进代理，表现为 502 / 超时。
llm_providers.is_local_url() 识别 loopback / 内网 / *.local / host.docker.internal 地址，
对这些地址创建 trust_env=False 的 httpx.Client，用户无需改代理规则。
相关 API（桌面模式）：
GET /api/v1/settings/local-presets— 预设列表GET /api/v1/settings/compatible-models?base_url=…— 列出兼容服务的模型POST /api/v1/settings/test-api—provider接受ollama/lmstudio
5. 测试
cd backend && python -m pytest tests/test_local_presets.py tests/test_cli.py -q
test_local_presets.py：预设解析、LLMManager 还原、test-api接受预设、本地地址绕过代理、is_local_urltest_cli.py：参数解析、--help子进程、项目目录准备与 SQLite 注册（隔离引擎）、结果汇总与评分归一、进度监听、MCP 工具注册test_upload_post_publisher.py：Upload-Post 配置优先级、multipart 表单、错误映射、状态归一化、CLI / MCP / API 注册（不联网）
真跑一次（需要 Ollama 或云端 key）：
autoclip run /path/to/talk.mp4 --provider ollama --min-score 0.5 --json