企业官网建设流程全解析

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/OpenCreator

KrillinAI 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），目标平台与架构支持环境变量覆盖：

1.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 "$WORKDIR"

test -f用于在真正执行前断言二进制已构建成功；WORKDIR指向独立的演示任务目录，避免把中间产物散落到仓库根目录。

二、执行工作目录与配置加载

2.1 配置的加载位置

CLI 以进程工作目录为基准加载config/config.toml。入口 cmd/cli/main.go 中，非 dry-run 的真实执行路径会先调用config.LoadConfig()，若找不到配置文件，直接返回config_not_found的 usage 错误。因此不同运行方式对工作目录的要求不同：

切换工作目录后，输入、字幕、音频与输出路径必须使用绝对路径的--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 命令总表

所有命令均支持-h/--help/help触发帮助文本（见 commands.go）。以下参数表直接取自命令帮助与解析实现（commands.go）。

3.2 subtitle

krillinai-cli subtitle <input> --origin-lang <lang> --target-lang <lang> --workdir <dir> [flags]

3.3 tts

krillinai-cli tts --workdir <dir> --input-srt <file> [flags]

3.4 speech

krillinai-cli speech (--text <text> | --text-file <file>) --output <file> [flags]

解析实现会强制校验：“--text与--text-file必须恰好提供一个”、“--output必填”、“--format仅允许 wav/mp3”、“--speed必须在 0.5 到 2 之间”（commands.go）。

3.5 render-horizontal / render-vertical

krillinai-cli render-horizontal --workdir <dir> --video <file> --subtitle <file> [flags] krillinai-cli render-vertical --workdir <dir> --video <file> --subtitle <file> [flags]

3.6 cover

krillinai-cli cover --workdir <dir> --prompt <text> [flags]

契约特别提醒：当前cover只接受完整文本提示词与尺寸，不要声称它消费了参考图。

3.7 pipeline 与 voices

krillinai-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 中已有的上游输出，而不是猜测文件名。默认输出路径契约如下：

横屏/竖屏配音变体实际写入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_CLI=1时，subtitle与tts会在终止响应前输出进度帧：

{"type":"progress","phase":"translating_subtitles","percent":50,"message":"正在翻译字幕"}

该机制的实现位于 cmd/cli/main.go：仅当OPENCREATOR_KRILLINAI_CLI=1时，通过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.go，Error.Retryable字段与kind == retryable保持一致。

六、退出码与错误分类

6.1 退出码约定

映射实现在 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 错误处理策略

真实失败场景中的错误码示例：audio_transcription_failed、prepare_media_failed、platform_caption_failed、source_video_missing（subtitle 流程，见 subtitle.go）、prompt_required（cover，见 cover.go）。错误码统一遵循kind+code+message三段结构，便于自动化程序稳定匹配。

七、Dry Run 语义差异

dry-run 并非所有命令行为一致，契约明确区分了三档：

dry-run 的实现集中在 commands.go：subtitle/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_CLI=1，因此面向桌面端的集成路径不要手工替换为源码树配置。

十、完整最小工作流示例

以下流程覆盖“从视频 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?v=VIDEO_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