auto-geo

auto-geo

Công cụ GEO mã nguồn mở giúp thương hiệu của bạn được nhắc đến trong ChatGPT, Claude, Gemini, Perplexity và Grok.

Kiểm tra, tạo, sửa và theo dõi các trang mà các mô hình ngôn ngữ lớn trích dẫn — một CLI duy nhất, dựa trên tệp, MIT.

Khi ai đó hỏi ChatGPT, Perplexity, Claude, Gemini hoặc Google AI Overviews một câu hỏi mà doanh nghiệp của bạn nên trả lời, các công cụ đó có trích dẫn tên miền của bạn không? auto-geo là vòng lặp hoàn chỉnh để biến điều đó thành hiện thực và chứng minh nó đang xảy ra:

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

Mọi thứ đều dựa trên tệp và có thể commit — theo dõi prompt, lịch sử kiểm tra, cấu hình. Không cần máy chủ, không cần tài khoản, không cần cơ sở dữ liệu. Chỉ cần cài đặt một lần:

npm i -g auto-geo

Được xây dựng bởi Shadow — một phòng thí nghiệm nghiên cứu truyền thông xây dựng thế hệ công nghệ thông tin và truyền thông hỗ trợ AI tiếp theo, hợp tác với các đội ngũ đã đưa OpenAI, TikTok, Meta, Amazon và Lovable lên bản đồ. Shadow sử dụng auto-geo để xuất bản lên shadow.inc/resources.

---

Mục lục

• Bắt đầu nhanh
• GEO là gì?
• Quy trình làm việc
• auto-geo init — thiết lập hệ thống
• auto-geo doctor — kiểm tra bất kỳ trang nào về mức độ sẵn sàng trích dẫn
• auto-geo write — tạo trang từ truy vấn
• auto-geo fix — viết lại trang để sẵn sàng trích dẫn
• auto-geo prompts — quản lý prompt theo dõi của bạn
• auto-geo check — đo lường mức độ bao phủ trích dẫn thực tế
• auto-geo history — mức độ bao phủ trích dẫn theo thời gian
• Cấu hình
• Kiến trúc trang
• Đầu ra thân thiện với agent
• Thân thiện với LLM
• Đóng góp
• Giấy phép

---

Bắt đầu nhanh

# 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

Yêu cầu Node >=18.17. Nâng cấp sau này là npm i -g auto-geo@latest. Các cách khác:

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

Các tệp thực thi độc lập (không cần Node) cho macOS, Linux và Windows được đóng gói kèm với mỗi bản phát hành.

---

GEO là gì?

Tối ưu hóa công cụ tạo sinh là kỷ luật làm cho các trang của bạn trở thành những trang mà các công cụ tìm kiếm AI trích dẫn khi chúng trả lời một câu hỏi. Đây là sự kế thừa của SEO: thay vì xếp hạng trong danh sách liên kết, bạn đang cạnh tranh để được trích dẫn bên trong câu trả lời.

Các trang chiến thắng không phải là bài blog. Nghiên cứu thực nghiệm liên kết xác suất trích dẫn với một hình dạng cụ thể:

1. Kiến trúc, không phải văn xuôi. Các khối được đặt tên, xác thực — TL;DR, giới thiệu, các phần H2 định dạng câu hỏi, hướng dẫn liên quan, điểm chính, FAQ, tiết lộ. Các công cụ AI trích xuất các khối có cấu trúc; cấu trúc cứng nhắc cải thiện việc trích xuất.
2. Trả lời trước. Mỗi phần mở đầu bằng một "viên nang trả lời" 40–60 từ trả lời đầy đủ câu hỏi của phần trước khi có bất kỳ đoạn hỗ trợ nào.
3. Tiêu đề định dạng câu hỏi. Các H2 được viết dưới dạng các câu hỏi mà người dùng thực sự hỏi các công cụ AI.
4. Mật độ thực thể cao. Các thực thể được đặt tên (công ty, con người, sản phẩm) với mật độ cao — liên kết với xác suất trích dẫn cao hơn ~4,8 lần.
5. Dựa trên schema. Article + FAQPage JSON-LD được phát ra từ cấu trúc, không phải viết tay.

auto-geo mã hóa hình dạng này trong một schema nghiêm ngặt (xem docs/sop.md — quy trình vận hành chuẩn đầy đủ), kiểm tra bất kỳ URL nào theo schema đó, tạo các trang mới tuân thủ schema, sau đó khép kín vòng lặp bằng cách đo lường xem các công cụ có thực sự trích dẫn bạn hay không.

---

Quy trình làm việc

┌──────────────────────────────────────────────────────┐
       │                    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 đo lường mức độ sẵn sàng (trang này có được định hình để trích dẫn không?). check đo lường kết quả (trang có thực sự được trích dẫn không?). history biến kết quả thành đường xu hướng.

---

auto-geo init — thiết lập hệ thống

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

Một lệnh duy nhất tạo ra mọi thứ:

Tệp	Nội dung
auto-geo.config.json	Cấu hình mặc định của bạn — tên miền, nhà cung cấp, mô hình, tác giả. Có thể commit; không bao giờ chứa bí mật.
.env.local	Các ô khóa API. Tự động tải bởi mọi lệnh. Thêm vào .gitignore.
.auto-geo/prompts.txt	Các prompt theo dõi của bạn — mỗi dòng một prompt, cho phép chú thích #.
.auto-geo/checks/	Mọi lần chạy check, được lưu dưới dạng JSON. Dữ liệu đằng sau history.

Luồng tương tác kết thúc bằng cách hỏi các prompt bạn muốn theo dõi, để một dự án mới đi từ con số không đến đường cơ sở trích dẫn có thể đo lường trong một lần ngồi. init không bao giờ ghi đè .env.local hiện có và từ chối ghi đè cấu hình hiện có nếu không có --force.

---

auto-geo doctor — kiểm tra bất kỳ trang nào về mức độ sẵn sàng trích dẫn

Chạy trên bất kỳ URL nào — của bạn, của đối thủ, mọi trang trong sitemap của bạn — và nhận báo cáo có cấu trúc về các tín hiệu trích dẫn mà các công cụ AI tìm kiếm.

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

Mã thoát 0 nếu điểm ≥ 75%, 1 nếu ngược lại — dùng để chặn triển khai. Xem docs/doctor.md để biết tài liệu tham khảo kiểm tra đầy đủ.

---

auto-geo write — tạo trang từ truy vấn

Cung cấp tên miền của bạn và các truy vấn bạn muốn được trích dẫn; nhận lại các tệp JSON đã xác thực, sẵn sàng xuất bản — mỗi truy vấn một trang có cấu trúc, tuân thủ đầy đủ kiến trúc 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

Prompt hệ thống mã hóa GEO SOP — độ dài TL;DR, cửa sổ viên nang trả lời, cấm từ cường điệu, cấu trúc FAQ — và đầu ra bị ràng buộc vào schema ở cấp hệ thống kiểu thông qua generateObject của Vercel AI SDK, với vòng lặp tự sửa có giới hạn khi xác thực thất bại. Mặc định: gpt-5.4 (OpenAI) hoặc claude-sonnet-4-6 (Anthropic), tự động phát hiện từ khóa API bạn đã đặt.

# 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

Với tệp cấu hình (auto-geo init), --domain, trường tác giả và nhà cung cấp đến từ cấu hình — chỉ cần --query trống là đủ. Xem docs/write.md.

---

auto-geo fix — viết lại trang để sẵn sàng trích dẫn

Nơi doctor cho bạn biết điều gì sai, fix tạo ra bản viết lại tối ưu GEO vượt qua tất cả 8 kiểm tra — tìm nạp, kiểm tra, tạo lại và xác thực theo cùng schema mà write sử dụng.

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

Xem docs/fix.md.

---

auto-geo prompts — quản lý prompt theo dõi của bạn

Các prompt theo dõi của bạn là những câu hỏi bạn muốn các công cụ AI trả lời bằng cách trích dẫn tên miền của bạn. Chúng nằm trong .auto-geo/prompts.txt (văn bản thuần, có thể commit) và là những gì check chạy theo mặc định.

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

Không biết theo dõi gì? Hãy để công cụ đề xuất bộ prompt của bạn — discover tìm nạp trang chủ của bạn, xem những gì bạn đã theo dõi và yêu cầu LLM tạo các truy vấn có ý định cao mà bạn nên cạnh tranh:

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

prompts add (và discover) khởi tạo không gian làm việc khi sử dụng lần đầu, vì vậy bạn thậm chí không cần init để bắt đầu theo dõi.

---

auto-geo check — đo lường mức độ bao phủ trích dẫn thực tế

Với mỗi prompt, hỏi một công cụ tìm kiếm AI thực và báo cáo xem tên miền của bạn có nằm trong các trích dẫn hay không. Đây là sự thật cơ bản mà doctor dự đoán.

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)

Các công cụ: perplexity (mặc định), openai, anthropic, gemini, xai (bí danh grok) hoặc --engine all — chạy mọi công cụ có khóa API được đặt và báo cáo mức độ bao phủ theo từng công cụ cùng tổng hợp hợp nhất.

# 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

Mỗi lần chạy được lưu vào .auto-geo/checks/ tự động (tắt bằng --no-save). Mã thoát 0 nếu mức độ bao phủ > 0%, 1 nếu 0%. Xem docs/check.md để biết hình dạng đầu ra, cách bắt truy vấn fan-out, quy tắc khớp tên miền và chế độ tương tác --format geo-audit.

---

auto-geo history — mức độ bao phủ trích dẫn theo thời gian

Phần thưởng cho việc lưu mọi lần chạy: một đường xu hướng. Mức độ bao phủ theo từng lần chạy với chênh lệch theo từng công cụ, cộng với chính xác các prompt bạn bắt đầu hoặc ngừng được trích dẫn.

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

Xu hướng so sánh tương đương — mỗi lần chạy được đo so với lần chạy trước của cùng bộ chọn công cụ. --engine all lọc các lần chạy đa công cụ; --limit N kiểm soát độ sâu; --json phát ra các hàng + chênh lệch ở dạng máy đọc được. Xem docs/history.md.

---

Cấu hình

Đặt một lần với auto-geo init, ghi đè ở bất kỳ đâu. Thứ tự ưu tiên, cao nhất trước:

1. Cờ CLI
2. Biến môi trường (nhà cung cấp tự động phát hiện từ khóa API được đặt)
3. auto-geo.config.json (đi lên từ thư mục làm việc hiện tại — thân thiện với monorepo)
4. Mặc định tích hợp

// 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…",
  },
}

Khóa API nằm trong .env.local (hoặc .env), tự động tải bởi mọi lệnh — các biến môi trường đã đặt luôn thắng:

Công cụ / nhà cung cấp	Biến môi trường
OpenAI (write, fix, check)	OPENAI_API_KEY
Anthropic (write, fix, check)	ANTHROPIC_API_KEY
Perplexity (check)	PERPLEXITY_API_KEY
Gemini (check)	GOOGLE_API_KEY hoặc GEMINI_API_KEY
xAI / Grok (check)	XAI_API_KEY

---

Kiến trúc trang

Mọi thứ write và fix tạo ra — và mọi thứ doctor kiểm tra — tuân theo kiến trúc bảy khối nghiêm ngặt:

1. TL;DR — viên nang trả lời 40–60 từ
2. Giới thiệu — các khối thiết lập bối cảnh
3. Các phần — H2 định dạng câu hỏi, mỗi phần mở đầu bằng viên nang trả lời 40–60 từ
4. Hướng dẫn liên quan — 4–8 mục
5. Điểm chính — 4–6 gạch đầu dòng khẳng định
6. FAQ — 3–10 câu hỏi và trả lời với câu trả lời 40–60 từ
7. Tiết lộ — ghi chú nguồn, dấu thời gian, dòng nhà xuất bản

Vi phạm cấu trúc là lỗi cứng (payload được tạo bị từ chối và tạo lại); các heuristic về mật độ và nhịp điệu là cảnh báo mềm. Thông số đầy đủ: docs/architecture.md, docs/validation.md và SOP đằng sau mọi ràng buộc: docs/sop.md.

JSON đầu ra không phụ thuộc vào trình kết xuất — POST nó vào CMS của bạn, hydrate một mẫu hoặc kết xuất bằng các thành phần của riêng bạn. Cấu trúc chính là hợp đồng.

---

Đầu ra thân thiện với agent

Mọi lệnh được xây dựng để agent điều khiển cũng như con người:

• --json — một đối tượng ổn định, máy đọc được trên stdout.
• --ndjson (check) — một dòng JSON cho mỗi truy vấn khi kết quả chảy vào, cộng với dòng _summary.
• Tiến trình đi đến stderr, kết quả đến stdout — các đường ống luôn sạch.
• Mã thoát ổn định — doctor và check là cổng CI ngay khi cài đặt.
• --no-color / NO_COLOR / phát hiện không phải TTY cho đầu ra thân thiện với nhật ký.

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

---

Thân thiện với LLM

auto-geo là một công cụ có đầu ra là nội dung được thiết kế để LLM trích dẫn — vì vậy kho lưu trữ này tự ăn thức ăn của chính nó:

• llms.txt — một chỉ mục được tuyển chọn theo quy ước llmstxt.org.
• llms-full.txt — README + mọi tài liệu quan trọng được nhúng vào một tệp duy nhất để tìm nạp một lần.
• Trang GitHub Pages tại shadowresearch.github.io/auto-geo — quảng cáo cả hai qua <link rel="alternate">, phát ra Article JSON-LD.
• AGENT.md — một thông số vận hành nhỏ gọn cho các agent mã hóa điều khiển CLI.

---

Đóng góp

Xem CONTRIBUTING.md. Báo cáo lỗi, cải tiến kiểm tra, công cụ mới và tinh chỉnh tài liệu đều được hoan nghênh.

---

Giấy phép

MIT.

---

Về Shadow

Shadow là một phòng nghiên cứu truyền thông đang xây dựng thế hệ tiếp theo của công nghệ trí tuệ truyền thông và truyền thông được hỗ trợ bởi AI, hợp tác với các đội ngũ đã đưa OpenAI, TikTok, Meta, Amazon và Lovable lên bản đồ. Shadow vận hành auto-geo từ đầu đến cuối theo lịch trình cho các đội nghiên cứu truyền thông, PR và truyền thông.

Tìm hiểu thêm tại shadow.inc.