Songhaoz666andClaude Opus 4.8
f281370209
把本仓从「Master 分解→派发→单评审」重构为去中心化自组织蜂群，并设为唯一行为
（本仓即 swarm 运行时，模式选择在仓外，无 ENABLE_swarm 开关）。依据：heicodeDocs 弱中心
定义 + 蜂群文章（stigmergy）+ OpenAI Swarm（handoff）。
流程（全部无条件生效）：
- 播种 build_seed_task_specs（不主控分解）→ 自选 swarm_dispatch（能力+τ+负载+预算，唯一派发）
→ 自主分解 task_proposal（autonomous_tasks）→ 竞争/接管 task_bid/yield/takeover（task_competition）
→ 同伴交叉评审 ≥2 评审者（cross_review，取代单 critic）→ 收敛 ConvergenceReport+termination_reason
（convergence）→ 守卫 guard.diagnose（检测无法运作并列原因）。
删除：planner 主控分解、贪心/ACO/scored 派发与 scored_matchmake、单 critic 评审环、
全部 ENABLE_* swarm 构建开关。master_agent.synthesize 作为汇总工具保留。
测试：test-workflow-e2e 改写为真实 swarm 全流程；test-merge-smoke 改为 seeder/cross-review；
新增 test-swarm-{seed,dispatch,autonomous,competition,cross-review,convergence,guard} + 模块单测；
CI 同步。本地 18 套全绿。
影响范围：agent_swarm（orchestrator + 新模块 + 测试 + docs + CI）。不改 Manager↔Swarm 事件契约
（新事件均为运行时内部状态/遥测，不进 HM 注册表）；不影响 Client/计费/密钥/审计/发布链路。
无新增长期开关。
诚实边界：不动 benchmark 验收（G_E 仍需真实 run，#13）；convergence 暂为解释性（不强制覆盖
run.status）；前端可见状态为跨端（#18）；「去中心化是否更优」未证（需 Group C）。
#6 的 DoD（Path B 决策 + 定位文档）本 PR 已满足并实现 Path B → 关闭 #6。
#7/#8/#11/#12 的运行时机制已落地（事件 + e2e），但其 DoD 含前端可见状态（跨端 #18）与
多 Agent 回放，故以 Refs 链接、不自动关闭，留维护者在前端/验收就绪后关闭。
Closes #6
Refs #7
Refs #8
Refs #11
Refs #12
Refs #18
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
4.2 KiB
4.2 KiB
CLAUDE.md — HeiCode Swarm（执行面 / 运行时）
本仓库（agent_swarm_v6，对应 HeiCode-Swarm）是蜂群执行面 / 回调 / Swarm Runtime。整体介绍见 README.md，工程标准见 PROJECT_STANDARD.md，交付说明见 docs/DELIVERY.md。
改动前必读
- 先读本
CLAUDE.md与本仓PROJECT_STANDARD.md。 - heicodeDocs 是唯一标准源；涉及产品/工程/Agent/Swarm/计费/安全/交付标准时，先读取 heicodeDocs 对应标准文件。
- 跨端或动 Manager ↔ Swarm 接口时，必须先读
heicode-mananger/docs/heicode.md与docs/integration/契约。 - 不确定标准时，先停止修改并要求提供标准路径；发现文档与代码冲突时，输出冲突点，不得自行选择一方。
仓库边界
- 只允许修改 Swarm（orchestrator + agent）范围；不得跨仓改 Manager、客户端、release 仓库或 heicodeDocs。
- 一个任务只允许修改任务声明范围内的模块。
- 禁止直接 push / force push
main；所有改动走 PR，并按 PR 模板声明影响范围。
安全与合规
- 禁止把密钥、Token、云凭据、
.env、证书、私钥写入代码、日志、Markdown 或提交记录。 - 凭据一律经部署环境 /
secret_ref/ Key Vault 注入；.env已被.gitignore忽略，仅供本地开发。 secret_ref、审批链、鉴权、计费、审计相关改动必须遵循 Manager 审批链与 heicodeDocs 安全规则。- 禁止只写 TODO / mock / 示例代码就声称完成。
架构与关键约束（便于定位）
- orchestrator/：FastAPI 编排器。Manager 面接口、HMAC 签名回调、审批链必须保持契约。Redis 为权威存储；内存回退仅限
REDIS_FAKE/ALLOW_MEMORY_STORE（开发/CI）。 - agent/：执行单元，OpenAI 兼容模型；保留计费/审计归属（
usage与X-Agent/X-Agnet头）。 - 去中心化蜂群是唯一行为（cutover 已完成）：本仓就是蜂群运行时，模式选择（single/chain/sub/swarm）在仓外——无「启用 swarm」开关。流程：编排器播种单一种子任务 → Agent 感知共享池自选（信息素 τ + 能力/负载/预算，
swarm_dispatch）→ 经task_proposal自主分解（#7）→ 经task_bid/yield/takeover竞争/接管（#8）→ 同伴交叉评审（≥2 评审者，#11）→ 收敛（termination_reason，#12）。这些原语全部无条件生效（无 feature flag）。已删除：Masterplanner分解兜底、贪心/ACO/scored 派发模式、单 critic Master 评审环及其开关。master_agent.synthesize作为汇总工具保留。设计见docs/swarm/decentralized-rework-plan.md。 - 仅剩的真实开关：
ENABLE_QUALITY_EVAL+HEICODE_SANDBOX_ISOLATED（Group B 代码沙箱，见下）、ENABLE_SUBTASK_HANDOFF（agent 侧子任务移交）。decision_engine（信息素 τ）与dispatch_score（可解释打分）现为swarm_dispatch复用的库，无独立模式开关。 - 待办（P-guard）：检测「swarm 无法运作」并列原因（无 Agent/无模型/依赖死锁/预算耗尽/种子无法分解）——唯一保留的非正常路径处理，最后编写。
- 代码测试沙箱（
orchestrator/sandbox.py）：会执行模型生成代码，OS 级隔离边界 = K8s Pod。Fail-closed 双门控：需同时ENABLE_QUALITY_EVAL=1（开功能）+HEICODE_SANDBOX_ISOLATED=1（显式确认运行在隔离 Pod）；二者缺一则启动拒绝/运行时抛SandboxIsolationError，不执行任何代码。安全模型见docs/integration/security-boundary.md §8.1。HEICODE_SANDBOX_ISOLATED只允许在真正隔离的 Pod 或 ephemeral CI/test runner 中设置。 - 提交前必须本地通过：
python scripts/test-runtime-contract.py python scripts/test-merge-smoke.py python scripts/test-workflow-e2e.py
Agent / Teammate 协作
- 每个 teammate / agent 必须遵循本
CLAUDE.md与 heicodeDocs。 - 不允许 teammate 跨仓自行修改未声明范围内的代码，或绕过 Manager ↔ Swarm 契约、计费、审计、审批链。
- 多 agent 协作的最终总结需说明各 agent 负责范围、修改文件、风险与未完成项。