指南 · Home Assistant

Home Assistant 自訂整合怎麼被 AI 搜尋找到?

更新於 2026-11-14 · kagentx

簡答

自訂整合在公開網頁上主要只有一處:GitHub 儲存庫頁。2026-11-14 實測:HACS 的目錄資料是 data-v2.hacs.xyz 上的 JSON(5,166 個整合儲存庫,沒有 README),hacs.xyz 的 sitemap 只有 59 個文件頁,沒有整合頁;home-assistant.io 的 1,701 個 integrations 網址是核心整合的文件,我們的對比裡只有 50 個 domain 同名;github.com 對八個 AI 爬蟲沒有禁儲存庫首頁。所以要把 GitHub 的 About、topics 和 README 寫清楚,再滿足 HACS 官方的收錄要求。

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.json200,5,166 個儲存庫(plugin 1,113,theme 125,template 12,appdaemon 55,python_script 9)是機器可讀的清單,不是給人看的頁面
data-v2.hacs.xyz/integration/data.json200,約 3.5 MB;每個儲存庫有 description、domain、downloads、topics、last_version 等欄位沒有 README 內文,AI 從這裡讀不到你的使用說明
hacs.xyz/sitemap.xml200,59 個網址,全是文件頁沒有收錄任何單個整合的頁面
hacs.xyz/robots.txt404,沒有 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.io200,76 位元組:User-agent * 加空的 Disallow:,另有 Sitemap 行;沒有點名 AI 爬蟲,全部放行能:樣本頁的內文在 HTML 裡,無 noindex
hacs.xyz404,沒有 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 描述儲存庫右側 AboutHACS 裡顯示的描述;儲存庫頁的 title 和 meta description
topics儲存庫 About 裡的 topicsHACS 商店裡的搜尋(HACS 裡不顯示);GitHub 上的主題頁
README儲存庫根目錄 README.mdHACS 詳情頁的主體;儲存庫首頁內文
hacs.json 的 name儲存庫根目錄 hacs.jsonHACS 裡顯示的名字
manifest.json 的 name、documentationcustom_components/<名字>/manifest.json整合在 Home Assistant 裡顯示的名字和文件連結
官網或文件頁(可選)你自己的網域官網第一屏的定義,是 AI 能讀到的第二個來源

官網和文件頁怎麼寫,見 開發者文件怎麼寫,AI 才讀得懂、引得到?。

發布之前和之後,該做哪幾件事?

  1. 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. 2. 寫好 GitHub About 的一句話

    「做什麼、對接什麼設備或服務」,開頭直接寫出品牌和型號。這句話會同時出現在 HACS 的列表、儲存庫頁的 title 和 meta description 裡。

  3. 3. topics 寫使用者會搜的詞

    設備品牌、協定、類型,例如 home-assistant、hacs、integration、thermostat。HACS 官方說它們在 HACS 裡不顯示,但可用於搜尋。

  4. 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. 5. 發 GitHub release,再提 PR

    只打 tag 不行,要是完整的 release;先讓 HACS Action 和 Hassfest 都通過,再向 hacs/default 提 PR。官方寫明要等幾個月,等的時候儲存庫已經可以作為自訂儲存庫被使用者手動加入。

  6. 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. 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 儲存庫。

出處

kagentx

AI 的回答裡
有沒有你?

評測會把買家的問題拿去問 ChatGPT、Perplexity、Claude(開啟連網搜尋),記下推薦了誰、引用了哪些網頁、你在不在裡面。基礎版 $1,一般 2–3 分鐘出結果。