heicode/docs/integration/AgentManager普通sub产物回调缺失问题.md

Agent Manager 普通 sub 产物回调缺失问题

更新时间：2026-05-29
发给：Agent Manager / Agent Runtime 负责人
范围：普通 sub 敏捷模式，不包含 HeiCode-Swarm 独立蜂群 Runtime。

1. 问题现象

Heicode 桌面客户端执行任务：

给我做一个 oracle 云的代理商网站，做前后端分离

客户端最终只显示：

Swarm initialized and planning started
Swarm execution completed
completed

但右侧运行数据中：

ARTIFACTS = 0
SK SNAPSHOTS = 0

用户无法看到真正交付物，例如代码分支、提交、预览地址、部署清单、文档或最终结果摘要。

2. 本次链路归属

本次不是走 HeiCode-Swarm 独立蜂群 Runtime。

Heicode Manager 生产配置确认当前普通 sub 走：

AGENT_RUNTIME_BASE_URL=http://20.212.121.126
AGENT_RUNTIME_CREATE_PATH=/api/swarms

SWARM_RUNTIME_BASE_URL 当前为空。

因此本问题归属：

Heicode 桌面客户端
  -> Heicode Manager 生产
  -> Agent Manager / Agent Runtime 普通 sub 入口
  -> Heicode Manager callback
  -> 桌面客户端查询 artifacts/timeline

不是独立蜂群 Runtime http://52.139.240.116:8000 的问题。

3. Heicode Manager 生产侧实查结果

Heicode Manager deployment：

dep_fa4f43da9e0a

Runtime 返回并保存的 swarm/deployment id：

swm_f9ce3f6c90aa

Heicode Manager 生产库记录：

字段	值
deployment_id	dep_fa4f43da9e0a
status	completed
phase	deploy
runtime_state	completed
runtime_deployment_id	swm_f9ce3f6c90aa
runtime_swarm_id	swm_f9ce3f6c90aa
created_at_text	2026-05-29T08:40:50Z
updated_at_text	2026-05-29T08:40:51Z

Heicode Manager 收到的 callback 类型统计：

callback event_type	count
agent.started	2
budget.alert	1
deployment.status_changed	3
phase.changed	2
timeline.updated	2

关键缺失：

artifact.created = 0
task.completed = 0
sk_tool.completed = 0

Heicode Manager artifact 表查询结果：

agent_artifacts where deployment_id = 'dep_fa4f43da9e0a'
=> 0 rows

说明：Heicode Manager 没有收到任何产物事件，因此客户端显示 ARTIFACTS 0 是真实数据，不是客户端漏显示。

4. Heicode Manager callback 接收链路是通的

生产日志中，Agent Manager 在任务完成时间段连续请求：

POST /api/agent/callbacks/swarm-events

HTTP 状态均为：

200

这说明：

1. Agent Manager 能打到 Heicode Manager callback 地址。
2. Heicode Manager 没有拒收这些 callback。
3. 问题不是 callback 鉴权失败。
4. 问题不是 Heicode Manager callback endpoint 不通。

但 callback 事件内容中没有 artifact.created，因此 Heicode Manager 无法落库 artifacts。

5. Agent Manager 侧直查结果

直查 Agent Manager Runtime：

GET http://20.212.121.126/api/swarms/swm_f9ce3f6c90aa

返回关键信息：

{
  "deployment_id": "swm_f9ce3f6c90aa",
  "swarm_id": "swm_f9ce3f6c90aa",
  "status": "completed",
  "phase": "planning",
  "progress": 100,
  "agents": [
    {
      "agent_id": "agi_backend_59717a71",
      "role": "backend",
      "status": "running",
      "output": null
    },
    {
      "agent_id": "agi_frontend_3063c6c9",
      "role": "frontend",
      "status": "running",
      "output": null
    }
  ],
  "metrics": {
    "total_messages": 0,
    "tokens_used": 0
  },
  "artifacts": []
}

直查日志：

GET http://20.212.121.126/api/swarms/swm_f9ce3f6c90aa/logs

返回：

Logs will be fetched from K8s in Phase 2

这说明 Agent Manager 自己也没有保存或返回真实产物。

6. 当前判断

本问题根因不在 Heicode Manager，也不在桌面客户端。

当前证据指向 Agent Manager / Agent Runtime：

1. Runtime 将 deployment 标记为 completed。
2. Runtime 自身返回 artifacts: []。
3. Runtime 没有 callback artifact.created。
4. Runtime agents 仍显示 running，但 deployment 已 completed，状态不一致。
5. Runtime metrics 中 tokens_used=0、total_messages=0，没有真实模型执行用量。
6. Runtime logs 仍是占位文本，没有真实 K8s / Agent 日志。

因此客户端只能展示完成状态，不能展示交付结果。

7. Agent Manager 需要修复的内容

P0：任务完成必须回调 artifact

普通 sub 任务完成时，Agent Manager 必须向 Heicode Manager callback：

POST https://code.xinghanlab.com/api/agent/callbacks/swarm-events
event_type = artifact.created

即使没有 Git 分支，也必须返回一个可展示的交付物。

建议 artifact 类型：

场景	artifact_type	uri / 内容
代码已提交	code_patch	git://repo#<branch> 或 repo URL + branch + commit
生成了前后端项目	deployment_manifest	项目结构、启动方式、服务端口、部署说明
只产出设计/说明	document	文档地址或文档摘要
无法生成正式产物	other	明确失败原因、已完成内容、下一步动作

最低要求：不能只发 completed，必须有一个 artifact.created 或明确失败事件。

P0：completed 状态与 Agent 状态一致

当前 Runtime 返回：

deployment.status = completed
agents[].status = running

需要修复为一致状态：

1. 如果 deployment completed，则相关 agent 应为 completed、stopped 或明确的终态。
2. 如果 agent 仍 running，则 deployment 不应为 completed。
3. 如果任务未真实执行，应返回 failed 或 blocked，并说明原因。

P0：回调 task.completed / task.failed

当前 Heicode Manager 没收到：

task.completed
task.failed
task.blocked

Agent Manager 应在每个子 Agent / 子任务结束时回调任务状态，至少包含：

{
  "event_type": "task.completed",
  "deployment_id": "dep_fa4f43da9e0a",
  "swarm_id": "swm_f9ce3f6c90aa",
  "task_id": "task-backend-xxx",
  "agent_instance_id": "agi_backend_59717a71",
  "payload": {
    "task_id": "task-backend-xxx",
    "agent_role": "backend",
    "status": "completed",
    "summary": "后端实现完成，产物见 artifact"
  }
}

P1：回传真实 usage / cost

当前 Runtime 返回：

tokens_used = 0
total_messages = 0

如果任务真实调用了模型，应回传：

{
  "model_usage": {
    "input_tokens": 1234,
    "output_tokens": 5678,
    "total_tokens": 6912,
    "model_cost_usd": 0.0123,
    "model_id": "xxx"
  }
}

如果没有真实调用模型，应明确返回 blocked 或 failed，不能标记为正常 completed。

P1：提供真实日志

当前日志仍是：

Logs will be fetched from K8s in Phase 2

需要至少返回可排障日志摘要：

1. Agent 是否启动成功。
2. 是否领取任务。
3. 是否调用模型。
4. 是否生成文件/分支/产物。
5. 失败原因。

8. 建议的 artifact.created callback 示例

{
  "event_id": "evt_artifact_<unique>",
  "event_type": "artifact.created",
  "deployment_id": "dep_fa4f43da9e0a",
  "swarm_id": "swm_f9ce3f6c90aa",
  "agent_instance_id": "agi_backend_59717a71",
  "task_id": "task-backend-001",
  "occurred_at": "2026-05-29T08:40:51Z",
  "correlation_id": "corr_xxx",
  "source": "agent-manager",
  "payload": {
    "artifact_id": "art_swm_f9ce3f6c90aa_backend_001",
    "artifact_type": "code_patch",
    "title": "Oracle 云代理商网站后端实现",
    "summary": "已生成后端接口、数据模型和启动说明",
    "uri": "git://repo#feature/swm_f9ce3f6c90aa",
    "checksum": "commit_sha_if_available",
    "metadata": {
      "redacted": true,
      "agent_role": "backend",
      "runtime_deployment_id": "swm_f9ce3f6c90aa"
    }
  }
}

如果没有 Git 分支，也可以先回：

{
  "event_type": "artifact.created",
  "deployment_id": "dep_fa4f43da9e0a",
  "swarm_id": "swm_f9ce3f6c90aa",
  "payload": {
    "artifact_id": "art_swm_f9ce3f6c90aa_summary",
    "artifact_type": "document",
    "title": "任务执行结果摘要",
    "summary": "Runtime 已完成任务，但未返回 Git 分支。这里应写清生成内容、文件位置或未生成原因。",
    "uri": "runtime://swm_f9ce3f6c90aa/artifacts/summary",
    "metadata": {
      "redacted": true
    }
  }
}

9. 验收标准

修复后请用同类任务重新跑一次：

给我做一个 oracle 云的代理商网站，做前后端分离

必须满足：

验收项	标准
Runtime 状态	deployment 和 agents 状态一致
callback	Heicode Manager 收到 artifact.created
Manager artifacts	/api/agent/user/deployments/{deployment_id}/artifacts 返回 total > 0
客户端展示	右侧 ARTIFACTS 不再是 0
交付物	能看到 Git 分支、提交、预览地址、部署清单或最终结果文档
usage	如果真实调用模型，tokens/cost 不应一直为 0
logs	不再只有 Phase 2 占位文本

10. 当前结论

Heicode Manager 和桌面客户端当前表现是正确反映 Runtime 数据。

真正缺口在 Agent Manager / Agent Runtime：

任务被标记 completed，但 Runtime 没有生成或回传 artifact.created。

请 Agent Manager 优先修复任务完成后的产物生成、产物回调、状态一致性、usage 和日志回传。