API 契约清单

本页是 Holon HTTP 控制平面 API 的基线后清单。它补充 HTTP 控制平面参考页，记录路由列表、 请求参数、响应形状，以及在脚本和集成能够长期依赖该 API 之前仍需稳定化的契约 缺口。

• 最后核对基准： holon v0.39.0，main 位于 885367b9。
• 权威来源： src/http/mod.rs 的 Axum 路由和 请求/响应结构体。
• 生成的 schema： openapi.json，由 holon::openapi::generate_openapi_json() 生成，并由 make snapshots-check 检查。
• 路由/schema 漂移检查： tests/snapshots/http_route_inventory.json，由 make snapshots-check 从 Axum 路由树和生成的 OpenAPI 基线产出。
• 客户端源码： src/client.rs，对应 TUI/CLI 使用的那部分子集。
• 当前状态： 1.0 之前的基线。把下面的形状视为已观察到的行为，而不是最终的 兼容性承诺。里程碑 8 确立了首个受检基线；剩余的缺口属于第二阶段稳定化工作。

稳定性级别

跨领域契约

传输与认证

入口信任/认证边界

通用 JSON 与响应行为

大多数成功响应是 JSON，但 Holon 不采用单一全局成功信封。稳定策略按路由类别划分：

当前代表性示例：

• /api/ 和 /api/handshake 返回 { "ok": true, ... }。
• /api/models 返回 { "available_models": ..., "model_availability": ... }， 没有 ok 字段。
• /api/agents/list、/api/agents/:id/status、/api/agents/:id/state、 /api/agents/:id/tasks 等读取路由直接返回记录或数组。
• /api/control/agents/:id/prompt、/api/control/agents/:id/wake 以及 workspace/model 变更路由返回 { "ok": true, ... }。
• /api/control/agents/:id/tasks、/api/control/agents/:id/work-items 和 /api/control/agents/:id/timers 直接返回创建出的记录。
• /api/agents/:id/events/stream 在流打开后返回服务端发送事件，而不是 JSON 响应体。

处理器产生的控制平面错误使用一个共享 JSON 信封：

{
  "ok": false,
  "error": "message",
  "code": "machine_readable_code",
  "hint": "optional operator guidance"
}

对这些处理器产生的错误，ok 始终为 false；error 是人类可读消息。code 和 hint 是可选共享字段。路由可以在共享字段之外添加有文档的路由专属扩展字段。 在处理器运行前产生的框架级拒绝，例如 Axum 针对畸形 JSON 的 extractor 失败，或 被 DefaultBodyLimit 拒绝的请求体，尚未纳入该信封。

状态码映射：

当前常见的路由专属错误扩展包括：

已知的稳定错误 code 值：

src/client.rs 以兼容方式解码该信封：显示时只要求 error，并在 LocalHttpError 中保留可选的 code 和 hint。除非调用方直接检查原始响应， 否则客户端会忽略未知扩展字段。

端点清单

发现与运行时

Agent 读模型

默认 agent 别名：

事件与流

事件分页游标是排他的：after_seq 返回 event_seq 更大的记录，before_seq 返回 event_seq 更小的记录，两者同时给出时返回 after_seq < event_seq < before_seq。省略 after_seq 时，SSE 流从当前尾部 之后开始；after_seq=0 时从当前重放窗口重放；当非零 after_seq 落在该重放 窗口之外时，会在打开流之前返回 404 cursor_not_found。落后的实时接收方会关闭 SSE 连接，而不是跨越隐藏的间隙继续；客户端从每个 agent 最后一个连续的 event_seq 恢复。仅实时的全局流没有全局游标，因此客户端要分别回填每个 agent。

稳定的 StreamEventEnvelope 字段：

{
  "id": "event-uuid",
  "event_seq": 42,
  "ts": "2026-05-24T00:00:00Z",
  "agent_id": "main",
  "type": "task_created",
  "provenance": { "authority_class": "operator_instruction", "task_id": "task-..." },
  "payload": {}
}

事件 payload 是协议标准，会完整包含。事件页可以用 max_level=info|verbose|debug 过滤事件是否被包含；过滤不会改变 payload。 实时事件流是原始的，不支持级别过滤。

从已移除的 projection 契约迁移的破坏性变更：

• 从事件分页和流请求中删除 projection=operator / projection=local_debug
• 停止读取 StreamEventEnvelope.projection；现在所有信封都包含完整的标准 payload
• 用 /api/agents/:id/events?max_level=info 获取 operator 密度的历史页面， 原始流则由客户端侧过滤

公共入口

EnqueueRequest 字段：

控制操作

任务、工作项和定时器

CreateCommandTaskRequest 字段：

工作区与模型控制

Operator 传输集成

OperatorTransportBindingRequest 是严格的（deny_unknown_fields），包含 binding_id?、transport、operator_actor_id、target_agent_id?、 default_route_id、delivery_callback_url、delivery_auth、capabilities、 provider?、provider_identity_ref? 和 metadata?。

delivery_auth.kind = "bearer" 要求非空的 bearer_token。 在实现 HMAC 签名之前，delivery_auth.kind = "hmac" 会被拒绝。

Skills

Skill 管理把库操作和 agent 启用分开：

回调能力入口

Body 解码规则：

• JSON content type 变成 MessageBody::Json。
• text/* content type 变成 MessageBody::Text。
• 其他带类型的 body 变成 JSON，附带 content_type 和 body_base64。
• 无类型的 UTF-8 body 变成 text；非 UTF-8 body 变成 JSON，附带 body_base64。

需要稳定化的共享记录形状

以下响应类型由多个端点暴露，应作为 schema 接口来对待，而不是偶然的 Rust 结构体：

v0.38.0 身份迁移遗留

AgentVisibility、AgentOwnership、PrivateChild 和 PublicNamed 仅作为 v0.38.0 迁移词汇保留。它们不是当前的公共 API 身份区分符。新集成应使用 CreateAgent 创建可寻址 agent，使用 InvokeAgent 进行父级监督的委派执行。

已发现的契约缺口

1. OpenAPI 路由/类型元数据仍只部分与实现同处一地。 路由覆盖和 schema 快照 已经存在，但生成的基线仍依赖一份保守的 OpenAPI 表。第二阶段会把操作元数据 移近 Axum 路由/类型定义。
2. 稳定 DTO schema 需要收紧。 若干 task、work-item、timer、agent、event 和 信封响应在 OpenAPI 基线中仍以宽泛形式表示；在它们成为稳定的客户端契约之处， 应变成一等带类型组件。
3. 事件级别过滤需要更多真实场景覆盖。 在把 max_level 的包含规则当作最终 规则之前，应针对真实的 TUI/客户端会话进行验证。
4. WorkItem 变更 API 现在覆盖 focus/update/complete。 HTTP 可以列出/读取/ 创建/入队工作项，拾取焦点，更新 objective/planning/blocker 字段，并完成工作项。 在需要独立生命周期契约之前，取消/删除有意保持在范围外。
5. 定时器生命周期 API 现在覆盖取消。 HTTP 可以创建/列出/读取定时器，并取消 活跃定时器。删除/清除仍不在范围内。
6. 部署指引仍需加固。 HTTP 入口信任/认证表已有文档，但面向生产的指引仍应 说明何时使用 bearer 模式、本地模式、回调能力和专用 operator 适配器。
7. 工具 schema 是独立的 API 接口。 内置工具的输入/结果 schema 现在有了自己 的受检清单；本 HTTP 清单应链接到它，而不是重复它。

跟踪 issue

里程碑 8 的基线 issue 已完成。第二阶段的后续 issue 归在同一个 CLI/API Stability Contracts 里程碑下，并由 #1444 跟踪。

建议的后续工作

1. 把 OpenAPI 基线迁移到 aide 路由/类型元数据 （#1438）。
2. 为稳定读模型和控制平面结果收紧 DTO schema （#1439）。
3. 定义稳定的、面向 operator 的事件 payload 子集 （#1443）。