8.1 技能流水线思想

8.1 技能流水线思想

本节摘要：编排的第一步不是写 Agent，而是把已有流水线改造成"可被编排的形态"。本节给出技能的定义：一段可重跑的流水线，加上输入输出契约与验收条件——契约让调用方知道给什么、拿什么，验收让执行方知道什么时候算成功。以 OpenMontage（社区口径约 68.6k 星）的技能体系为主案例，拆解"12 条流水线、700 多个技能"背后的分层：原子技能做一件小事，组合技能把原子技能连成线。然后落成三件东西：一份技能注册表、一个带验收的执行器、一张 Agent 职责边界表；最后用"生成模型做内容、决策模型做把关"收束——这是全章的思想地基。仓库数据为社区口径，以官方文档为准。

学习目标

• 用"输入输出契约加验收条件"给自己流水线里的每一段下定义。
• 设计技能注册表的结构：标识、描述、输入、输出、验收、命令。
• 写出带输入校验与产物验收的技能执行器。
• 划清 Agent 与技能的职责边界：路由、改参、重试、上报。
• 说清生成与把关分离的理由，并指出混装的典型事故。

一、从"跑脚本"到"用技能"

前七章积累了大量脚本：生成镜头的、配音的、混音的、做字幕的。它们的共同问题是：只有作者本人知道怎么调用——输入是什么格式、输出落在哪、怎样算成功。把脚本升级为技能，就是把这些隐性知识写成显式契约：

技能的定义只有一句话：技能等于输入输出契约加验收条件。契约回答"接口长什么样"，验收回答"怎样算做完了"。两者齐备，任何调用者——人、调度器或 Agent——都不需要读懂实现。

二、案例解剖：OpenMontage 式技能体系

OpenMontage（calesthio/OpenMontage）是 Agent 式视频生产的代表性开源项目，社区口径约 68.6k 星，官方口径以项目文档为准。它最值得学的不是某个算法，而是组织方式：据报道其技能体系包含 12 条流水线与 700 多个技能。两个数字背后是清晰的分层——12 条流水线对应 12 类成品形态（不同时长、风格、用途的片子），700 多个技能是组成这些流水线的原子能力：生成一帧、生成一个镜头、合成一段音频、检索一张参考图、校验一处一致性。

分层示意（以 OpenMontage 体系为原型的抽象）

 成品层    12 条流水线：竖屏短剧线、解说线、混剪线……
            │ 每条流水线 = 有序的技能引用 + 组装规则
 组合层    "出一条短剧"技能 = 剧本→分镜→镜头→音频→字幕→合成
            │
 原子层    700+ 技能：单镜头生成、单句 TTS、单图检索、单项校验
            │ 每个技能 = 输入输出契约 + 验收条件
​

分层带来的直接收益是复用：同一段"单镜头生成"技能，短剧线用、解说线也用；升级一处，十二条线同时受益。自建体系不必追求 700 个技能，先从每条流水线抽出五到十个原子技能开始，数量会随着复用需求自然生长。

三、契约设计三要素

要素一：输入 schema。声明必需字段与类型，执行前先校验，缺字段立刻报错——比跑到一半崩掉便宜得多。镜头契约是全书的枢纽结构（第 02 章定义），技能输入大多是它的投影或扩展。要素二：输出清单。技能产物一律"文件加清单"：文件落盘，清单写明路径与关键属性（时长、分辨率、sha256），机器验收只看清单与磁盘是否一致。要素三：验收条件。写成可执行的判定：文件存在、时长不低于计划值、分辨率等于目标值。验收条件是第 10.3 节质量门禁的最小单元，两者一脉相承。

# skills.jsonl —— 技能注册表：每行一个技能（示意，字段自定义）
{"id": "shot.t2v", "desc": "文生视频生成单镜头",
 "requires": ["id", "prompt", "video_sec"],
 "output": "build/clips/{id}.mp4",
 "accept": "存在且时长不低于 video_sec 减 0.3s",
 "cmd": "python skills/shot_t2v.py"}
{"id": "audio.tts_line", "desc": "单句TTS配音",
 "requires": ["shot_id", "line_id", "text", "voice_id"],
 "output": "audio/voice/{shot_id}_{line_id}.wav",
 "accept": "存在且时长不低于字数除以 4.3 再减 1s",
 "cmd": "python skills/tts_line.py"}
{"id": "sub.make_cues", "desc": "转写段加工为字幕cue",
 "requires": ["segments", "anchors"],
 "output": "build/cues.json",
 "accept": "存在且 validate_cues 通过",
 "cmd": "python skills/make_cues.py"}
​

四、执行器与 Agent 的职责边界

注册表是静态的，执行器把它跑起来：按标识查表、按 schema 校验输入、起子进程执行、按验收条件判定、把结果落成一行结构化状态。

# run_skill.py —— 技能执行器：查表、校验、执行、验收、落状态
import datetime, json, os, subprocess

REGISTRY, STATE = "skills/skills.jsonl", "build/skill_runs.jsonl"

def load_registry():
    rows = [json.loads(line) for line in open(REGISTRY, encoding="utf-8")
            if line.strip() and not line.startswith("#")]
    return {row["id"]: row for row in rows}

def validate_input(skill, payload_file):
    payload = json.load(open(payload_file, encoding="utf-8"))
    missing = [k for k in skill.get("requires", []) if k not in payload]
    if missing:
        raise SystemExit(f"技能 {skill['id']} 输入缺字段: {missing}")
    return payload

def accepted(skill, payload):
    out = skill["output"].format(**{k: v for k, v in payload.items()})
    return os.path.exists(out)

def run(skill_id, payload_file):
    skill = load_registry()[skill_id]
    payload = validate_input(skill, payload_file)
    subprocess.run(skill["cmd"].split() + [payload_file], check=True)
    event = {"skill": skill_id, "accepted": accepted(skill, payload),
             "at": datetime.datetime.now().isoformat(timespec="seconds")}
    with open(STATE, "a", encoding="utf-8") as f:
        f.write(json.dumps(event, ensure_ascii=False) + "\n")
    return event

if __name__ == "__main__":
    import sys
    print(run(sys.argv[1], sys.argv[2]))
​

执行器本身不知道"下一步做什么"，那是 Agent 的职责。边界如下：

五、生成与把关的分工

技能体系里最容易犯的错，是把"把关"也塞给生成模型：让视频模型自己评价自己生成的镜头。这等于让考生自己批卷。正确分工是：生成模型做内容，决策逻辑做把关——把关可以是确定性规则（时长、分辨率、黑帧），也可以是独立的小模型（语义贴合度的粗筛），但必须是与生成方利益分离的另一个组件。这与《Jev 决策编程》第 02 章《核心心智模型》的提醒一致：决策应当显式建模、独立演进，而不是藏在生成提示词的只言片语里。本章后续与第 10 章的质量门禁，都是这个分工的落地。

本节要点回顾

• 技能等于输入输出契约加验收条件，契约让调用方不读实现也能用。
• OpenMontage 式分层：成品层流水线引用组合技能，组合技能编排原子技能。
• 契约三要素：输入 schema、输出清单（文件加清单）、可执行验收条件。
• 执行器管"跑一个技能"，Agent 管"路由、改参、重试、上报"，结构性改动归人。
• 生成与把关分离：规则与独立模型做决策，不让生成模型自批自卷。

技能体系立起来了，先拿一个"不在本机"的环节练手：素材采集。下一节按 video-use 的思路，让 Agent 操作浏览器取参考图，并把来源与许可一并登记进契约。