auto-geo

auto-geo

开源 GEO 引擎，让你的品牌出现在 ChatGPT、Claude、Gemini、Perplexity 和 Grok 的引用中。

审计、生成、修复并追踪大语言模型引用的页面——一个 CLI，基于文件，MIT 许可。

当有人向 ChatGPT、Perplexity、Claude、Gemini 或 Google AI Overviews 提出你的业务应该回答的问题时，这些引擎会引用你的域名吗？auto-geo 就是实现这一目标并证明其正在发生的完整闭环：

auto-geo init      # set up the system once
auto-geo doctor    # audit any page for citation readiness
auto-geo write     # generate publish-ready pages from target queries
auto-geo fix       # rewrite an existing page so it passes the audit
auto-geo check     # measure: do AI engines actually cite you?
auto-geo history   # track citation coverage over time

一切都是基于文件且可提交的——跟踪的提示词、检查历史、配置。无需服务器、无需账户、无需数据库。一次安装即可：

npm i -g auto-geo

由 Shadow 构建——一家媒体研究实验室，与将 OpenAI、TikTok、Meta、Amazon 和 Lovable 推向世界的团队合作，打造下一代 AI 驱动的媒体智能与传播技术。Shadow 使用 auto-geo 发布内容至 shadow.inc/resources。

---

目录

• 快速开始
• 什么是 GEO？
• 工作流程
• auto-geo init —— 设置系统
• auto-geo doctor —— 审计任意页面的引用就绪度
• auto-geo write —— 根据查询生成页面
• auto-geo fix —— 重写页面以提升引用就绪度
• auto-geo prompts —— 管理你跟踪的提示词
• auto-geo check —— 衡量实际引用覆盖率
• auto-geo history —— 引用覆盖率随时间的变化
• 配置
• 页面架构
• 面向 Agent 友好的输出
• 对 LLM 友好
• 贡献
• 许可证

---

快速开始

# 0. Install once (or run any command one-shot via \`npx auto-geo@latest\`)
npm i -g auto-geo

# 1. Set up — config, .env.local key slots, and the .auto-geo workspace
auto-geo init

# 2. Add an API key to .env.local (auto-loaded by every command)

# 3. Audit any page — yours or a competitor's
auto-geo doctor https://example.com/some-page

# 4. Track the prompts you want AI engines to cite you for
auto-geo prompts add "best media monitoring tools" "what is GEO"

# 5. Measure — every run is saved to history automatically
auto-geo check

# 6. Watch coverage move over time
auto-geo history

需要 Node >=18.17。后续升级为 npm i -g auto-geo@latest。其他安装方式：

brew install shadowresearch/tap/auto-geo   # Homebrew (macOS / Linux)
mise use -g npm:auto-geo                   # mise

适用于 macOS、Linux 和 Windows 的独立可执行文件（无需 Node）随每个版本一起发布。

---

什么是 GEO？

生成式引擎优化（Generative Engine Optimization） 是一门让你的页面成为 AI 搜索引擎在回答问题时引用的对象的学科。它是 SEO 的继任者：不再是争夺链接列表中的排名，而是竞争在答案中被引用。

胜出的页面不是博客文章。实证研究将引用概率与特定的结构形态联系起来：

1. 架构，而非散文。 命名且经过验证的模块——TL;DR、引言、问题格式的 H2 章节、相关指南、关键要点、FAQ、披露声明。AI 引擎提取结构化内容块；严格的结构能提升提取效果。
2. 答案优先。 每个章节都以 40–60 字的"答案胶囊"开头，在任何支撑段落之前完整回答该章节的问题。
3. 问题格式的标题。 H2 标题写成用户实际向 AI 引擎提出的问题。
4. 实体密集。 高密度的命名实体（公司、人物、产品）——与约 4.8 倍更高的引用概率相关。
5. 由 Schema 驱动。 Article + FAQPage JSON-LD 从结构自动生成，而非手写。

auto-geo 将这种形态编码为严格的 schema（参见 docs/sop.md——完整的标准操作流程），据此审计任意 URL，生成符合该 schema 的新页面，然后通过衡量引擎是否真正引用你来闭环。

---

工作流程

┌──────────────────────────────────────────────────────┐
       │                    auto-geo init                     │
       │   config · .env.local · .auto-geo/ workspace         │
       └──────────────────────────────────────────────────────┘
             │
  ┌──────────┼──────────────┬─────────────────┐
  ▼          ▼              ▼                 ▼
doctor     write           fix             prompts
audit a    generate        rewrite an      track the queries
page       new pages       existing page   that matter to you
  │          │              │                 │
  └──────────┴──────────────┴────────┬────────┘
                                     ▼
                                   check ──── saves every run ────┐
                               measure actual                     ▼
                               citations                       history
                                                           coverage over time,
                                                           newly cited / lost

doctor 衡量就绪度（这个页面是否具备被引用的形态？）。check 衡量结果（它是否真的被引用了？）。history 将结果转化为趋势线。

---

auto-geo init —— 设置系统

auto-geo init        # interactive (a handful of questions)
auto-geo init --yes  # non-interactive template

一条命令即可搭建一切：

文件	用途
auto-geo.config.json	你的默认配置——域名、提供商、模型、作者。可提交；绝不包含密钥。
.env.local	API 密钥槽位。每条命令自动加载。加入 Gitignore。
.auto-geo/prompts.txt	你跟踪的提示词——每行一个，允许 # 注释。
.auto-geo/checks/	每次 check 运行，保存为 JSON。history 背后的数据。

交互式流程最后会询问你想跟踪的提示词，因此一个新项目可以一次性从零达到可衡量的引用基线。init 从不覆盖已有的 .env.local，并且在没有 --force 的情况下拒绝覆盖已有配置。

---

auto-geo doctor —— 审计任意页面的引用就绪度

在任意 URL 上运行它——你自己的、竞争对手的、sitemap 中的每个页面——并获得关于 AI 引擎所关注的引用信号的结构化报告。

auto-geo doctor https://example.com/some-page

✓ TL;DR present (52 words, in range)
✗ Question-format H2 headings (2 of 6 are question-format; SOP §3 targets all)
✓ Article JSON-LD present
✗ FAQPage JSON-LD present (No FAQPage JSON-LD block detected)
✓ Entity density (12.3/1k words)
✗ Image cadence (0 images for 1247 words)
✓ Answer-first first paragraph
✓ No self-link in related guides

Score: 5 / 8 checks pass — moderate GEO posture

Top 3 fixes (ranked by citation lift):
  1. Add a FAQPage JSON-LD block. Each Q is a citable extraction target.
  2. Convert 4 statement-form H2 headings to question form.
  3. Add 2 images with descriptive alt text (entity + context).

# Whole sitemap — mean score, lowest-scoring pages, most common failures
auto-geo doctor --site https://example.com/sitemap.xml --max-pages 50

# JSON for CI / dashboards
auto-geo doctor https://example.com/page --json

如果得分 ≥ 75%，退出码为 0，否则为 1——用它来把关部署。完整的检查参考见 docs/doctor.md。

---

auto-geo write —— 根据查询生成页面

提供你的域名和你希望被引用的查询；你将获得经过验证、可直接发布的 JSON 文件——每个查询对应一个结构化页面，符合完整的 GEO 架构。

auto-geo write \
  --query "what is GEO" \
  --query "GEO vs SEO" \
  --out ./resources

✓ "what is GEO"        → ./resources/geo.json (validated, ~$0.06)
✓ "GEO vs SEO"         → ./resources/geo-vs-seo.json (validated, ~$0.06)

Total: 2 pages · 2 ok · ~$0.12 spent · 31s elapsed

系统提示词编码了 GEO SOP——TL;DR 长度、答案胶囊窗口、禁止的夸张用语、FAQ 结构——并且输出通过 Vercel AI SDK 的 generateObject 在类型系统层面被约束到 schema，验证失败时有有界的自我修正循环。默认值：gpt-5.4（OpenAI）或 claude-sonnet-4-6（Anthropic），根据你设置的 API 密钥自动检测。

# Dry-run — plan + cost estimate, no LLM calls
auto-geo write --query "what is X" --dry-run

# Batch from a file, anthropic, 4 pages at a time
auto-geo write --queries-file queries.txt --provider anthropic --concurrency 4

有了配置文件（auto-geo init），--domain、作者字段和提供商都来自配置——只需一个裸的 --query 即可。参见 docs/write.md。

---

auto-geo fix —— 重写页面以提升引用就绪度

当 doctor 告诉你哪里有问题时，fix 会生成一个通过全部 8 项检查的 GEO 优化重写——获取、审计、重新生成，并针对 write 使用的同一 schema 进行验证。

auto-geo fix https://www.example.com/some-blog-post --out ./fixed.json

Score (before):    3 / 8
Generating rewrite via openai gpt-5.4...
Score (projected): 8 / 8 — strong GEO posture
→ ./fixed.json (validated)

auto-geo fix https://example.com/page --provider anthropic   # Claude instead
auto-geo fix https://example.com/page --dry-run              # audit + cost estimate only

参见 docs/fix.md。

---

auto-geo prompts —— 管理你跟踪的提示词

你跟踪的提示词是你希望 AI 引擎通过引用你的域名来回答的问题。它们存放在 .auto-geo/prompts.txt（纯文本，可提交）中，也是 check 默认运行的内容。

auto-geo prompts add "best media monitoring tools" "what is GEO"
auto-geo prompts            # numbered list
auto-geo prompts rm 2       # by index — or by exact text

不知道要跟踪什么？让引擎来建议你的提示词集——discover 获取你的首页，查看你已跟踪的内容，并让 LLM 生成你应该竞争的高意图查询：

auto-geo prompts discover --dry-run    # preview the proposals
auto-geo prompts discover --count 15   # append 15 (never overwrites, never duplicates)

prompts add（和 discover）在首次使用时引导工作区，所以你甚至不需要 init 就能开始跟踪。

---

auto-geo check —— 衡量实际引用覆盖率

对于每个提示词，向真实的 AI 搜索引擎提问，并报告你的域名是否在引用之列。这是 doctor 所预测的基准真相。

auto-geo check        # tracked prompts, domain from config

using 3 tracked prompts from .auto-geo/prompts.txt
  [1/3] ✗ "what is GEO" — not cited (5 sources)
  [2/3] ✓ "how do I get cited by ChatGPT" — cited (2 sources)
  [3/3] ✓ "open source GEO tools" — cited (1 source)

Coverage: 2/3 queries (67%) · 3 page citations total · ~$0.012 spent
  saved → .auto-geo/checks/2026-06-10T13-22-05--perplexity.json (auto-geo history)

引擎：perplexity（默认）、openai、anthropic、gemini、xai（别名 grok）或 --engine all——它会运行所有已设置 API 密钥的引擎，并报告每个引擎的覆盖率以及并集汇总。

# Explicit queries instead of the tracked set
auto-geo check --domain shadow.inc --query "what is GEO"

# Every engine you have keys for, union coverage
auto-geo check --engine all

# CI: fail the deploy when critical queries don't cite you
auto-geo check --queries-file geo/critical-queries.txt && deploy

# Streaming JSON for agents / dashboards
auto-geo check --ndjson

每次运行都会自动保存到 .auto-geo/checks/（可通过 --no-save 选择退出）。如果覆盖率 > 0%，退出码为 0；如果为 0%，则为 1。输出格式、扇出查询捕获、域名匹配规则以及 --format geo-audit 互操作模式参见 docs/check.md。

---

auto-geo history —— 引用覆盖率随时间的变化

保存每次运行的回报：一条趋势线。逐次运行的覆盖率及每个引擎的增量，以及你开始或停止被引用的具体提示词。

auto-geo history

2026-06-01 08:30  perplexity   33% ·   1/3 cited  $0.01
2026-06-08 09:15  perplexity   67% ↑34  2/3 cited  $0.01

Since last run (perplexity · 2026-06-01 08:30 ▸ 2026-06-08 09:15)
  ✓ newly cited  open source GEO tools
  ✗ lost         (none)

2 runs · .auto-geo/checks

趋势对比是同类型比较——每次运行都与同一引擎选择器的上一次运行进行对比。--engine all 过滤到多引擎运行；--limit N 控制深度；--json 以机器可读方式输出行 + 增量。参见 docs/history.md。

---

配置

使用 auto-geo init 设置一次，随处覆盖。优先级从高到低：

1. CLI 标志
2. 环境变量（根据设置的 API 密钥自动检测提供商）
3. auto-geo.config.json（从当前工作目录向上查找——对 monorepo 友好）
4. 内置默认值

// auto-geo.config.json — committable, no secrets
{
  "domain": "https://www.example.com",
  "basePath": "/resources",
  "provider": "openai",
  "model": "gpt-5.4",
  "engine": "perplexity",
  "concurrency": 4,
  "author": {
    "name": "Jane Doe",
    "jobTitle": "Head of Content",
    "bio": "Jane writes about generative engine optimization…",
  },
}

API 密钥存放在 .env.local（或 .env）中，由每条命令自动加载——已设置的环境变量始终优先：

引擎 / 提供商	环境变量
OpenAI（write、fix、check）	OPENAI_API_KEY
Anthropic（write、fix、check）	ANTHROPIC_API_KEY
Perplexity（check）	PERPLEXITY_API_KEY
Gemini（check）	GOOGLE_API_KEY 或 GEMINI_API_KEY
xAI / Grok（check）	XAI_API_KEY

---

页面架构

write 和 fix 生成的所有内容——以及 doctor 审计的所有内容——都遵循严格的七模块架构：

1. TL;DR —— 40–60 字答案胶囊
2. 引言 —— 设定上下文的模块
3. 章节 —— 问题格式的 H2，每个以 40–60 字答案胶囊开头
4. 相关指南 —— 4–8 条
5. 关键要点 —— 4–6 条陈述性要点
6. FAQ —— 3–10 个问答，答案 40–60 字
7. 披露声明 —— 来源说明、时间戳、发布者信息

结构违规是硬错误（生成的负载会被拒绝并重新生成）；密度和节奏启发式规则是软警告。完整规范：docs/architecture.md、docs/validation.md，以及每个约束背后的 SOP：docs/sop.md。

输出的 JSON 与渲染器无关——你可以将其 POST 到 CMS、填充模板，或使用自己的组件渲染。结构就是契约。

---

面向 Agent 友好的输出

每条命令都设计为既可由人类驱动，也可由 Agent 驱动：

• --json —— stdout 上输出一个稳定的、机器可读的对象。
• --ndjson（check）—— 结果流入时每个查询输出一行 JSON，外加一行 _summary。
• 进度输出到 stderr，结果输出到 stdout——管道保持干净。
• 稳定的退出码——doctor 和 check 开箱即用即可作为 CI 门槛。
• --no-color / NO_COLOR / 非 TTY 检测，实现日志友好的输出。

auto-geo check --ndjson | jq 'select(.cited) | .query'

---

对 LLM 友好

auto-geo 是一个输出内容旨在被 LLM 引用的工具——因此这个仓库在吃自己的狗粮：

• llms.txt —— 遵循 llmstxt.org 约定的精选索引。
• llms-full.txt —— README + 所有实质性文档内联到单个文件中，一次获取即可摄入。
• GitHub Pages 站点位于 shadowresearch.github.io/auto-geo——通过 <link rel="alternate"> 宣传两者，并输出 Article JSON-LD。
• AGENT.md —— 面向驱动 CLI 的编码 Agent 的紧凑操作规范。

---

贡献

参见 CONTRIBUTING.md。欢迎提交 Bug 报告、检查改进、新引擎和文档优化。

---

许可证

MIT。

---

关于 Shadow

Shadow 是一家媒体研究实验室，与将 OpenAI、TikTok、Meta、Amazon 和 Lovable 推向世界的团队合作，构建下一代由 AI 驱动的媒体智能与传播技术。Shadow 按计划为媒体研究、公关和传播团队端到端运行 auto-geo。

了解更多信息，请访问 shadow.inc。