跳到正文

进阶

自定义身体适配器

用几十行 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 语音)完成。

完整类型见 适配器接口。