添加 mananger和Swarm分工.md

2026-06-01 07:04:29 +00:00
parent 262fbd90ff
commit 0055f5f6ca
1 changed files with 174 additions and 0 deletions
@@ -0,0 +1,174 @@
+这两个项目要做的是“把职责边界钉死”，不是继续在客户端补丁里猜。
+
+**heicode-mananger 要做**
+1. **成为唯一裁决方**
+   - 不要直接镜像 Runtime 的 `completed`。
+   - 根据 Runtime 回传的结构化字段判断：
+     - `completed`
+     - `completed_without_deliverable`
+     - `needs_codegen`
+     - `failed`
+     - `stopped`
+
+2. **统一 artifact 契约**
+   - 固定 `artifact_type` 枚举：
+     - `code_patch`
+     - `code_bundle`
+     - `document`
+     - `test_report`
+     - `deployment_manifest`
+     - `summary_only`
+     - `other`
+   - Manager 按结构化字段判断是否是真交付物，不再靠 title/summary/uri 正则。
+
+3. **统一 Runtime 创建入口配置**
+   - Sub Agile 可走 `/api/agnet/deployments`
+   - Swarm 可走 `/api/swarms`
+   - 但 Manager 内部需要明确：
+     ```text
+     mode=sub_agile -> 普通子 agent 执行
+     mode=swarm     -> 蜂群 task graph 执行
+     ```
+
+4. **补齐状态枚举和文档**
+   - 文档、Go model、客户端都要认：
+     ```text
+     accepted
+     running
+     completed
+     completed_without_deliverable
+     needs_codegen
+     failed
+     stopped
+     ```
+   - 不要再出现文档里没有 `completed`，代码却写 `completed`。
+
+5. **统一 callback schema**
+   - 继续用：
+     ```text
+     POST /api/agnet/callbacks/swarm-events
+     ```
+   - 但必须校验并落库：
+     - `deployment.status_changed`
+     - `phase.changed`
+     - `timeline.updated`
+     - `artifact.created`
+     - `usage.recorded`
+     - `approval.requested`
+     - Swarm 模式额外支持 `task.*`、`handoff.*`
+
+6. **暴露给客户端的结果要是“裁决后结果”**
+   - 客户端查 deployment/artifacts 时，Manager 返回：
+     ```json
+     {
+       "status": "completed_without_deliverable",
+       "deliverable_status": "summary_only",
+       "artifacts": [...]
+     }
+     ```
+   - 客户端只展示，不再重新判断。
+
+**HeiCode-Swarm 要做**
+1. **不要自报成功即成功**
+   - 现在最大问题是模型说 `completed`，Runtime 就当完成。
+   - Runtime 必须上报结构化事实：
+     ```json
+     {
+       "has_diff": true,
+       "files_modified": [],
+       "commit_sha": "",
+       "artifact_type": "summary_only",
+       "summary_only": true,
+       "tokens_used": 2682
+     }
+     ```
+
+2. **Sub Agile 下作为子 agent runtime**
+   - 不要让 Swarm 抢客户端主 agent 的角色。
+   - 接收到 Manager payload 后，只执行：
+     ```text
+     planning/design/development/testing/review
+     ```
+   - 通过 callback 汇报阶段和产物。
+
+3. **Swarm 模式才启用 task graph**
+   - `mode=sub_agile`：可以没有完整 task graph。
+   - `mode=swarm`：必须有：
+     - `task.created`
+     - `task.claimed`
+     - `task.heartbeat`
+     - `task.blocked`
+     - `task.completed`
+     - `handoff.requested`
+     - `handoff.completed`
+
+4. **artifact 回调必须结构化**
+   - 不要只塞一大段 Markdown。
+   - 回调里要有：
+     ```json
+     {
+       "artifact": {
+         "artifact_id": "art_xxx",
+         "artifact_type": "code_patch",
+         "title": "Backend patch",
+         "summary": "...",
+         "uri": "artifact://...",
+         "metadata": {
+           "files_modified": ["..."],
+           "has_diff": true,
+           "summary_only": false,
+           "agent_role": "backend"
+         }
+       }
+     }
+     ```
+
+5. **补 usage 回传**
+   - 每次模型调用或任务完成后回传：
+     ```json
+     {
+       "event_type": "usage.recorded",
+       "payload": {
+         "model_id": "gpt-5.4",
+         "model_tokens": 2682,
+         "model_cost_usd": 0.03,
+         "agent_role": "backend"
+       }
+     }
+     ```
+
+6. **callback id 规则要稳定**
+   - `deployment_id` 用 Manager 的 deployment id。
+   - `runtime_deployment_id` 用 Runtime 自己的 id。
+   - `swarm_id` 用 Runtime swarm id。
+   - 不要混用，否则 Manager 无法归档。
+
+**两边共同要统一**
+最关键是一份契约：
+
+```text
+客户端 = main_agent
+Manager = control_plane / judge
+HeiCode-Swarm = sub_agent_runtime
+```
+
+建议新增或更新一份共享文档：
+
+```text
+docs/integration/heicode-runtime-unified-contract.md
+```
+
+里面固定这些内容：
+- `mode`: `sub_agile | swarm`
+- 状态机枚举
+- artifact 类型枚举
+- completed 判定规则
+- callback envelope
+- usage schema
+- approval schema
+- id 映射规则
+
+**一句话分工**
+- `heicode-mananger`：负责“判定、记录、计费、审计、给客户端稳定结果”。
+- `HeiCode-Swarm`：负责“执行、产生结构化事实、回调产物和用量”。
+- 客户端：只做“主 agent 会话和用户体验”，不再补下游判断逻辑。