🌐 语言 / Language：简体中文 ｜ 繁體中文 ｜ English
🔎 不花一分钱、不注册账号、不上传页面，在本机把整站爬一遍，按「焦点关键词」逐页体检 On-Page SEO，输出可直接行动的优化报告。纯 Python 标准库实现，零运行时第三方依赖，Windows / macOS / Linux 全平台可跑。
RankPilot 是什么？ RankPilot 是一款面向开发者、独立站长、技术写作者与增长团队的站内 SEO（On-Page SEO）审计与内容优化工作台。给它一个线上网址，或一个本地 HTML 目录，它就会：
- 🕷️ 礼貌地抓取（或离线读取）整站页面；
- 🎯 以你指定的**焦点关键词（Focus Keyword）**为核心，逐页分析标题、描述、标题层级、正文密度、可读性、图片 alt、内链结构；
- 🕸️ 自动构建内链图谱，找出孤儿页、断链、点击过深的页面；
- 🧬 检测重复标题 / 描述 / H1 与近似重复正文；
- 📊 给出百分制评分与 A–F 等级，并导出控制台 / JSON / CSV / Markdown / 单文件 HTML 五种报告。
它解决什么痛点？
- 💸 Semrush、Ahrefs 等工具订阅昂贵、套件臃肿，且**站点体检（Site Audit）**这类本可在本地完成的工作也要付费、还要把页面数据上传；
- 🔒 未上线的内测站、内网站、本地草稿根本无法交给 SaaS 工具抓取；
- 🧑💻 开发者更想要一个能进 CI、能出机器可读结果、能对比每次优化得分的命令行工具，而不是又一个营销后台。
自研差异化亮点（相对同类产品）
- ✅ 零 API Key、零账号、零联网也能用：离线模式直接审计本地目录，页面与关键词永不出本机；
- 🎯 关键词驱动而非运维健康检查：围绕 Yoast 式焦点关键词工作流（密度 / 位置 / 首段 / slug / 图片 alt），而不是只看 SSL、DNS、响应头；
- 🕸️ 整站视角：内链图谱、孤儿页、点击深度、跨页重复内容，而非只检查单个 URL；
- 📈 跨轮趋势对比：每次运行自动留痕，优化前后得分变化一目了然，可直接当 CI 质量门禁（
--min-score）； - 🧱 真正零依赖：不依赖 requests / bs4 / lxml，全部基于标准库，
pip install不拖入任何传递依赖，也可直接用单文件rankpilot.pyz运行； - 🌏 中英文混合内容感知：分词、密度、可读性同时兼容拉丁语种与中日韩文字。
灵感来源：GitHub Trending 上的开源 Semrush/Ahrefs 替代项目验证了「人人可用的 SEO 工具」这一真实需求，但它依赖付费数据 API 与 Docker 部署。RankPilot 取其「Site Audit」产品逻辑，做了完全独立的自研实现，并把最核心、最隐私敏感的站内优化能力做到本地、零依赖、开箱即用。
📸 运行截图 / 演示动图占位：
docs/demo-console.png（控制台报告）、docs/demo-html-report.png（HTML 报告）
- 礼貌 BFS 爬虫：同域约束、抓取深度 / 页数上限、请求间隔、超时重试、自定义请求头、HTTP Basic Auth
- 遵守 robots.txt：自动解析
Disallow与Crawl-delay（可用--ignore-robots关闭） - 完全离线模式：直接审计本地 HTML 文件 / 目录，并基于文件系统检测离线断链
- 健壮解析器：基于
html.parser，容错畸形 HTML，自动识别 UTF-8 / GB18030 等编码
- 出现次数、关键词密度（可配置理想区间，默认 0.5%–2.5%，自动识别堆砌）
- 关键词在 title / meta description / H1 / H2-H3 / 首段 / URL slug / 图片 alt 的覆盖情况
- 标题中的关键词位置检测，支持英文短语边界与中文子串两种匹配
- 正文词量（术语数）评估，识别薄内容 / 空页面
- 平均句长、长句占比、段落长度、英文 Flesch Reading Ease 可读性指数、中文句长统计
- Meta：title 缺失 / 过长过短、description、canonical（相对路径 / 跨页指向）、robots noindex
- 结构：H1 缺失 / 多个 H1、跳级标题、废弃标签、
<!DOCTYPE>、内联样式 - 技术：viewport、charset、html lang、HTTPS 混合内容（mixed content）
- 社交/结构化数据：Open Graph 完整性、Twitter Card、JSON-LD 存在性与JSON 合法性校验
- 链接/图片：缺失 alt、空 alt、懒加载、泛化锚文本（“点击这里 / click here”）、死胡同页、URL 大小写 / 下划线 / 长度
- 内链入度 / 出度 / 点击深度计算
- 孤儿页（无任何内链指向）识别
- 内链断链（线上 4xx/5xx、离线文件缺失）汇总
- 重复 title / description / H1，以及基于 5-gram Jaccard 相似度的近似重复正文检测
- 🖥️ 带等级配色的控制台报告（
--no-color可关闭） - 🧾
report.json（完整机器可读结果）、report.csv（问题清单平铺）、report.md - 🖨️ 单文件 HTML 报告：内嵌 CSS、评分仪表盘、分类得分条、SERP/社媒卡片预览、问题筛选搜索，零外链、可离线发送
- 🔎
preview子命令：在终端预览 Google 搜索摘要与社交分享卡片 - ⚖️
compare子命令：对比两次 JSON 报告的逐页得分变化 - 🔁 历史趋势：输出目录自动维护最近 10 次得分
- 🚦 CI 门禁：
--min-score低于阈值时以非零码退出
| 项目 | 要求 |
|---|---|
| Python | 3.8 / 3.9 / 3.10 / 3.11 / 3.12（仅标准库） |
| 操作系统 | Windows、macOS、Linux 全平台 |
| 网络 | 在线模式需要能访问目标站点；离线模式完全不需要网络 |
| 第三方依赖 | 运行时零依赖；仅开发测试可选装 pytest |
方式一：pip 安装（推荐，获得 rankpilot 命令）
git clone https://github.com/gitstq/rankpilot.git
cd rankpilot
pip install .
rankpilot --version或以可编辑模式参与开发：
pip install -e .方式二：单文件运行，免安装（最干净）
python scripts/build.py # 生成 dist/rankpilot.pyz（只用标准库）
python dist/rankpilot.pyz --version# 1) 在线爬取并审计一个站点（最多 50 页、深度 3），结果写入 ./report-out
rankpilot run https://example.com --keyword "example keyword" -o ./report-out
# 2) 完全离线：审计本地构建产物目录（未上线也能体检）
rankpilot audit ./dist-site -o ./report-out
# 3) 只看某个页面在 Google 结果里长什么样
rankpilot preview https://example.com/about免安装时把
rankpilot换成python dist/rankpilot.pyz，或用PYTHONPATH=src python -m rankpilot ...。
| 子命令 | 作用 | 典型场景 |
|---|---|---|
run <url> |
在线抓取并审计 | 线上站点日常巡检 |
audit <path> |
离线审计文件/目录 | 本地构建产物、内网页面、草稿 |
preview <url|file> |
输出 SERP + 社交卡片预览 | 改完标题描述快速自检 |
compare <a.json> <b.json> |
对比两份报告逐页得分 | 验证一轮优化是否提分 |
全站只用一个关键词并不现实。可以用 JSON 映射，按 URL 子串分配关键词：
rankpilot run https://example.com --keyword-map kw.json -o ./outkw.json 示例（见 examples/keyword-map.example.json）：
{
"default_keyword": "seo audit",
"rules": [
{ "match": "/blog/", "keyword": "technical seo guide" },
{ "match": "/pricing", "keyword": "seo audit pricing" }
]
}rankpilot run https://example.com \
--keyword "seo audit" \
--max-pages 100 \ # 最多抓取页数（默认 50）
--max-depth 4 \ # 最大点击深度（默认 3）
--delay 0.5 \ # 同域请求间隔秒数，礼貌抓取（默认 0.3）
--timeout 15 \ # 单页超时秒数
--include-subdomains \ # 允许抓取子域
--header "Cookie: x=1" \ # 自定义请求头（可重复）
--auth-user u --auth-pass p \ # HTTP Basic 认证
--ignore-robots \ # 跳过 robots.txt 限制（请自行负责）
-v # 输出抓取过程# 默认在 -o 目录下生成全部格式并同时打印控制台报告
rankpilot audit ./site -o ./out --format all
# 只要 JSON（自动化流水线）
rankpilot run https://example.com --format json -o ./out
# 组合格式
rankpilot audit ./site --format console,html,md -o ./out格式清单：console、json、csv、md、html、all。
页面得分低于 85 即让流水线失败：
rankpilot run https://staging.example.com --max-pages 20 --min-score 85 --format json -o ci-out
echo "exit code = $?"rankpilot audit ./site-v1 --format json -o v1
rankpilot audit ./site-v2 --format json -o v2
rankpilot compare v1/report.json v2/report.json
# Overall: 71.5 → 84.0 (+12.5)，并逐页列出涨跌- 每个分类从 100 分起扣：
error扣 18、warning扣 8、notice扣 3，分类得分下限 0； - 页面总分按权重加权：内容 28% · Meta 22% · 结构 17% · 链接 13% · 技术 12% · 社交 8%；
- 站点得分为全部页面平均；等级线：A ≥ 90、B ≥ 80、C ≥ 70、D ≥ 55、E ≥ 40，其余为 F；
- 4xx/5xx 错误页只记录传输层错误，不重复叠加内容规则，避免噪声。
rankpilot/
├── src/rankpilot/
│ ├── cli.py # 命令行入口（run/audit/preview/compare）
│ ├── crawler.py # 在线 BFS 爬虫 + 离线目录加载
│ ├── parser_html.py # 标准库 HTML 解析器
│ ├── content.py # 关键词 / 可读性 / 近似重复
│ ├── rules.py # 40+ 条 SEO 规则引擎
│ ├── graph.py # 内链图谱 / 孤儿页 / 深度
│ ├── score.py # 加权评分
│ ├── preview.py # SERP / 社交卡片预览
│ ├── engine.py # 流水线编排
│ └── report/ # console / json / csv / md / html 渲染
├── tests/ # 31 个 unittest + 本地站点夹具
├── scripts/build.py # 跨平台单文件打包（zipapp）
└── pyproject.toml
Q：真的一个第三方包都不装吗？
A：是的，运行时只用 Python 标准库（urllib、html.parser、json、csv…）。requirements.txt 里没有任何包；pytest 仅为可选开发依赖。
Q：会把我的页面或关键词上传到哪里吗？ A：不会。在线模式只与你指定的目标站点通信（请求其自身页面与该站 robots.txt）；离线模式完全不联网。报告默认只写入本机目录。
Q：为什么不做关键词调研 / 反链 / 排名追踪？ A：这些依赖搜索引擎结果页或第三方数据 API，与「本地、隐私、零依赖」的定位冲突。RankPilot 专注你能完全自控的站内优化；这类外部数据能力正是其他工具的领域。
Q：单页应用（JS 渲染）能审计吗？
A：RankPilot 不执行 JavaScript，分析的是服务器返回的原始 HTML。对 SSR / SSG / 静态站效果最佳；纯 CSR 页面建议先导出渲染后的 HTML 再用 audit 离线分析。
Q：抓取会给目标站造成压力吗？ A：默认串行抓取、带 0.3s 间隔、遵守 robots.txt，并有页数与深度上限，属于礼貌爬虫。请仅对你拥有或获许审计的站点使用。
- 本地优先、隐私优先：数据不出机器，断网可用；
- 确定性优先：规则不依赖任何大模型或在线服务，同一份输入永远得到同一份结果，适合 CI；
- 零依赖是特性不是约束：标准库覆盖需求时绝不引第三方，安装与审计永远稳定可复现；
- 建议必须可执行：每条问题都附带 how-to-fix，而不是只给一个吓人的分数。
- sitemap.xml / RSS 发现并作为抓取种子
- hreflang 多语言簇一致性检查
- 页面体积 / 未压缩资源等性能信号（基于响应头与引用资源）
- HTML 报告内链图谱的可交互可视化
- SARIF 输出，直接对接代码扫描平台
- 更多语言的可读性模型（日语、韩语、欧洲语种）
- 规则配置文件（自定义阈值、按需启停规则）
欢迎在 Issues 区提需求，也欢迎在 Discussions 讨论方向。社区贡献方向：新规则、新报告格式、可读性模型、测试夹具。
RankPilot 属于脚本 / 工具库类项目，无需安装即可运行，也不依赖任何外部服务，因此不发布二进制 Release。三种使用/分发方式：
python scripts/build.py # 产物：dist/rankpilot.pyz
python dist/rankpilot.pyz audit ./site -o ./outrankpilot.pyz 在任何装有 Python 3.8+ 的 Windows / macOS / Linux 上均可运行。
pip install . # 本地安装
pip install "git+https://github.com/gitstq/rankpilot.git" # 他人直接从 Git 安装FROM python:3.12-slim
WORKDIR /app
COPY . /app
RUN pip install --no-cache-dir .
ENTRYPOINT ["rankpilot"]docker build -t rankpilot .
docker run --rm -v "$PWD/site:/site" rankpilot audit /site -o /site/out兼容环境：Python 3.8+，操作系统无关；控制台颜色在非 TTY 环境自动降级，也可显式加 --no-color。
欢迎 PR！提交前请阅读完整的 CONTRIBUTING.md。简要约定：
- 提交信息遵循 Angular 规范：
feat:/fix:/docs:/refactor:/test:； - 不得引入运行时第三方依赖（标准库优先）；
- 新规则请同时补
tests/单测，并保证python -m unittest discover -s tests全绿； - 新增/修改用户可见能力时，同步更新三语文档。
# 提交前自检
python -m compileall src
PYTHONPATH=src python -m unittest discover -s tests -v
python scripts/build.py安全问题请私下联系维护者，不要在公开 Issue 中披露利用细节。
本项目基于 MIT License 开源，可自由使用、修改、分发与商用，保留版权声明即可。
如果 RankPilot 帮你省下了一次 SaaS 订阅，欢迎给个 ⭐ Star 支持！