# 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 安全规则。