chenchenandClaude Opus 4.8
0fe1d20d67
按桌面客户端统一方案 v0.1 + agent_management Sub Mode Runtime 对接,强制全量统一,不留兼容。
命名统一(强制,无兼容):
- 全仓 agnet/Agnet/AGNET → agent/Agent/AGENT:后端 Go(路由 /api/agent/*、env AGENT_*、
结构体/函数、19 个文件改名)、前端(agent-console/agent-hub、/api/agent 调用、i18n)、
DB(表 agent_*、列 agent_id)、compose/.env、文档、脚本。
- DB 加幂等迁移 renameAgnetTablesToAgent():启动时 rename 老 agnet_* 表/列,保住生产数据。
统一方案核心(10 项):
- callback 统一 /api/agent/callbacks/runtime-events(路由/广播URL/函数名)。
- artifact 兜底判定改用 Runtime 权威信号 metadata.synthesized(§7.2)+ 结构化 artifact_type。
- Manager→Runtime 路径对齐 /api/agent/sub-agile/deployments(§2.2),{deployment_id} 回退 swarm_id。
- 状态裁决 display_status:Manager 唯一裁判,completed 无有效产物→needs_codegen/
completed_without_deliverable(§10.6),接入 detail/timeline/workflow。
- GET /api/heicode/capabilities 能力发现(§6)。
- 模型策略 per_role(role_models)+ 收集 allowed_model_ids(§9)。
- resource_binding_id→secret_ref 服务端解析,客户端不再 inline secret_ref(§17.6)。
- 客户端统一路由层 /api/heicode/sub-agile|swarm/*(task≡deployment,复用控制面)+ workflow 投影。
- 日志分层 user_logs/debug_logs(§13)。
验证:go build ./... + go test(controller/router/model/middleware)全绿;前端 tsc -b + rsbuild build 通过。
待部署:VM .env 的 AGNET_*→AGENT_*;启动迁移自动 rename 表;其他三仓库需同步切到 /api/agent。
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
390 lines
9.4 KiB
Markdown
390 lines
9.4 KiB
Markdown
# Agent Manager 普通 sub 产物回调缺失问题
|
||
|
||
更新时间：2026-05-29
|
||
发给：Agent Manager / Agent Runtime 负责人
|
||
范围：普通 sub 敏捷模式，不包含 HeiCode-Swarm 独立蜂群 Runtime。
|
||
|
||
## 1. 问题现象
|
||
|
||
Heicode 桌面客户端执行任务：
|
||
|
||
```text
|
||
给我做一个 oracle 云的代理商网站，做前后端分离
|
||
```
|
||
|
||
客户端最终只显示：
|
||
|
||
```text
|
||
Swarm initialized and planning started
|
||
Swarm execution completed
|
||
completed
|
||
```
|
||
|
||
但右侧运行数据中：
|
||
|
||
```text
|
||
ARTIFACTS = 0
|
||
SK SNAPSHOTS = 0
|
||
```
|
||
|
||
用户无法看到真正交付物，例如代码分支、提交、预览地址、部署清单、文档或最终结果摘要。
|
||
|
||
## 2. 本次链路归属
|
||
|
||
本次不是走 HeiCode-Swarm 独立蜂群 Runtime。
|
||
|
||
Heicode Manager 生产配置确认当前普通 sub 走：
|
||
|
||
```text
|
||
AGENT_RUNTIME_BASE_URL=http://20.212.121.126
|
||
AGENT_RUNTIME_CREATE_PATH=/api/swarms
|
||
```
|
||
|
||
`SWARM_RUNTIME_BASE_URL` 当前为空。
|
||
|
||
因此本问题归属：
|
||
|
||
```text
|
||
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：
|
||
|
||
```text
|
||
dep_fa4f43da9e0a
|
||
```
|
||
|
||
Runtime 返回并保存的 swarm/deployment id：
|
||
|
||
```text
|
||
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 |
|
||
|
||
关键缺失：
|
||
|
||
```text
|
||
artifact.created = 0
|
||
task.completed = 0
|
||
sk_tool.completed = 0
|
||
```
|
||
|
||
Heicode Manager artifact 表查询结果：
|
||
|
||
```text
|
||
agent_artifacts where deployment_id = 'dep_fa4f43da9e0a'
|
||
=> 0 rows
|
||
```
|
||
|
||
说明：Heicode Manager 没有收到任何产物事件，因此客户端显示 `ARTIFACTS 0` 是真实数据，不是客户端漏显示。
|
||
|
||
## 4. Heicode Manager callback 接收链路是通的
|
||
|
||
生产日志中，Agent Manager 在任务完成时间段连续请求：
|
||
|
||
```text
|
||
POST /api/agent/callbacks/swarm-events
|
||
```
|
||
|
||
HTTP 状态均为：
|
||
|
||
```text
|
||
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：
|
||
|
||
```http
|
||
GET http://20.212.121.126/api/swarms/swm_f9ce3f6c90aa
|
||
```
|
||
|
||
返回关键信息：
|
||
|
||
```json
|
||
{
|
||
"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": []
|
||
}
|
||
```
|
||
|
||
直查日志：
|
||
|
||
```http
|
||
GET http://20.212.121.126/api/swarms/swm_f9ce3f6c90aa/logs
|
||
```
|
||
|
||
返回：
|
||
|
||
```text
|
||
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：
|
||
|
||
```text
|
||
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 返回：
|
||
|
||
```text
|
||
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 没收到：
|
||
|
||
```text
|
||
task.completed
|
||
task.failed
|
||
task.blocked
|
||
```
|
||
|
||
Agent Manager 应在每个子 Agent / 子任务结束时回调任务状态，至少包含：
|
||
|
||
```json
|
||
{
|
||
"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 返回：
|
||
|
||
```text
|
||
tokens_used = 0
|
||
total_messages = 0
|
||
```
|
||
|
||
如果任务真实调用了模型，应回传：
|
||
|
||
```json
|
||
{
|
||
"model_usage": {
|
||
"input_tokens": 1234,
|
||
"output_tokens": 5678,
|
||
"total_tokens": 6912,
|
||
"model_cost_usd": 0.0123,
|
||
"model_id": "xxx"
|
||
}
|
||
}
|
||
```
|
||
|
||
如果没有真实调用模型，应明确返回 `blocked` 或 `failed`，不能标记为正常 completed。
|
||
|
||
### P1：提供真实日志
|
||
|
||
当前日志仍是：
|
||
|
||
```text
|
||
Logs will be fetched from K8s in Phase 2
|
||
```
|
||
|
||
需要至少返回可排障日志摘要：
|
||
|
||
1. Agent 是否启动成功。
|
||
2. 是否领取任务。
|
||
3. 是否调用模型。
|
||
4. 是否生成文件/分支/产物。
|
||
5. 失败原因。
|
||
|
||
## 8. 建议的 artifact.created callback 示例
|
||
|
||
```json
|
||
{
|
||
"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 分支，也可以先回：
|
||
|
||
```json
|
||
{
|
||
"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. 验收标准
|
||
|
||
修复后请用同类任务重新跑一次：
|
||
|
||
```text
|
||
给我做一个 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：
|
||
|
||
```text
|
||
任务被标记 completed，但 Runtime 没有生成或回传 artifact.created。
|
||
```
|
||
|
||
请 Agent Manager 优先修复任务完成后的产物生成、产物回调、状态一致性、usage 和日志回传。
|