docs: update desktop sub agile integration flow

docs/integration/heicode-desktop-sub-agile-api.md

@@ -74,6 +74,61 @@ Accept: application/json
 9. 完成后继续迭代或停止 deployment
 ```
 
+### 3.1 2026-05-27 生产验证结果
+
+本节记录已经按“桌面客户端应调用的顺序”在生产环境跑过的结果，客户端可按同一顺序和参数形状对接。
+
+生产环境：
+
+| 项 | 值 |
+|---|---|
+| Manager | `https://code.xinghanlab.com` |
+| Manager 版本 | `1.4.6` |
+| Agent Manager Runtime | `http://20.212.121.126` |
+| Runtime health | `healthy` |
+
+已验证成功的链路：
+
+```text
+Manager 登录
+-> /api/user/self
+-> /api/agnet/runtime/health
+-> /api/agnet/user/tasks/{task_id}/deployment-draft
+-> /api/agnet/user/deployments
+-> /api/agnet/user/deployments/{deployment_id}
+-> 直查 Agent Manager runtime deployment
+-> /api/agnet/user/deployments/{deployment_id}/metrics
+-> /api/agnet/user/deployments/{deployment_id}/events
+-> /api/agnet/user/deployments/{deployment_id}/logs
+-> /api/agnet/user/deployments/{deployment_id}/artifacts
+-> /api/agnet/user/deployments/{deployment_id}/sk-snapshots
+-> /api/agnet/user/deployments/{deployment_id}/timeline
+-> /api/agnet/user/deployments/{deployment_id}/stop
+-> 直查 Agent Manager runtime deployment 状态为 stopped
+```
+
+本次生产烟测 ID：
+
+| 对象 | ID / 结果 |
+|---|---|
+| task snapshot | `task-client-sim-1779875397` |
+| Manager deployment | `dep_40730ad87435` |
+| Runtime deployment | `dep_6747d5eeb54c` |
+| create 结果 | 200，Manager 成功保存 runtime deployment id |
+| stop 结果 | 200，Manager 和 Agent Manager 均为 `stopped` |
+
+本次未由 Codex 直接跑通的步骤：
+
+| 步骤 | 结果 | 原因 | 客户端要求 |
+|---|---|---|---|
+| `POST /api/heicode-auth/api/user/tasks/intent` | 401 | Codex 没有桌面客户端持有的 `heicode_access_token` | 客户端必须带 `Authorization: Bearer <heicode_access_token>` |
+
+说明：
+
+- 如果客户端已经有 HeicodeTask snapshot，可以直接从 `deployment-draft` 开始跑，生产已验证可通。
+- 如果客户端需要从自然语言创建任务，必须先完成 Heicode 登录并拿到 `heicode_access_token`。
+- 当前 create / detail / metrics / stop 已真实有效；events / logs / artifacts / sk-snapshots / timeline 查询接口均 200，但本次 Runtime 没有产生真实回调数据，所以列表为空。
+
 ## 4. 当前用户信息
 
 ### `GET /api/user/self`
@@ -115,6 +170,14 @@ Base: /api/heicode-auth
 
 描述用户想做什么，创建 HeicodeTask。
 
+请求头必须包含桌面客户端登录后持有的 Heicode access token：
+
+```http
+Authorization: Bearer <heicode_access_token>
+Content-Type: application/json
+Accept: application/json
+```
+
 请求：
 
 ```json
@@ -209,6 +272,12 @@ Base: /api/heicode-auth
 
 #### `POST /api/heicode-auth/api/user/tasks/{task_id}/answer`
 
+同样必须携带：
+
+```http
+Authorization: Bearer <heicode_access_token>
+```
+
 请求：
 
 ```json
@@ -254,6 +323,8 @@ Base: /api/heicode-auth
 
 把 HeicodeTask 快照转换成 Manager 可创建的 Agnet orchestration plan。
 
+生产已验证：客户端只要能提供 task snapshot，就可以不依赖 Manager 再去拉 task，直接调用本接口生成 draft。
+
 请求：
 
 ```json
@@ -282,6 +353,50 @@ Base: /api/heicode-auth
 }
 ```
 
+生产烟测可用的最小请求形状：
+
+```json
+{
+  "task": {
+    "id": "task-client-sim-1779875397",
+    "name": "客户端模拟普通 sub 敏捷流程",
+    "intent": "做一个轻量待办系统，包含任务列表、状态流转、基础测试和上线说明",
+    "status": "running",
+    "card": {
+      "goal": "交付轻量待办系统 MVP",
+      "scope": "普通 sub 敏捷流程接口联调",
+      "generated_artifacts": []
+    }
+  },
+  "sub_mode": "agile",
+  "risk_level": "low",
+  "budget": {
+    "max_tokens": 20000,
+    "max_cost_usd": 1,
+    "max_duration_sec": 600
+  },
+  "binding_scope": "task-client-sim",
+  "role_templates": ["backend"],
+  "default_model_id": "smoke-model",
+  "resource_grants": [
+    {
+      "grant_id": "grant-client-sim-git",
+      "resource_id": "git-client-sim",
+      "resource_type": "git",
+      "binding_scope": "task-client-sim",
+      "target_role": "backend",
+      "target_agent_ref": "agent-backend-1",
+      "permission_scope": ["repo:read"],
+      "metadata": {
+        "repo_url": "https://example.invalid/heicode/client-sim.git"
+      },
+      "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/client-sim-git",
+      "status": "active"
+    }
+  ]
+}
+```
+
 字段：
 
 | 字段 | 类型 | 必需 | 说明 |
@@ -952,6 +1067,10 @@ const userId = self.data.id
 
 const task = await mcp.post('/api/heicode-auth/api/user/tasks/intent', {
   intent: userInput,
+}, {
+  headers: {
+    Authorization: `Bearer ${heicodeAccessToken}`,
+  },
 })
 
 let current = task.data
@@ -1006,5 +1125,7 @@ setInterval(async () => {
 
 1. `https://code.xinghanlab.com` 的 Manager 用户态接口已上线。
 2. Manager 本地控制面可创建 `sub_mode=agile/waterfall` deployment。
-3. 当前外部 Agnet Runtime 如未配置，`runtime_state` 会停留在本地队列/占位状态，真实执行、日志、指标和 artifact 需要 Runtime 接入后产生。
-4. 桌面端可以先按本文完整接入 Manager 流程；真实 Runtime 接入后，timeline/artifacts/sk-snapshots 会自然出现更多回传数据。
+3. 生产 Manager 已配置 Agent Manager Runtime，当前直接走 `http://20.212.121.126`；域名和 HTTPS 后续单独处理，不作为客户端当前接入阻塞项。
+4. `deployment-draft -> create -> detail -> stop` 已在生产验证通过，客户端可按本文参数形状接入。
+5. `events/logs/artifacts/sk-snapshots/timeline` 查询接口已验证不报错；真实阶段事件、产物、SK 调用结果需要 Agent Manager 执行任务并回调后才会出现。
+6. `POST /api/heicode-auth/api/user/tasks/intent` 需要桌面客户端提供 `heicode_access_token`；没有该 token 会返回 401。