From 4ae9841f6b5d592f4db3c531c3cba531c527b9ec Mon Sep 17 00:00:00 2001 From: chenchen Date: Wed, 3 Jun 2026 12:20:44 +0800 Subject: [PATCH] docs(integration): add pre-flight, account, run-info & full endpoint inventory MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Close the remaining coverage gaps in the client-facing API doc (verified against real routes in router/api-router.go): - §2.1 NEW "sub 可用性就绪闸门": the 4-gate composite the client must pass before enabling sub (capabilities.enabled + device-bound + active git binding + balance), with pseudo-code and per-gate data source — directly answers "客户端判断 sub 是否可用". - §2.2 NEW account/balance: GET /api/user/self (+/self/groups,/self/models), quota/used_quota/request_count, model intersection rule. - §2 capabilities: documented every field (runtime_kind/model_selection/supports_*). - §4.2 NEW run-info interfaces with response shapes: logs(user/debug), timeline(events incl delivery.pushed), events, metrics, diagnostics, sk-snapshots. - §12 NEW full endpoint inventory by flow stage (①startup ②create ③monitor ④approve ⑤artifacts ⑥iterate ⑦deploy ⑧resources) with 🟢/🟡/🔴 status — a coverage checklist mapping every real route so nothing is silently missing. Co-Authored-By: Claude Opus 4.8 --- .../heicode-desktop-unified-api.md | 136 +++++++++++++++++- 1 file changed, 135 insertions(+), 1 deletion(-) diff --git a/docs/integration/heicode-desktop-unified-api.md b/docs/integration/heicode-desktop-unified-api.md index e8f68c10..ad8bf9ed 100644 --- a/docs/integration/heicode-desktop-unified-api.md +++ b/docs/integration/heicode-desktop-unified-api.md @@ -87,7 +87,48 @@ signature = base64( ed25519_sign(device_priv, sha256(canonical)) ) }} ``` -`enabled` 反映该模式 Runtime 当前是否接通。 +`enabled` 反映该模式 Runtime 当前是否接通（HM 探测 agent_management / HeiCode-Swarm 的健康；`enabled:false` 时**不要**让用户进该模式）。 +字段：`runtime_kind`（后端运行时）、`model_selection`（`default|per_role|primary`）、`supports_roles/task_graph/continue_chat`（UI 能力位）、`models[].available`（该模型当前可用）。 + +### 2.1 判断 sub 模式是否可用（就绪闸门）🟡 + +客户端在让用户点「sub 模式」前，必须先过**四道闸门**；任一不满足就**禁用 sub 入口**并提示对应引导。这是一个**客户端本地组合判断**（HM 不提供单一「ready」接口）： + +| # | 闸门 | 数据来源 | 不满足时 | +|---|---|---|---| +| 1 | **Runtime 接通** | `GET /api/heicode/capabilities` → `modes[id=sub_agile].enabled === true` | 灰掉 sub，提示「云端暂不可用」 | +| 2 | **已认证（设备已绑定）** | 本地有设备绑定 token（§1；无则先走 heicode-auth 登录/配对） | 引导登录 | +| 3 | **已绑有效 git 仓库** | `GET /api/heicode/resources?type=git&status=active`（§8.2）非空 | 引导去「资源绑定」绑 git，或改用本地模式 | +| 4 | **余额充足** | `GET /api/user/self` → `quota - used_quota > 0`（§2.2） | 引导充值 | + +```text +canUseSub = + capabilities.modes.find(m => m.id==='sub_agile')?.enabled + && isDeviceBound() + && gitBindings.some(b => b.status==='active') + && self.quota > self.used_quota +``` + +- 闸门 3「强制绑 git」对齐 spec §3.1；建任务时若仍没传有效 git binding，HM 也会兜底拒绝（`SUB_GIT_BINDING_REQUIRED`，§11）。 +- 闸门 1/4 用现有接口（🟢）；闸门 3 的客户端版资源列表是 🔴 待建（§8.2），上线前可临时用 `/api/resources/`（会话鉴权）联调。 +- **本地模式**（客户端自己跑 agent）不需要闸门 1/3，只需 2/4。 + +### 2.2 账户与余额（判断能不能跑 / 给概览用）🟢 + +| 方法 | 路径 | 鉴权 | 说明 | +|---|---|---|---| +| GET | `/api/user/self` | 会话/设备 | 当前用户：`quota`(剩余额度)、`used_quota`(累计已用)、`request_count`(调用次数)、分组等 | +| GET | `/api/user/self/groups` | 同上 | 用户可用模型分组 | +| GET | `/api/user/self/models` | 同上 | 当前用户**可用模型**列表（与 `capabilities.models` 互补，按分组过滤） | + +```json +// GET /api/user/self → data 摘要 +{ "id":22, "username":"...", "quota":160470000, "used_quota":39530000, "request_count":521, "group":"default" } +``` + +- 余额/用量单位是内部 quota（展示按汇率换算）；`quota` 为**剩余**，`used_quota` 为**累计已用**。 +- 建任务前应检查 `quota > used_quota`（闸门 4）；运行中若超预算 HM 会把任务标 `budget_exceeded`（§4）。 +- 模型选择（需求包 `model_selection`）只能用 `capabilities.models` ∩ `/api/user/self/models` 里 `available` 的模型。 ## 3. 统一任务接口 @@ -267,6 +308,35 @@ HM 判的是**"有没有真东西"这个事实**，**不读代码、不判对错 `client_task_status`（本地交互态）由客户端自己维护，不由 Manager 返回。 +### 4.2 运行信息接口（日志 / 时间线 / 诊断 / 事件 / 指标）🟢 + +work 视图除 `/workflow` 外，下列接口给**过程信息**（都只读、GET、V2 无 body 签名）。**它们只承载"运行信息"，不承载代码产物**（代码看 git_ref，§5）。 + +| 方法 | 路径 | data 关键字段 | 用途 | +|---|---|---|---| +| GET | `.../tasks/{id}/logs` | `user_logs[]`（友好）、`debug_logs[]`（原始）| 日志面板分两层：普通用户看 user，调试面板看 debug | +| GET | `.../tasks/{id}/timeline` | `events[]`（task./agent./phase./handoff./delivery.）、`callbacks[]`、`artifacts[]` 聚合 | 任务时间线 | +| GET | `.../tasks/{id}/events` | `events[]`（原始事件流） | 细粒度事件 | +| GET | `.../tasks/{id}/metrics` | `tokens_used`、`elapsed_seconds`、`total_messages` | 指标卡 | +| GET | `.../tasks/{id}/diagnostics` | `runtime_status`、`warnings[]`（直查 Runtime） | 排障 | +| GET | `.../tasks/{id}/sk-snapshots` | `snapshots[]` | SK 快照 | + +```json +// GET .../logs → data +{ "task_id":"dep_xxx", + "user_logs":[{"ts":"2026-06-03T..","level":"info","agent":"backend","message":"开始实现登录接口"}], + "debug_logs":[{"ts":"2026-06-03T..","level":"debug","message":"tool: write_file path=backend/auth.go"}] } +``` +```json +// GET .../timeline → data +{ "task_id":"dep_xxx", + "events":[{"event_type":"phase.changed","occurred_at":"..","payload":{"phase":"development"}}, + {"event_type":"delivery.pushed","occurred_at":"..","payload":{"git_ref":{"branch":"delivery/dep_xxx","commit_sha":"a1b2c3d"}}}], + "callbacks":[], "artifacts":[{"artifact_id":"art_x","artifact_type":"test_report"}] } +``` + +> 轮询建议：work 视图主要轮询 `/workflow`（含 display_status + agents + git_ref，一次拿全）；需要日志/时间线明细时再单独拉 `/logs`、`/timeline`。SSE 上线后这些都可由事件流推送（§4b）。 + ## 4b. 响应 envelope 与实时刷新 **成功**：`{ "success": true, "message": "", "data": {...} }` @@ -462,3 +532,67 @@ Schema 查询：`GET /api/agent/callbacks/runtime-events/schema`。 | ~~`ARTIFACT_REVISION_CONFLICT`~~ / ~~`ARTIFACT_ARCHIVE_NOT_READY`~~ / ~~`ARTIFACT_ARCHIVE_FAILED`~~ / ~~`FILE_NOT_FOUND`~~ / ~~`FILE_PATH_REQUIRED`~~ | **遗留**（local-edits/archive/files 已退役，见 §5.4/§6） | — | 其余错误码沿用旧文档 §13。所有错误统一形如 `{"success":false,"error":{"code","message","retryable"}}`，可读 `error.retryable` 决定是否重试。 + +## 12. 完整接口清单（按流程，覆盖核查） + +> 以**真实路由**为准（`router/api-router.go`）。`sub-agile` 路径把前缀换 `swarm` 即同形。状态：🟢 已实现 / 🟡 部分 / 🔴 待建。 + +**① 启动与就绪（§2）** + +| 接口 | 状态 | 章节 | +|---|---|---| +| `GET /api/heicode/capabilities` | 🟢 | §2 | +| `GET /api/user/self`、`/self/groups`、`/self/models` | 🟢 | §2.2 | +| sub 可用性组合判断（客户端本地） | 🟡 | §2.1 | +| 设备绑定 / 登录（`/api/heicode-auth/*`、`/api/user/...`） | 🟢 | 见 heicode-auth 文档 | + +**② 建任务与对话（§3）** + +| 接口 | 状态 | +|---|---| +| `POST /api/heicode/sub-agile/tasks`（需求包，含 resource_bindings、X-Idempotency-Key） | 🟢 建任务 / 🔴 强制 git 校验 + 幂等 | +| `GET .../tasks`、`GET .../tasks/{id}` | 🟢 | +| `POST .../tasks/{id}/messages`、`.../execute` | 🟢 | +| `POST .../tasks/{id}/stop`、`DELETE .../tasks/{id}` | 🟢 | + +**③ 运行监控 / work 视图（§4）** + +| 接口 | 状态 | +|---|---| +| `GET .../tasks/{id}/workflow`（含 git_ref、per-agent 富字段） | 🟢 本体 / 🔴 git_ref + per-agent 字段 | +| `GET .../tasks/{id}/logs`、`/timeline`、`/events`、`/metrics`、`/diagnostics`、`/sk-snapshots` | 🟢 | +| `GET .../tasks/{id}/events/stream`（SSE） | 🔴 §4b | + +**④ 审批（§3.2）** + +| 接口 | 状态 | +|---|---| +| `GET .../tasks/{id}/approvals?status=pending` | 🟢 | +| `POST .../approvals/{approval_id}/approve`、`/reject` | 🟢 | + +**⑤ 产物（§5）** + +| 接口 | 状态 | +|---|---| +| `git_ref`（在 workflow/详情里）→ 客户端 `git clone/pull` | 🔴 | +| `GET .../tasks/{id}/artifacts`、`.../artifacts/{aid}/content`（仅非代码运行信息） | 🟢 | +| ~~`.../artifacts/{aid}/{manifest,files,archive,revisions,local-edits}`~~ | 退役（§5.4） | + +**⑥ 修改 / 重做（§6）**：复用 ②的 `messages`/`execute`（+ 将来 `/redo` 🔴）；本地改走 git。 + +**⑦ 部署（§7）** + +| 接口 | 状态 | +|---|---| +| `POST /api/heicode/resources/{id}/lease`（短期凭据租约） | 🔴 | +| `DELETE /api/heicode/resources/leases/{lease_id}`（吊销） | 🔴 | +| ~~`GET /api/heicode/deployment-targets`、`POST/GET .../tasks/{id}/deployments`~~ | 废弃（旧代部署） | + +**⑧ 资源绑定（§8）** + +| 接口 | 状态 | +|---|---| +| `GET/POST /api/resources/`、`POST /{id}/secret`、`PUT/DELETE /{id}`（会话鉴权，网页台） | 🟢 §8.1 | +| `GET/POST/DELETE /api/heicode/resources*`、`/{id}/lease`（V2 设备签名，客户端） | 🔴 §8.2 | + +> 凡标 🔴 的，客户端**按本文契约预埋字段**即可；HM 侧补齐后无需改协议直接对齐。本清单即"整个流程要用到的接口"的核查表——发现遗漏请回填本表对应分组。