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>
442 lines
14 KiB
Markdown
442 lines
14 KiB
Markdown
# Agent Manager 蜂群模式对接任务清单
|
||
|
||
更新时间：2026-05-28
|
||
发给：Agent Manager / HeiCode-Swarm 负责人
|
||
来源：Heicode Manager 当前代码、生产 1.4.9 验证结果、蜂群资料包和 Heicode 产品资料包。
|
||
|
||
## 1. 结论
|
||
|
||
Heicode Manager 端已经具备蜂群模式所需的控制面能力：创建 deployment、桥接 Runtime、保存 `runtime_deployment_id` / `swarm_id`、接收 callback、落 artifact、落 approval、聚合 timeline、审批结果回传 Runtime、页面展示 task flow。
|
||
|
||
Agent Manager / Swarm Runtime 当前还需要补齐或确认的是：真实创建 Swarm Run、生成任务图、Agent claim/heartbeat/handoff/retry/blocked 状态机、artifact 真实产出、审批暂停和恢复、日志指标、用量回传。
|
||
|
||
## 2. 当前 Manager 已完成
|
||
|
||
| 能力 | 状态 | 说明 |
|
||
|---|---|---|
|
||
| Runtime 创建桥接 | 已完成 | Manager 可通过 `AGENT_RUNTIME_BASE_URL` + `AGENT_RUNTIME_CREATE_PATH` 调 Agent Manager |
|
||
| Runtime 停止桥接 | 已完成 | 默认 `POST /api/agent/deployments/{deployment_id}/stop` |
|
||
| `/api/swarms` adapter | 已完成 | Manager 用户态入口已存在，后续可切真实 Runtime |
|
||
| callback 接收 | 已完成 | `POST /api/agent/callbacks/swarm-events` |
|
||
| callback 鉴权 | 已完成 | 支持 service token 或 HMAC |
|
||
| callback 幂等 | 已完成 | 按 `event_id` / `idempotency_key` 去重 |
|
||
| task flow 校验 | 已完成 | `task.*` / `handoff.*` 缺关键字段会返回 `CALLBACK_SCHEMA_INVALID` |
|
||
| artifact 落库 | 已完成 | `artifact.created` 可落库并在 deployment 详情展示 |
|
||
| approval 落库 | 已完成 | `approval.requested` 可转 Manager 审批记录 |
|
||
| approval decision 回传 | 已完成 | 用户 approve/reject 后 Manager 可回传 Runtime |
|
||
| 页面验证 | 已完成 | 生产 1.4.9 已验证 `Sub task flow` 展示 task/blocked/retry/handoff |
|
||
|
||
## 3. Agent Manager 需要实现或确认的 P0
|
||
|
||
| 任务 | 必需 | 原因 | 验收 |
|
||
|---|---:|---|---|
|
||
| 提供真实创建 Swarm Run 接口 | 是 | Manager 只能发起，不能替 Runtime 生成真实任务图 | `POST /api/swarms` 或配置等价接口返回真实 `deployment_id` / `swarm_id` |
|
||
| 返回稳定 Runtime 标识 | 是 | Manager 要保存 `deployment_id <-> runtime_deployment_id/swarm_id` 映射 | 创建响应包含 `deployment_id` 或 `id`，建议同时包含 `swarm_id` |
|
||
| 生成任务图 | 是 | 蜂群模式核心是 task graph，不是单个占位 deployment | Runtime 内部能创建任务节点，并回调 `task.created` |
|
||
| Agent claim / heartbeat | 是 | Manager 页面和客户端需要知道哪个 Agent 在做哪个任务 | 回调 `task.claimed`、`task.heartbeat` |
|
||
| blocked / retry / failed 状态机 | 是 | 失败恢复和阻塞是蜂群运行核心 | 回调 `task.blocked`、`task.retried`、`task.failed`，字段符合 schema |
|
||
| handoff 状态机 | 是 | 蜂群 Agent 间交接需要可审计 | 回调 `handoff.requested`、`handoff.completed` |
|
||
| artifact 真实产出 | 是 | Manager 只保存摘要和引用，真实产物来自 Runtime | 回调 `artifact.created`，带 `uri`、`summary`、`artifact_type` |
|
||
| 高危审批暂停/恢复 | 是 | 高危操作需要客户端审批后 Runtime 才能继续 | Runtime 回调 `approval.requested`，并接收 Manager decision |
|
||
| 日志/指标 | 是 | 线上排障和验收需要真实运行数据 | 提供 logs/metrics 查询或通过 callback 摘要回传 |
|
||
| 不记录明文长期密钥 | 是 | 安全红线 | Runtime 只消费 `secret_ref` / `credential_ref`，日志和 artifact metadata 不出现明文密钥 |
|
||
|
||
## 4. Runtime 创建接口
|
||
|
||
生产目标：
|
||
|
||
```http
|
||
POST /api/swarms
|
||
Authorization: Bearer <service_token>
|
||
X-User-ID: <manager_user_id>
|
||
X-Binding-Scope: <binding_scope>
|
||
X-Correlation-ID: <correlation_id>
|
||
X-Idempotency-Key: manager-<manager_deployment_id>
|
||
Content-Type: application/json
|
||
```
|
||
|
||
Manager 当前可通过环境变量切换：
|
||
|
||
```text
|
||
AGENT_RUNTIME_BASE_URL=http://20.212.121.126
|
||
AGENT_RUNTIME_CREATE_PATH=/api/swarms
|
||
AGENT_RUNTIME_HEALTH_PATH=/api/agent/health
|
||
AGENT_RUNTIME_STOP_PATH=/api/agent/deployments/{deployment_id}/stop
|
||
AGENT_RUNTIME_APPROVAL_DECISION_PATH=/api/swarms/{swarm_id}/approvals/{approval_id}
|
||
```
|
||
|
||
请求体核心形状：
|
||
|
||
```json
|
||
{
|
||
"orchestration_plan": {
|
||
"intent_id": "task_xxx",
|
||
"objective": "完成本轮用户目标",
|
||
"sub_mode": "agile",
|
||
"risk_level": "medium",
|
||
"budget": {
|
||
"max_tokens": 120000,
|
||
"max_cost_usd": 8,
|
||
"max_duration_sec": 3600
|
||
},
|
||
"user_context": {
|
||
"user_id": "22",
|
||
"channel_id": "heicode"
|
||
},
|
||
"billing_context": {
|
||
"provider": "newapi",
|
||
"default_model_id": "model_xxx",
|
||
"allowed_model_ids": ["model_xxx"],
|
||
"secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/model-gateway-key"
|
||
},
|
||
"agile_context": {
|
||
"iteration": "2026-05-28",
|
||
"stage": "development",
|
||
"checkpoint": "draft_created",
|
||
"next_action": "continue",
|
||
"requires_user_approval": false
|
||
},
|
||
"agents": []
|
||
},
|
||
"agents": [
|
||
{
|
||
"role": "backend",
|
||
"resource_grants": []
|
||
}
|
||
],
|
||
"resource_grants": [
|
||
{
|
||
"grant_id": "grant-task-backend",
|
||
"resource_id": "repo-main",
|
||
"resource_type": "git",
|
||
"permission_scope": ["repo:read", "repo:write:feature-branches"],
|
||
"secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/repo-main",
|
||
"ref": "azkv://heicode-kv.vault.azure.net/secrets/repo-main",
|
||
"target_role": "backend"
|
||
}
|
||
],
|
||
"callback": {
|
||
"url": "https://code.xinghanlab.com/api/agent/callbacks/swarm-events",
|
||
"signing_secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/agent-callback-signing-key",
|
||
"subscribed_events": [
|
||
"deployment.status_changed",
|
||
"task.created",
|
||
"task.claimed",
|
||
"task.heartbeat",
|
||
"task.blocked",
|
||
"task.retried",
|
||
"task.failed",
|
||
"task.completed",
|
||
"handoff.requested",
|
||
"handoff.completed",
|
||
"approval.requested",
|
||
"artifact.created",
|
||
"timeline.updated"
|
||
]
|
||
},
|
||
"sub_mode": "agile",
|
||
"metadata": {
|
||
"manager_deployment_id": "dep_xxx",
|
||
"heicode_deployment_id": "dep_xxx",
|
||
"heicode_runtime_bridge": true,
|
||
"correlation_id": "corr_xxx"
|
||
}
|
||
}
|
||
```
|
||
|
||
响应必须至少满足一种：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"deployment_id": "runtime-dep-123",
|
||
"swarm_id": "swarm-123",
|
||
"status": "running"
|
||
}
|
||
}
|
||
```
|
||
|
||
或：
|
||
|
||
```json
|
||
{
|
||
"deployment_id": "runtime-dep-123",
|
||
"swarm_id": "swarm-123",
|
||
"status": "running"
|
||
}
|
||
```
|
||
|
||
Manager 解析规则：
|
||
|
||
| Runtime 字段 | Manager 保存到 |
|
||
|---|---|
|
||
| `data.deployment_id` / `deployment_id` / `id` | `runtime_deployment_id` |
|
||
| `data.swarm_id` / `swarm_id` / `runtime_swarm_id` | `runtime_swarm_id` |
|
||
| `data.status` / `status` | `runtime_state` |
|
||
|
||
## 5. Runtime 回调 Manager
|
||
|
||
统一入口：
|
||
|
||
```http
|
||
POST https://code.xinghanlab.com/api/agent/callbacks/swarm-events
|
||
X-Agent-Service-Token: <callback_token>
|
||
X-Agent-Event-Id: <event_id>
|
||
X-Correlation-ID: <correlation_id>
|
||
Content-Type: application/json
|
||
```
|
||
|
||
也支持 HMAC：
|
||
|
||
```http
|
||
X-Agent-Timestamp: <unix_ms>
|
||
X-Agent-Signature: sha256=<hex>
|
||
```
|
||
|
||
签名内容：
|
||
|
||
```text
|
||
timestamp + "." + event_id + "." + raw_body
|
||
```
|
||
|
||
Agent Manager / 蜂群侧可以先拉取 Manager 当前接受的事件 schema：
|
||
|
||
```http
|
||
GET https://code.xinghanlab.com/api/agent/callbacks/swarm-events/schema
|
||
```
|
||
|
||
该接口不返回任何 token 或密钥，只返回事件类型、分类和必填字段，用于联调前核对 `task.*`、`handoff.*`、`artifact.created`、`approval.requested` 等 callback payload 是否符合 Manager 接收规则。
|
||
|
||
统一 envelope：
|
||
|
||
```json
|
||
{
|
||
"event_id": "evt_xxx",
|
||
"idempotency_key": "evt_xxx",
|
||
"event_type": "task.blocked",
|
||
"deployment_id": "dep_xxx",
|
||
"swarm_id": "swarm-123",
|
||
"agent_instance_id": "agent-backend-1",
|
||
"task_id": "task-backend-1",
|
||
"occurred_at": "2026-05-28T10:00:00Z",
|
||
"correlation_id": "corr_xxx",
|
||
"source": "heicode-swarm-runtime",
|
||
"payload": {}
|
||
}
|
||
```
|
||
|
||
## 6. task / handoff 事件 schema
|
||
|
||
Manager 已上线校验。以下字段缺失会拒绝，返回 `CALLBACK_SCHEMA_INVALID`。
|
||
|
||
| event_type | 必填字段 |
|
||
|---|---|
|
||
| `task.created` | `task_id`, `payload.title` |
|
||
| `task.claimed` | `task_id`, `payload.agent_role` |
|
||
| `task.running` | `task_id`, `payload.agent_role` |
|
||
| `task.heartbeat` | `task_id`, `payload.agent_role` |
|
||
| `task.blocked` | `task_id`, `payload.reason` |
|
||
| `task.retried` | `task_id`, `payload.attempt` |
|
||
| `task.released` | `task_id`, `payload.agent_role` |
|
||
| `task.failed` | `task_id`, `payload.reason` |
|
||
| `task.completed` | `task_id` |
|
||
| `handoff.requested` | `task_id`, `payload.from_role`, `payload.to_role` |
|
||
| `handoff.completed` | `task_id`, `payload.from_role`, `payload.to_role` |
|
||
| `artifact.created` | `artifact.artifact_id` 或 `payload.artifact_id` |
|
||
|
||
示例：
|
||
|
||
```json
|
||
{
|
||
"event_id": "evt_task_blocked_1",
|
||
"event_type": "task.blocked",
|
||
"deployment_id": "dep_xxx",
|
||
"swarm_id": "swarm-123",
|
||
"agent_instance_id": "agent-backend-1",
|
||
"task_id": "task-backend-1",
|
||
"source": "heicode-swarm-runtime",
|
||
"payload": {
|
||
"task_id": "task-backend-1",
|
||
"agent_role": "backend",
|
||
"reason": "等待前端接口字段确认",
|
||
"severity": "warning",
|
||
"next_action": "handoff_to_frontend"
|
||
}
|
||
}
|
||
```
|
||
|
||
```json
|
||
{
|
||
"event_id": "evt_handoff_1",
|
||
"event_type": "handoff.requested",
|
||
"deployment_id": "dep_xxx",
|
||
"swarm_id": "swarm-123",
|
||
"task_id": "task-backend-1",
|
||
"source": "heicode-swarm-runtime",
|
||
"payload": {
|
||
"task_id": "task-backend-1",
|
||
"from_role": "backend",
|
||
"to_role": "frontend",
|
||
"summary": "后端接口已完成，交给前端接页面"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 7. artifact 回调
|
||
|
||
Runtime 不要把大文件正文塞进 callback。只回写摘要和可访问引用。
|
||
|
||
```json
|
||
{
|
||
"event_id": "evt_artifact_1",
|
||
"event_type": "artifact.created",
|
||
"deployment_id": "dep_xxx",
|
||
"swarm_id": "swarm-123",
|
||
"task_id": "task-backend-1",
|
||
"source": "heicode-swarm-runtime",
|
||
"artifact": {
|
||
"artifact_id": "art_backend_patch_1",
|
||
"artifact_type": "code_patch",
|
||
"title": "Backend patch",
|
||
"summary": "完成工单列表和状态流转接口",
|
||
"uri": "git://repo#feature/task-backend-1",
|
||
"checksum": "sha256:abc123",
|
||
"metadata": {
|
||
"redacted": true,
|
||
"agent_role": "backend"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 8. approval 回调和 decision 接口
|
||
|
||
Runtime 在高危动作前必须暂停，并回调 Manager：
|
||
|
||
```json
|
||
{
|
||
"event_id": "evt_approval_1",
|
||
"event_type": "approval.requested",
|
||
"deployment_id": "dep_xxx",
|
||
"swarm_id": "swarm-123",
|
||
"agent_instance_id": "agent-backend-1",
|
||
"task_id": "task-backend-1",
|
||
"source": "heicode-swarm-runtime",
|
||
"payload": {
|
||
"approval_id": "appr_runtime_1",
|
||
"operation": "git.write",
|
||
"resource_id": "repo-main",
|
||
"resource_type": "git",
|
||
"resource_scope": "feature/*",
|
||
"target_role": "backend",
|
||
"risk_level": "high",
|
||
"requires_credential": true,
|
||
"secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/repo-main",
|
||
"ttl_seconds": 900,
|
||
"reason": "需要写入功能分支"
|
||
}
|
||
}
|
||
```
|
||
|
||
Manager 用户同意或拒绝后会调用 Runtime：
|
||
|
||
```http
|
||
POST /api/swarms/{swarm_id}/approvals/{approval_id}
|
||
Authorization: Bearer <service_token>
|
||
X-Correlation-ID: <correlation_id>
|
||
X-Idempotency-Key: approval-decision-<approval_id>-<approved|rejected>
|
||
Content-Type: application/json
|
||
```
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"approval_id": "appr_runtime_1",
|
||
"decision": "approved",
|
||
"manager_deployment_id": "dep_xxx",
|
||
"runtime_deployment_id": "runtime-dep-123",
|
||
"swarm_id": "swarm-123",
|
||
"operation": "git.write",
|
||
"resource_id": "repo-main",
|
||
"resource_type": "git",
|
||
"resource_scope": "feature/*",
|
||
"target_role": "backend",
|
||
"risk_level": "high",
|
||
"requires_credential": true,
|
||
"user_id": "22",
|
||
"credential_ref": "lease://agent/lease_xxx",
|
||
"lease_id": "lease_xxx",
|
||
"lease_expires_at": 1779850900000
|
||
}
|
||
```
|
||
|
||
注意：Manager 不会把长期 `secret_ref` 发回 decision，只会在同意时发短期 `credential_ref`。
|
||
|
||
## 9. 停止接口
|
||
|
||
默认：
|
||
|
||
```http
|
||
POST /api/agent/deployments/{runtime_deployment_id}/stop
|
||
Authorization: Bearer <service_token>
|
||
Content-Type: application/json
|
||
```
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"reason": "Heicode Manager requested stop",
|
||
"manager_deployment_id": "dep_xxx"
|
||
}
|
||
```
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"deployment_id": "runtime-dep-123",
|
||
"swarm_id": "swarm-123",
|
||
"status": "stopped"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 10. 验收用例
|
||
|
||
| 用例 | 操作 | 期望 |
|
||
|---|---|---|
|
||
| health | `GET /api/agent/health` | 200，`status=healthy` |
|
||
| create | Manager 创建 deployment | Runtime 返回 `deployment_id` 和 `swarm_id` |
|
||
| task flow | Runtime 回调 `task.created/claimed/heartbeat/blocked/retried/completed` | Manager timeline 和页面 Sub task flow 可见 |
|
||
| handoff | Runtime 回调 `handoff.requested/completed` | Manager 页面可见 from/to role |
|
||
| schema 拒绝 | 发送缺 `to_role` 的 `handoff.requested` | Manager 返回 `CALLBACK_SCHEMA_INVALID` |
|
||
| artifact | Runtime 回调 `artifact.created` | Manager artifacts 列表出现产物 |
|
||
| approval | Runtime 回调 `approval.requested` | Manager pending approval 出现 |
|
||
| decision | 用户 approve/reject | Runtime decision 接口收到 `approved/rejected` |
|
||
| stop | Manager stop deployment | Runtime 状态变为 stopped |
|
||
| 安全 | 搜索日志和回调 payload | 不出现 password/token/private_key/access_key/connection_string 明文 |
|
||
|
||
## 11. Agent Manager 不需要做的事
|
||
|
||
| 不需要做 | 原因 |
|
||
|---|---|
|
||
| 实现桌面客户端 V2 body 加密 | 这是客户端到 Manager 的协议，Manager 已支持 |
|
||
| 直接让普通用户访问 Azure Key Vault | 密钥入口由 Manager 控制，Runtime 只消费 `secret_ref` 或短期 `credential_ref` |
|
||
| 在 callback 中发送明文模型 key / Git token / 云密钥 | 安全红线，Manager 会拒绝疑似明文敏感字段 |
|
||
| 替 Manager 保存用户、资源绑定、审批主记录 | Manager 是控制面和记录面 |
|
||
|
||
## 12. 联调顺序建议
|
||
|
||
1. Agent Manager 确认 health、create、stop、approval decision 路径。
|
||
2. Manager 配置 `AGENT_RUNTIME_CREATE_PATH=/api/swarms` 后创建一个真实 deployment。
|
||
3. Agent Manager 回调 `task.created`、`task.claimed`、`task.heartbeat`。
|
||
4. 回调 `task.blocked`、`handoff.requested`、`handoff.completed`、`task.retried`。
|
||
5. 回调 `artifact.created`。
|
||
6. 回调 `approval.requested`，客户端/Manager approve 后 Runtime 接收 decision 并继续。
|
||
7. Manager stop，Runtime 停止任务并回调最终状态。
|