cad-viewer

CAD Viewer

来源：维护于 earthtojake/text-to-cad。
使用本地安装的技能文件作为运行时真实来源；
仓库链接仅用于来源和版本审查。

使用此技能在 CAD Viewer 中打开现有或新生成的 CAD、隐式 CAD、
机器人描述、DXF 或普通 FDM G-code 文件，并返回实时审查链接。
预期输入是一个或多个显式文件路径。

启动 Viewer

使用 npm run agent:start 启动或复用一个本地 CAD Viewer，
将绝对工件目录作为 --dir 传递。agent:start 启动器负责端口选择、
兼容服务器复用、目录激活以及 ?dir= 查询参数。
开发模式下的 Viewer 仅对匹配的 git 身份进行复用；
dist 包 Viewer 可以在 viewer 版本匹配时跨 git 分支复用。
它通过 Viewer 的轻量级目录激活 API 激活复用的服务器，
无需代理探测端口或手动触发目录扫描。
直接使用 agent:start 打印的 Viewer URL，然后仅添加
file= 查询值用于要审查的工件。

选择 --dir 为包含模型工件和 sidecar 文件的绝对目录，
通常是 <repo>/models 或消费项目的等效模型目录。
file= 值必须相对于该 --dir。
不要手动选择端口、探测服务器、重写 ?dir= 或启动单独的 Viewer 来切换目录。

从本技能目录运行：

npm --prefix scripts/viewer run agent:start -- --host 127.0.0.1 --dir <absolute-model-root>

使用打印的 Viewer URL 并附加 file=：

http://127.0.0.1:<printed-port>/?dir=/absolute/project/models&file=path/to/model.step

如果非 Viewer 进程或其他工作树的 Viewer 占用了候选端口，
启动器将自动继续。在沙盒代理环境中，
本地绑定或探测失败（如 EPERM 或 EACCES）是预期的；
使用所需的权限/提权重新运行相同的命令。

链接

• 在返回任何 file= 链接之前，解析 <dir>/<file> 并确认
  工件存在。传递生成的工件（例如 .step），而不是其生成源（例如 .py）。
  如果解析路径缺失，不要返回链接，而是报告问题并指向正确的生成工件路径。
• 每个请求的文件返回一个 Viewer URL。
• 每个绝对目录 --dir 启动/复用一次 Viewer，然后为每个请求的文件附加
  file=<path>。文件路径必须相对于 --dir。
• 对于仅目录的审查链接，返回 agent:start 打印的 URL，不添加 file=。
• 除非用户要求，否则不要停止现有的 Viewer 服务器。
• 如果 Viewer 启动失败，报告失败并继续使用所属技能的非 GUI 验证或工件。

Claude Preview

Viewer 端口是动态的——它在启动时选择，并且可能因工作树而异。
要与 Claude Preview 工具集成，请在 agent:start 命令中添加 --json：

npm --prefix scripts/viewer run agent:start -- --host 127.0.0.1 --dir <absolute-model-root> --json

启动器在人类可读行之后向 stdout 写入一行 JSON 结果。
通过取 stdout 中以 { 开头的最后一行来解析它：

{"url":"http://127.0.0.1:<port>/?dir=<absolute-model-root>","port":<port>,"action":"reuse"}

action 为 "reuse" 表示复用了现有服务器且立即可用，
或 "start" 表示已生成新服务器进程且可能仍在初始化。
对于 "start" 结果，在将 url 值传递给 Claude Preview 工具之前，
在基础 URL 上探测 GET /__cad/server（例如 http://127.0.0.1:<port>/__cad/server）
直到返回 HTTP 200。

参考

• 当用户要求修改、调试或迭代 CAD Viewer 源代码时，阅读 references/development.md。
• 当需要支持的文件类型、Viewer 控件或文件特定功能细节时，阅读 references/viewer-features.md。
• 仅当用户特别需要可选的 SRDF MoveIt2 IK 或路径规划控件时，阅读 references/moveit2-server.md。