topview-3d-cli

topview-3d-cli

topview-3d-cli 可编辑和渲染本地导演项目：包含 .topview-3d/ 文件夹的目录。 目标是为视频生成提供抽象且符合物理规律的场景布置参考：简单的形状、 正确的比例与支撑关系、清晰的走位，以及由多台静态摄像机拍摄的同一个世界。角色 位置优先，其次是合理性和摄像机连续性，最后是构图。精细的视觉细节不是目标；手机可以是块状物。请使用用户的语言回复。

此版本的范围：基本道具、四个内置角色（Child、Youth、Female、Man）、 121 种静态姿势、静态摄像机和根节点关键帧。没有动作库：绝不要承诺行走循环或其他身体动画。若要表现移动，可为角色指定合适的静态姿势（例如迈步姿势）；且仅在用户要求移动时，添加 transform.position / transform.rotation 关键帧（参见 references/edit.md）。 保留现有动画和剪辑数据，不要扩展它们。

第 1 步：检查环境

在会话中，先运行此命令：

topview-3d-cli doctor --json

命令始终以 0 退出；请根据顶层的 ok 判断后续操作。如果 ok 为 false，请读取每个失败项的 checks.<name>.hint，并遵循 references/doctor-browser.md：

• 找不到 topview-3d-cli： 它在每台机器上只需安装一次，且应安装在所有项目共享的环境中。安装任何内容前，请先检查以下路径：macOS 和 Linux 上的 ~/.local/share/topview-3d-cli/venv/bin/topview-3d-cli，Windows 上的 $env:LOCALAPPDATA\topview-3d-cli\venv\Scripts\topview-3d-cli.exe。 如果文件存在，且其 doctor --json 报告的 cliVersion 与此技能固定的版本 topview-3d-cli==0.1.8 一致，请在每条命令中使用该路径。 否则，请按 references/doctor-browser.md（Installing topview-3d-cli）中的说明安装一次。 绝不要在用户的项目或工作区内创建虚拟环境，也不要使用 pip install --user。
• node 检查失败： 需要 Node.js 20.6 或更高版本（含 npm）；请让用户安装。
• 检出目录： 如果此技能所在文件夹中也有 agent/ 和 editor/（插件安装属于检出目录），请运行其中的 scripts/install.sh（Windows 上为 install.ps1）安装一次。它会将 CLI 安装到共享环境中，并一并安装渲染器和 Studio 的 Next.js。 不要只安装渲染器包。
• playwright 或 chromium 检查失败： 运行一次 topview-3d-cli browser ensure（它会将固定版本的 Chromium 下载到用户缓存中）。
• 在 Agent 沙盒中渲染失败，但 doctor 检查通过：沙盒阻止了浏览器，而不是 topview-3d-cli。请说明这一点，请用户批准在沙盒外运行渲染命令，并继续处理不需要浏览器的工作。绝不要构建替代渲染器（图像库、SVG、手绘帧）。

CLI 合约

• 每个命令都会在 stdout 上打印一个 JSON 对象。失败时会在 stderr 上打印 {"ok": false, "code", "error"}， 并在可用时附带 details（例如失败的 index）。退出码 0 表示成功，2 表示输入无效，包括指定的 id 不对应任何现有节点、资源、姿势或摄像机（请修正输入）；1 表示命令无法执行（冲突、缺少依赖项、渲染器失败）。
• 规范文件必须是 JSON 对象；- 表示从 stdin 读取。请先将它们写入临时文件。
• 写入前先验证：对 document apply、node batch 和 pose batch 使用 --dry-run，并使用 topview-3d-cli evaluate <dir> plan.json 验证计划中的数值。命令失败时不会写入任何内容。
• 从最新结果中传入 expectedSceneSequence。遇到 SCENE_SEQUENCE_CONFLICT 时，重新读取并重新规划；切勿盲目递增该数值。
• 原样复制命令输出中的 id（libraryId、poseId、presetId 和节点 id）。切勿编造 id、尺寸或测量值。
• 渲染后，打开返回的 PNG 文件并查看，然后再进行判断。未查看的渲染结果不能作为视觉证据。
• 使用 topview-3d-cli（node batch、pose batch、document apply）更改 3D 场景。不要在 Studio 页面中点击、拖动或输入，也不要使用浏览器自动化来移动或编辑节点。In-App Browser 仅用于打开 Studio，供用户查看场景。
• 同一时间只能有一个写入者：Studio 正在保存同一项目时，不要运行写入命令。用户在 Studio 中编辑后，请先通过 document get 重新读取，再规划下一次更改。Studio 会通过 project adopt 写回，因此磁盘上的项目就是已编辑的场景。

每个会话都从上下文开始

topview-3d-cli project status <dir>            # or: topview-3d-cli project init <dir> for a new scene
topview-3d-cli document get <dir> --summary    # nodes, cameras, sceneSequence
topview-3d-cli bom get <dir>                   # the plan record: intent, relations, cameras, verification

规划前先阅读这些内容；仅在你自己写入内容或发生冲突后才重新读取。`topview-3d-cli document get

--entity ` 会返回一个完整的节点或片段。

工作流阶段

每个会话中，在首次执行某阶段的命令前，先阅读该阶段的参考资料：

在每个阶段交界处引导用户

核心原则：引导应让下一步有用的操作清晰明了。在创意决策点暂停；对于已获批准操作中的执行步骤，使用进度更新。

默认情况下，完成下方的一个阶段，让用户能够查看结果，然后询问用户是否要继续到指定的下一阶段，或修改当前结果。等待用户回答后再开始下一阶段。不要悄悄执行完整张表，直到渲染后才提问。 这适用于新场景、编辑和修订，包括最终交付。 例外：一旦用户授权为当前任务生成视频，阶段 10 可继续完成准备、提交服务和交付，无需再询问阶段交界处的批准。 此授权仅适用于当前生成轮次，不适用于 3D 计划未来的所有版本。 如果反馈要求返回场景、模型、姿势或摄像机阶段，请完成并验证修订后的预览，然后暂停并询问用户是要基于该预览生成，还是要进一步调整。不要将上一轮的同意延续到这个决策点。明确要求同时修订并重新生成，已回答了这个选择；请参阅 references/generate.md。

• 简要说明当前已准备就绪的内容，展示相关方案、预览或结果，并提及会影响下一步选择的任何未解决限制。对于非视觉阶段，简要概述即可。
• 推荐一项具体的下一步操作，并用一句话说明其目的。最后用用户所用的语言提出一个明确的问题。说清楚实际要执行的操作以及可以修改的内容，而不是只问“继续吗？”或“接下来做什么？”。以下示例以英文撰写；回复时请本地化：
  • 完成布局方案后：“您希望我在 3D 中构建这个场景，还是先修改布局？”
  • 完成场景构建后：“您希望我设置镜头运动，还是先修改这个场景？”
  • 完成镜头设置后：“您希望我渲染预览视频，还是先调整镜头运动？”
  • 准备好参考视频和生成提示词后：“您希望继续生成视频、修改这个场景，还是先编辑生成提示词？”
  • 根据反馈修改 3D 预览后：“修改后的镜头预览已就绪。您希望我据此生成新的视频写实版本，还是进一步调整场景或镜头运动？” 仅提供适用于当前结果且现有能力支持的选项。如果参考视频尚未就绪，请先提出渲染或导出参考视频，再提供生成交接选项。
• 一个阶段是面向用户的里程碑，而不是每次 CLI 调用。完成让该阶段结果可供评审所需的读取、测量、试运行、渲染和必要修正后，再提出问题。不要针对每次工具调用征求许可，也不要停在未经验证的中间结果上。
• 如果用户要求修改，请在当前阶段完成并验证修改，展示更新后的结果，然后再次提供进入下一阶段或继续修改的选项。用户要求修改本身并不代表授权进入后续阶段。沉默不代表答复。
• 只执行与请求相关的阶段：编辑不应重新开始已完成的设置，也不应重建无关对象。对于最后一个适用阶段，请提供具体的后续操作或进一步修改选项；尊重“停止”“现在不用”或不再提问的要求。
• 如果用户明确要求不间断地完成多个阶段或整个工作流，请按要求执行，并在结束时再提问。对于常规的“构建场景”请求，遵循上述分阶段引导流程。不要反复确认用户已批准的阶段。
• 在渲染输出交接时，遵循第 10 阶段：准备并展示生成提示词。只有当用户尚未授权从当前版本生成时，才询问是否生成。像“渲染并生成视频”这样的明确请求已构成授权。获得授权后，请提供进度更新，不要反复询问是否批准准备或执行。 | 阶段 | 操作 | 参考 | | --- | --- | --- | | 1. 理解 | 根据对话和当前状态明确意图；将其记录在 BOM 中 | references/state-intent.md | | 2. 布局 | 关系、支撑、朝向、间距；BOM 字段 | references/layout.md | | 3. 道具 | 优先使用 1–4 个基本图元；仅在需要时导入模型 | references/add-prop.md | | 4. 人物 | 从内置角色中选择；先放置再摆姿势 | references/add-character.md | | 5. 姿势 | 使用经过审核的文本映射；调整座椅适配 | references/pose.md | | 6. 摄像机 | 必须包含鸟瞰总览，并根据人物数量调整故事镜头覆盖范围 | references/camera.md | | 7. 编辑 | 只修改用户要求的内容；使用批处理语法；设置关键帧 | references/edit.md | | 8. 检查 | 检查数字和渲染结果，查看 PNG 并进行修改 | references/checks.md | | 9. Studio | 使用 In-App Browser 在本地 Studio 中打开完成的场景 | references/doctor-browser.md | | 10. 生成 | 编写并展示提示词；如果尚未获得授权，则请求一次生成授权，然后生成并记录结果，不要重复确认 | references/generate.md、references/video-prompt.md |

帧准备就绪后

对于所有以渲染视频或帧为结果的工作流，阶段 10 都是必不可少的一环：渲染完成后不要就此结束会话。 请阅读 references/generate.md 并遵循其中的说明。视频渲染完成后，立即按照 references/video-prompt.md 自行编写生成提示词，无需用户提出要求， 并将其展示给用户；如果尚未获得本次生成的授权，则询问用户是否生成。获得授权后， 完成服务选择、生成和结果记录，不要重复请求批准。 视频生成时，使用渲染或导出的视频作为参考。

构建、检查和渲染均保持离线。阶段 10 是唯一可以在用户授权的生成任务范围内访问外部 服务的阶段。其他任何阶段都不得联系生成 服务。

道具、角色和姿势的素材搜索规则见 references/asset-selection.md。 安装、浏览器和沙盒限制见 references/doctor-browser.md。

命令

需求	命令
新建项目／状态	topview-3d-cli project init <dir>、topview-3d-cli project status <dir>
读取文档	topview-3d-cli document get <dir> --summary、topview-3d-cli document get <dir> --entity <id>
添加、更改、删除节点	topview-3d-cli node batch <dir> changes.json [--dry-run]、topview-3d-cli node delete <dir> <id>
底层操作（场景设置、关键帧）	topview-3d-cli document apply <dir> ops.json [--dry-run]
查找素材	topview-3d-cli asset search <words> --kind character|pose|prop、topview-3d-cli asset show <id>
姿势列表	topview-3d-cli pose catalog [--category sit]
为人物设置姿势	topview-3d-cli pose batch <dir> poses.json [--dry-run]、topview-3d-cli pose apply <dir> <nodeId> <poseId>
摄像机预设	topview-3d-cli camera presets
不使用浏览器查看数字	topview-3d-cli evaluate <dir> [plan.json] [--frames 0,24] [--camera <id>]
网格测量	topview-3d-cli inspect nodes <dir> <id>... [--frame N]
查看各摄像机的数字和渲染结果	topview-3d-cli inspect views <dir> --camera <id> ... --primary <id>
单次渲染	topview-3d-cli render <dir> [payload.json]
查找已渲染的 PNG	topview-3d-cli renders list <dir>、topview-3d-cli renders show <dir> [runId] [--frame N]
计划记录	topview-3d-cli bom get <dir>、topview-3d-cli bom checkpoint <dir> patch.json
结构验证	topview-3d-cli document validate <dir>
在 Studio 中打开	topview-3d-cli studio open <dir>，然后在 In-App Browser 中打开返回的 url

## 硬性规则

1. 坐标系为右手坐标系，Y 轴朝上，单位为米；旋转使用欧拉角（度）；缩放为正数倍数（纸片般薄的轴使用 0.001）。节点 ID 匹配 [A-Za-z0-9_-]{1,128}。
2. 在放置或就座前进行测量（topview-3d-cli inspect nodes）；evaluate 中的视锥和地面检查仅使用节点原点和基本体边界框。
3. 每个场景都要保留一个专用的鸟瞰相机（BOM 相机角色 layout_overview），并在布局变更后重新调整。它用于展示布局，不是主要叙事画面。
4. 选择一个 BOM story 相机作为 inspect views 的 --primary。除非用户指定数量，否则多人物场景须满足 references/camera.md 中的最低要求（3 人或以上：一个群体主视图、每个互动群体一个视图，以及每个主要角色一个特写）。
5. 一般所说的“坐着”是指坐在椅子、沙发、长凳或凳子上，除非明确要求坐在地上、盘腿坐或跪坐。优先复用座椅，或先用 1–4 个基本体搭建座椅。
6. 如实报告不足之处：简化替代方案须明确说明；未经验证的约束保持为 unknown。
7. 细线、条纹、Z-fighting 和锯齿都是渲染器伪影，并非缺陷。只有在有测量结果或 BOM 硬性关系检查失败作为依据时，才进行修改。每轮修正只运行一次 inspect views。
8. 默认时间线：24 fps，共 120 帧。切勿在消息中粘贴图像字节或 Base64；请提供路径。
9. 使用 CLI 更改 3D 场景。不要通过 Studio 页面或浏览器自动化进行编辑。
10. 在 In-App Browser 中打开本地 Studio，供用户查看。studio open 只会启动服务器并返回 url；请在 In-App Browser 中打开该 url，不要使用系统浏览器。如果因未安装 Next.js 而失败，请在检出目录的 editor/ 目录中运行一次 pnpm install，然后重试一次 studio open。参见 references/doctor-browser.md。