fengqun/README.md

# Minimal Swarm Loop

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

## 当前状态

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

最新标准矩阵（S01-S08）已通过；S07 已换成外部 GitHub 复杂项目 `fastapi/fastapi` 的代码场景，以下是 S07 live 证据：

```json
{
  "run_id": "37155251926d4165a7b7af68e8967f64",
  "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_QUALITY_STANDARD.zh-CN.md`：Agent / 蜂群 Agent 质量标准、测试标准来源、S07 外部 GitHub 代码任务分配和接手机制。
- `docs/ACADEMIC_STANDARD_TEST_REPORT.zh-CN.md`：S01-S08 测试场景、测试过程、测试结果、算法清单和马尔可夫过程判定。
- `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.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_academic_standard_evaluation.py
```

完整 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`：马尔可夫式状态转移判定测试。
- `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 任务分配、模型接手机制和当前结论。