FastheiandClaude Opus 4.8
f9df550ac9
修 #75:蜂群单任务铺不到多 agent。两层根因 + 对应修复(均经本地 k8s 端到端验证):
1) 真实 agent 执行器从未实现 #7「自主分解提案」(autonomous-task-generation.md §4 标为
「后续」;此前只有 stub_agent 演示)。编排器侧 handle_task_proposal 早已就绪,缺 agent 侧出口。
- agent/main.py: 新增 propose_task()(发 WS task_proposal,字段对齐 handle_task_proposal);
execute_task 传入 proposal_callback;control_messages 接受 task_proposal_ack。
- agent/task_executor.py: 新增 _maybe_propose_subtasks() —— 执行顶层种子时用 _parse_task 拆分,
把每个子任务经 proposal_callback 提案入池(由编排器 review→create_task→其他 agent 自选)。
仅顶层种子提案(parent 为空、source 非 agent_proposed/dynamic_handoff),子任务不再递归提案,无环。
env ENABLE_AUTONOMOUS_PROPOSALS(默认 on)可关。
2) _parse_task 又脆又静默退化为单任务(原 max_tokens=2000 截断 + 严格 json.loads + except 兜底):
- max_tokens 可配 AGENT_PLAN_MAX_TOKENS(默认 65536;注:qwen3.7-max 网关上限即 65536,>之 400);
- 新增 _coerce_subtasks 宽容解析(裸数组 / ``` 围栏 / {"subtasks":[...]} / 从文本抠 [...]);
- 解析失败重试 1 次再退化;成功打 INFO "Decomposed into N",退化打明确 WARNING(可观测)。
派发:提案子任务 required_capabilities 置空(像种子,任意空闲 agent 可自选)。否则 LLM 给的具体能力
不是固定能力池子集 → can_agent_run_task 永远拒 → 子任务卡 PENDING(本地实测到的死锁)。能力提示保留在
agent_role(不门控派发);能力感知路由(把子任务能力映射到能力池)作为后续增强,见 #75。
本地验证(Docker Desktop k8s,qwen3.7-max,池16):两次 run 复现「种子→拆 6/8 子任务→派给 6/8 个不同
agent 并行执行」,此前恒为单 agent。
测试(本地全过):test-runtime-contract / test-contract-freeze / test-merge-smoke / test-workflow-e2e /
test-autonomous-tasks / test-agent-launcher / test-convergence。
影响:仅 agent/(执行单元);不动 Manager↔Swarm 冻结契约 / 计费 / 审计 / 编排器接口。
Refs #75
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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 §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 基线 runnerrunners/、baselines.compare算G_E/G_E,c、自证合流selfcert_collector、telemetry 导出 Cosmos/Blobexport/）；评分标准待定——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。下文若有「主控 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 安全规则。