ahnafnafee/dsh-web-fallbacks

DSH Web Fallbacks

为 DeepSeek Harness 提供可靠的网页搜索和站点抓取。

一个插件。四个后备后端。你现有的 CLI 登录。

Tests
Node.js
Dependencies
License

快速开始 · 功能特性 · 配置 · 验证 · 故障排查

✨ 功能特性

当某个搜索提供商不可用、返回的是散文而非源 JSON，或者超时时，下一个提供商就会接管。当直接 HTTP 抓取失败或返回几乎为空的页面时，同一条链会检索页面内容。

🔎 返回来源的搜索

Claude Code 使用 JSON schema；Codex 使用结构化输出和原生实时网页搜索。结果共享 DSH 的 URL、标题和摘要格式。

📄 两个 CLI 中的站点抓取

Claude Code 调用 WebFetch。Codex 通过其原生网页工具打开请求的 URL。Firecrawl 和 Linksc 提供额外的检索选项。

🔁 有序恢复

缺失的可执行文件、提供商错误、格式错误的回复以及空结果都会自动向下传递。Firecrawl 始终先于 Linksc。

⏱️ 为整条链留出时间

每个提供商都有一个截止时间。面向模型的工具预算允许后续后备方案运行，而调用方取消会停止整个请求。

🔐 现有身份验证

无头调用使用已安装的 CLI 及其保存的登录信息。可选的 MCP 端点和凭据保留在你的本地 DSH 配置中。

🧩 小巧、可检查的插件

一个 JavaScript 模块、两个 JSON schema，没有 npm 依赖。包含离线回归测试和可选的实时集成测试。

🧭 工作原理

flowchart LR
S[Web search] --> D[DeepSeek]
F[Site fetch] --> H[HTTP]
D --> C[Claude Code]
H --> C
C --> X[Codex]
X --> FC[Firecrawl]
FC --> L[Linksc]

箭头表示后备尝试。第一个有效结果会结束请求。未配置的 MCP 后端会被跳过；不可用的主提供商也会被跳过。

| 操作 | 主提供商 | 后备顺序 |
| --- | --- | --- |
| 搜索 | deepseek-official | Claude Code → Codex → Firecrawl → Linksc |
| 抓取 | http | Claude Code → Codex → Firecrawl → Linksc |

两条链都注册在现有的 DSH 提供商 ID claude-code 下，从而保持配置与早期版本的插件兼容。

🚀 快速开始

1. 检查先决条件

- DeepSeek Harness，并启用其 web 服务和 web 工具。
- Node.js 22.12 或更高版本。
- 已通过身份验证的 Claude Code 和 Codex CLI 安装，用于各自的后端。
- 可选的 Firecrawl 和 Linksc MCP 端点，用于后续的回退。

无头集成已在 DSH 0.1.5-rc.1、Claude Code 2.1.273 和 Codex CLI 0.154.0 上测试过。CLI 标志和 DSH 内部实现可能会变化；请参阅兼容性说明。

2. 克隆并测试

git clone https://github.com/ahnafnafee/dsh-web-fallbacks.git
cd dsh-web-fallbacks
npm test

无需安装依赖或构建步骤。

3. 将其连接到 DSH

使用你的检出目录的绝对文件 URL 打印配置片段：

node scripts/print-config.mjs

将打印出的条目合并到 ~/.dsh/cordis.patch.yml。如果相同的 ID 已存在，请更新这些条目。示例配置展示了不含机器特定路径或凭据的结构。

请保留检出目录：DSH 会从其中加载模块和两个 schema。初始安装后重启 DSH。如果你的 agent 预设拥有 web 工具定义，请同时在该预设的 tool-web 配置中启用 fetch: true。

4. 尝试两种操作

在 DSH 会话中，询问：

Search the web for the official Node.js test runner documentation.

Fetch https://example.com/ and show the page text.

要使用已保存的 CLI 登录直接测试无头后端：

npm run test:live

实时测试会访问外部服务并消耗相应账户的配额。

🔧 配置

插件的 config 对象控制提供商链。以下是最常见的设置：

| 选项 | 默认值 | 用途 |
| --- | --- | --- |
| bin / model | claude / haiku | Claude Code 可执行文件和模型 |
| codexBin / codexModel | codex / gpt-5.6-sol | Codex 可执行文件和模型；codexBin: "" 禁用它 |
| primary | deepseek-official | 第一个搜索提供商；"" 跳过它 |
| fetchPrimary | http | 第一个抓取提供商；"" 跳过它 |
| firecrawlMcpUrl | "" | 暴露 firecrawl_search 和 firecrawl_scrape 的 Streamable HTTP 端点 |
| linkscMcpUrl | "" | 暴露 search 和 fetch 的 Streamable HTTP 端点 |
| linkscHeaders | {} | 你的 Linksc 部署所需的请求头 |
在你的本地 DSH 补丁中设置 MCP URL，以启用这些后端。该链会直接调用它们的 MCP 端点；如果你还希望它们的工具被单独暴露，可选的独立 DSH MCP 插件注册也是可以的。

提供方超时与完整配置参考

| 提供方 | 搜索 | 抓取 |
| --- | ---: | ---: |
| Primary | 5 秒 | 15 秒 |
| Claude Code | 25 秒 | 60 秒 |
| Codex | 40 秒 | 45 秒 |
| Firecrawl | 20 秒 | 30 秒 |
| Linksc | 20 秒 | 20 秒 |
| 面向模型的工具预算 | 120 秒 | 180 秒 |

默认值会为整条链留出时间。如果你增加单个提供方的截止时间，请相应增加整体工具预算。

有关每个选项、MCP 要求、可执行文件路径和重载行为，请参阅配置参考。

🧪 验证

npm test 使用本地 MCP 服务器和子进程夹具运行离线回归用例。npm run test:live 还会检查真实的 Claude 和 Codex 搜索与抓取调用，包括一个故意不可用的 Claude 可执行文件，以强制走 Codex 路径。

公开包通过了全部 29 项测试，包括使用通用文档查询进行的实时 CLI 检查。底层实现也在打包前通过了六项服务器内实时检查。GitHub Actions 在 Linux 和 Windows 上使用 Node.js 22 和 24 运行离线测试套件。

覆盖范围包括模式强制、仅散文回复、提供方排序、失败的子进程、空结果、有界超时、调用方取消、MCP 响应解析和页面检索。有关实时检查的范围和限制，请参阅验证说明。

🧰 故障排除

| 症状 | 需要检查的内容 |
| --- | --- |
| could not run | 确认该 CLI 位于 DSH 的 PATH 中，或将 bin / codexBin 设置为该可执行文件的绝对路径。 |
| 身份验证或配额错误 | 以交互方式运行受影响的 CLI，以检查其登录和账户状态。 |
| 编辑插件后出现旧的解析错误 | 重启 DSH，或更改绝对文件 URL上的版本后缀，以便加载器导入新代码。 |
| 会话中没有 web_fetch 工具 | 在该代理预设的 tool-web 条目上启用 fetch: true，然后创建或重新加载会话。 |
| 某个回退始终没有时间运行 | 保持工具预算大于各提供方截止时间之和。 |
| MCP 401、502 或超时 | 直接检查该端点及其凭据。失败会推进到下一个已配置的提供方。 |

抓取的文本受后端的检索和输出能力限制。Claude 和 Codex 可能会转换或限制长页面；它们的成功包装器会报告 HTTP 200，因为 CLI 输出不会暴露来源的 HTTP 状态。当需要精确字节或来源状态时，请使用直接抓取或 scrape 后端。

🤝 贡献
欢迎提交错误报告和有针对性的拉取请求。请附上通用复现步骤、相关 CLI 版本以及你验证过的内容。参见 CONTRIBUTING.md。

📄 许可证

MIT。

让你的 Web 工具持续运转。

报告问题 · 浏览源代码 · 返回顶部