进阶
自定义身体适配器
用几十行 TypeScript 让一台新设备成为身体:实现 BodyAdapter 接口,独立构建,用 QUETZAL_ADAPTER 指定。
#适配器是什么
设备的一切能力(传感器采样、系统通知、播放声音、设备动作)都由身体适配器提供,运行基座的核心只通过它接触设备。适配器是一个独立构建的 ES 模块,默认导出一个 BodyAdapter 对象。
仓库自带几个平台级的参考实现:
runtime/adapters/android/:任意安卓手机,身体能力经 Quetzal App 的本机身体接口提供,构建为dist/android.mjs;runtime/adapters/termux/:旧的 Termux 安装,任意安卓手机 + Termux:API,传感器按名字探测,构建为dist/termux.mjs;runtime/adapters/linux/:任意 Linux 机器,电池与温度读/sys,桌面工具按可用程序探测,构建为dist/linux.mjs;runtime/adapters/windows/:任意 Windows 10(1809 起)/ 11 电脑,电源读系统电源状态,通知、截图与操作屏幕、剪贴板、拍照、录音用系统自带的 PowerShell 5.1、.NET(含 UI Automation)与 WinRT,构建为dist/windows.mjs,见 Windows。
#接口
typescript
import type { BodyAdapter, RawSample, AdapterTool } from "./adapter"; // 只能 import type
const adapter: BodyAdapter = {
name: "my-board",
describe: "一块装在窗台上的开发板,有光线传感器和一个蜂鸣器",
async init() { /* 可选:打开设备、检查依赖 */ },
async sample(): Promise<RawSample> {
return {
battery: { level: 0.82, charging: true, tempC: 31 },
lux: await readLux(),
motion: 0,
extra: { humidity: 46 }, // 设备特有的读数,原样进入身体孪生
};
},
async notify(title, text) { /* 系统通知:配对码、主动消息的本地出口 */ },
async playAudio(file) { /* 播放语音合成的结果 */ },
tools: [
{
name: "beep",
description: "让蜂鸣器响一声",
parameters: { type: "object", properties: { ms: { type: "number" } } },
permission: "device", // 必须是闸门已知的能力类别
handler: async ({ ms }) => { await beep(ms ?? 200); return "响了"; },
},
],
};
export default adapter;| 成员 | 必需 | 说明 |
|---|---|---|
name / describe | 是 | describe 一句话描述这具身体,写进 ta 的自我认知 |
sample() | 是 | 一次物理采样,字段全部可选:有什么报什么 |
init() | 否 | 启动时调用一次 |
notify() | 否 | 本地系统通知;没有它配对码只能从令牌文件读 |
speak() / playAudio() | 否 | 说话 / 播放音频文件 |
tools | 否 | 设备动作,每个声明所属能力类别(device、camera、microphone、location…) |
hands | 否 | 手:读屏幕、截图、点击、拖拽、滚动、输入、按键、打开应用(类型见 适配器接口);核心据此提供 screen_* 工具,归「操作屏幕与应用」 |
#约束
- 适配器只能
import type接口文件的类型,不得依赖核心的其他实现。构建时类型被擦除,产物因此不依赖核心。 - 工具的
permission必须是闸门已知的类别,否则按「允许」处理。 - 加载失败时,核心改用通用适配器(无传感器),并在日志里说明。
- 实现
hands时,坐标一律用整屏截图的像素(原点在截图左上角),多显示器偏移与 DPI 自己换算;核心负责把它换成 ta 看到的缩小截图上的坐标。snapshot()尽量给出无障碍树里看得见的元素,并给每个元素一个ref,之后按编号操作时原样交回。做不到的动作抛错并说明怎么才能做(装什么、开什么)。openApp只打开已安装的应用。
#构建与指定
bash
npx esbuild my-adapter.ts --bundle --platform=node --target=node22 --format=esm --outfile=my-adapter.mjs
QUETZAL_HOME=~/.quetzal QUETZAL_ADAPTER=$PWD/my-adapter.mjs node --enable-source-maps main.cjs也可以写进配置 config/quetzal.json 的 adapter 字段。
#采样如何变成感受
图表加载中…
采样间隔随变化调整:有显著变化时 2 分钟,平静时逐步拉长到 10 分钟。采样不调用模型,也不算醒来。
#安卓适配器提供了什么(参考)
安卓适配器的能力与下面的 Termux 适配器相同,由 App 原生实现(拍照用 Camera2,定位定不到时返回最近一次已知位置),详见 适配器接口。旧的 Termux 适配器提供:
sample():电量 / 充电 / 体温 / 健康、光照与运动(传感器按名字探测,没有就不报);notify()(带「打开 Quetzal」按钮)、playAudio();工具 take_photo、record_audio、location、vibrate、torch、clipboard、read_sensor。它不提供 speak(很多手机没有系统 TTS),说话由运行基座的 voice_speak(Azure 语音)完成。
完整类型见 适配器接口。