taijibaga/heicode-mananger
9
0
Fork 0
Code Issues 12 Pull Requests Actions Packages Projects 1 Releases Wiki Activity

fix: enable encrypted swarm requests

Browse Source
This commit is contained in:
gongzhiyong
2026-05-28 16:58:27 +08:00
parent 7f9f70b1dc
commit d2f7ab7333
6 changed files with 153 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/integration/AgentManager蜂群Runtime接口实现要求.md
+54 -1
View File
@@ -24,6 +24,45 @@ Agent Manager / Swarm Runtime 需要负责执行层：
- 接收审批结果后继续或停止。
- 回传日志、指标、用量和最终结果。
### 1.1 2026-05-28 生产联调实测结论
使用测试用户 `zsbgnw@gmail.com`（Manager 用户 `chenchen`，`user_id=22`）在生产 Manager 上实测蜂群入口。
当前生产 Manager Runtime 配置实际为：
```text
AGNET_RUNTIME_BASE_URL=http://20.212.121.126
AGNET_RUNTIME_CREATE_PATH=/api/agnet/deployments
AGNET_RUNTIME_STOP_PATH=/api/agnet/deployments/{deployment_id}/stop
```
实测结果：
| 项 | 结果 |
|---|---|
| `GET /api/agnet/runtime/health` | 通过，远端 Agent Manager IP healthy |
| `POST /api/swarms` 使用 `agent_runtime.platform=agnet-swarm` | 失败，Manager 返回 `agent_runtime.platform must be agnet when runtime context is present` |
| `POST /api/swarms` 使用 `agent_runtime.platform=agnet` | 通过 |
| Manager deployment | `dep_72cdc138b9c8` |
| Manager 返回 swarm_id | `dep_72cdc138b9c8`，当前是 Manager 本地 deployment id |
| Runtime deployment | `dep_77370f27186f` |
| Manager events | `deployment.accepted`、`runtime.sync.started`、`runtime.sync.accepted` |
| Manager stop | 通过 |
| Runtime stop | 通过，Agent Manager 侧 `dep_77370f27186f` 状态为 `stopped` |
| Runtime callback | 未观察到，生产 Manager callback 表 0 条对应记录 |
| artifact / timeline callback | 未产出 |
| SK / usage callback | 未产出 |
| Runtime logs | 仅 `Pod ... has no logs yet` |
| Runtime metrics | 返回固定 CPU/内存/网络汇总，看起来仍是占位值 |
结论：
1. Heicode Manager 的 `/api/swarms` adapter 能接收用户态蜂群请求，并能通过当前 Runtime bridge 调 Agent Manager IP。
2. 当前生产链路实际走的是 Agent Manager `/api/agnet/deployments`，不是 Agent Manager `/api/swarms`。
3. Manager stop 可以传递到 Agent Manager deployment stop。
4. 当前还没有真实蜂群 Runtime callback、task graph、artifact、SK、usage。
5. Agent Manager 如果要满足正式蜂群模式，仍需实现本文后续定义的 `/api/swarms`、`/api/swarms/{swarm_id}`、`/api/swarms/{swarm_id}/stop`、callback 和 usage 约束。
## 2. 总体调用链
```text
@@ -40,6 +79,21 @@ Heicode Desktop Client
POST /api/swarms/{swarm_id}/approvals/{approval_id}
```
客户端到 Heicode Manager 的 `POST /api/swarms` 与普通 sub 用户态接口一样，必须支持 V2 body 加密：
```http
Content-Encoding: heicode-aead-v1
X-Heicode-Device-Id: <device_id>
X-Heicode-Timestamp: <unix_ms>
X-Heicode-Nonce: <nonce_hex>
X-Heicode-Fingerprint: <device_fingerprint>
X-Heicode-Eph-Pubkey: <base64_x25519_ephemeral_pubkey>
X-Heicode-Signature: <base64_ed25519_signature>
Content-Type: application/json
```
未加密 Web 控制台请求仍按 Manager session cookie + `New-Api-User` 兼容处理。Manager 调 Agent Manager / Swarm Runtime 的服务间请求不使用该客户端 body 加密协议，而使用 `Authorization: Bearer <service_token>` 和公共追踪 Header。
## 3. Agent Manager 必须提供的接口
| 优先级 | 方法 | 路径 | 必须 | 用途 |
@@ -621,4 +675,3 @@ Runtime 可通过 `budget.alert` 或 `timeline.updated` 回传用量摘要。
9. 最终交付物回到客户端。
Manager 本地模拟事件、测试桩、空态页面和 schema 校验只能证明 Manager 接收和展示能力，不能证明蜂群生产闭环完成。
docs/integration/heicode-desktop-sub-agile-api.md
+20 -6
View File
@@ -1,6 +1,6 @@
# Heicode 桌面客户端 sub 敏捷流程 API 对接文档
更新时间：2026-05-27
更新时间：2026-05-28
适用范围：Heicode Desktop / 本地服务对接 Heicode Manager，跑通普通 sub 模式敏捷开发流程。
Manager 生产地址：`https://code.xinghanlab.com`
@@ -20,17 +20,19 @@ Manager 负责辅助控制面：任务草稿桥接、资源/权限、Agnet deplo
|---|---|---|
| `/api/heicode-auth/api/user/tasks/*` | HeicodeTask 任务编排代理，创建任务、追问、查询任务 | V2 加密 body + `Authorization: Bearer <heicode_access_token>` |
| `/api/agnet/user/*` | Manager 用户态 Agnet 控制面，deployment、timeline、artifact、审批 | V2 加密 body；未加密 Web 控制台请求继续使用 Manager session + `New-Api-User` |
| `/api/swarms` | 蜂群模式创建入口 / Runtime adapter 入口 | V2 加密 body；未加密 Web 控制台请求继续使用 Manager session + `New-Api-User` |
| `/api/user/self` | 查询当前 Manager 用户 | Manager 登录 session cookie |
### 2.2 桌面端请求 body 加密
桌面客户端调用 Manager 的 sub 流程接口时，应使用与模型调用一致的 V2 加密请求协议。生产 Manager 自 `1.4.7` 起已支持该能力。
桌面客户端调用 Manager 的 sub / 蜂群入口时，应使用与模型调用一致的 V2 加密请求协议。普通 sub 用户态接口在生产 Manager `1.4.7+` 已支持；`POST /api/swarms` 蜂群入口在本次 Manager 代码中补齐同一套 V2 body 加密鉴权，需随下一次生产部署生效。
适用接口：
| API 前缀 | V2 加密 body | 说明 |
|---|---|---|
| `/api/agnet/user/*` | 支持 | Manager 解密并校验设备签名后，按当前设备对应用户执行 |
| `/api/swarms` | 支持 | Manager 解密并校验设备签名后，按当前设备对应用户创建蜂群/Runtime adapter deployment |
| `/api/heicode-auth/*` | 支持 | Manager 解密并校验设备签名后，把明文 body 代理给上游 HeicodeTask 服务；仍需携带 `heicode_access_token` |
| 浏览器后台普通页面请求 | 兼容未加密 JSON | 不影响现有 Manager Web 控制台 |
@@ -84,7 +86,7 @@ Authorization: Bearer <heicode_access_token>
### 2.3 Manager 用户态 Header
未加密 Web 控制台请求调用 `/api/agnet/user/*` 时必须带：
未加密 Web 控制台请求调用 `/api/agnet/user/*` 或 `/api/swarms` 时必须带：
```http
Cookie: session=<manager-session>
@@ -95,9 +97,21 @@ Accept: application/json
`New-Api-User` 必须等于当前登录用户 ID，否则会返回未授权。
使用 V2 加密 body 时，`/api/agnet/user/*` 不依赖浏览器 session cookie，也不需要 `New-Api-User`；Manager 会从设备绑定 token 中解析用户身份。为兼容当前 Web 控制台，未加密请求仍按 session cookie + `New-Api-User` 处理。
使用 V2 加密 body 时，`/api/agnet/user/*` 和 `/api/swarms` 不依赖浏览器 session cookie，也不需要 `New-Api-User`；Manager 会从设备绑定 token 中解析用户身份。为兼容当前 Web 控制台，未加密请求仍按 session cookie + `New-Api-User` 处理。
### 2.4 统一响应 Envelope
### 2.4 蜂群入口加密边界
蜂群模式的业务流程与普通 sub 敏捷流程分开对接，但客户端到 Manager 的请求加密规则一致。
| 接口 | 所属模式 | 加密要求 |
|---|---|---|
| `POST /api/agnet/user/tasks/{task_id}/deployment-draft` | 普通 sub 敏捷 | V2 body 加密 |
| `POST /api/agnet/user/deployments` | 普通 sub 敏捷 | V2 body 加密 |
| `POST /api/swarms` | 蜂群模式 | V2 body 加密 |
注意：本文后续章节仍只描述普通 sub 敏捷主流程；蜂群 task graph、claim、heartbeat、handoff、approval decision 等字段以单独蜂群对接文档为准。
### 2.5 统一响应 Envelope
成功：
@@ -1221,7 +1235,7 @@ setInterval(async () => {
## 15. 当前生产注意事项
1. `https://code.xinghanlab.com` 的 Manager 用户态接口已上线，当前生产版本为 `1.4.9`。
1. `https://code.xinghanlab.com` 的 Manager 用户态接口已上线；本次蜂群入口 V2 加密修复随 Manager `1.4.10` 发布。
2. Manager 本地控制面可创建 `sub_mode=agile/waterfall` deployment。
3. 生产 Manager 已配置 Agent Manager Runtime，当前直接走 `http://20.212.121.126`；域名和 HTTPS 后续单独处理，不作为客户端当前接入阻塞项。
4. V2 加密 `deployment-draft` 已在生产验证通过：真实构造 `Content-Encoding: heicode-aead-v1` 请求返回 200，`sub_mode=agile`，`user_id=22`。