heicode-mananger/docs/integration/蜂群模式-AgentManager对接任务清单.md

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 创建接口

生产目标：

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 当前可通过环境变量切换：

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}

请求体核心形状：

{
  "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"
  }
}

响应必须至少满足一种：

{
  "success": true,
  "data": {
    "deployment_id": "runtime-dep-123",
    "swarm_id": "swarm-123",
    "status": "running"
  }
}

或：

{
  "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

统一入口：

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：

X-Agent-Timestamp: <unix_ms>
X-Agent-Signature: sha256=<hex>

签名内容：

timestamp + "." + event_id + "." + raw_body

Agent Manager / 蜂群侧可以先拉取 Manager 当前接受的事件 schema：

GET https://code.xinghanlab.com/api/agent/callbacks/swarm-events/schema

该接口不返回任何 token 或密钥，只返回事件类型、分类和必填字段，用于联调前核对 task.*、handoff.*、artifact.created、approval.requested 等 callback payload 是否符合 Manager 接收规则。

统一 envelope：

{
  "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

示例：

{
  "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"
  }
}

{
  "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。只回写摘要和可访问引用。

{
  "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：

{
  "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：

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

请求：

{
  "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. 停止接口

默认：

POST /api/agent/deployments/{runtime_deployment_id}/stop
Authorization: Bearer <service_token>
Content-Type: application/json

请求：

{
  "reason": "Heicode Manager requested stop",
  "manager_deployment_id": "dep_xxx"
}

响应：

{
  "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 停止任务并回调最终状态。