Agent Swarm（HeiCode Swarm）

一个多智能体「蜂群」系统：用户提出需求后，由主控逻辑自动将其分解为多个子任务，分发给擅长不同领域的专家 Agent 并行完成；专家之间可就重叠领域相互协作；产出汇总后由主控评审是否达标，未达标则退回重做，循环直至生成满意的最终回答。

系统架构

            用户
             │
        桌面客户端（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 安全规则。