需要可视化审查 CAD/URDF/SRDF/SDF/DXF/…

当有一个或多个明确文件路径的 CAD 或机器人描述文件需要图形化审查时，启动本地 Viewer 并提供每个文件的浏览链接。

适用场景

解决思路

1. 运行 Viewer 时以已安装本地技能文件为运行时事实来源；仓库链接仅用于来源和发布审查。
2. 接受一个或多个显式文件路径作为输入，在 CAD Viewer 中打开现有或新生成的 CAD、robot-description 或 DXF 文件，并交回实时审查链接。
3. 将本技能的 requirements.txt 安装到 Python >= 3.11：`python -m pip install -r requirements.txt`；cadgen 命令会携带服务器和预构建客户端，无需在运行时安装 Node。
4. 用 `cadgen doctor <this skill's directory>` 确认已安装的 cadgen 与技能发布版本匹配。
5. 启动 Viewer：`cd /absolute/project/models && cadgen viewer --host 127.0.0.1 --json`；如果 cadgen 不在 PATH，用同一解释器运行 `python -m cadgen.viewer`。
6. 启动是无条件的：命令总是以启动目录的实时 Viewer URL 结束；如果同一目录已有相同 Viewer 代码的实例（复用 key 为 realpath(directory) x 身份令牌——令牌由 cadgen 版本及其 Python 运行时和确切构建客户端的内容摘要组成，升级后的 Viewer 或不同 --dist 绝不会返回陈旧实例），则返回其 URL（action 为 reused）；否则从 3245 起首个空闲端口启动新服务器（action 为 started）。
7. 不要自行选择或推理端口，始终读取命令打印的 URL。
8. 每个实例只服务一个目录——启动时所在目录，进程生命周期内固定；没有指定目录的 flag，cwd 就是被服务目录。
9. 慎重选择启动目录：cwd 决定 catalog 扫描什么，也是实例复用 key；`cd` 到用户视作模型工作区的目录（通常是项目的 models/ 目录），再启动。
10. 不要从本技能目录内启动，否则服务的是技能而不是模型。
11. 总是传 `--json`，它打印机器可读的最后一行 stdout（包含 url、port、action；action 为 started 或 reused），并从那里取 URL。
12. 用 `--new` 强制新实例而不是复用。
13. 显式 `--port <n>` 是严格的“此端口或失败”，并禁用复用和滚动；`cadgen viewer --help` 列出其余参数。
14. URL 形状为裸 origin，`file=` 选择服务根内一个 artifact，例如 `http://127.0.0.1:3245/?file=gripper/STEP/gear_rack_gripper.step`。
15. `file=` 值相对于被服务目录；URL 中不出现目录，因此同一链接在不同实例下含义不同——根属于服务器，不属于链接。
16. 启动目录是工作区，不是文件所在文件夹；Viewer 递归扫描它，文件浏览器列出其下每个模型，用户无需新链接即可切换文件；从用户视作模型工作区的目录启动，通常项目的 models/ 目录或所审查文件最近的共同父目录，并把其余路径放进 `file=`。
17. 不要从 artifact 自己的深层文件夹启动（例如 `cd .../models/gripper/STEP`、`?file=gear_rack_gripper.step`），虽然打开同一模型，但隐藏项目其余部分，几乎不是用户想要的。
18. 端口冲突不是你要处理的：launcher 会滚动到空闲端口，打印的 URL 才是事实；在沙箱 agent 环境中，仍可能出现 `EPERM`/`EACCES` 等本地绑定失败；用所需权限/提权重跑。
19. 用 `cadgen viewer list` 显示每个运行实例及其服务目录；用 `cadgen viewer stop --port <n>` 结束一个；两者可在任何地方运行——只有启动关心 cwd。
20. 要审查当前 root 外的目录，只需 `cd` 到那里再次启动；reuse-or-start 让第二次启动廉价且正确。
21. Viewer 是静态可视化工具，只渲染已存在的 artifact；生成模型必须先由其模型脚本构建（见 CAD 技能）；Viewer 从不运行脚本，也从不了解文档是否有脚本。
22. .step/.stp 文档在 Viewer 中的状态由文件字节和 store 单独决定，有四种：not compiled（store 没有这些字节的树——Viewer 提供编译，并在打开时编译）、compiling · <phase> n/total（cadgen 构建池中的作业正在生成包含此文档的树——Viewer 自身编译、终端里的 `python model.py`、父级子构建都一样）、rendered、failed（该文档最后一次作业失败；显示消息）。
23. 编译是提交到每个 cadgen 入口所用同一构建池的作业，因此进度和错误会作为数据返回；没有“stale vs source”状态：文档是否落后于其脚本是 `cadgen store why` 的问题，不是 Viewer 的；当 agent 在做事时没有要先运行的东西：直接使用文件并返回链接。
24. 返回任何链接前，resolve `<directory>/<file>` 并确认存在；传 `.step`/`.stp` artifact 本身——生成的和导入的都一样；catalog 列出 artifact 并完全按磁盘上的写法命名：`moonwatch.step` 在标签、面包屑、catalog 行和文件选择器中都是 `moonwatch.step`，无论生成还是导入。
25. Viewer 从不了解文档是否生成：其状态只由 artifact 侧决定（not compiled / compiling / rendered / failed），模型脚本不在 UI 中显示；生成模型的文档必须已存在（运行模型脚本）；store 没有树的文档在打开时从其字节编译；如果解析路径缺失，不要返回链接；报告问题并指出正确路径。
26. 每个请求文件返回一个 Viewer URL。
27. 每会话只启动一次 Viewer，并选一个 workspace root；每个链接是同一 origin 加 `?file=<path relative to that root>`，因此它们共享一个可浏览 catalog；该 root 外的 artifact 需要自己的 Viewer——用那个 root 再次启动（reuse-or-start 使其幂等）；单独链接无法到达。
28. 对于仅目录审查链接，返回不带 `?file=` 的 origin。
29. 除非用户要求，不要停止现有 Viewer 服务器。
30. 如果 Viewer 启动失败，报告失败，并继续使用 owning skill 的非 GUI 验证或 artifacts。
31. 需要支持文件类型、Viewer 控件或文件特定功能细节时，读 `references/viewer-features.md`。

适用边界 · 注意事项

• 不适用于修改、调试或迭代 CAD Viewer 源码本身；那是仓库的工作，本技能只运行 Viewer。
• 不适用于生成模型或运行模型脚本；Viewer 是静态可视化工具，不会运行脚本，生成必须先由 CAD 技能完成。
• 不适用于没有安装 cadgen 或无法本地绑定端口的沙箱环境；启动失败时应报告失败并走非 GUI 验证或 artifacts。