auto-geo

auto-geo

讓你的品牌出現在 ChatGPT、Claude、Gemini、Perplexity 和 Grok 提及內容中的開源 GEO 引擎。

稽核、生成、修復並追蹤大型語言模型引用的頁面 — 單一 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 — 隨時間變化的引用覆蓋率
• 設定
• 頁面架構
• 代理程式友善的輸出
• 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？

生成式引擎優化是一門讓你的頁面成為 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 是否符合，生成符合規範的新頁面，然後透過衡量引擎是否實際引用你來閉合迴路。

---

工作流程

┌──────────────────────────────────────────────────────┐
       │                    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（從 cwd 向上尋找 — 對 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. 揭露聲明 — 來源註記、時間戳、發佈者行

結構違規是嚴重錯誤（生成的 payload 會被拒絕並重新生成）；密度和節奏啟發式是軟性警告。完整規格：docs/architecture.md、docs/validation.md，以及每個約束背後的 SOP：docs/sop.md。

輸出 JSON 與渲染器無關 — 可 POST 到你的 CMS、填充範本，或使用你自己的元件渲染。結構就是契約。

---

代理程式友善的輸出

每個指令都設計為可被人類和代理程式驅動：

• --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 引用的工具 — 因此這個 repo 吃自己的狗糧：

• llms.txt — 遵循 llmstxt.org 慣例的策展索引。
• llms-full.txt — README 加上所有實質文件內聯為單一檔案，便於一次擷取。
• GitHub Pages 網站位於 shadowresearch.github.io/auto-geo — 透過 <link rel="alternate"> 宣傳兩者，並發出 Article JSON-LD。
• AGENT.md — 給驅動 CLI 的編碼代理程式的精簡操作規格。

---

貢獻

請參見 CONTRIBUTING.md。歡迎錯誤回報、檢查改進、新引擎和文件修訂。

---

授權

MIT。

---

關於 Shadow

Shadow 是一家媒體研究實驗室，與打造 OpenAI、TikTok、Meta、Amazon 和 Lovable 的團隊合作，建構下一代由 AI 驅動的媒體情報與傳播技術。Shadow 以排程方式端到端運行 auto-geo，服務於媒體研究、公關與傳播團隊。

了解更多請前往 shadow.inc。