DeepSeek Harness 插件：dsh-web-search-session-follow

前言¶

DeepSeek Harness (DSH) 内置的 web_search provider 将端点和凭据写死为官方 DeepSeek。如果用户配置了代理或使用第三方网关（如 OpenRouter、Zhipu AI），搜索功能会出现认证失败。dsh-web-search-session-follow 是一个 DSH web_search provider 插件，它读取当前会话路由的模型 provider，使用该 provider 的端点、凭据和协议方言完成搜索，并在未识别时回退至内置官方方案。

核心功能¶

• 运行时优先级链：每次搜索按优先级列表从上到下尝试，第一个成功的路由生效。支持特殊键 session 跟随当前会话路由。优先级可在 Web GUI 设置面板中实时调整并持久化。
• 会话跟随路由：通过 agents.currentInitiator().session.requestHeader().config 实时读取当前会话的 {provider, model}，不缓存、不猜测。
• 方言路由表：支持三种协议：
  • anthropic-web-search：Anthropic Messages + server tool web_search_20250305
  • openrouter-online：chat/completions + 服务端 web 插件，解析 url_citation 注释
  • zai-web-search：智谱 bigmodel Anthropic 兼容端点，web_search_prime 引擎，解析 tool_result 块的字符串化 JSON 内容
• 官方方案回退：优先级链全部失败时，回退至内置官方路由（同 @deepseek-ai/dsh-web-search-deepseek 默认值）。可通过 fallback: none 关闭回退。
• 设置 UI 面板：Web GUI 设置弹窗侧栏「Web 搜索」提供优先级排序、回退策略切换、单路由连通性测试（真实发起一次搜索）。
• 凭据分平面：解析顺序为字面 apiKey → credentials 服务（apiKeyEnv 引用）→ 环境变量。聊天 key 与搜索 key 各管各的。
• 模型跟随：路由未指定 model 时，anthropic 和 openrouter 方言使用会话当前模型，zai 方言固定使用路由模型。
• 调用审计：每次搜索追加一行 JSON 到 <DSH_HOME>/web-search-session-follow/audit.jsonl（包含 provider/endpoint/fallback/失败跳 attempts 标记，不含密钥）。

安装与启用¶

前置：已安装 DeepSeek Harness（developer preview，dsh web 命令可用）。

1、本地安装插件：

dsh plugin --profile web add /path/to/dsh-web-search-session-follow

2、在 profile 的 cordis.patch.yml 中覆盖搜索提供者配置：

- id: web
  config:
    searchProvider: session-follow

3、重启 dsh web 生效。如需回滚，删除上述覆盖段即可恢复内置行为。

配置示例¶

插件自带默认路由表，可在 cordis.patch.yml 或安装副本中调整。

config:
  priority: [zai-coding-cn, openrouter]
  fallback: official
  routes:
    zai-coding-cn:
      protocol: zai-web-search
      baseURL: https://open.bigmodel.cn/api/anthropic/v1
      apiKeyEnv: ZAI_CODING_CN_API_KEY
      model: glm-5.3-flash
    deepseek-official:
      protocol: anthropic-web-search
      baseURL: https://api.deepseek.com/anthropic/v1
      apiKeyEnv: DEEPSEEK_API_KEY
      model: deepseek-v4-flash
    openrouter:
      protocol: openrouter-online
      apiKeyEnv: OPENROUTER_API_KEY
      maxResults: 5

字段说明：
* priority：路由键数组，可包含 session。来源优先级：设置 UI 保存的 config.json > 插件 config 种子 > ["session"]。
* protocol：三选一（anthropic-web-search、openrouter-online、zai-web-search）。
* baseURL：anthropic/zai 方言自动追加 /messages，openrouter 方言追加 /chat/completions。
* apiKeyEnv / apiKey：凭据引用名 / 字面密钥（字面优先）。
* model：缺省跟随会话模型（zai 方言固定兜底 glm-5.3-flash）。

适用场景与注意事项¶

• 适用场景：使用自定义网关（如 OpenRouter、Zhipu AI）或代理的用户。插件允许按 provider 切换搜索端点和凭据。
• 会话日志安全：本插件绝不向会话日志写自定义事件类型。如果日志被污染（例如 v0.1.0 版本曾写入 web/session-follow-search-request 事件），会话可能无法从磁盘重开。修复方法：给对应事件行补 "ignorable":true，或等待上游提供 ignorable 机制。
• 成本：三种方言均计费为一次完整模型调用。
• 依赖：零运行时依赖。

结尾¶

该插件通过将搜索逻辑与会话路由解耦，解决了多网关环境下搜索功能不可用的问题。其可视化的设置面板和回退机制降低了配置门槛。更多细节可查阅插件目录或源码仓库。