用途：在本地对 agent-swarm 做完整端到端测试，使用真实 API 服务器与 Docker lead/worker 容器。适用于用户主动要求 QA，或在改动 API、runner、轮询、任务生命周期、会话日志、Docker entrypoint、worker/lead 行为后主动验证。可按 diff 选择相关子集，不必跑全部步骤。
前置条件：OrbStack 或 Docker Desktop 运行中；.env 配置 API_KEY 与 PORT；.env.docker-lead 配置 AGENT_ID、CLAUDE_CODE_OAUTH_TOKEN、MCP_BASE_URL；.env.docker 配置 AGENT_ID、CLAUDE_CODE_OAUTH_TOKEN 或 OPENROUTER_API_KEY、MCP_BASE_URL。
主要流程：先用 grep ^PORT= .env 确认端口，并核对两个 Docker env 文件的 MCP_BASE_URL 指向 http://host.docker.internal:$PORT；清理数据库并启动 API 服务器，需带 DESPLEGA_TELEMETRY_ENV=test；用 bun run docker:build:worker:slim 构建镜像；分别启动 lead 与 worker 容器，容器名建议带分支名避免冲突，等待约 15 秒后查看日志确认出现 Polling 信息；通过 /api/agents 验证注册状态并保存 agent ID。
任务与验证：创建任务时用 agentId 指定分配（用 assignedTo 会静默变成未分配任务）；不指定 agentId 的池任务由 worker 自动认领，lead 不认领池任务。可轮询 /api/tasks/<id> 查看 pending→in_progress→completed/failed，用 /api/tasks/<id>/session-logs 校验日志数量与 sessionId 隔离。UI 可用 cd apps/ui && bun run dev 启动，并用 agent-browser 做可视化检查。
清理与限制：用 docker stop 停止容器，用 lsof -ti :$PORT | xargs kill 停止 API 与 UI。注意轮询端点为 GET /api/poll 且需 X-Agent-ID；直接 API 取消任务不会终止 Docker 内 Claude 进程，需 docker restart；E2E 任务应保持简单，避免浪费时间和 API 额度。