子智能体评估专家 (Subagent Evaluator)

为子智能体（subagent）提供学术论文驱动的多维度评估能力，覆盖任务完成、上下文隔离、协作效率与归因分析。

适用场景

• 评估子智能体的任务完成能力与稳定性
• 检测子智能体的上下文泄露与摘要纯度
• 分析多智能体协作效率与信息保真度
• 诊断子智能体性能瓶颈、生成评估报告

Quick Start

依赖：仅需 Python 3.8+ 标准库（无第三方依赖）。

python scripts/evaluator.py

最小评估流程（3 步）：

1. 用 create_evaluation_scenario(...) 定义评估场景
2. 用 create_task_result(...) 包装子智能体的实际输出
3. 用 SubagentEvaluator().evaluate_batch(scenarios, results) 得到 JSON/Markdown 报告

完整端到端示例见 examples.md。

评估方法论

本 Skill 整合 4 种主流学术评估框架：

| 框架 | 来源论文 | 在本 Skill 中的对应实现 |

|------|----------|------------------------|

| 多维度基准 | AgentBench (ICLR 2024) | AgentBenchEvaluator：环境理解 / 工具使用 / 规划 / 错误恢复 |

| 细粒度推理链 | AgentBoard | 通过 metadata.steps 字段评估推理过程 |

| 智能体互评 | Agent-as-a-Judge | 通过 evaluator_agent 接入 LLM 评分（外部注入） |

| 混合评估 | Hybrid Evaluation Framework | 确定性指标 + LLM 评分加权综合 |

详细论文与启示参见 references/papers.md。

评估维度与指标

四大类指标，全部由 scripts/evaluator.py 中的 EvaluationMetrics dataclass 承载：

1. 核心能力指标

• pass_at_k：k 次采样中至少一次通过的概率（Codex 公式）
• accuracy：输出正确率
• completion_rate：任务完成率
• auc：分类能力（可选）

2. 上下文隔离指标（防止泄露）

• task_leakage：输入信息在输出中的泄露度（越低越好）
• summary_purity：摘要相对原始数据的纯净度
• citation_pollution：无关引用混入度

3. 协作效率指标

• information_diversity：消息序列的 Type-Token Ratio
• unnecessary_path_ratio：实际路径相对最优路径的冗余度
• information_fidelity：跨智能体信息传递的保真度

4. 归因分析指标

• intent_alignment：智能体行动与用户意图的对齐度
• recall_health：检索结果的 F1 健康度
• composition_priority：组件执行顺序是否满足依赖关系

完整指标定义、计算公式与阈值参见 references/metrics.md。

标准评估流程

[准备] 定义场景 (EvaluationScenario)
   ↓
[执行] 子智能体运行任务 → 包装为 TaskResult
   ↓
[评估] SubagentEvaluator.evaluate_scenario()
       ├─ AgentBenchEvaluator        多维度评分
       ├─ ContextIsolationEvaluator  泄露/纯度/污染
       ├─ CollaborationEfficiency    多样性/路径/保真
       └─ AttributionAnalysis        意图/召回/优先级
   ↓
[聚合] evaluate_batch() → 计算 pass@k 与平均指标
   ↓
[输出] generate_report(format="markdown" | "json")

阈值参考（经验值，非论文官方）

| 指标 | 优秀 | 良好 | 及格 | 不及格 |

|------|------|------|------|--------|

| pass@k | ≥95% | ≥85% | ≥70% | <70% |

| accuracy | ≥98% | ≥90% | ≥80% | <80% |

| task_leakage | 0% | ≤5% | ≤10% | >10% |

| summary_purity| ≥95% | ≥85% | ≥70% | <70% |

> ⚠️ 上表为社区经验值，正式发布前建议结合自有基线数据校准。

输出报告模板

generate_report() 输出的 Markdown 报告结构：

# 子智能体评估报告
## 评估概览        # 总场景数 / 成功 / 失败 / 成功率
## Pass@k 指标     # pass@1, pass@5, pass@10
## 平均指标        # 13 项 EvaluationMetrics 字段
## 详细结果        # 每个场景的成功状态、执行时间、指标

最佳实践

1. 样本量：单次评估至少 30 个场景以获得统计显著性。
2. 多样性：场景应覆盖正常路径、边界情况、对抗输入。
3. 基线对比：与已知 baseline 子智能体或人工标注做横向对比。
4. 持续监控：把评估接入 CI，回归检测性能漂移。
5. 结果可视化：将 report["detailed_results"] 接入图表工具便于解读。

文件清单

subagent-evaluator/
├── SKILL.md                  # 本文件（< 200 行）
├── examples.md               # 端到端使用示例
├── references/
│   ├── metrics.md            # 完整指标定义与公式
│   └── papers.md             # 学术论文索引（含可信度标注）
└── scripts/
    └── evaluator.py          # 零依赖 Python 评估器实现