Z.ai 联网搜索kenny2077/dsh-web-search-zai

DeepSeek Harness 网页搜索（Z.ai）

在 DeepSeek Harness 中使用 Z.ai 或智谱联网搜索，提供原生中英文设置卡片。明确选择 Coding Plan MCP 套餐额度或 REST API 余额；已有的 ZAI_API_KEY 若适用于所选服务，可直接复用。

CI
npm
License: MIT

0.2.0 新增： Coding Plan MCP 搜索、原生中英文设置卡片，以及明确的 Z.ai／智谱地址选项。继续支持 REST API 模式。

已有用户： 默认模式从 REST 改为 Coding Plan。要保留原来的 API 计费方式，请在升级后的第一次搜索前选择并保存 API — API 账户余额。详见从 0.1.0 升级。

0.2 带来的变化

- 两种计费模式。 默认使用 Coding Plan；API 模式保留原有 REST 请求、引擎和时间范围选项。不会自动回退到付费 API。
- 原生设置卡片。 在设置 → 网页搜索（Z.ai）中选择模式、管理密钥、选择 Z.ai 或智谱 MCP 地址。更改在下一次搜索时生效。
- 保持 DSH 接口。 提供方 ID zai、设置命名空间 web-search-zai 和模型使用的搜索工具均保持不变。
- 密钥由凭据服务管理。 密码框留空保留共享密钥；重置只清除搜索设置覆盖值，不删除密钥。

| 模式 | 消耗 | 适用情况 |
| --- | --- | --- |
| Coding Plan（coding-plan，默认） | 套餐 MCP 额度 | 密钥具有符合条件的 Coding Plan 订阅 |
| API（api） | 单独计费的 API 余额 | 使用 REST 搜索，或保留 0.1.0 的配置 |

即使没有聊天推理请求，搜索仍可能消耗额度。我们的智谱测试（2026 年 9 月）显示，每次搜索消耗 Coding Plan 滚动 5 小时额度池（每窗口 2,000 积分）中的 1 积分；REST API 模式下，每次搜索计费 ¥0.05 元。积分不是模型 token；以上为观测数据，不代表固定费率或额度承诺——请以当前 Z.ai 搜索文档、Z.ai 使用政策及智谱搜索文档为准。这是社区插件，社区目录收录不代表 DSH 或 Z.ai 官方背书。

安装与配置

需要 DeepSeek Harness 的 dsh CLI 和 Web 设置服务，以及 Node 22.19+（22 系列）或 Node 24+。请使用所选平台的原生密钥；不支持第三方聊天网关密钥。

将 npm 包安装到 web 配置环境：

dsh plugin --profile web add dsh-web-search-zai@latest
dsh web

仓库包含预构建 JavaScript，包管理器负责安装运行依赖，无需允许插件构建脚本。如果从 DSH 源码仓库运行，请在该仓库中将 dsh 替换为 pnpm dsh。

也可以安装 GitHub 最新版本：

dsh plugin --profile web add github:kenny2077/dsh-web-search-zai

打开 设置 → 网页搜索（Z.ai）：

1. 选择 Coding Plan — 套餐 MCP 额度或 API — API 账户余额。
2. 如果 DSH 已保存正确的 ZAI_API_KEY，密码框留空；否则输入密钥。替换共享密钥也会影响使用该凭据的聊天。
3. 智谱国内 Coding Plan 密钥：展开高级设置，点击使用智谱（中国）并保存。默认地址为 Z.ai 国际平台；密钥格式和界面语言不会自动决定地址。
4. 保存后，让 DSH 执行一次搜索。卡片显示的是已保存的模式，可能与尚未保存的选项不同。

安装本地源码目录

本地路径安装会链接到源码目录。注册前先安装插件依赖；每次拉取升级后，再运行一次 pnpm install --frozen-lockfile：

git clone https://github.com/kenny2077/dsh-web-search-zai.git
cd dsh-web-search-zai
pnpm install --frozen-lockfile
dsh plugin --profile web add .
dsh web

如果从 DSH 源码运行，先安装插件依赖，再到 DSH 仓库执行 pnpm dsh plugin --profile web add 。

从 0.1.0 升级

密钥、凭据引用名称、REST 地址、引擎和时间范围设置的含义保持不变。省略 billingMode 现在会选择 Coding Plan，包括 0.1.0 创建的配置。插件不会猜测订阅状态或自动替你迁移计费选择。

保留 REST API 计费

升级后，在卡片中选择 API — API 账户余额，并在搜索前保存。使用文件配置时，停止 DSH，将以下字段合并到 $DSH_HOME/settings.yaml 中现有的命名空间：

web-search-zai:
billingMode: api
保留已有的 apiKeyEnv、baseURL、searchEngine 和 searchRecency。

只合并该字段，不要覆盖整个设置文件。已有的 REST baseURL 或 ZAI_SEARCH_BASE_URL 不会自动选择 API 模式。

使用 Coding Plan

保存 Coding Plan，并选择与密钥签发平台对应的地址：

| 平台 | mcpURL |
| --- | --- |
| Z.ai 国际平台（默认） | https://api.z.ai/api/mcp/web_search_prime/mcp |
| 智谱国内平台 | https://open.bigmodel.cn/api/mcp/web_search_prime/mcp |

智谱示例：

web-search-zai:
billingMode: coding-plan
mcpURL: https://open.bigmodel.cn/api/mcp/web_search_prime/mcp
apiKeyEnv: ZAI_API_KEY

套餐额度耗尽或不符合条件时返回错误；只有用户主动选择 API 模式，才会使用 API 余额。

更新安装

停止 DSH，按安装来源执行更新，再重启 DSH 并刷新浏览器页面：

| 安装来源 | 更新方式 |
| --- | --- |
| npm | dsh plugin --profile web update dsh-web-search-zai --latest |
| GitHub | dsh plugin --profile web update dsh-web-search-zai --latest |
| 本地目录 | 在插件源码目录运行 git pull --ff-only，再运行 pnpm install --frozen-lockfile |

从 npm 切换到 GitHub 版本，执行上方 GitHub 安装命令即可。回退到旧版可执行 dsh plugin --profile web add dsh-web-search-zai@0.1.0 并重启；该版本始终使用 REST。共享密钥仍保存在 DSH 中。

设置参考

| 字段 | 默认值 | 用途 |
| --- | --- | --- |
| billingMode | coding-plan | coding-plan 或 api |
| mcpURL | 上方 Z.ai 国际地址 | 完整 MCP 地址，仅 Coding Plan 使用 |
| apiKeyEnv | ZAI_API_KEY | 每次搜索解析的 DSH 凭据引用 |
| apiKey | 未设置 | 可选明文密钥，优先于凭据服务中的密钥 |
| baseURL | https://api.z.ai/api/paas/v4 | 仅 REST 使用，追加 /web_search |
| searchEngine | search-prime | 仅 REST 使用；智谱使用 search_pro |
| searchRecency | 未设置 | 仅 REST 使用；day、week、month 或 year |

智谱 REST 使用 baseURL: https://open.bigmodel.cn/api/paas/v4 和 searchEngine: search_pro。MCP 使用独立的完整地址，不使用聊天地址或 REST 基础地址。

卡片通过 DSH 设置保存非密钥字段，仅通过 DSH 凭据服务写入密钥，不会将已保存的密钥读入浏览器。配置中的明文 apiKey 优先于凭据服务；卡片会提示该覆盖值，并禁用密钥编辑，直到移除明文配置。未挂载凭据服务时，提供方从启动环境读取指定凭据引用。

保存仅写入编辑过的字段，并检查设置版本。如果编辑期间设置发生变化，请放弃旧的编辑再重试。设置保存成功而密钥失败时，会单独报告；重新输入密钥即可重试。更改凭据引用名称后，请先保存，再输入对应密钥。

重置搜索设置仅清除卡片管理的非密钥用户覆盖值，恢复继承设置；没有组合配置覆盖时，模式恢复为默认 Coding Plan。共享密钥不变。主机设置或凭据服务不可用、只读时，相应控件会禁用。

常见问题

| 现象 | 检查方法 |
| --- | --- |
| Cannot find package '@modelcontextprotocol/sdk' | 本地链接安装时，在插件源码目录执行 pnpm install --frozen-lockfile，再重启 DSH。git pull 不会安装新依赖。 |
| 升级后搜索失败 | 检查已保存的模式。原 REST 用户需要明确选择 api。 |
| 认证或额度错误 | 检查密钥与 Z.ai／智谱地址是否匹配，以及所选模式的套餐额度或 API 余额。“已配置”只代表存在密钥，不代表认证成功。 |
| 没有新卡片 | 确认安装到 web 环境，重启 DSH 并刷新浏览器。旧版 0.1.0 没有此卡片，请升级到 0.2.0 或更新版本。 |
| 设置只读 | 使用支持可写设置与凭据的 DSH 主机连接；仍可使用文件配置。 |
| 结果少于请求数量 | 缺少 URL 或非空摘要的条目会被丢弃；最终数量由 DSH web 服务限制。 |

DSH 集成方式

DSH 模型 → web_search 工具 → ctx.web → zai 提供方
├─ coding-plan → MCP 搜索 → 套餐额度
└─ api → REST /web_search → API 余额
↓
来源链接、标题和摘要

插件注册到已有的 ctx.web 服务并返回来源，由聊天模型决定如何使用这些来源生成答案。插件不编造发布日期或生成答案，也不会启用模型提供方另行提供的聊天侧 web_search 选项。

MCP 每次搜索创建独立连接，结束后关闭。Coding Plan 操作整体限时 60 秒，支持调用方取消，并在插件卸载时取消。HTTP 重定向会被拒绝；搜索不会自动重试。错误保留 DSH 标准码：WEB_PROVIDER_ERROR、WEB_PROVIDER_CREDENTIAL_MISSING、WEB_ABORTED。

验证与开发

自动测试覆盖 REST 回归、本地 MCP JSON/SSE 服务、认证请求头、工具发现、额度错误、异常和双重编码响应、取消、超时、设置冲突、部分保存及浏览器包。CI 在 Windows 和 Ubuntu 上运行 Node 22、24 测试。

实时验证单独记录：智谱 Coding Plan 已通过直接调用和 DSH 注册后的 ctx.web 返回真实结果。维护者也在 Windows 的 DSH 中验证了插件，并在此前测试过 REST 模式。这些结果不保证其他账户或地址的额度可用性。

pnpm install --frozen-lockfile
pnpm typecheck
pnpm build
pnpm test

常规测试使用本地服务，不消耗搜索额度。实时测试需要 ZAI_API_KEY 和明确的 ZAI_LIVE_BILLING_MODE（coding-plan 或 api）；智谱请额外设置 ZAI_SEARCH_MCP_URL。每次运行 pnpm test:live 执行一次搜索。完整命令及发布检查见 CONTRIBUTING.md，变更见 CHANGELOG.md。

许可证

MIT