指南 · 開源

開源專案怎麼被 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 分鐘出結果。