ExtSkill（扩展技能）API · iOS

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

v1.5.0 新增。类均从 LinksoulAgentSDK 模块导出：import LinksoulAgentSDK 之后即可访问 ExtSkillRequest / ExtSkillQueryCallback / ExtSkillInvokeCallback。使用流程见 ExtSkill 指南。

类图

text

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

ExtSkillRequest
  ├── init(agentSdk: AgentSdk, agentId: String, requestId: String)
  ├── query(queryCallback: ExtSkillQueryCallback, timeout: Int64) -> String        // 返回 eventId (@discardableResult)
  └── invoke(extSkillId: String, input: AgentParam,
             invokeCallback: ExtSkillInvokeCallback, timeout: Int64) -> String     // 返回 eventId (@discardableResult)

open class ExtSkillQueryCallback: Timestamped
  └── open func onQueryResult(agentId: String, requestId: String, eventId: String,
                              code: Int, msg: String?, result: AgentParam?)

open class ExtSkillInvokeCallback: Timestamped
  ├── open func onInvokeAck(agentId: String, requestId: String, eventId: String,
                            code: Int, msg: String?)
  ├── open func onState(agentId: String, requestId: String, eventId: String,
                        stateName: String?, stateValue: String?)
  └── open func onInvokeResult(agentId: String, requestId: String, eventId: String,
                               code: Int, msg: String?, param: AgentParam?)

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

`AgentSdk`（新增方法）

方法	说明
`registerExtSkill(_ request: ExtSkillRequest)`	将 request 与当前 SDK 的 `LinkskyClient` 绑定，并加入 `AgentSdkExtSkillMgr` 索引。必须在调用 `query` / `invoke` 之前调用。
`unregisterExtSkill(requestId: String)`	从索引中移除。用完或不再需要该会话时调用，避免依赖 7200s 后台清理。

`ExtSkillRequest`

swift

public init(agentSdk: AgentSdk, agentId: String, requestId: String)

agentId：目标智能体的 agentId（由灵心开放平台颁发）；
requestId：会话 ID，用 IdGenerator.generateExtSkillRequestId() 生成，同一次扩展技能会话期间固定。

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

回调错误码

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

`ExtSkillQueryCallback`

open class（继承 Timestamped），业务侧继承并 override：

swift

final class MyQueryCallback: ExtSkillQueryCallback {
    override func onQueryResult(agentId: String, requestId: String, eventId: String,
                                code: Int, msg: String?, result: AgentParam?) {
        // code == 0 成功，result 承载技能清单；-1 服务端拒绝；1000 本地连接关闭（result == nil）
    }
}

`ExtSkillInvokeCallback`

open class（继承 Timestamped），invoke 分三段回调，均需 override；onState 为执行期间状态上报（0 到多次），基类有空实现、可不覆盖：

swift

final class MyInvokeCallback: ExtSkillInvokeCallback {
    override func onInvokeAck(agentId: String, requestId: String, eventId: String,
                              code: Int, msg: String?) {
        // 第一段：网关已受理本次 invoke（code == 0）
    }

    override func onState(agentId: String, requestId: String, eventId: String,
                          stateName: String?, stateValue: String?) {
        // 第二段：执行期间技能侧通过 agentsdk.ext_skill.report_state 上报的进度，0 到多次（可选覆盖）
    }

    override func onInvokeResult(agentId: String, requestId: String, eventId: String,
                                 code: Int, msg: String?, param: AgentParam?) {
        // 第三段：技能执行输出，code == 0 时 param 承载出参
    }
}

基类字段：

var agentId: String? —— SDK 内部注入；
var timeout: Int64 —— query / invoke 传入的 clamp 值；
var updateTs: Int64 —— SDK 内部用于超时清理。

`IdGenerator.generateExtSkillRequestId()`

swift

public static func generateExtSkillRequestId() -> String

返回形如 extskill_ABCDEFGHIJKLMNOPQRSTU 的会话 ID（前缀 + 21 位随机 [A-Za-z0-9]）。与 flow_ / event_ / teleop_ 等其他前缀互不冲突。

事件类型（`AgentEventType`）

iOS 端无独立 enums.md；ExtSkill 相关事件内联如下。Swift AgentEventType 使用 camelCase case 名，通过 .eventType 属性获取 wire 字符串。

Swift 枚举成员	wire 值	说明
`.extSkillQuery`	`agentsdk.ext_skill.query`	查询可用扩展技能清单（SDK → 网关）
`.extSkillQueryResult`	`agentsdk.ext_skill.query_result`	查询结果（网关 → SDK）
`.extSkillInvoke`	`agentsdk.ext_skill.invoke`	触发扩展技能执行（SDK → 网关）
`.extSkillInvokeAck`	`agentsdk.ext_skill.invoke_ack`	下发受理回执（网关 → SDK）
`.extSkillReportState`	`agentsdk.ext_skill.report_state`	执行期间状态上报（网关 → SDK）
`.extSkillInvokeResult`	`agentsdk.ext_skill.invoke_result`	执行结果（网关 → SDK）