1. 为什么我要给 dsh 写一个免费搜索插件用 DeepSeek Harness后面统一简称 dsh做本地智能体编排的朋友大概率都遇到过同一个尴尬模型推理能力够用但一旦让它去查点实时信息就抓瞎了。dsh 本身是个很克制的框架它把工具调用这件事交给插件生态去解决官方并没有内置一个开箱即用的联网搜索能力。你要么自己接一个付费搜索 API要么让模型凭记忆硬答——前者要花钱、要配 key、要担心额度后者在时效性问题上基本等于胡说八道。我最初的需求特别朴素让 dsh 里的智能体在需要的时候能自己去网上搜一圈把结果拿回来做二次加工。市面上的搜索 API 我盘了一圈按量计费的那种随便跑几个 agent 循环一天下来账单就不好看了。而免费的那些要么限制 IP、要么要注册一堆账号、要么返回结构乱七八糟还得自己清洗。折腾了两天之后我决定换个思路与其去接一个免费额度的 API不如直接写一个插件把多个公开搜索引擎的网页结果聚合起来在插件内部做去重、排序、截断最后以统一的结构吐给 dsh。这就是dsh-web-search-free的由来。它的定位很明确零成本、多引擎、可离线部署、结果结构统一。适合三类人——一是像我这样拿 dsh 做个人助理、知识库问答、自动化调研的独立开发者二是想研究插件机制、拿它当模板改造成自己搜索源的技术爱好者三是团队里想快速给内部 agent 加一个能查资料能力、又不想走采购流程的工程师。需要先说明一点这个插件解决的是让 agent 能拿到网页搜索的原始结果它不负责帮你绕过任何网站的访问限制也不做内容抓取之外的深度解析。它的价值在于把搜索这个动作标准化、插件化让 dsh 的工具调用链路完整起来。下面我会从插件机制、引擎选型、结果清洗、踩坑排查几个角度把整个实现过程拆开讲你能直接照着复现。2. dsh 插件机制到底是怎么跑起来的2.1 先搞清楚 dsh 的 plugin tree 加载逻辑很多人第一次装 dsh 插件就翻车报错长这样error: dsh: plugin tree failed to load: dsh: plugin(s) failed to load。这个报错信息其实已经把问题定位得很清楚了——不是插件代码本身崩了而是插件树在加载阶段就没通过。dsh 启动时会扫描插件目录读取每个插件的清单文件manifest然后按依赖关系构建一棵树。任何一个节点的清单格式不对、依赖缺失、或者 profile 不匹配整棵树就加载失败。所以你在动手写插件之前必须先理解 dsh 的 profile 概念。dsh 支持多套运行配置常见的有web、desktop等。你安装插件时要指定 profile比如热词里出现的dsh plugin --profile web add xxx意思就是往 web 这套配置里加一个插件。如果你装的时候用了 web profile启动的时候却用了默认 profile那插件自然不会被加载——这是新手最容易踩的坑没有之一。我的建议是先确认你当前用的是哪个 profile再决定往哪里装。查看当前 profile 的命令通常在 dsh 的 help 里能找到装之前先跑一遍别嫌麻烦。装完之后用dsh plugin list之类的命令确认插件确实进了列表再启动。这个顺序能帮你省掉至少一半的插件不生效问题。2.2 一个搜索插件最少需要哪些文件dsh 插件的目录结构不复杂核心就三样东西清单文件、入口代码、依赖声明。清单文件告诉 dsh 我是谁、我叫什么、我提供哪些工具、我依赖什么入口代码实现具体的工具函数依赖声明保证运行环境里有你需要的库。我写 dsh-web-search-free 的时候清单里最关键的两个字段是工具名和参数 schema。工具名就是 agent 调用时用的标识比如web_search参数 schema 定义了 agent 能传什么进来通常是query查询词、num返回条数、engines指定引擎这几个。schema 写得越清晰模型调用时越不容易传错参数——这一点后面还会展开讲。入口代码这块我强烈建议把网络请求和结果处理分开写。请求层负责跟各个搜索引擎打交道处理层负责去重、排序、截断。分开写的好处是以后你想加一个新引擎只需要在请求层加一个函数处理层完全不用动。我一开始图省事全写在一起后来加第三个引擎的时候改得想砸键盘重构成两层之后清爽多了。2.3 插件加载失败的完整排查链路我把当时踩坑的排查过程完整还原一下你遇到类似问题可以照着走第一步看报错原文。plugin tree failed to load后面通常会跟具体是哪个插件、哪个字段出的问题。别跳过这行很多人一看报错就慌其实答案就在里面。第二步检查清单文件格式。JSON 或 YAML 对缩进、引号、逗号极其敏感一个多余的空格就能让整棵树挂掉。我当时的坑是清单里写了一个不存在的依赖dsh 找不到就直接拒绝加载整棵树。第三步确认 profile 一致。装的时候用--profile web启动的时候也要带上对应的 profile 参数否则插件在另一套配置里根本不会被扫描到。第四步单独测试插件。dsh 一般提供了单独调用某个工具的方式绕过 agent 直接测你的搜索函数能快速判断是插件逻辑问题还是加载问题。第五步看依赖是否装全。如果你的插件用了第三方 HTTP 库而运行环境里没有加载阶段可能不报错但调用时会失败。这一步容易被忽略因为报错发生在运行时而不是加载时。提示排查插件问题时永远先怀疑配置和加载再怀疑代码逻辑。我见过太多人花几个小时 debug 业务代码最后发现是 profile 装错了。3. 多引擎聚合选哪些源、怎么调度3.1 免费搜索源的选型逻辑免费这两个字是核心约束但免费不等于随便抓。我在选源的时候定了三条硬标准无需 API key、返回结构相对规整、对自动化请求相对宽容。按这三条筛下来能用的公开搜索入口其实不多而且各有脾气。我最终在插件里内置了多个引擎适配器每个适配器负责一个源。为什么要多个而不是一个因为单一免费源有两个致命问题一是覆盖不全不同引擎的索引侧重不一样同一个 query 出来的结果差异很大二是稳定性差免费源随时可能限流或改结构多一个源就多一层冗余。多引擎聚合的本质是用广度换稳定代价是要做去重和排序。这里要特别提醒不要贪多。我一开始接了五六个源结果每次搜索要等所有源返回延迟高得离谱而且很多结果是重复的。后来砍到三个主力源 一个兜底源延迟和覆盖度达到了比较好的平衡。选源的原则是互补而不是数量比如一个偏通用、一个偏技术文档、一个偏新闻时效这样组合起来才有意义。3.2 并发请求与超时控制多引擎聚合最怕的就是一个慢源拖垮整体。假设三个源里有一个响应要 8 秒你串行请求的话总耗时就是三个源之和并发请求的话总耗时取决于最慢的那个。所以必须并发这是硬要求。我用的是异步并发 统一超时。具体做法是给每个引擎的请求设一个独立的超时我设的是 5 秒然后用asyncio.gather之类的机制并发发起谁先回来谁先算数超时的直接丢弃不阻塞其他源。这样即使某个源挂了整体搜索依然能在可接受的时间内返回。超时值怎么定我的经验是不要超过 6 秒。agent 调用工具是有上下文预算的搜索这一步如果拖太久整个对话的响应体验就崩了。5 秒是个比较稳妥的值大部分正常源能在 1-2 秒内返回5 秒足够覆盖网络抖动又不会让用户等太久。如果你发现某个源经常超时别调大超时直接把它从主力列表里降级成兜底源。3.3 结果去重URL 归一化是关键多引擎聚合出来的结果重复率能到 30% 以上。最直接的重复判断是看 URL但 URL 这东西坑很多同一个页面带不带www、带不带末尾斜杠、带不带追踪参数?utm_sourcexxx这种在字符串层面都是不同的 URL但指向的是同一个页面。所以去重之前必须做URL 归一化。我的处理步骤是去掉协议头差异、统一小写域名、去掉末尾斜杠、剥离常见的追踪参数、去掉锚点#后面的部分。归一化之后再比对重复率立刻降下来。这一步看起来琐碎但不做的话你给 agent 返回的结果里会有一堆看起来不一样其实一样的条目白白浪费上下文。除了 URL 去重我还加了一层标题相似度去重。有些页面 URL 不同但标题几乎一样比如同一篇文章的不同镜像这种情况用 URL 判断不出来。我用的是简单的标题归一化 前缀匹配能过滤掉大部分镜像站。更复杂的相似度算法比如编辑距离我也试过效果提升有限但计算开销上去了性价比不高最后砍掉了。4. 把搜索结果喂给 agent 之前要做的清洗4.1 为什么原始 HTML 不能直接给模型这是很多人忽略的一步。搜索引擎返回的原始结果里标题和摘要往往带着 HTML 标签、转义字符、甚至内联样式。你要是直接把这一坨丢给模型会发生两件坏事一是浪费 token标签占了一大堆上下文二是干扰理解模型可能把标签当成内容的一部分回答里冒出奇怪的符号。所以清洗是必须的。我的清洗流程是先剥离所有 HTML 标签再解码 HTML 实体amp;这种然后压缩多余空白最后做长度截断。每一步都有讲究——剥离标签要用能处理嵌套的解析方式别用简单的正则硬删否则遇到a href...这种带属性的标签会删不干净实体解码要覆盖常见的几种不然nbsp;会原样出现在结果里。4.2 摘要截断的粒度控制摘要截断看着简单其实很影响效果。截太短信息不够模型没法判断这条结果相不相关截太长几条结果就把上下文占满了。我的经验值是每条摘要控制在 200-300 字符标题控制在 100 字符以内。这个长度足够模型判断相关性又不会太占地方。截断的时候有个小技巧尽量在句子边界截断。如果硬截在句子中间模型读起来会别扭甚至误解原意。我的做法是先按句号、问号、感叹号切分然后从前往后累加超过阈值就停在上一个完整句子。如果第一个句子就超长那就只能硬截但这种情况很少。4.3 统一输出结构的设计清洗完之后所有引擎的结果要统一成同一个结构agent 才能稳定消费。我定义的结构很简单每条结果包含四个字段title、url、snippet、source。source字段记录这条结果来自哪个引擎方便调试和溯源。为什么要有source因为多引擎聚合之后你有时候需要知道这条结果是不是只有某一个源返回了这对判断结果可信度有帮助。而且调试的时候如果发现某个源的结果质量特别差你能快速定位并把它降级。输出给 agent 的时候我会把结果组织成一个带编号的列表而不是一堆 JSON。原因是模型对编号列表这种格式的理解和引用能力更强它能在后续回答里说根据第 3 条结果而面对纯 JSON 时经常引用错。这个细节是我实测下来差异最明显的一处优化。5. 实测中那些让人抓狂的坑5.1 编码问题中文搜索的隐形杀手中文搜索最容易翻车的地方是编码。有些源返回的是 GBK 编码有些是 UTF-8如果你不显式处理中文就会变成乱码。我一开始没注意搜出来的结果全是问号和方块排查了半天才发现是编码没指定。解决办法是在请求层显式声明期望的编码并在解析前做一次编码探测。如果响应头里带了 charset就按它来如果没带就根据内容特征猜比如先按 UTF-8 解出现大量替换字符就换 GBK 重试。这个逻辑我封装成了一个工具函数所有引擎适配器共用省得每个源都写一遍。5.2 反爬与频率控制别把免费源用废了免费源最怕的就是被高频请求打到限流。我踩过的坑是调试的时候疯狂跑测试结果某个源直接把我 IP 封了一段时间。后来我加了两层保护一是插件内部做请求间隔控制同一个源的连续请求之间强制间隔二是加缓存相同的 query 在短时间内直接返回缓存结果不打网络。缓存这块我用的是简单的内存缓存带过期时间我设的是 10 分钟。对于 agent 场景来说同一个 query 在短时间内被重复调用的概率其实不低缓存能显著降低对源的压力。如果你要长期跑建议把缓存换成带持久化的方案重启之后还能用。注意频率控制不是可选项是必选项。免费源的容忍度有限你把它用废了最后受影响的是自己。5.3 结果为空时的兜底策略搜索返回空结果是常态尤其是长尾 query。这时候如果插件直接返回空agent 会一脸懵不知道该干嘛。我的做法是分级兜底先用原始 query 搜如果结果太少就用 query 的关键词重新搜一次如果还是空就返回一个明确的未找到相关结果提示让 agent 知道该换个说法或者放弃。这个兜底逻辑看起来简单但能显著提升 agent 的体验。没有兜底的时候agent 经常在空结果上反复重试浪费好几轮对话有了兜底它能快速判断这条路走不通转而用其他方式回答。6. 从能跑到好用几个提升体验的细节6.1 让模型正确调用工具的参数设计工具能不能被正确调用很大程度上取决于参数 schema 的设计。我最初的 schema 只定义了query一个必填参数结果模型经常不知道该传几条结果、该用哪些引擎要么不传走默认要么乱传。后来我把num和engines都加进 schema并给了清晰的描述和默认值调用准确率明显提升。关键经验是给参数写清楚什么时候该传、传什么值。比如num的描述写成返回结果条数默认 5需要更多背景信息时可调到 10模型看到这种描述就知道该怎么用了。别指望模型自己猜schema 就是你和模型之间的接口文档。6.2 搜索结果的引用格式前面提到我用编号列表输出结果这里再补充一个细节在每条结果里保留 URL。有些实现为了省 token 会把 URL 去掉只留标题和摘要结果模型回答时没法给出出处用户想核实都找不到地方。URL 虽然占一点空间但它是结果可信度的锚点不能省。如果 token 实在紧张可以把 URL 缩短显示比如只显示域名 路径前几位但完整 URL 要保留在数据里需要的时候能取出来。我的做法是列表里显示完整 URL因为实测下来这点开销完全值得。6.3 插件配置的外部化最后说一个工程上的建议把引擎列表、超时值、缓存时间这些参数做成可配置的别硬编码在代码里。我一开始全写死后来想调超时值还得改代码重新加载特别烦。改成配置文件之后调参就是改一行配置的事效率高多了。配置的粒度也要注意别搞太细。我见过有人把每个引擎的每个请求头都做成配置项结果配置文件比代码还长维护成本反而上去了。我的原则是只把你可能会调的参数暴露出来比如超时、条数、引擎开关其他的保持默认。7. 关于这个插件后续还能怎么折腾写到这里dsh-web-search-free 的核心实现基本讲完了。它现在能稳定地做一件事接收一个 query并发调用多个免费搜索源清洗去重后返回统一结构的结果给 dsh 的 agent。整个过程零成本、可离线、结果可控。我自己在实际使用中最大的体会是免费方案的价值不在于省钱而在于可控。付费 API 你只能接受它给的结果和它的限流策略而自己写的插件从源的选择到结果的清洗每一环你都能调。这种可控性在 agent 场景里特别重要因为 agent 对工具返回结果的格式和质量非常敏感一点点不规整就可能导致它理解偏差。后续我打算加两个东西一是结果的相关性打分用简单的关键词匹配给每条结果打个分让 agent 优先看高分结果二是搜索历史记录方便回溯 agent 到底搜了什么、拿到了什么。这两个都不复杂但能进一步提升实用性。如果你也在用 dsh 做 agent又苦于没有顺手的搜索工具可以拿这个插件的思路去改。核心就三件事并发请求、URL 归一化去重、统一结构输出。把这三件事做扎实一个能用的免费搜索插件就成了。至于引擎选哪几个、超时设多少、缓存多久这些参数按你自己的场景调没有标准答案跑起来实测几轮就有感觉了。