docs: 新增全量环境变量清单 ENV_VARS.md

整理 agent/、orchestrator/、benchmark/、scripts/、k8s/ 下所有环境变量，
共 65+ 项，含安全敏感标注、解析优先级链和三套最小可运行配置示例。

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/ENV_VARS.md

@@ -0,0 +1,317 @@
+# 环境变量清单（agent_swarm）
+
+> 覆盖范围：`agent/`、`orchestrator/`、`benchmark/`、`scripts/`、`k8s/`。  
+> 所有布尔值：`"1"` / `"true"` / `"yes"` / `"on"`（不区分大小写）均为真。  
+> 带 ⚠️ 的变量为安全敏感项，**必须通过 secret_ref / Key Vault / K8s Secret 注入，禁止明文写入代码或提交记录**。
+
+---
+
+## 目录
+
+1. [必填项（无默认值）](#1-必填项无默认值)
+2. [模型 / API](#2-模型--api)
+3. [Redis](#3-redis)
+4. [Agent 运行时](#4-agent-运行时)
+5. [Git 操作](#5-git-操作)
+6. [Orchestrator 编排](#6-orchestrator-编排)
+7. [Agent 启动器](#7-agent-启动器)
+8. [Kubernetes Pod](#8-kubernetes-pod)
+9. [沙箱 / 代码执行](#9-沙箱--代码执行)
+10. [功能开关](#10-功能开关)
+11. [回调 / 签名 / Secret 解析](#11-回调--签名--secret-解析)
+12. [计费 / 用量归因](#12-计费--用量归因)
+13. [Benchmark 导出](#13-benchmark-导出)
+14. [可观测性 / 追踪](#14-可观测性--追踪)
+15. [运行时元数据](#15-运行时元数据)
+16. [AGNET 系列（向后兼容拼写错误变体）](#16-agnet-系列向后兼容拼写错误变体)
+
+---
+
+## 1. 必填项（无默认值）
+
+不设置则服务无法正常启动或执行任务。
+
+| 变量名 | 说明 |
+|---|---|
+| ⚠️ `OPENAI_API_KEY` | OpenAI 兼容 API 密钥（`sk-*` 格式）。模型调用的主鉴权凭据。 |
+| `GIT_REPO_URL` | Agent 工作区克隆的 Git 仓库地址。未设置时跳过 git 操作。 |
+
+---
+
+## 2. 模型 / API
+
+### 主变量
+
+| 变量名 | 默认值 | 说明 |
+|---|---|---|
+| `OPENAI_MODEL` | `gpt-4o-mini` | 模型 ID，适用于 agent、orchestrator planner、benchmark runner。 |
+| `OPENAI_API_BASE` | `https://api.openai.com/v1` | OpenAI 兼容 API 的 Base URL，兼容 Azure OpenAI / 私有部署。 |
+| `MASTER_REVIEW_MODEL` | 同 `OPENAI_MODEL` | Master/合成评审步骤使用的模型 ID（可单独覆盖）。 |
+| `AGENT_OPENAI_API_BASE` | 同 `OPENAI_API_BASE` | 启动器拉起子 Agent Pod 时注入的 API Base URL 覆盖值。 |
+
+### 备用 fallback 链
+
+以下变量为 fallback 兼容，优先级低于上方主变量：
+
+| 变量名 | 默认值 | 说明 |
+|---|---|---|
+| ⚠️ `MODEL_API_KEY` | — | `OPENAI_API_KEY` 的 fallback。 |
+| `MODEL_NAME` | — | `OPENAI_MODEL` 的 fallback。 |
+| `MODEL_ID` | — | `OPENAI_MODEL` 的第二 fallback。 |
+| `MODEL_API_BASE` | — | `OPENAI_API_BASE` 的 fallback。 |
+| `OPENAI_BASE_URL` | — | benchmark runner 侧 API Base URL fallback。 |
+
+**优先级链**（从高到低）：
+
+```
+OPENAI_API_KEY  >  MODEL_API_KEY  >  错误退出
+OPENAI_MODEL    >  MODEL_NAME     >  MODEL_ID       >  "gpt-4o-mini"
+OPENAI_API_BASE >  MODEL_API_BASE >  OPENAI_BASE_URL >  "https://api.openai.com/v1"
+```
+
+---
+
+## 3. Redis
+
+`REDIS_URL` 优先于所有离散变量。
+
+| 变量名 | 默认值 | 说明 |
+|---|---|---|
+| `REDIS_URL` | — | 完整连接 URL（如 `rediss://user:pass@host:6379`），设置后忽略下方所有离散变量。 |
+| `REDIS_HOST` | `redis-service` | Redis 主机，集群内服务发现名称。 |
+| `REDIS_PORT` | `6379` | Redis 端口。 |
+| `REDIS_DB` | `0` | Redis 逻辑库编号（0–15）。 |
+| ⚠️ `REDIS_PASSWORD` | — | Redis 鉴权密码，无密码时留空。 |
+| `REDIS_SSL` | `false` | 启用 TLS 连接（`true`/`1`/`yes`）。 |
+| `REDIS_CLUSTER` | `false` | 启用 Redis Cluster 模式，多分片部署必须设为 `true`。 |
+| `REDIS_FAKE` | `false` | 使用内存 fakeredis 替代真实 Redis（**仅限开发/CI**）。 |
+| `ALLOW_MEMORY_STORE` | `false` | Redis 不可用时回退到内存存储（**仅限开发/CI**）。 |
+
+---
+
+## 4. Agent 运行时
+
+| 变量名 | 默认值 | 说明 |
+|---|---|---|
+| `ORCHESTRATOR_URL` | `ws://localhost:8000` | Agent 注册并接收任务的 Orchestrator WebSocket URL。 |
+| `AGENT_ID` | 自动生成 UUID | Agent 唯一标识符，不设置时自动生成。 |
+| `AGENT_CAPABILITIES` | `general` | 该 Agent 的能力标签，逗号分隔（如 `python,code_generation,testing`）。 |
+| `WORKSPACE_DIR` | `/workspace` | Agent 执行任务的工作目录。 |
+| `MAX_CONCURRENT_TASKS` | `4` | 单 Agent 最大并发任务数。 |
+| `TASK_TIMEOUT_SECONDS` | `60` | 单任务执行超时（秒），超时后任务被取消。 |
+| `PEER_REPLY_TIMEOUT_SECONDS` | `20` | 等待 Peer Agent 响应的超时（秒）。 |
+| `PEER_CONSULT_MAX_TOKENS` | `500` | Peer 协商 LLM 调用的最大 token 数。 |
+| `HEICODE_USER_ID` | — | 该 Agent 归属的用户 ID，用于按用户 Agent 容量限制。 |
+| `METRICS_PORT` | — | Prometheus metrics HTTP 服务端口，设置后启动 metrics server。 |
+
+---
+
+## 5. Git 操作
+
+| 变量名 | 默认值 | 说明 |
+|---|---|---|
+| `GIT_REPO_URL` | — | 克隆目标仓库地址（见第 1 节）。 |
+| `GIT_BASE_BRANCH` | `main` | PR 和结果分支的基准分支。 |
+| `GIT_USERNAME` | — | Git 鉴权用户名。 |
+| ⚠️ `GIT_PASSWORD` | — | Git 鉴权密码，未设置时 fallback 到 `GIT_TOKEN`。 |
+| ⚠️ `GIT_TOKEN` | — | Git 个人访问令牌，`GIT_PASSWORD` 的替代选项。 |
+
+---
+
+## 6. Orchestrator 编排
+
+| 变量名 | 默认值 | 说明 |
+|---|---|---|
+| `MAX_AGENTS_PER_USER` | `10` | 单用户最大并发 Agent 数，Agent 注册时强制检查。 |
+| `MAX_REVIEW_CYCLES` | `2` | Swarm 运行中最大交叉评审轮次。 |
+| `PLANNER_TIMEOUT_SECONDS` | `45` | Planner LLM 任务分解的超时（秒）。 |
+| `MAX_SUBTASKS` | `6` | Planner 最多创建的子任务数。 |
+| `ENABLE_ACO_DISPATCH` | `false` | 启用 ACO（蚁群优化）概率派发，替代默认贪心派发。 |
+| `ACO_SEED` | — | ACO 随机数种子，设置后派发决策可复现（用于 CI / replay）。 |
+| `BENCHMARK_CAPTURE` | `on` | 采集 benchmark 遥测数据（显式设为 `off` 可关闭）。 |
+| `AGENT_PROPOSAL_BUDGET` | `5` | Agent 自主任务提案（task_proposal）的预算上限。 |
+
+---
+
+## 7. Agent 启动器
+
+| 变量名 | 默认值 | 说明 |
+|---|---|---|
+| `AGENT_LAUNCH_BACKEND` | `none` | 启动后端：`none`（外部管理）、`subprocess`（本地子进程）、`command`（模板命令）、`kubernetes`（K8s Pod）。 |
+| `AGENT_LAUNCH_POOL_SIZE` | `3` | 按用户上限前期望维持的 Agent Pool 大小。 |
+| `AGENT_LAUNCH_CAPABILITIES` | 默认池能力集 | Pool 各 Agent 能力多样性配置，分号分隔每个 Agent 的逗号能力列表。 |
+| ⚠️ `AGENT_LAUNCH_MODEL_KEY` | — | 开发用：覆盖每个 Agent 的模型 API 密钥（**仅限本地开发**）。 |
+| `AGENT_LAUNCH_CMD` | `""` | `command` 后端的模板命令（如 `kubectl run {...}`）。 |
+| `ORCHESTRATOR_PUBLIC_URL` | fallback 到 `AGENT_RUNTIME_WS_URL` 或 localhost | 启动的 Agent Pod 回连 Orchestrator 的公开 WS URL。 |
+| `AGENT_RUNTIME_WS_URL` | — | `ORCHESTRATOR_PUBLIC_URL` 的 fallback WS URL。 |
+| `SECRET_RESOLVER` | `""`（默认 azkv 工作负载身份） | Secret 解析策略：留空用 env map，`azkv` 用 Azure Key Vault。 |
+| `AZURE_FEDERATED_TOKEN_FILE` | — | Azure 工作负载身份令牌文件路径（由 AKS webhook 注入）。 |
+
+---
+
+## 8. Kubernetes Pod
+
+仅 `AGENT_LAUNCH_BACKEND=kubernetes` 时生效。
+
+| 变量名 | 默认值 | 说明 |
+|---|---|---|
+| `AGENT_POD_IMAGE` | `heicode/swarm-agent:latest` | Agent Pod 使用的 Docker 镜像。 |
+| `AGENT_POD_NAMESPACE` | `heicode-swarm` | Agent Pod 所在的 K8s Namespace。 |
+| `AGENT_POD_CPU_REQUEST` | `250m` | Agent Pod CPU 请求量。 |
+| `AGENT_POD_MEM_REQUEST` | `256Mi` | Agent Pod 内存请求量。 |
+| `AGENT_POD_CPU_LIMIT` | `1` | Agent Pod CPU 上限。 |
+| `AGENT_POD_MEM_LIMIT` | `1Gi` | Agent Pod 内存上限。 |
+| `AGENT_POD_SERVICE_ACCOUNT` | — | Agent Pod 使用的 K8s ServiceAccount（RBAC）。 |
+| `K8S_NAMESPACE` | `swarm-system` | 遥测/追踪使用的 K8s Namespace 标记。 |
+
+---
+
+## 9. 沙箱 / 代码执行
+
+> **双门控安全设计**：`ENABLE_QUALITY_EVAL=1` + `HEICODE_SANDBOX_ISOLATED=1` 必须**同时**设置才会执行模型生成代码。缺任意一项则启动拒绝或运行时抛 `SandboxIsolationError`。  
+> `HEICODE_SANDBOX_ISOLATED` **只允许在真正隔离的 K8s Pod 或 ephemeral CI runner 中设置**。
+
+| 变量名 | 默认值 | 说明 |
+|---|---|---|
+| `ENABLE_QUALITY_EVAL` | `false` | 启用质量评估功能（沙箱执行留出测试）。 |
+| `HEICODE_SANDBOX_ISOLATED` | `false` | **显式确认当前运行环境已隔离**，fail-closed 安全门控。 |
+| `SANDBOX_TIMEOUT_SECONDS` | `30` | 沙箱代码执行的挂钟超时（秒）。 |
+| `SANDBOX_CPU_SECONDS` | `20` | 沙箱代码的 CPU 时间限制（POSIX 资源限制，秒）。 |
+| `SANDBOX_MEM_BYTES` | `536870912`（512 MiB） | 沙箱代码内存限制（字节）。 |
+| `SANDBOX_FSIZE_BYTES` | `33554432`（32 MiB） | 沙箱代码输出文件大小限制（字节）。 |
+| `SANDBOX_NPROC` | `64` | 沙箱代码最大子进程数。 |
+
+---
+
+## 10. 功能开关
+
+| 变量名 | 默认值 | 说明 |
+|---|---|---|
+| `ENABLE_ACO_DISPATCH` | `false` | ACO 概率派发（见第 6 节）。 |
+| `ENABLE_QUALITY_EVAL` | `false` | 代码质量评估沙箱（见第 9 节）。 |
+| `ENABLE_SUBTASK_HANDOFF` | `false` | Agent 侧子任务移交（委托给子 Agent）。 |
+| `ENABLE_DISPATCH_SCORE_EVENT` | `false` | 向事件流写出可解释派发评分遥测。 |
+| `ENABLE_AGENT_TASK_PROPOSALS` | `false` | Agent 自主任务提案（P-guard 特性）。 |
+
+---
+
+## 11. 回调 / 签名 / Secret 解析
+
+| 变量名 | 默认值 | 说明 |
+|---|---|---|
+| ⚠️ `AGENT_CALLBACK_SERVICE_TOKEN` | — | Agent Manager 回调鉴权 Service Token。 |
+| ⚠️ `AGENT_CALLBACK_SIGNING_SECRET` | — | Agent Manager 回调 HMAC 签名密钥。 |
+| ⚠️ `AGENT_RUNTIME_SERVICE_TOKEN` | — | Agent Runtime 服务间通信 Token。 |
+| ⚠️ `AZURE_FEDERATED_TOKEN_FILE` | — | Azure 工作负载身份令牌文件路径（见第 7 节）。 |
+| ⚠️ `HEICODE_SECRET_<name>` | — | 动态 Secret 映射，格式 `HEICODE_SECRET_<大写名称>=值`，用于本地开发替代 Key Vault。 |
+
+Secret 解析优先级（`orchestrator/agent_launcher.py`）：
+
+```
+1. AGENT_LAUNCH_MODEL_KEY（开发覆盖，最高优先）
+2. billing_context.secret_ref（Manager 下发的 azkv:// 引用）
+3. HEICODE_SECRET_<name>（本地开发 env map）
+4. Azure Key Vault via AZURE_FEDERATED_TOKEN_FILE（生产）
+5. OPENAI_API_KEY（最终 fallback，仅限开发）
+```
+
+---
+
+## 12. 计费 / 用量归因
+
+| 变量名 | 默认值 | 说明 |
+|---|---|---|
+| `BILLING_SOURCE` | `unknown` | 计费来源标识符，用于用量归因（如 `manager`、`cli`）。 |
+| `MODEL_INPUT_COST_PER_1M` | `0` | 每百万输入 token 费率（USD），用于成本计算。 |
+| `MODEL_OUTPUT_COST_PER_1M` | `0` | 每百万输出 token 费率（USD），用于成本计算。 |
+
+---
+
+## 13. Benchmark 导出
+
+| 变量名 | 默认值 | 说明 |
+|---|---|---|
+| `BENCHMARK_EXPORT_TARGET` | `none` | 导出目标：`none`（禁用）、`cosmos`（Azure Cosmos DB）、`blob`（Azure Blob）。 |
+| ⚠️ `BENCHMARK_COSMOS_CONNECTION_STRING` | — | Azure Cosmos DB 连接字符串。 |
+| `BENCHMARK_COSMOS_DATABASE` | `benchmark` | Cosmos 数据库名。 |
+| `BENCHMARK_COSMOS_CONTAINER` | `selfcert` | Cosmos 容器名。 |
+| `BENCHMARK_BLOB_CONTAINER` | `benchmark-selfcert` | Azure Blob Storage 容器名。 |
+| `BENCHMARK_BLOB_ACCOUNT_URL` | — | Azure Blob Storage 账户 URL。 |
+| ⚠️ `AZURE_STORAGE_CONNECTION_STRING` | — | Azure Storage 连接字符串（Cosmos 或 Blob 共用）。 |
+
+---
+
+## 14. 可观测性 / 追踪
+
+| 变量名 | 默认值 | 说明 |
+|---|---|---|
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4317` | OpenTelemetry OTLP Collector 端点（gRPC）。 |
+| `ENVIRONMENT` | `production` | 部署环境标签，写入遥测（如 `staging`、`dev`）。 |
+| `HOSTNAME` | `unknown` | Pod 主机名，用于遥测识别（通常由 K8s 自动注入）。 |
+
+---
+
+## 15. 运行时元数据
+
+| 变量名 | 默认值 | 说明 |
+|---|---|---|
+| `SWARM_RUNTIME_SOURCE` | `heicode-swarm-runtime` | Swarm Runtime 模块标识名（写入事件信封）。 |
+| `SWARM_RUNTIME_PLATFORM` | `aks` | 平台标识（如 `aks`、`kind`、`local`），写入遥测。 |
+
+---
+
+## 16. AGNET 系列（向后兼容拼写错误变体）
+
+以下变量是历史拼写错误的向后兼容 fallback，**新部署应使用正确拼写的主变量**，这些变体仅作兼容保留：
+
+| 错误变体 | 对应正确变量 |
+|---|---|
+| ⚠️ `AGNET_CALLBACK_SERVICE_TOKEN` | `AGENT_CALLBACK_SERVICE_TOKEN` |
+| ⚠️ `AGNET_CALLBACK_SIGNING_SECRET` | `AGENT_CALLBACK_SIGNING_SECRET` |
+| ⚠️ `AGNET_RUNTIME_SERVICE_TOKEN` | `AGENT_RUNTIME_SERVICE_TOKEN` |
+
+---
+
+## 附：最小可运行配置
+
+### 本地开发（单机，不带 K8s）
+
+```env
+# 必填
+OPENAI_API_KEY=sk-...
+GIT_REPO_URL=https://github.com/your-org/your-repo
+
+# Redis（使用内存 fakeredis）
+REDIS_FAKE=true
+
+# 模型（按需修改）
+OPENAI_MODEL=gpt-4o-mini
+OPENAI_API_BASE=https://api.openai.com/v1
+
+# Orchestrator
+AGENT_LAUNCH_BACKEND=subprocess
+```
+
+### 生产 K8s（AKS）
+
+```env
+# 模型密钥通过 secret_ref / Key Vault 注入，不在此列出
+REDIS_URL=rediss://:password@redis-host:6380
+REDIS_SSL=true
+AGENT_LAUNCH_BACKEND=kubernetes
+AGENT_POD_NAMESPACE=heicode-swarm
+AGENT_POD_SERVICE_ACCOUNT=swarm-agent-sa
+ORCHESTRATOR_PUBLIC_URL=wss://orchestrator.internal/ws
+SWARM_RUNTIME_PLATFORM=aks
+ENVIRONMENT=production
+OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
+```
+
+### 沙箱 / 质量评估（隔离 Pod 内）
+
+```env
+ENABLE_QUALITY_EVAL=1
+HEICODE_SANDBOX_ISOLATED=1   # 仅在已确认隔离的 Pod 中设置
+SANDBOX_TIMEOUT_SECONDS=30
+SANDBOX_MEM_BYTES=536870912
+```