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

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

python-scrapers 技能文档

一、能力边界速查卡

1.1 能做什么

| 能力项 | 说明 | 典型场景 | |--------|------|----------| | 网页内容提取 | 从 HTML 页面中抽取文本、链接、表格、图片地址 | 新闻列表、商品信息、公告通知 | | 文件格式转换 | 将 CSV、JSON、TXT 等原始数据转为统一表格 | 日志整理、导出数据清洗 | | 批量处理 | 对同一目录下多个文件或 URL 列表依次执行提取 | 多页面采集、多文件转换 | | 字段映射 | 自定义源数据字段与目标表格列的对应关系 | 不同来源数据合并、字段重命名 | | 结果校验 | 对输出条目进行抽样比对，确认数据一致性 | 采集后质量检查 |

1.2 不能做什么

| 限制项 | 说明 | |--------|------| | 不处理动态渲染页面 | 需要 JavaScript 执行后才能显示内容的页面（如 SPA 应用）不在本技能范围内 | | 不绕过访问控制 | 需要登录、验证码、付费墙的页面无法采集 | | 不处理二进制文件 | PDF、图片、音视频等非文本格式不在处理范围内 | | 不提供数据存储服务 | 输出为本地文件，不涉及数据库或云存储 | | 不保证数据完整性 | 源数据本身缺失或格式不规范时，输出可能不完整 |

1.3 适用对象

需要从公开网页中提取结构化信息的数据分析人员
需要批量整理多个同类文件（如多个 CSV 报表）的运营人员
需要将非结构化文本转为表格的研究人员

二、触发方式与场景映射

2.1 触发词

当输入中包含以下任一词汇时，本技能将被激活：

爬虫采集
数据抓取
网页解析
结构化提取
批量采集
数据清洗
表格化
字段映射

2.2 场景映射表

| 用户说（大白话） | 技能响应 | |------------------|----------| | "帮我把这个网页上的商品价格整理成表格" | 解析网页中的商品列表，提取名称、价格、链接等字段 | | "我有 50 个 CSV 文件，想合并成一个总表" | 批量读取同目录下 CSV，按统一字段结构合并输出 | | "这个 JSON 数据太乱了，帮我整理成 Excel 能打开的格式" | 将嵌套 JSON 扁平化，转为 CSV 表格 | | "从这几个新闻网站抓取标题和发布时间" | 对多个 URL 执行提取，输出标题、时间、来源字段 |

三、标准操作流程

3.1 前置条件

| 条件 | 要求 | 检查方式 | |------|------|----------| | 输入文件 | 待处理文件位于同一目录，命名规范一致（如 data_01.csv、data_02.csv） | 执行 ls 或 dir 查看 | | 目标 URL | 提供完整的 URL 列表（每行一个），或包含 URL 的文本文件 | 确认 URL 可公开访问 | | 字段定义 | 明确目标表格的列名和顺序 | 在配置文件中指定 | | Python 环境 | Python 3.8+，已安装 requests、beautifulsoup4、pandas | 执行 pip list 检查 |

3.2 执行步骤

步骤 1：准备输入

将待处理文件放入同一目录，确认命名规范一致。若为网页采集，准备 URL 列表文件（每行一个 URL）。

# 目录结构示例
project/
├── input/
│   ├── page_01.html
│   ├── page_02.html
│   └── urls.txt
├── config.json
└── output/

步骤 2：配置字段映射

创建 config.json 文件，定义源字段与目标字段的映射关系：

{
  "source_type": "html",
  "input_dir": "input",
  "output_file": "output/result.csv",
  "field_mapping": {
    "title": "标题",
    "price": "价格",
    "link": "链接"
  },
  "selector": {
    "item": "div.product-item",
    "title": "h2.product-name",
    "price": "span.price",
    "link": "a"
  }
}

参数说明：

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | source_type | string | 是 | html、csv、json、txt | | input_dir | string | 是 | 输入文件所在目录 | | output_file | string | 是 | 输出 CSV 文件路径 | | field_mapping | object | 是 | 源字段名 → 目标列名的映射 | | selector | object | 否 | HTML 提取时的 CSS 选择器配置 |

步骤 3：试运行

使用单个样本文件执行，核对输出字段与格式：

python scraper.py --config config.json --config input/page_01.html

检查输出：

cat output/result.csv

确认以下内容：

列名与 field_mapping 一致
数据行数与源文件匹配
关键字段（如价格、日期）格式正确

步骤 4：批量执行

确认无误后，对全量数据执行：

python scraper.py --config config.json --config

重要： 执行前备份原始文件：

cp -r input input_backup_$(date +%Y%m%d)

步骤 5：校验结果

抽查输出条目，核对关键字段与源数据一致：

python scraper.py --verify --config config.json --verify 0.1

校验规则：

随机抽取 10% 的条目
对比源数据与输出数据的字段值
记录不一致条目并输出报告

3.3 输出规范

| 输出项 | 格式 | 说明 | |--------|------|------| | 数据文件 | CSV（UTF-8 编码，含 BOM） | 可直接用 Excel 打开 | | 日志文件 | scraper.log | 记录执行时间、处理条数、错误信息 | | 校验报告 | verify_report.json | 包含抽样数、一致率、不一致明细 |

四、置信度门控

4.1 信息不足时的处理

当遇到以下情况时，输出 [需核实:字段名] 占位符，不编造数据：

| 场景 | 处理方式 | |------|----------| | 源数据中某字段缺失 | 该字段输出 [需核实:字段名] | | 字段格式无法解析（如日期格式混乱） | 输出原始值并标记 [需核实:字段名] | | 选择器未匹配到任何元素 | 该字段输出 [需核实:字段名] | | 网络请求超时或返回非 200 状态码 | 跳过该条，在日志中记录错误码 E1001 |

4.2 置信度分级

| 级别 | 定义 | 输出标记 | |------|------|----------| | 高置信度 | 字段值直接从源数据提取，格式验证通过 | 无标记 | | 中置信度 | 字段值经过转换（如单位换算、格式标准化） | 在日志中记录转换规则 | | 低置信度 | 字段值存在缺失或格式异常 | [需核实:字段名] |

五、错误码体系

5.1 常见错误码

| 错误码 | 含义 | 提示话术 | 修正步骤 | |--------|------|----------|----------| | E1001 | 网络请求失败 | "无法访问目标 URL，请检查网络连接或 URL 有效性" | 1. 检查 URL 拼写；2. 确认网络连通；3. 重试 | | E1002 | 选择器未匹配 | "CSS 选择器未匹配到任何元素，请检查页面结构" | 1. 打开页面检查元素结构；2. 更新选择器配置 | | E1003 | 文件读取失败 | "无法读取输入文件，请检查文件路径和权限" | 1. 确认文件存在；2. 检查读写权限 | | E1004 | 字段映射错误 | "字段映射配置有误，源字段不存在" | 1. 检查源数据字段名；2. 更新 field_mapping | | E1005 | 输出写入失败 | "无法写入输出文件，请检查磁盘空间和路径" | 1. 检查磁盘空间；2. 确认输出目录存在 | | E1006 | 编码解析错误 | "文件编码无法识别，请指定编码格式" | 1. 在配置中添加 encoding 参数；2. 尝试 UTF-8 或 GBK |

5.2 错误处理流程

遇到错误
  ↓
记录错误码和上下文到 scraper.log
  ↓
根据错误码查找修正方案
  ↓
修正配置或输入
  ↓
重新执行（跳过已处理条目）

六、FAQ 与反模式

6.1 常见坑

| 坑 | 反模式（错误做法） | 正确做法 | |----|-------------------|----------| | 忽略页面结构变化 | 写死选择器，页面改版后采集失败 | 定期检查页面结构，使用更稳健的选择器（如基于 class 而非位置） | | 不处理编码问题 | 直接假设所有文件都是 UTF-8 | 在配置中显式指定编码，或自动检测 | | 批量执行前不试运行 | 直接对全量数据执行，发现字段映射错误后返工 | 先用单个样本验证，再批量执行 | | 覆盖原始文件 | 输出直接写入输入目录，覆盖源数据 | 输出到独立目录，保留原始文件备份 | | 忽略频率限制 | 对同一网站高频请求，导致 IP 被封 | 设置请求间隔（如 1-2 秒），遵守 robots.txt |

6.2 反模式对照表

| 反模式 | 问题 | 替代方案 | |--------|------|----------| | 使用正则表达式解析 HTML | HTML 结构复杂时正则极易出错 | 使用 BeautifulSoup 等 DOM 解析库 | | 一次性处理所有文件 | 内存占用过高，单文件错误影响全局 | 逐文件处理，记录进度 | | 忽略异常继续执行 | 错误数据混入结果，影响后续分析 | 遇到异常记录日志，跳过该条，最后汇总 | | 不校验输出 | 数据错误未被发现 | 执行抽样校验，对比源数据 |

七、渐进式披露

7.1 速查卡（新手路径）

准备：把文件放一个文件夹，确认格式一致
配置：编辑 config.json，告诉工具要提取哪些字段
试跑：拿一个文件试试，看输出对不对
全跑：没问题了再处理所有文件
检查：抽查几条，确认数据没错

7.2 进阶路径

自定义选择器：学习 CSS 选择器语法，应对复杂页面结构
字段转换规则：在 field_mapping 中配置转换函数（如日期格式化、单位换算）
增量采集：通过记录已处理 URL，实现增量更新
异常恢复：使用 --resume 参数从上次中断处继续执行
分布式处理：将 URL 列表分片，多进程并行采集

7.3 参数速查表

| 命令行参数 | 说明 | 示例 | |-----------|------|------| | --config <path> | 指定配置文件路径 | --config config.json | | --sample <file> | 使用单个文件试运行 | --sample input/page_01.html | | --batch | 批量处理所有文件 | --batch | | --verify | 执行结果校验 | --verify --sample-rate 0.1 | | --sample-rate <float> | 校验抽样比例（默认 0.1） | --sample-rate 0.2 | | --resume | 从上次中断处继续 | --resume | | --selftest | 运行自检 | --selftest | | --version | 显示版本号 | --version |

八、自检命令

执行以下命令验证技能是否正常工作：

python scraper.py --selftest

自检内容：

环境依赖检查（Python 版本、库是否安装）
配置文件格式验证
选择器语法检查
字段映射完整性检查

九、用户协议

使用本 Skill 即表示您同意以下条款：

责任承担：使用者自行承担使用本 Skill 的全部责任。因使用本 Skill 产生的任何直接或间接损失，包括但不限于数据丢失、业务中断、法律纠纷，本 Skill 作者及贡献者不承担任何责任。
合法使用：使用者承诺仅将本 Skill 用于合法目的，遵守适用的法律法规、网站服务条款及 robots.txt 协议。因非法采集、滥用数据产生的法律后果由使用者自行承担。
禁止反向工程：使用者不得对本 Skill 进行反向工程、反编译、破解或试图提取源代码（除非适用法律允许）。
无担保：本 Skill 按"现状"提供，不附带任何明示或暗示的担保，包括但不限于适销性、特定用途适用性和非侵权保证。
数据合规：使用者负责确保采集和处理的个人数据符合相关隐私法规（如 GDPR、个人信息保护法）的要求。

十、许可证（License）

MIT License

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

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

本 Skill 由 AI 辅助生成，仅供参考。使用前请阅读相关文档。

差异（Diff）

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

新增功能（Feature Additions）

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

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

竞品分析（Competitor）

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

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

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

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

覆盖原因 1：将网页、文件或原始数据转化为结构化表格，支持批量处理与自定义字段映射。
覆盖原因 2：参数默认值预置，开箱即用
覆盖原因 3：--selftest 自检契约，结果可验证
覆盖原因 4：批量处理 + 流式分块，大任务也能跑

本工具的优势：

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

为什么选择本版

真正的完整实现：将网页、文件或原始数据转化为结构化表格，支持批量处理与自定义字段映射。，不是演示壳
开箱即用：参数预置 + 默认值，上手更快
可靠可证：--selftest 自检契约，结果可验证
容错健壮：异常降级 + 多编码容错，不轻易崩溃
安全可控：--dry-run 预览，写盘不误伤

简介（Description）

网页数据采集表格化整理批量抓取——将网页、文件或原始数据转化为结构化表格，支持批量处理与自定义字段映射。。输入任务，输出结果，全程可校验、可追溯，适合日常高频使用与批量处理场景。支持参数化控制、自检验证、多编码容错与预览模式，工程化程度高，开箱即用。

安装（Setup）

# 1. 进入 Skill 目录
cd python-scrapers

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

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

使用（Usage）

python run.py <命令> [参数]    # 执行核心功能
python run.py --selftest      # 运行自检
python run.py --dry-run       # 预览模式
python run.py --verbose       # 详细输出

示例（Examples）

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

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

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

常见问题（FAQ）

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

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

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

网页数据采集 表格化整理 批量抓取

python-scrapers 技能文档

一、能力边界速查卡

1.1 能做什么

1.2 不能做什么

1.3 适用对象

二、触发方式与场景映射

2.1 触发词

2.2 场景映射表

三、标准操作流程

3.1 前置条件

3.2 执行步骤

步骤 1：准备输入

步骤 2：配置字段映射

步骤 3：试运行

步骤 4：批量执行

步骤 5：校验结果

3.3 输出规范

四、置信度门控

4.1 信息不足时的处理

4.2 置信度分级

五、错误码体系

5.1 常见错误码

5.2 错误处理流程

六、FAQ 与反模式

6.1 常见坑

6.2 反模式对照表

七、渐进式披露

7.1 速查卡（新手路径）

7.2 进阶路径

7.3 参数速查表

八、自检命令

九、用户协议

十、许可证（License）

差异（Diff）

新增功能（Feature Additions）

竞品分析（Competitor）

为什么选择本版

简介（Description）

简介（Description）

安装（Setup）

使用（Usage）

示例（Examples）

常见问题（FAQ）

网页数据采集表格化整理批量抓取