Files

T

FastheiandClaude Opus 4.8 aa498fc318 feat(redis): 支持 TLS + 密码 + REDIS_URL（接托管 Redis，如 heicode-rd）

orchestrator/redis_client.py 之前只支持裸 redis.Redis(host,port,db)
明文连接，无法连 Azure Redis Enterprise（强制 TLS + access key）。

改动：
- 新增 REDIS_URL（优先），rediss:// 自动启用 TLS，凭据写在 URL；
  否则用离散 REDIS_HOST/PORT/DB + 可选 REDIS_PASSWORD / REDIS_SSL。
- 完全向后兼容：都不设时维持现有明文 redis-service:6379 行为。
- 凭据只读 env（经 Secret/secret_ref 注入），日志只打脱敏目标，
  绝不输出 URL / 密码。
- 新增 scripts/test-redis-connection-config.py（无需真实 redis）。
- k8s manifest 补 Secret 引用示例；DELIVERY.md 补环境变量表。

验证：新单测 3 项 + REDIS_FAKE 回退 + test-runtime-contract /
test-contract-freeze / test-merge-smoke 全 PASS。

影响范围：仅 agent_swarm（orchestrator 连接层）。
不改 Manager↔Swarm 契约 / 计费 / 审计字段 / 发布链路。
涉及密钥：仅新增「从环境读取」路径，无任何密钥写入代码或日志。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-12 16:50:27 +08:00

9.0 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_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 中应一并说明，并按需清理：

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
```
否则建议删除该文件。文件顶部已加显著警告。
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 流程或移除。

9.0 KiB Raw Blame History Unescape Escape