docs(integration): record 2026-06-04 end-to-end re-test against AM's updated runtime

AM shipped its updated runtime + fixes; live re-test confirms deploy → running
→ direct /health & /message/send (task completed) → stop → delete all pass, and
HM's per-agent access_token is minted + returned (non-empty UUID). Two AM-side
gaps remain: (1) the running agent does NOT enforce X-Agent-Access-Token
(no-token request still 200, agent card auth_required=None) — token isolation
not actually active; (2) subdomain is http:// (token + api_key in cleartext).
Contract §0.1 and client doc status notes updated accordingly.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
2026-06-04 23:50:09 +08:00
co-authored by Claude Opus 4.8
parent f128f4d03f
commit c171bb70ee
2 changed files with 26 additions and 15 deletions
@@ -7,7 +7,7 @@
> **本文取代旧的桌面 sub 任务编排接口文档**(描述 tasks/workflow/display_status/git_ref/产物下载的那套已下线,相关 md 已删除)。新客户端一律按本文对接。
>
> **2026-06-04 客户端流程已在生产逐接口实测**(`code.xinghanlab.com`,真实账号):capabilities / user-self / agent-templates / 部署 / 列表 / 状态 / 注销 / 删除 均返回真实数据。**唯一未通**是「直连 agent」——agent 暂停在 `Pending`、子域名外网未就绪(AM 侧在排查),HM 侧数据均真实。各响应示例下方均标注「生产实测」。
> **2026-06-04 二次复测:端到端已跑通**(`code.xinghanlab.com`,真实账号):部署→`running`→直连 `/health`/`/message/send`(带令牌任务 `completed`)→stop→delete 全通,`access_token` 为 HM 现签非空 UUID。**仅剩 AM 两项待加固**(不影响功能):① agent 端尚未真正启用令牌校验(无令牌也被放行);② 子域名目前是 `http://` 明文。详见 AM 契约 §0.1。
---
@@ -151,7 +151,7 @@ signature = base64( ed25519_sign( device_priv, sha256(canonical) ) )
> **2026-06-04 生产实测**:部署 / 列表 / 详情 / 状态 / 删除均真实可用。
> - `subdomain` 由 AM 分配(如 `dep-xxxx.taijiagnet.com`);新建后 `status` 为 `Pending`,需等 agent 起来变 `running`(直连前先确认,见 §6)。
> - **`access_token` 是 HM 现签的 per-agent 专属访问令牌**(非空,UUID)——直连 agent 时带上(`X-Agent-Access-Token` 头),agent 据此判定「是不是本 agent 的所有者」(见 §6)。
> - `stop`/`delete` 调 AM:目前 AM 的 `stop` 端点缺失、`delete` 有已知 bug,所以 `delete` 会**先清掉 HM 本地记录**并返回 `runtime_cleanup:"failed"`(AM 侧可能残留);`stop` 暂时会失败。
> - `stop`/`delete` 调 AM:**2026-06-04 复测均已通**——`stop` 返回 `status:stopped`,`delete` 返回 `runtime_cleanup:"ok"`(旧版的 404/500 已修)。`delete` 仍保留容错:即便 AM 删除失败也会清掉 HM 本地记录并以 `runtime_cleanup:"failed"` 提示。
| 方法 | 路径 | 说明 | 状态 |
|---|---|---|---|
@@ -202,7 +202,9 @@ signature = base64( ed25519_sign( device_priv, sha256(canonical) ) )
> 客户端**直接连 agent 子域名**(§5 的 `subdomain`),不经过 HM。agent 是 AM 的 `coding_a2a_agent`,走 **A2A 协议**。
> ⚠️ **连之前先确认 agent 就绪**:新建后 `status=Pending`(还在拉起)。等 `GET /api/heicode/agents/{id}/status` 变 `running`、或 `GET {subdomain}/health` 返 200 再连。**2026-06-04 实测:agent 暂时停在 Pending、子域名外网未就绪(AM 侧在排查),所以直连还连不上——HM 侧的列表/地址都是真实的。**
> ⚠️ **连之前先确认 agent 就绪**:新建后 `status=Pending`(还在拉起)。等 `GET /api/heicode/agents/{id}/status` 变 `running`、或 `GET {subdomain}/health` 返 200 再连。**2026-06-04 复测:数秒即 `running`,`/health` 200、`/message/send` 带令牌任务 `completed`,直连已通。**
>
> ⚠️ 当前 AM 侧两点(待加固,不影响调通):① **令牌校验尚未真正生效**——无 `X-Agent-Access-Token` 也被放行;客户端仍应规范地每请求都带,等 AM 开启校验即自动生效。② 子域名目前 `http://` 明文,令牌/`api_key` 会明文传输,等 AM 上 HTTPS。
- **同步**:`POST {subdomain}/message/send`
- **流式**:`POST {subdomain}/message/stream`(返回 `text/event-stream`)
@@ -292,6 +294,6 @@ signature = base64( ed25519_sign( device_priv, sha256(canonical) ) )
| `POST /api/heicode/agents/{id}/stop`、`DELETE /{id}` | 会话/设备 | 🟢(调 AM 🔴) |
| 模型 `/v1/*` | 同模型调用 | 🟢 |
| `POST /api/heicode/agent-access/verify` | 公开(令牌即凭据) | 🟢(可选兜底;接入用 ① 本地比对,默认不用此端点) |
| 直连 agent SSE(subdomain + X-Agent-Access-Token) | agent 本地比对令牌 | 🔴(待 AM agent 端) |
| 直连 agent SSE(subdomain + X-Agent-Access-Token) | agent 本地比对令牌 | 🟢 直连已通 / ⚠️ 令牌校验待 AM 开启 |
> 🔴 项不阻塞客户端集成:HM 侧字段/接口已定型并生产验证,等 AM 实现 agent 启动/状态/直连即全线打通。AM 契约见 `heicode-hm-template-agent-model.md` §7 与代码 `controller/agent_template_runtime.go`(隔离层)。
> 端到端(部署→running→直连→stop→delete)已生产验证。AM 侧仅剩两项加固:**令牌校验真正生效** + **子域名 HTTPS**(见 AM 契约 §0.1)。代码隔离层见 `controller/agent_template_runtime.go`。