3dMVP/blobit-cli-skill-pack

Blobit CLI

使用 blobit 作为资产后端，并在游戏需要消费托管的 Blobit 场景时，将其作为场景/发布后端。

• 使用 blobit 以：
  • 创建项目
  • 上传图像
  • 生成或重用 3D 资产
  • 检查放置元数据
  • 编排并验证场景
  • 发布清单
• 对于浏览器游戏，使用常规代码工具进行规划、搭建、实现、运行和视觉验证可玩游戏。
• 在游戏项目中，Blobit 负责运行时资产生成。游戏逻辑代码、UI、输入、相机、物理和游戏状态保留在游戏代码库中。
• 对于浏览器游戏，已发布的清单模式是默认的资产交付路径：使用 blobit publish create 返回的 manifest_url，并通过 @blobit/sdk 加载。

何时使用

当用户提出以下请求时使用此技能：

• 创建或管理 Blobit 项目与资产
• 从图像生成 3D 模型
• 使用语义放置命令布局场景
• 发布 Blobit 场景供浏览器使用
• 将已发布的 Blobit 内容集成到使用 SDK 的网页游戏中
• 创建或更新由 Blobit 生成或提供运行时资产的浏览器游戏

规则

• 当需要解析命令输出时，优先使用 blobit --json。
• 优先使用语义场景命令，而非手动编辑原始变换。
• 对于新资产，除非用户明确提供现有模型重用，否则优先使用 Blobit 图像生成、图像上传或本地图像上传加模型/世界生成。
• 对于模型和世界生成命令，优先使用存储的默认提供商，除非任务需要通过 --provider 进行一次性覆盖。
• 优先使用 blobit config set-provider <provider>，而不是告知用户手动编辑 Blobit 配置文件。
• 在新命令中不要使用旧的提供商别名 --endpoint-type；请使用 --provider。
• 在资产的原点、足迹或地面接触不明确时，在进行排列或取景前检查放置元数据。
• 在重大布局更改前后运行 scene analyze。
• 在发布前运行 scene validate。
• 当任务更改可见场景几何体并且本地预览或查看器可用时，截取屏幕截图并检查是否存在明显的视觉问题。
• 对于浏览器游戏，避免下载资产，并在运行时加载已发布的 Blobit 清单。
• 仅在用户明确要求打包、离线、静态或本地文件资产时，才使用 blobit assets download。
• 不要询问或报告美元资产预算。当前的 Blobit CLI 不返回资产生成花费；请询问资产范围、资产数量和优先级。
• 对于高精美度的游戏，默认使用审查门控模式：询问简短问题、生成视觉目标、编写 PLAN.md、生成或分配 Blobit 资产、构建首个可玩版本、捕获证明，然后根据反馈迭代。
• 在规划游戏实现之前，询问或记录碰撞/物理的架构选择：自定义街机碰撞、Babylon/Havok 物理或混合方式。
• 当任务要求使用 Blobit 制作的资产时，不要使用非 Blobit 的资产生成供应商或脚本。
• 将 Blobit 仅视为资产和场景后端；使用仓库的常规代码工具构建游戏逻辑和渲染。
• 对于已发布的运行时内容，使用 blobit publish create 返回的 manifest_url，并通过 @blobit/sdk 加载。

产出物

• 一个 Blobit project_id
• 已上传的源图像资产 ID 或重用的源资产 ID
• 生成的模型资产 ID，以及在适用时完成的作业 ID
• 一个包含已放置模型、相机状态和已应用的语义布局操作并持久化的场景
• scene analyze 和 scene validate 的结果
• 一个已发布的 manifest_url 以及相关的发布元数据，例如 publish_id 和 viewer_url
• Web 应用程序中 @blobit/sdk 加载已发布清单的运行时集成点
• 对于游戏任务，当项目工作流支持时，产出 PLAN.md、STRUCTURE.md、ASSETS.md 以及运行中浏览器游戏的视觉证明

管线

1. 检查或创建 Blobit 项目。
2. 上传源图像并生成模型，或者重用显式的现有资产。
3. 检查生成的或重用的资产，特别是放置元数据，然后再进行场景布局决策。
4. 将模型添加到场景中。
5. 应用语义放置操作，例如 drop-to-floor、place-near、arrange、align、avoid-overlap、distribute、snap 和 frame-camera。
6. 运行 scene analyze，检查重叠、边界和警告，并在必要时调整场景。
7. 在发布前运行 scene validate，并将验证警告视为阻塞性问题，除非用户明确接受它们。
8. 发布并捕获 manifest_url 以及任何相关的查看器或发布元数据。
9. 在游戏客户端中，通过 @blit/sdk 加载该清单。
10. 使用常规项目堆栈构建或更新实际的游戏逻辑和渲染。

对于可玩的浏览器游戏，在规划或编码前请阅读 references/game-workflow.md。它定义了一个针对仅使用 Blobit 资产而调整的规划和实现循环。 如需了解该游戏工作流背后的 Godogen 衍生原理，请仅在更新技能或协调工作流决策时阅读 references/godogen-patterns.md。

运行时验证

• 在重大布局或相机更改后，当本地游戏、预览或 Blobit 查看器可用时运行它们。
• 当渲染的几何体至关重要时，截取屏幕截图，并检查漂浮的模型、裁剪、比例错误、方向错误、相机取景不良以及语义检查可能遗漏的重叠。
• 将屏幕截图审查视为 scene analyze 和 scene validate 的补充，而非替代。
• 如果没有可用的运行时预览，则依赖 CLI 验证，并明确注明跳过了视觉验证。

场景说明

• 当对象应明显地放置在舞台或地平面时，使用 drop-to-floor。
• 在添加、移除或重新排列模型后，或者当前相机可能不再对准主体时，使用 frame-camera。
• 在对象的原点、支撑面或足迹不明确时，在 arrange 或 place-near 之前检查资产放置元数据。
• 优先使用语义场景操作，而非直接的变换编辑；仅在进行精确的最终调整或用户明确要求时使用直接变换。
• 在批量排列或重叠解决通过后运行 scene analyze，以确认场景符合预期。

预期输出 / 交接

• 关键 ID 和 URL：project_id、相关的资产 ID、作业 ID、publish_id、manifest_url 和 viewer_url（如适用）
• 所应用的场景操作和最终验证状态的简短摘要
• 应用程序通过 @blit/sdk 加载已发布清单的确切运行时集成点
• 关于是否执行了运行时屏幕截图验证及其结果的说明
• 任何仍需要跟进的未解决布局、验证或运行时限制

核心命令

• blobit --json projects list
• blobit --json projects create --name ...
• blobit --json assets generate-image ...
• blobit --json assets upload-image ...
• blobit --json jobs model-from-image ... --wait
• blobit --json jobs model-from-prompt ... --wait
• blobit --json jobs world-from-prompt ... --wait
• blobit --json assets inspect <asset_id>
• blobit --json assets download <asset_id> --out ...
• blobit --json scene add-model <project_id> <asset_id>
• blobit --json scene add-world <project_id> <asset_id>
• blobit --json scene analyze <project_id>
• blobit --json scene place-near ...
• blobit --json scene arrange ...
• blobit --json scene validate <project_id>
• blobit --json publish create <project_id> --allowed-origin ...

请阅读 references/workflows.md 以获取端到端命令示例。 请阅读 references/game-workflow.md 以获取浏览器游戏规划、实现、资产清单和视觉证明指南。