dsh-fetch-third-party

使用说明

服务商切换

设置 → 插件 → 插件配置 → 网页抓取（第三方） 卡片：

1. 服务商下拉：Tavily / Jina Reader / Firecrawl / 自定义服务商
2. API Key：写入托管保险箱（0600），只显示“已配置/未配置”；Jina 可留空（匿名可用），Tavily / Firecrawl 建议配置
3. 接口地址：默认按服务商自动切换（也可手动改）
4. 每会话抓取上限：默认 10，达到后本会话拒绝抓取
5. 本地代理：见下节

代理配置（网络被阻断时）

部分网络环境会阻断第三方服务直连（如 r.jina.ai 被 DNS 污染），需走本地 HTTP 代理。在卡片「本地代理」填入你的代理地址（示例端口，请填你本机实际代理端口）：

http://127.0.0.1:27822

• 保存后按请求生效（undici ProxyAgent 的 dispatcher），不影响其他网络流量
• 留空 = 直连

抓取缓存与目标安全

• 抓取缓存（卡片二级「抓取缓存」）：开关 + 有效期（秒）。同一 URL 在有效期内重复抓取走内存缓存，不消耗第三方额度与预算。默认开启，有效期 600 秒。
• 内容上限（卡片二级「单次抓取内容上限」）：单次抓取返回正文的最大字符数，超出截断并标记；0 = 不限（默认 100,000，即契约 v1 上限）。
• 拒绝内网目标（卡片二级「目标地址安全」）：转发前拒绝回环/私网/保留地址目标，防止模型诱导抓取内网资源。默认开启。
• 工具命名（配置文件 toolName，不进卡片）：web_fetch_url（默认）/ web_fetch / auto。选择官方名 web_fetch 时若已被占用会自动回退到 web_fetch_url。
• 回退链（卡片二级「回退链」）：逗号分隔的有序服务商名（留空=主服务商+兜底）；失败/配额耗尽的自动冷却降级（配额 3600s / 普通失败 60s 起指数退避），到期自动恢复；下方实时显示链顺序与冷却状态。
• 结构化输出：web_fetch_url 返回 { url, statusCode, content, title?, headings[], links[], wordCount, readingTimeSec }。

自建抓取工具（Crawl4AI，零 API key）

不想依赖商业服务商时，可用自建 Crawl4AI（Docker）+ 契约 v1 包装，接入自定义服务商——无需 API key，本机仍是“快递员模式”。

自动管理（插件内置，无需命令）：启动 dsh web 后，只要「默认服务商」或「兜底服务商」是 loopback 地址的自定义服务商（如 crawl4ai → http://127.0.0.1:8787），插件会自动拉起包装进程，并尽力确保 Crawl4AI 容器在运行。前提：Docker Desktop 已启动（建议设为开机自启）且镜像已拉取。

手动兜底 / 首次拉取镜像：

powershell -ExecutionPolicy Bypass -File scripts/start-crawl4ai.ps1

卡片注册：自定义服务商 → 名称 crawl4ai / 类型 custom（契约 v1） / 接口地址 http://127.0.0.1:8787 → 保存 → 「默认服务商」下拉选它。

契约 v1 对接标准见 docs/contract.md；选型与验证记录见 docs/custom-crawler-research.md。

验证脚本

node scripts/verify-tavily.mjs            # 需 TAVILY_API_KEY
node scripts/verify-jina.mjs              # 匿名即可；带 key 传参或设 JINA_API_KEY
node scripts/verify-firecrawl.mjs         # 需 FIRECRAWL_API_KEY

代理配置（网络被阻断时）

部分网络环境会阻断第三方服务直连（如 r.jina.ai 被 DNS 污染），需走本地 HTTP 代理。在卡片「本地代理」填入你的代理地址（示例端口，请填你本机实际代理端口）：

http://127.0.0.1:27822

• 保存后按请求生效（undici ProxyAgent 的 dispatcher），不影响其他网络流量
• 留空 = 直连

使用/依赖的第三方项目

项目	用途	协议
DeepSeek Harness（@deepseek-ai/dsh-*）	宿主平台：cordis 插件机制、settings / credentials / tools / web 服务	MIT
undici	Node HTTP 客户端（按请求代理）	MIT
Crawl4AI	可选：自建抓取栈（用户自行 Docker 部署，插件经契约 v1 包装对接）	Apache-2.0
Jina Reader	Jina 服务商（公共 API 或自托管）	Apache-2.0
Tavily / Firecrawl	第三方 SaaS 抓取服务（插件仅调用其公开 API，不打包）	各服务商服务条款
react / tsdown / typescript / vitest	构建与测试工具链	MIT 系