API 与事件

AgentHub 的公开契约分为 REST API、WebSocket event、Runtime adapter event 和 IM integration event。本页描述稳定方向与边界；具体 OpenAPI 规范、事件 schema 和 SDK 包仍在开发中。

契约分层

协议细节的拥有方是 AgentHub 仓库 api/ 目录。本公开文档保留读者视角：每一层做什么、谁负责、哪些东西不能越界。

稳定性矩阵

最后公开校验日期：2026-06-09。如果 AgentHub 仓库的 OpenAPI 或 event schema 与本页冲突，以 owning repository 的 schema 为准，并在同一轮更新本页。

Hub API

Hub API 负责协作和权限层。典型资源包括：

• sessions：用户会话、Hub session、低风险个性化状态。
• projects：团队项目、workspace 关联、可见性和成员关系。
• devices：Desktop / Edge 设备注册、在线状态和路由目标。
• tasks：来自 Web、Desktop 或 IM 的工作请求。
• runs：Agent 执行实例和运行状态。
• audit：重要操作、审批、失败和权限判断。

Hub API 不应直接暴露模型 API key，Web 客户端也不应绕过 Hub 直接操作本地 workspace。

预期 Hub API 分组：

公开示例只使用占位 host 和 token。不要把生产 admin key、JWT 或私有 callback payload 复制进文档。

最小请求形状如下。路径和字段在公开 OpenAPI 稳定前仍处于 preview 状态：

GET /client/sessions HTTP/1.1
Host: hub.example.invalid
Authorization: Bearer <agenthub_session_token>
Accept: application/json

{
  "items": [
    {
      "id": "session_123",
      "projectId": "project_123",
      "title": "Local review",
      "state": "active",
      "updatedAt": "2026-06-09T00:00:00Z"
    }
  ],
  "nextCursor": null
}

Edge API

Edge API 负责本地执行边界。典型能力包括：

• 列出和选择 workspace。
• 启动、取消和查询 run。
• 读取运行事件、artifact、diff 和 preview。
• 管理 runtime adapter preset。
• 执行本地健康检查。

Edge 是靠近文件系统和进程的边界，默认应更保守：最小权限、workspace allowlist、明确审批和可审计事件。

预期 Local Edge 分组：

浏览器 WebSocket 客户端通常无法可靠设置自定义 header，因此本地 Edge token 可能通过 query parameter 参与 WebSocket upgrade。这个机制只保护 loopback Edge 进程边界；Hub/Remote/Cloud 路由仍需要 Hub-issued session、target authorization 和 audit。

Local Edge 创建 run 的 preview 示例：

POST /v1/runs HTTP/1.1
Host: 127.0.0.1:3210
Content-Type: application/json
Authorization: Bearer <local_edge_token>

{
  "workspace": "workspace_123",
  "agentId": "codex-local",
  "input": {
    "text": "Review README and suggest one documentation improvement."
  },
  "mode": "read_only"
}

WebSocket 事件流示例：

ws://127.0.0.1:3210/v1/events?runId=run_123&token=<local_edge_token>

WebSocket Event

WebSocket event 用于把执行过程流式推送到 Desktop/Web：

字段命名应保持可版本化，客户端不应依赖未声明的内部字段。

Event 词汇表

API 文档、runtime adapter、Desktop/Web 渲染、搜索词和 release note 都使用这套词汇。不要混用 message.delta 这类裸名称和 run-scoped 名称。

Event Envelope

每个 event 都应该方便 Desktop/Web 渲染，也方便审计代码存储。保持稳定 envelope，payload 另行版本化：

推荐客户端行为：

• 忽略未知 event type，但保留在日志中。
• 按 id 或 seq 去重。
• 把 partial event 渲染为进展状态，而不是最终事实。
• 当 event 内含路径、prompt 或不宜公开的模型输出时，不要把原始细节放进公开截图。

示例 event：

{
  "id": "evt_001",
  "seq": 1,
  "type": "run.tool.call",
  "runId": "run_123",
  "sessionId": "session_123",
  "agentId": "codex-local",
  "createdAt": "2026-06-09T00:00:00Z",
  "payload": {
    "tool": "read_file",
    "label": "Read README",
    "status": "started"
  }
}

Runtime Adapter Event

Runtime adapter 把各 CLI/runtime 的输出归一化。例如 Claude Code 的 NDJSON、Codex 的 JSONL/event stream、OpenCode 的 JSON event 都应转换为 AgentHub 事件。

Adapter 至少需要表达：

• 运行开始、结束和失败。
• 模型消息和增量。
• 工具调用和工具结果。
• 文件修改、diff、artifact。
• 需要用户审批或额外输入的状态。

描述 runtime 输出时，Runtime adapter event 应优先使用上面的 run-scoped 词汇，例如 text delta、tool call、tool result、file change、permission request、session init 和 final result。只有在不暴露 secret 的情况下，才把 adapter 原始消息作为调试信息附带。

IM Integration Event

Feishu/Lark 集成事件由 Integration Gateway 处理，再转成 Hub 可理解的 task 或 action。当前重点是：

• im.message.receive_v1：单聊或群聊 @ 机器人消息。
• card.action.trigger：交互卡片按钮回调。
• TokenDance ID 绑定状态更新。

这些事件必须快速确认、异步处理耗时任务，并避免把 secret 或完整 workspace 上下文放进卡片 payload。

错误格式

REST API 应返回稳定错误格式，让 Web/Desktop 能展示可恢复失败，而不是解析日志：

预期状态要使用具体错误码：invalid agent id、unauthorized target、workspace outside allowlist、permission denied、runtime unavailable、timeout、cancellation 和 schema validation failure。

建议错误码：

授权矩阵

契约应在 handler 开始工作前明确授权边界。

不要复用 TokenDance API key 做这些产品动作。TokenDance API key 用于通过 TokenDance Gateway 调模型 API；AgentHub 产品动作需要 TokenDance ID 以及 Hub/Edge 授权。

分页和幂等

Hub API 在列出 session、project、task、run、audit event 或 message 时，应支持 cursor pagination。除非 owning OpenAPI 已经确认，否则公开 docs 不承诺 offset pagination。

推荐列表形状：

{
  "items": [],
  "nextCursor": null,
  "requestId": "req_123"
}

Web、Desktop、Hub 或 Integration Gateway 可能重试的写接口，应接受 idempotency key，或从 upstream event id 派生幂等键。最重要的场景包括 IM card action、task creation、run creation、approval action 和 artifact publication。

兼容性检查

把某组 API 或 event 写成稳定前，先确认：

1. 英文和中文 docs 描述相同状态和边界。
2. owning AgentHub 仓库里已经存在 OpenAPI 或 event schema。
3. Desktop/Web 能安全渲染未知字段。
4. 错误码覆盖 unauthorized target、workspace allowlist、runtime unavailable、timeout、cancellation 和 schema validation。
5. 请求和 event 示例使用占位 host、占位 token 和脱敏路径。
6. 搜索索引、侧栏 TOC、llms.txt、sitemap、FAQ 和 changelog 在相关处同步提到该契约。

安全边界

• TokenDance ID 认证用户；Hub 签发并校验 AgentHub 产品 session。
• TokenDance API key 用于模型 API 调用，不是 AgentHub 浏览器登录凭据。
• Web 是 Hub-only，不能直接调用 Local Edge。
• Desktop 可以在 loopback 上调用 Local Edge 做本地执行。
• Edge 只能在 allowlisted workspace 内访问本地文件。
• 飞书/Lark 事件必须通过 TokenDance ID 完成账号绑定后才能成为 Hub task。

版本和兼容性

• REST API 应以 OpenAPI 为准。
• WebSocket event 应有可版本化 schema。
• Runtime adapter contract 变更需要同步 Desktop/Web 渲染和审计逻辑。
• 公开 SDK 发布前，文档示例只作为架构说明，不承诺稳定 import path。

Schema 来源

本页是公开阅读指南。实现工作请以 AgentHub 仓库中的这些文件为准：