DeepSeek Harness 插件：通过 SketchUp 2023 桥接驱动建模任务

前言¶

DeepSeek Harness（DSH）的核心理念是「一切皆插件」，通过扩展插件体系，开发者可以把各种专业工具接入到智能体工作流中。在 3D 建模领域，SketchUp 是常用的桌面软件，但原生没有面向 Agent 的接口。手动操作 SketchUp 会话效率低，且难以被脚本化。DSH 插件 dsh-su 提供了一个本地 TCP 桥接层，把 SketchUp 2023 的会话变成一组可被 Agent 调用的工具，让智能体可以直接驱动建模任务。

是什么¶

dsh-su 是一个 DSH 插件，维护者为 summersummer-liu。它通过一个本地 JSON-lines TCP 桥接，把 DSH Agent 与 SketchUp 2023 的 Ruby API 联通。插件会自动安装/更新配套的 SketchUp 扩展，并在首次使用时把扩展拷贝到 SketchUp 的 Plugins 目录。Agent 可以通过 8 个工具命令，在 SketchUp 会话中运行 Ruby 脚本、检查模型状态、保存 .skp 文件、截取视口图像等。插件内置了建模工具包 su_kit 和 sketchup-modeling 技能，方便快速搭建建模任务。

核心功能¶

8 个 Agent 工具¶

工具名	功能
`su_status`	检查桥接健康状态、当前活动模型、扩展版本、检测到的路径、提示信息
`su_install_extension`	把配套的 SketchUp 扩展拷贝/更新到 SketchUp 的 Plugins 目录
`su_ensure`	安装扩展、启动或复用 SketchUp 会话、等待桥接端口就绪、将单位设置为米
`su_run`	在 SketchUp 内部运行一个 `.rb` 任务脚本，返回 `$dsh_result` 变量
`su_eval`	在 SketchUp 内部求值一段 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")

Ruby 脚本与 su_kit¶

任务脚本运行在 SketchUp 的 Ruby 2.7 环境中，可以使用内置的 su_kit 工具包。示例：

require 'su_kit'

k = SuKit::Kit.new
k.reset                        # 清空模型，单位设为米
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。

桥接协议¶

Agent 与 SketchUp 之间的通信通过本地 TCP 127.0.0.1:47311 上的 JSON-lines 协议进行。每行是一个 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 版本信息。

自动化与安全¶

插件默认开启工作区限制，su_run/su_save/su_capture 只能在当前会话的工作区范围内操作，拒绝静默覆盖文件。插件也会检查是否有其他桥接正在运行，避免对同一文档进行冲突操作。SketchUp 2023 的一个已知行为是：在欢迎屏幕打开时 Ruby 插件不会被加载。插件通过启动一个模板 .skp 来规避这一问题，确保扩展能正常加载。

测试¶

测试分为三类：

不需要 SketchUp 的模块测试：node test/unit.mjs（检查模块形状、工具/技能注册、路径守卫）
需要 SketchUp 的集成测试：node test/integration.mjs（扩展安装、启动、运行、保存、截取、退出）
通过工具端到端测试：node test/tools-e2e.mjs（通过插件工具完成上述流程）

集成测试和工具端到端测试会在检测到其他桥接正在响应时拒绝运行，因此不会触碰你当前打开的文档；它们会启动并退出自己的 SketchUp 会话。可以通过环境变量 SU_EXE、SU_TEMPLATE、SU_PORT 覆盖检测路径。

安装与启用¶

1. 在 DSH 中添加插件¶

在 DeepSeek Harness 的桌面配置目录（~/.dsh/profiles/desktop）的 package.json 中添加依赖与 bundle：

{
  "dependencies": {
    "dsh-su": "link:D:/path/to/dsh-su"
  },
  "dsh.profile.bundles": ["dsh-su"]
}

使用 DSH 自带的 Node/pnpm 执行安装：

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

$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 或你自己的配置文件进行配置：

- id: su-modeling
  name: dsh-su
  config:
    sketchupExecutable: 'C:\Program Files\SketchUp\SketchUp 2023\SketchUp.exe'  # 可选
    templatePath: 'C:\Program Files\SketchUp\SketchUp 2023\Resources\en-US\Templates\Temp01a - Simple.skp'  # 可选
    pluginsDirectory: ''        # 默认：%APPDATA%\SketchUp\SketchUp 2023\SketchUp\Plugins
    host: '127.0.0.1'
    port: 47311
    timeoutMs: 180000           # 单次桥接命令超时
    launchTimeoutMs: 240000     # 启动 SketchUp 后等待桥接就绪
    maxOutputChars: 20000
    restrictToWorkspace: true   # su_run/su_save/su_capture 受工作区限制
    autoInstallExtension: true
    registerSkill: true

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

适用场景与注意¶

适合需要把 SketchUp 2023 建模任务嵌入到 DSH 智能体工作流中的场景。开发者可以在 Agent 中通过 su_run 调用 Ruby 脚本，使用 su_kit 快速构建模型、设置材质与相机，再用 su_save 或 su_capture 输出结果。

注意：插件以当前 DSH 进程的权限运行。安装前应检查源码与许可证（MIT）。如果需要更复杂的权限控制或网络化访问，建议自行 fork 并调整配置。

结尾¶

dsh-su 把 SketchUp 2023 的桌面会话变成了一组 Agent 工具，配合 su_kit 建模工具包，可以在 DSH 工作流中完成建模、保存与截图等任务。如果你正在构建面向 SketchUp 的智能体应用，可以参考目录页与 GitHub 仓库了解更多细节。

目录页：https://www.skillhub.cn/plugins/summersummer-liu/dsh-su
GitHub：https://github.com/summersummer-liu/dsh-su