Songhaoz666andClaude Opus 4.8
15fe5d379b
回应 HM 驾驶舱（heicode-mananger #28/#45/#46）经 agent_swarm#14（runtime-contract）
+ #15（event-schema）提出的消费需求。HM 只读查询已落地（HM PR #53），唯一前置是本
仓契约冻结。本 PR 把回调契约冻结为 v1 并落代码 + 测试。
代码（orchestrator/）：
- swarm_runtime.emit_event：回调 envelope 新增 **per-swarm 严格递增 `sequence`**
（INCR 计数键 swarm_event_seq:{swarm_id}，从 1、无空洞，供客户端 events?after= 去重/续传）。
- 新增冻结的客户端 13 类事件（FROZEN_CLIENT_EVENT_TYPES）中此前缺的 6 类，均**附加**发出
（不动既有 deployment.status_changed，HM 仍用其更新 AgentDeployment.Status）：
· swarm.completed/failed（refresh_swarm_run_status 终态）、swarm.stopped（stop_run）；
· approval.approved/rejected（record_approval_decision 决定落地）；
· handoff.created（child 任务建立时）。
- artifact.created envelope 补扁平字段：created_at（默认 occurred_at）、task_id（回填）、
size_bytes 透传（未知则省略，不伪造，规则 #9）。
- redis_client 新增原子 incr（真实 + 两处 fake stub）。
文档（docs/integration/，FROZEN v1）：
- event-schema.md：envelope sequence、artifact 扁平字段、事件注册表标注 ⭐13 类 + 新增 6 类、
对齐状态更新（title/threshold_pct/sequence/artifact 已在 emit 统一处理）。
- runtime-contract.md：冻结 stop 端点 + ID 映射；§4.1 新增**状态机映射表**——运行时不臆造
preparing/degraded/verifying（规则 #9），由 HM/客户端按表映射真实状态
（blocked→degraded、评审期→verifying 等）；终态另发 swarm.* 事件。
测试：
- 新增 scripts/test-contract-freeze.py（hermetic）：sequence 单调/每-swarm/无空洞、13 类
round-trip、artifact 形状（含未知 size 不伪造）、approval.*/swarm.stopped 真实发出、
明文凭据脱敏而 azkv secret_ref 透传。接入 CI + CLAUDE.md 提交前清单。
- test-workflow-e2e.py：全流程 e2e 额外断言 swarm.completed + sequence 无空洞。
- 两处 FakeRedis stub 补 incr。
影响范围：仅 agent_swarm（orchestrator + docs/integration + 测试 + CI + CLAUDE.md）。
- Manager：回调**新增** sequence 字段与 6 类事件——向后兼容（旧消费方忽略新字段/新类型即可）；
HM 注册表需登记新 6 类方能对外暴露（agent_swarm#15.2，已在 doc 列为剩余项）。
- 计费/审计：不涉及（查询面不计费由 HM 保证；本仓未改计费/审计字段）。
- 密钥：envelope 不含明文凭据；secret_ref 仍为 azkv 引用，HM 对客户端再脱敏。
Refs #2
Refs #14
Refs #15
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
42 lines
4.9 KiB
Markdown
42 lines
4.9 KiB
Markdown
# 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 负责范围、修改文件、风险与未完成项。
|