Minimal Swarm Loop

这是一个独立的最小蜂群闭环原型，不接入 Heicode Manager 主项目，也不修改现有 API。

目标是先把蜂群的四个共享资源跑通：

1. 任务池：记录待执行、执行中、完成和失败的任务。
2. 信息素 / 得分：记录每个候选方案或 Agent 的分数，用于下一轮选择。
3. 共享状态：保存蜂群运行中的事实、锁、心跳和阶段状态。
4. 结果收敛：聚合多个 Agent 的结果，选择最终答案。

最小闭环

submit goal
  -> seed tasks
  -> agents claim tasks
  -> agents emit observations
  -> update pheromone scores
  -> write shared state
  -> converge result

默认实现使用内存存储，方便本地验证。Azure 资源模式通过可选依赖启用，真实连接信息只从环境变量读取。

Azure 资源映射

MVP 不使用 NATS，也不使用 Cosmos DB。

共享资源	MVP 存储	Azure 资源
任务池	PostgreSQL 表 + Redis Streams 通知	Azure Database for PostgreSQL Flexible Server、Azure Cache for Redis
信息素 / 得分	PostgreSQL 历史表 + Redis Sorted Set 热分数	Azure Database for PostgreSQL Flexible Server、Azure Cache for Redis
共享状态	PostgreSQL 状态表 + Redis 锁 / 心跳	Azure Database for PostgreSQL Flexible Server、Azure Cache for Redis
结果收敛	PostgreSQL 结果表 + Blob 工件	Azure Database for PostgreSQL Flexible Server、Azure Blob Storage

运行层建议：

• Azure Kubernetes Service：运行 swarm coordinator 和 worker。
• Azure Container Registry：保存自定义 worker 镜像，可选但推荐。
• Azure Key Vault 或 OpenBao：保存数据库、Redis、Blob、模型供应商密钥。
• Azure Monitor / Log Analytics：日志、指标、告警和收敛过程观测。

本地运行

cd swarm-minimal
python3 -B examples/run_demo.py
python3 -B -m unittest discover -s tests

Agnet / NewAPI 测试

NewAPI 连接使用 OpenAI-compatible /v1/chat/completions 形式。真实 key 只通过环境变量注入：

export NEWAPI_BASE_URL=<newapi-base-url>
export NEWAPI_API_KEY=<newapi-api-key>
# optional for single-model demo only
# export NEWAPI_MODEL=<openai-compatible-model>

python3 -B examples/run_newapi_agnet_demo.py

也可以在本机创建 swarm-minimal/.env，demo 会自动读取；该文件已被 .gitignore 忽略：

NEWAPI_BASE_URL=<newapi-base-url>
NEWAPI_API_KEY=<newapi-api-key>
# optional for single-model demo only
# NEWAPI_MODEL=<openai-compatible-model>

三模型测试会先请求模型列表，选择 3 个不同模型，然后创建 3 个 Agnet 分别调用：

python3 -B examples/run_three_newapi_agnets.py

模型发现会依次尝试 /v1/models、/models、/model。单元测试不会连接真实 NewAPI，会用 mock 验证请求 URL、鉴权头、payload、模型选择和蜂群收敛行为。

完整 live 测试会同时使用 Azure PostgreSQL / Redis / Blob 和 NewAPI 三模型 Agnet：

python3 -B examples/run_full_live_test.py

如果还没有导出环境变量，也可以使用交互式入口在本机输入，并可选择保存到被忽略的 .env：

python3 -B examples/run_full_live_test_interactive.py

Azure 资源模式

真实密钥不要写入仓库。先复制占位模板到自己的本地环境文件，填入轮换后的值，或直接在 shell 中 export：

cd swarm-minimal
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements-azure.txt

export PGHOST=<postgres-host>
export PGUSER=<postgres-user>
export PGPORT=5432
export PGDATABASE=<postgres-database>
export PGPASSWORD=<postgres-password>
export SWARM_REDIS_CONNECTION_STRING='<redis-host>:6380,password=<redis-key>,ssl=True,abortConnect=False'
export AZURE_STORAGE_CONNECTION_STRING='DefaultEndpointsProtocol=https;AccountName=<account-name>;AccountKey=<account-key>;EndpointSuffix=core.windows.net'
export SWARM_BLOB_CONTAINER=swarm-artifacts

python3 -B examples/run_azure_demo.py

examples/run_azure_demo.py、examples/run_newapi_agnet_demo.py、examples/run_three_newapi_agnets.py 和 examples/run_full_live_test.py 都会自动读取本地私有 swarm-minimal/.env。

如果连接字符串、数据库密码、Redis key 或 Storage account key 曾经出现在聊天、日志、截图或提交记录里，应在 Azure 侧轮换后再长期使用。

文件说明

• swarm_minimal/core.py：最小蜂群闭环逻辑。
• swarm_minimal/config.py：从环境变量读取 PostgreSQL、Redis、Blob 配置，并只输出脱敏摘要。
• swarm_minimal/local_env.py：读取本地私有 .env，不依赖第三方 dotenv 包。
• swarm_minimal/azure_store.py：可选 Azure 后端，使用 PostgreSQL、Redis Streams / Sorted Set 和 Blob Storage。
• swarm_minimal/azure_resources.py：Azure 资源需求清单。
• swarm_minimal/newapi_agnet.py：NewAPI / OpenAI-compatible Agnet 适配器。
• examples/run_demo.py：一轮可运行演示。
• examples/run_azure_demo.py：使用真实 Azure 资源的一轮演示。
• examples/run_newapi_agnet_demo.py：使用 NewAPI Agnet 替换 verifier 的一轮演示。
• examples/run_three_newapi_agnets.py：发现模型后用 3 个不同模型 Agnet 跑测试。
• examples/run_full_live_test.py：使用 Azure 后端和 3 个 NewAPI 模型 Agnet 的完整 live 测试。
• examples/run_full_live_test_interactive.py：本机交互式输入密钥并运行完整 live 测试。
• tests/test_minimal_swarm.py：闭环和资源约束测试。
• tests/test_newapi_agnet.py：NewAPI Agnet 的 mock 测试。