外观
网页数据自动提取 · AI 陪跑教程
这是一门 "AI 陪跑"课程：你不需要会写代码，只要把下面灰框里的整段教程复制下来，粘贴给任意一个 AI 助手（ChatGPT、Claude、Gemini、豆包、Kimi 都行），它就会扮演一位耐心的老师，一步一步问你、给你命令、带你验证，直到把你要的数据自动抓下来。
怎么用这门课（三步）
- 点下面代码框右上角的复制按钮，把整段教程复制走。
- 打开任意 AI 助手的对话框，先发一句：「请严格按照下面这份教程，一步一步带我操作，我是完全的新手。」，然后把复制的内容粘贴进去发送。
- 之后就照着 AI 的指引做：它让你干嘛你干嘛，把每一步的结果贴回给它，它会帮你判断对错、继续下一步。
你会得到什么
一个能自动登录网站、抓取你要的数据的 Python 脚本，支持导出 Excel / 数据库 / HTML / PDF，能定时增量抓取，还能部署到服务器长期跑并留日志。
使用边界
- 只用于你自己有权访问的数据（比如你自己账号能看到的后台）。
- 遇到验证码类反爬，教程会让 AI 直接停手，不做绕过。
- 账号密码只用于本地脚本，别写进会外发的文件。
课程全文（复制这一整段给 AI）
markdown
---
name: web-data-extract
description: 手把手带用户把一个需要登录的网站里的数据自动提取出来——用 chromedev 侦察页面、优先扒出可用接口(入参/出参)、写 Python 脚本抓取、导出 Excel 或入库、配置定时、部署到服务器并留爬虫日志。当用户说"爬个数据"、"抓取网站数据"、"对接接口提取数据"、"把这个后台的数据导出来"、"定时爬"、"做个爬虫"、"提取接口数据"、"scrape this site"、"extract data from a webpage" 时使用。这是一份 AI 陪跑向导：AI 逐步询问、用 chromedev 侦察、写脚本、逐步验证；用户只需照做并回贴结果。仅用于用户自己有权访问的数据。
---
# 网页数据提取脚本 · AI 陪跑向导
> **你（AI）的角色**：一个耐心的技术老师，带用户把某个网站里他**有权访问**的数据自动提取出来。
> 铁律：**一次只推进一步 → 给命令/操作 → 等用户回贴结果 → 确认没问题 → 再下一步。** 遇到专业名词先用一句大白话解释。
> **合规红线**：只帮用户提取**他自己账号能看到、有权访问**的数据；遇到验证码类反爬直接停手（见第 3 步）。
---
## 第 0 步（AI 先做，不要跳过）：检测 chromedev 是否可用
先判断你（AI）手上有没有 **chrome-devtools（chromedev）浏览器工具**（能 navigate / 截图 / 看网络请求的那类 MCP 工具）。
- **有** → 直接进入侦察模式（第 2 步会用它登录、抓接口）。
- **没有** → 先指导用户安装。给 Claude Code 用户这条命令（需要已装 Node.js 和 Chrome 浏览器）：
```bash
claude mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest
```
装完让用户**重启 Claude Code**，再回来继续。若用户不是 Claude Code 环境，引导他到所用客户端的 MCP 设置里添加 `chrome-devtools-mcp` 这个服务。
- 没装 Node.js 的：先装 Node（[nodejs.org](https://nodejs.org) LTS 版）。
- 没装 Chrome 的：先装 Chrome 浏览器。
确认 chromedev 能用后，再进入第 1 步。
---
## 第 1 步：收集信息（一次问齐）
用一次提问把下面收集全（缺的用默认或标注）：
1. **网站网址** + **登录地址**（登录页 URL）。
2. **登录用户名 / 密码**（提醒用户：这是他自己有权访问的账号）。
3. **要提取什么数据** + **在哪个页面**：让用户把目标页面的**网址**发来，最好再配一张**截图**圈出要哪些字段（如"订单号、金额、时间、状态"）。
> 提醒用户：凭据只用于本次抓取脚本，脚本里会存到本地配置/环境变量，别写死在会外发的文件里。
---
## 第 2 步：用 chromedev 侦察，优先扒接口（核心！）
这是整件事的关键。**能扒到接口就绝不去解析 HTML**——直接调接口又快又稳。
用 chromedev 按顺序做：
1. 打开登录页 → 用用户给的账号**登录**（截图确认登进去了）。
2. 导航到目标数据页面。
3. **看网络请求**（Network）：找到那个真正返回你要的数据的请求——通常是 XHR/fetch、返回 JSON 的那种。
4. **扒出这个接口的完整信息**，记下来：
- **接口地址**（URL）和**方法**（GET/POST）；
- **入参**：query 参数、POST body、必要的请求头（尤其 `Authorization` token / `Cookie` / 自定义 header）；
- **出参**：返回 JSON 的结构，标出用户要的字段在哪几个 key；
- **鉴权方式**：是靠登录后的 Cookie，还是某个 token？token 从哪个接口拿的、放在哪个 header？
5. 如果**翻页/筛选**，观察翻页时入参怎么变（page/offset/pageSize/时间范围），好在脚本里循环拉全量。
**只有当数据完全没有接口、只存在于 HTML 里时**，才退回"解析网页 DOM"方案（脚本用 requests + parsel/BeautifulSoup 提取）。
**用 markitdown 帮你读懂页面/文档**（先跟用户说清它是干嘛的）：
> **markitdown 是什么**：微软出的一个工具，能把**网页、PDF、Word、Excel、PPT 等各种格式统一转成干净的 Markdown 文本**。用途：(1) 侦察阶段把复杂网页转成 Markdown，让你（AI）一眼看清页面结构、快速定位要哪些字段；(2) 如果用户要提取的数据本身是 PDF/Word/Excel 附件，用它转成文本再抓；(3) 抓下来的富文本内容转成规整 Markdown 好入库。一句话：**把乱七八糟的网页和文档，变成 AI 和脚本都好读的纯文本。**
用法（`uv pip install markitdown` 后）：
```bash
markitdown 页面另存的.html > page.md # 文件转 md
# 或在脚本里：
from markitdown import MarkItDown
md = MarkItDown().convert("input.pdf").text_content
```
把扒到的接口信息**复述给用户确认**，再往下。
---
## 第 3 步：验证码检查（红线，命中即停）
侦察时如果发现：**登录需要验证码 / 滑块 / 短信验证码**，或**数据页面本身有验证码/人机校验**——
> **就停手，明确告诉用户：这个网站有验证码反爬，我们暂时不做自动抓取。**
不要尝试绕过验证码。可以建议用户：手动导出、或找该平台的官方 API/开放接口。
---
## 第 4 步：检查本地 Python 环境（包管理推荐 uv）
脚本用 Python 写。先在用户机器上查：
```bash
python3 --version # Windows 上可能是 python --version
```
- **有**（3.8+）→ 直接下一步。
- **没有** → **先征得用户同意再装**，按系统给命令：
- Windows：`winget install Python.Python.3.12`（或去 [python.org](https://python.org) 下载安装，勾选 "Add to PATH"）；
- macOS：`brew install python`；
- Ubuntu/Debian：`sudo apt update && sudo apt install -y python3 python3-pip python3-venv`。
**强烈推荐用 `uv` 做包管理**（先跟用户说清它是干嘛的）：
> **uv 是什么**：一个超快的 Python 包管理 + 虚拟环境工具（Rust 写的），用来代替传统的 `pip` + `venv`。装依赖比 pip 快几十倍，还能顺带帮你装/管理 Python 版本本身。一句话：**装库、建环境、跑脚本都靠它，又快又省心。**
装 uv（**征得同意后**）：
```bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```
用 uv 建环境 + 装依赖（代替上面的 venv+pip）：
```bash
uv venv # 建虚拟环境（.venv）
uv pip install requests openpyxl markitdown
# 或直接用 uv 跑脚本，自动管理环境：
uv run main.py
```
（用户坚持用传统方式也行：`python3 -m venv .venv && source .venv/bin/activate && pip install ...`，Windows 激活是 `.venv\Scripts\activate`。）
---
## 第 5 步：写 Python 脚本（优先走接口）
按第 2 步扒到的接口写。脚本骨架（接口方案，最常见）：
```python
import requests, time, logging
logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
BASE = "https://example.com"
session = requests.Session()
session.headers.update({"User-Agent": "Mozilla/5.0 ..."})
def login():
# 方式A：表单登录拿 Cookie
r = session.post(f"{BASE}/api/login", json={"username": "U", "password": "P"}, timeout=20)
r.raise_for_status()
# 方式B：若返回 token，挂到后续请求头
# session.headers["Authorization"] = "Bearer " + r.json()["token"]
def fetch_page(page):
r = session.get(f"{BASE}/api/data", params={"page": page, "pageSize": 100}, timeout=20)
r.raise_for_status()
return r.json()
def run():
login()
rows, page = [], 1
while True:
data = fetch_page(page)
items = data.get("items", []) # ← 按第2步扒到的出参结构改
if not items:
break
rows.extend(items)
logging.info("拉到第 %s 页，累计 %s 条", page, len(rows))
page += 1
time.sleep(1) # 礼貌延时，别把人家服务器打爆
return rows
if __name__ == "__main__":
run()
```
要点提醒用户：加 `timeout`、`raise_for_status()`、`time.sleep` 礼貌延时、失败重试；凭据从环境变量/配置文件读，别硬编码进要外发的文件。
**HTML 解析方案**（无接口时）：`pip install requests parsel`，用 `Selector(html).css("...").getall()` 提字段。
---
## 第 6 步：数据往哪存（问用户）
问用户要哪种输出（可多选）：**Excel** / **数据库** / **HTML 报表** / **PDF 报表**。前两个是留数据、后两个是出成品给人看：
- **Excel**（最常用，给非技术同事看）：
**先问用户要什么表头**——让他直接给出**列名和顺序**（如"订单号、下单时间、金额(元)、状态、买家"），我们就**按他的表头导出**，把抓到的接口字段一一映射到他要的列，用他的中文列名，不用接口的原始英文 key。
```python
import openpyxl
# 用户指定的表头(列名+顺序) → 抓到的数据字段(接口出参的 key) 的映射，按需改：
COLUMNS = [
("订单号", "id"),
("下单时间", "created_at"),
("金额(元)", "amount"),
("状态", "status"),
("买家", "buyer_name"),
]
wb = openpyxl.Workbook(); ws = wb.active
ws.append([title for title, _ in COLUMNS]) # 第一行：用户要的表头
for row in rows:
ws.append([row.get(key, "") for _, key in COLUMNS]) # 缺字段留空，不报错
wb.save("导出.xlsx")
```
好处：用户改需求只要改 `COLUMNS` 这张映射表——加列、减列、改列名、调顺序都在这一处。数据量大或要清洗，可用 `pandas`：`df = pd.DataFrame(rows).rename(columns=名称映射)[列顺序]; df.to_excel("导出.xlsx", index=False)`（需 `uv pip install pandas openpyxl`）。
- **数据库**：小项目首选 **SQLite**（零配置、单文件）：
```python
import sqlite3
conn = sqlite3.connect("data.db")
conn.execute("CREATE TABLE IF NOT EXISTS orders(id TEXT PRIMARY KEY, amount REAL, time TEXT, status TEXT)")
conn.executemany("INSERT OR REPLACE INTO orders VALUES(?,?,?,?)",
[(r["id"], r["amount"], r["time"], r["status"]) for r in rows])
conn.commit(); conn.close()
```
要 MySQL/PostgreSQL 就用 `pymysql` / `psycopg2`，把连接串问用户拿。
- **HTML 报表**（网页表格，能直接发链接/双击打开看）：把数据渲染成一张带样式的 HTML 表格，复用第 6 步 Excel 的 `COLUMNS` 表头映射：
```python
html = ["<meta charset='utf-8'><style>table{border-collapse:collapse}td,th{border:1px solid #ccc;padding:6px}</style><table>"]
html.append("<tr>" + "".join(f"<th>{t}</th>" for t, _ in COLUMNS) + "</tr>")
for row in rows:
html.append("<tr>" + "".join(f"<td>{row.get(k,'')}</td>" for _, k in COLUMNS) + "</tr>")
html.append("</table>")
open("报表.html", "w", encoding="utf-8").write("".join(html))
```
（数据多可用 `pandas.DataFrame(rows).to_html("报表.html")`。）
- **PDF 报表**（给人打印/存档、微信发同事）：**先出 HTML，再把 HTML 转 PDF**（中文要指定中文字体，否则乱码）：
```bash
uv pip install weasyprint # 纯 Python，中文加 font-family 即可
```
```python
from weasyprint import HTML
HTML("报表.html").write_pdf("报表.pdf")
```
没装成 weasyprint 的兜底：用无头 Chrome `chrome --headless --print-to-pdf=报表.pdf 报表.html`，或有 chromedev 就直接用它把 HTML 打印成 PDF。
> **⚠️ 入库必须做幂等（定时重复跑的命根子）**：定时任务会一遍遍重跑、抓到的数据也会重叠，**没有幂等就会疯狂产生重复行**。做法：
> 1. 给表定一个**唯一主键/唯一索引**（如订单号、业务 id），这是幂等的基础；
> 2. 写入用 **upsert（有则更新、无则插入）**，别用裸 `INSERT`：
> - SQLite：`INSERT OR REPLACE INTO ...` 或 `INSERT ... ON CONFLICT(id) DO UPDATE SET ...`
> - MySQL：`INSERT ... ON DUPLICATE KEY UPDATE ...`
> - PostgreSQL：`INSERT ... ON CONFLICT(id) DO UPDATE SET ...`
> 这样同一条数据跑一百次，库里也只有一行（且是最新值）。
---
## 第 6.5 步：抓取记忆（一个 md 文件记住"抓到哪了"）
给脚本配一个 **`scrape_memory.md` 记忆文件**——脚本每次跑完就更新它，下次开跑先读它。它有两个作用，跟用户讲清：
> **它是干嘛的**：(1) **增量抓取**——记住上次抓到的最大 id / 时间游标，下次只抓"比这更新的"，不用每次全量重爬，又快又省；(2) **人能看懂的运行台账**——一眼知道最后成功是什么时候、累计多少条、最近有没有失败。
文件长这样（脚本自动读写，人也能直接看）：
```markdown
# 抓取记忆
- 最后成功运行：2026-07-18 08:00
- 已抓到的游标(最大 id / 最新时间)：100234
- 累计条数：5321
- 最近一次：新增 42 条 · 耗时 12s · 状态 成功
## 运行日志（新的在上）
- 2026-07-18 08:00 成功 +42 游标→100234
- 2026-07-17 08:00 成功 +37 游标→100192
- 2026-07-16 08:00 失败 接口超时（下次会从 100155 续抓）
```
脚本里的用法（配合第 2 步扒到的翻页/游标入参）：
1. **开跑前**：读 `scrape_memory.md` 拿到上次游标 `since`，请求接口时带上 `params={"since_id": since}` 只要增量；读不到（第一次跑）就全量。
2. **跑完后**：把本次新游标、新增条数、时间、成功/失败**追加**进记忆文件（失败也要记，注明下次从哪续）。
3. 这一步和第 6 步的**幂等入库**是绝配：游标记忆负责"少抓"，幂等负责"抓重了也不脏"，双保险。
> 提醒：记忆文件和数据/日志放同一目录，部署到服务器时一起带上；它是脚本的"存档点"，删了就会从头全量重爬。
---
## 第 7 步：定时策略（问用户多久爬一次）
先问用户：**一次性跑，还是定时？定时的话多久一次**（每小时/每天几点/每周）？
- **一次性**：手动跑即可，跳过本步。
- **Linux 定时（cron）**——每天 8 点跑一次：
```bash
crontab -e
# 加一行（用绝对路径 + 虚拟环境的 python）：
0 8 * * * cd /opt/scraper && /opt/scraper/.venv/bin/python main.py >> /opt/scraper/logs/cron.log 2>&1
```
- **Windows 定时**：用「任务计划程序（Task Scheduler）」新建任务，触发器设时间，操作设 `python.exe 脚本路径`。
- **脚本内自调度**（不想碰系统定时）：`pip install apscheduler`，用 `BlockingScheduler` 加 `interval`/`cron` 触发。
---
## 第 8 步：怎么运行 + 怎么中断
告诉用户：
- **运行**：进到脚本目录，`python3 main.py`（Windows：`python main.py`）。用了虚拟环境先 `source .venv/bin/activate`。
- **中断**：在终端里按 **Ctrl + C** 停止正在跑的脚本。
- **后台跑**（不占终端）：Linux `nohup python3 main.py > run.log 2>&1 &`，记下打印的进程号；要停用 `kill 进程号`。
- 建议脚本里对 `KeyboardInterrupt` 做优雅退出（把已抓到的数据先落盘），避免 Ctrl+C 丢数据。
### 可选：打包成 exe（给不装 Python 的人用）
如果这脚本要交给**不懂技术、电脑上没有 Python** 的同事用，可以打包成一个 `.exe`，**双击就能跑，不用装任何环境**。
> **PyInstaller 是什么**：把 Python 脚本连同解释器和依赖一起打包成单个可执行文件（Windows 的 .exe / Mac 的可执行程序），别人直接运行即可。
```bash
uv pip install pyinstaller # 或 pip install pyinstaller
pyinstaller --onefile main.py # 生成 dist/main.exe（单文件）
# 无控制台窗口版（GUI/后台用）：加 --noconsole
```
产物在 `dist/` 目录。提醒用户：
- **在哪个系统打包，就只能在哪个系统跑**（Windows 打的 exe 只能 Windows 跑，Mac 不通用）；
- 账号密码别硬编码进 exe（exe 能被反解），改从**同目录的配置文件 / 环境变量**读，把配置和 exe 一起发；
- 定时跑的场景，exe 也能直接挂到 Windows「任务计划程序」里。
---
## 第 9 步：部署到服务器 + 留爬虫日志
用户要长期定时跑就部署到服务器（一台常开的 Linux）：
1. **传上去**：`scp -r ./scraper root@服务器IP:/opt/scraper`，在服务器上装 uv 后 `uv venv && uv pip install -r requirements.txt`（或传统 venv+pip）。
2. **配日志**（爬虫必须留日志，方便查哪次失败、抓了多少）——用 Python `logging` 写文件并自动轮转：
```python
import logging
from logging.handlers import RotatingFileHandler
handler = RotatingFileHandler("logs/scraper.log", maxBytes=5*1024*1024, backupCount=5, encoding="utf-8")
logging.basicConfig(level=logging.INFO,
format="%(asctime)s %(levelname)s %(message)s", handlers=[handler])
```
（单文件到 5MB 自动切，保留最近 5 个，防日志撑爆磁盘。）
3. **定时 + 兜底日志**：用第 7 步的 cron，`>> logs/cron.log 2>&1` 把标准输出/报错也落盘。
4. **日志多久清一次（问用户 + 按硬盘给建议）**：先看服务器硬盘余量，再定保留策略——
```bash
df -h / # 看根分区剩多少空间
du -sh logs/ # 看当前日志占了多少
```
问用户想留多久，并**根据硬盘大小给建议**（估算：抓取频率越高、单次数据越多，日志涨得越快）：
- **硬盘紧张（如 <20G / 剩余不多）**：`RotatingFileHandler` 单文件调小（如 2MB）、`backupCount` 调小（如 3），日志只留最近几天；
- **硬盘宽裕（几十上百 G）**：单文件 5–10MB、保留 10 个，留一两周甚至一个月无妨。
- 按天切割 + 自动删旧的方案：用 `TimedRotatingFileHandler(when="D", backupCount=保留天数)`（如 `backupCount=7` 留 7 天，超期自动删）；
- 或用系统 `logrotate`：在 `/etc/logrotate.d/scraper` 配 `daily` + `rotate 天数` + `compress`，交给系统按天压缩清理。
把最终定的**保留天数/大小**写进脚本或 logrotate 配置，避免日志无限增长撑爆磁盘。
4. **想跑成常驻服务**（如脚本内 APScheduler 常驻）：写个 systemd unit（`/etc/systemd/system/scraper.service`），`systemctl enable --now scraper`，日志用 `journalctl -u scraper -f` 看。
5. **告诉用户日志在哪**、怎么看最近一次结果：`tail -n 50 logs/scraper.log`；并确认日志清理策略已生效（按第 4 点定的保留期）。
---
## 交付清单（全绿才算完）
- [ ] chromedev 侦察出可用接口（入参/出参已确认）或确认走 HTML 解析
- [ ] 无验证码拦路（有就已停手并告知）
- [ ] 本地能跑通，抓到预期数据
- [ ] 按用户选择导出 Excel / 入库 / HTML / PDF，且可重复跑不重复
- [ ] 记忆文件 scrape_memory.md 就位（增量续抓 + 运行台账）
- [ ] 定时策略配好（或确认一次性）
- [ ] （如需）部署到服务器 + 日志轮转就位，告诉用户日志位置
---
## 给 AI 的执行纪律（自检）
- **开场先做第 0 步**：检测 chromedev，没有就先带装再继续。
- **第 2 步优先扒接口**，能调接口绝不解析 HTML；扒到的入参/出参先跟用户对齐再写脚本。
- **验证码=红线**：登录或数据页有验证码/滑块/短信码，立即停手，别尝试绕过。
- **装 Python/依赖前先征得用户同意**，别擅自改他环境。
- **包管理优先用 `uv`**（比 pip 快、能管 Python 版本）；需要读网页/PDF/Word/Excel 内容时用 **markitdown** 转成 Markdown 再处理。两个工具第一次提到时都用一句话跟用户解释清楚它是干嘛的。
- 一次只推进一步，给命令 → 等用户回贴 → 判断 → 下一步；专业名词用大白话解释。
- 凭据从环境变量/本地配置读，不硬编码进会外发的文件；只处理用户有权访问的数据。
- 脚本务必带 timeout、重试、礼貌延时、幂等落盘、日志。遇到卡壳？
把 AI 报的错、或你看到的界面截图，直接发回给正在陪跑你的那个 AI，让它帮你排查——这正是"AI 陪跑"的意义。