heicode-mananger/docs/integration/heicode-desktop-client-api.md

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、分组

// data 摘要
{ "id":22, "username":"chenchen", "quota":..., "used_quota":..., "request_count":... }

---

3. 能力发现 🟢

方法	路径	说明
GET	/api/heicode/capabilities	模型目录(渲染模型选择);免登录

{ "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 模板

{ "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 对象:

{ "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:

{ "template_id": "architect", "binding_ids": [16] }

• binding_ids 是网页台「资源绑定」里已绑资源的 id(可空数组,表示不挂资源)。
• HM 处理:加载模板 .md → 把所选资源按类型解成 env(非密配置 + 从 Key Vault 解出的密钥)→ 连同模板定义交 AM 启动 → 存 {subdomain, access_token} 返回。

状态查询 GET /api/heicode/agents/{id}/status:

{ "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. 客户端完整流程

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(隔离层)。