前言¶
用 DeepSeek Harness（dsh）跑智能体时，一个很常见的落差是：官方 App 里模型能联网查资料，切到 API 或本地 harness 后，联网能力就弱了甚至直接消失。DeepSeek、GLM 等模型本身并不自带可靠的网页检索，dsh 虽然内置了 web_search 工具，但默认走的是 DeepSeek 的 keyed 搜索接口，对「零配置、免 API key」的诉求并不友好。
社区里围绕这个问题有不少方案。今天要介绍的是 SkillHub 插件库「联网工具」分类下的 liustack/modsearch（ModSearch）：由维护者 liustack 开源，GitHub 上约 259 star、12 fork，MIT 许可。它既是 dsh 原生 bundle 插件，也能作为 Agent Skill 装进 Claude Code、Codex、Pi、OpenCode 等宿主，核心卖点是免费、免注册、免 API key 起步，把网页搜索、X（推特）搜索和单页抓取补回来，并以结构化 JSON 证据返回，方便模型引用与二次处理。
需要说明的是：DeepSeek Harness 的理念是「一切皆插件」，SkillHub（https://www.skillhub.cn/plugins）是社区整理的插件目录，与 DeepSeek / 幻方并无官方从属关系；下文安装命令以插件仓库与目录页交叉核实后的写法为准。
这是什么¶
ModSearch 是一个面向 coding agent 的联网搜索桥接插件。对 dsh 用户来说，它不只是额外挂一个 skill——npm 包 @liustack/modsearch 自带 dsh.bundle.patch，安装后会：
- 把 dsh Web 端的
searchProvider切到modsearch，让内置web_search走 ModSearch 引擎链，同时保留原生引用卡片 UI； - 额外注册
x_search（X 语料搜索）和read_page（单页精读）两个工具。
对没有原生联网能力的模型，ModSearch 相当于外挂了一层「搜索 + 抓取 + 引用」能力；装完默认就能用 Firecrawl 的免注册通道（每月约 1,000 免费 credits，无需账号与 API key），不必先折腾密钥。
核心功能与亮点¶
结合 GitHub README 与 docs/dsh.md，ModSearch 已核实的主要能力如下。
1. 开箱免费，零配置可搜¶
默认引擎是 Firecrawl keyless：搜索与单页抓取直接可用，不用注册、不用绑卡。若后续需要更高额度，可再配置 Tavily、Exa、免费 Firecrawl key 等，也均有免费层。
2. 多引擎链与自动故障转移¶
除 Firecrawl 外，还支持 Antigravity CLI、Tavily、Exa、Grok Build（X 搜索）、local（本地单页抓取）。一个通道失败或额度耗尽时，会自动切换到下一个；同一引擎还可配置逗号分隔的多密钥轮换。
3. 结构化 JSON 输出，而非整页塞进上下文¶
CLI 向 stdout 打印统一信封的 JSON（mode、query、results、meta 等），每条结果带 engine、summary、items（标题、URL、摘要）、uncertainty（事实存疑提示）和 warnings（路由/降级说明）。相比部分内置搜索把整页原文推入模型上下文，结构化证据通常更省 token，也更利于 agent 做引用。
4. 三类联网动作，覆盖 dsh 缺口¶
| 能力 | dsh 入口 | 说明 |
|---|---|---|
| 网页搜索 | 内置 web_search |
走 ModSearch 引擎链，保留原生引用卡片 |
| X 搜索 | 新增 x_search |
安装并登录 Grok Build 后可检索 X 语料；无 Grok 时可能降级为网页替代，并在输出中标注 |
| 单页精读 | 新增 read_page |
读取单个 URL，可带问题聚焦；默认拦截私有网段，公网页可走 Firecrawl 云浏览器 |
5. 一次安装，多端复用¶
除 dsh 原生 bundle 外，ModSearch 也可作为 skill 用于 Claude Code、Codex、Pi、OpenCode 等。对 Codex 这类已有 DeepSeek 官方 web_search 的宿主，作者建议关闭内置搜索后再交给 ModSearch，以避免模型优先调用内置工具、skill 插不上话，同时也能降低上下文占用。
安装与启用¶
dsh 用户（推荐路径）¶
在实际启动的 profile 上安装。浏览器 UI 通常用 web profile。目录页与仓库文档给出的命令一致，当前版本为 5.9.1（写死版本号是为规避 pnpm 11 minimumReleaseAge 导致 @latest 解析到旧包的问题）：
npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modsearch@5.9.1
安装后重启 dsh，再确认插件已解析：
npx -y @deepseek-ai/dsh plugin --profile web list --depth 0
npx -y @deepseek-ai/dsh --profile web --dump-config
--dump-config 输出里应同时看到 searchProvider: modsearch 与名为 @liustack/modsearch 的插件行。
离线体检¶
不必先消耗搜索额度，可先跑健康检查：
npx -y @liustack/modsearch@5.9.1 doctor
图形化配置（免命令行）¶
dsh Web 端可在 设置 → 插件 → 插件配置 找到 搜索引擎（ModSearch） 卡片：选择首选引擎、填写 API key 或自建端点、勾选参与故障转移的引擎，保存后写入与 CLI 相同的 ~/.modsearch/config.json（文件权限 0600）。
可选：增强免费引擎¶
若希望综述质量更好，可安装 Antigravity CLI 并浏览器登录：
curl -fsSL https://antigravity.google/cli/install.sh | bash
agy # 浏览器完成登录后退出
也可通过 CLI 或设置卡片配置 Tavily / Exa / Firecrawl 的免费 key，例如：
modsearch config set tavily.apiKey <key>
modsearch config set exa.apiKey <key>
modsearch config set firecrawl.apiKey <key>
作为 Agent Skill 安装¶
若宿主不是 dsh，可把仓库 skills/modsearch 链到各宿主约定的 skills 目录（Claude Code → ~/.claude/skills/，Codex → ~/.codex/skills/，Pi / OpenCode → ~/.agents/skills/）。官方 INSTALL.md 建议直接对 agent 说：
按 https://github.com/liustack/modsearch 的 INSTALL.md 安装并配置 modsearch skill，完成后运行体检并把结果告诉我。
典型用法示例¶
装好后不需要记专用命令，正常对话即可；需要查证的问题、开放域新闻、或粘贴 URL，插件会按场景自动触发。
验证三类工具是否生效¶
启动 profile 后，可用 docs/dsh.md 推荐的三条小提示做冒烟测试：
Search the web for the current Node.js LTS release and cite the sources.—— 应走 dsh 原生web_search卡片；Search X for recent posts from @deepseek_ai.—— 应调用x_search（需 Grok Build 就绪）；Read https://example.com and summarize the page.—— 应调用read_page。
日常对话式使用¶
中文场景下同样适用，例如：
- 「今天 AI 领域有什么重要新闻？」—— 开放域网页搜索，返回带来源的条目列表；
- 「帮我总结这篇文章讲了什么：https://example.com/blog/post」—— 单页抓取与结构化摘要；
- 「Node.js 现在哪条版本线还在维护？」——
read_page可读官网版本页与发布计划，再给出结论表。
返回 JSON 中的 uncertainty 字段会提示哪些细节来自检索聚合、可能需要二次核实，适合在 agent 工作流里当作「置信度脚注」。
适用场景与注意事项¶
适合谁用：
- 在 dsh 里用 DeepSeek / GLM 等模型，希望不绑搜索 API key 也能联网的开发者；
- 需要 X 语料 或 单 URL 精读，而宿主原生工具覆盖不到的智能体场景；
- 希望搜索证据以 JSON 结构化返回、便于引用与流水线处理的工程团队。
使用前请注意：
- 权限边界：插件以当前 dsh 进程权限运行，会访问外网并按配置读写
~/.modsearch/config.json。安装前建议浏览源码与 MIT 许可证，确认可接受其安全模型（仓库提供 SSRF 防护、DNS 重绑定防护等说明，见docs/security.md）。 - 上游引擎条款：Firecrawl、Tavily、Exa、Grok Build 等各有服务条款与额度，遵守责任在用户侧。
- dsh 仍在快速迭代：当前 bundle 已在
@deepseek-ai/dsh 0.1.0-rc.7上验证；大版本升级后建议重新--dump-config并跑doctor。 - 默认云抓取：公网 URL 默认可能经 Firecrawl keyless 云浏览器抓取，结果会带路由警告；若希望自动抓取尽量本地化，可设置
modsearch config set firecrawl.keylessFetch false。 - 仓库协作政策：作者声明不接受 PR，问题与建议走 GitHub Issues。
结尾¶
如果你正在给 DeepSeek Harness 或其它不能联网的 coding agent 找一条「免 key 起步、能搜网页也能搜 X、还能精读单页」的通路，ModSearch 值得先试：doctor 通过、三条冒烟提示跑通，基本就能判断引擎链是否就绪。
- 目录页：https://www.skillhub.cn/plugins/liustack/modsearch
- GitHub：https://github.com/liustack/modsearch
- 当前文档版本：5.9.1 | 许可：MIT
