用途
topview-3d-cli 用于在本地机器上搭建、编辑、检查并渲染 3D 预演（staging）场景。其目标是生成一个抽象、物理一致的舞台参考，供后续视频生成使用：使用简单形状、正确的比例与支撑关系、清晰的场面调度，以及从多个静态相机观察同一个世界。角色位置优先，其次是合理性与相机连续性，最后才是构图。精细视觉细节不是目标，例如手机可以用一块板表示。
主要能力
- 项目与状态管理：初始化新项目、查看项目状态。
- 文档读取：以摘要或按实体读取场景文档。
- 节点操作：批量添加、修改、删除节点，支持 --dry-run 预演。
- 底层操作：通过 document apply 进行场景设置与关键帧等操作。
- 资产查找：按 character、pose、prop 类型搜索资产并查看详情。
- 姿势：查看姿势目录（可按类别过滤）、批量应用姿势、对指定节点应用姿势。
- 相机：查看相机预设。
- 数值评估：无需浏览器即可评估场景数值，支持指定帧与相机。
- 网格测量：检查节点尺寸，支持指定帧。
- 视图检查：按相机生成数值与渲染结果，可指定主相机。
- 渲染：执行单次渲染，并列出、查看已渲染的 PNG。
- 计划记录：读取与更新 BOM（意图、关系、相机、验证）。
- 结构校验：对文档进行结构验证。
- Studio：启动本地 Studio 并返回 URL，供用户在应用内浏览器查看场景。
使用方式
每个会话开始时先运行环境自检：
topview-3d-cli doctor --json
该命令始终以 0 退出，需根据顶层 ok 字段判断。当 ok 为 false 时，阅读各失败检查项的 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 安装一次。不要在用户项目或工作区内创建虚拟环境，也不要使用 pip install --user。
会话开始时读取上下文：
topview-3d-cli project status <dir> # 或：topview-3d-cli project init <dir> 创建新场景 topview-3d-cli document get <dir> --summary # 节点、相机、sceneSequence topview-3d-cli bom get <dir> # 计划记录：意图、关系、相机、验证
规划前先读取，仅在自己的写入或冲突后重新读取。
常用命令包括：project init/status、document get、node batch/delete、document apply、asset search/show、pose catalog/batch/apply、camera presets、evaluate、inspect nodes/views、render、renders list/show、bom get/checkpoint、document validate、studio open。
规范文件为 JSON 对象，- 表示从 stdin 读取，应先写入临时文件。写入前先验证：document apply、node batch、pose batch 使用 --dry-run，计划数值使用 topview-3d-cli evaluate <dir> plan.json。命令失败时不写入任何内容。
工作流阶段
- 理解：从对话与当前状态解析意图，记录到 BOM。
- 布局：关系、支撑、朝向、间距；BOM 字段。
- 道具：优先 1–4 个基础几何体，必要时才导入模型。
- 人物：从内置角色中选择，先放置再摆姿势。
- 姿势：使用经过审阅的文本映射；座椅适配。
- 相机：必须有鸟瞰总览，并按人数扩展故事覆盖。
- 编辑：只改被要求的内容；批量语法；关键帧。
- 检查：数值、渲染、查看 PNG、修正。
- Studio：用应用内浏览器打开完成的场景。
- 生成：编写并展示提示词；若缺少授权则获取一次生成授权，然后生成并记录结果，不再反复确认。
默认在每个阶段边界暂停，让结果可审阅，再询问用户是否继续到下一阶段或修改当前结果。若用户明确要求连续完成多个阶段或整个流程，则尊重该范围，在结束时再询问。
适用场景
- 为视频生成准备抽象、物理一致的 3D 舞台参考。
- 需要角色位置、支撑关系、相机连续性优先于视觉细节的预演。
- 使用基础几何体道具与内置角色（Child、Youth、Female、Man）搭建场景。
- 使用 121 个静态姿势、静态相机与根关键帧进行场面调度。
- 在本地离线完成构建、检查与渲染，仅在视频生成阶段访问外部服务。
限制
- 本版本范围：基础几何体道具、四个内置角色、121 个静态姿势、静态相机与根关键帧。
- 没有运动库：不得承诺行走循环或其他身体动画。若要暗示运动，可给角色一个合适的静态姿势（例如行走步态），且仅在用户要求运动时添加 transform.position / transform.rotation 关键帧。
- 应保留现有动画与编辑数据，而不是扩展它们。
- 渲染在代理沙箱内可能失败，因为沙箱阻止浏览器而非 topview-3d-cli；此时应说明情况，请用户在沙箱外批准运行渲染命令，并继续处理不需要浏览器的工作。不得构建替代渲染器（图像库、SVG、手绘帧）。
- 坐标约定：右手系、Y 轴向上、单位米；旋转为欧拉角度；缩放为正乘数（0.001 表示纸薄轴）。节点 id 匹配 [A-Za-z0-9_-]{1,128}。
- 默认时间线：24 fps、120 帧。
- 不得在消息中粘贴图像字节或 Base64，应给出路径。
- 一次只允许一个写入者：Studio 正在保存同一项目时不要运行写入命令。用户在 Studio 编辑后，规划下一次更改前先用 document get 重新读取。
- 只能通过 CLI 更改 3D 场景，不要通过 Studio 页面或浏览器自动化编辑。
- 细线、条纹、z-fighting 与锯齿是渲染器伪影，不是缺陷。仅在背后有测量或失败的 BOM 硬关系时才编辑。每次修正只做一次 inspect views。
- 资产搜索规则见 references/asset-selection.md；安装、浏览器与沙箱限制见 references/doctor-browser.md。