Side Space

开发

附加信息

每个版本上按命名空间存放的 JSON 元数据。内置的结构、自定义命名空间，以及把一个命名空间交给一个工具独占。

查看 Markdown

附加信息（sidecar）是挂在文件某一个版本上、属于某个命名空间的一份 JSON。一个视频版本可以同时带着媒体信息、转写、AI 标签、生成它的提示词、大家的评分和你的质检结果，各在各的命名空间里，各由负责这件事的人或工具来写。

搜索读的是附加信息，应用里“信息”面板显示的是它，版本比较比的也是它，AI agent 通过 MCP 了解一个文件时读它，而不用下载文件。

读和写

要做的事调用
一个版本的全部附加信息GET /v1/spaces/{sid}/versions/{vid}/sidecars
某个命名空间GET /v1/spaces/{sid}/versions/{vid}/sidecars/{ns}
写入（整份替换这个命名空间）PUT /v1/spaces/{sid}/versions/{vid}/sidecars/{ns}，带 {"doc": {…}}
删除DELETE /v1/spaces/{sid}/versions/{vid}/sidecars/{ns}
curl -X PUT "https://side.example.com/v1/spaces/$SPACE/versions/$VERSION/sidecars/x-acme.qc" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" -H "Content-Type: application/json" \
  -d '{"doc": {"passed": false, "issues": [{"at_s": 12.4, "kind": "dropped_frame"}]}, "producer": {"name": "acme-qc", "version": "1.4"}}'

写入需要编辑者权限，令牌需要 sidecars:write，或者只针对一个命名空间的 sidecars:write:<ns>（一组用 sidecars:write:x-acme.*）。producer 记录是哪个工具写的，应用里会显示。

内置命名空间

内置命名空间写入时按 JSON Schema 校验（在仓库的 proto/sidecar/ 里），所以所有工具都能放心依赖它们的结构。

命名空间谁写内容
core服务器content_hash、size、mime、author_id、device_id、client_mtime、created_at
media服务器（ffprobe）duration_s、container、bitrate、width、height（按显示方向）、fps、video_codec、audio_codec、audio_channels、creation_time
transcriptside.transcribe 或你的工具text、language、duration、segments（start、end、text、speaker）、model、provider
ai.tagsside.tags 或你的工具description、tags、shot_type、setting、mood、people、text_on_screen、frames、model
ai.generation生成素材的工具tool（必填）、model、provider、prompt、negative_prompt、seed、parameters、inputs、job_id、cost、regenerate_url
user应用里的成员tags、rating、label、note、status（草稿、审阅中、已通过…）
derived生成新文件的动作from（node_id、version_id、path）、action、params、run_id

core 和 media 只有服务器能写。保存新版本时，user 和 ai.generation 会从上一个版本带过来（producer.inherited_from 记录来源），因为重新导出不会改变提示词和评分；其余的描述的是具体字节，会重新生成。

记录 AI 素材是怎么来的

如果你的工具生成图片或视频，上传时顺便写 ai.generation。搜索就能按提示词找到文件，应用里也会显示模型，并给出回到原工具重新生成的链接。

JSON
{
  "tool": "cliptap",
  "model": "video-model-x",
  "prompt": "A fishing harbor at night, slow dolly in, rain",
  "seed": 1234,
  "inputs": [{ "role": "reference", "node_id": "nod_…", "version_id": "ver_…" }],
  "regenerate_url": "https://cliptap.example/jobs/9f2c"
}

自定义命名空间

自定义命名空间以 x- 开头，一般写成 x-<公司>.<工具>（x-acme.qc）。在服务器大小限制内的任何 JSON 对象都可以，内容由你自己负责。

一个命名空间只给一个成员写

空间管理员可以把某个命名空间交给一个成员，通常是一个 AI 成员。之后在这个空间里只有它能写，其他人只能读，多个 AI 工具就不会互相覆盖结果。

Shell
sidespace namespace claim "Film A" x-qc "Clip Tagger"
sidespace namespace list "Film A"
sidespace namespace release "Film A" x-qc

能交出去的是 ai.generation 和自定义的 x-…。core、media 属于服务器，user 是大家共用的。