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 仓库。