Vos 程式碼混音工具是什麼？

此技能讓 AI 代理能將 vos.so 上的任何畫廊影片「混音」（remix）成使用者自己的私人版本。每個 vos 影片本質上都是一個程式（輸入 + 確定性函數 → 影片），混音流程涉及下載其 JSON 設定，在本地編輯已宣告的控制項（knobs）與 JavaScript 函數字串，使用 `vos check` 驗證，然後將結果推送至使用者的 vos.so 帳戶，並保留原始作品的出處（lineage）。支援三種認證方式：一次性混音授權碼、長期 API 金鑰，或無需憑證的可認領推送（claimable push）。此工具也內建版本迭代機制，可追蹤變更並與人類在 Studio 中的編輯同步，確保每次推送都保持一致。主要用於自訂動畫，替換 3D 模型，或根據使用者的偏好迭代已擷取的程式。

相容平台~Claude Code~Codex CLI~Cursor

npx skills add https://github.com/vosjs/skills/tree/main/skills/vos-remix

說明文件

混音 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 "我的混音"
# → claim: https://vos.so/claim/…   到期：<72 小時後>

# 沒有 CLI 或版本較舊？透過純 HTTP 做相同的事：
curl -s -X POST https://vos.so/api/claim \
  -H 'content-type: application/json' \
  -d '{"title": "我的混音", "config": <VosConfigJson>}'
# → { "claimUrl": "https://vos.so/claim/…", "expiresAt": "…" }
```
將 claimUrl 交給使用者，不要交給其他人——它是唯一的參考和唯一憑證。該連結持續 72 小時；無人認領的作品會在此之後刪除（這是刻意的清理，不是資料遺失——如果過期就重新推送）。認領會將 vos 移入使用者的資料庫，並開始其託管預覽；認領後的迭代會使用他們的金鑰（下方的循環）。限制：設定 ≤200KB，每個網路每天 5 次推送。

CLI 會自動解析授權碼和金鑰（export VOS_API_KEY=…）。沒有任何形式可以公開發布：推送的 voses 會保持私人，直到人類在 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   # 執行它 — 檢查編譯
                                 # 但從不執行模組；執行時拋出錯誤
                                 # （針對函數自身宣告的 TDZ）僅在檢查時
                                 # 隱形地傳送。在每次程式碼編輯之後、
                                 # 每次推送之前，產生一個靜止畫面。

修復所有錯誤；認真對待確定性警告（每次執行呈現不同的設定本質上就是壞的）。

推送為帶有血緣關係的私人 vos（CLI 會讀取 config.json 旁邊的 vos.json 來取得 remixOfId 歸屬）：

vos push <slug>/config.json --title "Aurora Ribbons — 黃昏"
# → 已建立私人 vos <id>
#   監看： https://vos.so/vos/<id>
#   工作室： https://vos.so/studio?vos=<id>

迭代 — 後續的編輯會成為同一個 vos 的版本：
```
vos push <slug>/config.json --vos <id> --note "較冷的色板，較慢的漂移"
```
目錄透過 vos.json 追蹤其 vos，因此基礎版本會自動攜帶：如果人類自你上次推送後在工作室中編輯過，推送會連同他們輸入的變更日誌一起被拒絕。--note 是你的交接行——是人類最先讀到的東西；--label 為版本命名。
每次編輯前先拉取 — 人類可能已經微調過：
```
vos pull <slug>          # 自你的基礎版本以來什麼改變了，然後同步
```
列印每個版本的歸屬（v3 (工作室 · 較暖色): 控制項 hue 0.2→0.35
- 他們的筆記），將 config.json 同步到最新版本（你之前的副本會保留為 config.backup.json），並重新指向基礎版本。人類編輯過的節點受到保護：一個觸及這些節點的推送會被拒絕，除非你傳入 --override <id> — 僅在使用者的指令明確針對該節點時才這麼做。他們對你控制項的調整是偏好資料：在決定下一步動作之前，先閱讀變更日誌。
回傳兩個連結 — 監看頁面（預覽、控制項、程式碼）和工作室（https://vos.so/studio?vos=<id>），使用者可以在那裡微調你的控制項。發布是他們的行為，在 vos.so 上進行。

保持推送誠實的規則

私人是合約。 絕不要嘗試 visibility: "public" — 它會被限制為私人，且透過金鑰發布的設計會被拒絕。
注意配額：長期金鑰每 24 小時建立 ≤50 個 voses；授權碼最多推送 5 次。在一個 vos 上迭代版本，而不是建立許多 voses。
伺服器渲染限制（預覽叢集使用軟體 GL）：不能在傳輸材質上使用 THREE.DoubleSide，不能使用 dispersion，且每個擷取的資產必須是叢集可以到達的絕對 https URL。
每個控制項都必須起作用。 一個程式碼從不讀取的參數比沒有參數更糟——請參閱 references/params-knobs.md 的誠實章節。
3D 模型替換（將 GLB 放入展示程式中）：references/3d-recipe.md。
完整的端點參考、配額和錯誤表： references/remix-contract.md。

Vos 程式碼混音工具