fengqun/README.md

Minimal Swarm Loop

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

当前状态

本仓库已经补齐最小 Agent / 蜂群 Agent 标准化测试闭环。这里的标准不是普通软件开发质量标准，而是围绕 Agent 的任务理解、上下文承接、模型选择、工具边界、敏感信息保护、可观测性、handoff、信息素协作、收敛和马尔可夫式状态转移建立的 AQS / SW-AQS v1。

最新 live 标准矩阵已通过：

{
  "run_id": "063632eeb17b45c197aa866066158667",
  "completed_tasks": 7,
  "accepted_score": 1.0,
  "check_count": 12,
  "failed_checks": []
}

主要报告入口都放在 docs/，完整索引见 docs/README.md：

• docs/AGENT_SWARM_QUALITY_STANDARD.zh-CN.md：Agent / 蜂群 Agent 质量标准、测试标准来源、S07 任务分配和接手机制。
• docs/ACADEMIC_STANDARD_TEST_REPORT.zh-CN.md：测试场景、测试过程、测试结果、算法清单和马尔可夫过程判定。
• docs/MODEL_AGNET_IO_REPORT.zh-CN.md：每个模型 / Agnet 的任务、输入、输出、评分和交接过程。
• docs/STANDARD_TEST_MATRIX.md：S01-S07 标准矩阵。
• docs/INDUSTRY_STANDARD_AGNET_TEST_PLAN.md：行业参考框架到本项目标准的映射。

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

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：日志、指标、告警和收敛过程观测。

本地运行

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

标准化测试入口：

python3 -B -m py_compile swarm_minimal/*.py examples/*.py tests/*.py
python3 -B -m unittest discover -s tests
python3 -u -B examples/run_academic_standard_evaluation.py

完整 live 标准矩阵需要本机被忽略的 .env 中提供 Azure PostgreSQL、Redis、Blob 和 NewAPI 测试凭据：

python3 -u -B examples/run_standard_scenario_acceptance.py

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

也可以在本机创建项目根目录 .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 都会自动读取本地私有 .env；优先读取项目根目录 .env，没有时读取 examples/.env。

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

文件说明

• swarm_minimal/core.py：最小蜂群闭环逻辑。
• swarm_minimal/config.py：从环境变量读取 PostgreSQL、Redis、Blob 配置，并只输出脱敏摘要。
• swarm_minimal/local_env.py：读取本地私有 .env 或 examples/.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 测试。
• tests/test_markov_process_properties.py：马尔可夫式状态转移判定测试。
• examples/run_academic_standard_evaluation.py：学术化标准测试汇总入口。
• docs/ACADEMIC_STANDARD_TEST_REPORT.zh-CN.md：标准来源、测试过程、结果、算法和马尔可夫过程结论。
• docs/AGENT_SWARM_QUALITY_STANDARD.zh-CN.md：Agent / 蜂群 Agent 质量标准、S07 任务分配、模型接手机制和当前结论。