cad-viewer

CAD Viewer

来源：由 earthtojake/text-to-cad 维护。 请以已安装的本地技能文件作为运行时的权威依据；仓库链接仅用于追溯来源和审查发布版本。如果用户要求修改、调试或迭代 CAD Viewer 源码，那属于该仓库的工作，而非本技能的工作——本技能负责运行 Viewer，而不是编辑它。

使用此技能在 CAD Viewer 中打开现有或新生成的 CAD、机器人描述或 DXF 文件，并提供实时审阅链接。预期输入为一个或多个明确的文件路径。

设置

Viewer 是 cadgen 的一部分：将此技能的 requirements.txt 安装到 Python >= 3.11 环境中，cadgen 命令便会包含服务端和预构建客户端。无需安装其他内容，运行时也不需要 Node。

python -m pip install -r requirements.txt

cadgen doctor <this skill's directory> 可确认已安装的 cadgen 与发布此技能时所依据的版本一致。

启动 Viewer

启动命令始终会在最后输出一个指向启动目录中实时 Viewer 的 URL。如果该目录下已有运行中的实例，且磁盘上的 Viewer 代码相同（复用键为 realpath(directory) x 一个身份令牌——即 cadgen 版本，加上其 Python 运行时和精确构建的客户端的内容摘要，因此升级后的 Viewer 或不同的 --dist 绝不会返回过时实例），则会返回其 URL（"action": "reused"）；否则会从 3245 起使用第一个空闲端口启动新服务（"action": "started"）。切勿自行选择或推测端口——请读取命令输出的 URL。每个实例仅服务一个目录——即启动时所在的目录——且在进程存续期间固定不变。没有可用于指定目录的标志：cwd 就是服务目录。

基础端口 3245 的十六进制值为 0xCAD，也就是“CAD”。

cd /absolute/project/models && cadgen viewer --host 127.0.0.1 --json

（cadgen 必须是通过此技能的 requirements.txt 安装的版本。如果它不在 PATH 中，用该解释器运行 python -m cadgen.viewer 即可启动相同服务。）

请谨慎选择启动目录——这是最关键的一步。 cwd 决定目录目录会扫描哪些内容（项目根目录会把 node_modules、.git 和构建输出也纳入其中），也决定实例的复用键，因此从当前所在目录启动可能会返回一个服务于其他位置的 Viewer。请先 cd 到用户认定的模型工作区目录——通常是项目的 models/ 目录——再从那里启动。切勿从此技能的目录中启动：那样服务的是技能文件，而不是模型。

标志：--json 会输出机器可读的最后一行 stdout（{"url", "port", "action": "started"|"reused"}）——请始终传入该标志，并从输出中获取 URL。--new 会强制启动新实例，不复用现有实例。显式指定 --port <n> 表示严格使用该端口，否则失败，并会禁用复用和滚动分配。cadgen viewer --help 会列出其余选项。

URL 形式

页面是纯源站地址，file= 用于选择服务根目录中的一个构件：

http://127.0.0.1:3245/?file=gripper/STEP/gear_rack_gripper.step

file= 的值相对于服务目录。URL 中不会显示目录，因此同一个链接在不同实例中指向不同文件——根目录属于服务端，而非链接。

启动目录是工作区，不是文件所在文件夹。 Viewer 会递归扫描该目录，因此文件浏览器会列出其中的所有模型，用户无需新链接即可切换文件。从用户认为的模型工作区目录启动——通常是项目的 models/ 目录，或者要审核的文件的最近公共父目录——并将其余路径放在 file= 中。从构件所在的深层文件夹启动（cd .../models/gripper/STEP，?file=gear_rack_gripper.step）会打开同一个模型，但会隐藏项目的其余部分，这几乎从来不是用户想要的。

端口冲突不是你需要操心的事：启动器会切换到可用端口，打印出的 URL 才是准确信息。在沙盒化的 Agent 环境中，仍可能发生 EPERM/EACCES 等本地绑定失败；请使用所需权限或提升权限后重新运行。

cadgen viewer list 会显示所有正在运行的实例及其服务目录；cadgen viewer stop --port <n> 会结束其中一个实例。（两者都可以从任意位置运行——只有启动时才会用到当前工作目录。） 要查看当前根目录以外的目录，只需切换到该目录并再次启动——复用或启动机制会让第二次启动既快速又正确。

生成是 CAD 技能的职责；文档在 Viewer 中编译

Viewer 是静态可视化工具：它负责渲染已经存在的构件。生成的模型必须先运行其模型脚本来构建（参见 CAD 技能）；Viewer 不会运行脚本，也不会判断某个文档是否有脚本。

Viewer 中 .step/.stp 文档的状态有四种，仅根据文件字节和存储区确定：未编译（存储区中没有与这些字节对应的树——Viewer 会提供编译选项，并在打开时进行编译）、编译中 · n/total（cadgen 构建池中的某个任务正在生成一棵树，其输出包含此文档——无论是 Viewer 自身的编译、终端中的 python model.py，还是父任务的子构建）、已渲染或失败（最近一次针对该文档的任务失败；会显示错误消息）。 编译是提交到 cadgen 每个入口共用的构建池中的任务，因此进度和错误会作为数据返回。不存在“过时与源文件不一致”状态：文档是否落后于其脚本，应由 cadgen store why 判断，而非 Viewer。如果 Agent 正在完成相关工作，就无需先运行任何操作：直接使用该文件并返回链接即可。

链接

• 返回任何链接前，解析 <directory>/<file> 并确认其存在。传递 .step/.stp 工件本身，无论是生成的还是导入的。目录会列出工件，并按照其磁盘上的名称原样显示：moonwatch.step 在标签页、面包屑导航、目录行和文件选择器中都显示为 moonwatch.step，无论它是生成的还是导入的。Viewer 不会获知文档是否由生成得到：其状态仅属于工件一侧（未编译 / 正在编译 / 已渲染 / 失败），模型脚本也不会显示在 UI 的任何位置。生成模型的文档必须已存在（运行模型脚本）；存储中没有树结构的文档会在打开时根据其字节内容编译。如果解析出的路径不存在，请勿返回链接；请报告问题并指出正确路径。
• 每个请求的文件返回一个 Viewer URL。
• 每次会话只启动一次 Viewer，并选定一个工作区根目录。每个链接都是相同的源站加上 ?file=<path relative to that root>，因此它们共用一个可浏览的目录。根目录之外的工件需要使用独立的 Viewer——用该根目录重新启动（重复启动会复用现有实例，因此操作是幂等的）；仅凭链接无法访问它。
• 对于仅指向目录的审查链接，返回不带 ?file= 的源站地址。
• 除非用户提出要求，否则不要停止现有的 Viewer 服务。
• 如果 Viewer 启动失败，请报告失败情况，并继续使用所属技能的非 GUI 验证方式或工件。

参考资料

• 需要了解支持的文件类型、Viewer 控件或特定文件的功能详情时，请阅读 references/viewer-features.md。