dsh-web-search-session-follow

September 5, 2026 · View on GitHub

A DSH web_search provider that follows the conversation's routed model — per-provider endpoint, credential, and wire dialect.

每次调用读会话真实路由 —— ctx.web.registerSearchProvider

一个替换 DeepSeek Harness 内置 web_search 搜索后端的 provider 插件。 内置实现把端点和凭据写死为 DeepSeek 官方（自配网关的用户必现认证失败）；本插件改为按当前会话路由的 model provider 查路由表：用该 provider 自己的端点、凭据引用与协议方言完成搜索，未识别的 provider 默认回退内置官方方案，整条链路在报错中透明说明。English: per-session routed search with a configurable dialect table and a built-in official fallback.

能力

能力	机制
运行时优先级链	每次搜索按优先级列表从上到下尝试，第一个成功的路由生效；特殊键 `session` = 跟随当前会话路由。设置 UI「Web 搜索」面板可拖动调整，保存即生效（持久化到 `<DSH_HOME>/web-search-session-follow/config.json`，每次调用现读、无需重启）
会话跟随路由	`session` 键实时读 `agents.currentInitiator().session.requestHeader().config` 的 `{provider, model}`，不缓存、不猜测
方言路由表	路由条目 `protocol` 三选一：`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 方言用会话当前模型（兜底 `deepseek-v4-flash`）、openrouter 方言用会话当前模型、zai 方言固定用路由模型（兜底 `glm-5.3-flash`，绝不继承外来会话模型名）
调用审计	每次搜索追加一行 JSON 到 `<DSH_HOME>/web-search-session-follow/audit.jsonl`（provider/endpoint/fallback/失败跳 attempts 标记，不含密钥）。不写会话日志，原因见「会话日志安全」

会话日志安全

本插件绝不向会话日志写自定义事件类型。 Harness 核心对事件类型采取白名单制（@deepseek-ai/dsh-session 的 KNOWN_SESSION_EVENT_TYPES），且 Session.append 不支持把事件标记为 ignorable。写入白名单之外的自定义类型后：会话在内存中一切正常，但任何冷读（子代理目录树、历史打开、续跑、automation 汇总）都会抛 SessionFormatUnsupportedError: ... unknown to this harness and not marked ignorable; refusing to interpret the log — it was likely written by a newer harness—— 子代理在目录里显示为「不可用」、整个会话无法从磁盘重开。

v0.1.0 曾以 web/session-follow-search-request 事件做调用审计，正踩中此坑（v0.1.1 起改为本地文件审计）。已污染的日志可修复：给对应事件行补 "ignorable":true （信封契约允许、seq 不变），或等上游暴露 ignorable / 类型注册机制后原生解决。

Quick Start

前置：DeepSeek Harness（developer preview，dsh web 可用）。

# 本地目录安装（也可推到 GitHub 后 github:owner/repo 安装）
dsh plugin --profile web add /path/to/dsh-web-search-session-follow

在 profile 的 cordis.patch.yml 把搜索选择器切到本插件：

- id: web
  config:
    searchProvider: session-follow

重启 dsh web 生效。回滚 = 删除上面的覆盖段，恢复内置行为。

Configuration

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

config:
  priority: [zai-coding-cn, openrouter]   # 部署种子优先级；首次在设置 UI 保存后由 config.json 接管
  fallback: official        # official（默认）| none：链全失败时回退官方方案还是保持报错
  routes:
    zai-coding-cn:          # 智谱 bigmodel：Anthropic 兼容端点 + web_search_prime 引擎
      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:      # key = 会话里看到的 provider id
      baseURL: https://api.deepseek.com/anthropic/v1
      apiKeyEnv: DEEPSEEK_API_KEY
      model: deepseek-v4-flash          # 缺省跟随会话模型（anthropic 方言缺省内置默认）
    openrouter:
      protocol: openrouter-online       # OpenRouter 自己的搜索方言
      apiKeyEnv: OPENROUTER_API_KEY
      maxResults: 5                     # 注入的搜索结果条数
    # <其他 provider id>:
    #   baseURL: https://<支持所选方言的端点>
    #   apiKeyEnv: <该网关的凭据名>

字段	适用方言	说明
`priority`	全部	优先级链（路由 key 数组，可含 `session`）；来源优先级：设置 UI 保存的 `config.json` > 插件 config 种子 > `["session"]`（v0.1 兼容行为）
`protocol`	全部	缺省 `anthropic-web-search`；OpenRouter 网关填 `openrouter-online`；智谱 bigmodel 填 `zai-web-search`
`baseURL`	全部	anthropic/zai 方言自动追加 `/messages`；openrouter 方言追加 `/chat/completions`
`apiKeyEnv` / `apiKey`	全部	凭据引用名 / 字面密钥（二选一，字面优先）
`model`	全部	缺省跟随会话模型（zai 方言固定兜底 `glm-5.3-flash`，anthropic 方言兜底 `deepseek-v4-flash`）
`maxResults`	openrouter	服务端 web 插件注入的结果条数（默认 5）
`maxTokens` / `maxUses` / `apiVersion`	全部	同内置默认（4096 / 5 / 2023-06-01；openrouter `maxTokens` 默认 1024）

运行时优先级（设置 UI）

Web GUI → 设置 → 侧栏「Web 搜索」：

优先级链：列表即尝试顺序，↑↓ 调序、✕ 移除、下拉加回；每一项可「测试」真实发一次搜索并显示结果数与样例链接。
回退策略：official（链全失败后用内置 DeepSeek 官方方案兜底）/ none（不回退，省余额）。
保存写入 <DSH_HOME>/web-search-session-follow/config.json，下一次搜索立即生效，无需重启。
面板背后的 HTTP API（同机可用）：GET /web-search/config、POST /web-search/config {priority?, fallback?}、POST /web-search/test {key}。

FAQ

和内置 provider 的区别？ 内置 deepseek-official 只有一个写死的端点 + 一把固定引用的 key；本插件按会话路由切换端点/凭据/方言，并对未知 provider 回退而非报死。参见上游讨论 deepseek-harness #408、#1078。

任意网关都能接吗？ 只有说这三种方言之一的网关可以纯配置接入。网关完全不支持服务端搜索时（如仅 OpenAI chat-completions 的代理），换 key 无法修复——要么让它走回退的官方方案，要么在 routes 里把它指向一个支持搜索的端点。

成本怎么算？ 三种方言都是「一次搜索 = 一轮带搜索结果的完整模型调用」：anthropic/zai 方言计费在端点所属 provider （zai 的 web_search_prime 在实测中 usage.server_tool_use.web_search_requests: 0，疑似随编码套餐计，不单扣资源包，但请自行留意账单），openrouter 方言按你 OpenRouter 账号上的模型计费。

开发

npm test   # node --test，35 例：优先级链 / 三方言响应映射 / 路由决策 / 回退链路 / 凭据解析序 / 运行时配置文件 / 设置 API / 端到端 fetch / 会话日志安全回归

MIT License · 为 DeepSeek Harness 插件生态编写

能力

会话日志安全

Quick Start

Configuration

运行时优先级（设置 UI）

FAQ

开发

Footer