gongzhiyongandClaude Opus 4.8
e32f711f26
README 将该项标 🟡「事件 envelope 与签名待 Manager 对齐」，暗示规范尚未 确定；而 event-schema.md §1 写「已实现，与 HM 一致」并给出完整规范串/头/ 容差。两处口径不一致（组织规则：文档冲突应点出、不自行裁定——本次按总架构 指示统一）。 依据代码实证（swarm_runtime.py:691-702 HMAC-SHA256(timestamp.event_id.body) → X-Agent-Signature/Timestamp，_post_callback httpx 投递）+ event-schema §1 已含 HM 侧参数（容差 300s、去重顺序），统一为： **机制已实现、规范与 HM 对齐、待主链路端到端联调验收**。 - README 行 11：改为「机制已实现，待主链路联调验收」并分别指向 runtime- contract §3 与 event-schema §1。 - event-schema.md §1：「已实现，与 HM 一致」→「机制已实现，规范与 HM 对齐； 待主链路端到端联调验收」。 纯文档措辞，未改任何事件 schema 字段/类型/sequence/artifact（契约冻结不受影响）。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
110 lines
8.7 KiB
Markdown
110 lines
8.7 KiB
Markdown
# Agent Swarm（HeiCode Swarm）
|
||
|
||
一个**去中心化自组织**的多智能体「蜂群」运行时。本仓**就是 swarm 运行时本身**（模式 single/chain/sub/swarm 的选择在仓外）；无中央主控分解派发，秩序与质量是**涌现**的。流程：编排器把用户需求**播种**为单一种子任务 → 各 Agent 感知共享池（任务池 + 信息素 τ）**自选**最适任务（`swarm_dispatch`）→ 经 `task_proposal` **自主分解**出后续子任务（bottom-up，非主控分解）→ 经 `task_bid/yield/takeover` **竞争/接管** → **同伴交叉评审**（≥2 评审者，取代单一评审者）→ **收敛**判定并给出 `termination_reason`，最后**汇总**为统一回答。设计与历史见 [docs/swarm/decentralized-rework-plan.md](docs/swarm/decentralized-rework-plan.md)。
|
||
|
||
> ⚠️ **能力边界（主链路接入状态）**
|
||
> 本仓当前是一个**可运行的多 Agent 工作流运行系统**，**尚未**作为 Heicode 主链路的正式 Runtime Backend 接入。下表区分能力状态；契约见 [docs/integration/](docs/integration/)，量化标准见 [docs/benchmark/](docs/benchmark/)。
|
||
>
|
||
> | 能力 | 状态 |
|
||
> |---|---|
|
||
> | 任务分解（规划回退）、能力路由派发、专家执行（OpenAI 兼容）、评审/重做循环、结果汇总、peer 协作消息路由、WebSocket Agent 协议、Redis 持久化、Prometheus 指标 | ✅ 已实现（仓内可运行） |
|
||
> | Manager↔Runtime 生命周期契约（对齐 `heicode-am-contract`）、HMAC 签名回调事件 envelope、稳定的 `deployment_id`/`workflow_id`/`trace_id` | 🟡 机制已实现，待主链路联调验收（生命周期接口见 `docs/integration/runtime-contract.md §3`；envelope/HMAC 签名机制已实现且规范与 HM 对齐，见 `docs/integration/event-schema.md §1`，待 Manager 端验签端到端联调验收） |
|
||
> | 统一 usage/计费聚合（归属 NewAPI）、审计/lineage trace、前端事件 API、统一 Agent registry/scheduling、统一 secret/workspace/tool/MCP/tenant 安全边界 | 🟡 待接入（需与 Billing / Audit / Frontend / Infra / Security Team 对齐） |
|
||
> | Benchmark 自证（`Benchmark_Agent`、`S_swarm`、`G_E`、`G_E,c`、治理/协作/通信/鲁棒性指标、baseline 对比、telemetry 架构） | 🟡 采集器已落地（`benchmark/`：指标公式 `metrics.py`、活体 run 采集 `collectors/`、4 基线 runner `runners/`、`baselines.compare` 算 `G_E`/`G_E,c`、自证合流 `selfcert_collector`、telemetry 导出 Cosmos/Blob `export/`）；**评分标准待定**——`O`（可观测性）公式、`BASE_COEFFICIENTS`、`S_gain` 阈值需累积真实用户使用数据后经验标定（长期工单）。诚实原则：缺真实输入的量返回 `NaN`、不伪造分值（标准见 `docs/benchmark/`） |
|
||
>
|
||
> 在以上「待接入 / 规划中」项目完成并经对应 Team 验收前，本文与各子文档**不得宣称**「已接入主链路」或「已具备完整 Agent Swarm 工程能力」。
|
||
>
|
||
> 🔄 **去中心化重构：核心 cutover 已完成（Path B）**。已从 Master 中心化切换为「播种 + 自组织」蜂群并设为**唯一**流程：删除了 planner 主控分解、贪心/ACO/scored 派发模式、单 critic 评审环及其全部 `ENABLE_*` 开关；播种/自选/自主分解/竞争/交叉评审/收敛**无条件生效**。仅剩待办为 **P-guard**（检测「swarm 无法运作」并列原因）。进度见 [docs/swarm/decentralized-rework-plan.md](docs/swarm/decentralized-rework-plan.md)。下文若有「主控 Agent 分解」字样为历史描述，以本段与计划文档为准。
|
||
|
||
## 系统架构
|
||
|
||
> 说明：下图中 **Heicode Manager → Orchestrator** 为**目标形态**。当前 orchestrator 仅实现了占位的 Manager 面接口与回调骨架，尚未按 `heicode-am-contract` 正式注册为 Runtime Backend（见 `docs/integration/runtime-contract.md`）。
|
||
|
||
```
|
||
用户
|
||
│
|
||
桌面客户端（desktop-client）
|
||
│ 提交需求 / 查看状态与结果
|
||
▼
|
||
Heicode Manager（控制面，外部）
|
||
│ 下发编排方案 / 接收带签名回调（审批、计费、审计）
|
||
▼
|
||
Orchestrator（编排器，FastAPI）
|
||
分解 · 派发 · 协作路由 · 评审/重做 · 汇总
|
||
├─ Redis（权威状态存储）
|
||
└─ WebSocket ┐
|
||
▼
|
||
Agent · Agent · Agent …（执行单元 / K8s Pod，调用大模型完成任务）
|
||
```
|
||
|
||
## 工作流
|
||
|
||
```
|
||
分解（Plan） → 派发给专家（Dispatch） → 专家执行（Execute）
|
||
→ 重叠领域协作 / 移交（Collaborate & Handoff）
|
||
→ 主控评审（Review）──不达标──▶ 退回相关任务重做（循环，受上限约束）
|
||
└──达标──▶ 汇总为统一回答并交付（Deliver）
|
||
```
|
||
|
||
- **分解**：优先采用 Manager 提供的编排方案；若未提供且开启规划回退（`ENABLE_PLANNER_FALLBACK`），由编排器用大模型把目标拆解为「实现 → 测试 → 文档」等专家子任务。
|
||
- **派发**：按「能力匹配 + 剩余容量」将就绪任务下发给已连接的 Agent；派发时把已完成依赖的产物与同伴信息注入上下文。
|
||
- **协作 / 移交**：测试、文档等角色可向实现角色咨询以保持语义一致；复杂子任务可移交给更合适的专家。
|
||
- **评审 / 重做**：所有任务完成后由评审者判断是否达标（开启 `ENABLE_REVIEW_LOOP`），不达标则退回相关任务重做，受 `MAX_REVIEW_CYCLES` 约束。
|
||
- **汇总交付**：通过后将各专家产出汇总为统一、面向用户的最终回答。
|
||
|
||
## 仓库结构与子文档
|
||
|
||
| 目录 | 角色 | 文档 |
|
||
|---|---|---|
|
||
| `orchestrator/` | 编排器：分解、派发、协作、评审、汇总、Manager 对接 | [orchestrator/README.md](orchestrator/README.md) |
|
||
| `agent/` | 执行单元：连接编排器、调用大模型完成任务、提交结果 | [agent/README.md](agent/README.md) |
|
||
| `desktop-client/` | 桌面客户端：任务提交、复杂度分析、状态展示、结果聚合 | [desktop-client/README.md](desktop-client/README.md) |
|
||
| `desktop-client/src/ai/` | 复杂度分析模块：评估规模、推荐 Agent 数量 | [desktop-client/src/ai/README.md](desktop-client/src/ai/README.md) |
|
||
| `docs/` | 交付说明（交付物、构建/部署、配置、验收、影响与合规） | [docs/DELIVERY.md](docs/DELIVERY.md) |
|
||
| `k8s/` | Kubernetes 部署清单（编排器、Agent、Redis、RBAC、监控等） | — |
|
||
| `scripts/` | 部署、契约校验、冒烟与端到端工作流测试脚本 | — |
|
||
| `test-data/` | 复杂度分析的标注数据集 | — |
|
||
|
||
## 快速开始（本地）
|
||
|
||
需要 Python 3.13+ 环境。本地开发可用受控的内存存储（`REDIS_FAKE=1`，免装 Redis）。
|
||
|
||
```bash
|
||
# 1) 编排器（在本目录 agent_swarm_v5 下运行，开启规划回退与评审循环）
|
||
set "REDIS_FAKE=1"
|
||
set "ENABLE_PLANNER_FALLBACK=1"
|
||
set "ENABLE_REVIEW_LOOP=1"
|
||
python -m uvicorn orchestrator.main:app --host 0.0.0.0 --port 8000
|
||
|
||
# 2) 一个 Agent（凭据放在本目录 .env：OPENAI_API_KEY 等）
|
||
set "ORCHESTRATOR_URL=ws://localhost:8000"
|
||
set "AGENT_ID=worker-1"
|
||
set "AGENT_CAPABILITIES=python,code_generation,testing,pytest,technical-writing,general"
|
||
set "WORKSPACE_DIR=..\tmp-workspace\worker-1"
|
||
python -m agent.main
|
||
|
||
# 3) 提交一个需求
|
||
curl -s -X POST http://localhost:8000/api/swarms -H "Content-Type: application/json" ^
|
||
-d "{\"mode\":\"swarm\",\"requirement\":{\"objective\":\"实现 add(a,b) 并补充测试与说明\"},\"callback\":{\"url\":\"http://localhost:9999/cb\",\"subscribed_events\":[]},\"metadata\":{\"manager_deployment_id\":\"dev-1\"}}"
|
||
```
|
||
|
||
随后可通过 `GET /api/swarms/{deployment_id}/workflow` 与 `/logs` 观察分解、派发、评审与汇总过程。各组件的环境变量与接口详见对应子文档。
|
||
|
||
## 关键设计
|
||
|
||
- **存储**：Redis 为权威状态存储；仅 `REDIS_FAKE` / `ALLOW_MEMORY_STORE` 开启时才使用进程内回退，生产环境在 Redis 不可用时快速失败。
|
||
- **模型**：Agent 与编排器规划/评审均使用 **OpenAI 兼容** API，可指向自定义端点；未配置密钥时规划/评审退化为静态分解与启发式判定。
|
||
- **Manager 契约**：面向 Manager 的接口、带签名回调、审批链与计费/审计字段均予以保留。
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
python scripts/test-runtime-contract.py # Manager 契约校验
|
||
python scripts/test-merge-smoke.py # 工作流冒烟测试（评审 / 协作 / 汇总等）
|
||
```
|
||
|
||
## 安全与合规
|
||
|
||
- **禁止**将密钥、令牌、云凭据写入代码、日志或提交记录；凭据通过 `.env`（已忽略）或部署环境 / `secret_ref` 注入。
|
||
- 涉及鉴权、审批链、计费与审计的改动需遵循 Manager 安全规则。
|