OBS Studio 场景集合的 Agent 原生编辑：cli-anything-obs_studio 状态化 CLI 实战指南

本篇技术指南围绕 OBS Studio Agent Harness 的核心文档 SKILL.md 展开，系统讲解 cli-anything-obs_studio 这一有状态命令行接口（stateful CLI）的安装、命令体系、状态管理与 Agent 对接方式。它采用 JSON 场景集合（scene collection）格式，编辑过程完全不需要安装 OBS Studio，读者读完可以掌握如何用纯命令行为 OBS 直播/录播搭建整套场景结构（场景、来源、滤镜、音频、转场与推流录制配置），并以可解析的 JSON 输出被 AI Agent 直接消费。

一、CLI 定位与设计理念

cli-anything-obs_studio 是一套用于 OBS Studio 场景集合编辑的有状态命令行界面，遵循 CLI-Anything 生态中与 Blender CLI harness 相同的设计模式：

• 纯 JSON 工作流：整个项目就是一个符合 OBS 场景集合结构的 JSON 文件，所有命令围绕对该文档的增删改查展开；
• 免 GUI、免 OBS 安装：编辑场景集合本身不依赖 OBS Studio 运行，仅对 JSON 数据建模与校验，因此天然适合脚本化、批量化和无人值守场景；
• Agent 友好：支持 --json 结构化输出、明确的返回码与 stderr 错误通道，是 "Making Software Agent-Native" 理念在直播推流配置领域的具体落地。

其模块化实现位于 obs_studio 包目录，入口脚本为 obs_studio_cli.py，内部按职责拆分为 project/scenes/sources/filters/audio/transitions/output/session 八个核心模块，详见后文"源码架构"一节。

二、安装与前置条件

该 CLI 作为 cli-anything-obs_studio 包的一部分安装：

pip install cli-anything-obs_studio

前置条件：

• Python 3.10+；
• 系统需已安装 obs_studio（如果只是做纯 JSON 场景编辑建模，OBS 本体非必须——SKILL 文档明确说明 "No OBS installation required for editing"）；
• 依赖 click 与 prompt_toolkit（交互式 REPL 需要），仓库内的 setup.py 声明了打包入口。

三、两种运行模式与基础命令

3.1 一次性（one-shot）命令模式

# 查看帮助
cli-anything-obs_studio --help

# 创建新项目
cli-anything-obs_studio project new -o project.json

# 以 JSON 输出运行（面向 Agent 消费）
cli-anything-obs_studio --json project info -p project.json

3.2 交互式 REPL 模式

不带任何子命令直接运行即进入交互式 REPL：

cli-anything-obs_studio

REPL 支持 tab 补全与历史记录，输入 help 查看命令，输入 quit/exit/q 退出。REPL 的皮肤与提示逻辑由 repl_skin.py 提供，CLI 内部通过 cli.main(args, standalone_mode=False) 复用同一套子命令解析，保证 REPL 与 one-shot 模式下行为完全一致。

从源码看，CLI 顶层注册了三个全局选项（见 obs_studio_cli.py）：

全局选项	说明
--json	输出结构化 JSON（对应源码 --json is_flag，切换到机器可读输出）
--project <path>	指定 OBS 场景集合 JSON 文件，启动时自动加载
--dry-run	不落盘执行（修改状态但跳过自动保存）

此外，CLI 的 result_callback 实现了"退出自动保存"：只要会话持有项目且状态被修改（sess._modified 为真）且存在项目路径，one-shot 命令结束后会自动调用 save_session() 落盘；--dry-run 与 REPL 模式除外。

四、八大命令组全景

4.1 Project 项目组

命令	说明
new	创建新的 OBS 场景集合
open	打开已有项目文件
save	保存当前项目
info	显示项目信息（分辨率、FPS、编码器、各对象计数等）
json	打印项目原始 JSON

project new 的完整参数（源码 obs_studio_cli.py project_new）：

参数	默认值	取值/说明
--name/-n	untitled	项目名
--width/-w	1920	输出宽度
--height/-h	1080	输出高度
--fps	30	帧率
--encoder	x264	x264/x265/nvenc/qsv/amd/svt-av1
--output/-o	无	JSON 保存路径

4.2 Scene 场景组

命令	说明
add	新增场景（--name/-n）
remove <index>	按索引删除场景
duplicate <index>	复制场景
set-active <index>	设置活动场景
list	列出全部场景（含 active 标记）

删除场景时，如果只剩最后一个场景会被拒绝（保证至少保留一个场景）；同时会自动修正 active_scene 引用避免越界（scenes.py）。

4.3 Source 来源组

命令	说明
add <type>	向场景添加来源
remove <index>	按索引移除来源
duplicate <index>	复制来源
set <index> <prop> <value>	设置来源属性（name/visible/locked/opacity/rotation）
transform <index>	变换来源（position/size/crop/rotation）
list	列出场景内全部来源

source add 的核心参数：

• --name/-n：来源名称，缺省自动使用类型标签；
• --scene/-s <int>：目标场景索引，默认 0；
• --position/-p x,y：位置坐标，如 640,360；
• --size WxH：尺寸，如 1280x720；
• --setting/-S key=value：来源私有设置，可多次传入。

源码中 sources.py 以 SOURCE_TYPES 注册表声明了 12 类来源，CLI 会自动根据注册表枚举合法的 type 并做参数校验：

type	对应 OBS 来源	category
video_capture	视频采集设备	video
display_capture	显示器采集	video
window_capture	窗口采集	video
image	图像	media
media	媒体源（本地视频）	media
browser	浏览器源	web
text	文本（FreeType2）	text
color	颜色源	utility
audio_input	音频输入采集	audio
audio_output	音频输出采集	audio
group	编组	utility
scene	嵌套场景源	utility

例如给场景 0 添加一个摄像头与一个游戏画面采集：

cli-anything-obs_studio --project project.json source add video_capture -n Camera
cli-anything-obs_studio --project project.json source add display_capture -n Game --position 640,0 --size 1280x720

source transform 支持 --position、--size、--crop top,bottom,left,right 与 --rotation；底层会调用 obs_utils.py 中的 validate_position/validate_size/validate_crop 等工具做边界校验（尺寸必须为正整数、裁剪边非负、坐标必须是有限数值）。source set 支持 name/visible/locked/opacity/rotation 五个属性，其中 visible/locked 接受 true/1/yes 文本布尔值，opacity 校验范围 0.0~1.0。

4.4 Filter 滤镜组

命令	说明
add <type>	给来源添加滤镜
remove <index>	移除某来源上的滤镜
set <index> <param> <value>	设置滤镜参数
list	列出某来源上的滤镜
list-available	列出全部可用滤镜类型（可按 -c video/audio 分类过滤）

filter add 参数：

• --source/-S <int>：目标来源索引，默认 0；
• --scene/-s <int>：场景索引，默认 0；
• --name/-n：滤镜名称；
• --param/-p key=value：滤镜参数，可多次传入。

filters.py 通过 FILTER_TYPES 注册表为每种滤镜声明了参数名、类型、默认值与取值范围，这是这套 CLI 最有价值的"自描述"能力。下面归纳各滤镜的关键参数范围：

滤镜 type	类别	主要参数与范围
color_correction	video	gamma −3~3、contrast −4~4、brightness −1~1、saturation −1~5、hue_shift −180~180、opacity 0~1
chroma_key	video	key_color_type（green/blue/magenta/custom）、similarity 1~1000、smoothness 1~1000、spill 1~1000
color_key	video	key_color（#RRGGBB）、similarity 1~1000、smoothness 1~1000
lut	video	path、amount 0~1
image_mask	video	path、type（alpha/blend）
crop_pad	video	top/bottom/left/right 各 0~8192
scroll	video	speed_x/speed_y −5000~5000、loop（bool）
sharpen	video	sharpness 0~1
noise_suppress	audio	method（rnnoise/speex/nvafx）、suppress_level −60~0
gain	audio	db −30~30
compressor	audio	ratio 1~32、threshold −60~0、attack 1~500、release 1~1000、output_gain −30~30
noise_gate	audio	open_threshold/close_threshold −96~0、attack/hold/release
limiter	audio	threshold −60~0、release 1~1000

_validate_filter_params 会拒绝未知参数、对数值做范围钳制/校验并自动填充未提供参数的默认值。例如为场景 0 中索引 0 的来源加绿色抠像：

cli-anything-obs_studio --project project.json filter add chroma_key -S 0 -p similarity=400 -p smoothness=80

4.5 Audio 音频组

命令	说明
add	添加全局音频来源
remove <index>	移除全局音频来源
volume <index> <level>	设置音量（0.0~3.0，1.0 为 100%）
mute <index> / unmute <index>	静音 / 取消静音
monitor <index> <type>	设置监听类型
list	列出全部音频来源

audio add 参数包括 --name/-n、--type（input/output）、--device/-d（设备标识）、--volume/-v（默认 1.0）。monitor 的三个合法值为 none、monitor_only、monitor_and_output，与 OBS 的音频监听语义一致（audio.py）。音频来源在内部 JSON 中还包含 balance（−1.0~1.0）与 sync_offset（毫秒）字段，可经由 core 层函数 set_balance / set_sync_offset 操作。

cli-anything-obs_studio --project project.json audio add -n Microphone --type input --device "USB Mic" -v 1.0
cli-anything-obs_studio --project project.json audio volume 0 0.8
cli-anything-obs_studio --project project.json audio monitor 0 monitor_and_output

4.6 Transition 转场组

命令	说明
add <type>	添加转场
remove <index>	移除转场
set-active <index>	设置活动转场
duration <index> <ms>	设置转场时长（毫秒）
list	列出全部转场

TRANSITION_TYPES（transitions.py）声明了 7 类转场及其默认时长：cut（0ms）、fade（300ms）、swipe（500ms）、slide（500ms）、stinger（1000ms）、fade_to_color（300ms）、luma_wipe（500ms）。与场景类似，系统保证至少保留一个转场。

4.7 Output 输出组（推流/录制/编码）

命令	说明
streaming	配置推流设置
recording	配置录制设置
settings	配置输出设置（分辨率/FPS/码率/编码器/预设）
info	显示当前输出配置
presets	列出可用编码预设

output streaming --service <svc> --server <url> --key <key>：service 取值 twitch/youtube/facebook/custom。 output recording --path <dir> --format <fmt> --quality <q>：format 取值 mkv/mp4/mov/flv/ts；quality 取值 low/medium/high/lossless。 output settings 可单独覆盖 --width/--height/--fps/--video-bitrate/--audio-bitrate/--encoder，也可用 --preset 一键套用整套编码方案。

output.py 内置 8 套 ENCODING_PRESETS，编码预设覆盖推流与录制两类诉求：

预设名	编码器	视频码率	音频码率	适用
ultrafast	x264	2500	128	极速推流
fast	x264	4500	160	快速推流
balanced	x264	6000	160	均衡推流
quality	x264	8000	192	高质量推流
high_quality	x264	12000	320	高码率推流
nvenc_fast	nvenc	6000	160	NVIDIA 硬编
nvenc_quality	nvenc	10000	192	NVIDIA 硬编高质
recording_high	x264	20000	320	本地录制

# 配置 Twitch 推流并套用预设
cli-anything-obs_studio --project project.json output streaming --service twitch --key "live_xxxx"
cli-anything-obs_studio --project project.json output settings --preset balanced
cli-anything-obs_studio --project project.json output recording --path ./recordings --format mkv --quality high

注意：默认新建项目的 settings 为 1920x1080@30、视频码率 6000、音频码率 160、编码器 x264；streaming 默认 service 为 twitch、server 为 auto。

4.8 Session 会话组

命令	说明
status	显示会话状态
undo	撤销上一步操作
redo	重做被撤销的操作
history	显示撤销历史

五、状态管理：会话、快照与持久化

SKILL 文档声明的三个状态管理要点，在 session.py 中均有对应实现：

• Undo/Redo 深度 50 层：Session.MAX_UNDO = 50。每次变更前 CLI 先调用 session.snapshot(description) 把当前项目深拷贝进 _undo_stack（含描述与时间戳），超过 50 条自动淘汰最旧的；执行新变更时清空 _redo_stack。undo() 把当前状态压入 redo 栈再回退，redo() 反向操作。
• 项目持久化：项目即为 JSON 文档，save_session() 写入磁盘并更新 metadata.modified 时间戳；底层 _locked_save_json 使用 fcntl.flock 做排他文件锁 + 截断重写的原子化保存（在非 POSIX 平台降级为普通写入），防止多进程/多 Agent 并发写坏文件。
• 会话跟踪：status() 会返回 has_project/project_path/modified/undo_count/redo_count/project_name，list_history() 则按时间倒序列出每条快照的描述。

# 演示撤销/重做
cli-anything-obs_studio --project project.json scene add -n "BRB"
cli-anything-obs_studio --project project.json session undo    # 撤销添加 BRB
cli-anything-obs_studio --project project.json session redo    # 重做
cli-anything-obs_studio --project project.json session history # 查看历史

六、JSON 场景集合的数据结构

新建项目的默认 JSON 结构由 project.py 的 _default_project 生成，顶层字段如下：

{
  "version": "1.0",
  "name": "my_stream",
  "settings": {
    "output_width": 1920, "output_height": 1080, "fps": 30,
    "video_bitrate": 6000, "audio_bitrate": 160, "encoder": "x264"
  },
  "scenes": [
    { "id": 0, "name": "Scene", "sources": [] }
  ],
  "active_scene": 0,
  "transitions": [
    { "name": "Cut",  "type": "cut",  "duration": 0 },
    { "name": "Fade", "type": "fade", "duration": 300 }
  ],
  "audio_sources": [],
  "streaming": { "service": "twitch", "server": "auto", "key": "" },
  "recording":  { "path": "./recordings/", "format": "mkv", "quality": "high" },
  "metadata":   { "created": "...", "modified": "...", "software": "obs-cli 1.0" }
}

场景内的来源（source）对象则包含 id/name/type/visible/locked/position/size/crop/rotation/opacity/filters/settings 等字段，滤镜（filter）对象包含 id/name/type/enabled/params。由于整份文档就是普通 JSON，用户可以：

• 用 project json 直接导出原始结构；
• 用其他 JSON 工具离线比对、迁移或版本管理场景集合；
• 把生成的 .json 作为后续批量任务的输入。

校验规则上，create_project 会强制分辨率与 FPS 为正数、视频码率 ≥100、音频码率 ≥32，并校验编码器名称；加载文件时要求顶层存在 version 与 scenes 字段，否则报 "Invalid OBS project file"。

七、双输出格式：人类可读与机器可读

所有命令默认输出人类可读格式（表格、缩进文本），加 --json 则输出结构化 JSON。两种模式的核心区别是错误语义也不同：错误处理器 handle_error 在 --json 模式下会把错误序列化为 {"error": "...", "type": "..."} 结构；异常类型包括 file_not_found、file_exists 以及具体的 Python 异常名（如 ValueError、IndexError）。

# 人类可读
cli-anything-obs_studio project info -p project.json

# Agent 可解析
cli-anything-obs_studio --json project info -p project.json

八、AI Agent 集成最佳实践

SKILL.md 对以编程方式使用该 CLI 的 Agent 提出了 5 条纪律，直接来自其双输出/返回码/错误通道设计：

1. 始终使用 --json：保证输出可被解析，不要依赖表格文本；
2. 检查返回码：0 表示成功，非 0 表示出错（one-shot 模式下失败会 sys.exit(1)）；
3. 失败时解析 stderr：错误信息统一走错误通道（err=True），便于与正常 stdout 分离；
4. 文件操作使用绝对路径：避免工作目录假设导致找不到项目文件；
5. 导出操作后校验产物存在：例如 project save 后确认目标 JSON 确实落盘。

配套地，CLI 还提供 --dry-run 全局选项用于"预演"：Agent 可在不写盘的前提下验证命令链是否合法。

九、从零到可推流：一条完整命令链

把上述命令组串起来，即可构建一个包含场景、来源、滤镜、音频、转场与推流录制的完整直播/录播项目：

# 1. 创建项目并命名
cli-anything-obs_studio project new --name "my_stream" -o project.json

# 2. 采集来源：摄像头 + 显示器
cli-anything-obs_studio --project project.json source add video_capture -n "Camera" -s 0
cli-anything-obs_studio --project project.json source add display_capture -n "Game" -s 0

# 3. 给摄像头做绿幕抠像 + 色阶微调
cli-anything-obs_studio --project project.json filter add chroma_key -S 0 -p similarity=400 -p smoothness=80
cli-anything-obs_studio --project project.json filter add color_correction -S 0 -p brightness=0.05

# 4. 加"休息中"场景并设为备用
cli-anything-obs_studio --project project.json scene add --name "BRB"
cli-anything-obs_studio --project project.json source add text -n "Back Soon" -s 1 -p "text=Back Soon~"

# 5. 音频与会话保护
cli-anything-obs_studio --project project.json audio add -n "Mic" --type input -v 1.0
cli-anything-obs_studio --project project.json session status

# 6. 推流与录制参数
cli-anything-obs_studio --project project.json output streaming --service twitch --key "live_xxxx"
cli-anything-obs_studio --project project.json output settings --preset balanced
cli-anything-obs_studio --project project.json output recording --path ./recordings --format mkv --quality high

# 7. 提交并核验
cli-anything-obs_studio --project project.json project save
cli-anything-obs_studio --json --project project.json project info

每一步（source add、scene add、filter add、output settings 等）执行前都会先 session.snapshot(...)，因此整条链可随时 session undo 回滚。

十、源码架构、测试与更多资料

本包源码模块与职责如下，全部位于 obs_studio 包 下：

obs_studio/
├── obs_studio_cli.py      # 主入口：Click 命令组 + REPL + 全局选项
├── core/
│   ├── project.py         # 项目创建/打开/保存/信息（JSON 数据模型）
│   ├── scenes.py          # 场景增删改查（含 active_scene 修正）
│   ├── sources.py         # 来源管理 + SOURCE_TYPES 注册表
│   ├── filters.py         # 滤镜管理 + FILTER_TYPES 注册表 + 参数校验
│   ├── audio.py           # 全局音频管理
│   ├── transitions.py     # 转场管理
│   ├── output.py          # 推流/录制/编码配置 + ENCODING_PRESETS
│   └── session.py         # 会话状态、undo/redo、原子化保存
├── utils/
│   ├── obs_utils.py       # ID/重名/范围/位置/尺寸/裁剪等校验工具
│   └── repl_skin.py       # REPL 皮肤与提示会话
├── skills/SKILL.md        # 供 Agent 读取的技能说明书（本文所依据文档）
├── tests/
│   ├── TEST.md            # 测试说明
│   ├── test_core.py       # 单元测试
│   ├── test_full_e2e.py   # 端到端测试
│   ├── test_validate_geometry_nan.py  # 几何参数 NaN/Inf 校验
│   └── test_validate_range_nan.py     # 范围参数 NaN/Inf 校验
└── README.md              # 包级使用文档（命令组与架构说明）

值得注意的工程细节是 obs_utils.py 中的数值健壮性设计：_finite_number/_finite_int/validate_range 会显式拒绝 NaN、Infinity 等非有限数值，避免脏数据渗透进场景集合，且独立存在对应的 NaN 校验测试（test_validate_geometry_nan.py、test_validate_range_nan.py）；unique_name 会为同名列自动追加 .001、.002 后缀，保证场景/来源/滤镜/音频名称唯一。

进一步阅读：

• 包级 README：obs_studio/README.md
• 测试说明：tests/TEST.md
• Agent Harness 方法论：cli-anything-plugin/HARNESS.md
• 顶层 Harness 文档：agent-harness/OBS.md

十一、版本

当前 SKILL 版本为 1.0.0（对应入口 ReplSkin("obs_studio", version="1.0.0") 与项目 metadata.software = "obs-cli 1.0"）。该 CLI 的价值在于：以一套可版本化、可校验、可回滚的 JSON 场景集合为核心，把 OBS 直播/录播的前期配置工作完整地交还给命令行与 AI Agent，实现场景搭建的声明化与自动化。