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

六特征总通过条件：

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 测试任务定义

总任务：

外部 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 证据：

{
  "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 扩缩容、人类审批、生产权限和全链路平台认证。