docs(integration): update client API doc to production-verified reality

Ran the full desktop-client flow against production (real account) and updated
the doc to the verified responses:
- capabilities model = gpt-5.4; modes still returned but ignored.
- agent object: access_token is "" (AM issues none — connect via A2A api_key),
  subdomain is a host (dep-xxx.taijiagnet.com), status starts Pending; real
  binding_ids; shown as "生产实测" examples.
- §4: clarified the template `model` field is a role-tier hint (opus), not the
  runtime model (gpt-5.4 injected at deploy).
- §5: stop currently fails / delete returns runtime_cleanup:"failed" (AM stop
  missing + delete bug); HM removes the local record regardless.
- §6: must wait for status=running / health 200 before connecting; noted the
  agent currently stays Pending and the subdomain isn't reachable yet (AM side).
- top banner: per-endpoint production verification note.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

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

@@ -6,6 +6,8 @@
 > 状态图例：🟢 已实现并生产验证 · 🔴 待建（依赖 AM）
 
 > **本文取代旧的桌面 sub 任务编排接口文档**（描述 tasks/workflow/display_status/git_ref/产物下载的那套已下线，相关 md 已删除）。新客户端一律按本文对接。
+>
+> **2026-06-04 客户端流程已在生产逐接口实测**(`code.xinghanlab.com`,真实账号):capabilities / user-self / agent-templates / 部署 / 列表 / 状态 / 注销 / 删除 均返回真实数据。**唯一未通**是「直连 agent」——agent 暂停在 `Pending`、子域名外网未就绪(AM 侧在排查),HM 侧数据均真实。各响应示例下方均标注「生产实测」。
 
 ---
 
@@ -112,10 +114,11 @@ signature = base64( ed25519_sign( device_priv, sha256(canonical) ) )
 | GET | `/api/heicode/capabilities` | 模型目录(渲染模型选择);免登录 |
 
 ```json
+// 生产实测:models = [{"id":"gpt-5.4",...}]（modes 仍返回 sub_agile/swarm，客户端忽略即可）
 { "success": true, "data": { "models": [{"id":"gpt-5.4","name":"gpt-5.4","available":true}] }}
 ```
 
-> 旧的 `modes`(sub_agile/swarm 任务模式)在新模型已无意义,客户端只需 `models`。
+> 客户端只需 `models`(当前可用 `gpt-5.4`);`modes` 是旧任务模式,新模型已无意义。
 
 ---
 
@@ -139,12 +142,16 @@ signature = base64( ed25519_sign( device_priv, sha256(canonical) ) )
 
 - `template_id` 是模板的稳定 key(如 `architect`),部署时回传。
 - `name` / `description` 为中文,直接展示。
+- `model` 是模板的**角色层级提示**(如 `opus`),**不是实际跑的模型**——agent 实际用网关模型 `gpt-5.4`(部署时 HM 注入)。客户端不用管这个字段。
 
 ---
 
-## 5. 我的 Agent 🟢（部署调用 AM，AM 接口待建）
+## 5. 我的 Agent 🟢（已对接 AM，生产验证）
 
-> ⚠️ `subdomain` / `access_token` 来自 AM。当前 AM 的启动/状态接口尚未实现(🔴),`POST /agents` 会返回 `RUNTIME_UNAVAILABLE`;HM 侧逻辑已就绪并生产验证,AM 一上线即通。
+> **2026-06-04 生产实测**:部署 / 列表 / 详情 / 状态 / 删除均真实可用。
+> - `subdomain` 由 AM 分配(如 `dep-xxxx.taijiagnet.com`);新建后 `status` 为 `Pending`,需等 agent 起来变 `running`(直连前先确认,见 §6)。
+> - **`access_token` 当前恒为空字符串**——AM 的 coding_a2a_agent **不发专属令牌**,直连用 A2A 的 `api_key`(见 §6)。
+> - `stop`/`delete` 调 AM:目前 AM 的 `stop` 端点缺失、`delete` 有已知 bug,所以 `delete` 会**先清掉 HM 本地记录**并返回 `runtime_cleanup:"failed"`(AM 侧可能残留);`stop` 暂时会失败。
 
 | 方法 | 路径 | 说明 | 状态 |
 |---|---|---|---|
@@ -158,18 +165,19 @@ signature = base64( ed25519_sign( device_priv, sha256(canonical) ) )
 **列表 / 详情 / 部署成功 返回的 agent 对象:**
 
 ```json
+// 生产实测响应(GET /api/heicode/agents 的一项 / 部署成功返回)
 { "success": true, "data": {
   "items": [
     {
-      "agent_id": "dep_b5fab27e9255",     // HM 侧 agent 记录 id
+      "agent_id": "dep_4bb07dc1e376",            // HM 侧 agent 记录 id（部署/停删都用它）
-      "template_id": "architect",          // 用了哪个模板
+      "template_id": "architect",                 // 用了哪个模板
-      "subdomain": "https://xxxx.agents.example",  // ★ 直连地址(AM 分配)
+      "subdomain": "dep-4bb07dc1e376.taijiagnet.com",  // ★ 直连地址(AM 分配，主机名)
-      "access_token": "…",                 // ★ 连 agent 用的 token
+      "access_token": "",                         // 当前恒空(AM 不发；直连用 A2A api_key)
-      "binding_ids": [16],                 // 挂了哪些资源绑定
+      "binding_ids": [],                          // 挂了哪些资源绑定(网页台绑的)
-      "status": "running",                 // running | stopped | failed | …
+      "status": "Pending",                        // Pending | running | failed | stopped …
-      "runtime_id": "rt_…",                // AM 侧运行时 id
+      "runtime_id": "dep-4bb07dc1e376",           // AM 侧运行时 id
-      "created_at": "2026-06-04T…",
+      "created_at": "2026-06-04T09:04:15Z",
-      "updated_at": "2026-06-04T…"
+      "updated_at": "2026-06-04T09:04:15Z"
     }
   ],
   "total": 1
@@ -178,10 +186,10 @@ signature = base64( ed25519_sign( device_priv, sha256(canonical) ) )
 
 **部署请求** `POST /api/heicode/agents`:
 ```json
-{ "template_id": "architect", "binding_ids": [16] }
+{ "template_id": "architect", "binding_ids": [17] }
 ```
 - `binding_ids` 是网页台「资源绑定」里已绑资源的 id(可空数组,表示不挂资源)。
-- HM 处理:加载模板 `.md` → 把所选资源按类型解成 env(非密配置 + 从 Key Vault 解出的密钥)→ 连同模板定义交 AM 启动 → 存 `{subdomain, access_token}` 返回。
+- HM 处理:加载模板 `.md` → 把所选资源按类型解成 env(非密配置 + KV 解出密钥)+ 注入模型环境(`OPENAI_BASE_URL`/`OPENAI_API_KEY`/`MODEL_NAME=gpt-5.4`)→ 交 AM 启动 → 存子域名返回。
 
 **状态查询** `GET /api/heicode/agents/{id}/status`:
 ```json
@@ -194,6 +202,8 @@ 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 侧的列表/地址都是真实的。**
+
 - **同步**:`POST {subdomain}/message/send`
 - **流式**:`POST {subdomain}/message/stream`(返回 `text/event-stream`)
 - **发现/健康**:`GET {subdomain}/.well-known/agent.json`、`GET {subdomain}/health`