核心用法
native-cli 是 QCut 桌面视频编辑器的底层命令行接口，基于 Bun + TypeScript 构建，提供三类核心能力：
1. AI 媒体生成：集成多模态模型（Kling、Veo3、OmniHuman 等）生成图像、视频、虚拟形象；支持成本估算、模型列表查询及 API 密钥管理。
2. 流水线编排：通过 YAML 定义多步骤 AI 工作流，实现从创意到成片的自动化处理；内置 ViMax 引擎支持 idea2video、script2video、novel2movie 等 Agentic 视频生产模式。
3. 编辑器状态控制：以确定性方式操控 QCut 编辑器——包括项目导航、媒体管理、时间轴导出，以及通过 HTTP 端点实现状态快照、事件流、事务管理和通知桥接，适用于需要精确状态同步的自动化场景。
显著优点
- 统一入口：单条命令覆盖从 AI 生成到视频编辑的全链路，避免多工具切换。
- 状态感知：
editor:*命令具备内置健康检查与项目发现机制，降低脚本编写复杂度。 - 安全密钥管理：API 密钥存储于
~/.qcut/.env并强制 0600 权限，支持交互式配置与批量检测。 - 流式反馈：
--stream输出 JSONL 进度事件，便于集成到 CI/CD 或外部监控系统。 - 生产就绪：同时提供开发（
bun run pipeline）、源码（直接执行.ts）及生产二进制（qcut-pipeline）三种调用模式。
潜在缺点与局限性
- 强绑定 QCut 桌面端：
editor:*命令依赖本地 Electron 应用运行，无法独立作为纯 SaaS CLI 使用。 - Bun 运行时依赖：非 Node.js 原生，需额外安装 Bun 环境，增加部署门槛。
- 文档分散：功能拆分为多个 Markdown 文件（REFERENCE.md、editor-core.md 等），新手需跨文件查阅。
- 无沙箱隔离：AI 生成任务直接调用外部 API（FAL、Runway 等），无内置速率限制或成本熔断机制，误操作可能导致高额账单。
- YAML 流水线调试困难：错误定位依赖
--verbose日志，缺乏可视化调试工具。
适合人群
- 视频创作者/工作室：需要批量生成 AI 素材并自动导入剪辑工程。
- 自动化工程师：需将 QCut 集成到自研 CMS 或 MAM 系统，实现项目模板的程序化操控。
- AI 工作流开发者：基于 ViMax 构建从脚本到成片的端到端视频生产管线。
常规风险
- API 密钥泄露：
.env文件若被备份工具同步至云端，可能导致密钥外泄；建议配合gitignore与文件系统监控。 - 状态竞争：多进程同时调用
editor:*命令可能引发事务冲突，需自行实现分布式锁或串行队列。 - 生成内容合规性：AI 生成视频可能涉及版权、肖像权及平台政策风险，建议启用人工审核节点。
- 长时间任务中断：视频生成任务（如 ViMax 120 秒影片）可能因网络波动失败，需设计断点续传或幂等重试策略。