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 评测:案例页的数据,日期写在每个例子里。