执行工厂 · Skill API (0.1.3)

上传一个技能包。**Content-Type 只接受 multipart/form-data 或 application/x-www-form-urlencoded**，发 application/json 会被直接拒绝， 报 unsupported content type。

file_type 决定 file 字段怎么解读：

响应里的 files 列出解包后识别到的文件。

分页列出当前主体获授权访问的技能，支持按名称、状态、分类、创建人过滤。

与 /tool-box/names 同契约：不存在的 ID 静默略过、不占位。

**也注册在 internal-v1**。公开面按调用者的 view 过滤（无权限的 ID 与不存在的 ID 一样被略过），内部面不过滤——服务间调用要的是「这些 ID 还在不在」，用于知识网络 能力绑定的元数据回填与悬空判定。

从技能发布版本表分页列出当前调用者拥有 view 权限的技能，供 Agent 能力发现使用。 该接口读取已发布快照，不读取工作区仓库行的当前状态；因此已发布技能在编辑下一版本时 仍可被发现。它与 /skills/market 的区别是权限口径：本接口只认 view，市场接口只认 public_access。

已发布技能的列表。比工作区列表少一个 status 过滤——市场里的都是已发布的。

市场视角的技能详情，结构与 GET /skills/{skill_id} 一致。

取技能的元数据。文件清单与内容走 /content，包体走 /download。

**也注册在 internal-v1**，供 bkn-backend 校验知识网络能力绑定。内部面不做 调用者维度的 view 判定，同一技能对任何调用者返回相同结果；未发布的技能通过 status 字段体现，不返回 404。别拿 /skills/market/{skill_id} 代替它——那条路 走 public_access 且未发布即 404，会把「存在但未发布」误报成「不存在」。

404 只表示技能不存在或已删除。

删除技能及其全部版本。已被 Agent 挂载的技能删除后装载会失败； 指向它的知识网络能力绑定会变成悬空引用——search_capabilities 列不出来， execute_skill 也执行不了。

只接受 published 与 offline 两个值——不能通过这个接口把技能改回 unpublish 或 editing，那两个状态由注册与编辑动作产生。

本面用的是 PUT（工具箱的同类接口用 POST），注意区别。

改名称 / 描述 / 分类，不动技能包本身。三个字段都是必填——整体覆盖。

更新会产生新 version。

换掉技能的文件内容。与注册一样只接受 form / multipart，不接受 JSON。 更新产生新 version，原版本进历史。

列出该技能发布过的版本，含每次发布的说明与发布人。

取某个历史版本的内容，写回当前草稿——不直接发布。用于「拿旧版本当起点 继续改」。改完再走正常发布流程。

与 history/publish 的区别：那个是直接发布旧版本，跳过草稿。

把某个历史版本直接发布成当前版本，跳过草稿。回滚用。 草稿里未发布的改动不受影响，仍留在草稿态。

返回已发布版本的文件清单与包地址。Agent 运行时读的是这个。

要看草稿里未发布的改动，用 /management/content。

按包内相对路径读一个文件。返回的是文件的下载 URL 而不是内容本身—— 拿到 url 再去取。路径从 /content 返回的 files[].rel_path 里挑。

下载已发布版本的技能包。

/content 的管理态版本：读的是当前草稿，含尚未发布的改动。 Studio 的编辑页用它。

响应结构与消费态不同，比 /content 多了 name / description / version / source / file_type，以及 response_mode=content 时的 content 正文——编辑页要一次拿全，不想再跑一趟详情接口。

/files/read 的管理态版本：读草稿里的文件。默认返回下载地址； response_mode=content 时直接返回文件文本内容。

/download 的管理态版本：下的是当前草稿。

在沙箱里跑技能包里的一条命令。技能包被上传到沙箱工作目录，然后执行 entry_shell 指定的命令。

当前主体必须对具体 skill:{skill_id} 持有 execute。请求体不能替换 OAuth/AppKey 或受信任内部上下文产生的执行主体。

mocked 字段要看：为 true 表示这次并没有真的在沙箱里执行 （沙箱不可用等原因下的降级），返回的 stdout/stderr 不是真实结果。

与函数执行一样，命令失败不体现在 HTTP 状态码上——看 exit_code。

重建技能的检索索引——search_capabilities 的语义召回依赖它。

execute_type 决定范围：full 全量重建，incremental 只处理游标之后 变更的技能。任务异步执行，用返回的 task_id 查进度。

分页列出索引构建任务。

**status 过滤不接受 canceled**：任务状态本身有 5 个值 （pending / running / completed / failed / canceled）， 但这个查询参数的白名单只有前 4 个，传 canceled 会 400。

取单个任务的进度与计数。

取消排队中或运行中的任务。响应里的 action 说明实际做了什么， queue_state 说明取消时任务在队列里的位置——已经跑完的任务取消是无操作。

以失败任务为模板新建一个任务重跑。响应里 source_task_id 是原任务、 task_id 是新任务——原任务记录保留不变。