自动化

AI 处理与流水线

一次调用就能转写、打标签或转格式，结果按内容缓存；也可以让落进某个文件夹的每个文件自动处理，支持条件、串联和现成模板。

动作（action）对文件的某一个版本做一件事。服务器自带三个，插件可以加更多。

动作	做什么	写到哪里	服务器需要的设置
`side.transcribe`	把说的话转成带时间的文字，可以搜索	`transcript` 附加信息	装 ffmpeg；`SIDESPACE_TRANSCRIBE_URL` 指向任何兼容 OpenAI `/audio/transcriptions` 的服务（OpenAI、Groq、本地 whisper.cpp 或 faster-whisper），加 `SIDESPACE_TRANSCRIBE_KEY`
`side.tags`	视觉模型看几帧关键画面，给出描述、标签、景别、场景和情绪	`ai.tags` 附加信息	默认用 Claude（`SIDESPACE_ANTHROPIC_API_KEY`），或本地模型：`SIDESPACE_TAGS_PROVIDER=openai`、`SIDESPACE_TAGS_URL`、`SIDESPACE_TAGS_MODEL`
`side.convert`	ffmpeg 预设：`mp4`、`webm`、`prores-proxy`、`wav`、`mp3`、`jpg`、`png`、`webp`、`gif`	在原文件旁边新建一个文件，带 `derived` 附加信息	装 ffmpeg

GET /v1/spaces/{sid}/actions 列出这台服务器能做什么。没配好的动作标为 available: false 并写明缺哪个设置，每个动作还附带它的 params_schema。

运行

sidespace actions "Film A"
sidespace run "Film A" /Ep01/a.mov side.transcribe --param language=zh
sidespace run "Film A" /Ep01/a.mov side.convert --param preset=mp4 --param max=720
sidespace runs "Film A" /Ep01/a.mov

// 等待结果。失败时抛出 SideSpaceError（code 为 run_failed）。
const run = await side.run("Film A", "/Ep01/a.mov", "side.transcribe", { language: "zh" });
console.log(run.cached, run.result?.sidecars?.transcript);

curl -X POST "https://side.example.com/v1/spaces/$SPACE/runs" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" -H "Content-Type: application/json" \
  -d '{"action": "side.tags", "path": "/Ep01/a.mov"}'
# 然后 GET /v1/spaces/$SPACE/runs/$RUN，直到 state 变成 done 或 failed

一次运行（run）依次经过 queued、running，最后是 done、failed 或 canceled，过程中 progress 从 0 到 1。编辑者可以发起，令牌需要 runs:write。POST …/runs/{rid}/cancel 可以取消。SDK 里用 startRun/start_run 和 waitRun/wait_run 把发起和等待分开。

按内容缓存

同样的字节、同样的参数只处理一次。重新上传、复制或恢复旧版本都不会再调用模型，运行会立刻返回并带 cached: true。只写附加信息的结果可以跨空间复用；生成新文件或预览文件的结果只在同一空间内复用。想重做时传 "fresh": true（CLI 用 --fresh）。

失败与重试

可能过一会儿就好的失败（超时、模型服务返回 5xx）会在 30 秒、3 分钟后重试，共 3 次；不会好的失败（密钥被拒、文件没有声音）立刻失败，原因写在 error 里。

运行做出的改动记在发起人名下，actor_kind 是 plugin，actor_via 是动作名，所以在历史里能看出是 AI 做的。

流水线

流水线（pipeline）是空间的常设规则：新保存的文件只要符合路径 glob 和 MIME 前缀，就自动跑某个动作。只有空间管理员能建，令牌需要 pipelines:manage。

sidespace pipeline create "Film A" side.tags --path "/dailies/**" --mime video/ --name "给样片打标签"
sidespace pipeline create "Film A" side.transcribe --mime audio/ --backfill    # 连同已有文件一起
sidespace pipeline list "Film A"
sidespace pipeline enable "Film A" pip_… --off

流水线和 Webhook 一样，各自按变更日志往前走，从建好的那一刻开始；--backfill（或 POST …/pipelines/{pid}/backfill）补上已有的文件。由运行生成的新版本不会再触发流水线，所以“转成 mp4”的流水线不会循环。

条件

conditions 让流水线只处理同时满足这些条件的文件：min_size、max_size（字节），以及媒体探测得到的 min_duration_s、max_duration_s、min_width、min_height、has_audio。文件没有这项数值就算不满足（图片没有时长）；不认识的键会被拒绝，免得拼错一个字就把所有文件都匹配上。新版本还在探测时，流水线会等探测结果，最多等 15 分钟。

# 只给 4K 母版出审片小样
sidespace pipeline create "Film A" side.convert --mime video/ --param preset=mp4 --param max=1920 --when min_width=2560
# 只转写有声音、长于 10 秒的视频
sidespace pipeline create "Film A" side.transcribe --mime video/ --when has_audio=true --when min_duration_s=10

curl -X POST "https://side.example.com/v1/spaces/$SPACE/pipelines" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" -H "Content-Type: application/json" \
  -d '{"name": "转写采访", "action": "side.transcribe", "mime_prefix": "video/", "conditions": {"has_audio": true, "min_duration_s": 10}}'

串联

after: <动作> 让流水线在那个动作对匹配的文件跑完时开始，而不是在文件保存时开始。适合依赖前一步结果的处理，比如视频转写完之后再打标签。运行按版本、动作和参数去重，所以就算串成一个环，也只会走一轮；串联流水线补处理已有文件时，只处理它跟随的动作已经做完的文件。

Shell

sidespace pipeline create "Film A" side.tags --mime video/ --after side.transcribe

模板

模板是常见任务的现成流水线组合。它们写在服务器代码里，服务器升级时模板也跟着变好。

模板	做什么
`video-insights`	新视频自动用 AI 打标签，有声音的顺便转写
`review-copies`	宽于 2560 像素的新视频，旁边生成一份 1080p H.264 MP4
`interviews`	转写新的音频，以及有声音的视频
`tag-images`	描述新图片并打标签

sidespace pipeline templates "Film A"
sidespace pipeline template "Film A" video-insights --path "/Ep01/**" --backfill

curl "https://side.example.com/v1/spaces/$SPACE/pipeline-templates" -H "Authorization: Bearer $SIDESPACE_TOKEN"
curl -X POST "https://side.example.com/v1/spaces/$SPACE/pipeline-templates/video-insights" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" -H "Content-Type: application/json" \
  -d '{"path_glob": "/Ep01/**", "backfill": true}'
# → {"items": [新建的流水线], "runs": 对已有文件发起的运行数}

开启模板就是新建普通的流水线，之后可以像其他流水线一样列出、暂停或删除。服务器还没配好的动作，模板照样列出；它的流水线会等服务器配好再处理。

网页版里，空间管理员在文件夹工具栏的自动处理里开启模板，可以只对这个文件夹或对整个空间，也在那里关闭。

给 AI agent

通过 MCP，list_actions 查看能做什么，run_action 发起并等待结果（默认等 60 秒，最多 300 秒），get_run 查进度。