前言¶

在 DeepSeek Harness（DSH）裏擴展智能體能力，常見做法是把新功能做成 harness 包再發布。每次小改動都要走打包與安裝流程，迭代成本高。另一方面，模型本身無法在中途持久化自己需要的工具——會話結束後，臨時能力就消失了。

dsh-custom-tool 針對這兩類問題：用戶在設置界面用 Monaco 編輯器編寫 JavaScript 工具，模型則通過 custom_tool_create / custom_tool_remove / custom_tools_list 自行增刪工具集。工具持久化存儲、熱註冊，下一步系統提示詞即可見。

這是什麼¶

• 插件名稱：dsh-custom-tool
• 維護者：omdsh-dev
• 分類：admin-security
• GitHub 星標：24
• 許可證：MIT
• 當前版本：v0.1.2

一句話定位：在 DSH 設置 UI 中創建與管理沙箱 JavaScript 工具，配備 Monaco 編輯器與模型驅動的工具生命週期。

核心功能¶

設置界面¶

設置頁新增 Custom Tool 分區（獨立導航圖標），支持列出、創建、編輯、啓用/禁用、刪除工具。模型創建的工具與工作區作用域的工具帶有標識。界面字符串跟隨 harness 語言偏好（中文/英文）切換。

Monaco 編輯器¶

使用 VS Code 引擎與 TypeScript 語言服務：args 根據參數 schema 自動補全類型，env 與沙箱全局變量有聲明，補全與診斷即時生效。編輯器與 TS worker 內聯打包，客戶端 bundle 爲單文件。

持久化與熱註冊¶

工具存儲在 custom-tools 設置命名空間（schema 默認值、組合基類、用戶文檔——普通 settings 分層）。編輯即時生效，重啓後恢復。啓用的工具在 settings 寫入提交時即註冊到 ctx.tools；禁用或刪除後立即註銷。Harness 自動將工具 schema 組裝進系統提示詞。

模型自助管理¶

三者與 UI 共用同一套校驗門控。模型創建的工具有 source: model 標記；用戶創建的爲 source: user，模型不得刪除後者。

創建 location: 'global' 的工具需用戶顯式批准（harness approval 彈窗）；location: 'workspace' 的工具可自主創建。

執行作用域與權限邊界¶

每個工具聲明兩種執行作用域之一：

workspace 作用域的路徑限制：

• 根目錄爲會話工作區目錄（發起 agent 的 cwd），調用時解析。
• 相對路徑從根目錄解析；絕對路徑不得越出根目錄。
• 無發起者上下文時返回 no workspace root，而非無邊界運行。
• 限制爲詞法級別（resolve + 前綴檢查）；工作區內符號鏈接仍可能指向外部——workspace 作用域面向可信代碼，不是對抗惡意宿主的全隔離沙箱。

存儲位置¶

兩個維度可自由組合：例如 location: global + scope: workspace 的工具，在任意工作區被調用時，其 fs 操作作用於調用方的工作區。

沙箱執行¶

每次調用在獨立的 worker 線程中執行，運行於 node:vm realm，配有顯式 allowlist、Node Permission Model 與硬性預算。Worker 不繼承環境變量，無配置範圍外的文件系統訪問，無子進程能力。

執行預算（兩種作用域均適用）：

• 每次調用一個 worker 線程，超時、中止或完成後終止。
• 牆鍾截止（timeoutMs）、堆上限（memoryLimitMb）、結果文本上限（maxResultChars）、代碼體積上限（maxCodeBytes）、存儲工具數上限（maxTools）。

安裝與啓用¶

dsh plugin --profile web add https://github.com/omdsh-dev/dsh-custom-tool/archive/refs/tags/v0.1.2.tar.gz
dsh web   # restart the server to pick the plugin up

包聲明 dsh.bundle.patch（掛載宿主插件）與 dsh.client（在 /plugins/dsh-custom-tool/client.js 提供瀏覽器端）。lib/ 已提交，GitHub tarball 安裝無需構建步驟。

Harness 要求：settings 命名空間須通過 WEB_SETTINGS_NAMESPACES allowlist 暴露給 web 配置客戶端（packages/host/apiproxy/src/api-proxy.ts 中需包含 'custom-tools' 字符串；上游 harness commit d6ea05b5 已添加）。缺失時 UI 可渲染但保存會被靜默拒絕（settings-not-exposed）。

典型用法¶

工具代碼契約¶

code 字段爲 async 函數體：async (args, env) => value。

// args 根據你聲明的參數 JSON Schema 自動類型化
const url = `https://api.example.com/weather?city=${encodeURIComponent(args.city)}`
const response = await fetch(url)
if (!response.ok) throw new Error(`upstream returned ${response.status}`)
return await response.json()

約定：

• 返回 JSON 值（string、number、boolean、null、array 或 plain object）；undefined 或非 JSON 值會導致調用失敗。
• 參數：對象根 JSON Schema，支持 harness 子集（type、properties、required、items、enum、const、oneOf、additionalProperties、description、title、default、examples）。
• 全局變量：fetch（allowNetwork: false 時禁用）、console、TextEncoder/TextDecoder、URL/URLSearchParams、atob/btoa、structuredClone、AbortController、setTimeout/setInterval 及對應 clear。env 爲 { tool, scope }；workspace 作用域額外提供 fs。

配置項¶

在 cordis.yml 的 dsh-custom-tool 條目下調整：

適用場景與注意¶

適合誰

• 需要在 DSH 中快速擴展智能體能力、又不想每次改動都打包 harness 的開發者。
• 希望模型在會話中按需創建並持久化工具的場景（如重複的數據處理、文件操作工作流）。
• 關注 admin-security 分類、需要明確權限邊界的部署環境。

注意事項

1. 插件以當前 dsh 進程權限運行；安裝前應檢查源碼與 MIT 許可證。
2. workspace 作用域的 fs 限制是詞法級別，不防符號鏈接逃逸；僅將可信代碼放入 workspace 工具。
3. 模型創建 global 位置工具需用戶批准；用戶創建的工具只能由用戶在設置 UI 刪除。
4. 默認 allowNetwork: true；若環境不允許工具訪問外網，應在配置中關閉。
5. Node 引擎要求：^22.19 || >=24。

結尾¶

dsh-custom-tool 把「擴展智能體」從打包發佈降爲設置表單：Monaco 編輯器寫工具、沙箱 worker 執行、模型通過 API 自助增刪。對於需要在 DSH 中靈活定製工具鏈的開發者，這是 admin-security 分類下較完整的方案之一。

• 目錄頁：https://www.skillhub.cn/plugins/omdsh-dev/dsh-custom-tool
• GitHub：https://github.com/omdsh-dev/dsh-custom-tool