指南 · 开源

开源项目怎么被 AI 搜索推荐?README 以外的 6 个地方

更新于 2026-11-07 · kagentx

短答案

除了 README,你能写的文字还有包页(npm、PyPI)的描述和关键词、文档站、项目官网、awesome 列表和版本发布说明。2026-11-07 我们读了 pypi.org 的 robots.txt:没有为 AI 爬虫单列规则,项目页没被禁;npm 的 robots.txt 被 Cloudflare 验证页挡住,没读到,规则未核实。AI 是否引用包页,官方没写、我们也没有证据,所以把项目的定义同时写在自己的官网和文档站上,包页的描述和关键词当作 npm、PyPI 站内搜索用。

README 以外,AI 还会从哪里了解一个开源项目?

有六处可以写、而且你能控制的文字:包页(npm、PyPI)、文档站、项目官网、awesome 列表、版本发布说明,加上 README 本身。README 单独一篇讲过,见 GitHub README 会被 AI 搜索引用吗?。下面这张表说的是另外五处各自的特点。哪一家 AI 会读哪一处,三家 AI 公司的官方文档都没有写,我们未核实;表里只放能查到的事。

位置你能写什么我们查到的
npm / PyPI 包页一行描述、关键词、主页和文档链接、README字段的用途有官方说明;两家网站对程序化请求都出现验证页(下一节)
文档站一页一个问题的文档、版本号、更新日期写法见开发者文档指南;抽样 11 个文档站的 llms.txt 在那一篇
项目官网一句话定义、对比表、安装方法、价格或许可证你唯一完全控制的页面,可加结构化数据
awesome 列表被别人的精选列表收录,带一句描述各列表规则不同;sindresorhus/awesome 在 2026-11-07 暂停了接收合并请求
版本发布说明每个版本改了什么、要求什么版本GitHub 发布基于 Git 标签,说明可手写或自动生成

npm 和 PyPI 对 AI 爬虫是什么态度?

我们在 2026-11-07 读了两家的 robots.txt:PyPI 没有为 AI 爬虫单独写规则,项目页没被禁;npm 的 robots.txt 我们没读到,因为请求被 Cloudflare 的验证页挡了。两个结果都不能证明 AI 爬虫实际取不取得到包页,也不能证明会被引用。

我们做了什么结果(2026-11-07)能说明什么
读 pypi.org/robots.txtHTTP 200。只有一组 “User-agent: *”,加一行 sitemap;禁 /simple/、/packages/、/pypi/*/json、/search*、/account/ 等;没有为 GPTBot、ClaudeBot、PerplexityBot 单列规则按 robots.txt 的字面读,AI 爬虫和别的爬虫一样:项目页 /project/<名字>/ 可抓,包文件和 JSON 接口不可抓
读 www.npmjs.com/robots.txtHTTP 403,返回的是 Cloudflare 的 “Just a moment...” 验证页;换成 GPTBot、ClaudeBot 的 User-Agent 字符串同样 403;WebFetch 也是 403规则没读到,未核实;说明 npm 的网站对我们这种程序化请求有验证,真实 AI 爬虫是否也遇到,我们不知道
打开 pypi.org/project/requests/(WebFetch)得到的是 “Client Challenge” 页,没有摘要、README 和侧栏链接包页对程序化请求也可能出现验证;AI 爬虫实际能不能取到,未核实

这意味着:不要把“项目是什么”只写在包页上。包页的描述和关键词主要服务于 npm 和 PyPI 自己的搜索,你要被 AI 读到,同样的定义也要写在你自己的官网和文档站上,见 AI 爬虫的 robots.txt 怎么写? 和 AI 爬虫 User-Agent 对照表。

npm 的 description 和 keywords 要怎么写?

官方文档(npm Docs · package.json,2026-11-07 核对)写明:description 和 keywords 都是为了让人在 npm search 里找到你的包;homepage 填项目主页,repository 填代码地址,README 和 LICENSE 总会随包发布。npm 搜索把搜索词和包的 title、description、readme、keywords 匹配,按匹配度排序,对垃圾包和很新的包略降权;新发布的包最多两周才出现在搜索里,被弃用的包不出现。

字段怎么写为什么
description一句话:是什么、做什么、支持的运行环境和版本。不写口号它参与 npm 搜索匹配,也是包页最先显示的一句
keywords4 到 8 个用户会搜的词:功能、类别、竞品常用的叫法官方说它同样帮助被搜到;堆无关的词会被当成垃圾包降权
homepage填你的官网或文档首页的完整网址把读到包页的人和程序带到你能控制的页面
repository填仓库地址让人和 npm repo 命令找到代码
{
  "name": "examplemd",
  "version": "2.4.0",
  "description": "Command-line tool that converts Markdown notes into a static site. Node.js 18+.",
  "keywords": ["markdown", "static-site-generator", "cli", "notes"],
  "homepage": "https://example.com/examplemd/",
  "repository": { "type": "git", "url": "git+https://github.com/example/examplemd.git" }
}

PyPI 的 description、keywords 和项目链接要怎么写?

Python 打包指南(Writing your pyproject.toml,2026-11-07 核对)写明:description 是一行摘要,显示在项目页标题处和搜索结果列表;readme 是项目页上的长描述;keywords 帮助 PyPI 搜索框推荐你的项目;classifiers 只用于搜索和浏览;urls 显示在项目页左侧栏,Homepage、Documentation、Changelog 这些常见标签有特定含义。

字段怎么写为什么
description一行摘要:是什么、支持的 Python 版本显示在项目页标题处和搜索结果里
readme指向 README.md,开头照 README 指南写它就是项目页上的长描述,PyPI 页和 GitHub 页用同一份文字
keywords用户会搜的词官方说它帮助搜索框推荐你的项目
project.urls至少填 Homepage、Documentation、Changelog 三个常见标签显示在项目页左侧栏,标签有特定含义
[project]
name = "examplemd"
description = "Command-line tool that converts Markdown notes into a static site. Python 3.9+."
readme = "README.md"
keywords = ["markdown", "static site generator", "cli", "notes"]

[project.urls]
Homepage = "https://example.com/examplemd/"
Documentation = "https://example.com/examplemd/docs/"
Changelog = "https://github.com/example/examplemd/releases"

awesome 列表和版本发布说明有什么用?

awesome 列表是别人维护的精选清单,被收录等于在一个别人写的页面里出现一行带描述的链接,和“最佳工具”文章是同一类来源,做法见 怎么进「最佳 X 工具」榜单文章?。每个列表的收录规则不同,投稿前读它的贡献说明;比如 sindresorhus/awesome 本身,我们 2026-11-07 看到它写着合并请求暂时关闭,细则在它链接的 contributing.md,我们没读。

版本发布说明是 AI 回答“这个版本改了什么”“升级要注意什么”时最可能读的文字。GitHub 的发布基于 Git 标签,说明可以手写,也可以用默认模板或自定义模板自动生成(GitHub Docs · About releases,2026-11-07 核对)。官方没写发布说明该包含什么,下面是我们的建议写法:第一段说清这个版本最重要的一件事和版本要求,改动分类列出,破坏性改动写出迁移办法。

## 2.4.0 (2026-11-07)

Adds incremental builds: unchanged notes are skipped, so a rebuild of 2,000
notes takes seconds instead of minutes. Requires Node.js 18 or later.

### Changed
- `--out` now defaults to ./site (was ./dist). Migration: pass --out ./dist to keep the old path.

### Fixed
- Wiki links with spaces in the target no longer break the build (#312).

开头怎么写成能被摘走的样子,见 怎么写出 AI 愿意引用的内容?改写前后对照;官网加什么结构化数据,见 结构化数据对 AI 搜索有用吗?。

如果你的项目是 MCP 服务器或 Hugging Face 上的模型,它们各有自己的目录页和元数据,见 MCP 服务器怎么被 AI 推荐、被连接器目录收录? 和 Hugging Face 上的模型和 Space 怎么被 AI 推荐?。

怎么一步一步改?

  1. 1. 先把 README 改好

    README 同时是 GitHub 页、npm 页和 PyPI 页的正文。照 GitHub README 会被 AI 搜索引用吗? 重写第一段,其余几处都会受益。

  2. 2. 改包的 description 和 keywords

    一句话写清是什么、做什么、要求什么版本;关键词只写用户会搜的词。npm 的写在 package.json,PyPI 的写在 pyproject.toml。

  3. 3. 填全主页、文档和更新日志链接

    npm 填 homepage,PyPI 填 Homepage、Documentation、Changelog。这些是把人和爬虫带到你自己网站的出口。

  4. 4. 官网和文档站写同一句定义

    官网第一屏用一句话定义项目,文档站一页一个问题,见 开发者文档怎么写,AI 才读得懂、引得到?。确认你自己的 robots.txt 没有拦 AI 爬虫。

  5. 5. 每次发布写清楚发布说明

    第一段说最重要的改动和版本要求,破坏性改动写迁移办法,日期写在标题里。

  6. 6. 挑几个相关的 awesome 列表投稿

    先读每个列表的贡献说明,按它的格式写一行描述,如实写项目是什么,不夸大。

  7. 7. 几周后用同样的问题再测

    问 AI “有什么开源工具可以做 X”,每个问题问 3 次,看你出现几次、引用了哪些网址,方法见 怎么衡量 AI 可见度?四个指标和一张可照做的表。注意新发布的 npm 包最多两周才出现在 npm 搜索里。

如果你的项目是 WordPress 插件,目录页和 readme.txt 的写法见 WordPress 插件怎么被 AI 推荐?。

如果你的项目是 Linux 桌面应用,Flathub、Snap Store、AUR 的页面怎么读,见 Linux 应用怎么被 AI 搜索推荐?。

项目发布成 Docker 镜像或 GitHub Action 的话,Docker Hub 和 Marketplace 页面的实测见 Docker 镜像和 GitHub Action 怎么被 AI 推荐?Docker Hub 与 Marketplace 页面实测。

做的是 Blender 插件的话,Extensions 平台的 robots.txt、详情页 HTML 实测和官方上架要求见 Blender 插件怎么被 AI 搜索找到?Extensions 平台实测与官方上架要求。

常见问题

npm 的 keywords 对 AI 搜索有用吗?

官方文档只说 keywords 让包在 npm search 里更容易被找到。AI 搜索是否读 keywords,没有官方说明,我们未核实。

PyPI 允许 AI 爬虫抓取吗?

2026-11-07 读取的 pypi.org/robots.txt 只有一组 “User-agent: *”,没有为 GPTBot、ClaudeBot、PerplexityBot 等单列规则;禁止的是 /simple/、/packages/、/pypi/*/json、/search*、/account/ 等路径,项目页没有被禁。

npm 的 robots.txt 对 AI 爬虫怎么写?

未核实。2026-11-07 我们请求 www.npmjs.com/robots.txt,得到的是 Cloudflare 的验证页(HTTP 403),没有读到文件。

新发布的包多久能在 npm 上搜到?

npm 官方文档写的是:新发布的包最多可能要两周才出现在搜索里,被弃用的包不出现。

要不要给开源项目做官网?

建议做。包页和 README 受平台格式限制,不能放结构化数据,页面上还有很多无关的界面文字;官网是你唯一完全控制的页面。一页就够:一句话定义、安装方法、对比表、文档链接。

出处

kagentx

你的页面,爬虫读得到吗?
让评测告诉你

评测检查爬虫能不能进、正文是否直出,再把买家的问题拿去问 ChatGPT、Perplexity、Claude(开联网搜索),看有没有提到你。基础版 $1,一般 2–3 分钟出结果。