端插件概述

端插件用于让智能体或工作流调用用户设备、本地软件、桌面客户端或专用终端中的函数。AIOS 保存插件与工具契约，真实业务逻辑、设备权限和本地数据访问由端侧实现。

图 1：端插件跨越 AIOS 与终端运行边界。平台负责选择工具和生成参数，端侧调用桥与客户端负责定位设备、校验权限、执行函数并返回结构化结果。

什么是端插件

端插件是一份“平台可理解、端侧可实现”的函数契约。它至少包含稳定的工具名称、端侧函数标识、工具说明、输入参数和输出参数。发布插件只会发布这份契约，不会把客户端程序、驱动、第三方 SDK 或设备固件上传到 AIOS。

因此，端插件适合必须靠近用户或设备执行的能力，不适合把普通公网 API 再包装一层。选择错误会导致权限边界不清、调用链过长或无法完成真实试运行。

适用场景

• 读取用户明确授权的本地文件或目录。
• 调用桌面软件、企业客户端或本地自动化能力。
• 使用摄像头、麦克风、串口、蓝牙、打印机等设备能力。
• 数据因隐私、网络或性能要求必须在终端侧处理。

典型示例包括读取用户授权的日程、控制蓝牙音箱播放、调用打印机、采集摄像头画面、操作桌面软件或执行企业内网终端命令。对删除文件、发送消息、录音录像、设备控制等高风险能力，客户端必须再次向用户确认。

如果能力实际运行在远程 HTTP 服务，应创建云侧 API 插件；如果已经提供 MCP Server，应创建MCP 插件。

参与方与责任边界

参与方	负责内容
AIOS 资源库	插件基本信息、函数工具契约、调试标记、发布版本和引用关系
智能体/工作流运行时	选择工具、生成参数、发起端侧执行请求、消费结果
端侧调用桥或业务服务	识别用户与设备、路由调用、等待结果、处理取消和超时
客户端或设备	注册函数、校验权限、执行本地逻辑、返回结构化结果或错误
第三方 SDK/硬件服务	提供底层能力；其账号、许可、数据策略和稳定性不由 AIOS 保证

发布端插件不会自动安装客户端、实现函数、授予设备权限或保证设备在线。平台显示“已发布”只表示工具契约可以被引用。

创建端插件

1. 进入低代码资源库的“插件”列表并新建插件。
2. 填写插件名称、一句话介绍、描述和头像。
3. 类型选择“端插件”。
4. 创建后进入详情页，点击创建工具。
5. 维护工具名称、说明、端侧函数标识、输入参数和输出参数。
6. 在客户端或设备中实现同名函数，并保持参数和返回结构一致。

图 2：类型选择“端插件”后，不需要填写云侧服务 URL；创建后的重点是端侧函数工具和客户端实现。图中云侧创建方式只在选择“云侧插件”时显示。

设计函数工具

配置	要求
工具名称	面向模型的稳定标识，清晰表达动作
工具说明	写明调用条件、用户可见效果、风险和结果
函数标识	与客户端注册的函数名称完全一致
输入参数	明确类型、必填、路径/格式、单位、枚举和权限前提
输出参数	返回结构化结果，并与平台契约一致

函数标识建议使用英文小写、数字和下划线，并在发布后保持稳定。需要破坏性修改时，优先新增函数并迁移调用方，不要直接让旧客户端接收到无法识别的新参数。

历史端插件文档以截图、列目录和读取文件为例，这些示例仍可用于理解契约设计，但不能照搬旧接口地址。当前接入应以本项目的端侧客户端和运行时协议为准。

调用流程

端插件通常经历以下过程：

1. 用户发起请求，模型判断是否需要调用端插件工具。
2. 运行时生成符合工具契约的参数，并把执行请求交给端侧。
3. 客户端检查登录空间、设备状态和本地权限。
4. 客户端执行函数并返回结构化结果或明确错误。
5. 运行时把结果交给模型或后续工作流节点继续处理。

历史文档使用 requires_action 和“提交工具执行结果”描述这一等待过程。该思想仍可帮助理解异步等待，但旧 /v3/chat、submit_tool_outputs、24 小时过期规则和旧状态图都不是当前项目的公开接口契约，接入时不能直接照搬。

客户端实现要求

能力	最低要求
函数注册	建立函数标识到真实处理器的白名单映射；未知函数必须拒绝
参数校验	按发布 Schema 校验类型、必填、枚举、范围和文件引用
身份与设备	同时校验用户、工作空间、设备和客户端版本，禁止仅凭函数名执行
权限与确认	先检查操作系统权限；高风险操作在端侧再次获得用户确认
幂等与并发	使用调用 ID 防止重复执行；为设备互斥操作设置锁和冲突提示
超时与取消	设置执行超时，收到取消后停止可停止的本地任务并回收资源
结果与错误	返回稳定的结构化结果；区分权限拒绝、设备离线、参数错误和执行失败
日志与隐私	记录调用 ID、函数、耗时和结果状态，不记录密钥、文件正文和隐私数据

试运行与联调

当前资源库为端插件提供“完成试运行”动作。该动作只把工具的调试状态标记为通过，并不会从浏览器执行设备函数。不能只点击“完成”就认为接入成功，至少完成一次真实端到端联调：

1. 客户端版本支持当前端插件协议。
2. 设备登录了正确用户和工作空间。
3. 函数标识、输入参数和输出参数与平台一致。
4. 文件、摄像头、麦克风或设备权限已经授予。
5. 断网、设备离线、权限拒绝和执行超时都有可见错误。
6. 高风险本地操作在执行前获得用户确认。

建议同时覆盖同一用户多设备、设备离线后重连、客户端版本过旧、重复调用、执行中取消和返回字段缺失等场景。

第三方设备与 SDK

接入摄像头、音箱、打印机、车机、IoT 网关或桌面软件时，第三方厂商界面、SDK 和云服务均不属于 AIOS 系统。应单独核对：

• SDK 许可、支持系统、版本生命周期和商用限制。
• 设备账号、区域、固件、驱动和网络要求。
• 音视频、位置、通讯录、文件等数据是否离开本地，以及第三方如何保存和删除数据。
• 第三方服务不可用时是否可以降级，以及错误是否能明确反馈给用户。
• 厂商截图只用于说明厂商自身配置，不应伪装成 AIOS 页面；文档优先使用当前系统截图和自绘边界图。

文件与隐私

• 本地路径、文件内容和设备标识只在必要范围内传递。
• 限制文件类型、大小和可访问目录，防止越权读取。
• 返回文件时使用当前平台支持的文件引用或 URL，不沿用历史文件 API 示例。
• 日志不记录文件正文、访问令牌和用户隐私数据。
• 对截图、录音、发送消息、删除文件等操作提供明确确认。

端插件不应把“运行在本地”等同于“天然安全”。只要结果、日志或文件引用返回平台，就已经跨越本地边界，应按最小必要原则设计字段和留存时间。

常见故障

现象	优先检查
模型不选择工具	工具名称、说明、发布和调用方绑定状态
已选择但没有执行	客户端在线状态、用户/空间绑定、函数是否注册
参数无法解析	平台契约与客户端版本是否一致
权限被拒绝	操作系统权限、应用权限和用户确认状态
返回后工作流取不到字段	输出 Schema 与真实返回对象是否一致
同一操作执行了两次	调用 ID 是否参与幂等控制，客户端是否在重连后重复消费
新版本发布后旧设备失败	工具参数是否发生破坏性变化，客户端版本是否满足最低要求

继续阅读配置工具并试运行、在智能体和工作流中使用和发布、版本与治理。