搜索路由跟随 NattoCB/dsh-web-search-session-follow

dsh-web-search-session-follow

一个 DSH web_search provider，跟随对话的路由模型 —— 按 provider 使用各自的端点、凭据与协议方言。

每次调用读会话真实路由 —— 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 搜索」面板可拖动调整，保存即生效（持久化到 /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 到 /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 / 类型注册机制后原生解决。

快速开始

前置：DeepSeek Harness（开发者预览版，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 生效。回滚 = 删除上面的覆盖段，恢复内置行为。

配置

路由表随插件自带默认值安装，可在插件的 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 # 注入的搜索结果条数

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（不回退，省余额）。
- 保存写入 /web-search-session-follow/config.json，下一次搜索立即生效，无需重启。
- 面板背后的 HTTP API（同机可用）：GET /web-search/config、POST /web-search/config {priority?, fallback?}、POST /web-search/test {key}。

常见问题

和内置 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 / 会话日志安全回归

Footer

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