翻录一个 vos 程序
vos.so/gallery 上的每个视频都是一个程序： 输入 + 一个确定性函数 → 视频。翻录就是编辑该程序的 JSON 配置，并将结果作为一个私有的 vos 推送到用户的帐户上， 并带有谱系。你在本地编辑；平台负责验证、 编译和渲染预览。
设置
npm i -D @vosjs/cli # fetch/check/push/pull 循环
此循环无需浏览器（渲染预览发生在平台上）。
如果 CLI 不可用，一切也可以通过纯 HTTP 完成：
references/remix-contract.md 记录了每个端点。
凭证（切勿打印）
两种形式，均用作 Authorization: Bearer：
- 翻录授权 (
vos_rg_…) — 如果用户的提示中包含此授权，请使用它。 有效期 24 小时，绑定到一个源 vos，最多推送 5 次。 - 持久密钥 (
vos_sk_…) — 在询问用户之前的解析顺序：VOS_API_KEY环境变量，然后是~/.config/vos/credentials的第一行。 人类可在 https://vos.so/app/api 创建密钥。 - 没有任何凭证 — 可认领推送（仅限程序）：
vos push my-remix.json --claimable --title "My remix" # → claim: https://vos.so/claim/… expires: <72h from now> # 没有 CLI，或 CLI 版本较旧？通过纯 HTTP 实现相同操作： curl -s -X POST https://vos.so/api/claim \ -H 'content-type: application/json' \ -d '{"title": "My remix", "config": <the VosConfigJson>}' # → { "claimUrl": "https://vos.so/claim/…", "expiresAt": "…" }claimUrl交给用户且仅交给用户——它是唯一的引用 和唯一的凭证。链接有效期 72 小时；未认领的作品在此之后 将被删除（有意清理，并非数据丢失——如果链接过期，重新推送即可）。 认领操作会将 vos 移入用户的库并启动其托管预览； 认领后的迭代将使用用户的密钥（详见下方循环）。 限制：配置 ≤200KB，每个网络每天 5 次推送。
CLI 会自动解析授权和密钥（export VOS_API_KEY=…）。
任何凭证形式都无法发布：推送的 vos 保持私有，直到人类在 vos.so 上手动发布。
工作循环
-
获取 源程序（公开程序无需认证）：
vos fetch https://vos.so/vos/<id> # 或仅使用 id # → <slug>/config.json (参数已保留) + <slug>/vos.json (追踪数据) -
编辑 本地的
config.json。函数字段（setup、createContent、createTimeline、onFrame）是字符串形式的 JavaScript — 没有 TypeScript 语法，没有${}模板插值。 果断更改 1–2 个主要方面（调色板、运动语法、密度）——绝不要 做一个只有 10% 微调的复制品。如果程序声明了params， 优先调整或扩展这些旋钮，而不是修改函数字符串。 -
声明旋钮和外观 — 翻录的控制面。2–4 个 意图命名的参数加上 2–3 个预设。这是一种有规则的手艺： 参见
references/params-knobs.md。 -
推送前本地检查：
vos check <slug>/config.json # 迁移 → 校验架构 → 语法 → 编译 → 代码检查 vos still <slug>/config.json probe.webp --time 2 # 运行它——检查编译是否通过 # 但绝不执行模块；仅靠检查无法捕获 # 运行时抛出（函数自身的声明中的暂时性死区） # 每次代码编辑后，每次推送前，渲染一个静态图。修复所有错误；认真对待确定性问题（一个每次运行 渲染结果不同的配置本身就有问题）。
-
推送 为带有谱系的私有 vos（CLI 会读取 config 旁边的
vos.json以获取remixOfId归属）：vos push <slug>/config.json --title "Aurora Ribbons — dusk" # → Created private vos <id> # watch: https://vos.so/vos/<id> # studio: https://vos.so/studio?vos=<id> -
迭代 — 进一步的编辑将成为同一个 vos 的版本：
vos push <slug>/config.json --vos <id> --note "cooler palette, slower drift"目录通过
vos.json追踪其 vos，因此基础版本是自动携带的： 如果人类自你上次推送后在工作室中进行过编辑，则此推送会被拒绝， 并附带人类输入的变更日志。--note是你的交接说明行—— 它是人类最先阅读的内容；--label为版本命名。 -
每轮编辑前先拉取 — 人类可能进行过微调：
vos pull <slug> # 显示自你的基础版本以来发生了什么变化，然后同步打印每个版本的归属（
v3 (studio · warmer): knob hue 0.2→0.35以及人类的注释），将config.json同步到最新版本（你之前的副本会 保存为config.backup.json），并重新指向基础版本。人类编辑过的 节点受到保护：触及这些节点的推送会被拒绝，除非你传递--override <id>——仅在用户的指令明确针对该节点时才这样做。 他们对你旋钮的调整是偏好数据：在决定下一步做什么之前， 先阅读变更日志。 -
交回两个链接 — 观看页面（预览、旋钮、代码）和 工作室（
https://vos.so/studio?vos=<id>），用户可以在其中 实时微调你的旋钮。发布是他们的操作，在 vos.so 上完成。
确保推送诚实可靠的规则
- 私有是契约。 切勿尝试
visibility: "public"——它会强制转为私有， 并且通过密钥发布会被设计性地拒绝。 - 注意配额：持久密钥每 24 小时创建 ≤50 个 vos；授权最多推送 ≤5 次。 在一个 vos 上迭代版本，而不是创建许多个 vos。
- 服务器渲染约束（预览集群使用软件 GL）：
在透射材质上禁止使用
THREE.DoubleSide，禁止使用dispersion， 并且每个获取的资源必须是集群可访问的绝对httpsURL。 - 每个旋钮必须起作用。 代码从未读取的参数比没有参数更糟——
参见
references/params-knobs.md的诚实性部分。 - 3D 模型替换（将 GLB 放入展示程序）：
references/3d-recipe.md。 - 完整端点参考、配额和错误表：
references/remix-contract.md。