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。

⚠️ 能力边界（主链路接入状态） 本仓当前是一个可运行的多 Agent 工作流运行系统，尚未作为 Heicode 主链路的正式 Runtime Backend 接入。下表区分能力状态；契约见 docs/integration/，量化标准见 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；事件 envelope 与签名待 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 架构）	🔴 规划中（标准见 docs/benchmark/，采集器尚未落地）

在以上「待接入 / 规划中」项目完成并经对应 Team 验收前，本文与各子文档不得宣称「已接入主链路」或「已具备完整 Agent Swarm 工程能力」。

🔄 去中心化重构：核心 cutover 已完成（Path B）。已从 Master 中心化切换为「播种 + 自组织」蜂群并设为唯一流程：删除了 planner 主控分解、贪心/ACO/scored 派发模式、单 critic 评审环及其全部 ENABLE_* 开关；播种/自选/自主分解/竞争/交叉评审/收敛无条件生效。仅剩待办为 P-guard（检测「swarm 无法运作」并列原因）。进度见 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
agent/	执行单元：连接编排器、调用大模型完成任务、提交结果	agent/README.md
desktop-client/	桌面客户端：任务提交、复杂度分析、状态展示、结果聚合	desktop-client/README.md
desktop-client/src/ai/	复杂度分析模块：评估规模、推荐 Agent 数量	desktop-client/src/ai/README.md
docs/	交付说明（交付物、构建/部署、配置、验收、影响与合规）	docs/DELIVERY.md
k8s/	Kubernetes 部署清单（编排器、Agent、Redis、RBAC、监控等）	—
scripts/	部署、契约校验、冒烟与端到端工作流测试脚本	—
test-data/	复杂度分析的标注数据集	—

快速开始（本地）

需要 Python 3.13+ 环境。本地开发可用受控的内存存储（REDIS_FAKE=1，免装 Redis）。

# 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 的接口、带签名回调、审批链与计费/审计字段均予以保留。

测试

python scripts/test-runtime-contract.py   # Manager 契约校验
python scripts/test-merge-smoke.py         # 工作流冒烟测试（评审 / 协作 / 汇总等）

安全与合规

• 禁止将密钥、令牌、云凭据写入代码、日志或提交记录；凭据通过 .env（已忽略）或部署环境 / secret_ref 注入。
• 涉及鉴权、审批链、计费与审计的改动需遵循 Manager 安全规则。