tatselkrik/dsh-web-search-ddg

dsh-web-search-ddg

CI
License: MIT
Node

为 DeepSeek Harness 提供的无需密钥的 DuckDuckGo 网页搜索。
无需 API 密钥。无需账户。无需信用卡。不消耗 token —— 搜索以对 DuckDuckGo lite 结果页面的
普通 HTTP 抓取方式运行，并通过 harness 公开的 ctx.web provider 接缝注册。

为什么

DeepSeek Harness 是自由软件。运行于其中的 agent 也可以是自由的。
编码 agent 真正需要的一切 —— 文件、shell、git、规划、
子 agent —— 都是本地的，且不花分文。网页搜索曾是唯一的一道墙：每一个
随附的 provider 都要求付费账户（DeepSeek 平台密钥、Exa、
Perplexity），而像 Claude Code 和 ChatGPT 这样的闭源工具则将实时搜索捆绑
进它们的订阅中。

这个插件之所以存在，是因为“免费”不应意味着“免费，但互联网除外”。
搜索不应成为迫使你首次注册 API 并收到第一张按量计费账单的功能。
它运行在你的浏览器所用的同一个公开页面上 —— 没有会耗尽的配额，
没有需要轮换的密钥，试用期结束时也没有任何需要取消的东西。
而且因为它存在于你的代码检出中，而非某人的端点里，它属于你，
供你审计、修补并保留：自由软件理应享有自由的搜索。

特性

- 零凭据 —— available() 是纯粹的配置结构检查；无需在凭据保险库中存储任何内容
- 零模型 token —— 与内置的 DeepSeek provider 不同，一次搜索绝不会消耗一次辅助模型轮次
- 严格模式 —— 仅接受 DuckDuckGo 结果标记的锚点；零解析结果会抛出 WEB_PROVIDER_ERROR，绝不会静默地返回空成功
- 重定向感知解析 —— /l/?uddg= 包装被解包为真实目标；内部的 duckduckgo.com 链接被丢弃；重复 URL 被去重
- 实体安全文本 —— 数字/十六进制/命名实体解码时 & 最后处理，因此转义文本绝不会被双重解码
- GET 与 POST —— 为 GET 会触发异常检查的部署提供 POST 表单回退
- 片段配对处理得当 —— 每个片段仅附加到其前面的锚点

安装

安装到 profile 中（推荐）

dsh plugin --profile my-profile add github:tatselkrik/dsh-web-search-ddg

构建产物已提交在 lib/ 下，因此无需构建脚本许可。
该 bundle 会将自身插入 ctx.web 注册表；当它是唯一可用的搜索 provider 时，
它会被自动选中。若要显式固定它，请添加到你的 profile 的 cordis.patch.yml：

- id: web
name: '@deepseek-ai/dsh-web'
config:
searchProvider: duckduckgo

然后使用你的 profile 启动：

dsh --profile my-profile web

在源码检出中（树内变体）
对于已经包含树内包的 Harness 开发检出，请将 packages/web/web-search-ddg/src/ 替换为此仓库的 src/，然后从 Harness 根目录重新构建：

pnpm exec tsc -b packages/web/web-search-ddg
pnpm exec vitest run packages/web/web-search-ddg

全新的树内集成还需要将该包添加到 Harness 工作区和构建图中。对于正常使用，上述 profile 安装是受支持的途径，无需更改源码树。

配置

| 键 | 默认值 | 含义 |
|---|---|---|
| baseURL | https://lite.duckduckgo.com/lite/ | 精简版结果页面。基础 URL 上的额外参数（例如 ?kl=us-en）会被保留。 |
| limit | 10 | 提供程序层面对每次搜索来源数量的上限；接缝仍会强制执行工具请求的 maxResults。 |
| method | get | 查询动词。GET 将 q 放在 URL 中发送；POST 仅将其作为 URL 编码的表单正文发送。 |
| timeoutMs | 15000 | 每次请求的挂钟时间上限，独立于调用方取消；超时表现为 WEB_PROVIDER_ERROR。 |

通过 patch 行覆盖其中任意一项：

- id: web-search-ddg
name: dsh-web-search-ddg
config:
limit: 5
method: post

安全与性能说明

安全

- 无密钥，无 vault 访问 —— 该提供程序不从凭据域读取任何内容；没有任何可泄露的东西。
- 无安装时代码执行 —— 没有 prepare/postinstall 脚本；lib/ 以已提交的形式发布，因此安装过程运行零构建脚本（即 harness 文档所警告的供应链攻击途径）。
- 有界依赖范围 —— 每个已发布的依赖都有显式的脱字符范围，从不用 *；如果你偏好精确性，请将它们与你正在运行的 harness 版本对齐。
- 输入处理 —— GET 查询通过编码后的 q URL 参数传输；POST 查询仅通过编码后的表单正文传输。结果按惰性文本解析（绝不求值），未标记/内部/非 http 目标在被用作引用之前会被拒绝。
- 解析器诚实性 —— 提取基于正则表达式，而非完整的 HTML 解析器：对于精简版页面的扁平标记来说足够，而且它只会看到 DuckDuckGo 返回的内容。像对待任何搜索工具的输出一样对待结果标题/摘要——进入模型上下文的不可信文本。
- 隐私 —— 每个查询对 DuckDuckGo Inc. 可见（搜索就是这样工作的）；除此之外没有任何其他方收到任何内容，并且此包中不存在遥测。

性能

- 每次搜索一次小型 HTTP 往返（约 20–60 KB 的精简版页面）；解析是单次线性 token 遍历。
- 调用之间无状态；即使消费者忘记取消，每次请求的挂钟时间也被限制在 timeoutMs（默认 15 秒）以内。
- 结果数量在接缝应用其自身的 maxResults 之前由 limit 限制，因此上下文成本保持可预测。
- 对比：内置的 DeepSeek 提供程序每次搜索要付出完整的辅助模型轮次（数秒 + token）；而这里只需一次抓取。

已知限制
- 非官方端点 — 无 SLA。激进的突发请求可能导致 403/CAPTCHA；标记变更会明显破坏解析，直到修补为止。
- 无发布日期 — 精简页面不公开这些信息。
- Bing 索引深度 — 结果质量与 DuckDuckGo 的索引相当，在细分技术查询上略逊于 Google。
- 对等依赖版本 — 针对 harness 包以宽松范围声明；如果你在注册表安装的副本与内置副本之间遇到类身份问题（WebError instanceof），请将 dependencies 固定为与正在运行的 harness 版本匹配。

开发

pnpm install --frozen-lockfile
pnpm run typecheck
pnpm test             # 24 tests
pnpm run build         # regenerate committed lib/
git diff --exit-code -- lib

lib/ 已提交，因此最终用户永远不需要构建步骤。

许可证

MIT