docs: update desktop sub agile integration guide

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

@@ -4,6 +4,35 @@
 适用范围：Heicode Desktop / 本地服务对接 Heicode Manager，跑通普通 sub 模式敏捷开发流程。
 Manager 生产地址：`https://code.xinghanlab.com`
 
+## 0. 当前生产联调结论
+
+截至 2026-05-30，普通 sub 敏捷链路已按生产地址完成端到端联调：
+
+| 项目 | 状态 | 生产验证 |
+|---|---|---|
+| Manager 创建 deployment | 已通过 | `POST /api/agnet/user/deployments` 返回 `accepted` |
+| Agent Manager Runtime 执行 | 已通过 | Runtime 返回 `completed`，Agent 返回 `completed` |
+| 模型调用 | 已通过 | 使用生产 NewAPI 已存在模型 `claude-sonnet-4-6`，渠道日志显示调用成功 |
+| Callback / timeline | 已通过 | Manager 可查询 Runtime timeline 和状态 |
+| Artifact 列表 | 已通过 | `GET /artifacts` 返回业务交付 artifact |
+| Artifact 完整内容下载 | 已通过 | `GET /artifacts/{artifact_id}/content` 返回 `HTTP 200` 和完整文本内容 |
+
+本次真实生产烟测记录：
+
+| 字段 | 值 |
+|---|---|
+| `deployment_id` | `dep_829dd2da7494` |
+| `runtime_swarm_id` | `swm_0a2b712b0023` |
+| `artifact_id` | `art_swm_0a2b712b0023_fullstack_1` |
+| artifact content | `HTTP 200`，`text/plain; charset=utf-8`，`2436 bytes` |
+
+重要修正：
+
+1. 桌面客户端不要再使用 `agnet-model-builder`、`agnet-model-reviewer`、`agnet-model-product` 这类占位模型名。生产 NewAPI 没有这些模型，会返回 `No available channel for model ...`。
+2. 普通 sub 默认模型建议使用 `claude-sonnet-4-6`；审核类角色可使用 `claude-opus-4-7`。这两个模型当前生产 NewAPI 已有可用渠道。
+3. `orchestration_plan.metadata.correlation_id` 是创建 deployment 的必填字段，必须放在 `orchestration_plan` 内，不是顶层 `metadata`。
+4. `runtime-diagnostics.warnings` 目前可能包含 `runtime_zero_model_usage`，表示 Runtime 还没有完整回传 usage/token 统计；不影响任务执行和 artifact 获取，但计费统计展示应标记为“等待 Runtime usage 回传”。
+
 ## 1. 对接目标
 
 桌面客户端负责用户主体验：输入想法、回答追问、持续推进任务、查看子环节反馈、处理高危审批、接收交付结果。
@@ -545,7 +574,7 @@ Authorization: Bearer <heicode_access_token>
   },
   "binding_scope": "task-client-sim",
   "role_templates": ["backend"],
-  "default_model_id": "smoke-model",
+  "default_model_id": "claude-sonnet-4-6",
   "resource_grants": [
     {
       "grant_id": "grant-client-sim-git",
@@ -576,7 +605,7 @@ Authorization: Bearer <heicode_access_token>
 | `sub_mode` | string | 是 | `agile` 或 `waterfall`，桌面客户端默认传 `agile` |
 | `binding_scope` | string | 否 | 建议 `task-<task_id>` |
 | `role_templates` | string[] | 否 | 默认 `["backend"]` |
-| `default_model_id` | string | 否 | 子 Agnet 默认运行模型 |
+| `default_model_id` | string | 否 | 子 Agnet 默认运行模型；生产默认建议 `claude-sonnet-4-6` |
 | `budget` | object | 否 | 不传使用默认预算 |
 | `resource_grants` | array | 否 | 不传时 Manager 生成只读 task context grant |
 
@@ -642,6 +671,13 @@ Authorization: Bearer <heicode_access_token>
 
 使用上一步 `orchestration_plan` 创建 Manager deployment。
 
+必填注意：
+
+- `metadata.correlation_id` 必须在 `orchestration_plan.metadata` 内。
+- 如果客户端绕过 draft 接口直接创建 deployment，也必须自行生成该字段，例如 `task-<task_id>-<timestamp>`。
+- 不要把 `metadata` 放在请求顶层；顶层 metadata 不会满足创建校验。
+- `billing_context.default_model_id`、`agents[].default_model_id`、`constraints.allowed_model_ids` 必须使用生产 NewAPI 已存在模型。
+
 请求：
 
 ```json
@@ -734,6 +770,50 @@ Authorization: Bearer <heicode_access_token>
 - `runtime_state=queued` 表示 Manager 已建立本地控制面记录。
 - 如果生产 Runtime 未配置，deployment 仍可创建，但不会进入真实执行。
 
+直接创建的最小可用生产示例：
+
+```json
+{
+  "orchestration_plan": {
+    "intent_id": "task-prod-smoke",
+    "template_hint": "heicode-task",
+    "objective": "生成一个极简 hello world 网站交付说明，返回 artifact。",
+    "sub_mode": "agile",
+    "risk_level": "low",
+    "budget": {
+      "max_tokens": 20000,
+      "max_cost_usd": 0.5,
+      "max_duration_sec": 900
+    },
+    "user_context": {
+      "user_id": "22",
+      "channel_id": "heicode",
+      "binding_scope": "task-prod-smoke"
+    },
+    "billing_context": {
+      "provider": "newapi",
+      "default_model_id": "claude-sonnet-4-6",
+      "allowed_model_ids": ["claude-sonnet-4-6"],
+      "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/model-gateway-key"
+    },
+    "agents": [
+      {
+        "role_template": "fullstack",
+        "goal": "生成 hello world 网站交付说明 artifact。",
+        "default_model_id": "claude-sonnet-4-6",
+        "resource_grants": []
+      }
+    ],
+    "constraints": {
+      "allowed_model_ids": ["claude-sonnet-4-6"]
+    },
+    "metadata": {
+      "correlation_id": "prod-smoke-<timestamp>"
+    }
+  }
+}
+```
+
 ## 8. 查询 Deployment
 
 ### 8.1 列表
@@ -1316,6 +1396,34 @@ setInterval(async () => {
   )
   renderApprovals(approvals.data.items)
 }, 5000)
+
+async function refreshSubDelivery(deploymentId: string) {
+  const diagnostics = await manager.get<Envelope<RuntimeDiagnostics>>(
+    `/api/agnet/user/deployments/${deploymentId}/runtime-diagnostics`,
+    { headers: { 'New-Api-User': String(userId) } }
+  )
+  renderRuntimeDiagnostics(diagnostics.data)
+
+  const artifacts = await manager.get<Envelope<ArtifactList>>(
+    `/api/agnet/user/deployments/${deploymentId}/artifacts`,
+    { headers: { 'New-Api-User': String(userId) } }
+  )
+  renderArtifacts(artifacts.data.artifacts)
+
+  const firstDeliverable = artifacts.data.artifacts.find(
+    (item) => item.artifact_type !== 'log_bundle'
+  )
+  if (firstDeliverable) {
+    const content = await manager.get<string>(
+      `/api/agnet/user/deployments/${deploymentId}/artifacts/${firstDeliverable.artifact_id}/content`,
+      {
+        headers: { 'New-Api-User': String(userId) },
+        responseType: 'text',
+      }
+    )
+    renderArtifactContent(content.data)
+  }
+}
 ```
 
 兼容说明：