# CLAUDE.md — HeiCode Swarm（执行面 / 运行时）

本仓库（`agent_swarm_v6`，对应 **HeiCode-Swarm**）是蜂群执行面 / 回调 / Swarm Runtime。整体介绍见 [README.md](README.md)，工程标准见 [PROJECT_STANDARD.md](PROJECT_STANDARD.md)，交付说明见 [docs/DELIVERY.md](docs/DELIVERY.md)。

## 改动前必读
1. 先读本 `CLAUDE.md` 与本仓 `PROJECT_STANDARD.md`。
2. **heicodeDocs 是唯一标准源**；涉及产品/工程/Agent/Swarm/计费/安全/交付标准时，先读取 heicodeDocs 对应标准文件。
3. 跨端或动 Manager ↔ Swarm 接口时，必须先读 `heicode-mananger/docs/heicode.md` 与 `docs/integration/` 契约。
4. 不确定标准时，**先停止修改并要求提供标准路径**；发现文档与代码冲突时，**输出冲突点**，不得自行选择一方。

## 仓库边界
- 只允许修改 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）。已删除：Master `planner` 分解兜底、贪心/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
  python scripts/test-contract-freeze.py   # Manager/client 契约冻结（sequence + 13 事件 + artifact，#14/#15）
  ```
- **Manager/客户端契约冻结（FROZEN v1）**：回调 envelope 带 per-swarm 严格递增 `sequence`；客户端 13 类事件冻结于 `swarm_runtime.FROZEN_CLIENT_EVENT_TYPES`（task.* / handoff.created / approval.requested|approved|rejected / artifact.created / swarm.completed|failed|stopped）；artifact 扁平字段 `{uri,checksum,task_id,size_bytes?,created_at}`；状态机映射见 `docs/integration/runtime-contract.md §4.1`。改动这些字段/类型/状态前必须先读 `docs/integration/{event-schema,runtime-contract}.md` 并同步 HM（agent_swarm#14/#15）。

## Agent / Teammate 协作
- 每个 teammate / agent 必须遵循本 `CLAUDE.md` 与 heicodeDocs。
- 不允许 teammate 跨仓自行修改未声明范围内的代码，或绕过 Manager ↔ Swarm 契约、计费、审计、审批链。
- 多 agent 协作的最终总结需说明各 agent 负责范围、修改文件、风险与未完成项。