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