docs(integration): desktop client API doc for the template-agent model
New authoritative client doc (heicode-desktop-client-api.md): the desktop client lists its agents from HM, gets each agent's subdomain + access_token, and connects to the agent directly over SSE; models for both client and agent go through HM /v1/*. Grounded in the production-verified responses (19 Chinese templates, agent list/deploy/status shapes, error codes). Marks the old unified-api doc (sub task-orchestration) as superseded. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.8
@@ -0,0 +1,215 @@
|
||||
# Heicode 桌面客户端 对接接口文档（模板 Agent 模型 · v1）
|
||||
|
||||
> 更新时间：2026-06-04
|
||||
> 适用：Heicode Desktop 对接 Heicode Manager（HM）的**模板 Agent 模型**。
|
||||
> 生产地址：`https://code.xinghanlab.com`
|
||||
> 状态图例：🟢 已实现并生产验证 · 🔴 待建（依赖 AM）
|
||||
|
||||
> **本文取代旧的 `heicode-desktop-unified-api.md`**（那份描述的是已下线的 sub 任务编排模型：tasks/workflow/display_status/git_ref/产物下载等，均已删除）。新客户端一律按本文对接。
|
||||
|
||||
---
|
||||
|
||||
## 0. 模型总览（先读）
|
||||
|
||||
新模型很简单:
|
||||
|
||||
1. 用户在 **HM 网页控制台**绑定资源(git/vm/数据库/对象存储)、选「资源 + 模板」**部署一个常驻 agent**。
|
||||
2. HM 把所选资源解出后注入 agent 的 `.env`,交给 **AM** 启动;AM 返回**唯一子域名 + 访问 token**。
|
||||
3. **桌面客户端**从 HM 读 agent 列表 → 拿到**子域名 + token** → **直连 agent 子域名(SSE)对话使用**。**HM 不在对话回路里。**
|
||||
4. **模型调用**:客户端自己用模型、以及 agent 用模型,**都走 HM `/v1/*`**(鉴权 + 计费)。
|
||||
|
||||
> 客户端在新模型里的核心动作 = **列出我的 agent → 直连用**。部署/管理主要在网页台完成(客户端也可调同一接口)。
|
||||
|
||||
**总原则**
|
||||
- 客户端调 HM 用 **V2 设备签名**(与模型调用同一套,见 §1)。
|
||||
- 列表里的 `access_token` 是连 agent 用的,**由 agent 自己校验**;HM 只负责发给你。
|
||||
- 模型永远走 HM `/v1/*`,不要直连上游。
|
||||
|
||||
---
|
||||
|
||||
## 1. 认证与加密 🟢
|
||||
|
||||
与模型调用(`/v1/*`)完全一致,复用同一套 `encryptedFetch` / V2 设备签名,无需新增协议:
|
||||
|
||||
| 方式 | 适用 |
|
||||
|---|---|
|
||||
| **V2 加密 body + 设备签名**（`Content-Encoding: heicode-aead-v1` + `X-Heicode-*`，ChaCha20-Poly1305 + Ed25519） | 有 body 的写请求(POST/DELETE) |
|
||||
| **V2 无 body 设备签名**（`X-Heicode-*` 签名头，不带 `Content-Encoding`） | GET 等无 body 请求 |
|
||||
| Manager 会话 cookie + `New-Api-User: <user_id>` | 网页控制台路径(桌面端可不用) |
|
||||
|
||||
- canonical 里的 `path_with_query` 用 HM 实际收到的 path(不含 origin);每次新 nonce + 新临时 X25519 key。
|
||||
- 服务端中间件 `UserOrV2DeviceAuth` 解密 + 验签,从设备绑定 token 解析用户身份。
|
||||
- GET 无 body:不发 `Content-Encoding`、不加密,body 哈希填 `sha256("")`。
|
||||
|
||||
> 细节同旧文档 §1（该机制未变,只有上面这层加密链路保留)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 账户与余额 🟢
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|---|---|---|
|
||||
| GET | `/api/user/self` | 当前用户:`quota`(剩余)、`used_quota`(累计已用)、`request_count`、分组 |
|
||||
|
||||
```json
|
||||
// data 摘要
|
||||
{ "id":22, "username":"chenchen", "quota":..., "used_quota":..., "request_count":... }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 能力发现 🟢
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|---|---|---|
|
||||
| GET | `/api/heicode/capabilities` | 模型目录(渲染模型选择);免登录 |
|
||||
|
||||
```json
|
||||
{ "success": true, "data": { "models": [{"id":"gpt-5.4","name":"gpt-5.4","available":true}] }}
|
||||
```
|
||||
|
||||
> 旧的 `modes`(sub_agile/swarm 任务模式)在新模型已无意义,客户端只需 `models`。
|
||||
|
||||
---
|
||||
|
||||
## 4. Agent 模板列表 🟢
|
||||
|
||||
供客户端展示"有哪些 agent 角色可用"。模板由 HM 维护(管理员可在控制台增改),**展示用中文名 + 中文简介**。
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|---|---|---|
|
||||
| GET | `/api/heicode/agent-templates` | 列出可部署的 agent 模板 |
|
||||
|
||||
```json
|
||||
{ "success": true, "data": {
|
||||
"total": 19,
|
||||
"items": [
|
||||
{"template_id":"architect","name":"架构顾问","description":"只读地分析代码、定位缺陷、给出架构与调试建议","model":"opus","status":"active"},
|
||||
{"template_id":"code-reviewer","name":"代码审查员","description":"审查代码改动，找出 bug 与质量问题","model":"...","status":"active"}
|
||||
]
|
||||
}}
|
||||
```
|
||||
|
||||
- `template_id` 是模板的稳定 key(如 `architect`),部署时回传。
|
||||
- `name` / `description` 为中文,直接展示。
|
||||
|
||||
---
|
||||
|
||||
## 5. 我的 Agent 🟢（部署调用 AM，AM 接口待建）
|
||||
|
||||
> ⚠️ `subdomain` / `access_token` 来自 AM。当前 AM 的启动/状态接口尚未实现(🔴),`POST /agents` 会返回 `RUNTIME_UNAVAILABLE`;HM 侧逻辑已就绪并生产验证,AM 一上线即通。
|
||||
|
||||
| 方法 | 路径 | 说明 | 状态 |
|
||||
|---|---|---|---|
|
||||
| GET | `/api/heicode/agents` | 列出我部署的 agent | 🟢 |
|
||||
| GET | `/api/heicode/agents/{agent_id}` | agent 详情(读取时刷新状态) | 🟢 |
|
||||
| GET | `/api/heicode/agents/{agent_id}/status` | 主动拉 agent 实时状态(是否运行/挂了) | 🟢 |
|
||||
| POST | `/api/heicode/agents` | 部署:`{template_id, binding_ids:[...]}` | 🟢(调 AM 🔴) |
|
||||
| POST | `/api/heicode/agents/{agent_id}/stop` | 停止 | 🟢 |
|
||||
| DELETE | `/api/heicode/agents/{agent_id}` | 删除 | 🟢 |
|
||||
|
||||
**列表 / 详情 / 部署成功 返回的 agent 对象:**
|
||||
|
||||
```json
|
||||
{ "success": true, "data": {
|
||||
"items": [
|
||||
{
|
||||
"agent_id": "dep_b5fab27e9255", // HM 侧 agent 记录 id
|
||||
"template_id": "architect", // 用了哪个模板
|
||||
"subdomain": "https://xxxx.agents.example", // ★ 直连地址(AM 分配)
|
||||
"access_token": "…", // ★ 连 agent 用的 token
|
||||
"binding_ids": [16], // 挂了哪些资源绑定
|
||||
"status": "running", // running | stopped | failed | …
|
||||
"runtime_id": "rt_…", // AM 侧运行时 id
|
||||
"created_at": "2026-06-04T…",
|
||||
"updated_at": "2026-06-04T…"
|
||||
}
|
||||
],
|
||||
"total": 1
|
||||
}}
|
||||
```
|
||||
|
||||
**部署请求** `POST /api/heicode/agents`:
|
||||
```json
|
||||
{ "template_id": "architect", "binding_ids": [16] }
|
||||
```
|
||||
- `binding_ids` 是网页台「资源绑定」里已绑资源的 id(可空数组,表示不挂资源)。
|
||||
- HM 处理:加载模板 `.md` → 把所选资源按类型解成 env(非密配置 + 从 Key Vault 解出的密钥)→ 连同模板定义交 AM 启动 → 存 `{subdomain, access_token}` 返回。
|
||||
|
||||
**状态查询** `GET /api/heicode/agents/{id}/status`:
|
||||
```json
|
||||
{ "success": true, "data": { "agent_id":"dep_…", "status":"running", "updated_at":"2026-06-04T…" }}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 直连 Agent（客户端 ↔ agent，SSE）🔴
|
||||
|
||||
> 这一段是 **客户端直接连 agent**,不经过 HM。HM 只负责把 `subdomain + access_token` 给你。
|
||||
|
||||
- 从 §5 列表拿到某个 `status=running` agent 的 `subdomain` 和 `access_token`。
|
||||
- 客户端**直连该子域名,SSE 双向通信**,请求携带 `access_token`(具体头部/握手以 AM 的 agent 端契约为准)。
|
||||
- **agent 自己校验 token**;token 错/缺则拒绝(防公网裸奔)。
|
||||
- agent 用 `.env` 里注入的资源(git/vm/db/blob 配置)自行干活;**用模型仍打 HM `/v1/*`**。
|
||||
- agent 不会把 `.env`/密钥回显到对话或日志(由 AM 保证)。
|
||||
|
||||
> 该直连契约(SSE 握手、token 头名、消息格式)由 AM 的 agent 端定义,定稿后补入本节。
|
||||
|
||||
---
|
||||
|
||||
## 7. 模型调用 🟢
|
||||
|
||||
- 客户端自己用模型:`POST /v1/chat/completions` 等,base_url = HM,鉴权同模型调用。
|
||||
- agent 用模型:agent 内部也打 HM `/v1/*`(用户身份计费)。
|
||||
- 两边共用同一套模型接口,HM 统一鉴权 + 计费 + 路由。
|
||||
|
||||
---
|
||||
|
||||
## 8. 响应 envelope 与错误码
|
||||
|
||||
**成功**:`{ "success": true, "data": {…} }`
|
||||
**失败**:`{ "success": false, "error": { "code": "…", "message": "…" } }`
|
||||
|
||||
| code | 场景 | 说明 |
|
||||
|---|---|---|
|
||||
| `POLICY_REJECTED` | 参数非法 / 未认证 / 未知 `template_id` | 不可重试,改参数 |
|
||||
| `RESOURCE_BINDING_INVALID` | `binding_ids` 里有不存在/非本人的绑定 | 检查资源 |
|
||||
| `RUNTIME_UNAVAILABLE` | 调 AM 失败(含 AM 接口未就绪) | AM 侧问题,可稍后重试 |
|
||||
| `DEPLOYMENT_CONFLICT` | agent 不存在 | — |
|
||||
| `DEPLOYMENT_PERSIST_FAILED` | HM 落库失败 | — |
|
||||
|
||||
实时刷新:运行中轮询 `GET /agents` 或 `/agents/{id}/status`(3–5s);终态降频。
|
||||
|
||||
---
|
||||
|
||||
## 9. 客户端完整流程
|
||||
|
||||
```text
|
||||
0. (设备绑定/登录) — 复用模型调用的 V2 设备签名
|
||||
1. (可选) GET /api/heicode/capabilities 取模型目录
|
||||
2. (可选) GET /api/user/self 取余额
|
||||
3. GET /api/heicode/agents 列出我的 agent
|
||||
- 想看有哪些角色: GET /api/heicode/agent-templates (中文名/简介)
|
||||
- 部署(也可在网页台做): POST /api/heicode/agents {template_id, binding_ids}
|
||||
4. 选一个 status=running 的 agent → 取 subdomain + access_token
|
||||
5. 直连 subdomain (SSE, 带 token) → 与 agent 对话/干活 ← 不经 HM
|
||||
6. 期间用模型 → HM /v1/* (客户端与 agent 两端都是)
|
||||
7. 管理: GET /agents/{id}/status | POST /agents/{id}/stop | DELETE /agents/{id}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. 接口清单（覆盖核查）
|
||||
|
||||
| 接口 | 鉴权 | 状态 |
|
||||
|---|---|---|
|
||||
| `GET /api/heicode/capabilities` | 无 | 🟢 |
|
||||
| `GET /api/user/self` | 会话/设备 | 🟢 |
|
||||
| `GET /api/heicode/agent-templates` | 会话/设备 | 🟢(生产已验证 19 中文模板) |
|
||||
| `GET /api/heicode/agents` `/{id}` `/{id}/status` | 会话/设备 | 🟢 |
|
||||
| `POST /api/heicode/agents` | 会话/设备 | 🟢(调 AM,AM 接口 🔴) |
|
||||
| `POST /api/heicode/agents/{id}/stop`、`DELETE /{id}` | 会话/设备 | 🟢(调 AM 🔴) |
|
||||
| 模型 `/v1/*` | 同模型调用 | 🟢 |
|
||||
| 直连 agent SSE(subdomain+token) | agent 自校验 | 🔴(待 AM agent 端) |
|
||||
|
||||
> 🔴 项不阻塞客户端集成:HM 侧字段/接口已定型并生产验证,等 AM 实现 agent 启动/状态/直连即全线打通。AM 契约见 `heicode-hm-template-agent-model.md` §7 与代码 `controller/agent_template_runtime.go`(隔离层)。
|
||||
Reference in New Issue
Block a user