Download OpenAPI specification:
把知识网络已挂载的能力交给调用方使用：search_capabilities 在一个排序空间里检索
全部四类能力——Skill、函数工具、API 工具（metadata_type=openapi）与 MCP 工具——
execute_tool 通过知识网络的托管代理执行其中的工具类能力，同时保留真实调用者用于
网络级鉴权与审计。Skill 的读取与执行在
skill.yaml。
检索面只有这一条。曾经的 search_tools 与 find_skills 是本接口按类型钉死的
两个窄入口，各自只看自己那一类，跨类型比较得调两次再自行合并；两者已随 #1401 删除。
范围是知识网络的挂载。kn_id 必填：候选集取自该知识网络的能力绑定，收窄粒度是
能力而不是工具箱——同一个工具箱里可以只有部分工具挂到本网络，未挂载的那些既搜不到
也调不了。网络未挂载任何能力时返回空列表并给出提示，不会退回「当前账户可见的全部工具」。
检索与执行的权限不同：检索回填 schema 时仍按调用者可见性读取执行工厂；执行时要求
调用者拥有知识网络 execute，并由服务端校验精确的能力绑定后解析托管代理。调用者无需
直接拥有工具箱或 MCP Server 的执行权限，也不能在请求中指定代理身份。
execute_tool 有不可回滚的副作用：注册进来的函数可以对外部系统写入。调用前先读
search_capabilities 返回的 description 与 use_rule。服务端执行前校验知识网络 execute、
精确能力绑定、代理同步状态以及工具箱/MCP Server 生命周期；任一不满足都不会执行。
收窄检索面本身不构成管控——工具 ID 会活过产生它的那次检索。
托管 Interaction：execute_tool 必须在请求体中提供有效的 bkn_context。
conversation_id 与 interaction_id 会随调用透传到执行工厂，使执行和证据
归属于同一个 Interaction。search_capabilities 仍可不带上下文临时读取。
平台明确关闭证据采集时不签发 Interaction ID，execute_tool 可不带
bkn_context 执行，且不生成受管 Trace 记录。
Trace Core 基础设施故障时，本接口经只读探测确认后可不带上下文执行，
并标记本次调用未记录 Trace。
认证：Authorization: Bearer <token>（OAuth access token 或 bak_ AppKey）。
在一个排序空间里返回该知识网络已挂载、且当前账户可见的能力：Skill、函数工具、 API 工具与 MCP 工具混排，按相关度给出，而不是每类一段。
需要该知识网络本身的 view_detail 权限（#1550）。只有对象类等子资源权限，或对某个
Skill / 工具的单独授权，都会被拒绝（403，message 说明缺的是网络本身的查看权限）。
每条带 capability_type，据此决定下一步：function 与 mcp_tool 用
execute_tool 调用（命中带裁剪过的 input_schema，只保留业务入参，服务地址等
传输信息不下发），skill 用 get_skill_content 读取、execute_skill 执行。
types 按能力类型收窄；函数工具还可用 metadata_types 再分 openapi（API 工具）
与 function。两者都只在挂载集内收窄，越不出去。
limit 默认 20、上限 100：工具类命中都带一份入参 schema，调大会显著占用上下文。
命中数超过 limit 时 truncated=true 并给出 message。
回填 schema 时单个工具箱取列表失败会跳过该箱而不是整体失败：一个被撤销或损坏的 工具箱不该让调用方看不到其余所有能力。
生命周期门在可见性之前：命中的能力先按所属工具箱 / MCP Server 的发布状态
与工具自身的启用状态过滤，这两项从执行工厂自己的记录读取（不依赖调用方 token，
内部面同样生效），核不到一律按未发布处理——索引最多滞后到下一次事件或对账，这一道
保证下线、停用后的能力在那个窗口里也不会被推荐。剔除后若不足 limit 且排序还有
更多，会有界补召回一次（最多 limit×3，不超过 100）；仍不足则 truncated=true
并用 message 说明结果不完整，不会静默少给。空结果全因下线或状态无法确认时，
message 指向发布状态而不是权限。
不带 query 时成员集由挂载决定，不由索引决定：没有查询词就没有要排序的东西，
此时按绑定顺序列出挂载集，索引只用来补名称、说明与 metadata_type，索引没收录的
由目录（工具）或注册表（Skill）补齐。索引是异步构建的，新装的环境还没有，让它决定
成员集会使「刚挂上、还没进索引」的能力凭空消失。带 query 时索引不可用则报错——
排序没有可退化的东西。
metadata_types 是例外：绑定只记能力类型，不记工具箱种类，这个过滤只有索引
答得出。所以带 metadata_types 时索引不可用一律报错，不会退化成一份没过滤的列表。
空结果是 200 不是错误：无匹配时 capabilities: [] 并带 message 说明。
| response_format | string Default: "json" Enum: "json" "toon" 响应格式。 |
| Accept-Language | string 可选的 RFC 9110 语言偏好。服务从支持的 |
object (BKNContext) BKN Trace business-provenance context identifying the business
conversation and interaction to which this call belongs. Required on
MCP business tools and REST execution APIs while capture is enabled
and Trace Core is available;
optional on REST reads and Naming it makes the call managed: the service records an Operation under that interaction and attempts to return a receipt and capture evidence. Omitting it entirely, or sending an empty object, makes an eligible REST read or proxy call ad hoc. Only those two shapes are ad hoc — one id without the other, or a misspelt field, is refused rather than quietly downgraded. Both required child fields are server-issued handles and must not be invented by the caller:
These handles are available only through the provenance MCP tool above.
The BKN Trace Core session APIs under | |
| kn_id required | string 知识网络 ID。范围取自该网络的能力绑定；未挂载任何能力时返回空列表并给出提示。 |
| query | string 可选。在该网络已挂载的能力内按名称与说明排序。留空则按绑定顺序列出全部， 此时不依赖检索索引。 |
| types | Array of strings Items Enum: "skill" "function" "mcp_tool" 可选。收窄到某几类能力，留空为全部。只在挂载集内收窄，越不出去。 |
| metadata_types | Array of strings Items Enum: "openapi" "function" 可选。把 |
| owner_id | string 可选。只看某个来源：函数工具的工具箱、MCP 工具的 Server。Skill 没有来源，
传了这个就不会返回 Skill。取自本接口此前返回的 |
| limit | integer [ 1 .. 100 ] Default: 20 可选。最多返回多少条。工具类命中都带入参 schema。 |
{- "kn_id": "supply_chain"
}{- "capabilities": [
- {
- "capability_type": "skill",
- "capability_id": "skill_fx_report",
- "name": "汇率月报",
- "description": "汇总当月各币种结算汇率并出报表"
}, - {
- "capability_type": "function",
- "owner_id": "box_finance",
- "capability_id": "tool_fx_convert",
- "metadata_type": "function",
- "name": "fx_convert",
- "description": "按指定日期汇率换算金额",
- "use_rule": "只用于已结算币种，未结算单据先调 settle_order",
- "input_schema": {
- "request_body": {
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "amount": {
- "type": "number"
}, - "from": {
- "type": "string"
}, - "to": {
- "type": "string"
}
}
}
}
}
}
}
}
], - "total_matched": 2
}REST lifecycle context is optional, as for search_schema. Missing or empty bkn_context permits ad-hoc execution without depending on Trace Core or capture policy. Explicit nonempty context remains validated. Authentication, network execute permission and mounted-tool authorization still apply. MCP managed execution continues to require conversation/interaction IDs.
以知识网络托管代理执行工具，返回工具的原始响应；真实调用者仍用于网络级鉴权和审计。
toolbox_id 与 tool_id 必须取自 search_capabilities（owner_id / capability_id）；arguments 按其返回的
input_schema 填，只放业务参数——令牌、会话 id 等传输信息由平台携带，写进
arguments 既不生效也会被记进调用参数。
函数自身报错同样是 200：调用成功不等于业务成功，需读响应体判断。
工具未挂载、已停用、所属工具箱/MCP Server 未发布、代理未同步，或调用者没有知识网络
execute 权限时会拒绝，message 说明原因，请求不会执行目标工具。
缺少或传空 bkn_context 返回 400 conversation_required，并附
required_action: create_conversation；执行前应先建立受管 Interaction。
平台明确关闭证据采集时，此上下文要求不适用。
Trace Core 基础设施故障且只读探测确认不可用时，此要求也不适用，
本次执行会标记为未记录 Trace。
| Accept-Language | string 可选的 RFC 9110 语言偏好。服务从支持的 |
required | object (BKNContext) BKN Trace business-provenance context identifying the business
conversation and interaction to which this call belongs. Required on
MCP business tools and REST execution APIs while capture is enabled
and Trace Core is available;
optional on REST reads and Naming it makes the call managed: the service records an Operation under that interaction and attempts to return a receipt and capture evidence. Omitting it entirely, or sending an empty object, makes an eligible REST read or proxy call ad hoc. Only those two shapes are ad hoc — one id without the other, or a misspelt field, is refused rather than quietly downgraded. Both required child fields are server-issued handles and must not be invented by the caller:
These handles are available only through the provenance MCP tool above.
The BKN Trace Core session APIs under |
| kn_id required | string 知识网络 ID，须与 |
| toolbox_id required | string 工具箱 ID，取自 |
| tool_id required | string 工具 ID，取自 |
required | object 工具的业务入参，按 |
{- "bkn_context": {
- "conversation_id": "conv_01J8Z",
- "interaction_id": "int_01J8Z"
}, - "kn_id": "kn_finance",
- "toolbox_id": "box_finance",
- "tool_id": "tool_fx_convert",
- "arguments": {
- "amount": 1200,
- "from": "USD",
- "to": "CNY"
}
}{ }