heicodedebug/计划分工.md

一、系统分工

Heicode 客户端
= 主 Agent / 用户交互层
只负责发起任务、持续会话、展示状态、查看/下载产物

heicode-mananger
= 控制面 / 路由器 / 唯一裁判
负责用户权限、任务记录、Runtime 路由、状态裁决、产物归档、审计

agent_management
= Sub Agile Runtime
所有 Sub / Sub Agile / 普通 sub 模式都走这里

HeiCode-Swarm
= Swarm Runtime
所有 Swarm / 蜂群模式都走这里

最重要的边界：

客户端永远只调用 heicode-mananger
客户端不直连 agent_management
客户端不直连 HeiCode-Swarm

二、模式路由

Manager 不能再根据 /api/swarms 判断是不是 Swarm，因为 agent_management 里 /api/swarms 只是普通 sub 的 Runtime 兼容入口。

应该按任务模式路由：

mode = sub_agile / sub / agile
  -> agent_management

mode = swarm
  -> HeiCode-Swarm

建议 Manager 配置：

SUB_RUNTIME_BASE_URL=http://agent-management
SUB_RUNTIME_CREATE_PATH=/api/swarms

SWARM_RUNTIME_BASE_URL=http://heicode-swarm
SWARM_RUNTIME_CREATE_PATH=/api/swarms

也就是说，两个 Runtime 都可以有 /api/swarms，但 Manager 必须用 mode 决定请求哪个服务。

三、统一请求结构

客户端发给 Manager 时，必须明确模式和主 Agent 身份。

Sub Agile：

{
  "mode": "sub_agile",
  "sub_mode": "agile",
  "client_role": "main_agent",
  "task_id": "task_xxx",
  "conversation_id": "conv_xxx"
}

Swarm：

{
  "mode": "swarm",
  "client_role": "main_agent",
  "task_id": "task_xxx",
  "conversation_id": "conv_xxx"
}

Manager 转发 Runtime 时，补齐：

{
  "orchestration_plan": {
    "objective": "用户任务",
    "sub_mode": "agile",
    "user_context": {},
    "billing_context": {},
    "agent_runtime": {},
    "agents": [],
    "metadata": {
      "mode": "sub_agile",
      "client_role": "main_agent",
      "manager_deployment_id": "dep_xxx",
      "correlation_id": "task_xxx_xxx"
    }
  },
  "callback": {
    "url": "https://code.xinghanlab.com/api/agnet/callbacks/swarm-events",
    "signing_secret_ref": "azkv://..."
  }
}

四、统一状态裁决

heicodedebug 里反复强调：Runtime 只输出“结构化真相”，Manager 才是唯一裁判。

Runtime 不应该说“我 completed 所以就是完成”。它应该上报：

{
  "runtime_status": "completed",
  "deliverable": {
    "artifact_type": "code_patch",
    "has_deliverable": true,
    "summary_only": false,
    "files_modified": ["src/app.ts"],
    "has_diff": true,
    "commit_sha": "",
    "artifact_ids": ["art_xxx"]
  },
  "usage": {
    "model_tokens": 2470,
    "model_cost_usd": 0.03
  }
}

Manager 再判断最终用户看到的状态：

有有效产物 -> completed
只有总结，没有实际产物 -> completed_without_deliverable / needs_codegen
Runtime 失败 -> failed
用户停止 -> stopped
等待审批 -> waiting_approval

这样客户端就不会再自己用正则判断“这是不是产物”。

五、统一产物协议

无论 Sub Agile 还是 Swarm，都统一走 Manager 的产物接口：

GET /api/agnet/user/deployments/{deployment_id}/artifacts
GET /api/agnet/user/deployments/{deployment_id}/artifacts/{artifact_id}/content

Runtime 回调 artifact.created 只传摘要和 URI，不把完整内容塞进对话框。

Artifact 标准字段：

{
  "artifact_id": "art_xxx",
  "artifact_type": "code_patch",
  "title": "Backend task delivery",
  "summary": "摘要",
  "uri": "runtime://swm_xxx/artifacts/art_xxx",
  "mime_type": "text/plain",
  "size_bytes": 12345,
  "stage": "development",
  "checkpoint": "artifact_ready",
  "metadata": {
    "runtime_deployment_id": "swm_xxx",
    "agent_role": "backend",
    "content_hash": "sha256:xxx",
    "download_path": "/api/swarms/swm_xxx/artifacts/art_xxx/content"
  }
}

客户端只展示：

• 产物列表
• 查看详情
• 下载

不要再把完整产物重复塞进聊天气泡和侧边栏。

六、事件回调统一

统一回调入口可以继续用现有的：

POST /api/agnet/callbacks/swarm-events

虽然名字里有 swarm-events，但它可以作为 Runtime 统一事件入口。后续可以加别名：

POST /api/agnet/callbacks/runtime-events

标准事件分两层。

Sub Agile 必须支持：

deployment.status_changed
phase.changed
timeline.updated
agent.started
agent.completed
agent.failed
task.completed
task.failed
task.blocked
artifact.created
budget.alert
approval.requested

Swarm 在此基础上增加：

task.created
task.claimed
task.running
task.heartbeat
task.retried
task.released
handoff.requested
handoff.completed

七、客户端展示规则

客户端只按 mode 展示不同 UI：

Sub Agile：

阶段
角色
时间线
产物
审批
用量

Swarm：

阶段
任务图
Agent 节点
handoff
heartbeat
blocked/retry
产物
审批
用量

客户端不要展示：

• 部署草稿 JSON
• Runtime 内部 payload
• swarm_id / runtime_deployment_id
• callback 原始内容
• Runtime 内部诊断给普通用户

这些可以放到开发者诊断模式。

八、各项目需要做什么

heicode-mananger：

1. 按 mode 路由 Runtime
2. 成为唯一状态裁判
3. 统一 artifact schema
4. 统一 completed 判定
5. 保存 deployment_id / runtime_deployment_id / runtime_kind
6. 提供统一 artifacts/content 接口
7. 不再依赖文本正则判断产物有效性

agent_management：

1. 作为所有 Sub Agile 的 Runtime
2. 接收 Manager 的普通 sub plan
3. 生成 artifact.created
4. 上报结构化 deliverable 字段
5. 支持 content 下载路径
6. 不把 summary-only 当成完整代码交付

HeiCode-Swarm：

1. 只负责真正 Swarm 模式
2. 提供 task graph / handoff / heartbeat / retry
3. 也遵守统一 artifact / callback / usage schema
4. 禁止绕过 Manager 的旁路调用成为生产主链路

heicode-winos-release / heicode-macos-release：

1. 只调用 Manager
2. 最近任务保存 mode / task_id / deployment_id / conversation_id
3. Sub Agile 和 Swarm 显示分开
4. 产物只从 Manager artifact content 接口查看和下载
5. 不再本地裁决 completed 是否真实完成

九、推荐落地顺序

第一步：定 mode 路由
Sub Agile -> agent_management
Swarm -> HeiCode-Swarm

第二步：定状态机
completed / failed / stopped / waiting_approval / completed_without_deliverable / needs_codegen

第三步：定 artifact schema
所有 Runtime 都按同一结构回调

第四步：Manager 做唯一裁判
Runtime 上报事实，Manager 输出结论

第五步：客户端只消费 Manager 结论
不再本地正则判断产物和完成状态

最终一句话方案：

Sub Agile 和 Swarm 不合并 Runtime，只统一 Manager 对外协议；
agent_management 是 Sub Agile 执行层，HeiCode-Swarm 是 Swarm 执行层；
Manager 是唯一裁判，客户端是主 Agent 和展示层。