DeepSeek Harness 智譜 BigModel/GLM 供應商工具包

前言¶

DeepSeek Harness (DSH) 的核心理念是“一切皆插件”。在開發智能體時，接入智譜的 GLM 系列模型需要處理雙端點（Coding Plan 與普通 API）、思維層級映射以及本地密鑰管理等細節。該插件註冊了智譜 BigModel/GLM 家族作爲模型供應商路由，覆蓋了上述場景。

插件定位¶

zn-dk/dsh-zhipu-toolkit 是一個爲 DeepSeek Harness 提供智譜 BigModel/GLM 服務的工具包。它支持雙端點模型目錄（Coding Plan + 普通 API）、驗證的思維層級映射、實時模型發現以及 Web 設置卡片，旨在解決 GLM 模型接入時的配置與運維複雜度問題。

核心功能¶

插件提供以下核心能力：

端點選擇：在 Coding Plan 端點 (zai) 和普通 OpenAPI 端點 (zhipu) 之間切換，兩者使用相同的模型列表和請求語義，差異僅在於計費方式。
自維護目錄：提供完整的 GLM 聊天家族目錄（從 GLM-4.5 到 GLM-5.3-Flash），包含經過驗證的上下文窗口和輸出上限。
原生多模態：支持 glm-5.3-flash 的原生多模態能力（圖像輸入已啓用）。
用量與配額：提供通往官方控制台的深度鏈接，用於查看用量和限制。
思維層級驗證：針對 GLM-5.3 系列模型進行了思維語義驗證，確保請求格式正確。
實時模型發現：啓動和設置變更後輪詢端點 /models，動態更新可用模型列表。
本地 API 密鑰：支持在 Web 設置卡片中本地持有密鑰，而非僅依賴環境變量。
Web 設置卡片：提供可視化的 Web GUI 進行配置。
雙語 UI：界面跟隨宿主語言服務（zh-CN / en）。

安裝與啓用¶

通過官方命令行安裝插件：

dsh plugin --profile web add dsh-zhipu-toolkit

如果在開發過程中需要從本地安裝打包後的文件，可執行：

npm pack
dsh plugin --profile web add ./dsh-zhipu-toolkit-<version>.tgz

安裝完成後，必須重啓 dsh web。DSH 會在啓動時組裝客戶端包和宿主插件樹，重啓後才能生效。

配置與使用¶

插件使用 zhipu-toolkit 作爲設置命名空間。

配置項¶

在 ~/.dsh/settings.yaml 中配置以下關鍵字段：

zhipu-toolkit:
  endpoints: coding         # coding | paas (二選一)
  codingApiKeyEnv: BIGMODEL_API_KEY
  paasApiKeyEnv: ZHIPU_API_KEY
  displayName: BigModel
  defaultReasoningTier: low # low | medium | high | xhigh | max
  useLocalApiKey: false     # true = 在卡片上持有密鑰

API 密鑰配置¶

提供兩種方式供密鑰存儲：

環境變量引用（默認）：通過憑證服務存儲環境變量引用，例如：

    dsh credentials set BIGMODEL_API_KEY

本地密鑰（Web 卡片）：在 Web 設置卡片中開啓 useLocalApiKey，並將密鑰粘貼到密碼字段。密鑰存儲在 DSH 憑證存儲中（鍵爲 ZHIPU_TOOLKIT_API_KEY），顯示爲掩碼摘要，支持即時編輯或清除。

典型用法¶

安裝插件並重啓 dsh web。
使用 dsh credentials set BIGMODEL_API_KEY 設置環境變量密鑰，或在 Web 設置卡片中配置本地密鑰。
在模型選擇器中選擇對應的 GLM 模型（如 glm-5.3-flash）。
在請求中設置 reasoning_effort（默認爲 low）。

注意事項¶

重啓要求：安裝插件後必須重啓 dsh web。插件對路由的修改會在提交寫入後重新解析，無需重啓。
思維層級限制：GLM-5.3 系列模型不能關閉思維。API 會拒絕 thinking: disabled（錯誤代碼 1210）。插件已將 off 和 minimal 從選擇器中移除，並映射 low/medium/high 到 high，xhigh/max 到 max。
模型發現機制：模型選擇器會根據端點的 /models 報告進行實時過濾。如果端點停止提供某模型，該模型會從選擇器中消失。只有直接驗證的模型（如 glm-5.3）能容忍端點延遲。
只讀狀態：如果部署的設置文檔是隻讀的（例如託管配置），Web 設置卡片可能顯示爲只讀。此時應編輯編排入口而非直接編輯卡片。

結尾¶

該插件爲 DSH 用戶提供了標準化的智譜模型接入方案，解決了雙端點切換、思維語義適配和多模態支持的痛點。更多細節與源碼可查閱其 GitHub 倉庫。