API docs by Redocly

上下文加载 · Skill 读取与执行 API (0.1.6)

Download OpenAPI specification:

读取并执行知识网络已挂载的 Skill。召回不在这里：找 Skill 用 tool.yaml 的 search_capabilities（types: [skill]），它把 Skill 与 工具放在同一个排序空间里，返回 capability_id / name / description 这样的最小 元数据。曾经的 find_skills 是它按类型钉死的窄入口，已随 #1401 删除。

拿到 skill_id 之后：get_skill_content 读 SKILL.md 正文与包内文件清单， read_skill_file 按 rel_path 单取附属文件（渐进式加载，大文件不必常驻上下文）， execute_skill 在沙箱内执行 SKILL.md 声明的入口命令。

这三条都要求 kn_id，且 Skill 必须已挂载到该知识网络（0.1.5 起）。收窄召回本身 不构成管控——skill_id 会活过产生它的那次调用，也能从 list_skills 拿到，所以范围 在读取与执行处各核一次。未挂载返回 400。

权限跟知识网络走（#1550）：这三条都要求调用者持有该知识网络本身的 view_detail； 只有对象类等子资源权限，或对 Skill 的单独授权，都会被拒绝（403）。读取（get_skill_content、 read_skill_file）先以调用者身份直读，已有 Skill 授权的调用者结果不变；执行工厂拒绝调用者时， 改由该知识网络的托管代理读取，调用者无需单独的 Skill 授权。代理对 Skill 的授权由挂载或最近 发布该网络、且对 Skill 有执行权限的编辑者提供；代理没有该授权时返回 403，message 提示请 编辑者重新发布网络，或为调用者单独授予 Skill 的查看权限。execute_skill 仍按调用者自己的 Skill 执行权限执行，不走代理。

list_skills 是例外：它翻的是当前调用者拥有 view 权限的平台已发布技能目录，不受 挂载约束，用于挂载之前先看见自己可以配置什么。目录可见不等于能在任意知识网络里使用， 读取与执行仍会分别校验知识网络挂载关系以及对应操作权限。只有 public_access、没有 view 的市场技能不会出现在这里。

公开调用透传原始 bearer token；内部调用使用可信的 X-Account-ID / X-Account-Type 进入 execution-factory 的 caller-scoped 内部路由。两种入口都按真实调用者授权，不回退为 服务身份。两类身份都缺失时返回 401。

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

Skill

浏览已发布 Skill

翻已发布 Skill 列表，不需要知识网络上下文。与 search_capabilities 互补：那条在 某个网络已挂载的能力里按相关度召回，这条按名称或分类分页浏览整个平台目录。

只返回调用者拥有 view 权限且存在已发布版本的 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 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 /mcp/proxy/.../call. A verified disabled capture policy admits business calls without this context because no Conversation or Interaction IDs are issued. A verified Trace Core infrastructure outage also admits unrecorded REST execution after a bounded, read-only availability probe.

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:

  • conversation_id: obtained from the Context Loader MCP tool bkn_start_interaction on the first turn
  • interaction_id: obtained from the Context Loader MCP tool bkn_start_interaction

These handles are available only through the provenance MCP tool above. The BKN Trace Core session APIs under /api/agent-observability/v1 accept gateway credentials only from trusted in-cluster services. They do not accept OAuth tokens or bak_ AppKeys; direct external calls receive 401 permission_denied. Context Loader derives the Operation idempotency identity on the server from request correlation, tool name, and normalized input. Callers must not submit operation_key. Network retries should reuse bkn-request-id or provide a stable X-OpenBKN-Client-Invocation-Id for the same logical call. This hint is used only for idempotency and has no role in identity, authorization, or data-isolation decisions.

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
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 /mcp/proxy/.../call. A verified disabled capture policy admits business calls without this context because no Conversation or Interaction IDs are issued. A verified Trace Core infrastructure outage also admits unrecorded REST execution after a bounded, read-only availability probe.

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:

  • conversation_id: obtained from the Context Loader MCP tool bkn_start_interaction on the first turn
  • interaction_id: obtained from the Context Loader MCP tool bkn_start_interaction

These handles are available only through the provenance MCP tool above. The BKN Trace Core session APIs under /api/agent-observability/v1 accept gateway credentials only from trusted in-cluster services. They do not accept OAuth tokens or bak_ AppKeys; direct external calls receive 401 permission_denied. Context Loader derives the Operation idempotency identity on the server from request correlation, tool name, and normalized input. Callers must not submit operation_key. Network retries should reuse bkn-request-id or provide a stable X-OpenBKN-Client-Invocation-Id for the same logical call. This hint is used only for idempotency and has no role in identity, authorization, or data-isolation decisions.

kn_id
required
string

知识网络 ID。Skill 必须已挂载到该网络才能读取/执行，未挂载返回 400。

skill_id
required
string

Skill ID。取自 search_capabilities（当前网络已挂载的）或 list_skills（平台目录， 未必已挂载到本网络）。

Responses

Request samples

Content type
application/json
{
  • "kn_id": "kn_legal",
  • "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
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 /mcp/proxy/.../call. A verified disabled capture policy admits business calls without this context because no Conversation or Interaction IDs are issued. A verified Trace Core infrastructure outage also admits unrecorded REST execution after a bounded, read-only availability probe.

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:

  • conversation_id: obtained from the Context Loader MCP tool bkn_start_interaction on the first turn
  • interaction_id: obtained from the Context Loader MCP tool bkn_start_interaction

These handles are available only through the provenance MCP tool above. The BKN Trace Core session APIs under /api/agent-observability/v1 accept gateway credentials only from trusted in-cluster services. They do not accept OAuth tokens or bak_ AppKeys; direct external calls receive 401 permission_denied. Context Loader derives the Operation idempotency identity on the server from request correlation, tool name, and normalized input. Callers must not submit operation_key. Network retries should reuse bkn-request-id or provide a stable X-OpenBKN-Client-Invocation-Id for the same logical call. This hint is used only for idempotency and has no role in identity, authorization, or data-isolation decisions.

kn_id
required
string

知识网络 ID。Skill 必须已挂载到该网络才能读取/执行，未挂载返回 400。

skill_id
required
string
rel_path
required
string

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

Responses

Request samples

Content type
application/json
{
  • "kn_id": "kn_legal",
  • "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）。

必须提供有效的 bkn_context；缺失或传空时，执行前返回 400 conversation_required，附 required_action: create_conversation。 平台明确关闭证据采集时，bkn_start_interaction 不签发 ID，本接口可不带 bkn_context 执行，且不生成受管 Trace 记录。 Trace Core 基础设施故障时，本接口经只读探测确认后可不带上下文执行， 并标记本次调用未记录 Trace。

本端点由技能执行总闸控制：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
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 /mcp/proxy/.../call. A verified disabled capture policy admits business calls without this context because no Conversation or Interaction IDs are issued. A verified Trace Core infrastructure outage also admits unrecorded REST execution after a bounded, read-only availability probe.

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:

  • conversation_id: obtained from the Context Loader MCP tool bkn_start_interaction on the first turn
  • interaction_id: obtained from the Context Loader MCP tool bkn_start_interaction

These handles are available only through the provenance MCP tool above. The BKN Trace Core session APIs under /api/agent-observability/v1 accept gateway credentials only from trusted in-cluster services. They do not accept OAuth tokens or bak_ AppKeys; direct external calls receive 401 permission_denied. Context Loader derives the Operation idempotency identity on the server from request correlation, tool name, and normalized input. Callers must not submit operation_key. Network retries should reuse bkn-request-id or provide a stable X-OpenBKN-Client-Invocation-Id for the same logical call. This hint is used only for idempotency and has no role in identity, authorization, or data-isolation decisions.

kn_id
required
string

知识网络 ID。Skill 必须已挂载到该网络才能读取/执行，未挂载返回 400。

skill_id
required
string
entry_shell
required
string

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

timeout
integer [ 1 .. 600 ]

执行超时秒数。

Responses

Request samples

Content type
application/json
{
  • "bkn_context": {
    },
  • "kn_id": "kn_legal",
  • "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
}