vos-create

以用户的风格在其文件夹中创建 vos 程序

你在 属于文件夹的 vos 程序：用户位于 vos.so 上的文件夹是内容的集合，其中的 .md 文件（配方）是风格，其中的 voses 是范例。此技能仅包含 机械流程 和通用的工艺底线。品味属于用户数据，存在于他们的文件夹中，永远不会放在这里。创作规则（schema、dialect、knobs）位于 vos-authoring 技能中；knob 和外观相关的工艺则位于 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 个示例配置或文档。配方是按角色命名的方面（facets），命名方式采用大写，就像 CLAUDE.md 一样：TASTE.md 是评判标准，DESIGN.md 是技术规范，以及用户意图创建的任何其他文件（MOTION.md、COPY.md、BRAND.md……）。配方是一个集合在创作任何内容之前会读取的文件，其名称本身就说明了这一点；你归档的配方会以其词干大写的形式存储，因此请以这种方式编写它，架子会显示你编写的内容。平台不强制执行超出此范围的分类法；你需要读取所有配方。绑定规则如下：

• 配方和示例 覆盖此技能或创作技能所拥有的每一条默认规则。它们的持续时间就是持续时间；它们的调色板规范就是规范。
• 文件之间存在冲突时，更具体的一方胜出：文件夹自身的文件优先级高于继承的，较近的祖先优先级高于较远的，具体的指令优先级高于一般的指令。真正存在矛盾时，应该向用户提出问题，而不是默默地做出选择。
• 当某个配方与文件夹最近的示例存在分歧时，优先采用示例，并告知用户该配方可能已过时。

空文件夹（没有配方，没有示例）：仅适用下面的工艺底线。风格来自用户的参考或一次提问，绝不要使用内置的默认值。

3. 找到种子，然后进行创作

一个文件夹包含两样东西，它们有时重合：参考（好的标准，你用来评判的依据）和 种子（你复制并编辑以生成下一个成员的起点）。在编写任何代码之前，确定你持有的是哪一种：

• 程序家族（一个已签收的成员 + 一个 DESIGN.md，命名了机制及其轴）：种子 = 该成员。获取其配置并在配方命名的轴上对其进行变体。永远不要从一个空白文件开始创作，也不要仅从色调入手。
• 拍摄规格（一个配方，说明集合中每个录制品如何剪辑）：种子 = 用户给你的 新 录制品（通过 ID 引用文件夹中的录制、指向 vos record --strict 的 URL、或一个本地文件）。文件夹自身的录制是参考剪辑，而不是种子。
• 模板（一个指向或内联了某个机制及其变体方式的配方）：种子 = 模板。托管为 vos：像获取成员一样获取它；内联代码：是用于构建的片段。
• 仅包含 brief（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> 会写入 <slug>/config.json，保留参数，以及一个跟踪基础版本的 vos.json 文件。

对于 “复现 X” 类的 brief：首先获取源文件或录制品，或者确认 brief 只想要外观。一张静态图像无法完全确定动态；一个匹配了截图但发明了错误机制的程序，即使帧匹配也是失败的。源文件获取、许可和测量匹配循环是复现工作；先做这些，然后再回到这里，从它产生的结果进行创作。

4. 检查、拍摄、评判，依据 文件夹 的文档

1. 检查：

   vos check <file>.json     # migrate → schema → syntax → compile → lints
   

   修复并重新运行直至通过。永远不要为了通过而抑制 lint 错误。下面两种检查 vos check 尚未包含，因此需要通过渲染来完成：
   • 旋钮真实性：每个声明的参数必须可见地起作用。使用该键在 data 中分别取最小值和最大值渲染程序两次，并比较静态图像；在两端读取结果相同的旋钮是无效的。对于拍摄，使用 vos frames/vos render 的 --set <path>=<value> 参数来覆盖。
   • 调色板真实性：颜色旋钮不得通过 new THREE.Color() 传递到 uniform 中（颜色会被线性化；渲染的色相会偏离十六进制值）。在函数字符串中搜索此模式。
2. 拍摄：

   vos still <file>.json f12.webp --time <12% of duration>
   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 "one line" --tags a,b \
  --folder <folderId|slug> --label "你做了什么" --note "原因：要求是什么"

每次 推送都必须传递 --label 和 --note 参数，包括第一次：创建操作会将它们标记在 v1 上，历史记录就是人类阅读的对话。推送会在密钥所有者的架子上创建一个私有的 vos，并归入你拉取的文件夹；预览图和缩略图会在云端根据保存的内容渲染。使用 --vos <id> 针对跟踪的基础版本进行迭代（vos-remix 循环：每次迭代前都 vos pull，人工编辑的节点会被保护，仅在有明确指令时使用 --override）。密钥永远无法发布；推广是人类在 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 干净通过；绝不抑制错误。
• 确定性：寻址是 t 的纯函数（帧路径中不能有 Date.now 或 Math.random；确定性 lint 会强制执行）。
• 循环无缝数学：对于循环作品，相位必须是时长的整数倍，使得 frame(0) ≈ frame(end)。静态图像无法显示接缝；在数学上验证它。
• 真实的旋钮：2 到 4 个声明的参数，每个都要在其范围的两端可见地起作用。少数诚实旋钮胜过许多虚假旋钮。
• 旋钮在 onFrame 中、每帧读取，绝不在 createContent 内部快照到 uniform 中。编辑器将旋钮编辑作为仅交换 ctx.data 的实时数据传递；创建时的快照在刷新前永远不会更新。
• 非空白的第一帧：约 12% 的帧同时用作缩略图；不能有黑色、空白或“尚未开始”的开场。
• 无条带、无剪切：添加颗粒以防止条带；保持 bloom 远离过曝（强度 ≤ ~0.8，除非文件夹文档要求更高）；没有可见的平铺接缝或硬锯齿。
• 调色板真实性：颜色旋钮不得通过 new THREE.Color() 传递到 uniform 中；从十六进制值构建原始向量。
• 服务端渲染约束（预览集群使用软件 GL）：透射材质上不能使用 THREE.DoubleSide，不能使用 dispersion，每个获取的资源必须是集群可以访问的绝对 https URL。

这一行之后的所有内容（时长、密度、情绪、材质、调色板规范）都由文件夹来决定。

报告

以一个表格结束：slug · 概念 · 标签 · 结果（已推送 / 已放弃 + 原因），外加文件夹 URL（https://vos.so/app/projects?folder=<slug>）。明确说明失败情况：一个放弃的设计是正确的结果，而不是需要隐藏的错误。

硬性规则

• 参考资料是创意方向。移植外部代码需要兼容的许可 以及 用户的明确指示；拒绝带有品牌或商标的构图。
• 永不发布，永不切换可见性。推送天生就是私有的；推广是用户在 vos.so 上的人工决策。
• 架子（shelf）属于人类：创建文件夹并将 你的 作品归档；永远不要重命名、移动、删除或重新排序他们制作的内容。
• 切勿打印凭证，无论是在输出、日志还是报告中。