更新 2026-06-01_heicode客户端相关定义.md
This commit is contained in:
File diff suppressed because it is too large
Load Diff
@@ -1,338 +0,0 @@
|
|||||||
**一、系统分工**
|
|
||||||
|
|
||||||
```text
|
|
||||||
Heicode 客户端
|
|
||||||
= 主 Agent / 用户交互层
|
|
||||||
只负责发起任务、持续会话、展示状态、查看/下载产物
|
|
||||||
|
|
||||||
heicode-mananger
|
|
||||||
= 控制面 / 路由器 / 唯一裁判
|
|
||||||
负责用户权限、任务记录、Runtime 路由、状态裁决、产物归档、审计
|
|
||||||
|
|
||||||
agent_management
|
|
||||||
= Sub Agile Runtime
|
|
||||||
所有 Sub / Sub Agile / 普通 sub 模式都走这里
|
|
||||||
|
|
||||||
HeiCode-Swarm
|
|
||||||
= Swarm Runtime
|
|
||||||
所有 Swarm / 蜂群模式都走这里
|
|
||||||
```
|
|
||||||
|
|
||||||
最重要的边界：
|
|
||||||
|
|
||||||
```text
|
|
||||||
客户端永远只调用 heicode-mananger
|
|
||||||
客户端不直连 agent_management
|
|
||||||
客户端不直连 HeiCode-Swarm
|
|
||||||
```
|
|
||||||
|
|
||||||
**二、模式路由**
|
|
||||||
|
|
||||||
Manager 不能再根据 `/api/swarms` 判断是不是 Swarm，因为 `agent_management` 里 `/api/swarms` 只是普通 sub 的 Runtime 兼容入口。
|
|
||||||
|
|
||||||
应该按任务模式路由：
|
|
||||||
|
|
||||||
```text
|
|
||||||
mode = sub_agile / sub / agile
|
|
||||||
-> agent_management
|
|
||||||
|
|
||||||
mode = swarm
|
|
||||||
-> HeiCode-Swarm
|
|
||||||
```
|
|
||||||
|
|
||||||
建议 Manager 配置：
|
|
||||||
|
|
||||||
```env
|
|
||||||
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：
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"mode": "sub_agile",
|
|
||||||
"sub_mode": "agile",
|
|
||||||
"client_role": "main_agent",
|
|
||||||
"task_id": "task_xxx",
|
|
||||||
"conversation_id": "conv_xxx"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Swarm：
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"mode": "swarm",
|
|
||||||
"client_role": "main_agent",
|
|
||||||
"task_id": "task_xxx",
|
|
||||||
"conversation_id": "conv_xxx"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Manager 转发 Runtime 时，补齐：
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"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 所以就是完成”。它应该上报：
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"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 再判断最终用户看到的状态：
|
|
||||||
|
|
||||||
```text
|
|
||||||
有有效产物 -> completed
|
|
||||||
只有总结，没有实际产物 -> completed_without_deliverable / needs_codegen
|
|
||||||
Runtime 失败 -> failed
|
|
||||||
用户停止 -> stopped
|
|
||||||
等待审批 -> waiting_approval
|
|
||||||
```
|
|
||||||
|
|
||||||
这样客户端就不会再自己用正则判断“这是不是产物”。
|
|
||||||
|
|
||||||
**五、统一产物协议**
|
|
||||||
|
|
||||||
无论 Sub Agile 还是 Swarm，都统一走 Manager 的产物接口：
|
|
||||||
|
|
||||||
```text
|
|
||||||
GET /api/agnet/user/deployments/{deployment_id}/artifacts
|
|
||||||
GET /api/agnet/user/deployments/{deployment_id}/artifacts/{artifact_id}/content
|
|
||||||
```
|
|
||||||
|
|
||||||
Runtime 回调 `artifact.created` 只传摘要和 URI，不把完整内容塞进对话框。
|
|
||||||
|
|
||||||
Artifact 标准字段：
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"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"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
客户端只展示：
|
|
||||||
- 产物列表
|
|
||||||
- 查看详情
|
|
||||||
- 下载
|
|
||||||
|
|
||||||
不要再把完整产物重复塞进聊天气泡和侧边栏。
|
|
||||||
|
|
||||||
**六、事件回调统一**
|
|
||||||
|
|
||||||
统一回调入口可以继续用现有的：
|
|
||||||
|
|
||||||
```text
|
|
||||||
POST /api/agnet/callbacks/swarm-events
|
|
||||||
```
|
|
||||||
|
|
||||||
虽然名字里有 `swarm-events`，但它可以作为 Runtime 统一事件入口。后续可以加别名：
|
|
||||||
|
|
||||||
```text
|
|
||||||
POST /api/agnet/callbacks/runtime-events
|
|
||||||
```
|
|
||||||
|
|
||||||
标准事件分两层。
|
|
||||||
|
|
||||||
Sub Agile 必须支持：
|
|
||||||
|
|
||||||
```text
|
|
||||||
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 在此基础上增加：
|
|
||||||
|
|
||||||
```text
|
|
||||||
task.created
|
|
||||||
task.claimed
|
|
||||||
task.running
|
|
||||||
task.heartbeat
|
|
||||||
task.retried
|
|
||||||
task.released
|
|
||||||
handoff.requested
|
|
||||||
handoff.completed
|
|
||||||
```
|
|
||||||
|
|
||||||
**七、客户端展示规则**
|
|
||||||
|
|
||||||
客户端只按 `mode` 展示不同 UI：
|
|
||||||
|
|
||||||
Sub Agile：
|
|
||||||
|
|
||||||
```text
|
|
||||||
阶段
|
|
||||||
角色
|
|
||||||
时间线
|
|
||||||
产物
|
|
||||||
审批
|
|
||||||
用量
|
|
||||||
```
|
|
||||||
|
|
||||||
Swarm：
|
|
||||||
|
|
||||||
```text
|
|
||||||
阶段
|
|
||||||
任务图
|
|
||||||
Agent 节点
|
|
||||||
handoff
|
|
||||||
heartbeat
|
|
||||||
blocked/retry
|
|
||||||
产物
|
|
||||||
审批
|
|
||||||
用量
|
|
||||||
```
|
|
||||||
|
|
||||||
客户端不要展示：
|
|
||||||
- 部署草稿 JSON
|
|
||||||
- Runtime 内部 payload
|
|
||||||
- `swarm_id` / `runtime_deployment_id`
|
|
||||||
- callback 原始内容
|
|
||||||
- Runtime 内部诊断给普通用户
|
|
||||||
|
|
||||||
这些可以放到开发者诊断模式。
|
|
||||||
|
|
||||||
**八、各项目需要做什么**
|
|
||||||
|
|
||||||
`heicode-mananger`：
|
|
||||||
|
|
||||||
```text
|
|
||||||
1. 按 mode 路由 Runtime
|
|
||||||
2. 成为唯一状态裁判
|
|
||||||
3. 统一 artifact schema
|
|
||||||
4. 统一 completed 判定
|
|
||||||
5. 保存 deployment_id / runtime_deployment_id / runtime_kind
|
|
||||||
6. 提供统一 artifacts/content 接口
|
|
||||||
7. 不再依赖文本正则判断产物有效性
|
|
||||||
```
|
|
||||||
|
|
||||||
`agent_management`：
|
|
||||||
|
|
||||||
```text
|
|
||||||
1. 作为所有 Sub Agile 的 Runtime
|
|
||||||
2. 接收 Manager 的普通 sub plan
|
|
||||||
3. 生成 artifact.created
|
|
||||||
4. 上报结构化 deliverable 字段
|
|
||||||
5. 支持 content 下载路径
|
|
||||||
6. 不把 summary-only 当成完整代码交付
|
|
||||||
```
|
|
||||||
|
|
||||||
`HeiCode-Swarm`：
|
|
||||||
|
|
||||||
```text
|
|
||||||
1. 只负责真正 Swarm 模式
|
|
||||||
2. 提供 task graph / handoff / heartbeat / retry
|
|
||||||
3. 也遵守统一 artifact / callback / usage schema
|
|
||||||
4. 禁止绕过 Manager 的旁路调用成为生产主链路
|
|
||||||
```
|
|
||||||
|
|
||||||
`heicode-winos-release / heicode-macos-release`：
|
|
||||||
|
|
||||||
```text
|
|
||||||
1. 只调用 Manager
|
|
||||||
2. 最近任务保存 mode / task_id / deployment_id / conversation_id
|
|
||||||
3. Sub Agile 和 Swarm 显示分开
|
|
||||||
4. 产物只从 Manager artifact content 接口查看和下载
|
|
||||||
5. 不再本地裁决 completed 是否真实完成
|
|
||||||
```
|
|
||||||
|
|
||||||
**九、推荐落地顺序**
|
|
||||||
|
|
||||||
```text
|
|
||||||
第一步：定 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 结论
|
|
||||||
不再本地正则判断产物和完成状态
|
|
||||||
```
|
|
||||||
|
|
||||||
最终一句话方案：
|
|
||||||
|
|
||||||
```text
|
|
||||||
Sub Agile 和 Swarm 不合并 Runtime，只统一 Manager 对外协议；
|
|
||||||
agent_management 是 Sub Agile 执行层，HeiCode-Swarm 是 Swarm 执行层；
|
|
||||||
Manager 是唯一裁判，客户端是主 Agent 和展示层。
|
|
||||||
```
|
|
||||||
Reference in New Issue
Block a user