Skip to content

Formerly KrillinAI, VideoTranslation and Dubbing Tool for 120+ Languages. Open-source AI workspace for creators, powered by Codex. Video downloader, video translation, create videos, images, audios, and edits with Agents in one place. For your Social Media like YouTube, TikTok, Instagram, etc.

chore: untrack local superpowers docs

wulien0efd7888fef5
diff --git a/docs/superpowers/plans/2026-05-28-krillinai-cli-implementation.md b/docs/superpowers/plans/2026-05-28-krillinai-cli-implementation.md
deleted file mode 100644
index 91535d1a..00000000
--- a/docs/superpowers/plans/2026-05-28-krillinai-cli-implementation.md
+++ /dev/null
@@ -1,2066 +0,0 @@
-# KrillinAI CLI Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** 为 KrillinAI 增加阶段化 CLI,使 Agent 能稳定调用字幕生成、TTS、横屏渲染、竖屏渲染、封面生成和完整 pipeline。
-
-**Architecture:** 新增 `internal/pipeline` 作为同步 Pipeline Core,负责 manifest、阶段请求、产物路径、回退策略和 JSON 结果;新增 `internal/cli` 和 `cmd/cli` 作为命令行入口;在 `internal/service` 中增加薄导出包装,复用现有下载、字幕、TTS、渲染逻辑。第一批完成字幕/TTS/横竖屏/pipeline 的可运行闭环,封面接口随后接入。
-
-**Tech Stack:** Go 1.22、标准库 `flag`/`encoding/json`/`os/exec`、现有 `internal/service`、`internal/types`、`config`、`deps`、`yt-dlp`、`ffmpeg`、`ffprobe`。
-
----
-
-## 文件结构
-
-新增文件:
-
-- `cmd/cli/main.go`:CLI 二进制入口,初始化日志、加载配置、检查依赖、分发命令。
-- `internal/cli/commands.go`:子命令解析和执行分发,保持 CLI 参数处理与 pipeline 业务分离。
-- `internal/cli/commands_test.go`:验证参数解析、退出码映射、JSON 输出。
-- `internal/pipeline/types.go`:阶段枚举、请求结构、响应结构、错误结构、产物结构、字幕来源和 line-mode 常量。
-- `internal/pipeline/manifest.go`:manifest 读写、路径补齐、阶段状态更新。
-- `internal/pipeline/manifest_test.go`:manifest 读写和参数覆盖测试。
-- `internal/pipeline/srt.go`:SRT block 解析、双语字幕目标行抽取、目标 SRT 写入。
-- `internal/pipeline/srt_test.go`:line-mode 和多行字幕测试。
-- `internal/pipeline/workdir.go`:任务 ID、工作目录创建、输入路径规范化。
-- `internal/pipeline/workdir_test.go`:workdir 默认值和显式路径测试。
-- `internal/pipeline/service_adapter.go`:把现有 `service.Service` 适配成 pipeline 阶段接口。
-- `internal/pipeline/subtitle.go`:字幕阶段编排,包含平台字幕优先和回退转录策略。
-- `internal/pipeline/subtitle_test.go`:字幕来源策略和回退语义测试。
-- `internal/pipeline/tts.go`:TTS 阶段编排,支持 `--line-mode` 和 `--input-srt`。
-- `internal/pipeline/tts_test.go`:TTS 输入抽取、失败 index 记录测试。
-- `internal/pipeline/render.go`:横屏/竖屏渲染阶段编排,显式输出 bilingual/dubbed 文件名。
-- `internal/pipeline/render_test.go`:渲染请求、输出命名、竖屏警告测试。
-- `internal/pipeline/cover.go`:封面阶段接口和 prompt 模板渲染。
-- `internal/pipeline/cover_test.go`:prompt 变量替换和 provider 请求测试。
-- `internal/pipeline/pipeline.go`:完整 pipeline 编排。
-- `internal/pipeline/pipeline_test.go`:输出集合到阶段顺序的映射测试。
-- `internal/service/stage_exports.go`:导出既有 service 阶段能力的薄包装。
-- `internal/service/render_stage.go`:从现有 `srt_embed.go` 抽出可指定输入字幕和输出文件名的渲染函数。
-- `internal/service/render_stage_test.go`:验证渲染命令构造,不跑真实 ffmpeg。
-- `pkg/image/openai_compatible.go`:OpenAI-compatible image provider 客户端。
-- `pkg/image/openai_compatible_test.go`:image 请求 JSON 和错误处理测试。
-
-修改文件:
-
-- `config/config.go`:新增 `[image]` 配置结构;保留现有默认配置行为。
-- `config/config-example.toml`:新增 image provider 示例配置。
-- `internal/service/srt_embed.go`:让原有 `embedSubtitles` 复用新的指定字幕渲染函数。
-- `internal/service/subtitle_service.go`:后续可迁移到 Pipeline Core;第一批只修正 YouTube fallback 行为时需要最小改动。
-- `.goreleaser.yaml`:增加 CLI build。
-- `README.md` 和 `docs/zh/README.md`:增加 CLI 快速使用说明。
-
----
-
-### Task 1: 定义 Pipeline 基础类型和 JSON 响应
-
-**Files:**
-- Create: `internal/pipeline/types.go`
-- Test: `internal/pipeline/types_test.go`
-
-- [ ] **Step 1: 写失败测试**
-
-```go
-package pipeline
-
-import (
- "encoding/json"
- "testing"
-)
-
-func TestResponseJSONShape(t *testing.T) {
- resp := Response{
- OK: true,
- Stage: StageSubtitle,
- Workdir: "tasks/demo",
- TaskID: "demo",
- Outputs: Outputs{
- OriginSRT: "tasks/demo/origin_language_srt.srt",
- TargetSRT: "tasks/demo/target_language_srt.srt",
- BilingualSRT: "tasks/demo/bilingual_srt.srt",
- },
- Warnings: []string{"人工字幕未找到,使用自动字幕"},
- DurationMS: 123,
- }
-
- data, err := json.Marshal(resp)
- if err != nil {
- t.Fatalf("Marshal() error = %v", err)
- }
-
- var got map[string]any
- if err := json.Unmarshal(data, &got); err != nil {
- t.Fatalf("Unmarshal() error = %v", err)
- }
- if got["ok"] != true {
- t.Fatalf("ok = %v, want true", got["ok"])
- }
- if got["stage"] != "subtitle" {
- t.Fatalf("stage = %v, want subtitle", got["stage"])
- }
- outputs := got["outputs"].(map[string]any)
- if outputs["bilingual_srt"] != "tasks/demo/bilingual_srt.srt" {
- t.Fatalf("bilingual_srt = %v", outputs["bilingual_srt"])
- }
-}
-
-func TestExitCodeForErrorKind(t *testing.T) {
- cases := []struct {
- err *Error
- want int
- }{
- {&Error{Kind: ErrorKindUsage}, 1},
- {&Error{Kind: ErrorKindRetryable}, 2},
- {&Error{Kind: ErrorKindDependency}, 3},
- }
- for _, tc := range cases {
- if got := ExitCodeForError(tc.err); got != tc.want {
- t.Fatalf("ExitCodeForError(%q) = %d, want %d", tc.err.Kind, got, tc.want)
- }
- }
-}
-```
-
-- [ ] **Step 2: 运行测试确认失败**
-
-Run: `go test ./internal/pipeline -run 'TestResponseJSONShape|TestExitCodeForErrorKind' -count=1`
-
-Expected: FAIL,错误包含 `undefined: Response`、`undefined: StageSubtitle` 或 `undefined: ExitCodeForError`。
-
-- [ ] **Step 3: 实现基础类型**
-
-```go
-package pipeline
-
-type Stage string
-
-const (
- StageSubtitle Stage = "subtitle"
- StageTTS Stage = "tts"
- StageRenderHorizontal Stage = "render-horizontal"
- StageRenderVertical Stage = "render-vertical"
- StageCover Stage = "cover"
- StagePipeline Stage = "pipeline"
-)
-
-type CaptionSource string
-
-const (
- CaptionSourceAny CaptionSource = "any"
- CaptionSourceManual CaptionSource = "manual"
- CaptionSourceAuto CaptionSource = "auto"
- CaptionSourceWhisper CaptionSource = "whisper"
-)
-
-type LineMode string
-
-const (
- LineModeTargetOnly LineMode = "target-only"
- LineModeBilingualTargetTop LineMode = "bilingual-target-top"
- LineModeBilingualTargetBottom LineMode = "bilingual-target-bottom"
-)
-
-type ErrorKind string
-
-const (
- ErrorKindUsage ErrorKind = "usage"
- ErrorKindRetryable ErrorKind = "retryable"
- ErrorKindDependency ErrorKind = "dependency"
- ErrorKindInternal ErrorKind = "internal"
-)
-
-type Error struct {
- Kind ErrorKind `json:"kind"`
- Code string `json:"code"`
- Message string `json:"message"`
- Retryable bool `json:"retryable"`
-}
-
-func (e *Error) Error() string {
- if e == nil {
- return ""
- }
- return e.Message
-}
-
-func ExitCodeForError(err *Error) int {
- if err == nil {
- return 0
- }
- switch err.Kind {
- case ErrorKindUsage:
- return 1
- case ErrorKindRetryable:
- return 2
- case ErrorKindDependency:
- return 3
- default:
- return 1
- }
-}
-
-type Outputs struct {
- OriginVideo string `json:"origin_video,omitempty"`
- OriginAudio string `json:"origin_audio,omitempty"`
- OriginSRT string `json:"origin_srt,omitempty"`
- TargetSRT string `json:"target_srt,omitempty"`
- BilingualSRT string `json:"bilingual_srt,omitempty"`
- ShortOriginSRT string `json:"short_origin_srt,omitempty"`
- ShortOriginMixedSRT string `json:"short_origin_mixed_srt,omitempty"`
- TTSAudio string `json:"tts_audio,omitempty"`
- VideoWithTTS string `json:"video_with_tts,omitempty"`
- HorizontalVideo string `json:"horizontal_video,omitempty"`
- VerticalVideo string `json:"vertical_video,omitempty"`
- TransferredVideo string `json:"transferred_vertical_video,omitempty"`
- OriginCover string `json:"origin_cover,omitempty"`
- GeneratedCover string `json:"generated_cover,omitempty"`
- FinalCoverPrompt string `json:"cover_prompt,omitempty"`
- OriginText string `json:"origin_text,omitempty"`
- TargetText string `json:"target_text,omitempty"`
-}
-
-type Response struct {
- OK bool `json:"ok"`
- Stage Stage `json:"stage"`
- Workdir string `json:"workdir,omitempty"`
- TaskID string `json:"task_id,omitempty"`
- CaptionSource string `json:"caption_source,omitempty"`
- Inputs map[string]string `json:"inputs,omitempty"`
- Outputs Outputs `json:"outputs,omitempty"`
- Warnings []string `json:"warnings,omitempty"`
- FailedIndexes []int `json:"failed_indexes,omitempty"`
- Error *Error `json:"error,omitempty"`
- DurationMS int64 `json:"duration_ms,omitempty"`
-}
-```
-
-- [ ] **Step 4: 运行测试确认通过**
-
-Run: `gofmt -w internal/pipeline/types.go internal/pipeline/types_test.go && go test ./internal/pipeline -run 'TestResponseJSONShape|TestExitCodeForErrorKind' -count=1`
-
-Expected: PASS。
-
-- [ ] **Step 5: 提交**
-
-```bash
-git add internal/pipeline/types.go internal/pipeline/types_test.go
-git commit -m "feat: add pipeline response types"
-```
-
----
-
-### Task 2: 实现 manifest 读写和路径补齐
-
-**Files:**
-- Create: `internal/pipeline/manifest.go`
-- Test: `internal/pipeline/manifest_test.go`
-
-- [ ] **Step 1: 写失败测试**
-
-```go
-package pipeline
-
-import (
- "os"
- "path/filepath"
- "testing"
-)
-
-func TestManifestRoundTrip(t *testing.T) {
- dir := t.TempDir()
- m := NewManifest("demo", dir)
- m.InputURL = "https://www.youtube.com/watch?v=abc"
- m.OriginLanguage = "en"
- m.TargetLanguage = "zh_cn"
- m.Outputs.BilingualSRT = filepath.Join(dir, "bilingual_srt.srt")
- m.MarkStage(StageSubtitle, true, "")
-
- if err := m.Save(); err != nil {
- t.Fatalf("Save() error = %v", err)
- }
- loaded, err := LoadManifest(dir)
- if err != nil {
- t.Fatalf("LoadManifest() error = %v", err)
- }
- if loaded.TaskID != "demo" {
- t.Fatalf("TaskID = %q, want demo", loaded.TaskID)
- }
- if loaded.Stages[string(StageSubtitle)].OK != true {
- t.Fatalf("subtitle stage not marked ok")
- }
-}
-
-func TestApplyDefaultOutputs(t *testing.T) {
- dir := t.TempDir()
- m := NewManifest("demo", dir)
- m.ApplyDefaultOutputs()
-
- want := filepath.Join(dir, "target_language_srt.srt")
- if m.Outputs.TargetSRT != want {
- t.Fatalf("TargetSRT = %q, want %q", m.Outputs.TargetSRT, want)
- }
- if _, err := os.Stat(filepath.Join(dir, "output")); err != nil {
- t.Fatalf("output dir was not created: %v", err)
- }
-}
-```
-
-- [ ] **Step 2: 运行测试确认失败**
-
-Run: `go test ./internal/pipeline -run 'TestManifestRoundTrip|TestApplyDefaultOutputs' -count=1`
-
-Expected: FAIL,错误包含 `undefined: NewManifest` 或 `undefined: LoadManifest`。
-
-- [ ] **Step 3: 实现 manifest**
-
-实现内容:
-
-```go
-package pipeline
-
-import (
- "encoding/json"
- "os"
- "path/filepath"
-)
-
-const ManifestFileName = "krillinai_manifest.json"
-
-type StageStatus struct {
- OK bool `json:"ok"`
- Error string `json:"error,omitempty"`
- Updated string `json:"updated,omitempty"`
-}
-
-type Manifest struct {
- TaskID string `json:"task_id"`
- Workdir string `json:"workdir"`
- InputURL string `json:"input_url,omitempty"`
- OriginLanguage string `json:"origin_language,omitempty"`
- TargetLanguage string `json:"target_language,omitempty"`
- CaptionSource string `json:"caption_source,omitempty"`
- Provider map[string]string `json:"provider,omitempty"`
- Outputs Outputs `json:"outputs"`
- Warnings []string `json:"warnings,omitempty"`
- FailedIndexes []int `json:"failed_indexes,omitempty"`
- Stages map[string]StageStatus `json:"stages"`
-}
-
-func NewManifest(taskID, workdir string) *Manifest {
- return &Manifest{
- TaskID: taskID,
- Workdir: workdir,
- Provider: map[string]string{},
- Stages: map[string]StageStatus{},
- }
-}
-
-func ManifestPath(workdir string) string {
- return filepath.Join(workdir, ManifestFileName)
-}
-
-func LoadManifest(workdir string) (*Manifest, error) {
- data, err := os.ReadFile(ManifestPath(workdir))
- if err != nil {
- return nil, err
- }
- var m Manifest
- if err := json.Unmarshal(data, &m); err != nil {
- return nil, err
- }
- if m.Provider == nil {
- m.Provider = map[string]string{}
- }
- if m.Stages == nil {
- m.Stages = map[string]StageStatus{}
- }
- return &m, nil
-}
-
-func (m *Manifest) Save() error {
- if err := os.MkdirAll(m.Workdir, 0755); err != nil {
- return err
- }
- data, err := json.MarshalIndent(m, "", " ")
- if err != nil {
- return err
- }
- return os.WriteFile(ManifestPath(m.Workdir), append(data, '\n'), 0644)
-}
-
-func (m *Manifest) ApplyDefaultOutputs() error {
- if err := os.MkdirAll(filepath.Join(m.Workdir, "output"), 0755); err != nil {
- return err
- }
- m.Outputs.OriginVideo = filepath.Join(m.Workdir, "origin_video.mp4")
- m.Outputs.OriginAudio = filepath.Join(m.Workdir, "origin_audio.mp3")
- m.Outputs.OriginSRT = filepath.Join(m.Workdir, "origin_language_srt.srt")
- m.Outputs.TargetSRT = filepath.Join(m.Workdir, "target_language_srt.srt")
- m.Outputs.BilingualSRT = filepath.Join(m.Workdir, "bilingual_srt.srt")
- m.Outputs.ShortOriginSRT = filepath.Join(m.Workdir, "short_origin_srt.srt")
- m.Outputs.ShortOriginMixedSRT = filepath.Join(m.Workdir, "short_origin_mixed_srt.srt")
- m.Outputs.TTSAudio = filepath.Join(m.Workdir, "tts_final_audio.wav")
- m.Outputs.VideoWithTTS = filepath.Join(m.Workdir, "video_with_tts.mp4")
- m.Outputs.HorizontalVideo = filepath.Join(m.Workdir, "horizontal_bilingual.mp4")
- m.Outputs.VerticalVideo = filepath.Join(m.Workdir, "vertical_bilingual.mp4")
- m.Outputs.TransferredVideo = filepath.Join(m.Workdir, "transferred_vertical_video.mp4")
- m.Outputs.OriginCover = filepath.Join(m.Workdir, "origin_cover.jpg")
- m.Outputs.GeneratedCover = filepath.Join(m.Workdir, "generated_cover.png")
- m.Outputs.FinalCoverPrompt = filepath.Join(m.Workdir, "cover_prompt.final.txt")
- m.Outputs.OriginText = filepath.Join(m.Workdir, "output", "origin_language.txt")
- m.Outputs.TargetText = filepath.Join(m.Workdir, "output", "target_language.txt")
- return nil
-}
-
-func (m *Manifest) MarkStage(stage Stage, ok bool, msg string) {
- m.Stages[string(stage)] = StageStatus{OK: ok, Error: msg}
-}
-```
-
-- [ ] **Step 4: 运行测试确认通过**
-
-Run: `gofmt -w internal/pipeline/manifest.go internal/pipeline/manifest_test.go && go test ./internal/pipeline -run 'TestManifestRoundTrip|TestApplyDefaultOutputs' -count=1`
-
-Expected: PASS。
-
-- [ ] **Step 5: 提交**
-
-```bash
-git add internal/pipeline/manifest.go internal/pipeline/manifest_test.go
-git commit -m "feat: add pipeline manifest"
-```
-
----
-
-### Task 3: 实现工作目录、任务 ID 和输入路径规范化
-
-**Files:**
-- Create: `internal/pipeline/workdir.go`
-- Test: `internal/pipeline/workdir_test.go`
-
-- [ ] **Step 1: 写失败测试**
-
-```go
-package pipeline
-
-import (
- "path/filepath"
- "strings"
- "testing"
-)
-
-func TestResolveWorkdirExplicit(t *testing.T) {
- dir := filepath.Join(t.TempDir(), "custom")
- taskID, workdir, err := ResolveWorkdir("https://www.youtube.com/watch?v=abc123", dir)
- if err != nil {
- t.Fatalf("ResolveWorkdir() error = %v", err)
- }
- if workdir != dir {
- t.Fatalf("workdir = %q, want %q", workdir, dir)
- }
- if taskID == "" {
- t.Fatalf("taskID is empty")
- }
-}
-
-func TestResolveWorkdirDefault(t *testing.T) {
- taskID, workdir, err := ResolveWorkdir("https://www.youtube.com/watch?v=abc123", "")
- if err != nil {
- t.Fatalf("ResolveWorkdir() error = %v", err)
- }
- if !strings.HasPrefix(workdir, filepath.Join("tasks", taskID)) {
- t.Fatalf("workdir = %q does not start with tasks/taskID %q", workdir, taskID)
- }
-}
-
-func TestNormalizeLocalInput(t *testing.T) {
- got := NormalizeInput("demo.mp4")
- if got != "local:demo.mp4" {
- t.Fatalf("NormalizeInput() = %q, want local:demo.mp4", got)
- }
- if got := NormalizeInput("local:demo.mp4"); got != "local:demo.mp4" {
- t.Fatalf("NormalizeInput(local) = %q", got)
- }
- if got := NormalizeInput("https://www.bilibili.com/video/BV123"); got != "https://www.bilibili.com/video/BV123" {
- t.Fatalf("NormalizeInput(url) = %q", got)
- }
-}
-```
-
-- [ ] **Step 2: 运行测试确认失败**
-
-Run: `go test ./internal/pipeline -run 'TestResolveWorkdir|TestNormalizeLocalInput' -count=1`
-
-Expected: FAIL,错误包含 `undefined: ResolveWorkdir` 或 `undefined: NormalizeInput`。
-
-- [ ] **Step 3: 实现工作目录工具**
-
-实现内容:
-
-```go
-package pipeline
-
-import (
- "fmt"
- "krillin-ai/pkg/util"
- "net/url"
- "os"
- "path/filepath"
- "strings"
-)
-
-func ResolveWorkdir(input, explicit string) (string, string, error) {
- taskID := makeTaskID(input)
- workdir := explicit
- if workdir == "" {
- workdir = filepath.Join("tasks", taskID)
- }
- if err := os.MkdirAll(filepath.Join(workdir, "output"), 0755); err != nil {
- return "", "", err
- }
- return taskID, workdir, nil
-}
-
-func makeTaskID(input string) string {
- trimmed := strings.TrimSpace(input)
- last := trimmed
- if parsed, err := url.Parse(trimmed); err == nil && parsed.Path != "" {
- parts := strings.Split(strings.Trim(parsed.Path, "/"), "/")
- last = parts[len(parts)-1]
- if v := parsed.Query().Get("v"); v != "" {
- last = v
- }
- }
- last = strings.ReplaceAll(last, " ", "")
- runes := []rune(last)
- if len(runes) > 16 {
- runes = runes[:16]
- }
- base := util.SanitizePathName(string(runes))
- if base == "" {
- base = "task"
- }
- return fmt.Sprintf("%s_%s", base, util.GenerateRandStringWithUpperLowerNum(8))
-}
-
-func NormalizeInput(input string) string {
- if strings.HasPrefix(input, "local:") ||
- strings.HasPrefix(input, "http://") ||
- strings.HasPrefix(input, "https://") {
- return input
- }
- return "local:" + input
-}
-```
-
-- [ ] **Step 4: 运行测试确认通过**
-
-Run: `gofmt -w internal/pipeline/workdir.go internal/pipeline/workdir_test.go && go test ./internal/pipeline -run 'TestResolveWorkdir|TestNormalizeLocalInput' -count=1`
-
-Expected: PASS。
-
-- [ ] **Step 5: 提交**
-
-```bash
-git add internal/pipeline/workdir.go internal/pipeline/workdir_test.go
-git commit -m "feat: add pipeline workdir handling"
-```
-
----
-
-### Task 4: 实现 SRT 解析与 line-mode 目标字幕抽取
-
-**Files:**
-- Create: `internal/pipeline/srt.go`
-- Test: `internal/pipeline/srt_test.go`
-
-- [ ] **Step 1: 写失败测试**
-
-```go
-package pipeline
-
-import (
- "os"
- "path/filepath"
- "strings"
- "testing"
-)
-
-func TestExtractTargetOnlyKeepsSingleLineBlocks(t *testing.T) {
- dir := t.TempDir()
- in := filepath.Join(dir, "target.srt")
- out := filepath.Join(dir, "tts.srt")
- content := "1\n00:00:00,000 --> 00:00:01,000\n你好\n\n"
- if err := os.WriteFile(in, []byte(content), 0644); err != nil {
- t.Fatal(err)
- }
- if err := ExtractTargetSRT(in, out, LineModeTargetOnly); err != nil {
- t.Fatalf("ExtractTargetSRT() error = %v", err)
- }
- got, _ := os.ReadFile(out)
- if string(got) != content {
- t.Fatalf("output = %q, want %q", string(got), content)
- }
-}
-
-func TestExtractBilingualTargetTop(t *testing.T) {
- dir := t.TempDir()
- in := filepath.Join(dir, "bilingual.srt")
- out := filepath.Join(dir, "tts.srt")
- content := "1\n00:00:00,000 --> 00:00:01,000\n你好\nhello\n\n"
- if err := os.WriteFile(in, []byte(content), 0644); err != nil {
- t.Fatal(err)
- }
- if err := ExtractTargetSRT(in, out, LineModeBilingualTargetTop); err != nil {
- t.Fatalf("ExtractTargetSRT() error = %v", err)
- }
- got, _ := os.ReadFile(out)
- if !strings.Contains(string(got), "\n你好\n\n") {
- t.Fatalf("target top not extracted: %q", string(got))
- }
- if strings.Contains(string(got), "hello") {
- t.Fatalf("origin line leaked into target output: %q", string(got))
- }
-}
-
-func TestExtractBilingualTargetBottom(t *testing.T) {
- dir := t.TempDir()
- in := filepath.Join(dir, "bilingual.srt")
- out := filepath.Join(dir, "tts.srt")
- content := "1\n00:00:00,000 --> 00:00:01,000\nhello\n你好\n\n"
- if err := os.WriteFile(in, []byte(content), 0644); err != nil {
- t.Fatal(err)
- }
- if err := ExtractTargetSRT(in, out, LineModeBilingualTargetBottom); err != nil {
- t.Fatalf("ExtractTargetSRT() error = %v", err)
- }
- got, _ := os.ReadFile(out)
- if !strings.Contains(string(got), "\n你好\n\n") {
- t.Fatalf("target bottom not extracted: %q", string(got))
- }
-}
-```
-
-- [ ] **Step 2: 运行测试确认失败**
-
-Run: `go test ./internal/pipeline -run 'TestExtract' -count=1`
-
-Expected: FAIL,错误包含 `undefined: ExtractTargetSRT`。
-
-- [ ] **Step 3: 实现 SRT 抽取**
-
-实现内容:
-
-```go
-package pipeline
-
-import (
- "bufio"
- "fmt"
- "os"
- "strings"
-)
-
-type srtBlock struct {
- Index string
- Timestamp string
- Lines []string
-}
-
-func ExtractTargetSRT(input, output string, mode LineMode) error {
- blocks, err := readSRTBlocks(input)
- if err != nil {
- return err
- }
- var b strings.Builder
- for _, block := range blocks {
- text, err := targetLine(block.Lines, mode)
- if err != nil {
- return err
- }
- b.WriteString(block.Index)
- b.WriteString("\n")
- b.WriteString(block.Timestamp)
- b.WriteString("\n")
- b.WriteString(text)
- b.WriteString("\n\n")
- }
- return os.WriteFile(output, []byte(b.String()), 0644)
-}
-
-func readSRTBlocks(path string) ([]srtBlock, error) {
- f, err := os.Open(path)
- if err != nil {
- return nil, err
- }
- defer f.Close()
-
- var blocks []srtBlock
- var current []string
- scanner := bufio.NewScanner(f)
- flush := func() error {
- if len(current) == 0 {
- return nil
- }
- if len(current) < 3 {
- return fmt.Errorf("invalid srt block: %q", strings.Join(current, "\\n"))
- }
- blocks = append(blocks, srtBlock{
- Index: current[0],
- Timestamp: current[1],
- Lines: append([]string(nil), current[2:]...),
- })
- current = nil
- return nil
- }
- for scanner.Scan() {
- line := scanner.Text()
- if strings.TrimSpace(line) == "" {
- if err := flush(); err != nil {
- return nil, err
- }
- continue
- }
- current = append(current, line)
- }
- if err := scanner.Err(); err != nil {
- return nil, err
- }
- if err := flush(); err != nil {
- return nil, err
- }
- return blocks, nil
-}
-
-func targetLine(lines []string, mode LineMode) (string, error) {
- switch mode {
- case LineModeTargetOnly:
- return strings.Join(lines, " "), nil
- case LineModeBilingualTargetTop:
- if len(lines) < 2 {
- return "", fmt.Errorf("bilingual target top requires at least two subtitle lines")
- }
- return lines[0], nil
- case LineModeBilingualTargetBottom:
- if len(lines) < 2 {
- return "", fmt.Errorf("bilingual target bottom requires at least two subtitle lines")
- }
- return lines[len(lines)-1], nil
- default:
- return "", fmt.Errorf("unsupported line mode: %s", mode)
- }
-}
-```
-
-- [ ] **Step 4: 运行测试确认通过**
-
-Run: `gofmt -w internal/pipeline/srt.go internal/pipeline/srt_test.go && go test ./internal/pipeline -run 'TestExtract' -count=1`
-
-Expected: PASS。
-
-- [ ] **Step 5: 提交**
-
-```bash
-git add internal/pipeline/srt.go internal/pipeline/srt_test.go
-git commit -m "feat: add srt target extraction"
-```
-
----
-
-### Task 5: 给现有 service 增加阶段导出包装
-
-**Files:**
-- Create: `internal/service/stage_exports.go`
-- Test: `internal/service/stage_exports_test.go`
-
-- [ ] **Step 1: 写失败测试**
-
-```go
-package service
-
-import (
- "context"
- "krillin-ai/internal/types"
- "testing"
-)
-
-func TestStageExportMethodsExist(t *testing.T) {
- var svc Service
- param := &types.SubtitleTaskStepParam{}
-
- _ = svc.PrepareMedia
- _ = svc.GenerateSubtitlesFromAudio
- _ = svc.GenerateSpeechFromSRT
- _ = svc.FinalizeSubtitleResults
-
- if false {
- _ = svc.PrepareMedia(context.Background(), param)
- _ = svc.GenerateSubtitlesFromAudio(context.Background(), param)
- _ = svc.GenerateSpeechFromSRT(context.Background(), param)
- _ = svc.FinalizeSubtitleResults(context.Background(), param)
- }
-}
-```
-
-- [ ] **Step 2: 运行测试确认失败**
-
-Run: `go test ./internal/service -run TestStageExportMethodsExist -count=1`
-
-Expected: FAIL,错误包含 `svc.PrepareMedia undefined`。
-
-- [ ] **Step 3: 实现薄包装**
-
-实现内容:
-
-```go
-package service
-
-import (
- "context"
- "krillin-ai/internal/types"
-)
-
-func (s Service) PrepareMedia(ctx context.Context, stepParam *types.SubtitleTaskStepParam) error {
- return s.linkToFile(ctx, stepParam)
-}
-
-func (s Service) GenerateSubtitlesFromAudio(ctx context.Context, stepParam *types.SubtitleTaskStepParam) error {
- return s.audioToSubtitle(ctx, stepParam)
-}
-
-func (s Service) GenerateSpeechFromSRT(ctx context.Context, stepParam *types.SubtitleTaskStepParam) error {
- return s.srtFileToSpeech(ctx, stepParam)
-}
-
-func (s Service) FinalizeSubtitleResults(ctx context.Context, stepParam *types.SubtitleTaskStepParam) error {
- return s.uploadSubtitles(ctx, stepParam)
-}
-
-func (s Service) DownloadYouTubeSubtitle(ctx context.Context, req *YoutubeSubtitleReq) (string, error) {
- return s.YouTubeSubtitleSrv.downloadYouTubeSubtitle(ctx, req)
-}
-
-func (s Service) ProcessYouTubeSubtitle(ctx context.Context, req *YoutubeSubtitleReq) (string, error) {
- return s.YouTubeSubtitleSrv.processYouTubeSubtitle(ctx, req)
-}
-```
-
-- [ ] **Step 4: 运行测试确认通过**
-
-Run: `gofmt -w internal/service/stage_exports.go internal/service/stage_exports_test.go && go test ./internal/service -run TestStageExportMethodsExist -count=1`
-
-Expected: PASS。
-
-- [ ] **Step 5: 提交**
-
-```bash
-git add internal/service/stage_exports.go internal/service/stage_exports_test.go
-git commit -m "feat: expose service stage methods"
-```
-
----
-
-### Task 6: 抽出可指定字幕文件和输出名的视频渲染函数
-
-**Files:**
-- Create: `internal/service/render_stage.go`
-- Create: `internal/service/render_stage_test.go`
-- Modify: `internal/service/srt_embed.go`
-
-- [ ] **Step 1: 写失败测试**
-
-```go
-package service
-
-import (
- "path/filepath"
- "strings"
- "testing"
-)
-
-func TestBuildEmbedSubtitleArgsUsesRequestedSubtitleAndOutput(t *testing.T) {
- req := RenderVideoRequest{
- Workdir: "tasks/demo",
- InputVideo: "tasks/demo/origin_video.mp4",
- SubtitleFile: "tasks/demo/target_language_srt.srt",
- OutputFile: "tasks/demo/output/horizontal_dubbed.mp4",
- Horizontal: true,
- }
- args, assPath := buildEmbedSubtitleArgs(req)
- joined := strings.Join(args, " ")
- if !strings.Contains(assPath, filepath.Join("tasks", "demo")) {
- t.Fatalf("assPath = %q does not use workdir", assPath)
- }
- if !strings.Contains(joined, "tasks/demo/origin_video.mp4") {
- t.Fatalf("args do not contain input video: %v", args)
- }
- if !strings.Contains(joined, "tasks/demo/output/horizontal_dubbed.mp4") {
- t.Fatalf("args do not contain output file: %v", args)
- }
-}
-```
-
-- [ ] **Step 2: 运行测试确认失败**
-
-Run: `go test ./internal/service -run TestBuildEmbedSubtitleArgsUsesRequestedSubtitleAndOutput -count=1`
-
-Expected: FAIL,错误包含 `undefined: RenderVideoRequest` 或 `undefined: buildEmbedSubtitleArgs`。
-
-- [ ] **Step 3: 实现渲染请求和命令构造**
-
-实现内容:
-
-```go
-package service
-
-import (
- "context"
- "fmt"
- "krillin-ai/internal/storage"
- "krillin-ai/internal/types"
- "os/exec"
- "path/filepath"
- "strings"
-)
-
-type RenderVideoRequest struct {
- Workdir string
- InputVideo string
- SubtitleFile string
- OutputFile string
- Horizontal bool
- StepParam *types.SubtitleTaskStepParam
-}
-
-func (s Service) RenderVideo(ctx context.Context, req RenderVideoRequest) (string, error) {
- assPath := filepath.Join(req.Workdir, "formatted_subtitles.ass")
- stepParam := req.StepParam
- if stepParam == nil {
- stepParam = &types.SubtitleTaskStepParam{TaskBasePath: req.Workdir}
- }
- if err := srtToAss(req.SubtitleFile, assPath, req.Horizontal, stepParam); err != nil {
- return "", fmt.Errorf("RenderVideo srtToAss error: %w", err)
- }
- args, _ := buildEmbedSubtitleArgs(req)
- cmd := exec.Command(storage.FfmpegPath, args...)
- output, err := cmd.CombinedOutput()
- if err != nil {
- return "", fmt.Errorf("RenderVideo ffmpeg error: %w, output: %s", err, string(output))
- }
- return req.OutputFile, nil
-}
-
-func buildEmbedSubtitleArgs(req RenderVideoRequest) ([]string, string) {
- assPath := filepath.Join(req.Workdir, "formatted_subtitles.ass")
- ass := strings.ReplaceAll(assPath, "\\", "/")
- return []string{
- "-y",
- "-i", req.InputVideo,
- "-vf", fmt.Sprintf("ass=%s", ass),
- "-c:a", "aac",
- "-b:a", "192k",
- req.OutputFile,
- }, assPath
-}
-```
-
-- [ ] **Step 4: 修改旧渲染入口复用新函数**
-
-在 `internal/service/srt_embed.go` 的旧 `embedSubtitles(stepParam, isHorizontal, withTts)` 内部,只保留输出文件名、输入视频选择,然后调用 `Service{}.RenderVideo` 不合适,因为没有 receiver。推荐把旧的 package-level `embedSubtitles` 改为 `renderSubtitleFile`,再让 `Service.RenderVideo` 与旧入口共同调用它。
-
-目标形状:
-
-```go
-func renderSubtitleFile(req RenderVideoRequest) (string, error) {
- assPath := filepath.Join(req.Workdir, "formatted_subtitles.ass")
- stepParam := req.StepParam
- if stepParam == nil {
- stepParam = &types.SubtitleTaskStepParam{TaskBasePath: req.Workdir}
- }
- if err := srtToAss(req.SubtitleFile, assPath, req.Horizontal, stepParam); err != nil {
- return "", fmt.Errorf("renderSubtitleFile srtToAss error: %w", err)
- }
- args, _ := buildEmbedSubtitleArgs(req)
- cmd := exec.Command(storage.FfmpegPath, args...)
- output, err := cmd.CombinedOutput()
- if err != nil {
- return "", fmt.Errorf("renderSubtitleFile ffmpeg error: %w, output: %s", err, string(output))
- }
- return req.OutputFile, nil
-}
-```
-
-旧入口调用:
-
-```go
-_, err := renderSubtitleFile(RenderVideoRequest{
- Workdir: stepParam.TaskBasePath,
- InputVideo: input,
- SubtitleFile: stepParam.BilingualSrtFilePath,
- OutputFile: filepath.Join(stepParam.TaskBasePath, "output", outputFileName),
- Horizontal: isHorizontal,
- StepParam: stepParam,
-})
-return err
-```
-
-- [ ] **Step 5: 运行测试确认通过**
-
-Run: `gofmt -w internal/service/render_stage.go internal/service/render_stage_test.go internal/service/srt_embed.go && go test ./internal/service -run 'TestBuildEmbedSubtitleArgsUsesRequestedSubtitleAndOutput|TestStageExportMethodsExist' -count=1`
-
-Expected: PASS。
-
-- [ ] **Step 6: 提交**
-
-```bash
-git add internal/service/render_stage.go internal/service/render_stage_test.go internal/service/srt_embed.go
-git commit -m "feat: add explicit subtitle render stage"
-```
-
----
-
-### Task 7: 建立 pipeline service adapter 和 fake-friendly 接口
-
-**Files:**
-- Create: `internal/pipeline/service_adapter.go`
-- Test: `internal/pipeline/service_adapter_test.go`
-
-- [ ] **Step 1: 写失败测试**
-
-```go
-package pipeline
-
-import (
- "krillin-ai/internal/service"
- "testing"
-)
-
-func TestNewServiceAdapterKeepsService(t *testing.T) {
- svc := &service.Service{}
- adapter := NewServiceAdapter(svc)
- if adapter == nil {
- t.Fatalf("NewServiceAdapter() returned nil")
- }
-}
-```
-
-- [ ] **Step 2: 运行测试确认失败**
-
-Run: `go test ./internal/pipeline -run TestNewServiceAdapterKeepsService -count=1`
-
-Expected: FAIL,错误包含 `undefined: NewServiceAdapter`。
-
-- [ ] **Step 3: 实现接口和 adapter**
-
-实现内容:
-
-```go
-package pipeline
-
-import (
- "context"
- "krillin-ai/internal/service"
- "krillin-ai/internal/types"
-)
-
-type StageService interface {
- PrepareMedia(context.Context, *types.SubtitleTaskStepParam) error
- GenerateSubtitlesFromAudio(context.Context, *types.SubtitleTaskStepParam) error
- GenerateSpeechFromSRT(context.Context, *types.SubtitleTaskStepParam) error
- FinalizeSubtitleResults(context.Context, *types.SubtitleTaskStepParam) error
- DownloadYouTubeSubtitle(context.Context, *service.YoutubeSubtitleReq) (string, error)
- ProcessYouTubeSubtitle(context.Context, *service.YoutubeSubtitleReq) (string, error)
- RenderVideo(context.Context, service.RenderVideoRequest) (string, error)
-}
-
-type ServiceAdapter struct {
- svc *service.Service
-}
-
-func NewServiceAdapter(svc *service.Service) *ServiceAdapter {
- return &ServiceAdapter{svc: svc}
-}
-
-func (a *ServiceAdapter) PrepareMedia(ctx context.Context, p *types.SubtitleTaskStepParam) error {
- return a.svc.PrepareMedia(ctx, p)
-}
-
-func (a *ServiceAdapter) GenerateSubtitlesFromAudio(ctx context.Context, p *types.SubtitleTaskStepParam) error {
- return a.svc.GenerateSubtitlesFromAudio(ctx, p)
-}
-
-func (a *ServiceAdapter) GenerateSpeechFromSRT(ctx context.Context, p *types.SubtitleTaskStepParam) error {
- return a.svc.GenerateSpeechFromSRT(ctx, p)
-}
-
-func (a *ServiceAdapter) FinalizeSubtitleResults(ctx context.Context, p *types.SubtitleTaskStepParam) error {
- return a.svc.FinalizeSubtitleResults(ctx, p)
-}
-
-func (a *ServiceAdapter) DownloadYouTubeSubtitle(ctx context.Context, r *service.YoutubeSubtitleReq) (string, error) {
- return a.svc.DownloadYouTubeSubtitle(ctx, r)
-}
-
-func (a *ServiceAdapter) ProcessYouTubeSubtitle(ctx context.Context, r *service.YoutubeSubtitleReq) (string, error) {
- return a.svc.ProcessYouTubeSubtitle(ctx, r)
-}
-
-func (a *ServiceAdapter) RenderVideo(ctx context.Context, r service.RenderVideoRequest) (string, error) {
- return a.svc.RenderVideo(ctx, r)
-}
-```
-
-- [ ] **Step 4: 运行测试确认通过**
-
-Run: `gofmt -w internal/pipeline/service_adapter.go internal/pipeline/service_adapter_test.go && go test ./internal/pipeline -run TestNewServiceAdapterKeepsService -count=1`
-
-Expected: PASS。
-
-- [ ] **Step 5: 提交**
-
-```bash
-git add internal/pipeline/service_adapter.go internal/pipeline/service_adapter_test.go
-git commit -m "feat: add pipeline service adapter"
-```
-
----
-
-### Task 8: 实现字幕阶段编排和真实 fallback 语义
-
-**Files:**
-- Create: `internal/pipeline/subtitle.go`
-- Test: `internal/pipeline/subtitle_test.go`
-
-- [ ] **Step 1: 写失败测试**
-
-```go
-package pipeline
-
-import (
- "context"
- "errors"
- "krillin-ai/internal/service"
- "krillin-ai/internal/types"
- "testing"
-)
-
-type fakeStageService struct {
- downloadErr error
- processErr error
- calls []string
-}
-
-func (f *fakeStageService) PrepareMedia(context.Context, *types.SubtitleTaskStepParam) error {
- f.calls = append(f.calls, "prepare")
- return nil
-}
-func (f *fakeStageService) GenerateSubtitlesFromAudio(context.Context, *types.SubtitleTaskStepParam) error {
- f.calls = append(f.calls, "audio")
- return nil
-}
-func (f *fakeStageService) GenerateSpeechFromSRT(context.Context, *types.SubtitleTaskStepParam) error { return nil }
-func (f *fakeStageService) FinalizeSubtitleResults(context.Context, *types.SubtitleTaskStepParam) error { return nil }
-func (f *fakeStageService) DownloadYouTubeSubtitle(context.Context, *service.YoutubeSubtitleReq) (string, error) {
- f.calls = append(f.calls, "download-youtube")
- return "demo.en.vtt", f.downloadErr
-}
-func (f *fakeStageService) ProcessYouTubeSubtitle(context.Context, *service.YoutubeSubtitleReq) (string, error) {
- f.calls = append(f.calls, "process-youtube")
- return "bilingual_srt.srt", f.processErr
-}
-func (f *fakeStageService) RenderVideo(context.Context, service.RenderVideoRequest) (string, error) { return "", nil }
-
-func TestGenerateSubtitlesFallsBackToAudioWhenAnySourceFails(t *testing.T) {
- dir := t.TempDir()
- fake := &fakeStageService{downloadErr: errors.New("no captions")}
- req := SubtitleRequest{
- Input: "https://www.youtube.com/watch?v=abc",
- Workdir: dir,
- TaskID: "demo",
- OriginLang: "en",
- TargetLang: "zh_cn",
- CaptionSource: CaptionSourceAny,
- }
- resp, err := GenerateSubtitles(context.Background(), fake, req)
- if err != nil {
- t.Fatalf("GenerateSubtitles() error = %v", err)
- }
- if !resp.OK {
- t.Fatalf("OK = false, want true")
- }
- if got := fake.calls; len(got) != 3 || got[0] != "prepare" || got[1] != "download-youtube" || got[2] != "audio" {
- t.Fatalf("calls = %v", got)
- }
-}
-
-func TestGenerateSubtitlesManualDoesNotFallback(t *testing.T) {
- dir := t.TempDir()
- fake := &fakeStageService{downloadErr: errors.New("no captions")}
- req := SubtitleRequest{
- Input: "https://www.youtube.com/watch?v=abc",
- Workdir: dir,
- TaskID: "demo",
- OriginLang: "en",
- TargetLang: "zh_cn",
- CaptionSource: CaptionSourceManual,
- }
- resp, err := GenerateSubtitles(context.Background(), fake, req)
- if err == nil {
- t.Fatalf("GenerateSubtitles() error = nil, want error")
- }
- if resp.OK {
- t.Fatalf("OK = true, want false")
- }
- if got := fake.calls; len(got) != 2 || got[1] != "download-youtube" {
- t.Fatalf("calls = %v", got)
- }
-}
-```
-
-- [ ] **Step 2: 运行测试确认失败**
-
-Run: `go test ./internal/pipeline -run 'TestGenerateSubtitles' -count=1`
-
-Expected: FAIL,错误包含 `undefined: SubtitleRequest` 或 `undefined: GenerateSubtitles`。
-
-- [ ] **Step 3: 实现字幕阶段**
-
-实现要点:
-
-```go
-type SubtitleRequest struct {
- Input string
- Workdir string
- TaskID string
- OriginLang string
- TargetLang string
- UserLang string
- CaptionSource CaptionSource
- BilingualTop bool
- MaxWordOneLine int
-}
-```
-
-`GenerateSubtitles` 必须:
-
-1. 创建或加载 manifest。
-2. 构造 `types.SubtitleTaskStepParam`,字段包括 `TaskBasePath`、`TaskId`、`Link`、`OriginLanguage`、`TargetLanguage`、`SubtitleResultType`、`VttSwitch`、`MaxWordOneLine`。
-3. 调用 `svc.PrepareMedia`。
-4. 当输入为 YouTube 且 `CaptionSource != whisper` 时,调用 `DownloadYouTubeSubtitle` 和 `ProcessYouTubeSubtitle`。
-5. 当平台字幕失败且 `CaptionSource == any` 时,追加 warning 并调用 `GenerateSubtitlesFromAudio`。
-6. 当 `CaptionSource == manual` 或 `auto` 且平台字幕失败时,返回 `ErrorKindRetryable`,不调用转录。
-7. 写入 manifest 和 JSON response。
-
-核心伪代码必须按下列语义落地:
-
-```go
-if isYouTube(req.Input) && req.CaptionSource != CaptionSourceWhisper {
- vttFile, err := svc.DownloadYouTubeSubtitle(ctx, youtubeReq)
- if err == nil {
- youtubeReq.VttFile = vttFile
- _, err = svc.ProcessYouTubeSubtitle(ctx, youtubeReq)
- }
- if err == nil {
- m.CaptionSource = "youtube_vtt"
- return success
- }
- if req.CaptionSource != CaptionSourceAny {
- return failedWithoutFallback
- }
- m.Warnings = append(m.Warnings, "平台字幕不可用,回退到转录")
-}
-err := svc.GenerateSubtitlesFromAudio(ctx, stepParam)
-```
-
-- [ ] **Step 4: 运行测试确认通过**
-
-Run: `gofmt -w internal/pipeline/subtitle.go internal/pipeline/subtitle_test.go && go test ./internal/pipeline -run 'TestGenerateSubtitles' -count=1`
-
-Expected: PASS。
-
-- [ ] **Step 5: 提交**
-
-```bash
-git add internal/pipeline/subtitle.go internal/pipeline/subtitle_test.go
-git commit -m "feat: add subtitle pipeline stage"
-```
-
----
-
-### Task 9: 实现 TTS 阶段编排
-
-**Files:**
-- Create: `internal/pipeline/tts.go`
-- Test: `internal/pipeline/tts_test.go`
-
-- [ ] **Step 1: 写失败测试**
-
-```go
-package pipeline
-
-import (
- "context"
- "os"
- "path/filepath"
- "testing"
-)
-
-func TestGenerateTTSExtractsBilingualTargetBeforeSpeech(t *testing.T) {
- dir := t.TempDir()
- input := filepath.Join(dir, "bilingual.srt")
- if err := os.WriteFile(input, []byte("1\n00:00:00,000 --> 00:00:01,000\nhello\n你好\n\n"), 0644); err != nil {
- t.Fatal(err)
- }
- fake := &fakeStageService{}
- req := TTSRequest{
- Workdir: dir,
- TaskID: "demo",
- InputSRT: input,
- LineMode: LineModeBilingualTargetBottom,
- }
- resp, err := GenerateTTS(context.Background(), fake, req)
- if err != nil {
- t.Fatalf("GenerateTTS() error = %v", err)
- }
- if !resp.OK {
- t.Fatalf("OK = false, want true")
- }
- extracted := filepath.Join(dir, "tts_input.srt")
- data, err := os.ReadFile(extracted)
- if err != nil {
- t.Fatalf("tts input not written: %v", err)
- }
- if string(data) != "1\n00:00:00,000 --> 00:00:01,000\n你好\n\n" {
- t.Fatalf("tts input = %q", string(data))
- }
-}
-```
-
-- [ ] **Step 2: 运行测试确认失败**
-
-Run: `go test ./internal/pipeline -run TestGenerateTTSExtractsBilingualTargetBeforeSpeech -count=1`
-
-Expected: FAIL,错误包含 `undefined: TTSRequest` 或 `undefined: GenerateTTS`。
-
-- [ ] **Step 3: 实现 TTS 阶段**
-
-实现内容:
-
-```go
-type TTSRequest struct {
- Workdir string
- TaskID string
- InputSRT string
- LineMode LineMode
- Video string
- Voice string
- VoiceCloneSource string
-}
-```
-
-`GenerateTTS` 必须:
-
-1. 默认 `LineModeTargetOnly`。
-2. 默认 `InputSRT` 为 manifest 的 `TargetSRT`。
-3. 当 line-mode 不是 `target-only` 时,把抽取结果写到 `workdir/tts_input.srt`。
-4. 构造 `types.SubtitleTaskStepParam`,设置 `EnableTts`、`TtsSourceFilePath`、`TtsResultFilePath`、`InputVideoPath`、`TtsVoiceCode`、`VoiceCloneAudioUrl`。
-5. 调用 `svc.GenerateSpeechFromSRT`。
-6. 写 manifest:`TTSAudio`、`VideoWithTTS`、失败 index。
-
-- [ ] **Step 4: 运行测试确认通过**
-
-Run: `gofmt -w internal/pipeline/tts.go internal/pipeline/tts_test.go && go test ./internal/pipeline -run TestGenerateTTSExtractsBilingualTargetBeforeSpeech -count=1`
-
-Expected: PASS。
-
-- [ ] **Step 5: 提交**
-
-```bash
-git add internal/pipeline/tts.go internal/pipeline/tts_test.go
-git commit -m "feat: add tts pipeline stage"
-```
-
----
-
-### Task 10: 实现横屏和竖屏渲染阶段
-
-**Files:**
-- Create: `internal/pipeline/render.go`
-- Test: `internal/pipeline/render_test.go`
-
-- [ ] **Step 1: 写失败测试**
-
-```go
-package pipeline
-
-import (
- "context"
- "krillin-ai/internal/service"
- "strings"
- "testing"
-)
-
-type renderFakeService struct {
- fakeStageService
- lastRender service.RenderVideoRequest
-}
-
-func (f *renderFakeService) RenderVideo(ctx context.Context, req service.RenderVideoRequest) (string, error) {
- f.lastRender = req
- return req.OutputFile, nil
-}
-
-func TestRenderHorizontalDubbedOutputName(t *testing.T) {
- dir := t.TempDir()
- fake := &renderFakeService{}
- req := RenderRequest{
- Workdir: dir,
- TaskID: "demo",
- Video: "origin_video.mp4",
- Audio: "tts_final_audio.wav",
- Subtitle: "target_language_srt.srt",
- Horizontal: true,
- Dubbed: true,
- }
- resp, err := Render(context.Background(), fake, req)
- if err != nil {
- t.Fatalf("Render() error = %v", err)
- }
- if !resp.OK {
- t.Fatalf("OK = false, want true")
- }
- if !strings.HasSuffix(fake.lastRender.OutputFile, "horizontal_dubbed.mp4") {
- t.Fatalf("OutputFile = %q, want horizontal_dubbed.mp4 suffix", fake.lastRender.OutputFile)
- }
-}
-
-func TestRenderVerticalBilingualOutputName(t *testing.T) {
- dir := t.TempDir()
- fake := &renderFakeService{}
- req := RenderRequest{
- Workdir: dir,
- TaskID: "demo",
- Video: "origin_video.mp4",
- Subtitle: "short_origin_mixed_srt.srt",
- Horizontal: false,
- Dubbed: false,
- }
- resp, err := Render(context.Background(), fake, req)
- if err != nil {
- t.Fatalf("Render() error = %v", err)
- }
- if !resp.OK {
- t.Fatalf("OK = false, want true")
- }
- if !strings.HasSuffix(fake.lastRender.OutputFile, "vertical_bilingual.mp4") {
- t.Fatalf("OutputFile = %q, want vertical_bilingual.mp4 suffix", fake.lastRender.OutputFile)
- }
-}
-```
-
-- [ ] **Step 2: 运行测试确认失败**
-
-Run: `go test ./internal/pipeline -run 'TestRender' -count=1`
-
-Expected: FAIL,错误包含 `undefined: RenderRequest` 或 `undefined: Render`。
-
-- [ ] **Step 3: 实现渲染阶段**
-
-实现内容:
-
-```go
-type RenderRequest struct {
- Workdir string
- TaskID string
- Video string
- Audio string
- Subtitle string
- Horizontal bool
- Dubbed bool
- MajorTitle string
- MinorTitle string
-}
-```
-
-`Render` 必须:
-
-1. 当 `Video` 为空时默认使用 manifest 的 `OriginVideo`。
-2. 当 `Subtitle` 为空时:
- - 横屏双语默认 `bilingual_srt.srt`。
- - 横屏配音默认 `target_language_srt.srt`。
- - 竖屏双语默认 `short_origin_mixed_srt.srt`。
- - 竖屏配音默认 `target_language_srt.srt`。
-3. 当 `Audio` 非空时,先确保 `video_with_tts.mp4` 存在或调用现有替换音频工具;第一版可以复用 TTS 阶段已生成的 `VideoWithTTS`。
-4. 输出文件名:
- - `horizontal_bilingual.mp4`
- - `horizontal_dubbed.mp4`
- - `vertical_bilingual.mp4`
- - `vertical_dubbed.mp4`
-5. 调用 `svc.RenderVideo`。
-6. 写 manifest 和 stdout JSON。
-
-- [ ] **Step 4: 运行测试确认通过**
-
-Run: `gofmt -w internal/pipeline/render.go internal/pipeline/render_test.go && go test ./internal/pipeline -run 'TestRender' -count=1`
-
-Expected: PASS。
-
-- [ ] **Step 5: 提交**
-
-```bash
-git add internal/pipeline/render.go internal/pipeline/render_test.go
-git commit -m "feat: add render pipeline stages"
-```
-
----
-
-### Task 11: 实现 pipeline 输出集合到阶段顺序的编排
-
-**Files:**
-- Create: `internal/pipeline/pipeline.go`
-- Test: `internal/pipeline/pipeline_test.go`
-
-- [ ] **Step 1: 写失败测试**
-
-```go
-package pipeline
-
-import "testing"
-
-func TestPlanOutputsMapsToStages(t *testing.T) {
- got, err := PlanOutputs("subtitle,tts,horizontal-bilingual,horizontal-dubbed,vertical-bilingual,vertical-dubbed")
- if err != nil {
- t.Fatalf("PlanOutputs() error = %v", err)
- }
- want := []Stage{
- StageSubtitle,
- StageTTS,
- StageRenderHorizontal,
- StageRenderHorizontal,
- StageRenderVertical,
- StageRenderVertical,
- }
- if len(got) != len(want) {
- t.Fatalf("len = %d, want %d", len(got), len(want))
- }
- for i := range want {
- if got[i] != want[i] {
- t.Fatalf("stage[%d] = %s, want %s", i, got[i], want[i])
- }
- }
-}
-```
-
-- [ ] **Step 2: 运行测试确认失败**
-
-Run: `go test ./internal/pipeline -run TestPlanOutputsMapsToStages -count=1`
-
-Expected: FAIL,错误包含 `undefined: PlanOutputs`。
-
-- [ ] **Step 3: 实现编排计划**
-
-实现内容:
-
-```go
-type PipelineRequest struct {
- Subtitle SubtitleRequest
- TTS TTSRequest
- Outputs string
- Async bool
-}
-
-func PlanOutputs(outputs string) ([]Stage, error) {
- parts := strings.Split(outputs, ",")
- stages := make([]Stage, 0, len(parts))
- for _, part := range parts {
- switch strings.TrimSpace(part) {
- case "subtitle":
- stages = append(stages, StageSubtitle)
- case "tts":
- stages = append(stages, StageTTS)
- case "horizontal-bilingual", "horizontal-dubbed":
- stages = append(stages, StageRenderHorizontal)
- case "vertical-bilingual", "vertical-dubbed":
- stages = append(stages, StageRenderVertical)
- case "cover":
- stages = append(stages, StageCover)
- case "":
- default:
- return nil, fmt.Errorf("unsupported output: %s", part)
- }
- }
- return stages, nil
-}
-```
-
-`RunPipeline` 逐个调用 `GenerateSubtitles`、`GenerateTTS`、`Render`、`GenerateCover`。`--async` 第一版只允许返回 task_id 并后台 goroutine 执行;异步状态写入 manifest,不依赖内存 map。
-
-- [ ] **Step 4: 运行测试确认通过**
-
-Run: `gofmt -w internal/pipeline/pipeline.go internal/pipeline/pipeline_test.go && go test ./internal/pipeline -run TestPlanOutputsMapsToStages -count=1`
-
-Expected: PASS。
-
-- [ ] **Step 5: 提交**
-
-```bash
-git add internal/pipeline/pipeline.go internal/pipeline/pipeline_test.go
-git commit -m "feat: add pipeline planner"
-```
-
----
-
-### Task 12: 实现 CLI 参数解析和 JSON 输出
-
-**Files:**
-- Create: `internal/cli/commands.go`
-- Create: `internal/cli/commands_test.go`
-- Create: `cmd/cli/main.go`
-
-- [ ] **Step 1: 写失败测试**
-
-```go
-package cli
-
-import "testing"
-
-func TestParseSubtitleCommand(t *testing.T) {
- cmd, err := Parse([]string{
- "subtitle",
- "https://www.youtube.com/watch?v=abc",
- "--origin-lang", "en",
- "--target-lang", "zh_cn",
- "--workdir", "tasks/demo",
- "--caption-source", "any",
- })
- if err != nil {
- t.Fatalf("Parse() error = %v", err)
- }
- if cmd.Name != "subtitle" {
- t.Fatalf("Name = %q, want subtitle", cmd.Name)
- }
- if cmd.Subtitle.Input != "https://www.youtube.com/watch?v=abc" {
- t.Fatalf("Input = %q", cmd.Subtitle.Input)
- }
- if cmd.Subtitle.Workdir != "tasks/demo" {
- t.Fatalf("Workdir = %q", cmd.Subtitle.Workdir)
- }
-}
-
-func TestParseTTSCommandRequiresInputSRT(t *testing.T) {
- _, err := Parse([]string{"tts", "--workdir", "tasks/demo"})
- if err == nil {
- t.Fatalf("Parse() error = nil, want error")
- }
-}
-```
-
-- [ ] **Step 2: 运行测试确认失败**
-
-Run: `go test ./internal/cli -run TestParse -count=1`
-
-Expected: FAIL,错误包含 `undefined: Parse`。
-
-- [ ] **Step 3: 实现 CLI 解析**
-
-实现要求:
-
-1. 使用标准库 `flag.NewFlagSet`,不新增第三方 CLI 依赖。
-2. `Parse(args []string)` 返回 `Command`。
-3. 命令包括 `subtitle`、`tts`、`render-horizontal`、`render-vertical`、`cover`、`pipeline`、`status`。
-4. 参数错误返回普通 error,main 中转成 `pipeline.ErrorKindUsage`。
-
-核心结构:
-
-```go
-type Command struct {
- Name string
- Subtitle pipeline.SubtitleRequest
- TTS pipeline.TTSRequest
- Render pipeline.RenderRequest
- Pipeline pipeline.PipelineRequest
-}
-```
-
-`cmd/cli/main.go` 负责:
-
-```go
-func main() {
- log.InitLogger()
- defer log.GetLogger().Sync()
- if !config.LoadConfig() {
- writeAndExit(pipeline.Response{OK: false, Error: &pipeline.Error{Kind: pipeline.ErrorKindUsage, Code: "config_not_found", Message: "未找到配置文件", Retryable: false}})
- }
- if err := config.CheckConfig(); err != nil {
- writeAndExit(errorResponse(err, pipeline.ErrorKindUsage))
- }
- if err := deps.CheckDependency(); err != nil {
- writeAndExit(errorResponse(err, pipeline.ErrorKindDependency))
- }
- cmd, err := cli.Parse(os.Args[1:])
- if err != nil {
- writeAndExit(errorResponse(err, pipeline.ErrorKindUsage))
- }
- svc := service.NewService()
- adapter := pipeline.NewServiceAdapter(svc)
- resp := cli.Execute(context.Background(), adapter, cmd)
- writeAndExit(resp)
-}
-```
-
-- [ ] **Step 4: 运行测试确认通过**
-
-Run: `gofmt -w internal/cli/commands.go internal/cli/commands_test.go cmd/cli/main.go && go test ./internal/cli -run TestParse -count=1`
-
-Expected: PASS。
-
-- [ ] **Step 5: 提交**
-
-```bash
-git add internal/cli/commands.go internal/cli/commands_test.go cmd/cli/main.go
-git commit -m "feat: add cli command parser"
-```
-
----
-
-### Task 13: CLI 端到端 dry-run 测试与构建
-
-**Files:**
-- Modify: `internal/cli/commands.go`
-- Modify: `cmd/cli/main.go`
-- Test: `internal/cli/commands_test.go`
-
-- [ ] **Step 1: 增加 dry-run 测试**
-
-```go
-func TestExecuteDryRunSubtitleReturnsJSONReadyResponse(t *testing.T) {
- cmd, err := Parse([]string{
- "subtitle",
- "local:demo.mp4",
- "--origin-lang", "en",
- "--target-lang", "zh_cn",
- "--workdir", t.TempDir(),
- "--dry-run",
- })
- if err != nil {
- t.Fatalf("Parse() error = %v", err)
- }
- resp := Execute(context.Background(), nil, cmd)
- if !resp.OK {
- t.Fatalf("OK = false, error = %#v", resp.Error)
- }
- if resp.Stage != pipeline.StageSubtitle {
- t.Fatalf("Stage = %s", resp.Stage)
- }
-}
-```
-
-- [ ] **Step 2: 运行测试确认失败**
-
-Run: `go test ./internal/cli -run TestExecuteDryRunSubtitleReturnsJSONReadyResponse -count=1`
-
-Expected: FAIL,错误包含 `unknown flag: dry-run` 或 `undefined: Execute`。
-
-- [ ] **Step 3: 实现 `--dry-run`**
-
-实现要求:
-
-1. 所有命令支持 `--dry-run`。
-2. dry-run 不调用外部依赖和 service,只解析参数、创建 workdir、写 manifest、返回 JSON。
-3. 用于 CI 中验证 CLI 二进制不需要真实 API key。
-
-- [ ] **Step 4: 构建 CLI**
-
-Run: `go build -o build/krillinai-cli ./cmd/cli`
-
-Expected: 命令成功,`build/krillinai-cli` 存在。
-
-- [ ] **Step 5: 运行 dry-run**
-
-Run: `./build/krillinai-cli subtitle local:demo.mp4 --origin-lang en --target-lang zh_cn --workdir /tmp/krillinai-cli-demo --dry-run`
-
-Expected: stdout 是 JSON,包含 `"ok":true` 和 `"stage":"subtitle"`。
-
-- [ ] **Step 6: 提交**
-
-```bash
-git add internal/cli/commands.go internal/cli/commands_test.go cmd/cli/main.go
-git commit -m "feat: support cli dry run"
-```
-
----
-
-### Task 14: 增加 image 配置和封面 prompt 阶段
-
-**Files:**
-- Modify: `config/config.go`
-- Modify: `config/config-example.toml`
-- Create: `internal/pipeline/cover.go`
-- Create: `internal/pipeline/cover_test.go`
-- Create: `pkg/image/openai_compatible.go`
-- Create: `pkg/image/openai_compatible_test.go`
-
-- [ ] **Step 1: 写配置失败测试**
-
-```go
-package config
-
-import "testing"
-
-func TestDefaultImageConfig(t *testing.T) {
- if Conf.Image.Provider != "openai-compatible" {
- t.Fatalf("Image.Provider = %q, want openai-compatible", Conf.Image.Provider)
- }
- if Conf.Image.Openai.Model == "" {
- t.Fatalf("Image.Openai.Model is empty")
- }
-}
-```
-
-- [ ] **Step 2: 运行测试确认失败**
-
-Run: `go test ./config -run TestDefaultImageConfig -count=1`
-
-Expected: FAIL,错误包含 `Conf.Image undefined`。
-
-- [ ] **Step 3: 实现 image 配置**
-
-在 `config/config.go` 增加:
-
-```go
-type Image struct {
- Provider string `toml:"provider"`
- Openai OpenaiCompatibleConfig `toml:"openai"`
-}
-
-type Config struct {
- App App `toml:"app"`
- Server Server `toml:"server"`
- Llm OpenaiCompatibleConfig `toml:"llm"`
- Transcribe Transcribe `toml:"transcribe"`
- Tts Tts `toml:"tts"`
- Image Image `toml:"image"`
-}
-```
-
-默认值:
-
-```go
-Image: Image{
- Provider: "openai-compatible",
- Openai: OpenaiCompatibleConfig{
- Model: "gpt-image-1",
- },
-},
-```
-
-在 `config/config-example.toml` 增加:
-
-```toml
-[image]
- provider = "openai-compatible"
- [image.openai]
- base_url = ""
- api_key = ""
- model = "gpt-image-1"
-```
-
-- [ ] **Step 4: 实现 prompt 模板渲染测试**
-
-```go
-func TestRenderCoverPrompt(t *testing.T) {
- template := "{{title}}\n{{target_language}}\n{{style_hint}}"
- got := RenderCoverPrompt(template, CoverPromptData{
- Title: "原始标题",
- TargetLanguage: "zh_cn",
- StyleHint: "Bilibili 科技封面",
- })
- want := "原始标题\nzh_cn\nBilibili 科技封面"
- if got != want {
- t.Fatalf("RenderCoverPrompt() = %q, want %q", got, want)
- }
-}
-```
-
-- [ ] **Step 5: 实现 cover prompt**
-
-`internal/pipeline/cover.go` 增加:
-
-```go
-type CoverPromptData struct {
- Title string
- Description string
- OriginLanguage string
- TargetLanguage string
- StyleHint string
-}
-
-func RenderCoverPrompt(tmpl string, data CoverPromptData) string {
- replacer := strings.NewReplacer(
- "{{title}}", data.Title,
- "{{description}}", data.Description,
- "{{origin_language}}", data.OriginLanguage,
- "{{target_language}}", data.TargetLanguage,
- "{{style_hint}}", data.StyleHint,
- )
- return replacer.Replace(tmpl)
-}
-```
-
-- [ ] **Step 6: 运行测试确认通过**
-
-Run: `gofmt -w config/config.go internal/pipeline/cover.go internal/pipeline/cover_test.go pkg/image/openai_compatible.go pkg/image/openai_compatible_test.go && go test ./config ./internal/pipeline ./pkg/image -run 'TestDefaultImageConfig|TestRenderCoverPrompt|TestOpenAI' -count=1`
-
-Expected: PASS。
-
-- [ ] **Step 7: 提交**
-
-```bash
-git add config/config.go config/config-example.toml internal/pipeline/cover.go internal/pipeline/cover_test.go pkg/image/openai_compatible.go pkg/image/openai_compatible_test.go
-git commit -m "feat: add cover generation config"
-```
-
----
-
-### Task 15: 发布配置和文档
-
-**Files:**
-- Modify: `.goreleaser.yaml`
-- Modify: `README.md`
-- Modify: `docs/zh/README.md`
-- Test: build command
-
-- [ ] **Step 1: 修改 GoReleaser build**
-
-把 `.goreleaser.yaml` 的 `builds` 扩成两个 build:
-
-```yaml
-builds:
- - id: server
- binary: KrillinAI
- env:
- - CGO_ENABLED=0
- goos:
- - darwin
- - linux
- - windows
- main: ./cmd/server/main.go
- - id: cli
- binary: krillinai
- env:
- - CGO_ENABLED=0
- goos:
- - darwin
- - linux
- - windows
- main: ./cmd/cli/main.go
-```
-
-- [ ] **Step 2: 增加 README CLI 示例**
-
-在 `README.md` 和 `docs/zh/README.md` 中增加中文 CLI 说明。内容包括:
-
-```markdown
-### CLI 用法
-
-KrillinAI 提供阶段化 CLI,适合脚本和 Agent 调用。每个命令默认同步执行,完成后输出 JSON。
-
-```bash
-krillinai subtitle "https://www.youtube.com/watch?v=dQw4w9WgXcQ" --origin-lang en --target-lang zh_cn --workdir tasks/demo
-krillinai tts --workdir tasks/demo --input-srt tasks/demo/target_language_srt.srt --line-mode target-only
-krillinai render-horizontal --workdir tasks/demo --video tasks/demo/origin_video.mp4 --subtitle tasks/demo/bilingual_srt.srt
-krillinai render-vertical --workdir tasks/demo --video tasks/demo/origin_video.mp4 --subtitle tasks/demo/short_origin_mixed_srt.srt
-```
-
-Agent 应优先读取 stdout JSON 和 `krillinai_manifest.json`,不要解析普通日志。
-```
-
-- [ ] **Step 3: 构建 server 和 CLI**
-
-Run:
-
-```bash
-go build -o build/KrillinAI ./cmd/server
-go build -o build/krillinai ./cmd/cli
-```
-
-Expected: 两个命令都成功,`build/KrillinAI` 和 `build/krillinai` 存在。
-
-- [ ] **Step 4: 运行文档相关测试**
-
-Run: `go test ./internal/pipeline ./internal/cli ./internal/service ./config -count=1`
-
-Expected: PASS。
-
-- [ ] **Step 5: 提交**
-
-```bash
-git add .goreleaser.yaml README.md docs/zh/README.md
-git commit -m "docs: add cli usage"
-```
-
----
-
-### Task 16: 最终验证
-
-**Files:**
-- No code changes expected
-
-- [ ] **Step 1: 全量 Go 测试**
-
-Run: `go test ./...`
-
-Expected: PASS。如果现有桌面依赖导致环境相关失败,记录失败包和错误,并至少确认以下命令 PASS:
-
-```bash
-go test ./internal/pipeline ./internal/cli ./internal/service ./pkg/util ./config -count=1
-```
-
-- [ ] **Step 2: CLI dry-run 验证**
-
-Run:
-
-```bash
-go build -o build/krillinai ./cmd/cli
-./build/krillinai subtitle local:demo.mp4 --origin-lang en --target-lang zh_cn --workdir /tmp/krillinai-cli-demo --dry-run
-```
-
-Expected: stdout JSON 包含:
-
-```json
-{
- "ok": true,
- "stage": "subtitle"
-}
-```
-
-并且 `/tmp/krillinai-cli-demo/krillinai_manifest.json` 存在。
-
-- [ ] **Step 3: 真实短链路冒烟验证**
-
-在本地 `config/config.toml` 已配置可用 LLM 和 transcribe provider 时运行:
-
-```bash
-./build/krillinai subtitle "https://www.youtube.com/watch?v=dQw4w9WgXcQ" --origin-lang en --target-lang zh_cn --workdir /tmp/krillinai-real-demo --caption-source any
-```
-
-Expected:
-
-- stdout JSON 包含 `"ok":true`。
-- `/tmp/krillinai-real-demo/origin_language_srt.srt` 存在。
-- `/tmp/krillinai-real-demo/target_language_srt.srt` 存在。
-- `/tmp/krillinai-real-demo/bilingual_srt.srt` 存在。
-
-- [ ] **Step 4: 检查工作区**
-
-Run: `git status --short`
-
-Expected: 只出现执行验证产生的本地非提交文件;没有未提交的源码改动。
-
-- [ ] **Step 5: 保存项目状态到 AgentMemory**
-
-保存内容:
-
-```text
-KrillinAI CLI 化已完成第一阶段实施:阶段化命令、pipeline core、manifest、JSON 输出、字幕/TTS/横竖屏渲染和基础封面配置。记录通过的测试命令、未覆盖的真实 API 冒烟项和下一步发布事项。
-```
diff --git a/docs/superpowers/specs/2026-05-28-krillinai-cli-design.md b/docs/superpowers/specs/2026-05-28-krillinai-cli-design.md
deleted file mode 100644
index 5d905287..00000000
--- a/docs/superpowers/specs/2026-05-28-krillinai-cli-design.md
+++ /dev/null
@@ -1,318 +0,0 @@
-# KrillinAI CLI 化设计
-
-日期:2026-05-28
-
-## 背景
-
-KrillinAI 现有能力主要通过 Web/桌面入口触发,核心流程集中在 `StartSubtitleTask` 的后台 goroutine 中:链接转本地音视频、字幕生成、TTS、视频嵌字幕、结果上传。用户希望把这些能力 CLI 化,让 Agent 可以稳定、可组合地调用,并能在失败后基于已生成产物继续执行。
-
-现有任务目录已经形成了一套有效产物约定,例如 `origin_video.mp4`、`origin_audio.mp3`、`origin_language_srt.srt`、`target_language_srt.srt`、`bilingual_srt.srt`、`short_origin_mixed_srt.srt`。CLI 设计应复用这些约定,同时补齐机器可读输出、阶段化调用和真实回退语义。
-
-## 目标
-
-1. 提供阶段化 CLI,方便 Agent 单独调用字幕、TTS、横屏视频、竖屏视频、封面生成能力。
-2. 提供 `pipeline` 命令,把阶段串成完整流水线。
-3. 支持 YouTube、Bilibili 链接和本地文件。
-4. 字幕阶段优先使用平台已有字幕,找不到或处理失败时按策略回退到 Whisper/现有转录 provider。
-5. 每个命令默认同步执行,输出稳定 JSON,并维护 `krillinai_manifest.json`。
-6. 复用现有 service 能力,避免重新实现一套视频处理业务逻辑。
-
-## 非目标
-
-1. 第一版不重写 server/desktop UI。
-2. 第一版不要求完全移除现有 `StartSubtitleTask` 异步任务。
-3. 第一版不把 CLI 做成仅调用本地 HTTP server 的包装器。
-4. 封面生成可以先落接口和配置契约;如 image provider 接入成本过高,可排到第二阶段实现。
-
-## 推荐方案
-
-采用“阶段化命令 + pipeline 编排 + 本地 Pipeline Core”。
-
-新增 CLI 入口,命令直接调用本地 Pipeline Core,而不是强依赖已启动的 HTTP server。Pipeline Core 从现有 `internal/service` 中抽出同步阶段函数,供 CLI 调用;server/desktop 后续可逐步迁移到同一层。
-
-备选方案比较:
-
-1. HTTP API 包装型 CLI:改动小,但依赖 server 进程,任务状态在内存中,阶段化能力受限。
-2. 本地 Pipeline Core:更适合 Agent,可同步、可恢复、产物路径稳定。推荐采用。
-3. 独立新流水线:边界最干净,但会复制大量下载、字幕、TTS 和渲染逻辑,维护风险高。
-
-## CLI 命令结构
-
-推荐命令形态:
-
-```bash
-krillinai subtitle <url-or-local-file> --origin-lang en --target-lang zh_cn --workdir tasks/foo
-krillinai tts --workdir tasks/foo --input-srt target_language_srt.srt --line-mode target-only
-krillinai render-horizontal --workdir tasks/foo --video origin_video.mp4 --subtitle bilingual_srt.srt
-krillinai render-horizontal --workdir tasks/foo --video origin_video.mp4 --audio tts_final_audio.wav --subtitle target_language_srt.srt
-krillinai render-vertical --workdir tasks/foo --video origin_video.mp4 --subtitle short_origin_mixed_srt.srt
-krillinai render-vertical --workdir tasks/foo --video origin_video.mp4 --audio tts_final_audio.wav --subtitle target_language_srt.srt
-krillinai cover --workdir tasks/foo --input-cover origin_cover.jpg --prompt-template prompts/bilibili-cover.md
-krillinai pipeline <url-or-local-file> --origin-lang en --target-lang zh_cn --outputs subtitle,tts,horizontal-bilingual,horizontal-dubbed,vertical-bilingual,vertical-dubbed,cover
-```
-
-阶段命令默认同步执行。`pipeline` 默认同步,支持 `--async`;异步模式返回 `task_id`,并通过 `krillinai status <task_id>` 查询状态。
-
-## 工作目录与产物契约
-
-CLI 支持两种工作目录模式:
-
-1. 不传 `--workdir`:沿用 `./tasks/<task_id>/`。
-2. 传 `--workdir`:所有阶段在该目录读写,推荐 Agent 使用。
-
-字幕阶段核心产物:
-
-```text
-origin_video.mp4
-origin_audio.mp3
-origin_language_srt.srt
-target_language_srt.srt
-bilingual_srt.srt
-short_origin_srt.srt
-short_origin_mixed_srt.srt
-output/origin_language.txt
-output/target_language.txt
-```
-
-TTS 阶段产物:
-
-```text
-tts_final_audio.wav
-video_with_tts.mp4
-audio_duration_details.txt
-```
-
-视频阶段产物:
-
-```text
-horizontal_bilingual.mp4
-horizontal_dubbed.mp4
-vertical_bilingual.mp4
-vertical_dubbed.mp4
-transferred_vertical_video.mp4
-```
-
-封面阶段产物:
-
-```text
-origin_cover.jpg
-origin_cover.png
-generated_cover.png
-cover_prompt.final.txt
-```
-
-每个阶段更新 `krillinai_manifest.json`,记录输入 URL、语言、字幕来源、provider、产物路径、警告、阶段状态和可恢复信息。
-
-## 字幕生成流程
-
-`krillinai subtitle` 从链接或本地视频生成原语言、目标语言、双语字幕。输入支持 YouTube、Bilibili、`local:<path>` 和普通本地路径。
-
-字幕来源通过参数控制:
-
-```bash
---caption-source any
---caption-source manual
---caption-source auto
---caption-source whisper
-```
-
-默认 `any`,语义为:人工字幕、自动字幕、Whisper/转录 provider。`manual` 和 `auto` 表示禁止回退到转录,找不到或处理失败即失败。
-
-YouTube 流程:
-
-1. 用 `yt-dlp` 查询并下载匹配 `--origin-lang` 的人工或自动字幕,支持 `.srt` 和 `.vtt`。
-2. VTT 继续复用现有 word-level/block-level 处理逻辑生成标准 SRT。
-3. 生成目标语言字幕和双语字幕。
-4. 如果平台字幕不可用且策略允许,则下载音频并进入转录流程。
-
-Bilibili 流程:
-
-1. 优先尝试平台字幕。
-2. 字幕不可用且策略允许时,下载音频并进入转录流程。
-
-本地文件流程:
-
-1. 默认抽取音频并转录。
-2. 如果用户传 `--input-srt`,跳过转录,只做翻译和双语合成。
-
-需要修正现有行为:当前 YouTube VTT 下载或处理失败时日志写了 fallback,但代码实际把任务置失败。Pipeline Core 中应按 `caption-source` 策略真正回退到转录。
-
-字幕命令 stdout 示例:
-
-```json
-{
- "ok": true,
- "stage": "subtitle",
- "caption_source": "youtube_auto_vtt",
- "outputs": {
- "origin_srt": "tasks/foo/origin_language_srt.srt",
- "target_srt": "tasks/foo/target_language_srt.srt",
- "bilingual_srt": "tasks/foo/bilingual_srt.srt"
- },
- "warnings": ["人工字幕未找到,使用自动字幕"]
-}
-```
-
-## TTS 设计
-
-`krillinai tts` 把目标语言字幕变成配音。命令要求显式传 `--input-srt`,并用 `--line-mode` 描述文本提取方式:
-
-```bash
---line-mode target-only
---line-mode bilingual-target-top
---line-mode bilingual-target-bottom
-```
-
-默认输入为 `target_language_srt.srt`,默认 `line-mode` 为 `target-only`。输出 `tts_final_audio.wav`。如果 `--video` 存在,或 workdir 中存在 `origin_video.mp4`,额外生成 `video_with_tts.mp4`。
-
-TTS provider 复用现有配置中的 `openai`、`aliyun`、`edge-tts`。CLI 支持 `--voice` 和 `--voice-clone-source` 覆盖配置。
-
-失败策略沿用现有思路:少量字幕失败时允许继续,超过一半失败则整体失败。stdout 和 manifest 必须列出失败字幕 index,方便 Agent 重试或人工处理。
-
-## 横屏与竖屏视频生成
-
-视频生成拆成两个命令:
-
-```bash
-krillinai render-horizontal --subtitle bilingual_srt.srt
-krillinai render-horizontal --audio tts_final_audio.wav --subtitle target_language_srt.srt
-krillinai render-vertical --subtitle short_origin_mixed_srt.srt
-krillinai render-vertical --audio tts_final_audio.wav --subtitle target_language_srt.srt
-```
-
-没有 `--audio` 时表示“原视频 + 字幕”。有 `--audio` 时表示“替换为 TTS 配音 + 字幕”。
-
-横屏输出:
-
-```text
-horizontal_bilingual.mp4
-horizontal_dubbed.mp4
-```
-
-竖屏输出:
-
-```text
-vertical_bilingual.mp4
-vertical_dubbed.mp4
-```
-
-竖屏命令会把横屏源视频转换为竖屏中间产物 `transferred_vertical_video.mp4`。双语竖屏默认使用 `short_origin_mixed_srt.srt`,TTS 竖屏默认使用 `target_language_srt.srt`。
-
-现有 `horizontal_embed.mp4` 和 `vertical_embed.mp4` 命名对 Agent 不够明确。CLI 层应输出更具体的 bilingual/dubbed 文件名,避免后续步骤找错文件。
-
-## 封面生成
-
-`krillinai cover` 从原封面和 prompt 模板生成新封面:
-
-```bash
-krillinai cover --workdir tasks/foo --input-cover origin_cover.jpg --prompt-template prompts/bilibili-cover.md
-krillinai cover --workdir tasks/foo --url "https://youtube.com/..." --prompt-template prompts/bilibili-cover.md
-```
-
-如果传 URL,CLI 先用 `yt-dlp` 下载原封面到 `origin_cover.jpg` 或 `origin_cover.png`。
-
-prompt 模板支持变量:
-
-```text
-{{title}}
-{{description}}
-{{origin_language}}
-{{target_language}}
-{{style_hint}}
-```
-
-输出:
-
-```text
-cover_prompt.final.txt
-generated_cover.png
-```
-
-image provider 采用 OpenAI-compatible 配置:
-
-```toml
-[image]
-provider = "openai-compatible"
-
-[image.openai]
-base_url = ""
-api_key = ""
-model = "gpt-image-1"
-```
-
-## JSON 输出与退出码
-
-所有 CLI 命令统一遵守:
-
-1. 成功:退出码 `0`,stdout 输出 JSON,日志走 stderr 或 log 文件。
-2. 参数或配置错误:退出码 `1`,stdout 输出 JSON,`retryable:false`。
-3. 可恢复失败:退出码 `2`,stdout 输出 JSON,包含 `ok:false`、`stage`、`error.code`、`retryable:true` 和已生成产物。
-4. 外部依赖缺失:退出码 `3`,指出缺少 `ffmpeg`、`yt-dlp`、模型或 API key。
-
-Agent 应只依赖退出码、stdout JSON 和 `krillinai_manifest.json`,不解析普通日志。
-
-## 内部架构
-
-新增一层 Pipeline Core,建议包名为 `internal/pipeline`。核心接口:
-
-```go
-PrepareMedia(ctx, req) (Manifest, error)
-GenerateSubtitles(ctx, req) (Manifest, error)
-GenerateSpeech(ctx, req) (Manifest, error)
-RenderHorizontal(ctx, req) (Manifest, error)
-RenderVertical(ctx, req) (Manifest, error)
-GenerateCover(ctx, req) (Manifest, error)
-RunPipeline(ctx, req) (Manifest, error)
-```
-
-`Manifest` 是阶段之间的稳定接口。CLI 参数优先级高于 manifest,manifest 再补齐默认路径。
-
-第一版可先让 Pipeline Core 包装现有 `internal/service` 的能力,但要把异步 goroutine 流程改造成同步可调用阶段。server/desktop 可暂时保持现状,后续再迁移。
-
-## 测试策略
-
-单元测试:
-
-1. CLI 参数解析。
-2. manifest 读写与参数覆盖规则。
-3. 字幕来源策略。
-4. 双语字幕 `line-mode` 文本抽取。
-5. 输出文件命名。
-
-集成测试:
-
-1. 用短样例 SRT 验证 TTS 输入解析和音频拼接逻辑。
-2. 用短视频验证横屏/竖屏渲染命令构造和产物存在。
-3. 外部 API 使用 fake provider 或 mock client。
-
-冒烟测试:
-
-1. 本地配置可用时,用短 YouTube/Bilibili 链接跑字幕生成。
-2. 验证 stdout JSON、manifest 和核心产物存在。
-3. 验证平台字幕失败时能按策略回退转录。
-
-## 实施边界
-
-第一阶段实现:
-
-1. `subtitle`
-2. `tts`
-3. `render-horizontal`
-4. `render-vertical`
-5. `pipeline`
-6. `krillinai_manifest.json`
-7. 统一 stdout JSON 与退出码
-
-第二阶段实现或完善:
-
-1. `cover`
-2. server/desktop 迁移到 Pipeline Core
-3. 更完整的异步任务持久化
-4. 更多字幕平台来源策略
-
-## 待确认风险
-
-1. Bilibili 平台字幕获取能力需要在实施前验证现有 `yt-dlp` 行为;如果不可用,应明确回退到转录。
-2. 现有 TTS 少量失败继续执行的策略可能生成不完整配音;manifest 必须暴露失败 index。
-3. 横屏输入为竖屏时,现有逻辑会跳过横屏生成;CLI 应在 JSON 中返回 warning,而不是静默成功。
-4. image provider 的兼容协议可能因供应商差异需要适配层,第一版可先以 OpenAI Images API 形态作为最小实现。