docs: add agent manager sub integration requirements

docs/integration/AgentManager普通sub联调整改要求.md

@@ -0,0 +1,636 @@
+# Agent Manager 普通 sub 联调整改要求
+
+更新时间：2026-05-28
+发给：Agent Manager / Agnet Runtime 负责人
+范围：Heicode Manager 普通 sub 敏捷模式联调，不包含蜂群模式完整 task graph 的额外能力。
+
+## 1. 当前结论
+
+Agent Manager 新版文档 `HEICODE_API_INTEGRATION(5).md` 已经补充了 Runtime 主动 callback、HMAC、artifact、timeline、SK snapshot 等内容，方向基本对齐 Heicode Manager。
+
+但按 2026-05-28 实测结果，目前还不能认为普通 sub 敏捷模式已经完整闭环。主要问题是：
+
+1. Agent Manager 当前联调统一使用 IP `http://20.212.121.126`；域名 `https://agent-manager.taijiagnet.com` 后续解析和证书就绪后再切换，不作为当前联调阻塞项。
+2. `POST /api/swarms` 会在极简 body 或 `dry_run:true` 情况下创建真实 swarm，缺少参数校验和 dry-run 保护。
+3. `/api/swarms` 返回的 `swarm_id` 当前无法通过 `/api/swarms/{swarm_id}` 查询，也无法通过 `/api/swarms/{swarm_id}/stop` 停止。
+4. `/api/agnet/deployments/{swarm_id}/stop` 也无法停止 `/api/swarms` 创建出的 swarm，返回 `DEPLOYMENT_NOT_FOUND`。
+5. 文档写了 callback 重试和死信，但同时又写“发送失败只 warning”，需要明确当前真实实现。
+6. 文档还缺少 Agent 运行 usage / cost 回传字段，后续无法做 NewAPI / Manager 账单归属和审计。
+
+Heicode Manager 侧已确认：
+
+- `POST https://code.xinghanlab.com/api/agnet/callbacks/swarm-events` 生产路由在线。
+- callback 使用 `X-Agnet-Service-Token` 认证可以进入业务校验。
+- 不带认证会返回 `CALLBACK_UNAUTHORIZED`。
+- 带认证但缺少事件字段会返回 `CALLBACK_INVALID`。
+- `GET https://code.xinghanlab.com/api/agnet/callbacks/swarm-events/schema` 当前生产返回 404，Manager 会单独复核上线/路由；Agent Manager 不应依赖这个接口才能推送 callback。
+
+## 2. Agent Manager 必须整改的 P0
+
+| 优先级 | 事项 | 当前问题 | 要求 |
+|---|---|---|---|
+| P0 | 固定联调地址 | 当前阶段约定先走 IP，后续再切域名 | 文档和配置先统一使用 `http://20.212.121.126`；域名切换另行确认 |
+| P0 | `/api/swarms` 参数校验 | 极简 body / `dry_run:true` 也创建真实 swarm | 无有效 `orchestration_plan`、`callback.url`、`sub_mode` 时返回 4xx；支持 `dry_run` 则不能创建真实资源，不支持则返回 422 |
+| P0 | 返回可操作 ID | `/api/swarms` 只返回 `swarm_id`，但 stop/detail 不认这个 ID | 创建响应必须返回 `deployment_id` 和 `swarm_id`，且至少一个 ID 可用于查询和停止 |
+| P0 | Swarm detail | `/api/swarms/{swarm_id}` 当前 404 | 实现详情接口，返回当前状态、agents、phase、created_at、updated_at |
+| P0 | Swarm stop | `/api/swarms/{swarm_id}/stop` 当前 404 | 实现停止接口，保证 Manager 停止任务时 Runtime 真实停止 |
+| P0 | callback 主动推送 | 文档说已支持，但还没完成 Manager 端真实闭环验证 | 创建 Runtime run 后主动向 Manager 推送 phase/timeline/artifact/tool/status callback |
+| P0 | usage 回传 | 缺少真实 usage / cost 字段 | 通过 callback 或事件接口回传 token、成本、运行时长、资源使用 |
+
+## 3. 推荐接口契约
+
+### 3.1 健康检查
+
+```http
+GET /api/agnet/health
+```
+
+要求：
+
+- 不要求业务认证。
+- 返回 200。
+- 响应中包含 `success=true` 和 `data.status=healthy`。
+
+### 3.2 创建普通 sub 运行
+
+Heicode Manager 可以配置 Runtime create path 为 `/api/swarms` 或 `/api/agnet/deployments`。如果 Agent Manager 推荐 `/api/swarms`，则必须支持下面契约。
+
+```http
+POST /api/swarms
+Authorization: Bearer <HEICODE_SERVICE_TOKEN>
+Content-Type: application/json
+X-User-ID: <user_id>
+X-Binding-Scope: <binding_scope>
+X-Correlation-ID: <correlation_id>
+X-Idempotency-Key: <idempotency_key>
+```
+
+请求体示例：
+
+```json
+{
+  "orchestration_plan": {
+    "intent_id": "task_123",
+    "template_hint": "heicode-task",
+    "objective": "完成本轮普通 sub 敏捷任务",
+    "sub_mode": "agile",
+    "risk_level": "medium",
+    "budget": {
+      "max_tokens": 120000,
+      "max_cost_usd": 8,
+      "max_duration_sec": 3600
+    },
+    "user_context": {
+      "user_id": "123",
+      "channel_id": "heicode",
+      "binding_scope": "task-task-123"
+    },
+    "billing_context": {
+      "provider": "newapi",
+      "default_model_id": "model_xxx",
+      "allowed_model_ids": ["model_xxx"],
+      "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/model-gateway-key"
+    },
+    "agile_context": {
+      "iteration": "2026-05-28",
+      "stage": "development",
+      "checkpoint": "draft_created",
+      "acceptance_criteria": [
+        "Runtime 接收创建请求",
+        "Runtime 主动回调 phase/timeline/artifact",
+        "Manager 页面和接口可查到回调数据",
+        "不出现明文密钥"
+      ],
+      "next_action": "continue",
+      "requires_user_approval": false
+    },
+    "agents": [
+      {
+        "role": "backend"
+      },
+      {
+        "role": "frontend"
+      },
+      {
+        "role": "reviewer"
+      }
+    ],
+    "resource_grants": []
+  },
+  "callback": {
+    "url": "https://code.xinghanlab.com/api/agnet/callbacks/swarm-events",
+    "signing_secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/agnet-callback-signing-key",
+    "subscribed_events": [
+      "deployment.status_changed",
+      "phase.changed",
+      "timeline.updated",
+      "agent.started",
+      "agent.completed",
+      "sk_tool.called",
+      "sk_tool.completed",
+      "sk_tool.failed",
+      "approval.requested",
+      "budget.alert",
+      "artifact.created"
+    ]
+  }
+}
+```
+
+成功响应必须包含：
+
+```json
+{
+  "deployment_id": "dep_runtime_123",
+  "swarm_id": "swm_runtime_123",
+  "status": "initializing",
+  "agents": [
+    {
+      "agent_id": "agi_backend_001",
+      "role": "backend",
+      "status": "pending"
+    }
+  ],
+  "created_at": "2026-05-28T07:30:00Z",
+  "estimated_ready_at": "2026-05-28T07:32:00Z"
+}
+```
+
+要求：
+
+1. `deployment_id` 必须可用于 `/api/agnet/deployments/{deployment_id}`、`/api/agnet/deployments/{deployment_id}/stop`。
+2. `swarm_id` 必须可用于 `/api/swarms/{swarm_id}`、`/api/swarms/{swarm_id}/stop`。
+3. 如果只保留一种 ID，必须在文档中明确 Manager 应该配置哪个 stop path。
+4. 同一个 `X-Idempotency-Key` 重复请求必须返回同一个运行，不应重复创建。
+5. 请求缺少 `orchestration_plan`、`callback.url`、`sub_mode`、`user_context` 时必须返回 4xx。
+6. 不支持 `dry_run` 时，包含 `dry_run:true` 的请求必须返回 422，不能创建真实运行。
+
+### 3.3 查询 Swarm
+
+```http
+GET /api/swarms/{swarm_id}
+Authorization: Bearer <HEICODE_SERVICE_TOKEN>
+```
+
+响应示例：
+
+```json
+{
+  "swarm_id": "swm_runtime_123",
+  "deployment_id": "dep_runtime_123",
+  "status": "running",
+  "phase": "development",
+  "agents": [
+    {
+      "agent_id": "agi_backend_001",
+      "role": "backend",
+      "status": "running",
+      "current_task": "实现接口"
+    }
+  ],
+  "created_at": "2026-05-28T07:30:00Z",
+  "updated_at": "2026-05-28T07:31:00Z"
+}
+```
+
+### 3.4 停止 Swarm
+
+```http
+POST /api/swarms/{swarm_id}/stop
+Authorization: Bearer <HEICODE_SERVICE_TOKEN>
+Content-Type: application/json
+```
+
+请求体：
+
+```json
+{
+  "reason": "Heicode Manager requested stop",
+  "manager_deployment_id": "dep_manager_123"
+}
+```
+
+响应示例：
+
+```json
+{
+  "swarm_id": "swm_runtime_123",
+  "deployment_id": "dep_runtime_123",
+  "status": "stopped",
+  "stopped_at": "2026-05-28T07:40:00Z"
+}
+```
+
+要求：
+
+- 停止后不再继续执行任务。
+- 停止后可以继续查询状态。
+- 停止成功后建议 callback 一条 `deployment.status_changed`，状态为 `stopped`。
+
+### 3.5 停止 Deployment
+
+如果 Agent Manager 选择 `/api/agnet/deployments/{deployment_id}/stop` 作为主停止接口，也必须保证 `/api/swarms` 创建响应里的 `deployment_id` 能用于这个接口。
+
+```http
+POST /api/agnet/deployments/{deployment_id}/stop
+```
+
+当前实测问题：使用 `/api/swarms` 返回的 `swarm_id` 调该接口返回 `DEPLOYMENT_NOT_FOUND`。需要修复 ID 映射或在响应中返回真实 `deployment_id`。
+
+## 4. Callback 要求
+
+Manager 生产 callback 地址：
+
+```text
+https://code.xinghanlab.com/api/agnet/callbacks/swarm-events
+```
+
+### 4.1 认证方式
+
+优先使用 HMAC：
+
+```http
+X-Agnet-Event-Id: evt_xxx
+X-Agnet-Timestamp: <unix_ms>
+X-Agnet-Signature: sha256=<hex>
+X-Correlation-ID: <correlation_id>
+Content-Type: application/json
+```
+
+签名规则：
+
+```text
+signature_payload = timestamp + "." + event_id + "." + raw_body
+signature = HMAC_SHA256(callback_signing_secret, signature_payload)
+```
+
+过渡期可使用旧 token：
+
+```http
+X-Agnet-Service-Token: <HEICODE_SERVICE_TOKEN>
+```
+
+不要把真实 token 写入文档、日志或 artifact。
+
+### 4.2 必须回调的事件
+
+普通 sub 最少需要以下事件：
+
+| 事件 | 目的 | 最低要求 |
+|---|---|---|
+| `deployment.status_changed` | 整体运行状态 | `status`、`stage`、`checkpoint` |
+| `phase.changed` | 普通 sub 阶段推进 | `stage`、`checkpoint`、`progress_pct` |
+| `timeline.updated` | 客户端可展示反馈 | `title`、`summary`、`stage`、`checkpoint` |
+| `agent.started` | Agent 开始工作 | `agent_role`、`task_id` |
+| `sk_tool.called` | 工具调用开始 | `tool_name`、脱敏参数摘要 |
+| `sk_tool.completed` | 工具调用成功 | `tool_name`、耗时、摘要、可选 artifact 引用 |
+| `sk_tool.failed` | 工具调用失败 | `tool_name`、脱敏错误 |
+| `artifact.created` | 中间/最终产物 | `artifact_id`、`artifact_type`、`title`、`summary`、`uri` |
+| `approval.requested` | 高危操作审批 | `operation`、`resource_type`、`risk_level`、`reason` |
+| `budget.alert` | 预算告警/用量 | usage / cost 摘要 |
+
+### 4.3 Callback body 示例
+
+```json
+{
+  "event_id": "evt_phase_001",
+  "event_type": "phase.changed",
+  "deployment_id": "dep_manager_123",
+  "swarm_id": "swm_runtime_123",
+  "agent_instance_id": "agi_backend_001",
+  "occurred_at": "2026-05-28T07:35:00Z",
+  "correlation_id": "corr_123",
+  "source": "agent-manager",
+  "payload": {
+    "stage": "development",
+    "checkpoint": "agent_running",
+    "progress_pct": 35,
+    "summary": "backend agent 已开始实现接口"
+  }
+}
+```
+
+artifact 示例：
+
+```json
+{
+  "event_id": "evt_artifact_001",
+  "event_type": "artifact.created",
+  "deployment_id": "dep_manager_123",
+  "swarm_id": "swm_runtime_123",
+  "agent_instance_id": "agi_backend_001",
+  "occurred_at": "2026-05-28T07:38:00Z",
+  "correlation_id": "corr_123",
+  "source": "agent-manager",
+  "payload": {
+    "artifact_id": "art_backend_patch_001",
+    "artifact_type": "code_patch",
+    "title": "Backend API patch",
+    "summary": "新增普通 sub Runtime 联调接口",
+    "uri": "azblob://heicode-artifacts/task-123/backend.patch",
+    "mime_type": "text/x-diff",
+    "size_bytes": 18420,
+    "stage": "development",
+    "checkpoint": "artifact_ready",
+    "metadata": {
+      "agent_role": "backend",
+      "redacted": true
+    }
+  }
+}
+```
+
+### 4.4 明文密钥禁止项
+
+以下字段不能出现在 callback、artifact metadata、timeline、日志中：
+
+- `password`
+- `token`
+- `secret`
+- `private_key`
+- `connection_string`
+- `access_key`
+- 明文数据库连接串
+- 明文模型网关 key
+- 明文 Git token
+
+长期凭据只能传：
+
+```text
+azkv://<vault>/secrets/<name>
+```
+
+## 5. Usage / Cost 回传要求
+
+Agent Manager 文档当前缺少真实 usage 字段。普通 sub 后续要支持模型费用、运行费用和审计归属，Runtime 必须回传至少以下字段。
+
+可通过 `budget.alert`、`timeline.updated` 或专门的 `usage.updated` 事件回传。如果新增 `usage.updated`，需要提前和 Manager 对齐 schema。
+
+```json
+{
+  "event_id": "evt_usage_001",
+  "event_type": "budget.alert",
+  "deployment_id": "dep_manager_123",
+  "swarm_id": "swm_runtime_123",
+  "agent_instance_id": "agi_backend_001",
+  "occurred_at": "2026-05-28T07:39:00Z",
+  "correlation_id": "corr_123",
+  "source": "agent-manager",
+  "payload": {
+    "model_id": "model_xxx",
+    "model_tokens": 12000,
+    "prompt_tokens": 8000,
+    "completion_tokens": 4000,
+    "model_cost_usd": 0.23,
+    "runtime_seconds": 180,
+    "cpu_core_seconds": 36,
+    "memory_mb_seconds": 92160,
+    "billing_source": "newapi",
+    "budget": {
+      "max_tokens": 120000,
+      "max_cost_usd": 8,
+      "consumed_usd": 0.23,
+      "remaining_usd": 7.77
+    }
+  }
+}
+```
+
+字段要求：
+
+| 字段 | 必需 | 说明 |
+|---|---|---|
+| `model_id` | 是 | 本次 Agent 调用的模型 |
+| `model_tokens` | 是 | 总 token |
+| `prompt_tokens` | 建议 | 输入 token |
+| `completion_tokens` | 建议 | 输出 token |
+| `model_cost_usd` | 是 | 可归属的模型成本 |
+| `runtime_seconds` | 是 | Agent 实际运行秒数 |
+| `cpu_core_seconds` | 建议 | 集群资源成本核算 |
+| `memory_mb_seconds` | 建议 | 集群资源成本核算 |
+| `billing_source` | 是 | `newapi` / `manager_wallet` / `manager_subscription` / 其他约定 |
+
+注意：`budget.max_cost_usd` 是预算上限，不是已扣费金额。不能把预算当真实账单。
+
+## 6. Approval Decision 接收要求
+
+Manager 端已有 approval、credential lease、approve/reject 和 Runtime decision adapter。Agent Manager 需要提供接收审批结果的接口。
+
+推荐接口：
+
+```http
+POST /api/swarms/{swarm_id}/approvals/{approval_id}
+Authorization: Bearer <HEICODE_SERVICE_TOKEN>
+Content-Type: application/json
+```
+
+请求体：
+
+```json
+{
+  "approval_id": "apr_123",
+  "decision": "approved",
+  "manager_deployment_id": "dep_manager_123",
+  "runtime_deployment_id": "dep_runtime_123",
+  "swarm_id": "swm_runtime_123",
+  "operation": "git.write",
+  "resource_type": "git",
+  "resource_id": "repo_main",
+  "risk_level": "high",
+  "requires_credential": true,
+  "credential_ref": "lease://agnet/cred_123",
+  "lease_id": "lease_123",
+  "lease_expires_at": 1770000000000,
+  "decided_by": "user_123",
+  "reason": "允许本次写入",
+  "decided_at": 1770000000000
+}
+```
+
+要求：
+
+- `approved` 后 Runtime 继续对应高危动作。
+- `rejected` 后 Runtime 停止该动作并回调 `timeline.updated` 或 `sk_tool.failed`。
+- 不要求 Manager 回传明文密钥，只能使用 `credential_ref` 或 `lease://...`。
+
+## 7. Callback 重试策略需要说清楚
+
+Agent Manager 文档当前有两种说法：
+
+1. 当前发送失败只记录 warning，不阻塞任务执行。
+2. Runtime 推送失败时指数退避，最多重试 12 小时，超过进入死信队列。
+
+请明确当前真实实现是哪一种：
+
+| 能力 | 当前是否已实现 | 需要说明 |
+|---|---|---|
+| 失败重试 | 是/否 | 重试次数、间隔、最大时长 |
+| 死信队列 | 是/否 | 存储位置、人工重放方式 |
+| 幂等重放 | 是/否 | 是否复用原 `event_id` |
+| 失败告警 | 是/否 | 是否有日志、监控或告警 |
+
+如果当前只 warning，不重试，请在文档中写成“当前未实现重试/死信，后续增强”，不要把建议方案写成已完成。
+
+## 8. 联调验收步骤
+
+Agent Manager 改完后，按下面步骤验收。
+
+| 步骤 | 操作 | 通过标准 |
+|---:|---|---|
+| 1 | `GET /api/agnet/health` | 返回 healthy |
+| 2 | `POST /api/swarms` 创建普通 sub run | 返回 `deployment_id`、`swarm_id`、`status` |
+| 3 | 重复同一个 `X-Idempotency-Key` 创建 | 不重复创建，返回同一个 ID |
+| 4 | `GET /api/swarms/{swarm_id}` | 返回真实状态和 agents |
+| 5 | Runtime 主动 callback `phase.changed` | Manager callback 返回 success |
+| 6 | Runtime 主动 callback `timeline.updated` | Manager timeline 可查到 |
+| 7 | Runtime 主动 callback `artifact.created` | Manager artifacts 可查到 |
+| 8 | Runtime 主动 callback `sk_tool.completed` | Manager SK/timeline 可查到 |
+| 9 | Runtime 主动 callback usage | Manager 能看到 usage 摘要或 callback event |
+| 10 | Runtime 主动 callback `approval.requested` | Manager pending approval 生成 |
+| 11 | Manager approve/reject | Agent Manager 收到 decision |
+| 12 | `POST /api/swarms/{swarm_id}/stop` | Runtime 停止，状态变为 stopped |
+| 13 | 检查日志和 artifact metadata | 不包含明文密钥 |
+
+## 9. 当前实测记录
+
+2026-05-28 已测：
+
+| 接口 | 结果 | 说明 |
+|---|---|---|
+| `GET http://20.212.121.126/api/agnet/health` | 200 | Agent Manager IP 健康检查正常 |
+| `GET https://agent-manager.taijiagnet.com/api/agnet/health` | 暂不作为当前验收项 | 当前约定先走 IP，域名后续再切换 |
+| `POST https://code.xinghanlab.com/api/agnet/callbacks/swarm-events` 无认证 | 业务返回 `CALLBACK_UNAUTHORIZED` | Manager callback 路由在线 |
+| `POST https://code.xinghanlab.com/api/agnet/callbacks/swarm-events` 带旧 token 但空 body | 业务返回 `CALLBACK_INVALID` | 认证通过，进入事件校验 |
+| `GET https://code.xinghanlab.com/api/agnet/callbacks/swarm-events/schema` | 404 | Manager schema GET 生产未通，Manager 侧需复核 |
+| `POST http://20.212.121.126/api/swarms` 带 `dry_run:true` | 200，返回 `swm_080c59b10bbe` | 对方实际创建了 swarm，需要修复参数校验/dry-run |
+| `GET http://20.212.121.126/api/swarms/swm_080c59b10bbe` | 404 | 缺少 swarm detail |
+| `POST http://20.212.121.126/api/swarms/swm_080c59b10bbe/stop` | 404 | 缺少 swarm stop |
+| `POST http://20.212.121.126/api/agnet/deployments/swm_080c59b10bbe/stop` | 404 / `DEPLOYMENT_NOT_FOUND` | `/api/swarms` 返回 ID 与 deployment stop 不兼容 |
+
+### 9.1 2026-05-28 追加联调记录
+
+本次按当前约定使用 Agent Manager IP `http://20.212.121.126`。
+
+客户端完整用户态链路说明：
+
+- 已尝试通过生产 Manager `/api/user/login` 获取用户 session，但手头用户名组合未登录成功。
+- 因此本次没有宣称“桌面客户端登录后走 Manager 用户态创建 deployment”完整通过。
+- 本次完成的是服务到服务联调：Manager/客户端等价 payload -> Agent Manager IP，以及 Agent Manager callback 协议 -> Heicode Manager callback 接收端。
+
+Agent Manager `/api/agnet/deployments` 服务到服务链路：
+
+| 步骤 | 结果 | 证据 |
+|---|---|---|
+| `GET /api/agnet/health` | 通过 | 返回 `success=true`、`status=healthy` |
+| `POST /api/agnet/deployments` | 通过 | 返回 `deployment_id=dep_dbafd1ac37c3`，状态 `pending` |
+| `GET /api/agnet/deployments/{deployment_id}` | 通过 | 能查到 `user_id`、`binding_scope`、`sub_mode=agile`、`callback_configured=true` |
+| `GET /api/agnet/deployments/{deployment_id}/events` | 部分通过 | 只看到 `deployment.accepted`，未看到 `phase.changed/timeline.updated/artifact.created/sk_tool.*` |
+| `GET /api/agnet/deployments/{deployment_id}/logs` | 部分通过 | 返回系统日志 `Pod ... has no logs yet` |
+| `GET /api/agnet/deployments/{deployment_id}/metrics` | 通过但疑似占位 | 返回 CPU/内存/网络指标，但值看起来是固定模拟值，需要 Runtime 说明来源 |
+| `POST /api/agnet/deployments/{deployment_id}/stop` | 通过 | `dep_dbafd1ac37c3` 停止成功，返回 `status=stopped` |
+
+长等待测试：
+
+| 项 | 结果 |
+|---|---|
+| 测试 deployment | `dep_cd170573cf47` |
+| 等待时间 | 约 2 分钟 |
+| 最终状态 | 已清理停止 |
+| 事件结果 | 只有 `deployment.accepted` 和 `deployment.stopped` |
+| 未观察到 | `phase.changed`、`timeline.updated`、`artifact.created`、`agent.started/completed`、`sk_tool.called/completed` |
+| 结论 | Agent Manager 文档声称的“Runtime 主动推送 status/phase/timeline/agent/tool/artifact 事件”在本次实测中没有跑出来，需要 Agent Manager 继续排查 |
+
+Heicode Manager callback 接收端：
+
+| 步骤 | 结果 | 证据 |
+|---|---|---|
+| 无认证 POST callback | 通过预期 | 返回 `CALLBACK_UNAUTHORIZED` |
+| 带旧 token 但缺事件字段 | 通过预期 | 返回 `CALLBACK_INVALID`，说明认证通过并进入业务校验 |
+| 带旧 token 发送合法 `timeline.updated` | 通过 | 返回 `success=true`、`inserted=true` |
+| 重复发送同一 `event_id` | 通过 | 返回 `deduplicated=true`、`inserted=false` |
+
+本次合法 callback 测试事件：
+
+```text
+event_id=evt_agent_manager_ip_smoke_1779954828884
+event_type=timeline.updated
+swarm_id=dep_cd170573cf47
+source=agent-manager-ip-smoke
+```
+
+结论：
+
+1. Heicode Manager callback 接收端可用，旧 token 认证和幂等可用。
+2. Agent Manager IP 的 `/api/agnet/deployments` 创建、查询、停止可用。
+3. Agent Manager 当前没有在实测中产生普通 sub 所需的 phase/timeline/artifact/SK 主动回调。
+4. `/api/swarms` 仍存在 ID 不可查询/不可停止和 `dry_run` 误创建问题。
+5. 因没有可用生产 Manager 用户 session，本次没有完成“客户端登录态 -> Manager 用户态 deployment -> Runtime”的完整端到端测试。
+
+### 9.2 2026-05-28 测试用户客户端模拟链路
+
+测试用户：
+
+```text
+email: zsbgnw@gmail.com
+username: chenchen
+user_id: 22
+group: default
+```
+
+说明：密码只用于本次登录测试，不写入本文档。
+
+本次已完成“客户端模拟 -> Heicode Manager 生产用户态接口 -> Agent Manager IP Runtime”链路。
+
+| 步骤 | 结果 | 证据 |
+|---|---|---|
+| 登录生产 Manager | 通过 | `/api/user/login` 返回 `success=true`，用户 `id=22` |
+| 查询用户信息 | 通过 | `/api/user/self` 返回用户 `chenchen`、`group=default` |
+| 查询 Runtime 健康 | 通过 | `/api/agnet/runtime/health` 返回 `enabled=true`、`configured=true`、`status=healthy`、`create_path=/api/agnet/deployments`、远端为 Agent Manager IP |
+| 客户端模拟创建 deployment | 通过 | `POST /api/agnet/user/deployments` 返回 Manager deployment `dep_1ba14ccfb558` |
+| Manager -> Agent Manager create | 通过 | Manager detail 写回 `runtime_deployment_id=dep_3335e54e9bdf`，`runtime_state=pending` |
+| Manager 用户态 events | 通过 | 出现 `deployment.accepted`、`runtime.sync.started`、`runtime.sync.accepted` |
+| Manager 用户态 logs | 通过 | 出现 control-plane 日志和 runtime sync 日志，均为 redacted |
+| Manager 用户态 metrics | 部分通过 | 返回 `platform_estimated=true`，说明是 Manager 估算/占位，不是 Runtime 真实资源指标 |
+| Manager 用户态 artifacts | 未产出 | 返回空列表 |
+| Manager 用户态 timeline | 部分通过 | 能返回 deployment/events，但 callbacks/artifacts 为空 |
+| Manager stop | 通过 | `POST /api/agnet/user/deployments/dep_1ba14ccfb558/stop` 返回 `status=stopped` |
+| Runtime stop 结果 | 通过 | 直查 Agent Manager `dep_3335e54e9bdf`，状态为 `stopped` |
+
+本次真实 ID：
+
+```text
+manager_deployment_id=dep_1ba14ccfb558
+runtime_deployment_id=dep_3335e54e9bdf
+correlation_id=manager-client-sim-1779955103016
+runtime_agent_instance_id=agi_ed399bf8cc70
+```
+
+Agent Manager 侧直查 `dep_3335e54e9bdf`：
+
+| 接口 | 结果 |
+|---|---|
+| `GET /api/agnet/deployments/dep_3335e54e9bdf` | 200，状态 `stopped`，`user_id=22` |
+| `GET /api/agnet/deployments/dep_3335e54e9bdf/events` | 200，仅有 `deployment.accepted`、`deployment.stopped` |
+| `GET /api/agnet/deployments/dep_3335e54e9bdf/logs` | 200，仅有 `Pod ... has no logs yet` |
+| `GET /api/agnet/deployments/dep_3335e54e9bdf/metrics` | 200，返回 CPU/内存/网络固定值 |
+
+本次客户端模拟链路结论：
+
+1. 测试用户登录、Manager 用户态接口、Manager Runtime bridge、Agent Manager create、Agent Manager stop 均已真实跑通。
+2. Manager 能拿到 Runtime 健康状态，并能把用户态 deployment 同步到 Agent Manager IP。
+3. Manager stop 能传递到 Agent Manager，Runtime deployment 已停止。
+4. Agent Manager 仍未真实产生普通 sub 必需的阶段、timeline、artifact、SK 工具和 usage 回调。
+5. 当前 metrics/logs 更像 Runtime 占位数据：日志显示 `Pod ... has no logs yet`，metrics 为固定 CPU/内存/网络值。
+6. 本次 Manager 请求中的 agile context 没有在 Runtime 详情中表现为有效阶段推进，Runtime 事件里 `agile_context` 为空字段，需要双方继续核对字段解析和透传。
+
+## 10. 完成定义
+
+只有满足以下条件，才能认为普通 sub 敏捷 Runtime 联调完成：
+
+1. Manager 能创建 Runtime run，并保存 Runtime 返回的 `deployment_id` / `swarm_id`。
+2. Runtime 能主动回调 Manager，且 callback 通过认证、幂等、脱敏和 schema 校验。
+3. Manager 的 artifacts / timeline / sk-snapshots / events 能看到 Runtime 回传数据。
+4. Manager 发起 stop 后 Runtime 真实停止。
+5. Runtime 高危审批能暂停，Manager approve/reject 后 Runtime 收到 decision 并继续或停止。
+6. Runtime usage / cost 能按 user、deployment、task、agent role、model 归属。
+7. 整个流程不传递、不记录明文长期密钥。