开发者 · 开发者预览
为家开发。
用公开的 Plugin API 给 QiHome 增加能力:页面、设备和房间里的一段、首页小组件、AI 的技能、自动化模板和数据源。不需要真实的家,也不需要 QiHome 的源代码。
01平台状态
QiHome 3.0,Plugin API 0.1。
产品版本和接口版本是两回事。Plugin API 还是 0.x 开发者预览:可用、经过测试,但没有冻结。标为稳定的操作在 0.x 内保持可用;实验性的可能变化,每次变化都写在更新日志里。
- 开发者预览
SDK 0.1.1
三个平台的命令行工具、Go SDK、TypeScript 工具包、规范、文档和十个示例,一个打包好的下载(约 23 MB),含 WASM 插件和发布命令。SHA-256
- 开发者预览
装到你自己的 QiHome
打开开发模式,登记你的签名密钥,就能把自己的插件装到自己家里。
- 已上线
发布给其他家庭
社区插件商店:用 GitHub 登录,提交源码,商店自动审核、构建、签名后上架,通常一两分钟。只限声明式和 WASM 插件。
- 测试版
MCP
QiHome 作为 MCP 服务器,让你的 AI 应用接入家里;随 3.0 测试版提供。
func main() {
sdk.Run(sdk.Plugin{
Skill: func(ctx context.Context, c *sdk.Client, name string, raw json.RawMessage) (any, error) {
if name != "summarize_room_conditions" {
return nil, errors.New("unknown skill")
}
var a struct {
Room string `json:"room"`
}
json.Unmarshal(raw, &a)
var r struct {
Name string `json:"name"`
Environment struct {
Temperature *float64 `json:"temperature"`
Humidity *float64 `json:"humidity"`
} `json:"environment"`
Lighting struct {
On int `json:"on"`
} `json:"lighting"`
}
if err := c.Call(ctx, "room.get", map[string]any{"room": a.Room}, &r); err != nil {
return nil, err
}
return summary{Room: r.Name, Temperature: r.Environment.Temperature, Humidity: r.Environment.Humidity, LightsOn: r.Lighting.On}, nil
},
})
}02能用什么
插件能看到什么、能做什么。
Plugin API 0.1 有 66 个操作(30 个稳定、36 个实验性)和 61 种权限,每种权限都标明敏感程度和涉及的数据类别,安装时用大白话给主人看。
| 类别 | 插件可以 | 状态 |
|---|---|---|
| 家、房间、设备 | 读取家和房间;设备和统一的能力名(不会暴露品牌或 Home Assistant 的域);实时状态;有没有人(只说有没有,不说是谁) | 稳定 |
| 事件 | 订阅和读取最近的事件(有人、门窗、设备、环境、自动化、动作、安全、网络) | 稳定 |
| 动作 | 预览和请求动作,拿到确认过的结果;门锁、撤防、车库门一律拒绝 | 稳定 |
| 自动化 | 模板、提议、创建(主人确认)、提供条件 | 稳定 |
| 自己的东西 | 私有存储、设置、健康和日志、收件箱、发布界面数据;联网只能去声明过的 https 域名或一台局域网主机 | 稳定 |
| 更多 | 关系、户型图叠加、场景、数据源、密钥、“假如”、调试、守护和维护摘要、基础设施状态、网络摘要、备份状态 | 预览 |
| 不开放 | 官方插件专用的接口和权限、QiHome 自己的原生页面、摄像头画面、存储管理 | 不开放 |
03工具与测试
不需要真实的家,也能测到真实的反应。
Plugin Lab 是一个真实的 QiHome 内核加一个模拟的家(4 个房间、19 台设备):可以注入故障、模拟路由器、看插件的健康、页面、日志和对设备的调用。qihome-plugin dev 改一次就重新校验、构建、在新的 Lab 里跑一遍。
我们请只拿到 SDK 包的 AI 开发者从零做了两轮插件(共 18 个,覆盖页面、设备动作、侧边栏应用、自动化、AI 技能、网络和存储状态、数据源),第二轮全部通过,没有用到任何私有接口。
qihome-plugin create hello --id com.example.hello --kind basic
cd hello
qihome-plugin dev
qihome-plugin test
qihome-plugin validate
qihome-plugin packqihome-plugin login
qihome-plugin publish04发布
从提交到上架,没有人工排队。
发布者的命名空间跟着 GitHub 账号走(io.github.你的用户名)。社区插件的签名密钥只在商店服务器上。
发布说明 ›- 登录qihome-plugin login 用 GitHub 的设备授权登录。
- 提交源码qihome-plugin publish 上传源码包,不是编译好的程序。
- 自动审核规则、静态分析、商店从源码重新构建、在 Lab 里实际运行并记录;没有 AI 判断。没通过会写明原因,申诉找运营方。
- 签名上架通过后用社区密钥签名,进入社区目录;主人打开“允许社区插件”后就能安装。
05MCP
让你的 AI 应用接入家里,但守规矩。
QiHome 3.0 是一个 MCP 服务器(Streamable HTTP,JSON-RPC 2.0)。主人在“设置 → MCP”打开后,你的应用拿着为它单独生成的令牌接进来。
令牌分两种
“只能看”只读;“可以控制设备”才能动手。家人的限制和访客的房间照样生效。
要人点头的,
交给主人 栖家助手需要人确认的操作,经 MCP 来时会挂起,等主人在 MCP 页面或手机上点允许;开锁、撤防一律拒绝。
结果是真的
动作的结果写明设备确认了、已发送、没确认还是有冲突,并带着撤销用的 id。最近 200 次调用都有记录。
反过来也行
栖家的助手也能用别的 MCP 服务器的工具;加载项自己的 MCP 服务器会被自动发现。


- EndpointPOST /api/v1/mcp
- 认证Authorization: Bearer …
- Resourcesqihome://home · rooms · attention · activity
- Promptshome_brief · why · plan_scene
06现在的边界
先说清楚还做不到什么。
- 插件可以装在你自己的 QiHome 上(开发者模式),或者通过社区插件商店分发给别的家庭(只限声明式和 WASM 插件)。
- 带程序的插件只能用 Go 写;TypeScript 工具包用于声明式插件。
- 带程序的官方插件在单独的进程里运行,有资源和调用频率限制;社区插件的代码编译成 WASM,在 QiHome Core 的沙箱里运行,碰不到文件、网络和系统。
- 不能自定义 HTML,不能拿到摄像头画面,不能新增自动化的触发器或动作类型。
- Lab 还没有可控时钟,也不能替换网络请求。
07文档
从第一个插件到发布。
开发文档有中文版和英文版,在现在的网站上。
工具与发布