xiaohei/Agentswarm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e263dae11502387a7661da882a92addc92edb604
Agentswarm/docs/DELIVERY.md
T
FastheiandClaude Opus 4.8 35aab3a643 feat(redis): 加 REDIS_CLUSTER 支持 OSS Cluster 端点（heicode-rd 必需） 
heicode-rd（Azure Redis Enterprise）database clusteringPolicy=OSSCluster，
裸 redis.Redis 客户端在多分片下 keys()/跨 slot 操作会误路由/抛 MOVED。

- REDIS_CLUSTER truthy → 用 redis.asyncio.cluster.RedisCluster（URL 或
  host/port 两种入参，密码/TLS 同样支持）。cluster 模式无 DB select，
  REDIS_DB 被忽略（仅逻辑 DB0）。
- 不设时维持 standalone 行为，完全向后兼容。
- 测试加 cluster 用例；manifest/DELIVERY 补 REDIS_CLUSTER 说明。

验证：连接配置单测 4 项 + REDIS_FAKE 回退 + test-runtime-contract /
test-contract-freeze / test-merge-smoke 全 PASS。

影响范围：仅 agent_swarm orchestrator 连接层；不改契约/计费/审计/密钥落地。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-12 17:00:37 +08:00

9.2 KiB
Raw Blame History

交付说明（Delivery Guide）

本文件说明 Agent Swarm（agent_swarm_v5） 的交付物、构建/部署方式、配置项、验收方法，以及本次交付对各链路的影响与合规要求。系统总体介绍见根目录 README.md。

一、交付物清单

类别 内容 位置
编排器 FastAPI 编排服务（分解/派发/协作/评审/汇总、Manager 对接） orchestrator/
执行单元 Agent 运行时（WebSocket、并发、OpenAI 执行、Git 提交） agent/
桌面客户端 Electron + React 客户端（提交/分析/看板/聚合） desktop-client/
容器镜像定义 Agent 与编排器的 Dockerfile Dockerfile.agent、Dockerfile.orchestrator
部署清单 Redis、编排器、Agent、RBAC、监控等 K8s 清单 k8s/
部署脚本 一键部署脚本 scripts/deploy-orchestrator.sh、scripts/deploy-agent.sh
测试 契约校验与工作流冒烟测试 scripts/test-runtime-contract.py、scripts/test-merge-smoke.py
数据集 复杂度分析标注数据集 test-data/complexity-dataset.json
文档 各组件 README 与本交付说明 README.md、各目录 README.md、doc/

交付不包含任何密钥、令牌、.env 或证书。凭据由部署环境 / secret_ref / Key Vault 注入。

二、构建

容器镜像

# 编排器镜像
docker build -f Dockerfile.orchestrator -t agent-swarm-orchestrator:<tag> .

# Agent 镜像
docker build -f Dockerfile.agent -t agent-swarm-agent:<tag> .

桌面客户端

cd desktop-client
npm install
npm run build

三、部署（Kubernetes）

按以下顺序部署（具体清单见 k8s/）：

# 1) 命名空间与 RBAC
kubectl apply -f k8s/test-namespace.yaml
kubectl apply -f k8s/rbac/

# 2) Redis（权威状态存储）
kubectl apply -f k8s/redis-statefulset.yaml

# 3) 编排器
kubectl apply -f k8s/orchestrator-deployment.yaml

# 4) Agent（按需扩缩）
kubectl apply -f k8s/agent-deployment-v2.yaml

也可使用脚本：scripts/deploy-orchestrator.sh、scripts/deploy-agent.sh。

凭据（必须经 secret_ref / K8s Secret 注入，禁止明文）：

  • 模型访问：OPENAI_API_KEY（OpenAI 兼容；如使用自定义端点另配 OPENAI_API_BASE）。
  • Git 推送：GIT_USERNAME / GIT_PASSWORD（或 GIT_TOKEN）。
  • 服务间鉴权与回调签名：AGENT_RUNTIME_SERVICE_TOKEN、AGENT_CALLBACK_SERVICE_TOKEN、AGENT_CALLBACK_SIGNING_SECRET。

注意：模型后端为 OpenAI 兼容。部署时请确保以 OPENAI_* 凭据注入 Agent 与编排器，并据此核对/更新 Secret 与清单中的环境变量。

四、配置（环境变量与开关）

变量 作用 备注
REDIS_HOST / REDIS_PORT / REDIS_DB Redis 连接（明文） 生产必需（或用 REDIS_URL）
REDIS_URL 完整连接串，优先于上面离散变量；rediss:// 启用 TLS，凭据写在 URL 里 用托管 TLS Redis（Azure Cache / Redis Enterprise）时设置；经 Secret/secret_ref 注入，勿内联
REDIS_PASSWORD / REDIS_SSL 离散方式的密码 / 启用 TLS（truthy） 配合 REDIS_HOST 用；密码经 Secret 注入
REDIS_CLUSTER 用 Redis Cluster 协议端点（truthy） 连 Azure Redis Enterprise（clusteringPolicy=OSSCluster）必设，否则多分片下 keys()/跨 slot 误路由
REDIS_FAKE / ALLOW_MEMORY_STORE 内存回退 仅开发/CI，生产禁用
ENABLE_PLANNER_FALLBACK 无 Manager 分工时启用规划回退 默认关闭
ENABLE_REVIEW_LOOP / MAX_REVIEW_CYCLES 主控评审/重做循环 + 汇总 默认关闭 / 默认 2
ENABLE_SUBTASK_HANDOFF 动态子任务移交 默认关闭
OPENAI_API_KEY / OPENAI_API_BASE / OPENAI_MODEL 模型访问 Agent 与编排器规划/评审共用
AGENT_RUNTIME_SERVICE_TOKEN 等 鉴权与回调签名 与 Manager 契约相关
MAX_CONCURRENT_TASKS / TASK_TIMEOUT_SECONDS Agent 并发与超时 Agent 侧
OTEL_EXPORTER_OTLP_ENDPOINT 等 链路追踪 可选

各组件完整变量见对应 README：orchestrator、agent。

五、验收与验证

1) 自动化测试（无需 Redis 服务器，也无需模型密钥）

# 在 agent_swarm_v5 目录下
set "REDIS_FAKE=1"
python scripts/test-runtime-contract.py   # Manager 契约校验
python scripts/test-merge-smoke.py          # 机制级冒烟测试（评审 / 协作 / 汇总等，32 项）

验收标准：两者均通过（contract checks passed / all merge smoke checks passed）。

2) 端到端工作流测试（自动、确定性、无需密钥）

python scripts/test-workflow-e2e.py

该脚本在进程内启动真实编排器（uvicorn + 内存存储），通过真实 WebSocket 接入一个无需密钥的桩 Agent（scripts/stub_agent.py），提交一个目标，并逐项断言完整工作流：

断言 对应工作流步骤
生成 3 个专家任务且角色为 实现/测试/文档 主控分解为多专家任务
每个任务均完成 子 Agent执行
至少发生一次主控评审循环 主控评审并退回重做
运行最终 completed 循环直至达标
存在统一的最终汇总 专家产出汇总为最终回答

确定性来源：规划/评审/汇总被强制离线（静态分解 + 启发式评审 + 拼接汇总），桩 Agent 在首次「测试」任务返回冲突框架（unittest）、重做时返回对齐框架（pytest），从而稳定地触发一次评审重做后通过。

验收标准：输出 workflow follows the expected sequence: ...，退出码 0。

3) 端到端工作流演示（真实 Agent + 模型）

启动编排器（开启 REDIS_FAKE、ENABLE_PLANNER_FALLBACK、ENABLE_REVIEW_LOOP）与至少一个真实 Agent（.env 提供 OPENAI_API_KEY），提交需求，按 GET /api/swarms/{id}/tasks | /logs | /workflow 确认：分解 → 派发执行 →（评审/重做）→ 汇总交付。详细步骤见根目录 README.md 的「快速开始」。

辅助工具：scripts/stub_agent.py 是无需密钥的桩 Agent，可单独运行以对手动启动的编排器做 Tier-3 联调（设置 ORCHESTRATOR_URL / AGENT_ID / AGENT_CAPABILITIES 后 python scripts/stub_agent.py）。

六、交付影响说明

依据组织规范，本次交付影响范围如下（PR 中需复述）：

链路 是否影响 说明
Client（桌面客户端） 是 提交/分析/看板/聚合
Manager 否（契约保持） 面向 Manager 的接口、回调、审批链均保留
Swarm（编排器 + Agent） 是 新增分解/协作/评审/汇总能力，均默认关闭
Agent 是 OpenAI 执行、并发、重连、超时、取消、协作
CodeGW 否 无改动
计费 是（字段保留） 模型用量归属（usage 与归属头）保留；模型后端改为 OpenAI 兼容
密钥 是 需以 secret_ref 注入 OPENAI_* 等凭据
审计 否（契约保持） 事件与签名回调结构保留
发布链路 否 不涉及非 dev release 仓库的业务改动

七、安全与合规

  • 禁止将密钥、令牌、云凭据、.env、证书写入代码、日志、Markdown 或提交记录。
  • 凭据仅经部署环境 / secret_ref / Key Vault 注入；.env 已被 .gitignore 忽略，仅供本地开发。
  • 涉及鉴权、审批链、计费、审计的改动须遵循 Manager 安全规则与组织标准。
  • 生产环境必须使用真实 Redis；严禁开启内存回退（REDIS_FAKE / ALLOW_MEMORY_STORE）。

八、回退与运维

  • 回退：所有新增工作流能力（规划回退、评审循环、子任务移交）均由环境开关控制，关闭后行为回到基础的「Manager 编排 + 单任务执行」语义。
  • 可观测性：编排器与 Agent 暴露 Prometheus 指标（编排器 GET /metrics），可接入 k8s/prometheus-config.yaml 与 k8s/grafana-dashboard.json。
  • 健康检查：GET / 与 GET /health（含 Redis 连接状态与活跃连接数）。

九、已知事项与遗留项

以下为已知的陈旧/遗留资产，PR 中应一并说明，并按需清理：

  1. k8s/orchestrator-source-configmap.yaml 为陈旧快照（请勿用于当前部署）。 该 ConfigMap 内嵌的是旧版编排器源码（无规划/评审/汇总）。正式部署走镜像方式（Dockerfile.orchestrator → k8s/orchestrator-deployment.yaml，swarm-orchestrator:latest）。如确需源码挂载部署，请从 orchestrator/ 重新生成：

    kubectl create configmap orchestrator-source --from-file=orchestrator/ --dry-run=client -o yaml

    否则建议删除该文件。文件顶部已加显著警告。

  2. scripts/test-agent.py 为遗留测试脚本。 它针对旧版 Anthropic 初始化流程（使用占位密钥 sk-ant-test-...），与当前 OpenAI 运行时不一致，且不属于当前测试套件（scripts/test-runtime-contract.py、scripts/test-merge-smoke.py、scripts/test-workflow-e2e.py）。后续应更新为 OpenAI 流程或移除。

Reference in New Issue View Git Blame Copy Permalink