核心用法
native-cli 是 QCut 内置的 TypeScript 管道命令行工具，通过 bun run pipeline 或 qcut-pipeline 调用，覆盖三大能力域：
1. AI 内容生成：图像生成 (generate-image)、视频生成 (create-video)、头像生成 (generate-avatar)、视频分析 (analyze-video)、语音转录 (transcribe)；
2. ViMax 智能视频生产：端到端工作流 idea2video、script2video、novel2movie，支持角色肖像注册与场景自动化；
3. 编辑器 HTTP 自动化：状态快照、事件流、事务控制、通知桥管理，实现确定性状态感知操作。
CLI 采用三级渐进式帮助系统（Root→Command→Parameter），统一 JSON 输出信封（ok/error/pending），并支持 --json 机器可读格式。API 密钥以 0600 权限存储于 ~/.qcut/.env，支持 10+ 主流 AI 服务商。
显著优点
- 全链路整合：从内容生成、视频分析到智能编辑、项目导出，单工具覆盖完整工作流；
- 确定性状态控制：
editor:state:*命令实现快照、事务、关联 ID 追踪，适合自动化代理场景； - ViMax 代理化生产：支持小说/脚本到视频的自动化转换，降低专业视频制作门槛；
- 结构化 I/O：
--json统一信封 +project.json可解析状态，便于 AI Agent 集成； - 安全密钥管理：文件权限严格控制，支持多服务商密钥模板化配置。
潜在缺点与局限性
- 本地依赖重：需预先构建并启动 QCut Electron 应用（
bun run build && bun run electron），无法纯 CLI 独立运行； - 网络与启动时延：编辑器健康检查失败时需等待 5s 启动，批量自动化场景下累积延迟显著；
- 状态耦合风险：
editor:*命令依赖运行中的编辑器实例，崩溃或状态漂移可能导致事务失败； - 异步任务追踪：
pending状态仅返回jobId，需额外轮询或监听事件流获取结果； - 平台锁定：深度绑定 QCut 生态，难以迁移至其他视频编辑工具。
适合人群
- AI 视频创作者：需快速将文本/脚本转为成片，利用 ViMax 降低分镜、拍摄、剪辑成本；
- 自动化工作流工程师：通过
--json输出与状态快照构建 CI/CD 式视频生产流水线； - QCut 重度用户：已在使用 QCut 编辑器，希望通过 CLI 批量管理项目、媒体、导出任务；
- 多模态 AI 开发者：需统一接口调用 Fal、Runway、Kling、HeyGen 等 10+ 模型，避免分散配置。
常规风险
- 密钥泄露：
~/.qcut/.env虽权限受限，但明文存储仍面临备份、共享场景下的意外暴露； - 状态丢失：编辑器崩溃或强制退出时，未提交的事务与快照可能损坏项目完整性；
- 成本失控：AI 视频生成按秒/按帧计费，
estimate-cost为估算值，实际费用可能因重试、参数调整超支； - 服务可用性：依赖 Fal、Runway 等第三方 API，密钥失效或额度耗尽会导致命令级联失败；
- 并发冲突：多进程同时调用
editor:*命令，可能触发竞态条件，需通过--session或外部锁机制协调。