前言¶

给智能体接搜索 API，往往只能拿到链接列表，缺少统一的正文读取与合规约束；单独写爬虫则能读页面，却又不一定遵守 robots.txt，也很难和对话里的「检索—阅读」闭环对齐。DeepSeek Harness（DSH）把能力拆成可安装的插件；在「联网工具」这一类里，维护者 JiamingShi-JsPhys 发布的 web-forager 试图用同一套引擎同时解决检索、解析输出和合规边界问题。下文介绍它的定位、能力与在 DSH 中的安装与用法。社区目录页见 SkillHub，源码与文档见 GitHub 仓库（当前版本 1.2.0）。

这是什么¶

web-forager 是自研实现的公开网页信息采集工具包：在 HTTP 模式下尊重 robots.txt、按站点限速，把搜索结果、单页、站点地图和部分平台内容转成统一的 Markdown 记录；在浏览器模式下通过可插拔桥接真实浏览器，覆盖需要渲染或登录态的只读场景。它提供 CLI、两个 MCP 服务，以及 Claude Code 技能；在 DSH 侧作为单一插件打包（package.json 中通过 cordis.patch.yml 参与 bundle），CLI、mcp_server.py、browser/ 与 SKILL.md 共用同一引擎，不宜拆目录使用。

插件自述用途为学习与信息采集；用户须遵守目标站服务条款与版权法，不得用于恶意并发攻击，也不得收集、推断可识别个人的信息用于骚扰等用途（详见仓库 Disclaimer）。

核心功能¶

HTTP 模式¶

所有请求经统一的 HttpFetcher：检查 robots 策略、缓存、重试与退避、按来源限速及体积上限，再交给对应提取器。支持的能力包括：

1. 多引擎搜索：360、Bing、搜狗及搜狗微信；以中日韩文字为主的查询在默认 auto 下会并行询问 360、搜狗与搜狗微信。
2. 单页与本地文件：读取 HTML，以及 PDF、DOCX、XLSX、EPUB、CSV、RSS/Atom 等；长页可按标题分块（--chunk-size）。
3. B 站 HTTP 适配：专用 bili 动作；其他如知乎、微博、豆瓣等多数按通用 HTML 管道处理。
4. 可恢复的链接探索：surf 只跟随页面中已有的 <a href>，不猜 URL、不提交表单、不执行页面 JavaScript；支持会话名断点续游。
5. 站点地图：map 从 robots.txt 的 Sitemap:、sitemap index 与 .xml.gz 发现 URL。
6. 学术查询（可选）：通过文档化 API 查询 arXiv、Crossref、PubMed 或解析 DOI，而非抓取结果页。
7. 站点内搜索与订阅：find、feed 可在不依赖外部搜索引擎时，用站内搜索路径或 RSS/Atom 发现内容。

合规相关默认行为：每个 HTTP 请求前检查 robots.txt（RFC 9309 子集）、携带可联系的 User-Agent、默认每来源约每秒一发请求；不绕过登录、验证码、Cloudflare 或付费墙。

浏览器模式¶

位于 browser/，需要 Node.js 18+。通过桥（默认 browser/bridges/ 下 Playwright 桥，也可用 --bridge 或环境变量 WEB_FORAGER_BRIDGE 覆盖）与 JSON-RPC 通信；不提供自带浏览器二进制。内置 7 个只读剧本，覆盖 B 站信息流/单视频/续播链/弹幕实验、知乎与小红薯关键词挖掘，以及 B 站搜索深挖等。写操作（点赞、评论、发布等）默认拒绝；--strict-robots 可在导航前检查 robots.txt。未找到可用桥时现场运行以退出码 3 结束，而不是伪造已读页面。

统一输出契约¶

HTTP 与浏览器模式在核心字段上对齐：metadata、markdown、tables、warnings。调用方可加 --core 或 MCP 中 core: true，得到 schema_version: core-1 的共享形状；--agent 则返回稳定的 {"ok":…} 信封，便于智能体循环消费。版本 1.2.0 起：CLI 9 个动作、MCP 10 个 HTTP 工具（web_fetch、web_search、web_surf 等），浏览器 MCP 另 4 个工具。

安装与启用¶

安装前建议通读仓库 LICENSE、README 与 THIRD_PARTY_LICENSES.txt，确认以当前 DSH 进程的权限运行插件是否符合你的安全策略。

在 DSH 中安装¶

官方文档给出的 DeepSeek Harness 一行命令（安装到名为 web 的 profile，并钉在发布标签 v1.2.0）：

dsh plugin --profile web add github:JiamingShi-JsPhys/web-forager#v1.2.0

DSH 亦可通过各宿主插件市场注册本仓库 Git 地址后再安装；注册用的仓库 URL 为：

https://github.com/JiamingShi-JsPhys/web-forager

完整的一行安装命令、可选依赖与面向 Cursor 等「读规则文件」宿主的 install.py 说明见仓库内 docs/INSTALL_COMMANDS.md（或中文版 docs/INSTALL_COMMANDS_zh.md）。文档强调：CLI、两个 MCP 与技能须作为一个完整插件安装，避免把 run.py、mcp_server.py 等打散到无关目录导致导入失败。

可选依赖¶

核心 Python 依赖可通过 pip install -r requirements.txt 安装；PDF 需 pypdf，需要 JS 渲染或浏览器桥时需 Node 18+ 与 Playwright（pip install playwright && playwright install chromium，浏览器目录下亦可 npm install playwright）。缺少 Playwright 或 pypdf 时 CLI 分别以退出码 6、7 报告，而非静默失败。

典型用法¶

在 DSH 对话里¶

安装完成后，在当前工作区目录下输入 / 即可调用。技能命名空间为 web-forager；也可用插件命令缩短常用动作：

/web-forager:fetch https://example.org/article
/web-forager:scholar 10.1038/nature14539

五个命令分别对应抓取/搜索、可恢复冲浪、学术查询、站点地图发现、浏览器剧本浏览。技能示例：

/web-forager:web-forager  收集 https://www.bilibili.com/video/BV1xx411c7mD 并转成 Markdown

CLI（脚本或 CI）¶

与对话中等价的常见命令如下：

python run.py --action fetch --url "https://www.bilibili.com/video/BV1xx411c7mD"
python run.py --action fetch --query "城市漫步 攻略" --num-results 8 --max-pages 3
python run.py --action surf --url "https://www.zhihu.com/" --depth 1 --max-pages 5 --session zhihu-01
python run.py --action map --url "https://example.org" --limit 500
python run.py --action bili --mode feed --max-items 10

需要将结果写入工作区时，可使用 --root <WS>，输出落在 process/web-forager/ 与 _broadcast/ 下（不写入用户的 material/、results/）。

浏览器剧本¶

node browser/run.js --playbook zhihu-dig --query "强化学习" --agent
node browser/run.js --playbook xhs-dig --query "城市漫步 攻略" --agent
node browser/run.js --playbook bili-video --url "https://www.bilibili.com/video/BV1xx411c7mD"

MCP¶

在宿主 MCP 配置中分别启动 mcp_server.py（HTTP 工具集）与 browser/mcp_server.js（浏览器工具集）；路径须指向插件安装后的绝对路径，保持仓库内相对布局不变。

适用场景与注意¶

适合谁：需要在智能体或分析流程中，把公开网页、文档、订阅源和部分中文平台内容稳定转成 Markdown，并希望在引擎内而不是事后补丁里处理 robots 与限速的团队或个人；典型用途包括话题监测、公开讨论归档、个人知识库素材收集等（以仓库自述为准）。

应注意：

1. 插件不替代你对目标站 ToS 与法律的判断；禁止用于绕过访问控制或对个人做画像跟踪等用途。
2. 正文来自第三方站点，准确性与版权归属由来源站决定；工具不对第三方内容负责。
3. 浏览器模式成本高于 HTTP 模式；文档建议用 --out 或 MCP 的 out 把大记录写盘，并默认避免不必要的截图。
4. 知乎、小红薯等若呈现登录墙，剧本会以 login_required（退出码 6）停止，不会尝试绕过。
5. SkillHub 等社区目录与 DeepSeek / 幻方无官方从属关系；DSH 生态理念是「一切皆插件」，安装来源以你信任的仓库与版本标签为准。

结尾¶

web-forager 把搜索、单页读取、地图发现、B 站适配与浏览器只读剧本收进同一引擎，并用统一的 Markdown 记录与智能体友好信封降低接入成本；合规策略写在抓取路径里而不是外围脚本里。若你在 DSH 中需要可审计的联网信息采集能力，可从社区目录了解条目信息，并以 GitHub 上 1.2.0 标签的仓库与 docs/INSTALL_COMMANDS.md 中的 dsh plugin 命令完成安装与验证。