技能与工具
技能与工具为设备智能体补充可复用流程、知识和外部服务，例如巡检报告或节能建议。设备自身的状态、动作和事件由当前物模型及接入方式提供。
适用场景
先确认当前物模型提供的设备能力，再按实际需要增加技能或工具。
| 目标 | 推荐方式 |
|---|---|
| 增加设备可执行的动作，例如设置温度、开关电源、切换模式 | 配置物模型中的命令、服务或可写属性 |
| 增加设备会上报的数据或事件，例如湿度、制冷状态、异常告警 | 配置物模型中的属性和事件 |
| 让设备智能体按固定流程回答，例如巡检报告、排障清单、节能建议 | 导入并启用技能 |
| 让设备智能体访问外部信息或执行独立逻辑，例如节能策略、楼宇系统状态、告警服务 | 创建并启用工具 |
| 让设备智能体写文件或运行命令 | 在配置中开启对应工具权限 |
设备自身的操作使用当前模型提供的能力；需要调用外部系统时，使用工具完成调用，再通过技能组织业务流程。
导入技能
技能是一组可复用说明。启用技能后，用户仍然用自然语言提出目标；设备智能体会在需要时加载对应技能，并按技能中的流程完成回复。
在 技能 标签页中可以导入、启用、停用、导出或删除用户技能。
技能以 .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。设备智能体会根据请求和技能描述判断是否加载技能。系统内置技能随运行时自动提供，不在用户技能列表中管理。
创建工具
工具封装一个可调用动作，可以是本地逻辑，也可以是外部系统调用。启用工具后，用户仍然通过自然语言发起请求；设备智能体会根据工具名称、描述和参数结构决定是否调用它。
在 工具 标签页中可以查看、启用、停用或删除用户工具，也可以打开工具编辑器创建新工具。
在编辑器中使用下方的完整代码示例。
创建工具的常见步骤：
- 进入 技能与工具，切换到 工具。
- 点击 新建工具，打开编辑器侧栏。
- 修改工具的
name、label、description、parameters和execute。 - 点击 保存，确认页面提示保存成功。
- 回到 工具 标签页，确认工具出现在列表中，并保持启用状态。
下面的示例根据温控器当前温度和湿度给出设置建议。它不依赖外部接口，保存后可以直接在对话中触发；设备控制仍使用当前物模型提供的命令或可写状态。
import type { AgentTool } from "@earendil-works/pi-agent-core";
import type { AgentToolDescriptor } from "@device-agent/shared";
import type { Type as TypeboxType } 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, descriptor: AgentToolDescriptor): void;
Type: typeof TypeboxType;
}) {
const { registerTool, Type } = 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,
};
},
}, { execution: "read", approval: "none" });
}平台部署中，每个工具注册时都需要提供第二个参数，声明执行方式和审批策略。上述建议工具只计算结果，使用 { execution: "read", approval: "none" }。会修改外部数据或执行动作的工具使用 execution: "effect"；需要用户确认的操作使用 approval: "required"，并声明审批所需的参数摘要。完整字段见API 参考。
参数结构使用 api 对象提供的 Type 构建。可以使用纯类型导入（import type ...），不支持普通 npm 包的运行时导入。工具描述要说明适用场景，参数要说明需要哪些输入。content 用于对话结果，details 用于结构化结果。接入业务系统时，可以把示例中的 recommendSettings 替换为业务 API 或其他外部服务调用。
在对话中使用
在对话中直接描述目标、设备对象和条件即可：
根据当前温度和湿度给出节能设置建议；如果建议合理，把目标温度和运行模式更新到当前选中的设备。设备智能体可以先读取当前选中设备的状态，再调用 recommend_thermostat_settings 计算建议，最后通过当前模型的温控器命令或可写状态完成控制。工具由设备智能体在对话过程中自动选择，不需要手写工具调用。
系统内置能力会按当前场景自动提供，不需要在技能与工具页面手动创建。
权限与验证
- 新增、修改或停用工具后，等待保存成功。更改用于后续请求，发起新请求验证效果。
- 工具名称只能包含字母、数字、下划线和连字符，且不能与系统内置工具重名。
- 工具编辑器的保存和删除由配置中的
permissions.tools.toolEditorMutations.enabled控制。通过控制台调整权限；启动配置的生效规则见配置。 - 不要把工具编辑器暴露给不受信任用户。工具代码会在服务端执行，应像代码一样审查。
write_file和execute_command属于内置高权限工具，配置入口见 配置。- 使用技能时，回复应遵循技能中的结构、流程或术语。
- 使用工具时，对话中应显示工具执行过程，并返回工具结果。
- 涉及设备控制时，检查当前模型的命令、服务或可写状态是否支持该操作，并验证设备实际结果。
使用已接入的设备能力
设备模型能力、技能和工具的选择见适用场景。技能和工具仍受设备范围和操作权限约束。在自动化中复用前，检查工作流 Agent 能力和定时任务的设备范围；语音工具需要单独配置。