# 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 负责范围、修改文件、风险与未完成项。

---

# 本地测试环境 & 交接（LOCAL TEST & HANDOFF）

> 本节供**换机/新会话续接**。这是 `xmindlab-heicode/agent_swarm` 的**本地测试快照**(镜像 + #7 实验改动),非主仓权威。**所有密钥只列「清单+出处」,绝不写明文**(组织规则 #8)。线上/主仓以 GitHub 为准。

## 本快照相对上游 main 的本地改动
1. **#7 自底向上分解(让一个任务铺到多 agent)** — `agent/main.py` `propose_task()`(发 WS `task_proposal`)+ `agent/task_executor.py` `_maybe_propose_subtasks()`(种子用 `_parse_task` 拆分→逐个提案入池→其他 agent 自选)。仅顶层种子提案,子任务不递归(无环)。`ENABLE_AUTONOMOUS_PROPOSALS` 默认 on。
2. **`_parse_task` 健壮化** — `max_tokens` 可配 `AGENT_PLAN_MAX_TOKENS`(本快照默认 **65536**;**生产热修用 32768**,因部分模型网关上限 32768,>之 400)+ `_coerce_subtasks` 宽容解析 + 失败重试 + 日志。
3. **提案子任务 `required_capabilities=[]`** — 否则 LLM 给的具体能力非固定能力池子集 → 永远派不出 → 卡 PENDING(派发死锁修复)。
4. **`orchestrator/agent_launcher.py`** — `ENABLE_SUBTASK_HANDOFF` 透传给 agent(测 handoff 旁路用)。
5. **`k8s/orchestrator-local.yaml`** — 本地部署清单(下方)。
> 主仓对应:#75(根因)/ #76(PR,默认 65536)。本快照是本地验证版,未必与 #76 完全一致。

## 本地部署(Docker Desktop k8s,kind 式;arm64)
**镜像(本机构建,arm64;Docker Hub 走 mirror `https://8cz1yribqx6cws.xuanyuan.run`,见 `~/.docker/daemon.json`)**
```
docker build -f Dockerfile.orchestrator -t swarm-orchestrator:local .
docker build -f Dockerfile.agent -t swarm-agent:local .
# kind 集群不共享宿主镜像 → 导入每个节点:
for img in swarm-orchestrator:local swarm-agent:local redis:7-alpine; do
  docker save "$img" -o /tmp/i.tar
  for n in desktop-control-plane desktop-worker desktop-worker2 desktop-worker3; do
    docker exec -i "$n" ctr -n k8s.io images import - < /tmp/i.tar; done; done
```
**部署(kubectl apply 在本机权限被禁 → 用 create/set/delete)**
```
kubectl create namespace swarm-system
kubectl -n swarm-system create secret generic swarm-model-key --from-literal=OPENAI_API_KEY=<模型KEY>   # 见密钥清单
kubectl create -f k8s/rbac/
kubectl create -f k8s/redis-statefulset.yaml
kubectl create -f k8s/orchestrator-local.yaml
kubectl -n swarm-system port-forward svc/orchestrator-service 8000:8000   # → http://localhost:8000(本地无鉴权)
```
`orchestrator-local.yaml` 关键 env:`OPENAI_API_BASE/AGENT_OPENAI_API_BASE=<LLM网关/v1>`、`OPENAI_MODEL=<模型id>`、`OPENAI_API_KEY`(secretKeyRef→swarm-model-key)、`REDIS_HOST=redis-service`、`AGENT_LAUNCH_BACKEND=kubernetes`、`AGENT_POD_IMAGE=swarm-agent:local`、`AGENT_LAUNCH_MIN_POOL/POOL_SIZE=16`/`MAX_POOL=64`/`MAX_AGENTS_PER_USER=64`、`AGENT_PROPOSAL_BUDGET=8`(无 `SECRET_RESOLVER`,本地不走 azkv)。
**绑 git 仓**:create 请求里 `resource_grants[{resource_type:git, secret_ref:"azkv://local/secrets/<name>", metadata:{repo_url,base_branch}}]`;本地无 Azure → 在 orchestrator 设 `HEICODE_SECRET_<name>='{"git_username":..,"git_password":..}'`(dev 解析)。pod 连宿主服务用 kind 网关 `172.19.0.1`。

## 外部底座(本次新增,待接进蜂群 = Phase 3/4 未做)
- **OpenSandbox**(沙盒,代码执行):`uv venv --python 3.11` → `uv pip install opensandbox-server` → `opensandbox-server init-config ~/.sandbox.toml --example docker-zh` → `OPENSANDBOX_INSECURE_SERVER=YES opensandbox-server`(`127.0.0.1:8080`,docker 运行时)。SDK `opensandbox`(`SandboxSync.create(image, connection_config=ConnectionConfigSync(domain="127.0.0.1:8080",protocol="http"))` → `.commands.run(...)`)。
- **jina MCP**(搜索/web 工具):托管 `https://mcp.jina.ai/v1`(Streamable HTTP,`Authorization: Bearer <JINA_API_KEY>`),21 工具(search_web/read_url/…)。Python:`mcp` 包 `streamablehttp_client` + `ClientSession`。

## 密钥清单(只列出处,值自行获取/轮换;勿写明文)
| 用途 | 来源 / 重建方式 |
|---|---|
| 模型 key(`sk-`,放 k8s secret `swarm-model-key`) | 模型网关后台(api.heicode.cc / code.heicode.cc);**建议新建,勿复用已暴露的** |
| `JINA_API_KEY`(jina MCP) | Jina 后台;**对话中已暴露,务必吊销换新** |
| git 凭据(`HEICODE_SECRET_<name>` 的 username/password) | 你的 gitea(gitee.ath.cx) |
| Azure(ACR/AKS) | 新机 `az login`(不导 token) |
| Docker mirror / gitea / ugdocker 镜像仓 | 当前为开放/已认证,无需单独凭据 |

## 当前状态 / 未完成
- ✅ 本地 fan-out 验证:种子→拆 N 子任务→N 个不同 agent 并行(#7 通)。✅ 生产热修(agent 镜像 `swarm-agent:p75-mt32768`,池8/预算8)。
- ✅ OpenSandbox 本地起+执行验证;✅ jina MCP 托管验证。
- ⬜ Phase 3:agent 接 jina MCP(MCP client + function-calling)。⬜ Phase 4:代码执行走 OpenSandbox。
- ⚠️ 架构缺口(见 issue 备选):蜂群只 fan-out 不 convergence——产物碎在各结果分支、无合并/聚合(无 ResultAggregator);评审循环封顶 `MAX_REVIEW_CYCLES=2`(非迭代到最优);`master_agent.synthesize` 仅文字汇总,不整合代码。

## 换机续接
- 代码:本仓(`xiaohei/Agentswarm` @ gitee.ath.cx)。镜像:`app-40967-lovecc.cn23.ugdocker.link/swarm-{orchestrator,agent}:local`(**arm64**;amd64 环境需重构建)。
- Claude 会话记录/记忆在旧机 `~/.claude/projects/.../`(transcript)与 `~/.claude/.../memory/`,如需原样搬可拷贝(注意其中可能含敏感信息,自行甄别)。