Files

T

Songhaoz666andClaude Opus 4.8 54cb327348 Agent Swarm v6：基准 v2.1、主控 Agent、实质性对等回复、客户端指南

- 基准标准 v2.1：SwarmMetrics（15 字段）、τ/η/P_decision/reward 公式、对称 G_E,c（修正 C_base=1.0 退化）、Σλ=1.0 校验；新增基线对比与运行记录 schema；指标覆盖缺口分析；参考系数暂留为元数据（待量化）。
- 主控 Agent 实体（分解 / 评审决策 / 汇总）；事件契约修正（timeline.title、budget.threshold_pct、handoff 角色、task.released）+ 契约校验脚本。
- 实质性 LLM 对等回复（含降级回退）；集成契约（runtime / event / usage / audit / frontend / capability / security）；CLIENT_GUIDE 客户端指南；CI 工作流；治理与交付文档。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-09 16:21:18 +08:00

6.9 KiB

Raw Blame History

Manager ↔ Swarm Runtime Contract（Swarm 侧拥有）

状态：草案（Swarm 侧拥有，待 HM 对齐） · 对齐对象：Heicode Manager Runtime Team

依据：

HM 侧裁定 heicode-mananger/docs/integration/heicode-swarm-deferred.md：HM 当前不实现 swarm runtime；多 Agent 蜂群归 agent_swarm / HeiCode-Swarm（本仓）；HM 侧待本仓给出正式 /api/agent/swarm/* 接口后，在 HM 的 docs/integration/ 另立契约跟踪。

既有运行时集成范式 heicode-mananger/docs/integration/heicode-am-contract.md（单 Agent 模板 Agent，经 AM 启动）。本契约沿用其鉴权、回调、env、路径覆盖等约定。

本文是 HM 侧 deferred 锚点所要求的「Swarm 侧正式接口」起草。冻结需 Manager Runtime Team 评审。

1. 角色与边界

HM（Heicode Manager）：控制面。负责用户输入、资源/权限/计费/审计、模型网关（/v1/*）。HM 不承载蜂群编排。
Swarm Runtime（本仓）：执行面。接收 HM 下发的编排请求，分解→派发→执行→评审→汇总，并通过带签名回调回报生命周期事件。
HM 不在对话/执行回路；Swarm 通过回调把状态推回 HM，HM 也可主动拉取（见 §4）。

2. 鉴权（沿用 AM 约定）

HM → Swarm：Authorization: Bearer <service_token>。Swarm 侧校验 AGENT_RUNTIME_SERVICE_TOKEN（兼容 AGNET_RUNTIME_SERVICE_TOKEN）。未配置时为非安全开发模式（仅本地）。
统一响应信封：成功 { "success": true, "data": {...} }；失败 { "success": false, "error": { "code", "message", "request_id" } }。
常用请求头：X-Correlation-ID、X-Idempotency-Key、Authorization。

3. 生命周期接口（已实现 / 待对齐）

Swarm 暴露以下接口（三组别名等价，便于 HM 路径覆盖）： /api/swarms、/api/agent/swarm/deployments、/api/agnet/deployments。

动作	方法 + 路径	状态	说明
create	`POST /api/agent/swarm/deployments`	✅ 已实现	创建蜂群部署；幂等键 `X-Idempotency-Key`
status	`GET …/{deployment_id}`	✅ 已实现	返回部署概要与状态
task graph	`GET …/{deployment_id}/tasks`	✅ 已实现	任务 DAG
logs / events	`GET …/{deployment_id}/logs`、`/events`	✅ 已实现	事件流（分页 `cursor`/`limit`）
metrics / workflow / diagnostics	`GET …/{deployment_id}/metrics`、`/workflow`、`/diagnostics`	✅ 已实现	指标与编排视图
cancel	`POST …/{deployment_id}/stop`	✅ 已实现	停止并取消非终态任务，向 Agent 下发 `cancel_task`
approve	`POST …/{deployment_id}/approvals/{approval_id}`	✅ 已实现	接收 Manager 审批决定（approved/rejected）
resume	—	🟡 待对齐	当前仅「审批通过」隐式恢复（approvals）；无独立 resume 端点
retry	—	🟡 待对齐	任务级重试 / 评审重做为内部机制；无外部 retry 端点

3.1 create 请求（必填校验）

必填：orchestration_plan.objective、callback.url、metadata.manager_deployment_id。约束：mode 必须为 swarm；billing_context.secret_ref（若有）必须 azkv:// 前缀；resource_grants/metadata/callback 不得含明文密钥。

create 响应 data：deployment_id、runtime_deployment_id、manager_deployment_id、swarm_id、mode、status、runtime_execution_status、created。

3.2 ID 语义（回应 HM 标记的 `deployment_id ↔ swarm_id` 缺口）

deployment_id / runtime_deployment_id：Swarm 侧运行时部署 ID（runtime-dep-…）。
swarm_id：工作流 ID（swarm-…），作为 workflow_id；事件按 swarm_id 持久化与查询。
manager_deployment_id：HM 侧部署 ID（请求 metadata.manager_deployment_id 透传）。
correlation_id：贯穿一次交付的追踪 ID（X-Correlation-ID），作为 trace_id。
三者映射在 Swarm 持久化中维护：deployment_id ↔ swarm_id ↔ manager_deployment_id，get_run_by_identifier 支持三者任一查询。

HM 侧 heicode-swarm-deferred.md 记录的「Swarm 仅暴露 /tasks、缺 deployment_id↔swarm_id」为旧状态；本仓 v5/v6 已实现上述映射与 /api/agent/swarm/* 接口，需 HM 复核更新该锚点。

4. 状态机

部署状态：waiting_approval → running →（blocked ⇄ running）→ 终态 completed / failed / stopped。

状态	含义	进入方式
`waiting_approval`	高危/需审批，等待 Manager 审批	create 时命中审批条件
`running`	任务派发与执行中	审批通过 / 有在途任务
`blocked`	任务因移交/依赖阻塞	子任务 `blocked_on_handoff`
`completed`	所有任务终态且评审通过	全部完成（评审循环可选）
`failed`	存在失败且不可恢复	任务终态含 failed
`stopped`	Manager 主动停止	`…/stop`

每次状态变更通过回调 deployment.status_changed 推送（见 §5）。

5. 回调（已与 HM 处理器对齐）

Swarm → HM：POST {callback.url}（create 时下发，默认 HM 的 /api/agent/callbacks/runtime-events）。

鉴权与签名（与 HM agent_callback.go 一致，已实现）：

头：X-Agent-Service-Token（或 Authorization: Bearer）、X-Agent-Timestamp（Unix 毫秒）、X-Agent-Signature、X-Agent-Event-Id、X-Correlation-ID（均含 X-Agnet- 兼容别名）。
签名：signature = "sha256=" + hex(HMAC_SHA256(secret, f"{timestamp}.{event_id}.{raw_body}"))。
secret：AGENT_CALLBACK_SIGNING_SECRET（兼容 AGNET_…）；HM 侧容差默认 300s。
幂等：HM 按 X-Agent-Event-Id → body event_id → idempotency_key 去重。

事件 envelope 字段与 event_type 取值见 event-schema.md（与 HM 注册表一致）。

6. 路径与超时覆盖（沿用 AM 约定）

HM 侧可用 env 覆盖：AGENT_RUNTIME_BASE_URL、AGENT_RUNTIME_SERVICE_TOKEN、AGENT_RUNTIME_AGENT_START_PATH、AGENT_RUNTIME_AGENT_PATH、AGENT_RUNTIME_AGENT_STOP_PATH、AGENT_RUNTIME_START_TIMEOUT_SECONDS、AGENT_RUNTIME_CALLBACK_URL。

7. 安全

env/请求体不得含明文密钥；凭据经 secret_ref（azkv://）注入。详见 security-boundary.md。
Swarm 启动接口必须 HTTPS / 私网；回调走 HTTPS。

8. 待对齐项（冻结前需 Manager Runtime Team 确认）

resume / retry 是否需要独立外部端点，还是沿用 approvals + 内部重做。
HM 是否以 AM 同款 /agents 生命周期（而非 /api/agent/swarm/*）调用 Swarm；若是，需路径映射。
event-schema 中各 event_type 的必填字段与 HM 注册表逐项核对（见 event-schema.md）。
更新 HM 侧 heicode-swarm-deferred.md 锚点，登记本契约。

6.9 KiB Raw Blame History Unescape Escape