指南 · 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 分钟出结果。