OpenCreator KrillinAI Pipeline 技能：多阶段 CLI 产物计划校验与分步执行的工程实践

原创2026-09-14 12:16:531,078 阅读

文章标签：人工智能AI 应用AI AgentAI 技能媒体生成音视频桌面应用

OpenCreator KrillinAI Pipeline 技能：多阶段 CLI 产物计划校验与分步执行的工程实践

导读

krillinai-pipeline 是 OpenCreator 仓库中面向 Agent 的官方技能（Skill），用于校验多阶段 KrillinAI CLI 输出计划（output plan），并指导将合法计划拆解为独立的 subtitle、tts、render-horizontal、render-vertical、cover 阶段命令逐一执行。当前实现中 pipeline 命令只支持 --dry-run 计划校验，不支持端到端执行（非 dry-run 会返回 unsupported_command）。读完本文，你将掌握：如何用 --outputs 声明产物计划、各输出名到执行阶段的映射规则、如何借助 krillinai_manifest.json 实现断点续跑与故障恢复，以及 Agent 落地时的验证与验收标准。技能原文见 skills/krillinai-pipeline/SKILL.md。

一、技能定位与使用前提

该技能由 SKILL.md 的 frontmatter 声明：当需要校验或记录多阶段 KrillinAI CLI 输出计划时使用，同时明确标注"当前 pipeline 命令仅支持 dry-run 计划规划，不支持端到端执行"。因此 Agent 的正确用法是：

用 pipeline --dry-run 完成计划合法性校验（输出名拼写、阶段可映射性）；
用真实工作通过各阶段独立命令完成（subtitle、tts、render-horizontal、render-vertical、cover）；
全程遵循 skills/krillinai-cli/SKILL.md 的构建、定位二进制与操作规则，细节契约见 skills/krillinai-cli/references/cli-contract.md。

构建二进制统一使用仓库根目录脚本（见根目录 package.json 中的 krillinai:build 任务）：

pnpm krillinai:build

产物落在 .runtime/build/krillinai/<platform>-<arch>/，其中 <platform>-<arch> 形如 linux-x64、darwin-arm64，Windows 平台二进制带 .exe 后缀：

.runtime/build/krillinai/<platform>-<arch>/
├── bin/krillinai-cli[.exe]
├── bin/krillinai-server[.exe]
└── manifest.json

二、计划校验：`pipeline --outputs ... --dry-run`

技能给出的标准校验命令如下（注意使用子 shell 切换工作目录到 KrillinAI 源码目录，并使用绝对路径环境变量）：

(cd "$KRILLINAI_CWD" && "$KRILLINAI_CLI" pipeline \
  --outputs "subtitle,tts,vertical-bilingual" \
  --dry-run)

其中：

KRILLINAI_CWD 应指向源码检出目录 runtime/krillinai——CLI 会相对于进程工作目录加载 config/config.toml（源码检出下需从 config/config-example.toml 复制生成，配置示例见 runtime/krillinai/config/config-example.toml）；
KRILLINAI_CLI 指向按平台解析出的 krillinai-cli 二进制绝对路径；
--outputs 传入逗号分隔的产物名列表；
--dry-run 只做校验，不执行任何阶段，也不写入任务 manifest。

--outputs 与 --async 的解析在 runtime/krillinai/internal/cli/commands.go 的 parsePipeline 中完成：--outputs 默认值为 "subtitle"，解析后立即调用 pipeline.PlanOutputs 做合法性检查，不合法直接返回参数错误。dry-run 分支（dryRun 函数中 case "pipeline"）直接返回 {"ok": true, "stage": "pipeline"} 形式的成功响应，不触碰 manifest。

三、Outputs 取值与阶段映射

技能文档给出的 outputs 枚举与对应阶段如下：

Output	Stage
`subtitle`	Generate subtitle files
`tts`	Generate dubbing
`horizontal-bilingual`	Render landscape bilingual video
`horizontal-dubbed`	Render landscape dubbed video
`vertical-bilingual`	Render portrait bilingual video
`vertical-dubbed`	Render portrait dubbed video
`cover`	Generate cover

该映射表与源码实现完全一致。在 runtime/krillinai/internal/pipeline/pipeline.go 的 PlanOutputs 中，字符串按逗号切分、去空白后逐个 switch：

subtitle → StageSubtitle；
tts → StageTTS；
horizontal-bilingual、horizontal-dubbed → StageRenderHorizontal；
vertical-bilingual、vertical-dubbed → StageRenderVertical；
cover → StageCover；
空串被静默跳过；
其余任何值返回错误 unsupported output: <name>。

注意两个关键事实：

横竖屏的双语版与配音版映射到同一个渲染阶段，区别只体现在渲染参数（--dubbed）与产物文件名上（见下文 manifest 一节）；
校验由单测覆盖：TestPlanOutputsMapsToStages 验证了六产物全量列表的映射顺序，TestPlanOutputsRejectsUnsupportedOutput 验证了 "subtitle,unknown" 会被拒绝（见 runtime/krillinai/internal/pipeline/pipeline_test.go）。

dry-run 校验只验证输出名合法并返回成功的 pipeline-stage JSON 响应，不执行任何阶段，也不写任务 manifest。也就是说，它无法代替真实阶段的验证——subtitle 是否真的产出了 SRT、渲染是否真的烧录成功，都必须通过独立执行各阶段命令并检查产物来确认。

四、把计划拆解为独立阶段命令

技能明确要求：将校验通过的 outputs 映射到 subtitle、tts、render-horizontal、render-vertical、cover 五个真实命令，每个所需命令独立运行，并且所有命令使用同一个绝对路径 --workdir。

4.1 各阶段命令与关键参数

依据 skills/krillinai-cli/references/cli-contract.md 与 runtime/krillinai/internal/cli/commands.go 中的 Help 输出，五个阶段命令的核心用法如下：

subtitle —— 生成源语言、目标语言、双语及短视频字幕

(cd "$KRILLINAI_CWD" && "$KRILLINAI_CLI" subtitle <input> \
  --origin-lang en --target-lang zh_cn --workdir "$WORKDIR" [flags])

关键 flag：--user-lang（消息 UI 语言）、--caption-source（可选 any/platform/manual/auto/whisper，默认 any）、--prepare-video（下载原视频供后续渲染）、--source-only（只出源语言字幕不翻译）、--bilingual-top（目标字幕在上，默认 true）、--max-word-one-line（每行最大词数）、--subtitle-style-file（JSON 字幕样式覆盖文件）。

tts —— 从 SRT 生成目标语言配音

(cd "$KRILLINAI_CWD" && "$KRILLINAI_CLI" tts \
  --workdir "$WORKDIR" --input-srt <file> [flags])

关键 flag：--line-mode（target-only/bilingual-target-top/bilingual-target-bottom，默认 target-only）、--video（可选，产出配音版成片）、--voice、--voice-clone-source。parseTTS 强制要求 --input-srt 非空。

render-horizontal / render-vertical —— 渲染横屏/竖屏字幕版或配音版

(cd "$KRILLINAI_CWD" && "$KRILLINAI_CLI" render-vertical \
  --workdir "$WORKDIR" --video <file> --subtitle <file> [flags])

共同 flag：--audio（可选）、--dubbed（渲染配音版）、--subtitle-style-file；竖屏额外支持 --major-title / --minor-title。源码中 parseRender 以 horizontal 布尔值区分两个命令，Execute 中二者都走 pipeline.Render（见 commands.go 的 parseRender/Execute）。

cover —— 从完整文本提示词生成封面

(cd "$KRILLINAI_CWD" && "$KRILLINAI_CLI" cover \
  --workdir "$WORKDIR" --prompt "<完整提示词>" [flags])

关键 flag：--size（如 1024x1024 或 1536x1024）。parseCover 强制要求 --prompt 非空；注意当前 CLI 只接受完整文本提示词与尺寸，不消费参考图。

4.2 真实工作前先做命令形态验证

技能与 CLI 契约都建议在调用外部服务前先用 dry-run 校验命令形态（不需要 provider 凭据或媒体依赖）：

(cd "$KRILLINAI_CWD" && "$KRILLINAI_CLI" subtitle local:demo.mp4 \
  --origin-lang en --target-lang zh_cn \
  --workdir "$WORKDIR" --dry-run)

dry-run 行为存在差异（见 cli-contract.md 的 Dry Run 一节，与 commands.go 中 dryRun 函数对应）：

subtitle、render-horizontal、render-vertical、speech、pipeline：只校验，不写 manifest；
tts、cover：dry-run 会应用默认产物路径并写入 krillinai_manifest.json，但不产生媒体文件；
voices --dry-run：返回本地音色列表，不发起外部调用（支持 aliyun、openai、minimax）。

五、任务清单（manifest）与断点恢复

5.1 manifest 结构与默认产物路径

每个工作目录下都应维护 krillinai_manifest.json。其结构定义在 runtime/krillinai/internal/pipeline/manifest.go：包含 task_id、workdir、input_url、语言与字幕来源、outputs（产物路径映射）、warnings、failed_indexes 以及 stages（各阶段状态 {ok, error, updated}）。写入采用临时文件 + rename 的原子替换策略，避免半成品覆盖。

ApplyDefaultOutputs 规定的默认产物路径（均为 <workdir> 下）如下：

Output key	默认路径
`origin_video`	`<workdir>/origin_video.mp4`
`origin_audio`	`<workdir>/origin_audio.mp3`
`origin_srt`	`<workdir>/origin_language_srt.srt`
`target_srt`	`<workdir>/target_language_srt.srt`
`bilingual_srt`	`<workdir>/bilingual_srt.srt`
`short_origin_mixed_srt`	`<workdir>/short_origin_mixed_srt.srt`
`tts_audio`	`<workdir>/tts_final_audio.wav`
`video_with_tts`	`<workdir>/video_with_tts.mp4`
`horizontal_video`	`<workdir>/horizontal_bilingual.mp4`
`vertical_video`	`<workdir>/vertical_bilingual.mp4`
`transferred_vertical_video`	`<workdir>/transferred_vertical_video.mp4`
`origin_cover`	`<workdir>/origin_cover.jpg`
`generated_cover`	`<workdir>/generated_cover.png`
`cover_prompt`	`<workdir>/cover_prompt.final.txt`

横竖屏的配音版产物文件名为 horizontal_dubbed.mp4 / vertical_dubbed.mp4，但其 manifest 键仍为 horizontal_video / vertical_video；另外 output/origin_language.txt、output/target_language.txt 存放转录文本。恢复策略的第一原则就是：先读 krillinai_manifest.json 定位各阶段产物，复用上游输出而不是猜测文件名或重复昂贵工作。

5.2 技能给出的恢复策略

subtitle 成功但渲染失败：只重跑渲染阶段，使用相同的 --workdir，不要重跑字幕生成；
TTS 失败：保留字幕产物，修复 provider 配置（如 config-example.toml 中的 [tts] 段，支持 aliyun、openai、edge-tts、minimax）后仅重跑 tts；
任何重跑前先读 krillinai_manifest.json，确认哪些上游阶段已成功、产物路径是否有效，避免重复执行耗时阶段（转录、翻译、生图）。

5.3 输出协议与错误分类

CLI 的 stdout 是 JSON Lines 协议：逐行解析为 JSON，含 ok 字段的对象即终止响应。OpenCreator 模式（OPENCREATOR_KRILLINAI_CLI=1）下 subtitle/tts 会在终止响应前先发进度帧：

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

成功形状：

{
  "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
  }
}

退出码语义：0 成功、1 用法错误、2 可重试错误、3 依赖错误（ffmpeg/ffprobe/yt-dlp 缺失）。注意当前内部错误也以 1 退出，因此必须结合 error.kind 分类而非只看退出码：usage 修参数、retryable 延时重试或换 provider、dependency 安装/暴露外部工具、internal 检查日志与产物。

六、验证与验收标准

技能规定了严格的验证闭环，这是 Agent 交付可靠性的关键：

计划校验：dry-run 必须返回终止 JSON 且 "ok": true；
真实执行：确认每个独立执行的阶段命令均成功（每个阶段响应 ok: true）；
清单核对：确认 manifest 中登记的 stages 与请求的输出文件确实存在，不能只信计划响应；
成品检查：检查最终请求的媒体/封面文件（如 horizontal_bilingual.mp4、vertical_bilingual.mp4、generated_cover.png），而不只是中间产物；
渲染产物可进一步用 ffmpeg 抽取预览帧人工核验字幕烧录效果。

技能的核心立场是：dry-run 只是命令形态与产物名合法的"计划层"证据，真实产物必须靠各阶段独立执行 + manifest + 成品文件三重确认。这与 pipeline 命令"仅规划、不执行"的设计互相印证——在自动化的多阶段视频生产中，把计划校验与真实执行分离，配合 manifest 驱动断点续跑，能显著降低昂贵阶段（转录、翻译、配音、渲染）的重复开销与失败放大效应。

七、适用前提与限制

pipeline 命令当前只支持 dry-run 计划校验，任何非 dry-run 调用会返回 unsupported_command（见 commands.go 中 Execute 的 default 分支返回的 unsupported_command 错误码）；status 命令为保留面，同样不支持；
真实运行需要先准备 config/config.toml（源码检出下复制 config-example.toml 并按需配置 [llm]、[transcribe]、[tts]、[image] 等 provider 段）；
在 OpenCreator 桌面/守护进程集成场景下，Daemon 会自动准备独立的启动器目录与配置，不要用源码树配置替代该流程；
任何跨平台细节（.exe 后缀、平台目录名）以 .runtime/build/krillinai/ 下实际产物与 cli-contract.md 的定位脚本为准。

登录后查看全文

人工智能AI 应用AI AgentAI 技能媒体生成音视频桌面应用

OpenCreator

OpenCreator KrillinAI Pipeline 技能：多阶段 CLI 产物计划校验与分步执行的工程实践

OpenCreator KrillinAI Pipeline 技能：多阶段 CLI 产物计划校验与分步执行的工程实践

导读

一、技能定位与使用前提

二、计划校验：pipeline --outputs ... --dry-run

三、Outputs 取值与阶段映射

四、把计划拆解为独立阶段命令

4.1 各阶段命令与关键参数

4.2 真实工作前先做命令形态验证

五、任务清单（manifest）与断点恢复

5.1 manifest 结构与默认产物路径

5.2 技能给出的恢复策略

5.3 输出协议与错误分类

六、验证与验收标准

七、适用前提与限制

相关推荐

热门文章

二、计划校验：`pipeline --outputs ... --dry-run`