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 mới, sửa lỗi 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, dựa trên tệp, giấy phé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, liệu 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 đầy đủ để biến điều đó thành hiện thực và chứng minh nó đang diễn 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 — lời nhắc được theo dõi, lịch sử kiểm tra, cấu hình. Không máy chủ, không tài khoản, không cơ sở dữ liệu. Chỉ cần một lần cài đặt:

npm i -g auto-geo

Được xây dựng bởi Shadow — một phòng nghiên cứu truyền thông xây dựng thế hệ công nghệ truyền thông và thông minh truyền thông tiếp theo đượ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 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 mức độ sẵn sàng trích dẫn của bất kỳ trang nào
• 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ý các lời nhắc được theo dõi
• auto-geo check — đo lường phạm vi trích dẫn thực tế
• auto-geo history — phạm vi 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 tác nhân
• Thân thiện với LLM
• Đóng góp
• Giấy phép

---

Bắt đầu nhanh

0. Cài đặt một lần (hoặc chạy bất kỳ lệnh nào một lần qua npx auto-geo@latest)

npm i -g auto-geo

1. Thiết lập — cấu hình, các ô khóa .env.local và không gian làm việc .auto-geo

auto-geo init

2. Thêm khóa API vào .env.local (được tự động tải bởi mọi lệnh)

3. Kiểm tra bất kỳ trang nào — của bạn hoặc của đối thủ

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

4. Theo dõi các lời nhắc bạn muốn công cụ AI trích dẫn bạn

auto-geo prompts add "công cụ giám sát truyền thông tốt nhất" "GEO là gì"

5. Đo lường — mỗi lần chạy được tự động lưu vào lịch sử

auto-geo check

6. Xem phạm vi thay đổi theo thời gian

auto-geo history

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

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 phát hành cùng mỗi phiên bản.

---

GEO là gì?

Tối ưu hóa cho Công cụ Tạo sinh (Generative Engine Optimization) là lĩnh vực 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. Nó là sự kế thừa của SEO: thay vì xếp hạng trong một 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 đăng 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 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 đoạn có cấu trúc; cấu trúc cứng nhắc cải thiện việc trích xuất.
2. Ưu tiên câu trả lời. Mỗi phần mở đầu bằng một "viên nang câu trả lời" dài 40–60 từ trả lời đầy đủ câu hỏi của phần đó trước bất kỳ đoạn hỗ trợ nào.
3. Tiêu đề dạng câu hỏi. Các H2 được viết dưới dạng 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, 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ẫn xuất từ schema. Article + FAQPage JSON-LD được phát ra từ cấu trúc, không 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 tiêu chuẩn đầy đủ), kiểm tra bất kỳ URL nào dựa trên nó, tạo các trang mới tuân thủ nó, và sau đó đóng 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 sự 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ả (nó có thực sự được trích dẫn không?). history biến kết quả thành một đường xu hướng.

---

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

auto-geo init # tương tác (một vài câu hỏi) auto-geo init --yes # mẫu không tương tác

Một lệnh tạo khung cho mọi thứ:

Tệp	Nó là gì
auto-geo.config.json	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 chứa bí mật.
.env.local	Các ô khóa API. Được tự động tải bởi mọi lệnh. Thêm vào gitignore.
.auto-geo/prompts.txt	Các lời nhắc được theo dõi — mỗi dòng một lời nhắc, cho phép bình luận #.
.auto-geo/checks/	Mỗi lần chạy kiểm tra, được lưu dưới dạng JSON. Dữ liệu đằng sau lịch sử.

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

---

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

Chạy nó trên bất kỳ URL nào — của bạn, của đối thủ, mọi trang trong sơ đồ trang 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).

Toàn bộ sơ đồ trang — điểm trung bình, trang điểm thấp nhất, lỗi phổ biến nhất

auto-geo doctor --site https://example.com/sitemap.xml --max-pages 50

JSON cho CI / bảng điều khiển

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

Mã thoát 0 nếu điểm ≥ 75%, 1 nếu không — dùng để kiểm soát triển khai. Xem docs/doctor.md để tham khảo kiểm tra đầy đủ.

---

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

Cung cấp cho nó 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ủ kiến trúc GEO đầy đủ.

auto-geo write
--query "GEO là gì"
--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

Lời nhắc hệ thống mã hóa GEO SOP — độ dài TL;DR, cửa sổ viên nang câu trả lời, các từ ngữ cường điệu bị cấm, 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 một vòng lặp tự sửa lỗi 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.

Chạy thử — kế hoạch + ước tính chi phí, không gọi LLM

auto-geo write --query "X là gì" --dry-run

Hàng loạt từ một tệp, anthropic, 4 trang cùng lúc

auto-geo write --queries-file queries.txt --provider anthropic --concurrency 4

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

---

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

Trong khi doctor cho bạn biết điều gì sai, fix tạo ra một bản viết lại được tối ưu hóa GEO vượt qua tất cả 8 kiểm tra — được tìm nạp, kiểm tra, tạo lại và xác thực dựa trên 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 # Dùng Claude thay thế auto-geo fix https://example.com/page --dry-run # chỉ kiểm tra + ước tính chi phí

Xem docs/fix.md.

---

auto-geo prompts — quản lý các lời nhắc được theo dõi

Các lời nhắc được 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 túy, có thể commit) và chúng là những gì check chạy theo mặc định.

auto-geo prompts add "công cụ giám sát truyền thông tốt nhất" "GEO là gì" auto-geo prompts # danh sách được đánh số auto-geo prompts rm 2 # theo chỉ mục — hoặc theo văn bản chính xác

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

auto-geo prompts discover --dry-run # xem trước các đề xuất auto-geo prompts discover --count 15 # thêm 15 (không bao giờ ghi đè, không bao giờ trùng lặp)

prompts add (và discover) khởi tạo không gian làm việc trong lần sử dụng đầu tiên, 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 phạm vi trích dẫn thực tế

Đối với mỗi lời nhắc, hỏi một công cụ tìm kiếm AI thực sự và báo cáo liệu tên miền của bạn có nằm trong số 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 # lời nhắc được theo dõi, tên miền từ cấu hình

  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 phạm vi theo từng công cụ cộng với tổng hợp chung.

Truy vấn rõ ràng thay vì bộ được theo dõi

auto-geo check --domain shadow.inc --query "GEO là gì"

Mọi công cụ bạn có khóa, phạm vi tổng hợp

auto-geo check --engine all

CI: thất bại triển khai khi các truy vấn quan trọng không trích dẫn bạn

auto-geo check --queries-file geo/critical-queries.txt && deploy

JSON phát trực tuyến cho tác nhân / bảng điều khiển

auto-geo check --ndjson

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

---

auto-geo history — phạm vi 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. Phạm vi theo từng lần chạy với các delta theo từng công cụ, cộng với chính xác những lời nhắc nào 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 với tương đương — mỗi lần chạy được đo lường 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 + delta có thể đọc bằng máy. Xem docs/history.md.

---

Cấu hình

Đặt một lần với auto-geo init, ghi đè ở bất cứ đâ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 nào đượ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 sẵn

// auto-geo.config.json — có thể commit, không có bí mật { "domain": "https://www.example.com", "basePath": "/resources", "provider": "openai", "model": "gpt-5.4", "engine": "perplexity", "concurrency": 4, "author": { "name": "Jane Doe", "jobTitle": "Trưởng phòng Nội dung", "bio": "Jane viết về tối ưu hóa công cụ tạo sinh…", }, }

Khóa API nằm trong .env.local (hoặc .env), được tự động tải bởi mọi lệnh — các biến môi trường đã được đặ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 một kiến trúc bảy khối nghiêm ngặt:

1. TL;DR — viên nang câu trả lời 40–60 từ
2. Giới thiệu — các khối thiết lập ngữ cảnh
3. Các phần — H2 dạng câu hỏi, mỗi phần mở đầu bằng một viên nang câu 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 khai báo
6. FAQ — 3–10 Hỏi & Đáp 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 ra 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ố kỹ thuật đầ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ó lên CMS của bạn, hydrate một mẫu, hoặc kết xuất nó 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 tác nhân

Mọi lệnh được xây dựng để được điều khiển bởi một tác nhân cũng như bởi con người:

• --json — một đối tượng ổn định, có thể đọc bằng máy trên stdout.
• --ndjson (check) — một dòng JSON cho mỗi truy vấn khi kết quả truyền vào, cộng với một dòng _summary.
• Tiến trình đi đến stderr, kết quả đến stdout — các đường ống vẫn sạch sẽ.
• Mã thoát ổn định — doctor và check là các cổng CI ngay lập tức.
• --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 dự định để được LLM trích dẫn — vì vậy repo này tự mình thực hành điều mình đề cao:

• llms.txt — một chỉ mục được tuyển chọn tuâ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 để tiếp nhận một lần tìm nạp.
• Trang GitHub Pages tại shadowresearch.github.io/auto-geo — quảng bá 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 tác nhân lập trình đ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à cải tiến tài liệu đều được hoan nghênh.

• Quy tắc ứng xử
• Chính sách bảo mật
• Nhật ký thay đổi

---

Giấy phép

MIT.

---

Về Shadow

Shadow là một phòng nghiên cứu truyền thông xây dựng thế hệ công nghệ truyền thông và thông minh truyền thông tiếp theo đượ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 chạy auto-geo từ đầu đến cuối theo lịch trình cho các đội ngũ nghiên cứu truyền thông, PR và truyền thông.

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