OpenCreator KrillinAI CLI 契约详解构建、命令、JSON 协议与错误处理实战指南【免费下载链接】OpenCreatorFormerly KrillinAI. Open-source AI workspace for creators, powered by Codex. Create videos, images, voice, avatars, translations, and edits with Agents in one place.项目地址: https://gitcode.com/GitHub_Trending/kr/OpenCreatorKrillinAI CLI 是 OpenCreator前身 KrillinAI内置的 Go 命令行工具负责字幕生成、TTS 配音、横竖屏渲染、封面生成等视频创作流水线。本指南以仓库中 skills/krillinai-cli/references/cli-contract.md 为核心契约结合 命令行实现、入口逻辑 与 构建脚本 的源码证据完整讲解如何构建定位二进制、配置运行环境、逐条解析命令参数、读写 manifest、消费 JSON Lines 输出并正确分类与处理错误最终可直接用于 Agent 自动化编排或手工脚本集成。一、构建与二进制定位1.1 一键构建两个二进制从仓库根目录执行根package.json中注册的构建脚本见 package.json 的krillinai:build条目pnpm krillinai:build该命令会经由 scripts/build-krillinai.mjs 调用 Go 工具链同时构建两个目标runtime/krillinai/cmd/cli→ 生成krillinai-cli命令行入口runtime/krillinai/cmd/server→ 生成krillinai-server服务端从构建脚本源码可见scripts/build-krillinai.mjs目标平台与架构支持环境变量覆盖环境变量作用默认值OPENCREATOR_KRILLINAI_TARGET_PLATFORM交叉编译目标平台当前process.platformOPENCREATOR_KRILLINAI_TARGET_ARCH交叉编译目标架构当前process.archOPENCREATOR_KRILLINAI_BUILD_OUTPUT覆盖输出根目录.runtime/build/krillinai/platform-archOPENCREATOR_VERSION注入版本号读取apps/desktop/package.json的version1.2 产物布局原生二进制与 manifest 被写入Windows 下二进制带.exe后缀.runtime/build/krillinai/platform-arch/ ├── bin/krillinai-cli[.exe] ├── bin/krillinai-server[.exe] └── manifest.json其中manifest.json由构建脚本写入记录版本、源码 commit、源码树 SHA-256 与构建配方哈希可用于校验产物与源码的一致性。1.3 不假设平台与架构的定位方式为了在任意机器上稳定取到二进制路径契约给出了一套基于 Node 的通用定位片段REPO_ROOT$PWD TARGET$(node -p process.platform - process.arch) SUFFIX$(node -p process.platform win32 ? .exe : ) KRILLINAI_CLI$REPO_ROOT/.runtime/build/krillinai/$TARGET/bin/krillinai-cli$SUFFIX KRILLINAI_CWD$REPO_ROOT/runtime/krillinai WORKDIR$REPO_ROOT/tasks/demo test -f $KRILLINAI_CLI mkdir -p $WORKDIRtest -f用于在真正执行前断言二进制已构建成功WORKDIR指向独立的演示任务目录避免把中间产物散落到仓库根目录。二、执行工作目录与配置加载2.1 配置的加载位置CLI 以进程工作目录为基准加载config/config.toml。入口 cmd/cli/main.go 中非 dry-run 的真实执行路径会先调用config.LoadConfig()若找不到配置文件直接返回config_not_found的 usage 错误。因此不同运行方式对工作目录的要求不同运行场景工作目录配置来源源码检出runtime/krillinai从config-example.toml复制为被 gitignore 的config/config.toml仅配置当前阶段所需 provider发布压缩包解压后的包根目录从config/config-example.toml创建config/config.tomlOpenCreator 桌面端/Daemon隔离的启动器目录由 Daemon 自动准备不要用源码树配置替换该流程切换工作目录后输入、字幕、音频与输出路径必须使用绝对路径的--workdir、输入、字幕、音频、输出参数以避免相对路径解析歧义。2.2 完整配置示例解读config-example.toml 是配置的权威样例核心段落如下[app] segment_duration 5 # 音频切分处理间隔单位分钟建议值5-10 transcribe_parallel_num 1 # 并发转录上限建议 1-3本地模型建议 1 translate_parallel_num 3 # 并发翻译上限建议 3倍于转录 transcribe_max_attempts 3 # 转录最大尝试次数 translate_max_attempts 5 # 翻译最大尝试次数 max_sentence_length 70 # 每句最大字符数超过则拆分建议 50-70 enable_block_vtt_batch false # 是否启用块级 VTT 批量翻译 vtt_batch_size 10 # VTT 批量翻译批次大小 target_language_first true # 双语字幕中目标语言在上 short_subtitle_max_chars 20 # 短字幕英文每行最大字符数建议 15-25 proxy # 网络代理地址如 http://127.0.0.1:7890 [server] host 127.0.0.1 port 8888 [llm] # 支持 openai、deepseek、通义千问等所有兼容 OpenAI 请求格式的服务 base_url # 留空为 OpenAI 官方 API api_key model # 留空默认 gpt-4o-mini json false # 接口是否支持 JSON 输出格式不确定则保持 false [transcribe] # 视频转写可选 openai/fasterwhisper/whisperkit/whisper.cpp/aliyun provider openai enable_gpu_acceleration false # fasterwhisper 的 GPU 加速50 系显卡务必开启 [transcribe.openai] base_url api_key model whisper-1 [transcribe.fasterwhisper] model medium # tiny/medium/large-v2建议 medium 及以上 [transcribe.whisperkit] model large-v2 # 仅 M 芯片 [transcribe.whispercpp] model tiny # tiny/medium/large-v2 [transcribe.aliyun] # provider 选 aliyun 时 oss 与 speech 段都要填 [transcribe.aliyun.oss] access_key_id access_key_secret bucket [transcribe.aliyun.speech] access_key_id access_key_secret app_key [tts] provider aliyun # 可选 openai/aliyun/edge-tts/minimax [tts.openai] base_url api_key model # gpt-4o-mini-tts, tts-1, tts-1-hd [tts.minimax] # MiniMax TTS (T2A v2) base_url # 留空默认海外版 https://api.minimax.io api_key model # 留空默认 speech-2.8-hd [tts.aliyun] # 阿里云百炼语音合成仅 API Key 必填 base_url https://dashscope.aliyuncs.com/api/v1 api_key model qwen3-tts-flash [dubbing] # 配音合成控制 min_subtitle_duration 2.5 # 最短配音字幕时长短句优先合并 max_chunk_size 5 # 单个配音 chunk 最多合并字幕条数 gap_tolerance 1.5 # 可吸收的相邻字幕空隙秒 speed_min 0.95 # 允许的最慢调速倍率 speed_accept 1.15 # 推荐的最大自然调速倍率 speed_max 1.30 # 硬上限超过后优先改写文本 enable_text_rewrite true # 是否允许 LLM 改写为自然口播 rewrite_max_attempts 2 # 单条字幕最多改写次数 estimator statistical # 估时器当前支持 statistical [image] # 封面生图 provider openai-compatible # 当前支持 OpenAI Images API 兼容格式 [image.openai] base_url # 留空使用 OpenAI 官方接口转发站通常填以 /v1 结尾的地址 api_key model gpt-image-1注意下方不是所有段都必须填——只需按subtitle/tts/speech/cover等实际执行阶段配置对应的 provider 段。入口 main.go 中speech会校验 TTS 配置tts会校验 TTS 配置并检查 TTS 依赖subtitle在需要转录时校验转写配置配置缺失会以 usage 错误提前终止。三、命令一览与逐条参数解析3.1 命令总表命令用途subtitle生成源语言、目标语言、双语及短竖屏字幕tts生成 TTS 音频及可选配音视频speech由文本或 UTF-8 文本文件生成单个音频文件render-horizontal渲染横屏字幕/配音视频render-vertical渲染竖屏字幕/配音视频cover由完整文本提示词生成封面图voices列出aliyun、openai、minimax的语音码Edge TTS 无 CLI 语音目录pipeline以--dry-run校验输出计划非 dry-run 执行不支持status保留命令当前不支持所有命令均支持-h/--help/help触发帮助文本见 commands.go。以下参数表直接取自命令帮助与解析实现commands.go。3.2 subtitlekrillinai-cli subtitle input --origin-lang lang --target-lang lang --workdir dir [flags]Flag说明--origin-lang源语言如en、zh、ja--target-lang目标语言如zh_cn--user-lang生成消息的 UI 语言--workdir任务工作目录--task-id可选任务 ID--caption-sourceany、platform、manual、auto、whisper默认any--prepare-video下载原始视频供后续渲染使用--source-only仅生成源语言字幕不翻译--bilingual-top目标字幕在上方默认true--max-word-one-line每行字幕最大单词数--subtitle-style-fileJSON 字幕样式覆盖文件--dry-run校验命令而不调用外部服务3.3 ttskrillinai-cli tts --workdir dir --input-srt file [flags]Flag说明--input-srt待合成的 SRT 字幕文件必填--line-modetarget-only、bilingual-target-top或bilingual-target-bottom默认target-only--video可选的配音输出源视频--voiceprovider 特定的语音--voice-clone-source可选语音克隆源--dry-run校验并写 manifest不调用外部服务3.4 speechkrillinai-cli speech (--text text | --text-file file) --output file [flags]Flag说明--text/--text-file二选一必填--text-file要求 UTF-8 文本文件--output输出音频文件必填--provideraliyun、openai、minimax默认取当前配置--voiceprovider 特定语音--formatwav或mp3默认按输出扩展名推断--speed语速 0.5~2.0默认 1--instructionsprovider 支持时的口播指令解析实现会强制校验“--text与--text-file必须恰好提供一个”、“--output必填”、“--format仅允许 wav/mp3”、“--speed必须在 0.5 到 2 之间”commands.go。3.5 render-horizontal / render-verticalkrillinai-cli render-horizontal --workdir dir --video file --subtitle file [flags] krillinai-cli render-vertical --workdir dir --video file --subtitle file [flags]Flag说明--video输入视频--audio可选输入音频--subtitle要烧录的字幕文件--subtitle-style-fileJSON 字幕样式覆盖文件--dubbed渲染配音变体--major-title/--minor-title仅竖屏主标题/副标题--dry-run校验命令而不调用外部服务3.6 coverkrillinai-cli cover --workdir dir --prompt text [flags]Flag说明--prompt封面图提示词必填完整文本提示词--size图片尺寸如1024x1024或1536x1024--dry-run校验并写 manifest不产生媒体契约特别提醒当前cover只接受完整文本提示词与尺寸不要声称它消费了参考图。3.7 pipeline 与 voiceskrillinai-cli pipeline --outputs list [flags] krillinai-cli voices [flags]pipeline --outputs逗号分隔的输出列表如subtitle,tts,vertical-bilingual--async表示异步执行受支持时--dry-run校验请求的输出。解析时会对输出列表调用pipeline.PlanOutputs做合法性校验。voices --provider指定aliyun、openai、minimax或edge-tts列语音--dry-run返回相同本地语音列表而不调用外部服务。voices不接受位置参数。四、Manifest任务输出的唯一事实来源每个工作目录都应包含krillinai_manifest.json。真实阶段执行后manifest 与真实产物文件是唯一事实来源后续阶段应复用 manifest 中已有的上游输出而不是猜测文件名。默认输出路径契约如下输出键默认路径origin_videoworkdir/origin_video.mp4origin_audioworkdir/origin_audio.mp3origin_srtworkdir/origin_language_srt.srttarget_srtworkdir/target_language_srt.srtbilingual_srtworkdir/bilingual_srt.srtshort_origin_mixed_srtworkdir/short_origin_mixed_srt.srttts_audioworkdir/tts_final_audio.wavvideo_with_ttsworkdir/video_with_tts.mp4horizontal_videoworkdir/horizontal_bilingual.mp4vertical_videoworkdir/vertical_bilingual.mp4transferred_vertical_videoworkdir/transferred_vertical_video.mp4origin_coverworkdir/origin_cover.jpggenerated_coverworkdir/generated_cover.pngcover_promptworkdir/cover_prompt.final.txt横屏/竖屏配音变体实际写入horizontal_dubbed.mp4与vertical_dubbed.mp4但 manifest 键仍为horizontal_video与vertical_video——消费端必须按键读取而不是按文件名猜测。manifest 的生成与默认输出应用逻辑位于 runtime/krillinai/internal/pipeline/manifest.go并在 manifest_test.go 中有覆盖测试。五、JSON Lines 输出协议5.1 逐行解析原则stdout 必须按行解析为 JSON终止响应terminal response是包含ok字段的那个对象。任何错误消息都不会以人类可读文本混入 stdout。5.2 OpenCreator 进度帧当环境变量OPENCREATOR_KRILLINAI_CLI1时subtitle与tts会在终止响应前输出进度帧{type:progress,phase:translating_subtitles,percent:50,message:正在翻译字幕}该机制的实现位于 cmd/cli/main.go仅当OPENCREATOR_KRILLINAI_CLI1时通过configureOpenCreatorProgress包裹ReportProgress回调把阶段、百分比与消息序列化为{type:progress,...}行写出。进度帧的字段定义对应progressFrame结构type/phase/percent/message。5.3 成功与失败响应成功响应{ ok: true, stage: subtitle, workdir: tasks/demo, task_id: demo, outputs: {} }失败响应{ ok: false, error: { kind: retryable, code: audio_transcription_failed, message: connection timeout, retryable: true } }outputs对象内含 manifest 输出键如origin_srt、target_srt、tts_audio等可直接用于串联下一阶段。底层数据结构定义在 runtime/krillinai/internal/pipeline/types.goError.Retryable字段与kind retryable保持一致。六、退出码与错误分类6.1 退出码约定退出码含义0成功1用法错误usage2可重试错误retryable3依赖错误dependency映射实现在 types.go 的ExitCodeForError且有 types_test.go 的表格测试逐一验证usage→1、retryable→2、dependency→3。6.2 重要警告不能仅依赖退出码当前实现中内部错误internal也以退出码1退出因此分类必须以error.kind为准而不是只看退出码。入口 main.go 中writeAndExit在响应失败时用ExitCodeForError决定退出码但internal未在映射表中被区分会落入默认的1。6.3 错误处理策略error.kind处理建议usage修正 flag 或补齐缺失输入retryable延迟后重试或切换 provider/源dependency安装或暴露ffmpeg、ffprobe、yt-dlpinternal检查日志与生成的中间文件真实失败场景中的错误码示例audio_transcription_failed、prepare_media_failed、platform_caption_failed、source_video_missingsubtitle 流程见 subtitle.go、prompt_requiredcover见 cover.go。错误码统一遵循kindcodemessage三段结构便于自动化程序稳定匹配。七、Dry Run 语义差异dry-run 并非所有命令行为一致契约明确区分了三档命令dry-run 行为subtitle、render-horizontal、render-vertical、speech、pipeline仅校验不写任务 manifesttts、cover应用默认输出并写入krillinai_manifest.json但不产生媒体voices --dry-run返回相同本地语音列表不调用外部 providerdry-run 的实现集中在 commands.gosubtitle/render-*走dryRunResponse不落盘tts/cover走dryRunManifest会ApplyDefaultOutputs、MarkStage(..., dry-run)并Save()且对已存在文件以os.ErrExist容忍voices直接复用executeVoices。八、命令形态校验无凭据验证 CLI以下校验不需要任何 provider 凭据或媒体依赖可用于 CI 或集成前快速验证二进制形态与参数解析(cd $KRILLINAI_CWD $KRILLINAI_CLI subtitle local:demo.mp4 \ --origin-lang en \ --target-lang zh_cn \ --workdir $WORKDIR \ --dry-run)期望返回{ok:true,stage:subtitle,...}的终止响应退出码为0。对渲染类命令可进一步检查产物文件并用ffmpeg提取预览帧目检。入口 main.go 表明 dry-run 分支在配置加载与依赖检查之前短路执行这也是它能脱离凭据与ffmpeg独立运行的根本原因。九、与上层技能及 OpenCreator 的衔接仓库在 skills/krillinai-cli/SKILL.md 中把 CLI 定位为“KrillinAI 命令行工作的顶层路由技能”并给出意图到命令/子技能的映射字幕 →krillinai-subtitle配音 →krillinai-tts横屏 →krillinai-render-horizontal竖屏 →krillinai-render-vertical封面 →krillinai-cover多阶段计划 →krillinai-pipeline。各子技能文档位于 skills 目录可作为单阶段深化参考。对 Agent 的运维规则同样适用于人工脚本使用独立--workdir不要把输出散落到仓库根目录外部调用前先用--dry-run校验命令形态stdout 按 JSON Lines 解析终止响应是含ok的对象真实阶段后以 manifest 与产物文件为准复用上游输出避免重复运行昂贵阶段失败时按error.kind分类处置。在 OpenCreator 整体架构中Daemon 会为 CLI 准备隔离的启动器目录与配置并自动注入OPENCREATOR_KRILLINAI_CLI1因此面向桌面端的集成路径不要手工替换为源码树配置。十、完整最小工作流示例以下流程覆盖“从视频 URL 出字幕 → 竖屏渲染”整合了技能文档中的最小工作流与契约中的目录约定REPO_ROOT$PWD TARGET$(node -p process.platform - process.arch) SUFFIX$(node -p process.platform win32 ? .exe : ) KRILLINAI_CLI$REPO_ROOT/.runtime/build/krillinai/$TARGET/bin/krillinai-cli$SUFFIX WORKDIR$REPO_ROOT/tasks/demo mkdir -p $WORKDIR (cd $REPO_ROOT/runtime/krillinai $KRILLINAI_CLI subtitle \ https://www.youtube.com/watch?vVIDEO_ID \ --origin-lang en \ --target-lang zh_cn \ --workdir $WORKDIR \ --caption-source any \ --prepare-video) (cd $REPO_ROOT/runtime/krillinai $KRILLINAI_CLI render-vertical \ --workdir $WORKDIR)第一步结束后从$WORKDIR/krillinai_manifest.json读取bilingual_srt/origin_video等键作为下游输入第二步渲染竖屏双语成片。整个链路的输出键、JSON 协议与退出码语义均以本文所整理的契约与源码实现为准。【免费下载链接】OpenCreatorFormerly KrillinAI. Open-source AI workspace for creators, powered by Codex. Create videos, images, voice, avatars, translations, and edits with Agents in one place.项目地址: https://gitcode.com/GitHub_Trending/kr/OpenCreator创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考