更新 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