web-crawl

技能：web-crawl

抓取网页并将其转换为整洁的 Markdown，供 wiki / 大模型使用。后端是一个隔离的适配器（harness/web-crawl.config.yaml，verified:false）——内置功能现已可用，无需密钥。

WHAT

目的和上下文

• **目的：**将 URL（或网站）转换为整洁的 Markdown，并保存到 raw/ 或 wiki 草稿中，绝不保存原始 HTML。
• 触发条件（何时使用）：
  • 用户提供 URL 并需要其内容（“抓取这个”“提取内容”“获取页面”“读取这个页面”）。
  • 将外部文档 / 文章导入 raw/ 或 wiki 草稿。
  • 为研究批量读取多个页面（此时优先使用高级后端）。
• **非目标：**不克隆页面的 UI / 外观（那是 /web-clone）；不直接写入 wiki/（应通过 /propose / ingest）；不抓取有身份验证限制或禁止访问的内容。

心智模型

URL → 后端（会话内 WebFetch · 内置 urllib+regex · 高级适配器 firecrawl/crawl4ai/jina）→ markdown → raw/ 或 wiki 草稿 → /propose 或 ingest → wiki。后端采用先构建、后适配的隔离设计：内置后端 = 离线备用方案，高级后端 = 通过一个配置文件接入的真正升级方案。

输入和输出约定

	字段	必填？	含义
输入	URL	是	要抓取的页面或网站；或者在 md 模式下使用本地 .html 文件
输入	--out 路径	否	保存位置；约定为 raw/<slug>.md
输入	高级后端配置	否	harness/web-crawl.config.yaml 中的 backend + api_key_env/endpoint + verified:true
输出	markdown 文件	是	raw/ 中的整洁文本或 wiki 草稿
输出	后端说明	是	说明生成内容的后端；注明内置后端的质量限制，绝不冒充高级后端

规则和功能

• RULE-01（必须）：输出 Markdown，而非原始 HTML——这正是目的所在（节省 token + 文本整洁）。
• RULE-02（必须）：遵守 robots.txt / 网站条款；不得抓取有身份验证限制或禁止访问的内容。
• RULE-03（必须）：内置后端是离线备用方案；高级后端是 BNAL 适配器——绝不能把未接入的高级后端说成可用。
• RULE-04（必须）：自测：python3 harness/scripts/web-crawl.py --self-test。
• 功能：出站 HTTP 抓取（或在会话内使用可渲染 JS 的网页抓取）；HTML→markdown 转换；仅写入 raw/ 或 wiki 草稿。

失败边界

• 网站由 JS 渲染且仅有内置后端可用 → 部分完成（内置后端无法渲染 JS）；优先使用会话内 WebFetch 或接入高级后端。
• 请求抓取整个网站，但未接入高级后端 → 配置未就绪，无法执行（内置后端仅支持单页）；应如实说明，不得伪装完成。
• robots.txt / 网站条款禁止访问，或页面有身份验证限制 → 无法执行，不得抓取。
• 抓取错误 → 失败，报告 URL 和错误。

HOW

主要工作流

步骤	类型	输入	操作	输出/退出	失败/下一步
W01	判断	URL、会话类型	在 Agent 会话中处理 JS 密集型 / 渲染后的网站 → WebFetch 工具（B01）	markdown	不在会话中 → W02
W02	执行	URL	脚本处理单个静态页面：内置 web-crawl.py fetch（或处理本地 HTML 的 md）	raw/<slug>.md	需要 JS / 整站处理 → W03
W03	执行	配置	真正的抓取 → 在 harness/web-crawl.config.yaml 中接入高级后端，将 verified:true 切换为启用（B02）	高级后端输出	未接入 → 说明限制，不要声称已完成
W04	执行	markdown	保存到 raw/ 或知识库草稿，然后运行 /propose / ingest	文件已保存	绝不直接写入 wiki/

各步骤详情（W01–W04 的事实来源）：

1. JS 密集型 / 渲染后的网站？ 在 Agent 会话中，优先使用会话内的 WebFetch 工具 （它会渲染 JS 并返回 markdown）。这是信息最丰富的路径，无需设置。
2. 脚本处理单个静态页面（离线、无需密钥）： python3 harness/scripts/web-crawl.py fetch "<URL>" --out raw/<slug>.md ⚠️ builtin 后端有意设计为基础功能：通过 urllib 获取内容，再用正则将 HTML 转为 markdown —— 不渲染 JS、 仅处理单个页面、没有智能提取。它是离线备用方案，不具备 Firecrawl 级别的质量。 已经下载了本地 HTML？使用 web-crawl.py md <file.html>。
3. 真正的抓取（JS 渲染、整站处理、干净提取）→ 接入真正的引擎： 高级后端才是质量所在 —— 在 harness/web-crawl.config.yaml 中设置 backend: firecrawl|crawl4ai|jina 和 api_key_env/endpoint， 然后将 verified:true 切换为启用。Firecrawl（托管服务，可将抓取内容转为 markdown，token 用量减少约 5–10 倍，并提供用于 Agent 循环的 MCP），或 Crawl4AI（开源、可自托管，支持自适应选择器）。内置后端让技能 今天就能运行；这些才是真正的升级方案。
4. 保存： 将 markdown 保存到 raw/（人工收件箱）或知识库草稿，然后运行 /propose / ingest 将提炼后的内容加入知识库 —— 绝不要直接写入 wiki/（R1/R2）。

分支

ID	类型	条件	行为	跳过 / 失败	汇合
B01	可选能力	正在 Agent 会话中运行，且 WebFetch 可用；页面为 JS 密集型	使用 WebFetch，而不是内置脚本	没有 WebFetch → W02 内置后端（不渲染 JS，内容不完整）	W04
B02	可选能力	已配置高级后端且 verified:true	通过 firecrawl/crawl4ai/jina 适配器抓取（JS、整站）	未接入 → 继续使用内置后端，并说明其限制（RULE-03）	W04
B03	用户可选	已下载本地 HTML	使用 web-crawl.py md <file.html>，而不是 fetch	—	W04

验证与停止条件

运行 python3 harness/scripts/web-crawl.py --self-test 并通过，即表示后端运行正常。当 markdown 文件已存在于 raw/ 或草稿中，且回复中说明了所用后端时，即可视为完成。内置后端输出的质量（提取效果、JS 内容）仅供审核，不作保证。

示例

• 正向：“将 https://example.com/blog/post 抓取到 raw”（静态页面，无需密钥）→ python3 harness/scripts/web-crawl.py fetch "https://example.com/blog/post" --out raw/example-post.md → 保存 markdown，然后建议运行 ingest。
• **边界/失败：**当 verified:false 时要求“抓取整个文档站点” → 内置后端只能处理单个页面 → 说明必须在 harness/web-crawl.config.yaml 中接入高级后端；不要声称已抓取整个站点。

参考 — 相关内容

• harness/scripts/web-crawl.py + harness/web-crawl.config.yaml（后端适配器）。
• 真正的引擎（升级方案）： Firecrawl（github.com/mendableai/firecrawl，托管服务 + MCP）、 Crawl4AI（github.com/unclecode/crawl4ai，开源、可自托管）、Jina Reader。MinerU（你收藏的项目）适用于 PDF/文档。
• /web-clone — 当你想要的是页面的 UI / 外观，而不是文本时使用。
• build-now-adapt-later — 此后端遵循的隔离模式。