一个命令行工具有哪几个页面会被 AI 读到?
通常是三个:Homebrew 的 formula 页、GitHub 仓库页、官网的文档页。2026-11-12 我们拿 jq 当例子,用 curl 取了这三类页面(不执行脚本,User-Agent 是 Mozilla/5.0,没有模拟 AI 爬虫),三个都直接返回正文:
| 页面 | HTTP 和大小 | title 和 meta description | 可见正文(去掉脚本后) |
|---|---|---|---|
| formulae.brew.sh/formula/jq | 200,11,096 字节 | title 是 “Homebrew Formulae: jq”;meta description 是通用的 “Homebrew’s package index”;有 canonical | 约 1,230 字符:安装命令、一句话描述、官网、许可证、版本、依赖、下载数 |
| github.com/jqlang/jq | 200,约 297 KB | title 带项目名和一句话;meta description 是一句话加 GitHub 的通用后半句;没有 canonical 标签 | 约 5,670 字符,含 README 的 Installation 等小节 |
| jqlang.org(官网) | 200,11,540 字节 | title 只有 “jq”;没有 meta description;canonical 指向 jqlang.org | 约 2,431 字符 |
三个页面的 title 都不够描述工具本身,只有 formula 页和 GitHub 页正文里有「是什么」的一句话。所以三个地方的一句话要写成同一句,并且让官网的 title 和 description 自己写清楚;原理见 AI 爬虫会执行 JavaScript 吗?。
Homebrew 的 formula 页和 JSON API 有哪些字段?
formula 页是服务端直出的,同一份数据还有公开的 JSON API:formulae.brew.sh/api/formula/jq.json 返回 4,462 字节,不需要登录;全量的 formula.json 是 32,279,544 字节、8,730 条。几个对「被找到」有用的字段(jq 的实测值):
| 字段 | 页面上的位置 | jq 的值 |
|---|---|---|
| desc | 正文第一句 | Lightweight and flexible command-line JSON processor |
| homepage | 正文里的链接 | https://jqlang.github.io/jq/ |
| license | 正文 License 一行 | MIT |
| versions.stable | Current versions | 1.8.2 |
| executables | Binaries | jq |
| dependencies | Depends on | oniguruma 6.9.10 |
| analytics、github_packages_downloads | 下载数、安装事件(近 30 天) | 页面上写 280,128 次下载、63,420 个安装事件;数据来源和日期写在页面里 |
formula 页的 JSON-LD 只有一个通用的 WebPage,没有 SoftwareApplication;sitemap 有 16,605 个网址(含 /formula/ 的 8,731 个、含 /cask/ 的 7,826 个),没有 lastmod;robots.txt 只有一行 Sitemap,没有任何禁止规则。以上都是 2026-11-12 实测,来源 formulae.brew.sh/formula/jq。
Homebrew 官方对 desc 和 homepage 有什么要求?
Homebrew 的 Formula Cookbook(docs.brew.sh,2026-11-12 读原文)写得很短:
| 字段 | 官方要求 |
|---|---|
| desc | 用一行概括 formula 做什么;formula 名会在打印时自动加在 desc 前面,不用重复;原文没有写字符上限 |
| homepage | 必填,官方写明不接受没有 homepage 的 formula;优先用 https;官网拦自动请求时,可以写 browsed: 日期,跳过一年的自动检查 |
class Mytool < Formula desc "Command-line tool that converts CSV files to JSON" homepage "https://mytool.example.com/" url "https://github.com/example/mytool/archive/refs/tags/v1.0.0.tar.gz" license "MIT" end
上面是写法示例。官方没有写 desc 怎么影响搜索或 AI 引用,这一点我们没有证据,未核实。但 desc 同时出现在 formula 页正文和公开 JSON 里,是两个地方都读得到的那一句,值得认真写。
GitHub 仓库页和官网文档页怎么配合?
GitHub 的 robots.txt(29,821 字节)把 GPTBot、OAI-SearchBot、ChatGPT-User、ClaudeBot、Claude-SearchBot、Claude-User、PerplexityBot、Perplexity-User 放在同一个组:Crawl-delay: 1,没有 Disallow: /,禁的是 /*/tree/、/*/raw/、/*/blame/、/*/archive/ 和带 ?tab=、?q= 的网址。仓库首页没有被禁,子目录页被禁,所以 README 要在仓库首页能读完整。README 的写法见 GitHub README 会被 AI 搜索引用吗?。
官网文档页是你唯一能完全控制 title、description、canonical 和结构化数据的地方。jq 的官网 title 只有 “jq”,没有 meta description,这是一个可以改进的地方:写成「工具名 — 一句话描述」。文档的写法见 开发者文档怎么写,AI 才读得懂、引得到?。
怎么一步一步让命令行工具更容易被找到?
1. 写一句话,三个地方用同一句
formula 的 desc、GitHub 仓库的 About、官网的 meta description 和首屏第一句,写成同一句:做什么、给谁用、替代什么。
2. 官网首页和文档页写清 title 和 description
title 用「工具名 — 一句话描述」,description 写 120–160 字符的完整句子;jq 官网 title 只有工具名,是反面例子。
3. 官网放安装命令和最小例子
brew install、其他包管理器、一个能复制的最小例子。formula 页正文只有安装命令,没有例子,例子要写在官网和 README。
4. README 开头和官网对齐
README 的前几行写工具做什么和安装命令,写法见 GitHub README 会被 AI 搜索引用吗?;包仓库(npm、PyPI)的页面见 npm、PyPI 上的包怎么被 AI 推荐?。
5. robots.txt 不要误拦
官网的 robots.txt 检查有没有按 User-Agent 拦 AI 爬虫,写法见 AI 爬虫的 robots.txt 怎么写?。
6. 隔几周用同一组问题再测
问 ChatGPT、Perplexity「有没有做某某的命令行工具」「某某怎么用 brew 安装」,每个问题问 3 次,记下有没有提到你、引用了哪些网址。
同类的指南:开源项目怎么被 AI 搜索推荐?README 以外的 6 个地方;桌面端的对照见 Mac 应用怎么被 AI 推荐?、Linux 应用怎么被 AI 搜索推荐?。
常见问题
formulae.brew.sh 的 formula 页,爬虫不执行脚本也读得到吗?
读得到。2026-11-12 我们用 curl 取 jq 的页面(11,096 字节,不执行脚本),去掉脚本后约 1,230 个可见字符,里面有安装命令、一句话描述、官网、许可证、版本、依赖和下载数。只测了这一页。
formula 页的 meta description 是我的描述吗?
不是。jq 页的 meta description 是 Homebrew 通用的 “Homebrew’s package index”。你的描述出现在页面正文和 JSON API 的 desc 字段里,不在 meta description 里。我们只测了 jq 一页,其他页是否相同未核实。
desc 应该写多长?
Homebrew 的 Formula Cookbook 只要求用一行概括 formula 做什么,没有写字符上限;formula 名会自动加在 desc 前面,所以不要重复名字。
一定要有官网吗?
formula 必须有 homepage(官方原话是不接受没有 homepage 的 formula)。官网是你能把用法、对比和安装方式写全的地方,见这篇指南的步骤。
GitHub 的 robots.txt 对 AI 爬虫是什么规则?
2026-11-12 实测:GPTBot、OAI-SearchBot、ChatGPT-User、ClaudeBot、Claude-SearchBot、Claude-User、PerplexityBot、Perplexity-User 在同一个组,Crawl-delay: 1,没有 Disallow: /;禁的是 /*/tree/、/*/raw/、/*/blame/ 等路径和带 ?tab= 的网址。仓库首页没有被禁。
AI 回答里会引用 formulae.brew.sh 吗?
我们没有拿到引用证据,未核实。能确认的只是它对爬虫开放、页面直出安装命令。
官网文档页要写哪些内容?
至少写清:这个工具做什么、怎么装(brew install 和其他方式)、一个最小例子、和相近工具的区别。写法见开发者文档那篇指南。
要不要给命令行工具加 SoftwareApplication 结构化数据?
formula 页本身的 JSON-LD 只有通用的 WebPage。你自己的官网可以加,写法见 SoftwareApplication 那篇指南;加了是否被 AI 引用,我们没有证据。
出处
- Homebrew · formulae.brew.sh: robots.txt, sitemap, formula page and JSON API for jq (2026-11-12 读取)
- Homebrew · Formula Cookbook (desc and homepage) (2026-11-12 读原文,页面没有日期)
- GitHub · github.com/robots.txt and the jqlang/jq repository page (2026-11-12 读取)
- jq · jqlang.org home page (2026-11-12 读取)
- kagentx 评测:案例页的数据,日期写在每个例子里。