执行工厂 · 工具箱 API (0.1.3)

建一个空工具箱。metadata_type 决定这个箱子装哪类工具，建成后不可更改 （编辑接口的 metadata_type 是可选的，传了才校验）。

openapi 类型的箱子必须给 box_svc_url——箱内工具的请求都发往这个地址。

分页列出当前主体拥有 view 权限的工具箱。metadata_type 过滤用于「函数工具工作台 只列函数工具箱」这类场景。只有 execute、没有 view 的工具箱不会出现在顶层目录中； 已知其 ID 的运行时仍可读取具体工具元数据并执行。

条目里的 tools 是工具名字符串数组，不是工具对象也不是 ID——要工具详情 得再调 GET /tool-box/{box_id}/tools/list。

与 /skills/names 同契约：不存在的 ID 静默略过、不占位， 调用方自己比对哪些没回来。

取工具箱详情，含箱内工具的完整定义。

更新走 POST 不是 PUT。box_name / box_desc / box_category 都是必填 ——这是整体覆盖，不是部分更新，不传就报必填错误。

metadata_type 反而是可选的：工具箱建成后类型不会变，带了才校验取值。

响应里的 edit_tools 列出因本次更新而受影响的工具及其新状态。

删除工具箱及其下全部工具。已被 Agent 挂载的工具箱删除后调用方会拿到 404。

发布 / 下架工具箱。工具箱只有三个状态（unpublish / published / offline），没有 editing。

往箱子里加工具。metadata_type 决定必填字段：function 走 function_input（代码约定见 function.yaml，入口函数必须叫 handler），openapi 走 data（OpenAPI 原文）。

一次可以建出多个工具：一份 OpenAPI 文档里有几个操作就建几个工具， 所以响应是 success_count / failure_count 的批量结果，部分成功是常态 ——failure_count 非 0 时接口仍返回 200，失败明细在 failures 里。

取单个工具的完整定义，含元数据、全局参数与使用规则。该定义也是调用工具所需的运行时 输入，因此对所属工具箱拥有 view、public_access 或 execute 任一权限即可读取； 这不会让 execute-only 工具箱出现在顶层目录中。

更新走 POST 不是 PUT。 name、description、metadata_type 都是必填 ——整体覆盖，不是部分更新。

列出工具箱里的工具。对已知工具箱拥有 view、public_access 或 execute 任一权限 即可读取，因为工具定义是执行时构造参数所需的元数据；顶层工具箱目录仍只按 view 过滤。

**响应的数据字段叫 tools 不是 data**，还多一个 box_id——与本服务其他 分页接口（含同模块的 /tool-box/market/tools）不一致，解析时注意。

排序字段这里可选 create_time / update_time / tool_name，默认 create_time（工具箱列表默认的是 update_time）。

按 ID 批量删除工具箱里的工具。

请求体是数组，一次改多个工具的启停。工具的状态只有 enabled / disabled 两个值——与工具箱的发布状态是两套，别混。

禁用的工具不会出现在 Agent 可用的工具列表里，但仍留在箱子中。

用给定参数真实调用一次工具。与 /proxy/{tool_id} 的差别只在语义与审计 ——调试面向开发期，代理面向生产调用。请求与响应结构一致。

调用主体来自 OAuth/AppKey 或受信任内部身份上下文，并且必须对具体 tool_box:{box_id} 持有 execute。拒绝或 bkn-safe 判定失败时不会调用工具。

For platform Function tools, the authenticated request credential reaches the sandbox without requiring conversation/interaction IDs or enabling Trace. The proxy endpoint below uses the same credential forwarding rules.

参数按 HTTP 的四个位置分开传：header / query / path / body。 函数工具的顶层 timeout 以秒为单位控制沙箱执行；超时时响应体的 status_code 为 504，接口本身仍返回 200。

生产调用入口：由平台代为执行工具并返回结果，调用方不必知道工具背后打的是 哪个地址。与调试接口的差别在于会走权限校验与审计日志。

调用主体来自 OAuth/AppKey 或受信任内部身份上下文，并且必须对具体 tool_box:{box_id} 持有 execute。用于知识网络 Action 时，ontology-query 还会在此前校验具体 Action Type 和数据依赖。请求体不能覆盖执行主体。 平台身份头和 trace 控制头在请求离开平台前会被移除。

返回的是被调服务的原始响应（status_code / headers / body）， 不是平台自己的信封——上游返 500 时本接口仍是 200，status_code 里才是 500。 函数工具的顶层 timeout 以秒为单位控制沙箱执行，受代理最大超时配置约束； 沙箱执行超时时，信封的 status_code 为 504。

只有已发布工具箱里已启用的工具能被调用：工具箱 unpublish / offline， 或工具 disabled，都返回 400 ToolNotAvailable（details 说明是箱还是工具）。 这与调试接口不同——调试允许作者跑未发布的东西；生产调用不允许。下架一个 工具箱即刻让其全部工具停止响应本接口，不等下一次索引对账。

Function caller credentials and optional lifecycle context: both REST debug and proxy execution forward the authenticated request credential to this deployment's own Function runtime, regardless of Trace/evidence capture or whether conversation/interaction IDs are present. The Function can use bkn_osdk as the invoking caller without repeating a token in its inputs. Only a complete bkn-conversation-id / bkn-interaction-id pair is forwarded; partial lifecycle context is omitted. No MCP start/finish is required for these REST calls. Credential forwarding does not grant extra permissions.

这些值由服务端从请求本身捕获，不是工具的业务参数，不写进工具 Schema， 请求体里同名字段会被服务端捕获值覆盖。非函数工具不透传：OpenAPI 类工具 指向第三方地址，平台身份不出网。

注意随之而来的信任边界：函数代码由注册者提供，沙箱可出网，因此被调函数 能在自身环境变量里读到调用者的活令牌。只把函数工具发布给可信的注册者。

「能力包」注册：给一份 OpenAPI 3.0 文档，把里面每个操作直接建成一个工具放进 工具箱，与 POST /tool-box/{box_id}/tool 走同一条建工具路径。新建的工具 **初始为 disabled**，需要再启用。

box_id 与 box_name 二选一：给 box_id 就往已有的 openapi 类工具箱 里加，box_id 为空时按 box_name 新建一个 openapi 类工具箱。两者都不给 返回 400。

部分失败是常态：只要建成至少一个工具就返回 200，failure_count 与 failures 说明哪些操作没建成；一个都没建成返回 400。

已发布工具箱的列表。过滤条件比工作区列表少了 status 与 metadata_type。

跨工具箱按名称搜工具。

tool_name 是必填的——不传直接 400 （AgentOperatorIntegration.BadRequest.ValidationRequired）。这不是「列出 全部市场工具」的接口，是「按名字找工具」。

响应的数据字段是 data（与同模块 /tool-box/{box_id}/tools/list 的 tools 不同）。

市场视角的工具箱详情，结构与 GET /tool-box/{box_id} 一致。

与 MCP 的 /mcp/market/batch/{mcp_ids}/{fields} 同一套路子：两个参数都走 路径、都是逗号分隔。注意这里的路径段名叫 box_id，但接受的是 ID 列表（服务端字段就叫 BoxIDs）。

响应是按 fields 投影后的对象数组，未选中的字段不出现。