---
id: gh-cad-viewer
name: "cad-viewer"
url: https://skills.yangsir.net/skill/gh-cad-viewer
author: earthtojake
domain: hardware
tags: ["cad", "viewer", "3d-model", "design-review", "gcode"]
install_count: 9000
rating: 4.50 (120 reviews)
github: https://github.com/earthtojake/text-to-cad/tree/main/plugins/cad/skills/cad-viewer
---

# cad-viewer

> 此技能用于启动或重用 CAD Viewer，并为 CAD、隐式 CAD、机器人描述和 G-code 文件提供审查链接。它支持多种文件格式，方便用户对设计文件进行可视化审查，尤其适用于从 CAD 生成技能接收的文件，显著提升设计协作和验证效率。

**Stats**: 9,000 installs · 4.5/5 (120 reviews)

## Before / After 对比

### CAD 模型审查效率

**Before**:

在没有这个技能之前，开发者需要手动导出 CAD 模型，上传到共享平台，并指导审阅者下载和安装兼容的查看器，整个过程耗时且容易出错，导致审查周期延长。

**After**:

此技能能够快速启动 CAD Viewer 并生成可直接访问的审查链接，审阅者只需点击链接即可查看模型，极大地简化了审查流程，缩短了反馈周期。

| Metric | Before | After | Change |
|---|---|---|---|
| 审查链接生成时间 | 30分钟 | 1分钟 | -97% |

## Readme

# CAD Viewer

Provenance: maintained in [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad).
Use the installed local skill files as the runtime source of truth; the
repository link is only for provenance and release review.

Use this skill to open existing or newly generated CAD, implicit CAD,
robot-description, DXF, or plain FDM G-code files in CAD Viewer and hand back
live review links. The expected input is one or more explicit file paths.

## Start Viewer

Start or reuse one local CAD Viewer with `npm run agent:start`, passing the
absolute artifact directory as `--dir`. The `agent:start` launcher owns port
selection, compatible-server reuse, directory activation, and the `?dir=` query
parameter. It activates reused servers through the Viewer's lightweight
directory activation API, without requiring agents to probe ports or trigger
catalog scans manually. Use the Viewer URL printed by `agent:start` as-is, then
add only a `file=` query value for the artifact you want to review.

Choose `--dir` as the absolute directory that contains the model
artifacts and sidecars, commonly `<repo>/models` or the consuming project's
equivalent model directory. The `file=` value must be relative to that `--dir`.
Do not manually choose ports, probe servers, rewrite `?dir=`, or start a
separate Viewer just to change directories.

Always start new local Viewer servers with `--shutdown-after 12h` so forgotten
review servers clean themselves up. Do not rely on a default shutdown; the
server stays alive until stopped unless this flag or `VIEWER_SERVER_LIFETIME_MS`
is set.

Run from this skill directory:

```bash
npm --prefix scripts/viewer run agent:start -- --host 127.0.0.1 --dir <absolute-model-root> --shutdown-after 12h
```

Use the printed Viewer URL and append `file=`:

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

If a non-Viewer process or another worktree's Viewer occupies the candidate
port, the launcher will continue automatically. In sandboxed agent environments,
local binding or probe failures such as `EPERM` or `EACCES` can be expected;
rerun the same command with the needed permission/escalation.

## Links

- Return one Viewer URL per requested file.
- Start/reuse the Viewer once per absolute directory `--dir`, then append
  `file=<path>` for each requested file. The file path must be relative to
  `--dir`.
- For directory-only review links, return the URL printed by `agent:start`
  without adding `file=`.
- Do not stop an existing Viewer server unless the user asks.
- If Viewer startup fails, report the failure and continue with the owning skill's non-GUI validation or artifacts.

## References

- Read `references/development.md` when the user asks to modify, debug, or
  iterate on CAD Viewer source.
- Read `references/viewer-features.md` when you need supported file types, Viewer controls, or file-specific feature details.
- Read `references/moveit2-server.md` only when the user specifically needs optional SRDF MoveIt2 IK or path-planning controls.


---
*Source: https://skills.yangsir.net/skill/gh-cad-viewer*
*Markdown mirror: https://skills.yangsir.net/api/skill/gh-cad-viewer/markdown*