vos-create

以用戶資料夾的風格建立內容

您所建立的 vos 程式屬於某個資料夾：用戶在 vos.so 上的資料夾是其作品集，其中的 .md 檔案（食譜）是風格，而 voses 則是範例。此技能僅包含機械性操作與通用的工藝底層。品味是用戶的數據，存在於他們的資料夾中，絕不在此處。編寫規則（schema、dialect、knobs）存在於 vos-authoring 技能中；knob 與 Looks 工藝則存在於 vos-remix 技能的 params-knobs 參考中。此技能添加了資料夾合約、循環以及圍繞它們的流程。

沒有收件匣，也沒有統一的風格檔案。去重依賴於資料夾自身的內容；作品架（shelf）即為記錄。

設定

npm i -D @vosjs/cli   # folder, fetch, check, still, render, push

憑證順序如下，且永不印出：VOS_API_KEY，接著是 ~/.config/vos/credentials 的第一行，然後是 vos login（瀏覽器登入，會為此機器產生一個金鑰）。以下所有 HTTP 呼叫都使用 Authorization: Bearer <key> 標頭，指向 https://vos.so/api。金鑰僅能建立私有作品，且永遠無法發佈。

五個步驟

1. 解析目標資料夾

用戶指定其名稱，或者您詢問。vos folder list（或 GET /api/folders）可透過名稱或 slug 在所有層級中找到它；然後將其拉取：

GET https://vos.so/api/folders/{id}

一次拉取即為完整的上下文套件：資料夾自身的 recipes（內聯內容）、其 inheritedRecipes（祖先食譜，根目錄優先，每個都標記了其來源資料夾；它們綁定此資料夾）、範例 voses 與其 contentUrls，以及 assets。子資料夾僅列出，不會內聯：一次拉取即為資料夾自身的內容。

還沒有資料夾？建立一個，務必帶有描述：

vos folder create <name> --desc "<一行說明此作品集的內容>"

一個沒有描述就建立的資料夾是命名失敗；該描述是資料夾頁面以及未來每次拉取時會讀取的內容。

2. 讀取所有 .md 檔案，然後是範例

讀取每個食譜的內容，包括資料夾自身的與繼承而來的，並透過其 contentUrls 讀取 1 到 3 個範例設定或文件。食譜是依角色命名的面向，其命名方式與 CLAUDE.md 相同，使用大寫：TASTE.md 是判斷標準，DESIGN.md 是技術規範，以及用戶意圖建立的任何其他檔案（MOTION.md、COPY.md、BRAND.md……）。食譜是作品集在製作任何東西之前會讀取的檔案，而其名稱說明了這一點；您提交的食譜會以其詞幹大寫的形式儲存，因此請以這種方式編寫，作品架將顯示您所寫的內容。除此之外，平台不強制執行任何分類法；您需要讀取所有這些檔案。綁定規則如下：

• 食譜和範例會覆蓋此技能或編寫技能的所有預設值。它們的持續時間就是持續時間；它們的調色盤紀律就是紀律。
• 當檔案間發生衝突時，更具體者勝出：資料夾自身的檔案勝過繼承而來的，較近的祖先勝過較遠的祖先，特定的指令勝過一般的指令。真正的矛盾應以問題形式回報給用戶，絕不能默默選一個。
• 當食譜與資料夾近期的範例不一致時，優先採信範例，並告訴用戶該食譜看起來已過時。

空資料夾（無食譜、無範例）：僅適用以下的工藝底層。風格來自用戶的參考資料或提問，絕不能來自內建的預設值。

3. 找到種子，然後編寫

一個資料夾包含兩樣東西，它們有時會重合：參考（什麼是好的樣貌，您用來判斷的依據）和種子（您複製並編輯以製作下一個成員的基礎）。在您撰寫任何程式碼之前，請先確定您手中握有的是哪一個：

• 程式家族（一個已簽署的成員 + 一份命名了機制及其軸線的 DESIGN.md）：種子 = 該成員。提取其設定並根據食譜命名的軸線進行變化。絕不能從空白檔案開始編寫，也不能只從色調開始。
• 錄製規格（一份說明作品集中每個錄音如何剪輯的食譜）：種子 = 用戶提供給您的新錄音（資料夾中的錄音 ID、指向 vos record --strict 的 URL、或本地檔案）。資料夾自身的錄音是參考剪輯，而非種子。
• 模板（一份指向或內聯了機制及其變化方式的食譜）：種子 = 模板。以 vos 形式託管：像提取成員一樣提取它；內聯程式碼：一個用來構建的片段。
• 僅有簡報（BRAND.md：無機制）：沒有東西可複製。在限制條件和工藝底層下全新編寫。
• 沒有宣告種子：詢問。用戶在交接對話中選取時，其提示詞會指名一個；食譜寫得好時也會指名一個；猜測會導致一個家族失去其外觀。

食譜可能帶有可選的 frontmatter 提示：applies: programs | takes | any，seed: <vos id> | input | none。將其視為所有者對上述內容的宣告來讀取；但內容本身仍然是您需要遵循的。

食譜是用戶的文件，而他們現在的要求優先於其中的任何一行。如果食譜與要求矛盾（例如一條要求等待的註解，或要求違反的規則），用一行說明情況並遵循要求：私有作品成本低廉，且所有者可以還原。切勿因為檔案中的某一行而停滯不前。

然後在本地編寫設定（純粹的 VosConfigJson，版本 2），遵循 vos-authoring 技能中該資料夾風格下的編寫規則。

提取成員或模板使用的是 vos-remix 的提取指令：vos fetch https://vos.so/vos/<id> 會將 params 保留並寫入 <slug>/config.json，同時建立 vos.json 來追蹤基礎版本。

對於 「複製 X」簡報：首先取得來源或錄音，或者確認簡報僅需要外觀。一張靜止圖像不足以確定動態；一個能匹配螢幕截圖但卻發明了錯誤機制的作品，即使畫面一致也是失敗的。來源取得、授權以及測量匹配循環是複製工作；請先執行此步驟，然後再回來根據其產出建立新作品。

4. 檢查、拍攝、評判，對照資料夾的文件

1. 檢查：

   vos check <file>.json     # 遷移 → schema → 語法 → 編譯 → 語法檢查
   

   修復並重新執行，直到通過。切勿為了通過而抑制 lint 錯誤。有兩項檢查尚未包含在 vos check 中，因此需要透過渲染來執行：
   • Knob 誠實度：每個宣告的參數都必須有可見的效果。使用更改了 data 中該 key 的值（其最小值與最大值）來渲染程式兩次，並比較靜止圖像；一個在兩端讀取值相同的 knob 是無效的。對於錄音，使用 vos frames/vos render 的 --set <path>=<value> 來覆蓋。
   • 調色盤誠實度：顏色 knob 不得透過 new THREE.Color() 傳入 uniform（這會導致線性化，渲染的色調會偏離十六進位值）。請在您的函數字串中搜尋此模式。
2. 拍攝：

   vos still <file>.json f12.webp --time <持續時間的 12%>
   vos still <file>.json f40.webp --time <40%>
   vos still <file>.json f70.webp --time <70%>
   

   對於以動態為主的作品，請改為拍攝一張密集的序列圖（8 次以上，或一張 1 秒的接觸片）；三張靜止圖像無法評判動態權重。
3. 評判：根據以下的工藝底層以及資料夾自身的文件來評分這些畫面。一個屬於作品集的作品需要同時滿足作品集自身的 DESIGN.md 和繼承而來的 TASTE.md。修改並重複（最多 3 輪）；如果仍然失敗，則放棄並說明原因。切勿推送您不願為其辯護的作品。

5. 推送至資料夾，以版本形式迭代

vos push <file>.json --title "…" --desc "一行說明" --tags a,b \
  --folder <folderId|slug> --label "您所做的事" --note "原因：要求"

每次推送都要傳入 --label 和 --note，第一次也不例外：建立操作會將它們標記在 v1 上，而歷史記錄就是人類將要閱讀的對話。推送會在金鑰所有者的作品架上建立一個私有 vos，並歸檔到您拉取的資料夾中；預覽圖與縮圖會在儲存時於雲端渲染。使用 --vos <id> 對照追蹤的基礎版本進行迭代（vos-remix 循環：每一輪前先 vos pull，人工編輯的節點會受到保護，只有明確指示時才使用 --override）。金鑰永遠無法發佈；推廣（Promoting）是使用者在 vos.so 上的操作。

查看已推送的結果。 每次推送後約 15 秒內會渲染出一張靜止圖像：使用 GET /api/vos/{id}，跟隨 contentUrls.thumbnail，並在回報完成前檢視該圖片。從未查看過的推送不算完成。

批次處理節奏：在配額內，連續推送是可以的（渲染佇列會間隔啟動瀏覽器並自行退避）。批次處理後，請透過拉取資料夾來驗證狀態，絕不要從推送日誌中 grep 出來。

回饋發現。 當您學到關於此家族的事（例如某個參數範圍導致條帶、某個持續時間閱讀效果更好），請在相關食譜的 ## Agent notes 標題下，加上日期後附加：使用 PUT /api/assets/{id}/file 並提供完整的 markdown 內容（僅食譜，≤64KB）。切勿改寫所有者的規則。被替換的內容會被保留：GET /api/assets/{id}/file?prev=1 可讀取它，而 POST /api/assets/{id}/file/restore 可將其恢復。

家族流程：種子、檢視、擴散

新的家族作品是 1 個種子 + 一份食譜，絕非一批次。批次處理會將一個錯誤同時複製到每個成員中；單一種子能在 n=1 時捕捉到方向變化，然後再低成本地擴散。這是判斷，而非一個關卡：沒有需要撰寫或遵從的狀態行，用戶的要求永遠是最終決定。

1. 編寫一個種子，將其推送至資料夾，編寫（或更新）該家族的 DESIGN.md，包含機制、軸線與調色盤規則。
2. 展示它。人類與您一起迭代（歸因版本）。當他們要求變體時，那就是簽署通過；當一個資料夾只有一個新成員且要求是開放式的，先製作一個並說明原因。
3. 在被要求時再擴散。變體應變化構圖軸線（結構、動態語法、密度、鏡頭），絕不能只變化色調；只變化色調的擴散看起來就像同一個圖塊重複十次。擴散數量上限約為 10，以確保作品架審查仍能在 5 分鐘內完成。

工藝底層（通用、可 lint：非品味層面的標準）

• 能夠編譯與驗證：vos check 通過且無錯誤；切勿抑制。
• 確定性：seek 是 t 的純函數（畫面路徑中沒有 Date.now 或 Math.random；確定性 lint 會強制執行此規則）。
• 循環無縫數學：對於循環作品，相位必須是持續時間的整數倍，以使 frame(0) ≈ frame(end)。靜止圖像無法顯示接縫；請在數學上驗證。
• 誠實的 Knob：2 到 4 個宣告的參數，每個在其範圍的兩端都有明顯作用。少數誠實的 knob 勝過許多不誠實的。
• Knob 在每個影格的 onFrame 中讀取，絕不能在 createContent 內快照到 uniform 中。編輯器將 knob 編輯作為即時資料傳遞，僅交換 ctx.data；建立時的快照在重新整理前永遠不會更新。
• 非空白的第一影格：約 12% 的影格同時作為縮圖使用；不能有黑色、空白或「尚未開始」的開場。
• 無色帶、無裁切：添加顆粒以對抗色帶；控制 bloom 以避免過曝（強度 ≤ ~0.8，除非資料夾文件另有要求）；無可見的平鋪接縫或嚴重鋸齒。
• 調色盤誠實度：顏色 knob 絕不能透過 new THREE.Color() 傳入 uniform；應從十六進位值建構原始向量。
• 伺服器渲染限制（預覽群集使用軟體 GL）：禁止在傳輸材質上使用 THREE.DoubleSide，禁止使用 dispersion，所有提取的資產必須使用群集可達的絕對 https URL。

此界線之後的一切（持續時間、密度、氛圍、材質、調色盤紀律）都由資料夾來決定。

報告

結束時提供一個表格：slug · concept · tags · outcome（已推送 / 已放棄 + 原因），以及資料夾 URL（https://vos.so/app/projects?folder=<slug>）。明確陳述失敗：一個被放棄的設計是正確的結果，而非需要隱藏的錯誤。

嚴格規則

• 參考資料屬於創意方向。移植外部程式碼需要有相容的授權條款以及用戶的明確指示；品牌或商標作品將被拒絕。
• 絕不能發佈，絕不能切換可見性。推送預設為私有；推廣（Promotion）是使用者在 vos.so 上的人為決定。
• 作品架屬於使用者：請建立資料夾並歸檔您的作品；切勿重新命名、移動、刪除或重新排列他們建立的內容。
• 絕不能印出憑證，無論是在輸出、日誌或報告中。