ExtSkill（扩展技能）API

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

v1.5.0 新增。类均位于 com.agibot.aiem.sdk.extskill。使用流程见 ExtSkill 指南。

类图

text

AgentSdk
  ├── registerExtSkill(ExtSkillRequest)               // 关联 LinkskyClient
  └── unregisterExtSkill(String requestId): void

ExtSkillRequest
  ├── ExtSkillRequest(agentSdk, agentId, requestId)
  ├── query(ExtSkillQueryCallback cb, long timeout): String            // 返回 eventId
  └── invoke(String extSkillId, AgentParam input,
             ExtSkillInvokeCallback cb, long timeout): String          // 返回 eventId

ExtSkillQueryCallback            // 抽象基类
  └── onQueryResult(agentId, requestId, eventId, code, msg, AgentParam result): void

ExtSkillInvokeCallback           // 抽象基类
  ├── onInvokeAck(agentId, requestId, eventId, code, msg): void
  ├── onState(agentId, requestId, eventId, stateName, stateValue): void
  └── onInvokeResult(agentId, requestId, eventId, code, msg, AgentParam param): void

IdGenerator
  └── generateExtSkillRequestId(): String    // "extskill_<21 位随机字符>"

`AgentSdk`（新增方法）

方法	说明
`registerExtSkill(ExtSkillRequest request): void`	将 request 与当前 SDK 的 `LinkskyClient` 绑定，并加入全局 `AgentSdkExtSkillMgr` 索引。必须在调用 `query` / `invoke` 之前调用。
`unregisterExtSkill(String requestId): void`	从索引中移除。用完或不再需要该会话时调用。

`ExtSkillRequest`

java

new ExtSkillRequest(AgentSdk agentSdk, String agentId, String requestId)

方法	语义
`query(ExtSkillQueryCallback cb, long timeout): String`	查询该智能体当前可用的扩展技能清单。`timeout < 50` 会被 clamp 到 50（当前仅存储不生效）。返回本次消息 `eventId`。结果通过 `cb.onQueryResult` 回传。
`invoke(String extSkillId, AgentParam input, ExtSkillInvokeCallback cb, long timeout): String`	触发指定扩展技能执行。`extSkillId` 为技能 ID；`input` 为结构化入参（`AgentParam`）；`timeout` 处理规则同 `query`。返回本次消息 `eventId`。先经 `cb.onInvokeAck` 回受理，再经 `cb.onInvokeResult` 回执行输出。
`getUpdateTs(): long`	最近一次消息发送时间（毫秒）。7200s 无活动会被后台清理。
`getAgentId()` / `getRequestId(): String`	会话身份。
`getQueryCallback()` / `getInvokeCallback()`	最近一次绑定的回调对象。

回调错误码

`code`	含义
`0`	成功（网关业务层 ACK；`result` / `param` 承载返回内容）
`-1`	服务端返回失败，`msg` 携带 `errorMsg` 详情
`1000`	本地失败：发送时 SDK 侧 `LinkskyClient` 已 closed；SDK 同步在原线程回调该 code

`ExtSkillQueryCallback`

抽象基类，继承并覆盖 onQueryResult：

java

import com.agibot.aiem.sdk.AgentParam;
import com.agibot.aiem.sdk.extskill.ExtSkillQueryCallback;

ExtSkillQueryCallback queryCallback = new ExtSkillQueryCallback() {
    @Override
    public void onQueryResult(String agentId, String requestId, String eventId,
                              int code, String msg, AgentParam result) {
        // code == 0 成功，result 承载技能清单；-1 服务端拒绝；1000 本地连接关闭（result == null）
    }
};

`ExtSkillInvokeCallback`

抽象基类，invoke 分三段回调（三个方法均抽象、需全部覆盖）：onInvokeAck（受理）→ onState（执行期间 0 到多次状态上报）→ onInvokeResult（执行输出）。

java

import com.agibot.aiem.sdk.AgentParam;
import com.agibot.aiem.sdk.extskill.ExtSkillInvokeCallback;

ExtSkillInvokeCallback invokeCallback = new ExtSkillInvokeCallback() {
    @Override
    public void onInvokeAck(String agentId, String requestId, String eventId, int code, String msg) {
        // 第一段：网关已受理本次 invoke（code == 0）
    }

    @Override
    public void onState(String agentId, String requestId, String eventId,
                        String stateName, String stateValue) {
        // 执行期间技能侧通过 agentsdk.ext_skill.report_state 上报的进度，可能 0 到多次
    }

    @Override
    public void onInvokeResult(String agentId, String requestId, String eventId,
                               int code, String msg, AgentParam param) {
        // 第三段：技能执行输出，code == 0 时 param 承载出参
    }
};

两个回调基类还包含 timeout 字段（由 setTimeout(...) 在 SDK 内部注入，clamp 到 ≥50ms 的占位值）。

`IdGenerator.generateExtSkillRequestId()`

生成形如 extskill_ABCDEFGHIJKLMNOPQRSTU 的会话 ID（前缀 + 21 位随机字符）。与 flow_ / event_ / teleop_ 等其他前缀互不冲突。

事件类型（`AgentEventType`）

见枚举参考中的 AGENTSDK_EXT_SKILL_* 段。