本文由本站基于该插件已收录的字段自动派生（wiki / faq / compatibility_json / readme），非 AI 即时创作。每节末尾标源字段。

快速上手

modsearch

— 源: plugin_wiki.wiki_content

安装与验证

dsh plugin --profile web add @liustack/modsearch

复制以上命令在 DSH Web Profile 内运行。安装完成后在「插件列表」启用即可。

— 源: plugins.install

关键要点

• 完全免费。 默认走 Antigravity CLI 通道，无需 API key。三个备用通道（Tavily、Exa、Firecrawl）均有月度免费额度，注册均不要求绑卡。
• 自动故障转移。 一个通道失败或额度耗尽时自动切换下一个。
• 可搜索 X（推特）。 安装 Grok Build 后，可检索网页索引覆盖不到的 X 内容。
• 一次安装，多端可用。 支持 Claude Code、Codex、Pi、OpenCode。
• 提交 issue。 bug、建议、难以理解的报错或文档都欢迎。issue 会被认真阅读，并影响后续开发方向。

— 源: plugin_wiki.readme_zh (fallback readme_raw)

常见问题

modsearch 安装后能直接用吗，还需要配 API key 吗？

单页抓取（-u）零配置即可用；网页搜索（-q）至少需要一个搜索引擎。默认走 Antigravity CLI（免 key、浏览器登录一次），三个备用引擎 Tavily/Exa/Firecrawl 都有免费额度且不绑卡。什么都不配时，错误信息会列出所有可用的开启方式。

安装后 dsh 里会有什么变化？

原生的 web_search 工具仍叫同名、模型看到的就是原生 schema 和引用卡片，背后被换成 modsearch 的引擎链；另外多出两个 dsh 没有的工具：搜 X 的 x_search 和带焦点读单页的 read_page，直接出现在模型可用工具列表中。

搜索时会扣哪个账号的额度？会被哪个引擎处理？

未强制指定 -e 时，所有就绪引擎按优先级组成故障转移链。结果里 results[i].engine 标明实际回答者，attempts 列出尝试顺序，warnings 会在某个引擎失败、被降级、或打了 cooldown 时说出原因，永远不会无声扣费。

为什么同一个 X 问题有时候返回的不是 X 内容？

当 Grok Build 没装、未登录或本轮失败时，路由器会自动退回到网页搜索引擎回答，并在结果里把 source 标为 web、requestedSource 标为 x、status 标为 degraded、warnings 写明退路原因；不会假装是 X 真实结果。

如何知道本机到底配了什么、哪里出问题？

运行 modsearch doctor，纯本地检查，不耗额度不发网络请求，会报 Node 版本、每个引擎的就绪状态与原因、配置来源与权限、私网开关、cooldown 状态，每个未就绪的引擎都附一条可复制的修复命令；加 --json 可输出机读报告。

Antigravity CLI 提示 quota 用完了怎么办？

默认开启 quota cooldown failover：本轮会把 antigravity-cli 挪到链尾，下一次直接先用其他引擎。等周重置（错误信息会写明 Resets in …）或加配一个有 key 的引擎（Tavily/Exa/Firecrawl 任一）即可恢复。modsearch state clear 可立刻清空所有冷却。

VPN 把目标地址映射到内网 IP 时怎么处理？

默认拒绝私网/保留地址范围（SSRF 防护）。可通过 --allow-private-network 单次放行，或 modsearch config set allowPrivateNetwork true 设为全局；Firecrawl 抓取始终拒绝私网目标，即便开了开关。

卸载会留下什么？

卸装本插件即可。会留在机器上的只有 ~/.modsearch/config.json（你显式配的 key 与端点）和 ~/.modsearch/state.json（冷却状态）；不放 hook 也不改宿主本身的配置。

— 源: plugin_wiki.faq_json

兼容性

• DSH: 未声明（package.json 无 peerDependencies；通过 dsh.bundle.patch（cordis.patch.yml）注入 dsh 宿主，要求宿主 dsh 暴露 ctx.web.registerSearchProvider / ctx.tools.register）
• Node: >=22.13

— 源: plugin_wiki.compatibility_json

踩坑提醒

安装前请审阅上游仓库；本指南基于已收录字段自动派生，可能滞后于最新版本。如发现与官方文档冲突，请以上游为准。

— 来源：通用规则