fengqun/README.md

# Minimal Swarm Loop

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

## 当前状态

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

最新标准矩阵已经扩展到 S01-S10；S07 已换成外部 GitHub 复杂项目 `fastapi/fastapi` 的代码场景，S09 已补齐 3/5/7 并发 claim、候选融合和互相质询的最小代码验收，S10 固化去中心化、自组织、涌现性、鲁棒性、可扩展性、隐式协作六个蜂群一级指标。以下是 S07 live 证据：

```json
{
  "run_id": "9c7ccc6087c1435694a52efb12c32301",
  "target_repo": "fastapi/fastapi",
  "target_commit": "ecace740f3eaccb1aba152cf1de79477095c56f4",
  "completed_tasks": 7,
  "accepted_score": 1.0,
  "check_count": 14,
  "quality_consensus_rounds": 2,
  "failed_checks": []
}
```

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

- `docs/AGENT_SWARM_INDICATOR_TEST_MATRIX.zh-CN.md`：所有 Agent / 蜂群指标的统一测试矩阵，说明每个指标的设计场景和成功阈值。
- `docs/AGENT_SWARM_QUALITY_STANDARD.zh-CN.md`：Agent / 蜂群 Agent 质量标准、测试标准来源、S07 外部 GitHub 代码任务分配和接手机制。
- `docs/SWARM_CHARACTERISTICS_ACCEPTANCE_STANDARD.zh-CN.md`：蜂群六特征验收指标、公式、场景和当前结论。
- `docs/ACADEMIC_STANDARD_TEST_REPORT.zh-CN.md`：S01-S10 测试场景、测试过程、测试结果、算法清单和马尔可夫过程判定。
- `docs/SCORING_AND_ACCEPTANCE_FORMULAS.zh-CN.md`：分数实现、公式、变量含义、S07/S09/S10 和最小闭环通过判定。
- `docs/MODEL_AGNET_IO_REPORT.zh-CN.md`：每个模型 / Agnet 的任务、输入、输出、评分和交接过程。
- `docs/AGNET_FRAMEWORK_INPUT_OUTPUT_LOGIC.zh-CN.md`：不带代码的框架逻辑说明，只从 Agnet 输入、输出、交接和收敛解释实现过程。
- `docs/INDUSTRY_STANDARD_AGNET_TEST_PLAN.zh-CN.md`：行业参考框架到本项目标准的映射。
- `docs/MINIMAL_CLOSED_LOOP_STATUS.zh-CN.md`：最小闭环已完成项、已补边界、测试标准和仍非生产级的部分。

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

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

## 最小闭环

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

## 本地运行

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

标准化测试入口：

```bash
python3 -B -m py_compile swarm_minimal/*.py examples/*.py tests/*.py
python3 -B -m unittest discover -s tests
python3 -u -B examples/run_next_boundary_acceptance.py
python3 -u -B examples/run_swarm_characteristics_acceptance.py
python3 -u -B examples/run_large_scale_stress_acceptance.py
python3 -u -B examples/run_tpm_budget_acceptance.py
python3 -u -B examples/run_swarm_compliance_score.py
python3 -u -B examples/run_academic_standard_evaluation.py
```

`run_next_boundary_acceptance.py` 是 S09 的独立验收入口，专门验证三项此前未完成但可补的能力：3/5/7 Agent 并发自主 claim、候选融合输出、反驳-修正-再投票共识。

`run_swarm_characteristics_acceptance.py` 是 S10 的独立验收入口，专门验证蜂群六特征：去中心化、自组织、涌现性、鲁棒性、可扩展性、隐式协作。

`run_large_scale_stress_acceptance.py` 是 L01 的独立验收入口，默认使用本机全部逻辑 CPU 做本地多进程压力测试。本轮最大性能实测为 8 逻辑核、128 Agent、131072 任务、46.9689 秒完成、失败 0、重复 claim 0。

`run_tpm_budget_acceptance.py` 是 L02 的独立验收入口，按 `3000 TPM` 模型吞吐预算做本地确定性调度验收。本轮实测为 8 个 Agent、60 个模型预算任务、每任务 50 token、总需求 3000 token、单分钟窗口最大 3000 token、预算利用率 100%、失败 0、重复 claim 0。

`run_swarm_compliance_score.py` 是蜂群性数值评分入口，输出 `swarmness_score` 和 `minimal_compliance_score`。当前本地最小蜂群评分为 `100/100`，等级为“极强本地最小蜂群合规”；该分数不等同于生产级 Kubernetes runtime 认证。

指标成功值以 `docs/AGENT_SWARM_INDICATOR_TEST_MATRIX.zh-CN.md` 为准。最小闭环必须同时满足：A01-A09 全部通过、S01-S10 全部通过、F01-F06 六特征全部通过；其中 S07 live 场景必须 14 项检查全部 PASS，S10 必须 6 个蜂群特征场景全部 PASS。若声明本机压力和模型预算量级也通过，还必须同时满足 L01 与 L02。

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

```bash
python3 -u -B examples/run_standard_scenario_acceptance.py
```

## Agnet / NewAPI 测试

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

```bash
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` 忽略：

```bash
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 分别调用：

```bash
python3 -B examples/run_three_newapi_agnets.py
```

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

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

```bash
python3 -B examples/run_full_live_test.py
```

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

```bash
python3 -B examples/run_full_live_test_interactive.py
```

## Azure 资源模式

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

```bash
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`：马尔可夫式状态转移判定测试。
- `tests/test_swarm_characteristics_acceptance.py`：蜂群六特征验收测试。
- `tests/test_acceptance_scoring.py`：蜂群性数值评分和硬上限测试。
- `tests/test_tpm_budget_acceptance.py`：L02 3000 TPM 模型预算调度测试。
- `examples/run_next_boundary_acceptance.py`：S09 下一阶段边界最小验收入口，覆盖并发自主 claim、候选融合和互相质询。
- `examples/run_swarm_characteristics_acceptance.py`：S10 蜂群六特征验收入口。
- `examples/run_large_scale_stress_acceptance.py`：L01 本机最大性能压力验收入口。
- `examples/run_tpm_budget_acceptance.py`：L02 3000 TPM 模型预算调度验收入口。
- `examples/run_swarm_compliance_score.py`：蜂群性数值评分入口。
- `examples/run_academic_standard_evaluation.py`：学术化标准测试汇总入口。
- `docs/ACADEMIC_STANDARD_TEST_REPORT.zh-CN.md`：标准来源、测试过程、结果、算法和马尔可夫过程结论。
- `docs/AGENT_SWARM_INDICATOR_TEST_MATRIX.zh-CN.md`：指标、测试场景、成功阈值和证据入口的统一矩阵。
- `docs/AGENT_SWARM_QUALITY_STANDARD.zh-CN.md`：Agent / 蜂群 Agent 质量标准、S07 任务分配、模型接手机制和当前结论。