DeepSeek Harness 自定義工具工作室（DSH Custom Tool Studio）

前言¶

DeepSeek Harness（DSH）的設計理念是「一切皆插件」。開發者可以在不重啓 DSH 的情況下，通過插件動態擴展工具集。其中，dsh-custom-tool-studio 插件允許你在 DSH 環境中編寫並運行 Python 工具：它們會以「第一類 DSH 工具」的身份註冊，模型可以直接調用，且數據僅存儲在本地。

插件定位¶

名稱：dsh-custom-tool-studio（DSH Custom Tool Studio）
維護者：xtt-xt
分類：工作流
倉庫：https://github.com/xtt-xt/dsh-custom-tool-studio
許可證：MIT
當前版本：1.1.0（README）

插件通過 DSH bundle 插件機制提供，支持在 Web UI 與 AI 側兩種入口管理 Python 工具，並提供危險工具審批、工具包分組與延遲加載等能力。

核心功能¶

1. 創建與即時註冊¶

在 Web UI 的「自定義工具」頁面或通過 AI 的 custom_tool_manage 工具，起一個工具名、寫描述、參數 JSON Schema 與 Python 代碼。
保存/啓用/改名/刪除後，DSH 會立即對賬並註冊或註銷工具，無需重啓 DSH。
所有工具數據存儲在本地 %DSH_HOME%\custom-tools\tools.json，不會上傳。

2. 試運行¶

Web UI 的「測試」對話框可填 args JSON 並直接運行，查看結果、stdout、stderr 與耗時。
AI 通過 custom_tool_manage 的 action="test" 也可試運行。

3. 危險工具與內置審批¶

在編輯對話框中開啓「危險工具」開關，或 AI 側傳入 dangerous: true，該工具每次執行前都會觸發 DSH 內置審批界面。
危險工具執行審批與 DSH 內置的自動審查（@deepseek-ai/dsh-experimental-auto-review）兼容。
非危險工具不會觸發審批。
管理操作（創建、修改、刪除）可通過頁面「設置」中的開關讓 AI 操作也走審批，刪除默認開啓審批。

4. 工具包（分組）¶

工具包用於將多個工具歸到同一分組，支持一鍵啓停整包。
包內工具仍各自注冊爲獨立的 DSH 工具，僅做分組與整包開關。
工具包支持「始終解鎖」與成員管理。

5. AI 主動解鎖模式（延遲加載）¶

頁面「設置」中開啓「AI 主動解鎖模式」後，每個對話初始只可見兩個工具：custom_tool_manage 與 custom_tool_unlock。
AI 通過 custom_tool_unlock 的 action="unlock" 解鎖指定包後，包內啓用工具在下一輪請求中可見。
解鎖狀態按會話 ID 記錄在 unlocks.json 中，不同對話獨立。
支持包的「始終解鎖」與未分組工具單獨解鎖。

Python 工具約定¶

入口函數¶

def run(args):
    ...

必須定義 def run(args):；頁面與 AI 側會校驗。
args 由模型按參數 JSON Schema 傳入，爲普通 Python dict。
返回值必須是可 JSON 序列化的值（dict/list/str/數字/bool/None）。
print() / sys.stdout 作爲日誌通道（最多保留末尾 8,000 字符）。
sys.stderr 的內容進入 stderr；拋出的異常抓爲 error。
結果 JSON 超過 20,000 字符會被截斷。
腳本在獨立 Python 進程中執行，工作目錄爲 DSH 進程當前目錄。

超時與解釋器¶

默認超時 60 秒；可通過環境變量 DSH_CUSTOM_TOOL_TIMEOUT_MS 調整（毫秒），改完重啓 DSH。
解釋器探測順序：DSH_CUSTOM_TOOL_PYTHON（完整路徑）→ python → python3 → py -3。

參數 JSON Schema¶

參數根節點必須是 JSON 對象：

{
  "type": "object",
  "properties": {
    "text": { "type": "string", "description": "要統計的文本" },
    "limit": { "type": "integer", "description": "最多返回幾行" }
  },
  "required": ["text"]
}

description 寫給模型看。
required 列出必填參數。
無參數時填 {"type": "object", "properties": {}}。

工具命名規則¶

規則：^[a-z][a-z0-9_]{1,47}$（小寫字母開頭，長度 2–48，僅含小寫字母/數字/下劃線）。
run_code 爲 DSH 保留名，不可使用。
不能與內置工具或其它插件已註冊的工具重名。

AI 側管理工具 `custom_tool_manage`¶

模型可直接調用 custom_tool_manage 完成管理操作，與 Web UI 共用同一套邏輯。常用 action 與參數如下：

list：列出所有自定義工具（含啓用/危險狀態與工具包名）。
get：查看某個工具的完整定義（含代碼與所屬包）。
create：新建並註冊工具（必填：name、description、code）。
update：修改已有工具（必填：name + 至少一個字段）。
delete：刪除工具（同時從 DSH 註銷）。
set_enabled：啓用/停用工具。
test：用給定參數試運行一次。
pack_list：列出工具包及成員。
pack_get：查看一個工具包的成員與描述。
pack_create：新建工具包（必填：name；可選：description、tools、alwaysUnlocked）。
pack_update：改包描述/成員/改名/始終解鎖（必填：pack + 至少一項）。
pack_delete：刪除工具包（工具保留，變未分組）。
pack_set_enabled：一鍵啓停整包。

適用場景與注意¶

適合在 DSH 中需要運行本地 Python 腳本、擴展工具集的場景。
插件以當前 DSH 進程權限運行 Python 腳本，危險操作需通過「危險工具」開關與內置審批進行控制。
安裝前建議檢查倉庫源碼與許可證（MIT）。
所有工具數據存儲在本地 %DSH_HOME%\custom-tools，可整體備份與遷移。

總結¶

DSH Custom Tool Studio 讓開發者能夠用 Python 快速擴展 DSH 的工具能力，並利用內置審批與工具包機制控制風險與組織結構。通過 Web UI 或 AI 側工具，即可創建、管理並運行自定義工具，無需重啓 DSH。更多細節可參見插件目錄頁與 GitHub 倉庫。