3.5 KiB
草稿与结构校验 API
这是创作平台的第一层：创建私有草稿、维护文件和运行结构校验。尚不包含网页工作台、模型执行、MCP 探测、自动修复确认或发布集成。草稿校验通过不等于技能已发布，也不代表运行效果或安全扫描通过。
权限与文件
接口同时支持 /api/v1/authoring 与 /api/web/authoring；复用平台认证及浏览器 CSRF 规则。草稿与运行的读取、编辑和事件订阅仅允许所有者或超级管理员。创建草稿还要求目标空间可写，并满足已有空间成员权限。
POST /drafts 创建草稿并生成 SKILL.md 模板。文件操作在 /drafts/{draftId}/files，读取内容在 /drafts/{draftId}/files/content?path=...。保存请求可带 expectedRevision；版本不匹配返回冲突。同一草稿的写入串行化，文件仍受技能包路径、扩展名、单文件大小、文件数量和总大小限制。
文件保存和读取的 encoding 为 text 或 base64。合法 UTF-8 内容返回 text，非 UTF-8 字节返回 base64；调用方按返回的 encoding 解码，保存时使用相同 encoding，不能将图片等二进制内容当普通字符串处理。
删除草稿先提交数据库事务，再清理私有对象；数据库回滚不会删除仍被引用的文件。提交后存储清理失败会留下不可达的私有对象，并记录清理失败，不假装数据库删除失败。
运行与事件
POST /drafts/{draftId}/runs 为当前草稿 revision 创建运行。同一草稿最多有一个活动运行。执行时核验 revision 并捕获稳定的文件内容；排队期间草稿被修改则该运行失败，不能把新版内容冒充旧版的检测结果。已捕获内容不随之后的编辑改变；只有成功且草稿 revision 仍匹配的运行才更新草稿校验标记。
运行状态、事件和 findings 在 /runs/{runId} 及其子接口读取。SSE 在 /runs/{runId}/events/stream，可用 afterSeq 或 Last-Event-ID 恢复，按连续序号发送回放和实时事件。只有真正终态才能记录 RUN_FINISHED，重复完成不会产生第二条终态事件。连接或缓冲超过限制时关闭／拒绝连接，客户端可凭最后确认的事件编号重连，或通过轮询获取持久化记录。
执行器为有界线程池；队列满时已创建的排队运行会受控失败，不由 HTTP 请求线程代为执行，也不留下永久排队记录。取消或超时先使运行落入终态，阻止后续事件／finding 写入，再协作中断本机任务。中断不保证硬停止不响应中断的计算或外部 I/O，不能视为进程级沙箱。
配置与迁移
部署属性为 skillhub.authoring.executor-threads、run-timeout-ms、stale-run-minutes 与 workspace-root。默认执行线程 4、执行期限 900,000 毫秒、遗留活动运行清理阈值 30 分钟；期限从任务实际执行开始计算，遗留清理是恢复机制。修改启动配置需要重启应用。维护任务不会因数据库暂时失败就删除工作目录。
数据库迁移为未发布的 V69__authoring_platform.sql。正 revision、非负大小／计数及状态转换在业务代码中验证；数据库保留主键、外键和唯一性结构约束。头像／邀请 PR #947 使用 V70–V74，须在 V69 合入后验证其升级顺序，避免把较低编号的迁移留到已应用较高版本之后。
API 的完整字段、操作与响应以服务生成的 OpenAPI 为准；本文件不替代接口定义。