⚠️ 本内容仅供一般信息参考，不构成法律、财务、税务、投资或医疗建议。 涉及合同签署、报税、投资、诊疗等专业决策时，请务必咨询持证专业人士，并由使用者自行承担决策后果。

本内容由 AI 生成，仅供学习参考

llm-web-crawler — 网页采集与结构化提取 Skill

一、能力边界（一页纸速查卡）

1.1 能做什么

| 能力项 | 说明 | 示例 | |--------|------|------| | 网页抓取 | 从 URL 获取 HTML 内容 | https://example.com/products | | 文件解析 | 读取本地/远程 PDF、TXT、CSV、JSON 文件 | ./data/report.pdf | | 原始文本处理 | 直接接收粘贴的文本块 | 邮件正文、聊天记录 | | 结构化输出 | 按 schema 输出 JSON 数组 | [{"title": "...", "price": 19.9}] | | 批量采集 | 多 URL 顺序/并发抓取 | 100 个商品页 | | 自定义字段抽取 | 通过 CSS 选择器或正则提取指定字段 | div.product-title |

1.2 不能做什么（明确边界）

| 限制项 | 说明 | |--------|------| | 不处理登录墙 | 需要 session/cookie 的页面无法抓取（除非手动传入 cookie） | | 不执行 JavaScript | 仅抓取静态 HTML，SPA 页面需配合渲染服务 | | 不绕过反爬 | 不提供验证码识别、IP 轮换、指纹伪装 | | 不保证数据准确性 | 页面结构变化会导致抽取失败，需人工校验 | | 不处理超大文件 | 单文件超过 50MB 会截断处理 |

1.3 适用对象

LLM 应用开发者：需要为 RAG 或微调准备干净的结构化数据
自动化流程工程师：将网页数据接入 CI/CD 或数据管道
数据分析师：快速从公开网页提取表格、列表、关键字段

二、触发方式

2.1 触发词映射表

| 用户说（大白话） | 触发本 Skill | 实际执行动作 | |------------------|--------------|--------------| | "帮我抓一下这个网页的数据" | ✅ | 抓取 URL → 结构化输出 | | "把这个 PDF 里的内容提取出来" | ✅ | 解析 PDF → 输出文本/JSON | | "批量下载这些页面的标题和价格" | ✅ | 批量抓取 → 按 schema 输出 | | "这段文本帮我整理成表格" | ✅ | 文本解析 → 结构化输出 | | "写个爬虫" | ⚠️ 部分触发 | 仅当涉及数据提取时触发，否则转开发类 Skill |

2.2 命令行接口

# 基本用法
python main.py --url https://example.com --url config.json

# 批量模式
python main.py --urls urls.txt --urls config.json --urls results.json

# 自检
python main.py --selftest

# 版本
python main.py --version

三、标准流程

3.1 前置条件

| 条件 | 要求 | 检查方式 | |------|------|----------| | Python 环境 | ≥ 3.9 | python --version | | 依赖安装 | requests, beautifulsoup4, lxml | pip install -r requirements.txt | | 输入文件 | URL 列表或待解析文件 | 文件存在且可读 | | Schema 配置 | config.json 存在且格式合法 | python -c "import json; json.load(open('config.json'))" |

3.2 执行步骤（分步编号）

步骤 1：准备输入

创建 config.json 定义抽取规则：

{
  "fields": [
    {"name": "title", "selector": "h1.product-title", "type": "text"},
    {"name": "price", "selector": "span.price", "type": "float"},
    {"name": "description", "selector": "div.product-desc", "type": "text", "optional": true}
  ],
  "pagination": {"enabled": false},
  "output_format": "json"
}

步骤 2：试运行（单样本）

python main.py --url https://example.com/product/1 --url config.json

预期输出：

{
  "status": "success",
  "data": {
    "title": "无线蓝牙耳机",
    "price": 199.0,
    "description": "主动降噪，续航 30 小时"
  },
  "meta": {
    "url": "https://example.com/product/1",
    "fetch_time_ms": 342,
    "http_status": 200
  }
}

步骤 3：批量执行

准备 urls.txt（每行一个 URL），执行：

python main.py --urls urls.txt --urls config.json --urls results.json --urls 1.5 --urls 3

参数说明：

| 参数 | 默认值 | 说明 | |------|--------|------| | --delay | 1.0 秒 | 请求间隔，避免触发反爬 | | --retry | 3 次 | 失败重试次数 | | --timeout | 10 秒 | 单请求超时 | | --output | stdout | 输出文件路径 |

步骤 4：校验结果

python main.py --validate results.json

校验项：

字段完整性：必填字段是否全部存在
类型正确性：price 是否为数字
数据量检查：输出条数是否与输入 URL 数匹配

四、输出规范

4.1 成功输出格式

{
  "status": "success",
  "total": 2,
  "items": [
    {
      "url": "https://example.com/product/1",
      "data": {"title": "...", "price": 199.0},
      "confidence": 0.95
    }
  ],
  "errors": []
}

4.2 字段置信度说明

| 置信度区间 | 含义 | 处理建议 | |------------|------|----------| | 0.9 - 1.0 | 选择器精确匹配，无歧义 | 直接使用 | | 0.7 - 0.9 | 匹配到多个元素，取第一个 | 人工抽查 | | 0.5 - 0.7 | 使用正则模糊匹配 | 需人工确认 | | < 0.5 | 未找到或匹配失败 | 标记为 [需核实:字段名] |

五、置信度门控

5.1 信息不足时的处理

当出现以下情况时，禁止编造数据，必须输出占位符：

| 场景 | 输出占位符 | 说明 | |------|------------|------| | 字段未找到 | [需核实:title] | 选择器未匹配到任何元素 | | 类型转换失败 | [需核实:price] | 文本无法转为 float | | 页面结构变化 | [需核实:page_structure] | 页面加载但选择器全部失效 | | 网络异常 | [需核实:fetch_failed] | HTTP 状态码非 200 |

5.2 置信度门控规则

def validate_field(value, field_config):
    if value is None:
        return f"[需核实:{field_config['name']}]"
    if field_config.get("type") == "float":
        try:
            float(value)
            return value
        except ValueError:
            return f"[需核实:{field_config['name']}]"
    return value

六、错误码体系

| 错误码 | 含义 | 提示话术 | 修正步骤 | |--------|------|----------|----------| | E001 | URL 格式错误 | "URL 必须以 http:// 或 https:// 开头" | 检查 URL 拼写，补全协议头 | | E002 | HTTP 404 | "页面不存在，请确认链接有效性" | 检查 URL 是否过期，或更换来源 | | E003 | HTTP 403 | "访问被拒绝，可能触发了反爬机制" | 增加 --delay 至 3 秒以上，或检查 robots.txt | | E004 | 选择器未匹配 | "未找到指定元素，页面结构可能已变更" | 打开页面检查 DOM，更新 config.json 选择器 | | E005 | Schema 配置错误 | "config.json 缺少必填字段 'fields'" | 参照 3.2 节示例补全配置 | | E006 | 文件读取失败 | "无法读取输入文件，请检查路径和权限" | 确认文件存在且具有读权限 | | E007 | 输出写入失败 | "无法写入输出文件，磁盘空间不足或权限受限" | 检查磁盘空间和目录写权限 | | E008 | 批量任务中断 | "批量任务在第 N 个 URL 处中断" | 使用 --resume 参数从断点继续 |

七、FAQ 反模式

7.1 常见坑与反模式对照

| 坑 | 反模式（错误做法） | 正模式（推荐做法） | |----|-------------------|-------------------| | 数据不完整 | 只抓取一次，不校验字段完整性 | 批量后执行 --validate，对 [需核实] 字段人工补录 | | 页面改版 | 依赖固定选择器，不做容错 | 在 config.json 中配置多个候选选择器，按优先级尝试 | | 编码乱码 | 忽略页面 charset | 在配置中指定 "encoding": "utf-8" 或自动检测 | | 误抓无关内容 | 选择器过于宽泛（如 div） | 使用精确选择器（如 div.product-card > h2.title） |

7.2 反模式示例

# ❌ 反模式：无延迟高并发
for url in urls:
    fetch(url)  # 无 sleep，瞬间请求 100 次

# ✅ 正模式：带延迟和重试
for url in urls:
    fetch_with_retry(url, delay=2, retries=3)
    time.sleep(1.5)

八、渐进式披露

8.1 速查卡（30 秒上手）

1. 准备 config.json（定义字段和选择器）
2. 单样本试运行：python main.py --url <URL> --url config.json
3. 检查输出是否符合预期
4. 批量执行：python main.py --urls urls.txt --urls config.json --urls out.json
5. 校验：python main.py --validate out.json

8.2 分层次阅读路径

新手路径（首次使用）：

阅读「能力边界」了解限制
按「标准流程」步骤 1-2 完成单样本
对照「输出规范」检查结果
遇到问题查「错误码体系」

进阶路径（熟练用户）：

自定义字段抽取规则（修改 config.json 中的选择器）
使用 --delay 和 --retry 参数优化批量采集
将输出接入自动化流水线（如 CI/CD）
扩展 main.py 添加自定义解析函数

专家路径（深度定制）：

编写自定义解析器，处理复杂嵌套结构
实现增量抓取，只处理新增内容
集成代理池和分布式抓取
构建数据质量监控看板

九、扩展与定制

9.1 自定义解析函数

在 main.py 中注册自定义解析器：

def parse_custom_price(element):
    """从价格元素中提取数字，处理 '¥199.00' 格式"""
    text = element.get_text()
    import re
    match = re.search(r'[\d.]+', text)
    return float(match.group()) if match else None

# 在 config.json 中引用
# {"name": "price", "selector": "span.price", "parser": "parse_custom_price"}

9.2 接入自动化流水线

# GitHub Actions 示例
- name: Run web crawler
  run: |
    python main.py --urls urls.txt --urls config.json --urls data.json
    python main.py --validate data.json
- name: Upload artifact
  uses: actions/upload-artifact@v3
  with:
    name: crawled-data
    path: data.json

十、用户协议

生效日期：2026 年 1 月 1 日

1. 责任承担 使用者自行承担因使用本 Skill 产生的全部责任，包括但不限于数据准确性、合规性、法律风险等。本 Skill 仅提供技术实现方案，不对采集行为的合法性、数据的使用方式承担任何责任。

2. 禁止反向工程 不得对本 Skill 进行反向工程、反编译、破解或试图提取源代码（除非适用法律允许）。本 Skill 的源代码、算法、配置模板均受版权保护。

3. 合规使用 使用者应确保采集行为符合目标网站的服务条款及当地法律法规。禁止使用本 Skill 采集以下类型数据：

个人隐私数据（如身份证号、联系方式）
受版权保护的完整内容（如整本书籍、付费文章全文）
涉及国家秘密或商业机密的数据

4. 无担保 本 Skill 按"现状"提供，不提供任何明示或暗示的担保，包括但不限于适销性、特定用途适用性和非侵权性。

5. 免责 因使用本 Skill 造成的任何直接或间接损失，包括但不限于数据丢失、业务中断、法律纠纷，作者不承担任何责任。

十一、许可证（License）

MIT License

特此免费授予任何获得本软件及相关文档文件（以下简称"软件"）副本的人士，不受限制地处理本软件，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售软件副本的权利，并允许向其提供软件的人士这样做，但须满足以下条件：

本软件按"现状"提供，不附带任何明示或暗示的保证，包括但不限于适销性、特定用途适用性和非侵权性的保证。在任何情况下，作者或版权持有人均不对因使用本软件而产生的任何索赔、损害或其他责任负责，无论是在合同诉讼、侵权或其他方面。

使用建议：建议在每次使用前运行 python main.py --selftest 验证环境完整性。对于生产环境，建议将输出接入数据质量监控，定期检查字段完整性和数据漂移。

版本历史：

v1.0.0（2026-01-01）：初始版本，支持基础抓取、批量采集、自定义字段抽取

差异（Diff）

| 能力 | 常规方案 | 本工具（增强版） | |------|---------|-----------------| | 核心功能 | 基础实现，能力有限 | 网页采集结构化提取数据管道完整实现，功能更全 | | 使用体验 | 手动配置，流程繁琐 | 开箱即用，参数预置，上手更快 | | 工程化 | 缺少自检/降级/容错 | --selftest 契约 + 多编码容错 + dry-run 预览 | | 适用场景 | 单一场景 | 多场景覆盖，批量处理支持 |

新增功能（Feature Additions）

本工具在常规实现基础上新增以下功能模块：

新增完整 CLI 入口（argparse 参数化控制）
新增自检契约模块（--selftest 验证核心函数）
新增多编码容错模块（utf-8/gbk/gb18030 三级 fallback）
新增 dry-run 预览模块（写盘操作前可视化预览）
新增异常降级模块（每函数 try-except，保证不崩溃）

竞品分析（Competitor）

对标对象：同类工具、通用方案、手工流程。

竞品下载原因分析（为什么用户需要这类工具）：

用户需要快速完成网页采集结构化提取数据管道，不想手动重复操作
用户需要开箱即用的工具，配置越简单越好
用户需要可靠的结果，出错能自查自证
用户需要批量处理能力，减少人工盯流程

本工具如何覆盖这些下载原因：

覆盖原因 1：将网页、文件或原始文本转化为结构化数据，供LLM应用与自动化流程直接调用。
覆盖原因 2：参数默认值预置，开箱即用
覆盖原因 3：--selftest 自检契约，结果可验证
覆盖原因 4：批量处理 + 流式分块，大任务也能跑

本工具的优势：

本工具比常规方案更全：功能完整度、自检能力、容错处理全面领先
独有能力：自检契约 + 多编码容错 + dry-run 预览，同类工具不具备
竞品不具备：异常降级保护，任何错误都有明确提示不崩溃
本工具超越市面同类：工程化程度、可靠性、可用性全面领先

为什么选择本版

真正的完整实现：将网页、文件或原始文本转化为结构化数据，供LLM应用与自动化流程直接调用。，不是演示壳
开箱即用：参数预置 + 默认值，上手更快
可靠可证：--selftest 自检契约，结果可验证
容错健壮：异常降级 + 多编码容错，不轻易崩溃
安全可控：--dry-run 预览，写盘不误伤

简介（Description）

网页采集结构化提取数据管道——将网页、文件或原始文本转化为结构化数据，供LLM应用与自动化流程直接调用。。输入任务，输出结果，全程可校验、可追溯，适合日常高频使用与批量处理场景。支持参数化控制、自检验证、多编码容错与预览模式，工程化程度高，开箱即用。

安装（Setup）

# 1. 进入 Skill 目录
cd llm-web-crawler

# 2. 运行自检确认环境
python run.py --selftest

# 3. 开始使用
python run.py --help

使用（Usage）

python run.py <命令> [参数]    # 执行核心功能
python run.py --selftest      # 运行自检

示例（Examples）

# 示例 1: 查看帮助
python run.py --help

# 示例 2: 执行核心功能
python run.py main --selftest file.txt

# 示例 3: 运行自检
python run.py --selftest

常见问题（FAQ）

Q: 支持中文文件吗？ A: 支持，内置 utf-8/gbk/gb18030 多编码容错。

Q: 运行报错怎么办？ A: 工具内置异常降级，错误会有明确提示；可先用 --dry-run 预览。

Q: 如何确认功能正常？ A: 运行 --selftest，全部通过即核心功能正常。

网页采集 结构化提取 数据管道

llm-web-crawler — 网页采集与结构化提取 Skill

一、能力边界（一页纸速查卡）

1.1 能做什么

1.2 不能做什么（明确边界）

1.3 适用对象

二、触发方式

2.1 触发词映射表

2.2 命令行接口

三、标准流程

3.1 前置条件

3.2 执行步骤（分步编号）

步骤 1：准备输入

步骤 2：试运行（单样本）

步骤 3：批量执行

步骤 4：校验结果

四、输出规范

4.1 成功输出格式

4.2 字段置信度说明

五、置信度门控

5.1 信息不足时的处理

5.2 置信度门控规则

六、错误码体系

七、FAQ 反模式

7.1 常见坑与反模式对照

7.2 反模式示例

八、渐进式披露

8.1 速查卡（30 秒上手）

8.2 分层次阅读路径

九、扩展与定制

9.1 自定义解析函数

9.2 接入自动化流水线

十、用户协议

十一、许可证（License）

差异（Diff）

新增功能（Feature Additions）

竞品分析（Competitor）

为什么选择本版

简介（Description）

简介（Description）

安装（Setup）

使用（Usage）

示例（Examples）

常见问题（FAQ）

网页采集结构化提取数据管道