发现目录
GET /v1/catalog 返回 200、{connections,harnesses,harness_templates,harness_protocols},无分页。Connections 含 adapter kind/provider/capabilities 及可选 setup_url/evidence。Harnesses 是租户可见的执行定义;harness_templates 是独立模板集合,不承诺所有镜像已注册或可用。Harness_protocols 描述适配器协议契约。
注册 OCI Harness
POST /v1/harnesses 接受严格对象:
镜像引用采用 Docker Hub 或 GHCR 的仓库格式,不是任意 URL。
python:3.12 会展开为 Docker Hub 的 library/python;org/image:tag 默认使用 Docker Hub;支持显式 docker.io/... 和 ghcr.io/...。省略 tag / digest 时选择 latest。digest 选择器必须是 @sha256: 加 64 位小写十六进制字符。HTTP(S) scheme、自定义 registry 主机和主机端口会被拒绝。为可重复注册优先使用固定 digest;格式合法仍要求实际镜像实现选定的 Harness 协议。
私有 registry 的 managed Secret 值必须为严格 JSON {username,password},两项非空。不要把 registry Secret 放入镜像 URL 或日志。解析器检查支持的镜像/平台契约,当前固定 linux/amd64。可运行镜像要求见 OCI 集成。
将真实镜像定义保存为 harness-image.json:
400 harness_entrypoint_missing。
不可变键为租户/id/version。相同解析定义重复注册返回原定义,不同内容占用同键返回 409 harness_version_conflict。Tag 可在请求间移动,因此保留返回的 digest,并使用不可变镜像引用。OCI 与源码包共享版本命名空间,此处没有公开 update/delete 路由。
注册源码包
POST /v1/harness-packages 接受严格对象:
路径最多 240 字符,以字母/数字/下划线/连字符开头,其他字符可含字母数字、下划线、点、斜线、连字符。拒绝空段、
.、..、重复路径和文件/目录冲突。Content 是文本,不是 Base64,每文件最多 262,144 个 JavaScript 字符串码元,全部 UTF-8 内容最多 512 KiB。此接口不是通用依赖安装器。
按源码包指南准备 harness-package.json,包含实际可执行的协议实现:
409 harness_version_conflict。
注册在控制平面只保存数据。执行时在 Sandbox 安装并逐字节校验文件,要求 interpreter 存在,程序实现声明协议。源码接受不证明 Tool 支持、连续对话、正确性或超出已说明 Sandbox 边界的隔离。
严格输入无效返回 400 invalid_request,registry/manifest 问题返回解析器错误。私有 registry 查找可能返回 secret_not_found(404)、secret_disabled(409)、secret_store_unavailable(503)、image_registry_credential_invalid(400)。响应丢失后依据目录中的身份/digest 对账,不要用更换版本绕过冲突。
注册失败
两个注册接口使用通用错误封装。以下命名错误补充严格输入校验;传输或未分类服务端失败仍可能采用通用错误契约。
私有 registry Secret 错误见上文。source package 的路径、入口文件、文件数、编码后大小和严格 schema 违规返回
400 invalid_request;成功注册包不会运行解释器或验证执行行为。registry 内部可对有界读取失败重试,这不授权重试镜像发布、云资源分配或外部 Tool 写入。
来源:目录投影、OCI 注册、源码包、路由。示例 origin 不带 /v1;本轮没有访问 registry、执行注册或云任务。下一步:HTTP 总览、Harness 选择。