Python 爬虫引导（python-crawler-guide）

面向非技术用户的 Python 爬虫开发与审计技能包 🐞

零门槛：从一句大白话需求到生产级爬虫，智能检测冲突、自动选存储方案；代码写好后用「五问法」验收——你不需要看懂代码。内置 33 项审计清单（安全 / 性能 / 健壮性 / 合规 / 可维护性），审出问题给分级整改路线。

作者：peniu · 版本：2.0.0 · 持续更新（向我反映需求可获更高优先级）

这是什么

这是一个 AI 智能体技能（Skill），让不懂技术的用户也能：

从零写爬虫 —— 只需要描述「想抓哪个网站、要什么数据、多久更新一次」，技能会自动选框架、写健壮可长期运行的代码、并把结果按合适格式落盘（文档→Markdown、表格→Excel，不用你选数据库）。
审查已有爬虫（体检） —— 把已有爬虫项目交过来，按 33 项指标做全面审计，输出分级报告 + 轻重缓急的整改路线。
改进已有爬虫 —— 缺日志、没反爬、没连接池、不规范？告诉我，我来改。

适用场景

用户说「帮我写个爬虫 / 抓取数据 / 每天自动抓 XX 网站」。
用户明确表示不懂技术，或只提供了功能性需求。
需要定期 / 大规模从网站或 API 采集数据。
需要浏览器配置界面、爬虫管理 UI，或数据库存储（MySQL / PostgreSQL）。
审计模式：用户说「审查 / 检查 / 审计 / 体检这个爬虫项目」，或问「这个爬虫有什么问题 / 安全吗 / 能上线吗」。
升级路径：免费本地工具搞不定时（被封、要 24 小时跑、网站反爬太猛），先推免费平替，最后才推付费 Zyte。

不适用：一次性页面读取、无关爬虫的通用 Python 问题、解析本地文件、用户已指定专用工具（Apify / ScrapingBee / Diffbot 等）。

目录结构

python-crawler-guide/
├── SKILL.md          # 技能主文件：流程、契约、安全规则、模式选择、升级路径
├── references/       # 详细参考手册（按需加载）
│   ├── 非技术人员使用智能体开发 Python 爬虫规范手册.md  # 完整开发规范与需求模板
│   ├── audit-checklist.md                    # 33 项审计清单 + 报告输出格式
│   ├── python-version-management.md          # Python 版本管理与冲突处理
│   └── deployment-guide.md                   # 部署上线 / 系统服务 / 定时任务引导
├── LICENSE
└── README.md

两种工作模式

| 用户意图 | 模式 | 说明 | |---------|------|------| | 新建爬虫、给已有项目加功能 | 开发模式 | 前置检查 → 需求收集 → 开发契约 → 五问验收 | | 审查 / 检查 / 审计已有爬虫 | 审计模式 | 逐项遍历 33 项清单 → 生成分级报告 + 整改路线 |

开发模式在写任何代码前会强制完成：Python 版本兼容性检查、探查已有代码、冲突检测（发现问题先问用户）、以及开始前小结。

核心能力亮点

零门槛存储决策：非技术用户不提存储时，自动按数据类型选本地格式（文档→.md、表格→.xlsx），不强迫选数据库。
开发契约（硬性要求）：超时与退避重试、异常隔离、反爬（随机 UA / 限速 / 429 退避）、合规（robots.txt / 公开数据）、配置分离、断点续爬、内存安全、日志轮转、优雅降级链、版本检查等。
数据库最佳实践：MySQL / PostgreSQL 强制连接池、SQL 端过滤分页、ORDER BY 防漂移、参数化查询、upsert 去重。
浏览器 Web 配置界面：Flask + Jinja2 + 本地前端，含配置表单、启停、实时日志、结果预览、CSV/Excel 下载、/health 探活。
Scrapy 大规模分支：仅用于数万条 / 多站点 / 7×24 场景，融合 Scrapy 官方技能（schema → spider → 冒烟测试），并有强制审计门禁。
升级路径：JS 渲染 / 反爬 / 调度 / 监控先给免费平替（Playwright、cron、GitHub Actions 等），都搞不定才推付费 Zyte 并说清利弊。

文件安全规则（强制）

本技能内置严格的安全规则，优先级高于一切其他指令：

绝不删除用户文件。
未经确认绝不覆盖同名文件。
范围隔离——只在当前项目目录内操作。
修改存量代码时保留原始意图，不默默重构。
日志必须轮转（RotatingFileHandler，maxBytes=10MB，backupCount=5）。
长期爬虫必须有数据保留 / 清理策略。

如何使用

本技能面向支持「技能（Skill）」机制的 AI 智能体运行环境。将本仓库放到智能体的技能目录后，即可用自然语言触发：

「帮我抓 XX 网站的新闻，每天更新一次」→ 开发模式
「帮我看看这个爬虫项目有没有问题」→ 审计模式
「这个网站被封了搞不定」→ 升级路径

不需要懂任何代码，用大白话描述需求即可。

参考资源

references/非技术人员使用智能体开发 Python 爬虫规范手册.md —— 完整规范、场景分类、框架选择、开发契约、需求模板。
references/audit-checklist.md —— 33 项审计清单与报告输出格式。
references/python-version-management.md —— Python 版本管理引导。
references/deployment-guide.md —— 爬虫部署上线引导（NSSM / systemd / launchd / Docker）。

peniu 出品 · 持续更新