前言¶
DeepSeek Harness（DSH）的動態插件運行在沙箱環境中，通常被限制直接發起網絡請求或使用 Node.js 的 require。html.run 需要通過特定的接口發佈 HTML 文件，無法直接通過標準的 ctx.web.fetch 調用。
dsh-htmlrun 插件通過 ctx.subprocess 調用零依賴的本地 CLI（htmlrun.cjs）來繞過沙箱限制。它將 html.run 的發佈能力封裝爲 DSH 模型可調用的工具，讓模型能夠在會話內直接將本地 HTML 文件轉換爲可分享的鏈接。
插件定位¶
- 名稱：dsh-htmlrun
- 作者：iwker
- 類型：DSH 模型工具插件（聯網工具類）
- 許可證：MIT
- 核心價值：將 html.run 的 CLI 發佈流程封裝爲模型工具，無需人工複製鏈接。
核心功能¶
該插件提供以下能力：
- CLI 封裝：調用項目自帶的
scripts/htmlrun.cjs執行具體操作，包括激活、發佈、更新、檢查狀態等。 - 模型工具集成：在 DSH 會話中註冊名爲
htmlrun的工具，模型可直接調用。 - 認證管理：無需爲 DSH 插件單獨配置 Key。html.run 的認證 Token 存儲在
~/.htmlrun/config中，與終端使用 CLI 保持一致。 - 支持的命令：
check：檢查登錄狀態，未激活時返回激活鏈接與二維碼。publish：發佈或更新 HTML 文件。bind：通過配對碼綁定設備。login/logout：手工配置或清除 Token。whoami：查看當前狀態。
安裝¶
推薦通過 GitHub 安裝，並鎖定 commit SHA 以確保版本一致。
dsh plugin --profile <name> add github:iwker/dsh-htmlrun#<commit-sha>
安裝後，插件會作爲組合包（bundle）加載到 DSH 配置中。
使用方法¶
工具參數¶
調用 htmlrun 工具時，需傳入以下參數：
| 參數 | 類型 | 說明 |
|---|---|---|
action |
string | 必填。執行動作：check, publish, bind, login, logout, whoami |
file |
string | publish 動作必填。HTML 文件的絕對路徑或相對於 workspace 的路徑 |
note |
string | publish 動作用。本次發佈的簡短說明（可選） |
forceNew |
boolean | publish 動作用。強制新建工件拿全新鏈接（默認同路徑自動更新，版本 +1） |
noInline |
boolean | publish 動作用。不內聯本地資源（默認自動內聯同級目錄文件） |
code |
string | bind 動作用。8 位配對碼 |
token |
string | login 動作用。html.run 的 publish token（h_ 開頭） |
cliPath |
string | 可選。覆蓋 htmlrun.cjs 的執行路徑 |
典型流程¶
- 檢查狀態：模型首先調用
action=check。若未激活，CLI 會輸出激活鏈接和二維碼，模型需將這些信息轉達給用戶；用戶確認後，再次check靜默通過。 - 發佈內容：模型調用
action=publish, file=<文件路徑>。 - 結果反饋：CLI 返回鏈接、版本號、敏感詞提示等信息，模型需將這些原始輸出轉達給用戶，而不是簡單的“發佈成功”。
常見操作示例¶
- 更新鏈接：修改完 HTML 內容後，對同一文件路徑再次調用
action=publish（不加forceNew），鏈接不變，版本號自動 +1。 - Token 管理：Token 明文不應出現在對話回覆或日誌中。
login時僅傳遞h_開頭的值，後續操作由 CLI 內部讀取配置。
限制與注意事項¶
- 單文件限制：僅支持單文件靜態 HTML。CSS/JS 需內聯或使用本地相對引用，圖片等資源由 CLI 自動處理。
- 環境要求：依賴 Node.js >= 16。
htmlrun.cjs爲零依賴，但需在插件進程或工作區中可用。 - 動態插件特性：動態插件形態是進程內臨時的。DSH 進程重啓後，需要重新加載插件（通過
cordis_define或重新安裝）。 - Token 位置：Token 存儲在
~/.htmlrun/config（權限 0600）。換機器或換路徑發佈會被視爲新工件。
生態與來源¶
本插件由 iwker 維護，遵循 MIT 許可證。
* 插件本體：作者編寫，MIT。
* Skill 源碼：原樣拷貝自 html.run 官方發佈的 skill v2.0.1（MIT），隨項目分發。
總結¶
dsh-htmlrun 解決了 DSH 沙箱環境下無法直接調用 html.run 發佈接口的問題。它通過複用成熟的 CLI 工具，爲模型提供了可靠的本地文件發佈能力，適合需要將生成的 HTML 頁面直接分享給用戶的場景。
