API docs by Redocly

Skill 召回 (0.1.3)

Download OpenAPI specification:

按业务上下文召回 Skill 候选。Agent 在运行时传入知识网络与对象类（可再加具体 实例），拿回一批相关 Skill 的最小元数据（skill_id / name / description）， 再决定装载哪一个。

召回只是入口。拿到 skill_id 之后：get_skill_content 读 SKILL.md 正文与包内 文件清单，read_skill_file 按 rel_path 单取附属文件（渐进式加载，大文件不必 常驻上下文），execute_skill 在沙箱内执行 SKILL.md 声明的入口命令。不需要知识 网络上下文时用 list_skills 直接翻已发布技能列表。

Skill 与业务对象的绑定关系建在知识网络里：平台约定该网中存在一个固定的 skills 对象类，业务对象类通过关系类与它相连，召回就是沿这些关系走。 skills 对象类由 execution-factory 在注册 Skill 时写入。

认证：Authorization: Bearer <token>（OAuth access token 或 bak_ AppKey）。

Skill

按业务上下文召回 Skill

召回模式由参数自动决定，不用显式指定：

传入参数 模式
kn_id + object_type_id 对象类级：沿对象类与 skills 之间的关系路径召回
再加 instance_identities 实例级：从具体实例出发召回，并补充对象类级结果

skill_query 的检索方式随索引能力降级：对 skills 实例的 name / description 追加文本过滤——BKN 已建向量索引时用 knn，已建全文索引时用 match，都没有时退化为 like。

skills 对象类至少要有 skill_id 与 name 两个数据属性，description 可选；不满足时返回 400 并在 details 里列出缺失属性。

空结果是 200 不是错误：没有匹配时返回 entries: []，并可能带一个 message 说明为什么为空（如该对象类未绑定任何 Skill）以及下一步建议。

Authorizations:
OAuth2AppKey
query Parameters
response_format
string
Default: "json"
Enum: "json" "toon"

响应格式。toon 返回 application/toon，同构数组压成表格，省 token。

header Parameters
Accept-Language
string

可选的 RFC 9110 语言偏好。服务从支持的 zh-CN、en-US 中选择响应错误文本语言。

Request Body schema: application/json
required
required
object (BKNContext)

BKN Trace 业务溯源上下文，声明这次调用属于哪一轮业务对话。REST 面必填。

两个必填子字段均为服务端签发的句柄、不可自拟：

  • conversation_id：首轮调用 Context Loader MCP 工具 bkn_start_interaction 取得
  • interaction_id：调用 Context Loader 的 MCP 工具 bkn_start_interaction 取得

这两个句柄只能经上述 MCP 溯源工具取得。BKN Trace Core 的 /api/agent-observability/v1 会话接口只接受集群内可信服务的网关凭据， 不接受 OAuth token 或 bak_ AppKey，外部调用方直接调用会得到 401 permission_denied。 Context Loader 按请求关联信息、工具名和规范化输入服务端派生 Operation 幂等标识；调用方不得提交 operation_key。网络重试应复用 bkn-request-id，或提供同一次逻辑调用稳定不变的 X-OpenBKN-Client-Invocation-Id 请求头。该提示只用于幂等，不参与身份、 权限或数据隔离判定。

kn_id
required
string

知识网络 ID。

object_type_id
required
string

业务对象类 ID（取自 search_schema 返回的概念 ID）。必填，且必须存在于 该知识网络中。

Array of objects

对象实例标识列表，必须从 query_object_instance 或 query_instance_subgraph 结果里的 _instance_identity 取，不可自拼。 传入即切换到实例级召回。

skill_query
string

Skill 语义过滤词，对 skills 实例的 name / description 追加文本过滤。 检索方式按索引能力降级：向量索引用 knn，全文索引用 match，否则 like。

top_k
integer [ 1 .. 20 ]
Default: 10

最多返回的 Skill 数量。

Responses

Request samples

Content type
application/json
Example
{
  • "kn_id": "kn_legal",
  • "object_type_id": "contract",
  • "top_k": 10
}

Response samples

Content type
Example
{
  • "entries": [
    ]
}

浏览已发布 Skill

翻已发布 Skill 列表，不需要知识网络上下文。与 find_skills 互补：那条按对象类 / 实例召回，这条按名称或分类分页浏览。

只返回已发布状态的 Skill；草稿态不出现在这里。

空结果是 200 不是错误：无匹配时 entries: [] 并带 message 说明。

Authorizations:
OAuth2AppKey
query Parameters
response_format
string
Default: "json"
Enum: "json" "toon"

响应格式。toon 返回 application/toon，同构数组压成表格，省 token。

header Parameters
Accept-Language
string

可选的 RFC 9110 语言偏好。服务从支持的 zh-CN、en-US 中选择响应错误文本语言。

Request Body schema: application/json
optional
object (BKNContext)

BKN Trace 业务溯源上下文，声明这次调用属于哪一轮业务对话。REST 面必填。

两个必填子字段均为服务端签发的句柄、不可自拟：

  • conversation_id：首轮调用 Context Loader MCP 工具 bkn_start_interaction 取得
  • interaction_id：调用 Context Loader 的 MCP 工具 bkn_start_interaction 取得

这两个句柄只能经上述 MCP 溯源工具取得。BKN Trace Core 的 /api/agent-observability/v1 会话接口只接受集群内可信服务的网关凭据， 不接受 OAuth token 或 bak_ AppKey，外部调用方直接调用会得到 401 permission_denied。 Context Loader 按请求关联信息、工具名和规范化输入服务端派生 Operation 幂等标识；调用方不得提交 operation_key。网络重试应复用 bkn-request-id，或提供同一次逻辑调用稳定不变的 X-OpenBKN-Client-Invocation-Id 请求头。该提示只用于幂等，不参与身份、 权限或数据隔离判定。

name
string

按 Skill 名称模糊过滤。

category
string

按 Skill 分类过滤。

page
integer >= 1
Default: 1

页码，从 1 开始。

page_size
integer [ 1 .. 100 ]
Default: 20

每页大小。

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
{
  • "entries": [
    ],
  • "total_count": 1,
  • "page": 1,
  • "page_size": 20
}

读 SKILL.md 正文与包内文件清单

返回 Skill 主文档 SKILL.md 的正文，以及技能包内的文件清单 （files[].rel_path）。Skill 的用法与入口命令都写在正文里。

需要某个附属文件的内容时再调 read_skill_file 单取，不必整包下载。

正文超过 40000 字符会截断，此时 truncated=true 并带 message 说明。

Authorizations:
OAuth2AppKey
query Parameters
response_format
string
Default: "json"
Enum: "json" "toon"

响应格式。toon 返回 application/toon，同构数组压成表格，省 token。

header Parameters
Accept-Language
string

可选的 RFC 9110 语言偏好。服务从支持的 zh-CN、en-US 中选择响应错误文本语言。

Request Body schema: application/json
required
required
object (BKNContext)

BKN Trace 业务溯源上下文，声明这次调用属于哪一轮业务对话。REST 面必填。

两个必填子字段均为服务端签发的句柄、不可自拟：

  • conversation_id：首轮调用 Context Loader MCP 工具 bkn_start_interaction 取得
  • interaction_id：调用 Context Loader 的 MCP 工具 bkn_start_interaction 取得

这两个句柄只能经上述 MCP 溯源工具取得。BKN Trace Core 的 /api/agent-observability/v1 会话接口只接受集群内可信服务的网关凭据， 不接受 OAuth token 或 bak_ AppKey，外部调用方直接调用会得到 401 permission_denied。 Context Loader 按请求关联信息、工具名和规范化输入服务端派生 Operation 幂等标识；调用方不得提交 operation_key。网络重试应复用 bkn-request-id，或提供同一次逻辑调用稳定不变的 X-OpenBKN-Client-Invocation-Id 请求头。该提示只用于幂等，不参与身份、 权限或数据隔离判定。

skill_id
required
string

Skill ID，取自 find_skills 或 list_skills。

Responses

Request samples

Content type
application/json
{
  • "skill_id": "skill_contract_review"
}

Response samples

Content type
{
  • "skill_id": "string",
  • "status": "string",
  • "content": "string",
  • "truncated": true,
  • "files": [
    ],
  • "message": "string"
}

读技能包内单个文件

按 rel_path 取技能包内单个文件的正文。rel_path 取自 get_skill_content 返回的 files[].rel_path，不接受包外路径（../ 被拒）。

二进制文件不回正文：mime_type 为图片 / 音视频 / 压缩包 / PDF，或正文不是 合法 UTF-8 时，只返回元数据与 message 说明，避免把乱码灌进模型上下文。

正文超过 40000 字符会截断（truncated=true）；单文件超过 5 MiB 返回 413。

Authorizations:
OAuth2AppKey
query Parameters
response_format
string
Default: "json"
Enum: "json" "toon"

响应格式。toon 返回 application/toon，同构数组压成表格，省 token。

header Parameters
Accept-Language
string

可选的 RFC 9110 语言偏好。服务从支持的 zh-CN、en-US 中选择响应错误文本语言。

Request Body schema: application/json
required
required
object (BKNContext)

BKN Trace 业务溯源上下文，声明这次调用属于哪一轮业务对话。REST 面必填。

两个必填子字段均为服务端签发的句柄、不可自拟：

  • conversation_id：首轮调用 Context Loader MCP 工具 bkn_start_interaction 取得
  • interaction_id：调用 Context Loader 的 MCP 工具 bkn_start_interaction 取得

这两个句柄只能经上述 MCP 溯源工具取得。BKN Trace Core 的 /api/agent-observability/v1 会话接口只接受集群内可信服务的网关凭据， 不接受 OAuth token 或 bak_ AppKey，外部调用方直接调用会得到 401 permission_denied。 Context Loader 按请求关联信息、工具名和规范化输入服务端派生 Operation 幂等标识；调用方不得提交 operation_key。网络重试应复用 bkn-request-id，或提供同一次逻辑调用稳定不变的 X-OpenBKN-Client-Invocation-Id 请求头。该提示只用于幂等，不参与身份、 权限或数据隔离判定。

skill_id
required
string
rel_path
required
string

技能包内相对路径，取自 get_skill_content 的 files[].rel_path。 包外路径（含 ../）返回 400。

Responses

Request samples

Content type
application/json
{
  • "skill_id": "skill_contract_review",
  • "rel_path": "refs/checklist.md"
}

Response samples

Content type
{
  • "skill_id": "string",
  • "rel_path": "string",
  • "mime_type": "string",
  • "file_type": "string",
  • "content": "string",
  • "truncated": true,
  • "message": "string"
}

在沙箱内执行 Skill 入口命令

把 Skill 包投进沙箱会话解压，执行 entry_shell 指定的入口命令，回收 exit_code / stdout / stderr。

entry_shell 必须取自 SKILL.md 声明的入口，先用 get_skill_content 读清楚再调；这条接口不校验命令与 Skill 的对应关系。

授权由 execution-factory 按账户强制：需要该 Skill 的 execute 或 public_access 权限，无权限返回 403。

stdout / stderr 各自超过 8000 字符会截断（truncated=true）。

本端点由技能执行总闸控制：EXECUTE_SKILL_ENABLED=true 时才注册这条 路由，同名 MCP 工具也才出现在 tools/list 与 GET /mcp/info。默认关闭， 此时这条路径返回 404——「这个部署没有技能执行能力」在路由表上成立。 （旧名 MCP_EXECUTE_SKILL_ENABLED 仍被识别，用于兼容已按旧名配置的部署。）

Authorizations:
OAuth2AppKey
header Parameters
Accept-Language
string

可选的 RFC 9110 语言偏好。服务从支持的 zh-CN、en-US 中选择响应错误文本语言。

Request Body schema: application/json
required
required
object (BKNContext)

BKN Trace 业务溯源上下文，声明这次调用属于哪一轮业务对话。REST 面必填。

两个必填子字段均为服务端签发的句柄、不可自拟：

  • conversation_id：首轮调用 Context Loader MCP 工具 bkn_start_interaction 取得
  • interaction_id：调用 Context Loader 的 MCP 工具 bkn_start_interaction 取得

这两个句柄只能经上述 MCP 溯源工具取得。BKN Trace Core 的 /api/agent-observability/v1 会话接口只接受集群内可信服务的网关凭据， 不接受 OAuth token 或 bak_ AppKey，外部调用方直接调用会得到 401 permission_denied。 Context Loader 按请求关联信息、工具名和规范化输入服务端派生 Operation 幂等标识；调用方不得提交 operation_key。网络重试应复用 bkn-request-id，或提供同一次逻辑调用稳定不变的 X-OpenBKN-Client-Invocation-Id 请求头。该提示只用于幂等，不参与身份、 权限或数据隔离判定。

skill_id
required
string
entry_shell
required
string

沙箱内执行的入口命令，取自 SKILL.md 声明的入口。技能包已解压到工作目录， 命令相对该目录执行。

timeout
integer [ 1 .. 600 ]

执行超时秒数。

Responses

Request samples

Content type
application/json
{
  • "skill_id": "skill_contract_review",
  • "entry_shell": "python main.py --input contract.txt",
  • "timeout": 60
}

Response samples

Content type
application/json
{
  • "skill_id": "string",
  • "exit_code": 0,
  • "stdout": "string",
  • "stderr": "string",
  • "truncated": true,
  • "execution_time": 0,
  • "work_dir": "string",
  • "command": "string",
  • "mocked": true
}