【直播切片工作台】第40章:capcut-mate 客户端

简介: capcut-mate 客户端是轻量级剪映草稿操控工具,封装 create_draft/add_videos/add_captions/gen_video 四大接口,内置请求审计、双基址路由、健壮轮询等待器及两层错误处理,专注可靠、可追溯、易排障的自动化视频生成。

第40章:capcut-mate 客户端

capcut-mate 是独立的剪映草稿操控服务(第 48 章的部署拓扑中作为兄弟容器存在)。pkg/capcutmate 是它在 live-mixer 侧的薄客户端:四个业务端点(create_draft / add_videos / add_captions / gen_video)共享一个 HTTP 内核,外加每个请求的落盘审计与视频生成的轮询等待器。

流程

所有端点汇聚到 doJSONURL:序列化请求 → POST → 读取响应 → (可选)写审计记录 → 校验 HTTP 状态 → 反序列化。业务方法再叠加两层校验:业务码 code != 0 报错、关键字段为空(如 draft_url)报错。

flowchart TD
    A[CreateDraft / AddVideos /<br/>AddCaptions] --> B[doJSON<br/>baseURL+path]
    C[GenVideo / GenVideoStatus] --> D[doJSONURL<br/>genVideoBaseURL 或 baseURL]
    B & D --> E[序列化 → POST → 读响应]
    E --> F[writeRecord<br/>00N_endpoint.json]
    F --> G{HTTP 2xx?}
    G -- 否 --> H[错误含状态码与响应体]
    G -- 是 --> I{code != 0 或关键字段空?}
    I -- 是 --> J[业务错误]
    I -- 否 --> K[返回强类型响应]
    L[GenerateVideoAndWait] --> M[GenVideo 提交]
    M --> N[循环 GenVideoStatus<br/>5s × 最多360次]
    N --> O[completed → video_url<br/>failed → 错误信息<br/>未知状态 → 报错]

实现

双基址设计。Config.GenVideoBaseURL 允许视频生成接口走与草稿接口不同的根地址——生产环境中 gen_video 可能部署在带 GPU 的另一台机器(或需 API Key 的网关),genVideoEndpoint 在两个基址间做三元选择。BaseURL 缺省回落硬编码的 http://192.168.3.219:81(内网地址),组合根必会覆盖。

请求级审计落盘。writeRecord 把每次调用完整写入 recordDir(即 Session 的 RecordDir,staging/{task_id}/capcut_mate/),文件名 001_create_draft.json 序号递增。apiCallRecord 含 seq、UTC 时间戳、方法、路径、请求体、HTTP 状态、响应体。设计上的三个巧思:其一,传输层失败也落盘(_error 字段记录 Go 错误、status=0),网关 502 的 HTML 响应以 _raw_text 保留原文——非 JSON 响应正是生产排障最常缺的现场;其二,序号按目录已有文件数计算,同一任务从 001 起算、重试续号,天然形成时间线;其三,写记录失败被静默忽略(_ = c.writeRecord)——审计不能反过来破坏业务。

两层错误模型。HTTP 层错误带状态码与响应体全文;业务层错误带 code 与 message(capcut-mate 沿用本项目的 {code, message, data} 信封约定)。调用方从错误字符串即可区分"服务挂了"与"服务拒绝了这个请求"。

GenerateVideoAndWait 的状态机。提交后循环查询:completed 校验 video_url 非空再返回;failed 取 error_message,三级回退(error_message → message → 默认文案);pending/processing/空串继续等;未知状态直接报错——宁可失败也不把未定义状态当成功吞掉。轮询上限 360 次 × 5 秒 ≈ 30 分钟,与"视频生成是重活"的预期对齐。sleepWithContext 用 select+timer 实现可取消的 sleep,ctx 取消立即返回,不留悬挂 goroutine。

APIKey 的选择性要求:只有 GenVideo 校验 Key 非空(草稿接口免鉴权),与 capcut-mate 服务端的鉴权设计一致。

📌 设计决策

  • 客户端内建审计而非中间件:recordDir 作为方法参数一路从 Session 传到 HTTP 内核,每个业务调用自己决定是否记录;比全局 HTTP 拦截器更精准(健康检查等噪音不会混入)。
  • 非 JSON 响应不报错、先记录:网关 502 返回 HTML 时,HTTP 层错误已带原文,同时审计文件里有独立副本——两处现场互为备份。
  • 未知状态显式失败:capcut-mate 未来新增状态(如 "paused")时,旧客户端会明确报错而非静默空转,暴露契约漂移。
  • 轮询上限 30 分钟而非无限:给任务层的孤儿回收(20 分钟 stale 阈值)与用户预期一个确定边界;超时错误明确写"已尝试 N 次"。

代码示例

片段 1 展示 HTTP 内核与审计(摘自 capcutmate/client.go,节选):

// doJSONURL 向指定 URL 发送 JSON POST;recordPath 用于落盘记录中的 path 字段。
func (c *Client) doJSONURL(ctx context.Context, url, recordPath, name string, reqBody any, respBody any, recordDir string) error {
   
    payload, err := json.Marshal(reqBody)
    if err != nil {
   
        return fmt.Errorf("序列化请求失败: %w", err)
    }
    httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(payload))
    if err != nil {
   
        return fmt.Errorf("创建请求失败: %w", err)
    }
    httpReq.Header.Set("Content-Type", "application/json")

    httpResp, err := c.http.Do(httpReq)
    status := 0
    if err != nil {
   
        // 传输层失败也落盘,保留现场
        _ = c.writeRecord(recordDir, name, recordPath, payload, 0, map[string]string{
   "_error": err.Error()})
        return fmt.Errorf("请求 capcut-mate %s 失败: %w", recordPath, err)
    }
    defer httpResp.Body.Close()
    status = httpResp.StatusCode
    respBytes, _ := io.ReadAll(httpResp.Body)

    // 优先按 JSON 解析;失败则将原始文本写入记录,便于排查网关/502 问题。
    var recordedResp any
    if len(bytes.TrimSpace(respBytes)) == 0 {
   
        recordedResp = map[string]string{
   "_raw_text": ""}
    } else if json.Valid(respBytes) {
   
        recordedResp = json.RawMessage(respBytes)
    } else {
   
        recordedResp = map[string]string{
   "_raw_text": string(respBytes)}
    }
    _ = c.writeRecord(recordDir, name, recordPath, payload, status, recordedResp)

    if status < 200 || status >= 300 {
   
        return fmt.Errorf("capcut-mate %s HTTP %d: %s", recordPath, status, strings.TrimSpace(string(respBytes)))
    }
    return json.Unmarshal(respBytes, respBody)
}

// writeRecord 将一次 API 调用写入 recordDir,文件名形如 001_create_draft.json。
// 序号按目录内已有记录文件数递增,保证同一 task 的 staging 目录从 001 起算。
func (c *Client) writeRecord(recordDir, name, path string, requestJSON []byte, httpStatus int, response any) error {
   
    if strings.TrimSpace(recordDir) == "" {
   
        return nil
    }
    if err := os.MkdirAll(recordDir, 0o755); err != nil {
   
        return err
    }
    seq := 1
    if entries, err := os.ReadDir(recordDir); err == nil {
   
        seq = len(entries) + 1
    }
    rec := apiCallRecord{
   
        Seq: seq, RecordedAt: time.Now().UTC().Format(time.RFC3339Nano),
        Method: http.MethodPost, Path: path,
        Request: json.RawMessage(requestJSON),
        ResponseHTTPStatus: httpStatus, Response: json.RawMessage(respRaw),
    }
    data, _ := json.MarshalIndent(rec, "", "  ")
    return os.WriteFile(filepath.Join(recordDir, fmt.Sprintf("%03d_%s.json", seq, name)), data, 0o644)
}

片段 2 展示轮询等待器(摘自 capcutmate/gen_video.go,节选):

// GenerateVideoAndWait 提交视频生成并轮询直至完成/失败/超时,成功时返回 video_url。
func (c *Client) GenerateVideoAndWait(ctx context.Context, draftURL, recordDir string, onProgress VideoProgressCallback) (string, error) {
   
    if _, err := c.GenVideo(ctx, draftURL, recordDir); err != nil {
   
        return "", err
    }
    for i := 0; i < c.maxPolls; i++ {
   
        if i > 0 {
   
            if err := sleepWithContext(ctx, c.pollInterval); err != nil {
   
                return "", err
            }
        }
        statusResp, err := c.GenVideoStatus(ctx, draftURL, recordDir)
        if err != nil {
   
            return "", err
        }
        if onProgress != nil {
   
            onProgress(statusResp.Progress, statusResp.Status)
        }
        switch strings.ToLower(strings.TrimSpace(statusResp.Status)) {
   
        case GenVideoStatusCompleted:
            videoURL := strings.TrimSpace(statusResp.VideoURL)
            if videoURL == "" {
   
                return "", fmt.Errorf("gen_video 完成但未返回 video_url")
            }
            return videoURL, nil
        case GenVideoStatusFailed:
            msg := strings.TrimSpace(statusResp.ErrorMessage)
            if msg == "" {
   
                msg = "视频生成失败"
            }
            return "", fmt.Errorf("gen_video 失败: %s", msg)
        case GenVideoStatusPending, GenVideoStatusProcessing, "":
            // 继续轮询。
        default:
            return "", fmt.Errorf("gen_video 未知状态: %s", statusResp.Status)
        }
    }
    return "", fmt.Errorf("gen_video 轮询超时,已尝试 %d 次", c.maxPolls)
}

func sleepWithContext(ctx context.Context, d time.Duration) error {
   
    timer := time.NewTimer(d)
    defer timer.Stop()
    select {
   
    case <-ctx.Done():
        return ctx.Err()
    case <-timer.C:
        return nil
    }
}

小结

一个 HTTP 内核吃下四个端点;审计落盘把"调用过什么、返回过什么"变成任务级可回放的档案;轮询状态机用显式失败守住未知状态。这个包是"薄客户端做厚防御"的完整示范。

思考题

  1. 轮询记录也走 writeRecord——每 5 秒一条 gen_video_status 记录,30 分钟任务会产生约 360 个 JSON 文件。审计价值与文件膨胀如何权衡?你会只记录状态变化的"边沿"吗?
  2. writeRecord 的序号依赖"目录文件数 + 1",若清理进程在轮询期间删掉部分记录,序号会重复——这是否是缺陷?如何用原子计数或时间戳命名规避?

项目信息

  • GitHub仓库:Chyona/live-mixer
相关文章
|
7天前
|
Linux Go 开发工具
手机上跑 DeepSeek 智能体:开源安卓客户端 DSH Go 安装与使用指南
DSH Go 是一款开源安卓客户端,将 DeepSeek Harness 智能体引擎装进手机:免 Root、免 Termux,一键安装即用;支持本机运行(内置 Ubuntu+Node.js)或远程接管电脑会话;具备插话打断、过程折叠、屏幕操控、端到端加密分享等特色功能,真正实现智能体“口袋化”。
8381 19
|
7天前
|
弹性计算 人工智能 API
Codex超详细入门指南(下载·安装·登录·上手,全版本覆盖,2026最新版)
建议收藏本教程,2026 全年各版本更新随时回来查阅。如果你在搭建过程中遇到任何问题,欢迎结合 阿里云工单系统 提交技术支持请求,或在 阿里云开发者社区 搜索 Codex 相关话题交流。 祝你编码愉快,效率翻倍!
2563 12
|
2天前
|
人工智能 安全 应用服务中间件
NGINX 爆出两处高危漏洞 可导致未经身份验证的远程代码执行
NGINX曝出两个高危漏洞(CVE-2026-123633和CVE-2026-123007),CVSS 9.2分,均属HTTP/2内存安全缺陷,无需认证即可远程执行代码。影响自2015年起的多个版本,静态站点亦受威胁。修复版本为开源版1.30.7/1.31.9。(239字)
1256 0
NGINX 爆出两处高危漏洞 可导致未经身份验证的远程代码执行
|
5天前
|
传感器 安全 区块链
Windows 电脑运行安卓应用教程:开源工具 ApkStart 双击 APK 即装、独立窗口运行
ApkStart 是一款开源Windows工具,让安卓APP像原生软件一样运行:双击APK即安装、生成真实图标、独立窗口启动、开始菜单可搜索。无需传统模拟器,内置QEMU运行时,支持数据互通、ARM兼容与命令行操作。(239字)
|
9天前
|
人工智能 前端开发 API
阿里云Qwen4-Max 大模型详解:定位、特征、能力、适用场景与相对Qwen3-Max差异解析
2026年11月11日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问AI平台Token Plan并接入千问办公、Qoder等入口。该版本聚焦知识理解、世界感知、编程与Agentic四项升级,主打复杂编程、专业办公、前端设计与专业软件操作等真实任务。预览期为11月11日10:00至11月25日24:00,仅支持Token Plan调用,到期后模型标识下线;限时2折、新用户再享5折,最低1折可体验。
|
9天前
|
JSON 前端开发 API
阿里云最新Qwen4-Max大模型介绍:模型定位、特征、能力、适用场景解析
2026 年 11 月 11 日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问 AI 平台 Token Plan,并同步接入千问办公、Qoder 等入口。该版本聚焦知识理解、世界感知、编程与 Agentic 四项升级,主打复杂编程、专业办公、前端设计与专业软件操作。预览期至 11 月 25 日 24:00,到期后模型标识下线;限时 2 折、新用户再享 5 折,最低 1 折可体验。
|
22天前
|
Linux 开发工具 iOS开发
Codex保姆级教程(下载+安装+登录+使用,含所有版本,2026最新)
Codex是OpenAI推出的开源AI编程智能体,本地运行,可理解整个代码库,支持自然语言指令改代码、执行命令、跑测试、修Bug,兼容Win/macOS/Linux。(239字)
10751 59
|
5天前
|
人工智能 弹性计算 开发工具
零成本玩各大模型!DeepSeek Harness dsh-our-free-model 插件,13 个厂商模型直接用
总结一下:装这个插件,你不用注册、不用绑卡、不用填一个 Key,就能在 DeepSeek Harness 里用上 DeepSeek V4.1 Flash、Kimi K3 这一批前沿模型,而且是白嫖的、还不限量。三步搞定:下载插件,复制包含 `package.json` 的插件目录路径,在「添加插件」里粘贴路径安装并重启。无论是在阿里云 ECS 上通过命令行部署的 Web 版,还是本地的 Electron 桌面端,都能顺利跑通,快速搭建一套零成本的免费模型使用环境。
1202 1
|
8天前
|
Linux API iOS开发
【DSH】DeepSeek Harness新手保姆教程(下载+安装+配置+使用,2026最新实测)
DeepSeek Harness(dsh)是DeepSeek AI开源的智能体框架,秉持“一切皆插件”理念,支持读文件、改代码、跑命令、处理表格、联网搜索等操作。免费开源,兼容Windows/macOS/Linux,提供桌面端与网页端,可灵活安装插件扩展能力。

热门文章

最新文章