核心用法
native-cli 是 QCut 内置的 TypeScript 流水线命令行工具，可通过 bun run pipeline 或 qcut-pipeline 调用。核心功能分为五大类：
1. AI 内容生成：图像生成 (generate-image)、视频创建 (create-video)、虚拟形象 (generate-avatar)、成本估算 (estimate-cost)，支持 Kling、Veo3、OmniHuman 等多模型。
2. 视频分析：视频分析摘要 (analyze-video)、音频转录 (transcribe)，支持 SRT 字幕输出。
3. YAML 流水线编排：通过 run-pipeline 执行声明式配置，支持批量处理与自动化工作流。
4. ViMax Agentic 视频制作：idea2video 将创意转为完整视频，script2video 基于结构化脚本生成，novel2movie 支持长文本分镜改编，配合肖像注册实现角色一致性。
5. 编辑器状态控制：通过 HTTP 自动化实现确定性状态感知，包括项目导航 (navigator:*)、媒体管理 (media:*)、时间线操作 (timeline:*)、状态快照 (project:info/export-state)、事件流与通知桥控制。
显著优点
- 原生集成深度：直接操作 QCut 编辑器内部状态，非外部 API 调用，延迟极低且状态一致
- 结构化输出全链路：所有命令支持
--json，统一ok/error/pending信封格式，便于程序解析 - 三级渐进式帮助：
--help --json提供根级、命令级、参数级结构化文档，自动生成工具友好 - Agent 可读项目状态：
project.json导出完整项目结构（~2000 tokens），支持 AI 直接理解与操作 - 会话模式支持：
--session支持 STDIN 批处理，适合长流程自动化 - ViMax 端到端：从创意到成片的全自动视频生产链路，内置角色肖像管理
潜在缺点与局限性
- 强运行时依赖：所有
editor:*命令要求 QCut 桌面应用运行，需手动检查/启动（curl health+bun run electron） - ID 发现链路长：操作需先获取
project-id/media-id/element-id，新手需多步查询 - 密钥管理分散：10+ 外部 API 密钥需单独配置，无统一凭证托管
- 异步任务状态追踪：
pending状态返回 jobId，但文档未明确查询机制 - Electron 进程耦合：构建与启动步骤涉及 Node/Bun/Electron 三层，环境配置复杂
适合人群
- 自动化视频工作流开发者：需批量处理、CI/CD 集成、无人值守生成
- AI 视频产品团队：利用 ViMax 快速原型从创意到成片
- 高级 QCut 用户：需超越 GUI 的细粒度控制与状态导出
- Agent/工具构建者：通过结构化 JSON 接口与项目状态实现 AI 驱动编辑
常规风险
- 本地服务暴露：
127.0.0.1:8765HTTP 端点若在其他网络接口暴露，可能导致未授权控制 - 密钥文件权限：
~/.qcut/.env建议0600，但依赖用户自觉，泄露风险较高 - Electron 后台进程管理：
&后台启动若未妥善监控，可能产生僵尸进程或端口占用 - 异步任务中断：生成任务（尤其视频）耗时长，进程终止可能导致资源悬空或计费损失
- 状态操作不可逆：
timeline:*等编辑命令直接修改项目，无显式撤销/事务回滚机制