Agentswarm/docs/DELIVERY.md

# 交付说明（Delivery Guide）

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

---

## 二、构建

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

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

### 桌面客户端
```bash
cd desktop-client
npm install
npm run build
```

---

## 三、部署（Kubernetes）

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

```bash
# 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](../orchestrator/README.md)、[agent](../agent/README.md)。

---

## 五、验收与验证

### 1) 自动化测试（无需 Redis 服务器，也无需模型密钥）
```bash
# 在 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) 端到端工作流测试（自动、确定性、无需密钥）
```bash
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](../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/` 重新生成：
   ```bash
   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 流程或移除。