扩展技能（ExtSkill）指南

⚠️ 尚未上线：本能力为 v1.5.0-SNAPSHOT 开发中特性，接口与协议可能调整，正式发布前请勿用于生产环境。

v1.5.0 新增能力。ExtSkill = 扩展技能：二开应用把自定义技能挂到智能体上，运行期先 query 拉取该智能体当前可用的扩展技能清单，再 invoke 触发某个技能执行。它与「被动交互 / 主动交互 / 超视距遥操」并列，走独立的事件族与独立的策略枚举 AgentPolicy.EXT_SKILL（wire 值 "extskill"）。

使用场景

• 二开应用在灵心平台为智能体配置了若干扩展技能（如天气查询、工单创建、设备控制），需要在运行期动态获取清单并按需触发；
• 需要旁路对话链路直接调用一个确定性的能力（带结构化入参、拿结构化出参），而不是走 LLM 自由生成；
• 一次 invoke 分三段收结果：先 onInvokeAck 确认网关已受理，再 onState 收执行期间的状态上报（可选），最后 onInvokeResult 拿到技能真正的执行输出。

调用流程

registerExtSkill 注册后，可任意次 query 拉取清单、invoke 触发执行；不再需要时 unregisterExtSkill 释放。

   ┌─────────────────────────────┐
   │  ExtSkillRequest.query       │  拉取可用扩展技能清单
   │    (onQueryResult)           │
   └─────────────────────────────┘

   ┌─────────────────────────────┐
   │  ExtSkillRequest.invoke      │  触发某个扩展技能执行
   │    (onInvokeAck)             │  ← 第一段：网关已受理
   │    (onState)                 │  ← 第二段：执行期间状态上报（0 到多次）
   │    (onInvokeResult)          │  ← 第三段：技能执行输出
   └─────────────────────────────┘

• query 通过 onQueryResult 一次性回结果；code == 0 时 result 承载技能清单等返回内容；
• invoke 分三段：先 onInvokeAck（下发确认），再 onState（执行期间技能侧通过 agentsdk.ext_skill.report_state 上报进度，0 到多次），最后 onInvokeResult（执行输出，code == 0 时 param 承载出参）；
• 若发送瞬间 SDK 连接已关闭，query / invoke 回调会在原线程同步以 code == 1000 + msg == "Agentsdk connection is closed" 触发一次失败回执。

事件族与协议

事件类型枚举位于 com.agibot.aiem.sdk.enums.AgentEventType：

所有 ExtSkill 消息 wire 结构：

{
  "type": "<event type>",
  "agentId": "<目标智能体 agentId>",
  "eventId": "event_xxxxxxxxxxxxxxxxxxxxx",
  "agentMode": "extskill",
  "requestId": "extskill_xxxxxxxxxxxxxxxxxxxxx"
}

• 与 Teleop 用 sn 不同，ExtSkill 的机器人 / 智能体标识字段用 agentId；
• requestId 由 IdGenerator.generateExtSkillRequestId() 生成，是一次扩展技能会话的身份，query / invoke 复用同一个；
• invoke 额外携带 extSkillId（要触发的技能 ID）与 input（扁平的入参键值，对齐 input.getExtParam()）；
• agentMode 恒为 "extskill"（对应 AgentPolicy.EXT_SKILL）。

invoke 入参

invoke(extSkillId, input, callback, timeout) 的 input 是一个 AgentParam，承载该技能的结构化入参，具体键由技能定义决定。构造示例：

AgentParam input = AgentParam.create()
        .setString("city", "shanghai")
        .setInteger("days", 3);
String eventId = extSkillRequest.invoke("skill_weather", input, invokeCallback, 2000);

wire 上以扁平键值下发（input.city / input.days），与 Java 端 input.getExtParam() 输出一致。

结果错误码

query / invoke 回调的 code 语义统一：

code != 0 时，onQueryResult 的 result、onInvokeResult 的 param 均为 null。

API 速览

• 请求类：com.agibot.aiem.sdk.extskill.ExtSkillRequest
• 回调基类：ExtSkillQueryCallback（onQueryResult）/ ExtSkillInvokeCallback（onInvokeAck + onState + onInvokeResult）
• 注册：AgentSdk.registerExtSkill(ExtSkillRequest) / AgentSdk.unregisterExtSkill(requestId)
• ID：IdGenerator.generateExtSkillRequestId()

完整签名见 ExtSkill API。可运行示例见 ExtSkill 示例。

生命周期与清理

• AgentSdkExtSkillMgr 按 requestId 维护活跃 request；调用 query / invoke 前必须先 registerExtSkill(...)；
• 每次 request 方法调用会刷新内部 updateTs；超过 7200s 未活动的 request 会被后台清理线程回收；
• 用完或不再需要时，建议调用 agentSdk.unregisterExtSkill(requestId) 显式回收；
• AgentSdk.release() 会连带清理该实例名下的所有 ExtSkill request。

与 Teleop 的区别