Skill (0.1.3)

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

file_type 决定 file 字段怎么解读：

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

按业务域分页列出技能，支持按名称、状态、分类、创建人过滤。

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

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

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

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

删除技能及其全部版本。已被 Agent 挂载的技能删除后装载会失败； knowledge network 里的 skills 对象类记录也会随之失效 （context-loader 的 find_skills 依赖它）。

只接受 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 的管理态版本：读草稿里的文件。

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

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

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

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

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

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 是新任务——原任务记录保留不变。