Agentswarm/docs/ENV_VARS.md

环境变量清单（agent_swarm）

覆盖范围：agent/、orchestrator/、benchmark/、scripts/、k8s/。
所有布尔值："1" / "true" / "yes" / "on"（不区分大小写）均为真。
带 ⚠️ 的变量为安全敏感项，必须通过 secret_ref / Key Vault / K8s Secret 注入，禁止明文写入代码或提交记录。

---

目录

1. 必填项（无默认值）
2. 模型 / API
3. Redis
4. Agent 运行时
5. Git 操作
6. Orchestrator 编排
7. Agent 启动器
8. Kubernetes Pod
9. 沙箱 / 代码执行
10. 功能开关
11. 回调 / 签名 / Secret 解析
12. 计费 / 用量归因
13. Benchmark 导出
14. 可观测性 / 追踪
15. 运行时元数据
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	cosmos,blob	导出目标（逗号分隔可组合）：none（禁用）、cosmos（Azure Cosmos DB）、blob（Azure Blob）。默认同时写入两者；凭据缺失时自动降级为 noop 并打 warning。
⚠️ 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）

# 必填
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）

# 模型密钥通过 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 内）

ENABLE_QUALITY_EVAL=1
HEICODE_SANDBOX_ISOLATED=1   # 仅在已确认隔离的 Pod 中设置
SANDBOX_TIMEOUT_SECONDS=30
SANDBOX_MEM_BYTES=536870912