SketchUp 桥接 summersummer-liu/dsh-su

dsh-su — DeepSeek Harness 的 SketchUp 桥接

一个 DeepSeek Harness（DSH）插件，把常驻的 SketchUp Pro 会话变成智能体工具：跑 Ruby 任务脚本、查模型、存 .skp 文件、截视口图——全部走本地 JSON-lines TCP 桥接，配套的 SketchUp 扩展自动安装、自动更新。

一个把 SketchUp 2023 接入 DeepSeek Harness 的插件：DSH 智能体可以直接驱动一个常驻的 SketchUp 会话（跑 Ruby 脚本、查模型、存 .skp、截图），配套的 SketchUp 扩展由插件自动安装/更新。

screenshot

功能

- 8 个智能体工具 — su_status、su_install_extension、su_ensure、su_run、 su_eval、su_save、su_capture、su_stop。
- 常驻 SketchUp 会话 — 启动一次，之后每个任务只走一趟短桥接往返（通常 10–100 ms），不用重启应用。
- 自带 SketchUp 扩展 — 首次使用时装进 Plugins\ （也提供 .rbz 包）；扩展自动启动桥接，并添加 Extensions → DSH Bridge 菜单（状态 / 日志 / 重启）。
- 内置米制建模工具包 — 任务脚本 require 'su_kit' 即可用盒子、圆柱、拉伸、标签、材质、相机、截图和校验辅助函数（输入米，输出米）。
- 内置技能 sketchup-modeling — 工作流 + SketchUp 2023 / Ruby 2.7 踩坑指南。
- 默认安全 — 工具限定在工作区内，拒绝静默覆盖，也拒绝在另一个桥接已在运行时重置文档。

架构

DSH plugin (this package) SketchUp 2023 extension (bundled)
┌──────────────────────────────┐ TCP 47311 ┌────────────────────────────────────┐
│ index.js (8 tools) │ JSON lines │ dsh_su_bridge.rb (extension loader)│
│ lib/su-bridge.js │ ───────────▶ │ └─ dsh_su_bridge/server.rb │
│ lib/sketchup-extension.js │ ◀─────────── │ (TCP server on main thread) │
└──────────────────────────────┘ ok/result │ └─ dsh_su_bridge/su_kit.rb │
│ installs extension ─────────────────┐ └────────────────────────────────────┘
│ %APPDATA%\SketchUp\SketchUp 2023\ │
│ SketchUp\Plugins\ │ bridge data/logs:
└─────────────────────────────────────┘ %LOCALAPPDATA%\dsh-su\

SketchUp 的 Ruby API 是单线程的：socket 线程只做 I/O，模型命令通过 UI.start_timer 排到主线程执行。扩展还处理了 SketchUp 2023 的一个怪癖——欢迎界面开着时 Ruby 插件不会加载——所以插件启动 SketchUp 时带一个模板 .skp。

环境要求

- Windows 10/11
- SketchUp Pro 2023（开发和测试用 23.1.315，Ruby 2.7.7）
- DeepSeek Harness，带桌面配置档（~/.dsh/profiles/desktop）
- Node.js ≥ 22.12（DSH 自带）

安装

1. 添加 DSH 插件

$profile = "$env:USERPROFILE\.dsh\profiles\desktop"

In $profile/package.json:
dependencies += "dsh-su": "link:D:/path/to/dsh-su" (link: = live link, recommended)
or "dsh-su": "file:D:/path/to/dsh-su"
dsh.profile.bundles += "dsh-su"

Install with the Node/pnpm bundled with DSH:
$node = "$env:USERPROFILE\.dsh\dsh-runtimes\dsh-primary-runtime\dependencies\node\bin\node.exe"
$pnpm = "$env:USERPROFILE\.dsh\dsh-runtimes\dsh-primary-runtime\dependencies\pnpm\bin\pnpm.mjs"
Set-Location $profile
& $node $pnpm install --prefer-offline

重启 DeepSeek Harness。上面列出的工具会出现在工具集里，sketchup-modeling 技能也会完成注册。

2. SketchUp 侧（自动）

无需操作：su_ensure / su_install_extension 会把随包附带的扩展复制到 %APPDATA%\SketchUp\SketchUp 2023\SketchUp\Plugins\，版本变化时自动更新。已经打开的 SketchUp 实例必须重启一次，扩展才会加载。

手动替代方案：通过 Extension Manager 安装 dist/dsh-su-sketchup-<version>.rbz。用 python scripts/build-artifacts.py 构建它。

配置

通过插件的 cordis.patch.yml 或你的配置档 cordis.patch.yml 配置：

- id: su-modeling
name: dsh-su
config:
sketchupExecutable: 'C:\Program Files\SketchUp\SketchUp 2023\SketchUp.exe' # optional
templatePath: 'C:\Program Files\SketchUp\SketchUp 2023\Resources\en-US\Templates\Temp01a - Simple.skp' # optional
pluginsDirectory: '' # default: %APPDATA%\SketchUp\SketchUp 2023\SketchUp\Plugins
host: '127.0.0.1'
port: 47311
timeoutMs: 180000 # per bridge command
launchTimeoutMs: 240000 # wait for the bridge after launching SketchUp
maxOutputChars: 20000
restrictToWorkspace: true # su_run/su_save/su_capture stay inside the session workspace
autoInstallExtension: true
registerSkill: true

sketchupExecutable 和 templatePath 都是可选项：插件会探测常见安装位置（Program Files、D:\su、SU_EXE / SU_TEMPLATE 环境变量），并在 su_status 里报告探测结果。

工具

| 工具 | 作用 |
| su_status | 桥接健康状态、当前模型、扩展版本、探测到的路径、提示 |
| su_install_extension | 在 Plugins\ 中复制/更新 SketchUp 扩展 |
| su_ensure | 安装扩展，复用或启动 SketchUp，等待端口就绪，把单位设为米 |
| su_run | 在 SketchUp 内运行 .rb 任务脚本；返回 $dsh_result |
| su_eval | 执行一段 Ruby 代码；返回 $dsh_result |
| su_save | 把文档保存为 .skp（限制在工作区内，不静默覆盖） |
| su_capture | 写出视口 PNG（限制在工作区内，不静默覆盖） |
| su_stop | 退出持有桥接的 SketchUp 实例 |

典型流程：

su_status
su_ensure
su_run(script: "tasks/build_model.rb", args: { out: "deliver/model.skp" })
su_capture(output_path: "qa/hero.png", width: 1600, height: 1100)
用 read_image("qa/hero.png") 实际查看结果
su_save(output_path: "deliver/model.skp")

任务脚本在 SketchUp（Ruby 2.7）里运行，可以用自带的 kit：

require 'su_kit'

k = SuKit::Kit.new
k.reset # empty model, metres
k.tag('01-SOLID', 'C8BFA8')
k.box([0, 0, 0], 1.2, 1.2, 2.0, tag: '01-SOLID')
k.material('MAT-A', 'C8BFA8')
k.camera([3, -3, 2], [0.6, 0.6, 1.0], lens: 50)
k.zoom_extents
k.capture('preview.png', 1600, 1000)
$dsh_result = { 'counts' => k.counts, 'bbox_m' => k.bbox_m, 'summary' => k.summary }

su_kit API：reset units tag use_tag box cylinder polygon_extrude polyline arc_2d group erase_all smooth_curves material paint camera zoom_extents dolly_out capture bbox_m counts summary save export，另有辅助方法 Chrono box_f seg_box_f cyl_f sphere_f glass_f edge_hide! text3d white_studio! shadow_setup! frame_view! sanity_bounds!
deep_counts。

协议

通过 TCP（127.0.0.1:47311）传输，每行一个 JSON 对象：

{"id":"a1","cmd":"run","script":"C:/abs/task.rb","args":{}}
{"id":"a1","ok":true,"result":{"script":"...","elapsed_ms":53.4,"result":{}}}
{"id":"a2","ok":false,"error":"RuntimeError: ...","backtrace":[]}

命令：ping info setup reset run eval save capture open new reload quit。
扩展日志在 %LOCALAPPDATA%\dsh-su\logs\bridge.log；ready.json 记录当前端口和 SketchUp/Ruby 版本。

测试

no SketchUp needed: module shape, tool/skill registration, path guards
node test/unit.mjs

real SketchUp: extension install, launch, run, save, capture, quit
node test/integration.mjs

the same but through the actual plugin tools (needs SketchUp)
node test/tools-e2e.mjs

test/integration.mjs 和 test/tools-e2e.mjs 在另一个 bridge 正在应答时拒绝运行，所以绝不会碰你打开的文档；它们会启动并退出自己的 SketchUp 实例。设置 SU_EXE / SU_TEMPLATE / SU_PORT 可覆盖自动检测。

构建产物

python scripts/build-artifacts.py
dist/dsh-su-sketchup-<version>.rbz SketchUp extension (Extension Manager)
dist/dsh-su-<version>.zip DSH plugin package

scripts/build-artifacts.py 把扩展打包成 .rbz，把插件打包成 zip。扩展的 Ruby 文件已提交，所以构建是可选的。

仓库结构

dsh-su/
index.js DSH plugin entry (tools + skill registration)
cordis.patch.yml bundle registration
lib/su-bridge.js TCP JSON-lines client
lib/sketchup-extension.js extension install, path detection, launch/wait
sketchup/dsh_su_bridge.rb SketchUp extension loader
sketchup/dsh_su_bridge/ main.rb / server.rb / su_kit.rb / VERSION
skills/sketchup-modeling/ bundled agent skill
scripts/ build helpers
test/ unit + integration + end-to-end tests

卸载

1. DSH：从配置档 dependencies 和 dsh.profile.bundles 中移除 dsh-su，运行 pnpm install，重启 DSH。
2. SketchUp：在 Extension Manager 中卸载 DSH Bridge (SU + DSH)，或删除 Plugins\dsh_su_bridge.rb 和 Plugins\dsh_su_bridge\。
3. 可选：删除 %LOCALAPPDATA%\dsh-su\。

限制

- 每台机器只能有一个桥接：一个 SketchUp 实例占用端口 47311；其他实例要接管，必须重启。su_ensure 会报告它何时启动了新实例。
- 只测试过 SketchUp 2023（Ruby 2.7）。更新的 SketchUp 版本应该大多能用，但未经验证。
- 桥接只在本机运行（127.0.0.1），没有身份验证：请把它当作同一用户运行的开发工具。

许可证

MIT — 见 LICENSE。