viewer

name	viewer
description	多引擎网页预览(STEP/STL/GLB/URDF/G-code/DXF 实跑;PCB/SCH/SIM 占位 P3)。一句话起 server,后缀决定引擎。

viewer — 多引擎网页预览

一句话起 server,后缀决定引擎。CAD 实跑(Three.js),PCB / SCH / SIM 占位待 P3 落地。

用法

bash skills/viewer/scripts/start.sh /abs/path/to/<file> [workspace_root]
# stdout 唯一一行: http://127.0.0.1:<port>/?engine=<cad|pcb|sch|sim>&dir=...&file=...

from web_preview import start, snapshot
url = start("/abs/path/to/hip_bracket.step")          # 拿 URL 直接打开
res = snapshot("/abs/path/to/hip_bracket.step")        # 无浏览器时降级出图,见 headless-fallback.md
# res = {"tier":1|2|3, "kind":"url"|"png"|"json", "path":..., "fallback_reason":..., "duration_ms":...}

snapshot(mode=auto) 三档降级(P1-5 已落地):Tier 1 chromium 截图 → Tier 2 OCP/VTK PNG → Tier 3 dimensions JSON,逐级回落不静默。CLI:python web_preview.py --mode=auto|web|snapshot|probe <file>。

后缀路由表(33 后缀 / 21 条目权威表见 scripts/backend/router.mjs)

后缀	引擎	状态
.step .stp .brep .stl .glb .gltf .3mf	cad	ready
.iges .igs .obj	cad	P1
.fcstd	cad	P3(需 FreeCAD CLI)
.urdf .srdf .sdf	cad	ready
.gcode .nc	cad	ready(toolpath ribbon)
.dxf	cad	ready(2D)
.png .jpg .jpeg .webp	cad	ready(inline <img>)
.kicad_pcb .gbr .ger .drl .gtl .gbl	pcb	stub(P3)
.kicad_sch .sch .svg	sch	stub(P3)
.csv .mp4 .webm	sim	stub(P3)
.json	ambiguous	需 ?engine=sim 显式透传(否则 server 回 409)

扩支持新格式 = scripts/backend/router.mjs 加一行 + scripts/engines/<name>/ 放静态文件。

URL 协议(对外稳定接口)

http://127.0.0.1:<port>/?engine=<cad|pcb|sch|sim>&dir=<abs-dir>&file=<rel-file>

完整字段约束 + 安全规则见 references/url-protocol.md。跨子技能改动须在 shared/dependencies.md 同步。

启动行为

• 默认端口 4178(沿用 cad-viewer);冲突时跳 4188-4197,共 20 候选。
• 复用判定:GET /__cad/server → app="build123d-cad/viewer" + serverApiVersion>=2 + workspaceRoot 一致 + git 一致。
• shutdown:默认 --shutdown-after 12h,每请求重置;POST /__cad/shutdown 优雅关停(仅 127.0.0.1)。
• 仅监听 127.0.0.1,不绑公网。

退出码(start.sh)

0 成功 / 2 后缀不支持或参数错 / 3 文件不存在 / 4 端口分配失败

安全约束

• ?dir 必须在 --workspace-root 内,否则 403
• ?file 防 .. 穿越,否则 403
• 文件代理白名单:路由表所有后缀 + .json/.yaml/.yml,其它 415

测试

cd skills/viewer && pytest tests/ -v

CI 必跑(无浏览器,~9s):test_routing / test_url_assembly / test_placeholders 本地必跑(起 server):test_start / test_server_reuse / test_cad_engine P1-5 降级链:test_headless_fallback(纯逻辑 CI 必跑 / 真渲染缺 OCP·vtk 时 skip) P3 待落地:test_{pcb,sch,sim}_engine.py(skip)

子页面索引

• references/url-protocol.md — URL 协议字段约束 + 安全
• references/routing.md — 路由表(扩展核心)
• references/server-reuse.md — 端口/pid/git/workspace 复用规则
• references/cad-engine.md — Three.js + 各 loader 集成
• references/headless-fallback.md — P1-5 ✅:snapshot() 三档降级链(chromium URL → OCP/VTK PNG → dimensions JSON)
• references/viewer-features.md moveit2-server.md — 复刻 cad-viewer 细节
• references/pcb-engine.md sch-engine.md sim-engine.md — P3 路线

不集成

• 实时 ROS 数据流 / PCB 编辑器 / FEA 应力云图 / 公网部署 / 用户权限
• 详见 docs/superpowers/specs/03-viewer.md §13