ExtSkill（扩展技能）API · JS / 浏览器

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

v1.5.0 新增。本页列出 JS SDK 的公开 TypeScript API。wire 协议、事件类型与 Java v1.5.0 · ExtSkill API 一致；差异集中在回调模型（无回调类，走 message 事件）与浏览器鉴权（服务端代理）。使用流程见 ExtSkill 指南。

与原生 SDK 的差异

差异点	Java / Android / iOS	JS（浏览器）
创建	`new ExtSkillRequest(agentSdk, agentId, requestId)` + `registerExtSkill`	`sdk.createExtSkillSession({ agentId })` 一步完成
查询	`query(callback, timeout)`	`query()` 无回调、无 timeout 参数
触发	`invoke(extSkillId, input, callback, timeout)`	`invoke(extSkillId, input?)` 无回调、无 timeout
结果	`ExtSkillQueryCallback` / `ExtSkillInvokeCallback` 回调类	无；`sdk.on('message')` 里按 `type` 判读
释放	`unregisterExtSkill(requestId)`	无需显式反注册，会话对象失去引用即可
ID 生成	`IdGenerator.generateExtSkillRequestId()`	构造时自动生成 `extskill_<hex>`；也可通过 `options.requestId` 手动传入

导入

import {
  createAgentSdk,
  AgentSdk,
  ExtSkillSession,
  AgentEventType,
  AgentPolicy,
} from 'linksoul-agentsdk';

import type {
  ExtSkillOptions,
  ExtSkillQueryResult,
  ExtSkillInvokeAck,
} from 'linksoul-agentsdk';

类图

text

createAgentSdk(appId, options) → AgentSdk

AgentSdk
  ├── createExtSkillSession(options) → ExtSkillSession
  ├── on(event, listener) → () => void
  ├── send(message) → void
  └── newEventId() → string

ExtSkillSession
  ├── readonly agentId: string
  ├── readonly requestId: string
  ├── query() → string(eventId)
  └── invoke(extSkillId, input?) → string(eventId)

`AgentSdk`（ExtSkill 相关方法）

方法	说明
`createExtSkillSession(options: ExtSkillOptions): ExtSkillSession`	创建扩展技能会话。`options` 包含 `agentId`（必填）与可选 `requestId`（缺省自动生成 `extskill_<hex>`）。

`ExtSkillSession`

export type ExtSkillOptions = {
  agentId: string;
  requestId?: string;
};

export class ExtSkillSession {
  readonly agentId: string;
  readonly requestId: string; // 未传时自动生成 extskill_<hex>

  query(): string;
  invoke(extSkillId: string, input?: Record<string, unknown>): string;
}

方法	语义
`query(): string`	查询该智能体当前可用的扩展技能清单。发送 `agentsdk.ext_skill.query`，返回本次消息 `eventId`。结果通过 `sdk.on('message')` 收到 `ExtSkillQueryResult` 类型消息。
`invoke(extSkillId: string, input?: Record<string, unknown>): string`	触发指定扩展技能执行。`extSkillId` 为技能 ID；`input` 为结构化入参对象（原样放入 wire 的 `input` 字段）；缺省为 `{}`。发送 `agentsdk.ext_skill.invoke`，返回本次消息 `eventId`。先经 `ExtSkillInvokeAck` 回受理，再经 `ExtSkillInvokeResult` 回执行输出。

所有方法同步执行（内部 sdk.send() 立即经开着的 WebSocket 发出），返回 string（eventId），不返回 Promise；
WebSocket 未连接时调用，sdk.send 直接抛错；
无 per-session 事件回调；结果从 sdk.on('message') 解析。

下行结果判读

JS SDK 不提供回调类。在 sdk.on('message') 里按 type 判读：

sdk.on('message', ({ data }) => {
  let msg: { type: string; agentId?: string; requestId?: string; eventId?: string; code?: number; message?: string; output?: unknown };
  try { msg = JSON.parse(typeof data === 'string' ? data : ''); } catch { return; }
  switch (msg.type) {
    case AgentEventType.ExtSkillQueryResult:
      // msg.code === 0 成功，msg.output 承载技能清单
      break;
    case AgentEventType.ExtSkillInvokeAck:
      // msg.code === 0 网关已受理
      break;
    case AgentEventType.ExtSkillInvokeResult:
      // msg.code === 0 成功，msg.output 承载技能执行出参
      break;
  }
});

导出类型

export type ExtSkillOptions = {
  agentId: string;
  requestId?: string;
};

export type ExtSkillQueryResult = {
  agentId: string;
  requestId: string;
  eventId: string;
  code: number;
  message?: string;
  output?: unknown;
};

export type ExtSkillInvokeAck = {
  agentId: string;
  requestId: string;
  eventId: string;
  code: number;
  message?: string;
};

ExtSkillInvokeResult 与 ExtSkillQueryResult 形状一致（含 output）。

错误码

`code`	含义
`0`	成功（`output` 承载返回内容）
`-1`	服务端返回失败，`message` 携带错误详情

未连接时调用，底层 sdk.send 直接抛错（不走 code 回调）。

事件类型与策略

// AgentEventType 中 ExtSkill 相关常量
export const AgentEventType = {
  // ... 其他事件 ...
  ExtSkillQuery:         'agentsdk.ext_skill.query',
  ExtSkillQueryResult:   'agentsdk.ext_skill.query_result',
  ExtSkillInvoke:        'agentsdk.ext_skill.invoke',
  ExtSkillInvokeAck:     'agentsdk.ext_skill.invoke_ack',
  ExtSkillInvokeResult:  'agentsdk.ext_skill.invoke_result',
} as const;

// AgentPolicy 中 ExtSkill 常量
export const AgentPolicy = {
  // ... 其他策略 ...
  ExtSkill: 'extskill',
} as const;

wire 结构

上行 query：

json

{
  "type":      "agentsdk.ext_skill.query",
  "agentId":   "<agentId>",
  "eventId":   "event_xxxxxxxxxxxxxxxxxxxxx",
  "agentMode": "extskill",
  "requestId": "extskill_xxxxxxxxxxxxxxxxxxxxx"
}

上行 invoke：

json

{
  "type":       "agentsdk.ext_skill.invoke",
  "agentId":    "<agentId>",
  "eventId":    "event_xxxxxxxxxxxxxxxxxxxxx",
  "agentMode":  "extskill",
  "requestId":  "extskill_xxxxxxxxxxxxxxxxxxxxx",
  "extSkillId": "<技能 ID>",
  "input":      { "key": "value" }
}

agentMode 恒为 "extskill"（AgentPolicy.ExtSkill）。