QiHome3.0

开发者 · 开发者预览

为家开发。

用公开的 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 测试版提供。

sdk/examples/room-summary-skill/main.goGo
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 pack
终端 · 发布到社区商店
qihome-plugin login
qihome-plugin publish

04发布

从提交到上架,没有人工排队。

发布者的命名空间跟着 GitHub 账号走(io.github.你的用户名)。社区插件的签名密钥只在商店服务器上。

发布说明 ›
  1. 登录qihome-plugin login 用 GitHub 的设备授权登录。
  2. 提交源码qihome-plugin publish 上传源码包,不是编译好的程序。
  3. 自动审核规则、静态分析、商店从源码重新构建、在 Lab 里实际运行并记录;没有 AI 判断。没通过会写明原因,申诉找运营方。
  4. 签名上架通过后用社区密钥签名,进入社区目录;主人打开“允许社区插件”后就能安装。

05MCP

让你的 AI 应用接入家里,但守规矩。

QiHome 3.0 是一个 MCP 服务器(Streamable HTTP,JSON-RPC 2.0)。主人在“设置 → MCP”打开后,你的应用拿着为它单独生成的令牌接进来。

  • 令牌分两种

    “只能看”只读;“可以控制设备”才能动手。家人的限制和访客的房间照样生效。

  • 要人点头的,交给主人

    栖家助手需要人确认的操作,经 MCP 来时会挂起,等主人在 MCP 页面或手机上点允许;开锁、撤防一律拒绝。

  • 结果是真的

    动作的结果写明设备确认了、已发送、没确认还是有冲突,并带着撤销用的 id。最近 200 次调用都有记录。

  • 反过来也行

    栖家的助手也能用别的 MCP 服务器的工具;加载项自己的 MCP 服务器会被自动发现。

设置里的 MCP 页面:打开 MCP 服务器、AI 应用最近做了什么、让栖家助手用别的 MCP 服务器The MCP page in Settings: turn on the MCP server, what AI apps did recently, and other MCP servers for Qi Intelligence
  • 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 还没有可控时钟,也不能替换网络请求。