HACS 預設儲存庫的收錄要求是什麼?
官方文件寫得很具體:儲存庫公開在 GitHub 上,有描述、topics 和 README,根目錄有 hacs.json,整合目錄和 manifest.json 符合規定,HACS Action 和 Hassfest 都通過,並且發過至少一個完整的 GitHub release,然後向 hacs/default 提 PR。官方還寫明:新增儲存庫要等幾個月才能審完。下面是 2026-11-14 逐頁讀 hacs.xyz 文件整理的表。
| 要求 | 官方文件的說法(2026-11-14 讀原文) | 出自哪一頁 |
|---|---|---|
| 倉庫 | 只支援 GitHub 上的公開儲存庫;一個儲存庫只能有一個整合,檔案都在 custom_components/<名字>/ 下 | /docs/publish/start/、/docs/publish/integration/ |
| hacs.json | 放在儲存庫根目錄;name 必填,其餘鍵可選(content_in_root、zip_release、filename、hide_default_branch、country、homeassistant、hacs、persistent_directory) | /docs/publish/start/ |
| manifest.json | 至少要有 domain、documentation、issue_tracker、codeowners、name、version | /docs/publish/integration/ |
| 品牌素材 | 儲存庫裡加 brand 目錄,至少有 icon.png;沒有的話檢查會回頭看 home-assistant/brands 儲存庫裡這個 domain 有沒有 | /docs/publish/integration/、/docs/publish/include/ |
| GitHub 描述和 topics | 描述要有,說明儲存庫用途,HACS 裡會顯示;topics 要有,HACS 裡不顯示,但可用於 HACS 商店裡的搜尋 | /docs/publish/start/ |
| README | 要有,寫明怎麼使用 | /docs/publish/start/ |
| 授權條款 | GitHub 能辨識、並且開放原始碼促進會(OSI)認可;辨識不了(NOASSERTION)或限制用途(例如非商用)的不通過 | /docs/publish/include/ |
| 發布 | 至少一個完整的 GitHub release,不能只是 tag;儲存庫不能是封存狀態;issues 要開著 | /docs/publish/include/ |
| 自動檢查 | HACS Action 無錯誤、無忽略地通過;Hassfest 通過(僅整合);domain 不能和核心整合衝突 | /docs/publish/include/ |
| 提交方式 | 只有擁有者或主要貢獻者能提;PR 加到 hacs/default 的 integration 檔案裡,按字母序;不能用組織帳號提交 | /docs/publish/include/ |
官方沒有寫「README 要寫多長」「描述不超過多少字」,這些數字未核實。HACS Action 的檢查項也可以在你自己的儲存庫裡提前跑,見 /docs/publish/action/。
HACS 的列表是公開網頁,還是只在應用程式裡?
我們沒有找到公開的網頁版列表。2026-11-14 實測:HACS 的目錄資料是 data-v2.hacs.xyz 上的 JSON 檔案,不是一個個網頁,裡面也沒有 README 內文;hacs.xyz 的 sitemap 只有 59 個網址,全是文件頁,沒有任何一個整合的頁面。從 Home Assistant 2026.11 起,HACS 內建成 Marketplace,只對管理員開放,在設定裡打開。
| 資料來源 | 2026-11-14 實測 | 對 AI 搜尋意味著什麼 |
|---|---|---|
| data-v2.hacs.xyz/integration/repositories.json | 200,5,166 個儲存庫(plugin 1,113,theme 125,template 12,appdaemon 55,python_script 9) | 是機器可讀的清單,不是給人看的頁面 |
| data-v2.hacs.xyz/integration/data.json | 200,約 3.5 MB;每個儲存庫有 description、domain、downloads、topics、last_version 等欄位 | 沒有 README 內文,AI 從這裡讀不到你的使用說明 |
| hacs.xyz/sitemap.xml | 200,59 個網址,全是文件頁 | 沒有收錄任何單個整合的頁面 |
| hacs.xyz/robots.txt | 404,沒有 robots.txt | 沒有規則可讀,也就沒有點名任何 AI 爬蟲 |
| 應用程式內(HACS 或 Marketplace) | 搜尋範圍是作者、類型、描述、名字、狀態、topics;詳情頁主體是儲存庫 README 的渲染 | 只在登入後的應用程式裡看到,不是公開網頁 |
這意味著:GitHub 儲存庫的「描述」「topics」「README」,是 HACS 使用者在應用程式裡搜到你、看到你的依據,也是公開網頁上唯一能被讀到的那份文字。
home-assistant.io 的 integrations 頁會收自訂整合嗎?
我們沒有看到收錄。home-assistant.io 的 sitemap 有 4,431 個網址,其中 1,701 個在 /integrations/ 下,頁面是核心整合的文件:2026-11-14 取了樣本頁 /integrations/hue/,內文直接在 HTML 裡,canonical 指向自己,有一段 BreadcrumbList 的 JSON-LD,沒有 noindex。我們把 HACS 資料裡 5,166 個整合的 domain 去對這份 sitemap:有 5,116 個不同的 domain,只有 50 個和 /integrations/ 下的某個頁面同名,其餘沒有同名頁。
同名的那 50 個是什麼情況(可能是覆蓋核心整合的自訂整合,也可能是後來進入核心的),我們沒有逐個核對,未核實。能確認的是官方 Marketplace 說明頁的態度:Marketplace 裡的內容由社群製作和發布,不是 Home Assistant 專案的,沒有經過專案的測試、稽核或支援。所以不要指望靠 home-assistant.io 的頁面被找到。
| 網站 | robots.txt(2026-11-14) | 內文能否直接讀到 |
|---|---|---|
| www.home-assistant.io | 200,76 位元組:User-agent * 加空的 Disallow:,另有 Sitemap 行;沒有點名 AI 爬蟲,全部放行 | 能:樣本頁的內文在 HTML 裡,無 noindex |
| hacs.xyz | 404,沒有 robots.txt | 能:文件頁是靜態 HTML,200 |
| community.home-assistant.io(論壇) | 未核實:/robots.txt 和首頁都回傳 403 的 Cloudflare 驗證頁,沒有繞過 | 未核實 |
| github.com | 八個 AI 爬蟲共用一組:Crawl-delay: 1,282 條 Disallow,儲存庫首頁不在其中;Bytespider 整站禁止 | 能:樣本儲存庫頁 200,README 內文在 HTML 裡 |
論壇裡有很多人討論哪個整合好用,但它對 AI 爬蟲是否開放,我們讀不到,所以不能寫「會被抓」或「不會被抓」。要在論壇發文介紹整合,把它當作給使用者的管道,不要當作 AI 搜尋的來源。
那麼對自訂整合,AI 搜尋主要讀到什麼?
主要是 GitHub 儲存庫首頁。2026-11-14 我們取了一個 HACS 整合儲存庫(starwarsfan/shadow-control):HTTP 200,約 678 KB;<title> 是「GitHub - 儲存庫名: About 文字」,meta description 是 About 文字加儲存庫名,沒有 JSON-LD;去掉腳本後的可見文字裡有 README 的內文。這只是一個樣本頁。
github.com/robots.txt 對 GPTBot、OAI-SearchBot、ChatGPT-User、ClaudeBot、Claude-SearchBot、Claude-User、PerplexityBot、Perplexity-User 八個爬蟲寫了同一組規則:Crawl-delay: 1,282 條 Disallow,禁的是 /*/archive/、/gist/、/search$ 這類路徑,沒有禁儲存庫首頁(按 robots.txt 的文字讀,沒有用真實爬蟲驗證)。README 本身怎麼寫才能被引用,見 GitHub README 會被 AI 搜尋引用嗎?;GitHub 儲存庫之外的 6 個地方,見 開源專案怎麼被 AI 搜尋推薦?README 以外的 6 個地方。本頁只講 Home Assistant 特有的部分。
| 你能控制的 | 在哪裡寫 | 誰會讀到 |
|---|---|---|
| GitHub About 描述 | 儲存庫右側 About | HACS 裡顯示的描述;儲存庫頁的 title 和 meta description |
| topics | 儲存庫 About 裡的 topics | HACS 商店裡的搜尋(HACS 裡不顯示);GitHub 上的主題頁 |
| README | 儲存庫根目錄 README.md | HACS 詳情頁的主體;儲存庫首頁內文 |
| hacs.json 的 name | 儲存庫根目錄 hacs.json | HACS 裡顯示的名字 |
| manifest.json 的 name、documentation | custom_components/<名字>/manifest.json | 整合在 Home Assistant 裡顯示的名字和文件連結 |
| 官網或文件頁(可選) | 你自己的網域 | 官網第一屏的定義,是 AI 能讀到的第二個來源 |
官網和文件頁怎麼寫,見 開發者文件怎麼寫,AI 才讀得懂、引得到?。
發布之前和之後,該做哪幾件事?
1. 儲存庫結構先對,再談文字
按下面的目錄放檔案,hacs.json、manifest.json、brand/icon.png 三樣缺一不可。
custom_components/awesome/__init__.py custom_components/awesome/manifest.json custom_components/awesome/sensor.py brand/icon.png hacs.json LICENSE README.md
{ "name": "Awesome Thermostat", "homeassistant": "2026.11.0" }2. 寫好 GitHub About 的一句話
「做什麼、對接什麼設備或服務」,開頭直接寫出品牌和型號。這句話會同時出現在 HACS 的列表、儲存庫頁的 title 和 meta description 裡。
3. topics 寫使用者會搜的詞
設備品牌、協定、類型,例如 home-assistant、hacs、integration、thermostat。HACS 官方說它們在 HACS 裡不顯示,但可用於搜尋。
4. README 首屏先答「它是什麼、怎麼裝、支援什麼」
裝法要寫成 Home Assistant 2026.11 以後的路徑(設定 > Marketplace)和舊版 HACS 的路徑,兩個都寫。支援的設備寫成表格,一行一個型號。
# Awesome Thermostat for Home Assistant One sentence: this custom integration adds <device or service> to Home Assistant and gives you <entities>. Install: Settings > Marketplace (HACS before 2026.11) > search "Awesome Thermostat" > Install. Supported devices: a table, one model per row. Configuration: Settings > Devices & services > Add integration. Entities and actions: the exact names. Requires Home Assistant 2026.11.0 or newer. Changelog: link to GitHub releases.
5. 發 GitHub release,再提 PR
只打 tag 不行,要是完整的 release;先讓 HACS Action 和 Hassfest 都通過,再向 hacs/default 提 PR。官方寫明要等幾個月,等的時候儲存庫已經可以作為自訂儲存庫被使用者手動加入。
6. 用 curl 看一遍公開頁
看儲存庫頁的標題、描述是不是你寫的那句,README 裡的一句話能不能 grep 到。內文要在 HTML 裡,原因見 AI 爬蟲會執行 JavaScript 嗎?。
# What does the public repository page say in raw HTML? curl -sL -A "Mozilla/5.0" "https://github.com/YOUR-NAME/YOUR-REPO" | grep -io '<title>[^<]*</title>' curl -sL -A "Mozilla/5.0" "https://github.com/YOUR-NAME/YOUR-REPO" | grep -io '<meta name="description"[^>]*>' curl -sL -A "Mozilla/5.0" "https://github.com/YOUR-NAME/YOUR-REPO" | grep -c "a sentence from your README" # Is your repository in the HACS catalog data? curl -s "https://data-v2.hacs.xyz/integration/repositories.json" | grep -c '"YOUR-NAME/YOUR-REPO"'
7. 開聯網搜尋問三次
在 ChatGPT、Perplexity 裡問「Home Assistant 裡怎麼接某某設備」,記下推薦了哪些整合、引用了哪些網址。AI 是否引用 GitHub 上的整合儲存庫,我們沒有證據,未核實,要靠你自己測。
官網的結構化資料見 結構化資料對 AI 搜尋有用嗎?;robots.txt 怎麼寫見 AI 爬蟲的 robots.txt 怎麼寫?。
和 Obsidian、Figma 這類有公開外掛頁的平台比,有什麼不同?
| Home Assistant 自訂整合 | Obsidian、Figma 等有公開目錄頁的平台 | |
|---|---|---|
| 公開的詳情頁 | 沒有找到:HACS 和 Marketplace 在應用程式裡;hacs.xyz 只有文件頁 | 平台為每個外掛產生一個公開頁面 |
| AI 能讀到的主要文字 | GitHub 儲存庫頁:About 描述、topics、README | 平台的外掛頁,加上 GitHub 儲存庫頁 |
| 你能改的 | About、topics、README、hacs.json、manifest.json | 各平台的欄位(標題、描述、圖庫等) |
| 官方沒寫的 | 字數上限、AI 是否引用 | 各平台不同 |
做的是 Obsidian 外掛的話,社群外掛頁和 community-plugins.json 的實測見 Obsidian 外掛怎麼在 AI 搜尋裡被找到?。
常見問題
HACS 預設儲存庫的收錄要求有哪些?
官方文件寫的是:GitHub 上的公開儲存庫;描述、topics、README 齊全;根目錄有 hacs.json(name 必填);custom_components/<名字>/ 下有 manifest.json(domain、documentation、issue_tracker、codeowners、name、version);有 brand 目錄和 icon.png;有 OSI 認可的授權條款;至少一個完整的 GitHub release;HACS Action 和 Hassfest 都通過。2026-11-14 讀原文。
提交到 hacs/default 要等多久?
官方文件寫的是「新增儲存庫要等幾個月才能審完」,沒有寫具體天數。
HACS 的列表有公開網頁嗎?
我們沒有找到。2026-11-14 實測:目錄資料是 data-v2.hacs.xyz 上的 JSON,沒有 README;hacs.xyz 的 59 個網址都是文件頁。從 Home Assistant 2026.11 起,HACS 內建成 Marketplace,在設定裡打開,只對管理員開放。
home-assistant.io 的 integrations 頁會列出我的自訂整合嗎?
我們沒有看到。它的 1,701 個 /integrations/ 網址是核心整合的文件頁;把 HACS 的 5,116 個不同 domain 去對這份 sitemap,只有 50 個同名,其餘沒有同名頁。同名的 50 個是什麼情況,我們沒有核實。
Home Assistant 社群論壇的貼文會被 AI 爬蟲讀到嗎?
未核實。2026-11-14 我們請求 community.home-assistant.io,得到的是 Cloudflare 的驗證頁(HTTP 403),沒有讀到 robots.txt,也沒有繞過。
ChatGPT 或 Perplexity 會引用我的整合儲存庫嗎?
我們沒有找到官方說明,也沒有拿到實際引用的證據,未核實。能確認的是:github.com/robots.txt 沒有禁儲存庫首頁,樣本儲存庫頁的 HTML 裡有 README 內文(2026-11-14 實測)。
還需要做官網嗎?
不是必須。儲存庫頁已經是內文直出。如果要做,寫一頁說明:定義、支援的設備表、安裝步驟、更新記錄,內容和 README 一致,並連到 GitHub 儲存庫。
出處
- HACS · Include default repositories (2026-11-14 讀原文)
- HACS · Integrations (requirements) (2026-11-14 讀原文)
- HACS · General (requirements, hacs.json) (2026-11-14 讀原文)
- HACS · Data sources (2026-11-14 讀原文)
- HACS · Marketplace (2026-11-14 讀原文)
- Home Assistant · Marketplace (2026-11-14 讀原文)
- Home Assistant · robots.txt (2026-11-14 抓取)
- Home Assistant · sitemap.xml (2026-11-14 抓取)
- HACS · HACS Data:integration/repositories.json (2026-11-14 抓取)
- GitHub · robots.txt (2026-11-14 抓取)
- kagentx 評測:案例頁的資料,日期寫在每個例子裡。