fengqun/docs/AGENT_SWARM_QUALITY_STANDARD.zh-CN.md

# Agent / 蜂群 Agent 质量标准 v1

**版本**: AQS/SW-AQS v1
**对象**: `swarm-minimal` 最小蜂群原型
**目的**: 用 Agent 行业通用风险与能力框架，加上本项目自定义蜂群 Agent 标准，评价这个系统是否像一个可控、多 Agent、可交接、可观测、可收敛的 Agent 系统。

## 1. 边界说明

这份标准不是普通软件开发质量标准。

`py_compile`、`unittest`、场景脚本只作为“证据采集工具”，不作为最终质量标准本身。最终评价对象是：

- 单个 Agent 是否能理解任务、保持上下文、使用工具、产出可验证结果。
- 多个 Agent 是否能通过共享环境、信息素、handoff 和收敛机制形成蜂群行为。
- Agent 运行过程是否能被审计、复现、拒绝越权、避免明文密钥泄露。

所有指标的设计场景和成功阈值统一维护在 `AGENT_SWARM_INDICATOR_TEST_MATRIX.zh-CN.md`。本文定义质量项；凡是本文出现的 AQS、SW-AQS、S07、S09、S10 指标，都必须能在该矩阵中找到“场景 + 成功值 + 证据入口”。

## 2. 行业参考来源

当前行业没有统一的“Agent 质量认证”。本项目采用“行业参考 + 本项目配置标准”的方式：

| 来源 | 本项目采用的 Agent 质量含义 |
| --- | --- |
| NIST AI RMF 1.0 | 用 Govern / Map / Measure / Manage 管理 Agent 风险、可控性和可度量性 |
| NIST AI 600-1 Generative AI Profile | 关注生成式 AI 的幻觉、数据隐私、信息安全、供应链/组件、预部署测试和事件披露 |
| OWASP LLM Top 10 | 覆盖 prompt injection、敏感信息泄露、过度代理、过度信任、不安全输出处理 |
| OWASP Agentic Skills Top 10 | 覆盖 Agent 技能/工具执行层的权限、隔离、审计、供应链和运行时安全 |
| MITRE ATLAS | 用 AI 攻击/误用视角设计失败、越权、诱导和异常场景 |
| OpenTelemetry | 用 traces、metrics、logs、events 的思想要求 Agent 过程可观测 |
| LangGraph handoff 参考 | 用 active-agent / `transfer_to_<agent>` 语义约束 Agent 交接 |
| 蜂群模式文献/文章归纳 | 用去中心化、自组织、涌现性、鲁棒性、可扩展性、隐式协作作为蜂群一级验收指标 |

## 3. 通用 Agent 质量标准 AQS

| ID | 质量项 | 合格标准 | 当前证据 |
| --- | --- | --- | --- |
| AQS-01 任务理解 | Agent 输出必须回应分配给它的具体子任务，不泛泛回答 | S07 每步 task.input 明确当前步骤和要求 |
| AQS-02 指令遵循 | 输出必须包含指定 marker、约束、文件路径、验收命令或风险项 | `score_output()`、质量门和 S07 14 项检查 |
| AQS-03 上下文忠实 | 除第一步外，Agent 必须引用上一阶段 marker 和 summary | S07 `step_markers_and_previous_links` |
| AQS-04 可验证输出 | 输出必须能被规则检查，不能只有自然语言主张 | S03/S05/S07 checks |
| AQS-05 模型选择可控 | 多 Agent 不写死 `NEWAPI_MODEL`，必须从模型列表发现并选择 | S07 `three_distinct_models_from_discovery` |
| AQS-06 工具/资源边界 | 不把 NATS/Cosmos 等未批准依赖变成 MVP 必需项 | S04/S07 `no_required_nats_or_cosmos` |
| AQS-07 敏感信息保护 | `.env`、密钥、连接串不进入 Git、日志、报告或模型输出 | 配置脱敏测试、报告只输出 redacted/路径 |
| AQS-08 可观测性 | run_id、task status、score、observation、artifact、stream event 可查 | S07 PostgreSQL/Redis/Blob 证据 |
| AQS-09 错误可解释 | 失败任务必须记录 error、failed observation 和负信息素 | S06/B01/C01 |
| AQS-10 交接准备度 | 输出要给下一个 Agent 留出摘要、风险和下一步 | S07 prompt/output 中强制“下一步/交接” |
| AQS-11 外部依赖真实性 | live 测试必须真实连 PostgreSQL、Redis、Blob、NewAPI，并把代码任务指向外部 GitHub 项目 | S07 external GitHub live PASS |
| AQS-12 人类审计友好 | 最终报告必须能回答：任务、输入、输出、接手、结果、未满足项 | S08 + `MODEL_AGNET_IO_REPORT.zh-CN.md` 和本文件 |
| AQS-13 输出质量恢复 | 拒答、角色拒绝、偏题或目标漂移必须被扣分，并触发重试或 fallback 模型接手 | S07 `all_outputs_pass_quality_gate` + fallback 单元测试 |

### 3.1 AQS 场景和成功值摘要

| 指标组 | 设计场景 | 成功值 |
| --- | --- | --- |
| 任务理解 / 指令遵循 / 上下文忠实 | S07 外部 FastAPI 代码链路，STEP-01 到 STEP-07 连续承接 | 7/7 输出包含当前 STEP、previous marker、外部仓库和固定 commit；质量分 `Q >= 0.72` 且关键项全通过 |
| 模型选择可控 | NewAPI 模型发现后选择多模型 Agnet | `len(discovered_models) >= 3`；`len(set(selected_models)) = 3`；不固定单一 `NEWAPI_MODEL` |
| 资源边界 / 敏感信息保护 | 依赖边界测试、Markdown/报告密钥样式审计 | NATS/Cosmos 不能成为 MVP 必需依赖；明显密钥样式命中数 `0` |
| 可观测性 / 可验证输出 | PostgreSQL、Redis、Blob、shared_state、event stream 证据 | task rows、pheromone、cursor、edge、artifact、event delta 均存在；S07 14 项 checks 全 PASS |
| 输出质量恢复 | bad model 先产生拒答或角色边界输出 | 风险输出分数固定为 `0.12`；触发 retry/fallback；最终输出带 `used_model=good-model` |

## 4. 蜂群六特征一级验收指标

蜂群 Agent 的主验收指标调整为六个一级特征。它们不是补充说明，而是 S10 的直接验收标准。

| ID | 特征 | 定义 | 最小验收指标 | 当前证据 |
| --- | --- | --- | --- | --- |
| F01 | 去中心化 | 无单一 Agent 控制节点，每个 Agent 基于局部任务和共享环境自主决策 | 多 Agent 参与、自主 claim、无重复领取、无 leader/controller 控制键 | S10 `decentralization_no_single_agent_control_node` |
| F02 | 自组织 | Agent 通过局部交互自发形成有序结构，无需预设全局分类结果 | 局部信号写入 shared_state 后形成 dominant cluster | S10 `self_organization_from_local_interactions` |
| F03 | 涌现性 | 全局智能行为不是单个 Agent 局部输出的直接复制，而是群体聚合副产品 | 聚合候选分超过任何单个局部信号，并成为最终输出 | S10 `emergence_global_result_exceeds_single_signal` |
| F04 | 鲁棒性 | 单个 Agent 失效不影响整体功能，系统继续收敛 | 失败任务可观测、负反馈存在、其他任务完成、run converged | S10 `robustness_single_agent_failure_isolated` |
| F05 | 可扩展性 | 新增或移除 Agent 不改变系统架构，弹性伸缩 | 3/5/7 Agent 下同一 shared task pool 架构稳定，无重复 claim，无失败任务 | S10 `scalability_three_five_seven_agents_same_architecture` |
| F06 | 隐式协作 | Agent 不需要直接通信，通过环境变化间接协调 | 无 `message:*` 直接通信键，依赖 pheromone 和 shared_state trail | S10 `implicit_collaboration_by_environment` |

六特征总通过条件：

```text
SWARM_PASS =
  F01_decentralization
  ∧ F02_self_organization
  ∧ F03_emergence
  ∧ F04_robustness
  ∧ F05_scalability
  ∧ F06_implicit_collaboration
```

边界说明：当前 S10 证明的是本地最小原型的 Agent 层蜂群特征，不声称已经完成无协调器的生产级分布式 runtime。

完整细节见 `SWARM_CHARACTERISTICS_ACCEPTANCE_STANDARD.zh-CN.md`。

六特征成功值摘要：

| 特征 | 成功值 |
| --- | --- |
| 去中心化 | `participating_agents >= 4`、`duplicate_claims = 0`、`control_keys = 0`、`decision_records = task_count` |
| 自组织 | 初始不预置全局结果；`local_interaction_count >= 5`；`dominant_cluster = argmax(cluster_score)` |
| 涌现性 | `global_score(candidate_group) > max(local_signal_i)`，最终接受聚合胜出候选 |
| 鲁棒性 | `failed_tasks >= 1`、`completed_tasks >= 2`、存在负反馈、run 仍 `converged` |
| 可扩展性 | `3/5/7` Agent 下均满足 `completed_tasks = 2n`、`failed_tasks = 0`、`duplicate_claims = 0` |
| 隐式协作 | `direct_message_keys = 0`，通过 pheromone 和 shared_state trail 协调，最高信息素任务优先 claim |

## 5. 蜂群 Agent 质量标准 SW-AQS

| ID | 蜂群质量项 | 合格标准 | 当前证据 / 缺口 |
| --- | --- | --- | --- |
| SW-AQS-01 多角色能力 | 至少 3 个不同 Agent/模型参与，角色或步骤不同 | S07 3 个模型、7 个连续步骤 |
| SW-AQS-02 共享任务池 | 任务进入统一 task pool，Agent 从池中 claim | PostgreSQL `swarm_tasks` |
| SW-AQS-03 局部感知 | Agent 输入包含当前任务、上一阶段 summary 或 shared_state keys | S07 user prompt shape |
| SW-AQS-04 自主 claim / 去中心化 | Agent 根据 capability/任务状态领取任务，不能依赖单一 Agent 控制节点 | S10 F01；live S07 仍有 coordinator harness，不等同生产级去中心 runtime |
| SW-AQS-05 信息素/分数 | 每个任务完成后写入正分，失败写入负分 | `swarm_pheromones` + Redis sorted set |
| SW-AQS-06 隐式协作 | 后续 Agent 通过 shared_state/summary/pheromone 感知前序结果，无需直接消息 | S10 F06 + S07 chain summary 和 cursor |
| SW-AQS-07 handoff 连续性 | 交接必须有 from->to/previous->current edge，并保留 payload | B04 与 S07 `chain_edge` |
| SW-AQS-08 广播/事件 | claim、done、converged 等事件进入 stream/outbox | S07 Redis Stream 事件数检查 |
| SW-AQS-09 收敛条件 | 不能只说“跑完”；必须检查任务、分数、状态、artifact、事件、内容质量、多轮质量共识和候选融合能力 | S07 14 项 checks + S09 候选融合 |
| SW-AQS-10 鲁棒性 | 单个 Agent 失败不应吞掉整体状态，失败要可观测 | S10 F04 + B01/C01/S06 |
| SW-AQS-11 涌现性 | 群体聚合结果能超过单个局部强信号 | S10 F03 + B02/C02 |
| SW-AQS-12 传统基线对比 | 必须和单 Agent/FIFO/无共享状态基线比较 | C01-C04 |
| SW-AQS-13 live 外部闭环 | 不能只 mock，至少一次真实资源闭环 | S07 PASS |
| SW-AQS-14 马尔可夫式状态 | 给定完整当前状态，下一步工程转移由当前状态决定 | M01-M03，非严格 MDP |
| SW-AQS-15 多轮质询共识 | 最终接受结果必须经过交接连续性、输出质量、最终收敛审查，并支持反驳、修正、再投票 | S07 `multi_round_quality_consensus_accepts_chain` + S09 `question_revise_revote_consensus` |
| SW-AQS-16 扩缩容与并发 / 可扩展性 | 3/5/7 Agent 并发自主 claim 下仍稳定，新增或移除 Agent 不改变架构 | S10 F05 + S09 `sw_aqs_16_scaled_autonomous_claim_3_5_7` |
| SW-AQS-17 候选融合 | 可把多个有效候选输出去重融合，而不是只能接受单个最高分文本 | S09 `candidate_fusion_output` |
| SW-AQS-18 本机大规模压力 | 使用本机全部逻辑 CPU 做多进程大规模 claim、执行和收敛压力测试 | L01：8 逻辑核、128 Agent、131072 任务、失败 0、重复 claim 0 |
| SW-AQS-19 模型预算调度 | 多 Agent 并发执行时必须遵守模型侧 TPM 预算，不能把所有请求一拥而上 | L02：3000 TPM、8 Agent、60 个任务、单窗口 token 不超额、预算利用率 1.0 |

### 5.1 SW-AQS 场景和成功值摘要

| 指标组 | 设计场景 | 成功值 |
| --- | --- | --- |
| 多角色与共享任务池 | S07 3 模型、7 步外部代码链；S09/S10 本地 shared task pool | selected distinct 模型数 `=3`；chain step 数 `=7`；任务均来自同一 task pool |
| 自主 claim 与扩缩容 | S09/S10 使用 `3/5/7` Agent 领取 `2n` 任务 | 每个规模下 `completed_tasks=2n`、`failed_tasks=0`、`duplicate_claims=0`、`participating_agents=n` |
| 蜂群性数值评分 | F01-F06 占 60 分，S07/S08/S09 占 25 分，L01/L02 占 15 分 | 当前 `swarmness_score=100/100`，`minimal_compliance_score=100/100`，F01-F06 任一失败时最高 `59` |
| 本机最大性能压力 | L01 使用本机 8 逻辑核跑 8 进程、128 Agent、131072 任务 | `completed_tasks=131072`、`failed_tasks=0`、`duplicate_claims=0`、`converged_shards=8` |
| 3000 TPM 模型预算 | L02 使用 8 Agent 领取 60 个模型预算任务，每个任务 50 token | `total_reserved_tokens=3000`、`max_tokens_in_any_minute=3000`、`budget_utilization=1.0`、`failed_tasks=0`、`duplicate_claims=0` |
| 信息素和隐式协作 | 成功任务加分、失败任务扣分；F06 用 `0.9/0.4/0.1` 信息素控制顺序 | 成功 `P_t>0`；失败 `P_t<0`；F06 首个 claim 为 `high-signal` 且无 `message:*` 键 |
| 收敛和共识 | S07 质量共识、S09 反驳-修正-再投票 | S07 14 项 checks 全 PASS；共识 `round_count>=2`；S09 第一轮不收敛、最后一轮收敛 |
| 候选融合 | `quality=0.91`、`coverage=0.86`、`noise=0.2` | `min_score=0.5`；保留 quality/coverage；过滤 noise |

## 6. S07 live 测试任务定义

总任务：

```text
外部 GitHub 代码场景：审查 fastapi/fastapi 响应序列化与 OpenAPI 依赖链
```

目标不是让模型自由聊天，也不是拿本仓库验证自己闭环，而是让 7 个连续 Agent 阶段接力审查一个外部复杂 GitHub 项目：

- 目标仓库：`https://github.com/fastapi/fastapi`
- 固定 commit：`ecace740f3eaccb1aba152cf1de79477095c56f4`
- 代码范围：`fastapi/routing.py`、`fastapi/dependencies/utils.py`、`fastapi/openapi/utils.py`、`fastapi/params.py`、`fastapi/encoders.py`、`fastapi/applications.py`、`tests/test_serialize_response_model.py`、`tests/test_response_model_data_filter.py`

| 步骤 | 分配任务 | 主要验证点 |
| --- | --- | --- |
| STEP-01 | 界定问题和不可变约束 | 建立 FastAPI 外部代码审查目标、输入输出、不变量和禁止自测边界 |
| STEP-02 | 建立依赖图和状态模型 | 承接 STEP-01，给出路由、依赖注入、OpenAPI、响应序列化和测试文件依赖图 |
| STEP-03 | 定位跨文件风险路径 | 承接 STEP-02，定位 response_model、Depends、参数 metadata、jsonable_encoder 与 OpenAPI schema 的漂移风险 |
| STEP-04 | 构造反例和失败场景 | 承接 STEP-03，构造响应过滤、默认值、nullable、依赖参数和 schema 不一致反例 |
| STEP-05 | 修正算法和恢复策略 | 承接 STEP-04，给出模块修正策略、兼容性和 Starlette/Pydantic 交互边界 |
| STEP-06 | 落到文件级实现计划 | 承接 STEP-05，引用 fastapi/fastapi 真实源码文件和测试文件 |
| STEP-07 | 最终收敛和验收判定 | 承接 STEP-06，给出 FastAPI 仓库内可执行验收命令、指标和可合并结论 |

模型分配来自动态发现，不写死 `NEWAPI_MODEL`：

| 步骤 | Agnet | primary / used model | 交接边 |
| --- | --- | --- | --- |
| STEP-01 | `continuous-agnet-1` | `deepseek-v4-flash` | `START->STEP-01` |
| STEP-02 | `continuous-agnet-2` | `claude-haiku-4-5-20251001` | `STEP-01->STEP-02` |
| STEP-03 | `continuous-agnet-3` | `claude-sonnet-4-6` | `STEP-02->STEP-03` |
| STEP-04 | `continuous-agnet-4` | `deepseek-v4-flash` | `STEP-03->STEP-04` |
| STEP-05 | `continuous-agnet-5` | `claude-haiku-4-5-20251001` | `STEP-04->STEP-05` |
| STEP-06 | `continuous-agnet-6` | `claude-sonnet-4-6` | `STEP-05->STEP-06` |
| STEP-07 | `continuous-agnet-7` | `deepseek-v4-flash` | `STEP-06->STEP-07` |

## 7. 模型输入输出与接手机制

完整输入输出见 `MODEL_AGNET_IO_REPORT.zh-CN.md`。核心机制如下：

1. wrapper 给当前 Agnet 的 user prompt 注入：
   - `Previous marker`
   - `Previous summary`
   - `Task kind`
   - 完整 `Task input`
2. 当前 Agnet 输出必须带：
   - `chain_edge=<previous>-><current>`
   - `primary_model`
   - `used_model`
   - `model_selection=discovered_models_not_NEWAPI_MODEL`
3. 当前输出会先经过质量门：
   - 拒答、角色拒绝、偏题、本仓库漂移会被重罚。
   - 不满足当前 STEP、前序 STEP、外部仓库、commit、FastAPI 技术语义和交接要求时，会触发重试或 fallback 模型接手。
4. 当前 Agnet 完成后，系统写入：
   - `chain:{run_id}:{STEP}:summary`
   - `chain:{run_id}:cursor`
   - `chain:{run_id}:edge:<previous>-><current>=done`
5. 下一个 Agnet 读取上一步 summary 和 marker 后继续执行。
6. 最终接受结果还必须通过三类审查 Agnet 的多轮质量共识；第一轮只能形成候选，第二轮或之后达成接受才算通过。

因此“接手”不是人工解释，也不是模型凭空猜测，而是通过 PostgreSQL shared_state 中的 summary、cursor、edge 字段完成。

## 8. 本轮判定

最新标准矩阵已经扩展为 S01-S10。S10 六特征本地验收已通过；以下为 S07 外部 GitHub 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": []
}
```

结论：

- 按 AQS 通用 Agent 标准：当前最小测试通过。
- 按 SW-AQS 蜂群 Agent 标准：关键闭环、质量门、fallback 补救、多轮质量共识、3/5/7 并发 claim、候选融合、互相质询，以及去中心化、自组织、涌现性、鲁棒性、可扩展性、隐式协作六特征的最小代码验收已通过。
- 所以它满足“最小蜂群 Agent 质量标准 v1”，还不等于真实 runtime 扩缩容、人类审批、生产权限和全链路平台认证。