面向开发者的本地优先（local-first）、可完全离线运行的 SEO 爬虫审计工具。 既可以爬取线上站点，也可以直接审计本地构建产物目录；内置 36 条 SEO 规则，输出透明的 0–100 分与 A–F 评级，支持文本 / JSON / Markdown / 单文件 HTML 四种报告；零第三方依赖，仅靠 Python 3.8+ 标准库运行。
SEOForge 是一款命令行「技术型站内 SEO」审计引擎，工作方式像一位资深
SEO 工程师：从一个入口 URL 出发，礼貌地爬取整站，构建内链图谱，交叉核对
robots.txt 与 sitemap.xml，逐页解析 HTML 文档，并对每个问题说明
错在哪里、为什么重要、应该怎么改。
- Semrush / Ahrefs 一类商业 SEO 套件价格昂贵、爬取额度受限，且页面数据必须上云；
- 多数开源检查器一次只能查一个页面，发现不了跨页问题：重复标题、孤儿页面、 sitemap 覆盖缺口、重定向链等；
- SEO 问题往往在上线之后才被发现，可静态构建产物里其实早已包含排查所需的全部信息。
- 全站视角，而非单页检查：BFS 爬取 + 入链/出链图谱 + 爬取深度 + 重定向链记录；
- 跨页智能分析：重复 title/description、近重复正文（5-shingle Jaccard 相似度）、 孤儿页面、sitemap 覆盖度差异比对；
- 双输入模式：线上 URL 用
audit，本地dist/目录用lint，让 SEO 成为 部署前即可离线执行的门禁； - 评分量规完全透明：四大类目固定分值预算（内容 40 · 可抓取性 30 · 链接 20 · 体验 10），页面级问题按页面数归一化，大站不会因页面多而被重复惩罚；
- CI 原生设计：
--threshold分数门禁 +--fail-on严重度门禁，退出码语义稳定， 一行命令接入 GitHub Actions / GitLab CI； - 极致可移植：纯标准库实现，没有依赖安装链，Windows / macOS / Linux、 受限 CI 与内网离线环境均可运行。
项目灵感来自近期开源社区对「可自托管 SEO 工具」（Semrush/Ahrefs 的开源替代） 的高涨热情。未复制任何第三方代码，SEOForge 为完全独立的净室实现，聚焦于 每个开发者都能在本地跑起来的部分——技术型站内 SEO 审计。
- 🌐 同站 BFS 爬虫，受控线程池 + 礼貌延迟
- 🤝 类 RFC 9309 的
robots.txt解析：通配符、$、最长匹配优先、Crawl-delay、Sitemap:发现 - 🗺️ 支持 XML urlset / sitemap 索引 / 纯文本三种 sitemap
- 🔁 完整记录重定向链（长链与环路）
- 🔀 URL 包含/忽略正则、额外 sitemap、自定义 User-Agent
- 📁 本地目录模式：自动解析相对链接与
index.html目录索引
| 类目 | 分值预算 | 代表性规则 |
|---|---|---|
| 内容与元数据 | 40 | 标题/描述存在性与长度、H1 结构、标题层级顺序、Open Graph、Twitter Card、canonical、lang、JSON-LD、薄内容、无意义锚文本、重复标题/描述、近重复正文 |
| 抓取与索引 | 30 | robots 全站封禁、sitemap 缺失、sitemap 覆盖缺口、sitemap 死链、混合内容、重定向链、HTTPS、viewport/charset |
| 链接结构 | 20 | 内链死链、孤儿页面、埋藏过深页面、链接数过多 |
| 性能与体验 | 10 | HTML 体积过大、响应过慢、favicon、图片缺少 alt |
执行 seoforge rules 可查看完整规则目录（编号 / 严重度 / 权重）。
- 🎯 0–100 总分、A–F 评级、四类目分项得分
- 📄 四种报告：终端文本、机器可读 JSON、Markdown、单文件 HTML （内联 CSS + 原生 JS 筛选，离线双击即可打开）
- 🚦 CI 门禁：分数阈值 + 严重度触发，退出码稳定可编排
- 🏠 全部计算在本机完成，无任何分析、遥测与云端上传
- 🧱 仅依赖标准库，供应链就是 Python 本身
- 🐢 默认礼貌爬取：遵守 robots、限制并发、请求间隔
- Python 3.8 及以上（已在 3.8 / 3.10 / 3.12 验证）
- 支持 Windows 10+、macOS、Linux
- 运行期零第三方依赖，甚至不必创建虚拟环境
# 方式一：源码可编辑安装（当前推荐）
git clone https://github.com/gitstq/seoforge.git
cd seoforge
python3 -m pip install -e .
seoforge --version
# 方式二：构建通用 wheel 后随处安装
python3 -m pip install build
python3 -m build
python3 -m pip install dist/seoforge-1.0.0-py2.py3-none-any.whl
# 方式三：免安装直接运行
python3 -m seoforge --version# 文本报告，最多爬取 100 个页面
seoforge audit https://example.com --max-pages 100 --delay 200
# 生成可分享的单文件 HTML 报告
seoforge audit https://example.com -f html -o report.html
# 输出机器可读 JSON，供下游工具消费
seoforge audit https://example.com -f json -o report.json# 在 npm run build / hugo / mkdocs build 等构建完成之后
seoforge lint ./dist --base-url https://www.example.com/make demo-local # 在临时目录生成示例站点并完成审计
# 或
bash scripts/local_demo.shseoforge audit <url> [参数] # 爬取并审计线上站点
seoforge lint <目录> [参数] # 审计本地静态构建目录
seoforge rules # 列出全部 36 条规则| 参数 | 默认值 | 说明 |
|---|---|---|
--max-pages N |
100 | 爬取预算（HTML 页面 + 被探测的内链资源总数） |
--workers N |
4 | 并发抓取线程数 |
--delay MS |
200 | 请求派发之间的礼貌间隔（毫秒） |
--timeout S |
10 | 单请求超时（秒） |
--no-robots |
关闭 | 忽略 robots.txt（仅限自有站点） |
--include 正则 |
– | 只爬取匹配的 URL（可重复） |
--ignore-path 正则 |
– | 跳过匹配的 URL（可重复） |
--sitemap URL |
– | 额外指定 sitemap（可重复） |
--user-agent UA |
SEOForgeBot/1.0 | 自定义 User-Agent |
-f, --format |
text | text / json / md / html |
-o, --output F |
标准输出 | 报告写入文件 |
--ignore-rule ID |
– | 关闭指定规则，如 P17（可重复） |
--threshold N |
0 | CI 门禁：低于 N 分即失败 |
--fail-on |
never | error / warning / never |
-v, --verbose |
关闭 | 向 stderr 打印爬取进度 |
| 参数 | 默认值 | 说明 |
|---|---|---|
--base-url URL |
http://localhost/ |
解析相对链接与 sitemap 时使用的逻辑站点地址 |
| 其余 | 与上表相同的报告/门禁参数（-f、-o、--ignore-rule、--threshold、--fail-on） |
1. CI 质量门禁：低于 85 分或出现 error 即失败
seoforge audit https://staging.example.com \
--max-pages 200 --threshold 85 --fail-on error -f md -o seo.md
# 退出码：0 通过 · 1 门禁失败 · 2 运行时错误2. 静态站点部署前离线检查
seoforge lint ./public --base-url https://example.com \
--threshold 90 --fail-on warning -f html -o seo-report.html3. 只审计某个路径，并关闭个别噪声规则
seoforge audit https://example.com/docs \
--include '^https://example.com/docs/' \
--ignore-path '/docs/legacy/' \
--ignore-rule P17 --ignore-rule P124. 用 JSON 做问题趋势对比（配合 jq）
seoforge audit https://example.com -f json > "$(date +%F).json"
jq '.counts, .score' 2026-08-31.json每条规则都归属一个类目并带有固定权重。站点级问题直接扣分；页面级问题 按已爬取 HTML 页面数取平均后 × 5，避免千页站点被重复惩罚千次。各类目 扣分不超过其分值预算：
| 类目 | 最高扣分 |
|---|---|
| 内容与元数据 | 40 |
| 抓取与索引 | 30 |
| 链接结构 | 20 |
| 性能与体验 | 10 |
评级：A ≥ 90 · B ≥ 80 · C ≥ 70 · D ≥ 60 · F < 60。
- 终端报告：
docs/screenshots/terminal-demo.png（占位，可自行替换） - HTML 报告：
docs/screenshots/html-report.png（占位） - 随时可通过
make demo-local重新生成真实样例
- 本地优先、可离线：审计必须能在受限的 CI 容器里跑通；
- 零依赖是特性而非妥协：每个第三方依赖都是供应链、兼容性与维护成本， 而 HTTP、HTML 解析、线程、压缩标准库已全部覆盖；
- 规则即数据：每条规则都是一个带稳定编号（
Pxx页面级、Sxx站点级） 的小型纯函数，报告结果可逐版本 diff； - 解释而非恐吓：每个问题都附带可执行的修复建议。
Python 标准库全家桶：urllib（HTTP 与重定向）、html.parser（对真实世界
畸形 HTML 足够宽容）、concurrent.futures（受控并发）、gzip/zlib
（压缩）、unittest（自包含测试）。没有原生编译步骤、没有平台 wheel、
没有版本冲突。
- 支持
pyproject.toml/.seoforge.toml配置文件驱动规则参数 - 两次审计结果的 HTML 差异对比（回归视图）
- hreflang 语言簇校验与国际化检查
- 可选的渲染后 DOM 类 Core Web Vitals 启发式检查
- SARIF 输出，接入代码扫描看板
- JUnit XML 输出，接入 CI 测试报告器
新增规则、修复建议的多语言本地化、针对真实畸形 HTML 的解析加固、
更多报告主题，详见 CONTRIBUTING.md。
SEOForge 属于开发者工具 / 工具库，以源码与通用 wheel 形式发布， 不需要任何平台相关的可执行文件。
| 环境 | 支持情况 |
|---|---|
| Python | 3.8 / 3.9 / 3.10 / 3.11 / 3.12 |
| 操作系统 | Linux、macOS、Windows（原生 / WSL） |
| 运行依赖 | 无 |
| 网络要求 | audit 模式需要；lint 模式完全不需要 |
python3 -m pip install build
python3 -m build # 产物位于 dist/：.tar.gz 与 .whl# .github/workflows/seo.yml
name: seo-gate
on: [push, pull_request]
jobs:
seo:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with: { python-version: "3.12" }
- run: pip install .
- name: 审计本地构建产物
run: |
npm run build || true
seoforge lint ./dist --base-url https://example.com \
--threshold 85 --fail-on error -f html -o seo.html
- uses: actions/upload-artifact@v4
with: { name: seo-report, path: seo.html }docker run --rm -v "$PWD:/site:ro" python:3.12-slim \
sh -c "pip install --quiet seoforge 2>/dev/null || true; \
cd /site && python -m seoforge lint . --base-url https://example.com"Q：会执行 JavaScript 吗？
不会。工具分析服务端返回的原始 HTML，以保证快速与零依赖。JS 渲染型 SPA
建议先做静态生成，再用 lint 模式审计构建产物。
Q：和 Lighthouse 有什么区别？ Lighthouse 聚焦单个渲染后页面的性能与体验指标；SEOForge 聚焦整站： 内链图谱、sitemap/robots 覆盖、跨页重复与孤儿页面，并面向 CI 门禁设计。
Q：会不会把服务器压垮？
不会。默认遵守 robots、4 并发、200ms 派发间隔，可用 --workers、
--delay 自行调节。
Q：为什么不检查外链？ 这是刻意的设计：只抓取同站链接以保持礼貌与边界可控；外链 URL 已在数据 模型中采集，留作后续规则扩展。
Q：某条规则不适合我的站点怎么办？
用 --ignore-rule 编号 单次关闭，并欢迎携带最小复现样例提交 Issue。
欢迎提交 Issue 与 PR。规则编写规范、测试要求与 Angular 提交规范
（feat: / fix: / docs: / test: / refactor: / chore:）
请先阅读 CONTRIBUTING.md。
基于 MIT 协议开源，详见 LICENSE。