QuantumKuba/dsh-webstack

面向 DeepSeek Harness（ctx.web）的企业级网页搜索与检索插件

概述

dsh-webstack 是面向 DeepSeek Harness 的高性能网页能力套件，集成了用于元搜索发现的 SearXNG 以及用于多层级、抗反爬内容检索的 Scrapling。

dsh-webstack 专为在有限上下文窗口（32k–90k tokens）内运行的本地推理模型（例如 Qwen 2.5/3.8 27B 和 DeepSeek R1/V3）而设计，在不造成工具臃肿、上下文污染或安全漏洞的前提下，提供网页自主能力。

┌───────────────────────────────────────────────────────────┐
│                 DeepSeek Harness Agent                    │
│             Local LLM (Qwen 3.8 27B / R1)                 │
└─────────────────────────────┬─────────────────────────────┘
│
Native Schema    │  web_search / web_fetch
▼
┌───────────────────────────────────────────────────────────┐
│                  Cordis ctx.web Runtime                   │
└──────────────┬────────────────────────────┬───────────────┘
│                            │
Provider: searxng   │        Provider: scrapling │
▼                            ▼
┌──────────────────────────┐ ┌───────────────────────────────┐
│  SearxngSearchProvider   │ │     ScraplingFetchProvider    │
│   • Clean JSON Mapping   │ │   • Pre-Flight DNS Validation │
│   • Engine Deduplication │ │   • Same-Origin Redirect Lock │
└────────────┬─────────────┘ └───────────────┬───────────────┘
│                               │
▼                               ▼
┌──────────────────────────┐ ┌───────────────────────────────┐
│  本地 SearXNG 实例        │ │  Scrapling 多层级引擎          │
│  隐私保护的元搜索聚合     │ │  T1: curl_cffi 指纹模拟        │
│  （P95 1.7s）            │ │  T2: 无头 Playwright/DOM       │
└──────────────────────────┘ │  T3: 隐身 WAF 与 Turnstile     │
└───────────────┬───────────────┘
│
▼
┌───────────────────────────────┐
│  Markdown 精简器（GFM）        │
│  节省 73.1% token 上下文       │
└───────────────────────────────┘

架构与生产环境保障

1. 面向模型零工具膨胀
模型仅与原生 DeepSeek Harness 的 web_search 和 web_fetch schema 交互。高级抓取参数、隐身标志和 DNS 检查完全封装在提供者层内部。

2. 多层级检索流水线（scrapling）
内容获取会根据目标复杂度自动在三个性能层级之间伸缩：

| 层级 | 引擎 / 技术 | 延迟（均值） | 主要目标 |
| :--- | :--- | :---: | :--- |
| 第 1 层（默认） | curl_cffi（Chrome TLS 指纹） | 531ms | 文档、GitHub、Wikipedia、博客、REST 端点 |
| 第 2 层（动态） | Playwright 无头 Chrome | 2,088ms | 客户端渲染的 JavaScript SPA（React、Vue、Next.js） |
| 第 3 层（隐身） | StealthyFetcher 反机器人引擎 | 1,669ms | Cloudflare Turnstile、插页、反机器人 WAF 挑战 |

* Turnstile 求解器：针对交互式 Cloudflare 挑战的自动检测与点击坐标拟人化。
* 指纹伪装：Chromium canvas 噪声注入、WebRTC IP 泄漏抑制、真实 WebGL 上下文、Google Search referer 欺骗以及跟踪器拦截（约 3,500 个域名）。

3. 内核级 SSRF 与安全 URL 防护
所有获取请求在连接分发之前都会经过预检 DNS 地址验证：
* 私有子网拒绝：立即阻止回环地址（127.0.0.0/8、::1）、RFC 1918 子网、链路本地 / 云元数据端点（169.254.169.254）以及运营商级 NAT（100.64.0.0/10）。
* 分裂地平线保护：解析为混合公网/私有地址的主机名会被立即拒绝。
* 严格同源重定向：跨源或跨协议的重定向会以 WEB_REDIRECT_BLOCKED 终止。
* 零 DNS 延迟惩罚：安全检查在** 📊 有关完整的逐查询分布、延迟方差和测试设置，请参阅 基准测试报告。

快速开始

1. 安装插件
在你的 DeepSeek Harness 工作区中：
pnpm add dsh-webstack
或通过 npm
npm install dsh-webstack

2. 配置 SearXNG 与 Scrapling
* SearXNG：通过 Docker Compose 部署，并在 http://127.0.0.1:8080 上启用 JSON（参见 SearXNG 设置指南）。
* Scrapling：安装到带有隐身附加组件的虚拟环境中（参见 Scrapling 设置指南）：
pip install "scrapling[stealth]" && playwright install chromium

3. 挂载 Cordis 补丁层
将 cordis.patch.yml 应用到你的 DeepSeek Harness 配置文件，以连接 ctx.web：
- id: web
config:
searchProvider: searxng
fetchProvider: scrapling

- insert:
- id: dsh-webstack
name: dsh-webstack
config:
searxng:
baseURL: http://127.0.0.1:8080
scrapling:
pythonBinary: python3
enableDynamicFallback: true
enableStealthFallback: true

文档与指南

全面的指南和技术文档可在 docs/ 目录中找到：

| 指南 | 描述 |
| :--- | :--- |
| SearXNG 设置指南 | 官方 Docker Compose 部署、settings.yml 调优、密钥生成以及 Valkey 缓存。 |
| Scrapling 环境设置 | Python 3.11+ 虚拟环境设置、Playwright Chromium 安装以及 sidecar 验证。 |
| 配置参考 | 完整的 Cordis 补丁层、SearXNG 和 Scrapling 的参数目录以及上下文边界调优。 |
| 编程使用指南 | 在不使用 Harness 的情况下，独立以 Node.js 和 TypeScript 使用 SearxngSearchProvider 和 ScraplingFetchProvider。 |
| 故障排除与常见问题 | 针对 403 Forbidden、429 速率限制、缺少 Python 路径、Playwright 二进制文件以及 SSRF 拦截的解决方案。 |
| 基准测试报告 | 实证延迟分布、上下文 token 缩减统计以及 SSRF 安全测试遥测。 |

验证与测试套件

该代码库在搜索规范化、安全过滤器和实时集成方面维护了自动化测试覆盖：

运行完整测试套件（35 个测试，10 个套件）
pnpm test

运行重点测试套件
pnpm test:security      # SSRF 验证、私有 IP 拦截、重定向策略
pnpm test:searxng       # 查询参数编码、响应规范化
pnpm test:cancellation  # 信号取消、子进程终止
pnpm test:integration   # 实时 HTTP 获取、重定向强制执行、Cordis 接缝

运行实证基准测试套件
pnpm run benchmark

许可证

MIT © Kuba