xiaohei/Agentswarm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
Agentswarm/CLAUDE.md
T
local 169e82ce02
CI / tests (push) Failing after 14m36s
Details
CI / guardrails (push) Failing after 14m37s
Details
docs(CLAUDE.md): 追加本地测试&交接段(部署/底座/密钥清单[无值]/状态/换机续接)
2026-06-17 13:06:01 +08:00

10 KiB
Raw Permalink Blame History

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

本仓库（agent_swarm_v6，对应 HeiCode-Swarm）是蜂群执行面 / 回调 / Swarm Runtime。整体介绍见 README.md，工程标准见 PROJECT_STANDARD.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/,如需原样搬可拷贝(注意其中可能含敏感信息,自行甄别)。
Reference in New Issue View Git Blame Copy Permalink