技能与工具

技能与工具用于在设备规格之外扩展设备智能体：设备规格定义命令、状态和事件，技能与工具补充可复用流程、知识和可调用外部动作，例如巡检报告或节能建议。

什么时候使用

通常先完善设备规格，再按实际需要增加技能或工具。

目标	推荐方式
增加设备可执行的动作，例如设置温度、开关电源、切换模式	修改设备规格中的命令
增加设备会上报的数据或事件，例如湿度、制冷状态、异常告警	修改设备规格中的遥测和事件
让设备智能体按固定流程回答，例如巡检报告、排障清单、节能建议	导入并启用技能
让设备智能体访问外部信息或执行独立逻辑，例如节能策略、楼宇系统状态、告警服务	创建并启用工具
让设备智能体写文件或运行命令	在配置中开启对应工具权限

不要把设备自己的命令写成工具，也不要把需要调用外部系统的动作只写成技能。

导入技能

技能是一组可复用说明。启用技能后，用户仍然用自然语言提出目标；设备智能体会在需要时加载对应技能，并按技能中的流程完成回复。

在 技能 标签页中可以导入、启用、停用、导出或删除用户技能。

技能以 .zip 文件导入。压缩包中需要包含一个目录和 SKILL.md：

thermostat-inspection/
  SKILL.md
  references/
  templates/

SKILL.md 顶部需要包含 name 和 description：

---
name: thermostat-inspection
description: Generate an inspection report from thermostat status and recent events.
---

# Thermostat Inspection

...

以快速体验里的温控器为例，导入并启用巡检技能后，可以这样提问：

按巡检报告格式整理当前温控器最近状态、告警事件和建议处理动作。

用户不需要输入 use_skill。设备智能体会根据请求和技能描述判断是否加载技能。系统内置技能随运行时自动提供，不在用户技能列表中管理。

创建工具

工具封装一个可调用动作，可以是本地逻辑，也可以是外部系统调用。启用工具后，用户仍然通过自然语言发起请求；设备智能体会根据工具名称、描述和参数结构决定是否调用它。

在 工具 标签页中可以查看、启用、停用或删除用户工具，也可以打开工具编辑器创建新工具。

创建工具的常见步骤：

1. 进入 技能与工具，切换到 工具。
2. 点击 打开工具编辑器，再点击 新建扩展。
3. 修改工具的 name、label、description、parameters 和 execute。
4. 点击 保存。保存成功后，工具会写入 .device_agent/tools/extensions/<name>.tool.ts 并加载到当前运行时。
5. 回到 工具 标签页，确认工具出现在列表中，并保持启用状态。

下面的示例根据温控器当前温度和湿度给出设置建议。它不依赖外部接口，保存后可以直接在对话中触发；真正下发到设备的控制命令仍然由设备规格中的命令完成。

import type { AgentTool } from "@mariozechner/pi-agent-core";
import { Type } from "@sinclair/typebox";

function recommendSettings(currentTemperature: number, humidity: number) {
  if (currentTemperature >= 30) {
    return {
      mode: "cool",
      targetTemperature: 24,
      reason: "当前温度较高，建议制冷并降低目标温度。",
    };
  }

  if (currentTemperature <= 18) {
    return {
      mode: "heat",
      targetTemperature: 22,
      reason: "当前温度较低，建议制热并设置舒适目标温度。",
    };
  }

  if (humidity >= 70) {
    return {
      mode: "auto",
      targetTemperature: 24,
      reason: "当前湿度较高，建议自动模式，让设备根据环境状态调节。",
    };
  }

  return {
    mode: "eco",
    targetTemperature: 24,
    reason: "当前温湿度处于舒适范围，建议节能模式。",
  };
}

export default function (api: { registerTool(tool: AgentTool): void }) {
  api.registerTool({
    name: "recommend_thermostat_settings",
    label: "推荐温控器设置",
    description: "根据温控器当前温度和湿度给出目标温度和运行模式建议。只在用户要求节能建议、舒适度调整或根据当前状态调整温控器时使用。",
    parameters: Type.Object({
      currentTemperature: Type.Number({ description: "当前温度，单位为摄氏度" }),
      humidity: Type.Number({ description: "当前湿度，百分比" }),
    }),
    async execute(_toolCallId, params: { currentTemperature: number; humidity: number }) {
      const recommendation = recommendSettings(params.currentTemperature, params.humidity);

      return {
        content: [
          {
            type: "text",
            text: `建议切换到 ${recommendation.mode} 模式，目标温度 ${recommendation.targetTemperature} 度。${recommendation.reason}`,
          },
        ],
        details: recommendation,
      };
    },
  });
}

工具描述要说明适用场景，参数要说明需要哪些输入。content 会进入对话结果，details 会作为结构化结果保留。需要接入真实业务系统时，可以把示例中的 recommendSettings 替换为内部 API、数据库或其他服务调用。

在对话中使用

在对话中直接描述目标、设备对象和条件即可：

根据当前温度和湿度给出节能设置建议；如果建议合理，把目标温度和运行模式更新到当前模拟设备。

设备智能体可以先读取当前选中设备的状态，再调用 recommend_thermostat_settings 计算建议，最后通过设备规格中的温控器命令完成控制。工具由设备智能体在对话过程中自动选择，不需要手写工具调用。

设备智能体也可以使用内置能力：

1 分钟后把当前温控器的目标温度设为 24 度。

这类请求会使用内置 定时任务 能力。设备命令下发、MQTT 消息收发、只读数据查询、视觉分析、A2A 发布和模拟显示器更新等内置能力，会按当前场景自动提供给设备智能体，不需要在技能与工具页面手动创建。

权限与验证

• 新增、修改或停用工具后，开启新的对话验证；已有对话会继续使用创建时的工具列表。
• 工具名称只能包含字母、数字、下划线和连字符，且不能与系统内置工具重名。
• 工具编辑器的保存和删除由配置中的 permissions.tools.toolEditorMutations.enabled 控制。ENABLE_TOOL_EDITOR_MUTATIONS 可在启动时写入该值。
• 不要把工具编辑器暴露给不受信任用户。工具代码会在本地运行时执行，应像代码一样审查。
• write_file 和 execute_command 属于内置高权限工具，配置入口见 配置。
• 使用技能时，回复应遵循技能中的结构、流程或术语。
• 使用工具时，对话中应显示工具执行过程，并返回工具结果。
• 涉及设备控制时，最终命令仍然按设备规格中的命令下发。