geolint

geolint

面向 AI 搜索的 ESLint。 检查网站是否适合 AI 搜索 — 包括 AI 爬虫访问、llms.txt、结构化数据和引用适用性。

🇩🇪 Deutsch · 🇪🇸 Español · 🇯🇵 日本語

30 秒快速开始

无需安装，无需配置：

npx @iliasabk/geolint check yoursite.com

geolint 会抓取页面、其 robots.txt 和 llms.txt，依据 robots.txt 检查 51 个已知 AI 爬虫令牌，运行 52 条审计规则，并输出评分报告，为每项发现提供具体修复方法。

为什么需要它

• AI 回答已成为新的首页。 ChatGPT、Perplexity、Claude、Copilot 和 Google AI Overviews 是否为你带来流量，取决于它们的爬虫能否抓取并引用你的页面。
• 大多数网站会无意中屏蔽或误导 AI 爬虫。 过时的 Disallow: /、从暂存环境遗留下来的 noindex，或是对不运行 JavaScript 的机器人而言看似空白的客户端渲染页面。
• 现有工具要么是屏蔽列表，要么是只给分数的 Web 应用。 它们要么建议你屏蔽所有内容，要么只给出一个数字，却不告诉你如何改进。geolint 是一个 代码检查工具：提供具体发现和具体修复方案，可在每次 PR 时于 CI 中运行。

检查内容

涵盖 5 个类别的 52 条规则 — geolint rules 会列出所有规则；docs/rules.md 说明每条规则检查的内容、重要性以及违规后的修复方法。

类别	规则数	示例
AI 爬虫访问	10	ai-crawler/search-bots-blocked、ai-crawler/wildcard-block-all、ai-crawler/user-fetch-bypass、ai-crawler/stale-tokens
llms.txt	12	llms-txt/missing、llms-txt/invalid-structure、llms-txt/broken-links、llms-txt/relative-links
结构化数据	7	schema/no-jsonld、schema/invalid-jsonld、schema/missing-article-fields
引用适用性	12	content/thin-content、content/no-h1、content/missing-dates、content/no-question-headings
技术基础	11	technical/client-rendered、technical/https、technical/slow-response、technical/sitemap-missing

报告示例

以下是审计内置演示网站（examples/demo-site，该网站有意屏蔽了两个机器人）的实际输出 — 为适应页面宽度做了截取：

$ geolint check localhost:4173 --ignore technical/https

  geolint v0.2.1 — AI-search readiness
  http://localhost:4173/
  200 OK · text/html · TTFB 113ms · robots 200 · llms.txt 404

  ██████████████████████████░░░░  86/100  Grade B

  CATEGORIES
    AI Crawler Access     ███████░░░   70  ✗ 2 errors
    llms.txt              █████████░   92  ⚠ 1 warning · 1 hint
    Structured Data       █████████░   88  ⚠ 1 warning · 3 hints
    Citability            ████████░░   82  ⚠ 2 warnings · 3 hints
    Technical Foundation  ██████████  100  ✓ clean

  AI CRAWLER ACCESS — 49/51 allowed · 2 blocked
    OpenAI
      GPTBot                        ✓  training
      OAI-SearchBot                 ✓  search
      ChatGPT-User                  ✓  user-fetch
    Perplexity
      PerplexityBot                 ✗  search
      Perplexity-User               ✓  user-fetch
    Google
      Googlebot                     ✓  search
      Google-Extended               ✓  training
    … 51 tokens total, grouped by vendor …

  FINDINGS
    AI Crawler Access
      ✗ ai-crawler/search-bots-blocked  PerplexityBot is blocked by robots.txt — Perplexity cannot use your pages as AI answer sources
          fix: Remove the Disallow covering PerplexityBot in robots.txt, or add an explicit "Allow: /" for it.
          evidence: Disallow: / (matched by PerplexityBot)
    llms.txt
      ⚠ llms-txt/missing                No llms.txt found
          fix: Create /llms.txt at the site root: an H1 title, a short blockquote summary, and ## sections linking to your key content.
          evidence: http://localhost:4173/llms.txt → HTTP 404

  ────────────────────────────────────────────────────────────────────
  2 errors · 4 warnings · 7 hints · 32/44 checks passed

每项发现都包含规则 ID、严重性、geolint 匹配到的证据以及修复方法。你可以并排比较两个页面或两个竞争对手：

geolint check a.com --compare b.com

命令

命令	功能	主要标志
geolint check <url>	审查单个 URL	--format、--fail-under、--only/--ignore/--category、--compare、--baseline、--badge、--verbose
geolint crawl <url>	抓取同源页面并审查整个网站	--max-pages、--max-depth、--concurrency、--fail-under
geolint init <url>	抓取网站并生成 llms.txt	-o、--max-pages
geolint diff <old.json> <new.json>	比较两份 JSON 报告：分数变化、新增/已解决的问题	—
geolint rules	列出 52 条审查规则	--category、--format table|json|markdown
geolint bots	列出 51 个已知 AI 爬虫及屏蔽各个爬虫的影响	--format table|json
geolint mcp	通过标准输入/输出运行 MCP 服务，供 AI 助手使用	--timeout

完整标志参考：docs/configuration.md。

在 CI 中运行

GitHub Action

- uses: iliasabk/geolint@v1
  id: geolint
  with:
    url: https://example.com
    fail-under: 80

- uses: github/codeql-action/upload-sarif@v3
  if: always()
  with:
    sarif_file: ${{ steps.geolint.outputs.sarif-file }}

该 Action 会生成分数/等级步骤输出、供 GitHub 代码扫描使用的 SARIF 报告，以及用于作业摘要和 PR 评论的 Markdown 报告。完整用法示例——SARIF 上传、更新单条 PR 评论、基线偏差检测——请参阅 docs/github-action.md。

其他 CI

npx @iliasabk/geolint check https://example.com --fail-under 80

当分数低于门槛（或相较于 --baseline 出现问题回退）时，退出代码为 1，否则为 0——适用于 GitLab CI、CircleCI、npm 脚本和部署前钩子。

将分数显示为 README 徽章

npx @iliasabk/geolint check https://example.com --badge
# → writes geolint-badge.svg + prints the markdown snippet to paste

提交 SVG，或在 CI 中重新生成 shields endpoint JSON（--badge-endpoint），即可获得永不过时的徽章。

输出格式

-f pretty（默认）会渲染上方的终端报告。机器可读格式包括：

• -f json — 完整的 ScanReport：问题、各类别分数、爬虫访问矩阵
• -f sarif — SARIF 2.1.0，可直接上传至 GitHub 代码扫描
• -f markdown — 适用于 PR 评论/作业摘要的表格
• -f html — 独立的交互式报告（分数环、问题筛选器、爬虫矩阵），可供分享或托管在任何位置

添加 -o report.json 可将结果写入文件；标准输出会保持干净，便于通过管道传递。

真实网络上的 geolint

该仓库会用自身工具审查自身：每晚工作流会重新审查八个知名网站并提交分数，而展示站点会发布完整的交互式报告——包括 github.com、anthropic.com、stripe.com 等，每次推送到 main 时都会重新生成。

编程接口

import { scan } from '@iliasabk/geolint';

const report = await scan('https://example.com', {
  ignore: ['technical/https'],
  timeout: 10_000,
});

console.log(report.score, report.grade);          // e.g. 86 'B'
for (const f of report.findings) {
  console.log(f.severity, f.ruleId, f.message, f.fix);
}

scan(url, options) 会返回类型化的 ScanReport。此外还导出了：爬虫注册表（AI_BOTS、botsByPurpose）、规则注册表（allRules、ruleById）、robots.txt/llms.txt 解析器、徽章生成器、评分器和全部四种报告生成器。

在 AI 助手中使用（MCP）

geolint mcp 通过标准输入/输出使用 Model Context Protocol——Claude Desktop、Cursor、VS Code 和 Windsurf 可将其作为原生工具来审查网站、生成 llms.txt 和比较 URL：

// claude_desktop_config.json / ~/.cursor/mcp.json
{
  "mcpServers": {
    "geolint": {
      "command": "npx",
      "args": ["-y", "@iliasabk/geolint", "mcp"]
    }
  }
}

五种工具：audit_url、generate_llms_txt、compare_urls、list_rules、list_ai_bots——均为只读，提供结构化输出，并支持单次调用超时设置。各客户端的设置方法：docs/mcp.md。

机器人注册表是核心

geolint bots 会列出 51 个 AI 爬虫令牌，并提供结合用途的影响评估——因为“我该屏蔽这个机器人吗？”这个问题，对每种机器人都有不同的答案：

用途	示例	屏蔽后果
training	GPTBot、ClaudeBot、CCBot	不会出现在未来的训练数据中
search	OAI-SearchBot、PerplexityBot、Claude-SearchBot	现在无法出现在 AI 答案中
user-fetch	ChatGPT-User、Claude-User	现在无法出现在 AI 答案中
mixed	Bytespider、Amazonbot、Diffbot	两者兼有

此外，还有其他工具会忽略的两点：

• 有些抓取器会忽略 robots.txt。 OpenAI、Perplexity 和 Meta 文档说明，它们由用户触发的抓取器（ChatGPT-User、Perplexity-User、Meta-ExternalFetcher）可能不会遵守 robots.txt。ai-crawler/user-fetch-bypass 会告诉你何时 Disallow 不起作用——此时应改用 WAF／身份验证层进行限制。
• 过时的令牌。 anthropic-ai、Claude-Web、FacebookBot 已停用。ai-crawler/stale-tokens 会标记这些令牌并指出替代令牌——如今，User-agent: anthropic-ai 规则已不起作用。

Google-Extended 和 Applebot-Extended 这类仅用于控制的令牌从不会抓取内容——它们只设置偏好，geolint 会据此处理。

geolint 坦诚说明的内容

• llms.txt 是一项提案，并非标准。 没有任何主要 AI 厂商承诺会读取它——因此，llms-txt/* 检查结果会标记为警告和提示，而非错误。geolint 仍会检查它（且 geolint init 会生成该文件），因为它的采用率正在提高，而成本仅仅是一个文件。
• 相关性 ≠ 因果关系。 可引用性规则以已发表的 GEO 研究为依据（引用、统计数据和引文可显著提升答案中的占比；除 Googlebot 和 Applebot 外，AI 爬虫不会执行 JavaScript），但诸如疑问句式标题之类的信号只是提示，并非事实——它们的严重级别为 info，geolint 也会明确说明这一点。
• 每条规则都会说明其依据。 docs/rules.md 记录了每条规则的存在原因；研究来源见 docs/research-notes.md，其中包括各机器人 robots.txt 行为依据的厂商文档。
• 机器人注册表是一份独立的参考资料。 docs/ai-crawlers.md 列出了所有受跟踪的令牌，包括用途、各厂商的 robots.txt 行为以及厂商文档——geolint bots 和 list_ai_bots MCP 工具公开的也是同一组数据。

与其他方案的比较

	结合用途的机器人注册表	各厂商的 robots.txt 行为	可在 CI 中运行	为每项检查结果提供修复方案	生成 llms.txt	免费／开源
geolint	✅	✅	✅	✅	✅	✅
ai.robots.txt 风格的屏蔽列表	❌	❌	不适用	❌	❌	✅
GEO 优化技能／提示词包	❌	❌	❌	❌	❌	不定
llms.txt 验证器	❌	❌	部分支持	部分支持	部分支持	✅
托管式 GEO 审核 Web 应用	部分支持	❌	❌	部分支持	❌	❌

各列的详情及其依据：docs/comparison.md。 geolint 还附带 MCP 服务、评分徽章和回归基线。

路线图

计划在 v0.4+ 中推出：

• geolint watch——在部署／文件变更时重新审核
• 面向项目特定检查的自定义规则 API
• 更深入的 Schema 覆盖（更多 @type 验证器）
• Homebrew formula
• 支持英语以外的报告本地化

贡献

欢迎提交问题和 PR——请参阅 CONTRIBUTING.md。新增规则是最好的贡献：每条规则都需要 check(ctx)、带有 fix 的检查结果、测试和文档条目。

许可证

MIT · 变更日志 · 安全

---

如果 geolint 对你有帮助，点个 ⭐ 可以让更多人发现它。