Analyzer 集成

当你需要对执行结果进行诊断或统计，但不应改变 Benchmark 的权威评测结果时，新增一个 Analyzer。

Analyzer 在一次任务尝试产生 RunResult 后执行。它可以检查规范化答案、轨迹、指标、状态、错误和产物，并返回 AnalysisResult。它不能重新运行 agent、改变 Benchmark 的正确性判定，也不能替代应在 BaseBenchmark.evaluate() 中实现的评分逻辑。

​

实现一个公开 Analyzer

下面的示例基于 Benchmark 的 Harness 驱动教程中的公开 Benchmark example_exact_match。它用于标记空答案或异常长的最终答案，不依赖任何 Environment provider 实现：

from agentcompass.runtime import (
    ANALYZERS,
    AnalysisResult,
    AnalyzerCategory,
    BaseAnalyzer,
    RunResult,
)


@ANALYZERS.register()
class ExampleAnswerLengthAnalyzer(BaseAnalyzer):
    id = "ExampleAnswerLengthAnalyzer"
    description = "Flag empty or unusually long example final answers."
    category = AnalyzerCategory.BEHAVIOR
    datasets = ["example_exact_match"]
    data_requirements = ["$.final_answer"]
    conf = {
        "only_incorrect": False,
        "max_characters": 1000,
    }
    distribution_fields = {
        "answer_characters": "numeric_stats",
    }

    async def analysis(self, task, prepared, result: RunResult, req, plan) -> AnalysisResult:
        _ = prepared, req, plan
        answer = str(result.final_answer or "").strip()
        answer_characters = len(answer)
        max_characters = max(1, int(self.conf.get("max_characters", 1000)))

        return AnalysisResult(
            task_id=task.task_id,
            is_badcase=not answer or answer_characters > max_characters,
            details={
                "answer_characters": answer_characters,
                "max_characters": max_characters,
                "empty_answer": not answer,
            },
        )

基于规则的 Analyzer 应保持确定性。如果 Analyzer 需要调用 Model，应公开并验证其配置，且不得修改被评测结果。分析失败应记录为 Analyzer 输出，不能修改任务状态或得分。

​

BaseAnalyzer 契约

属性或方法	在当前 runtime 中的含义
id	唯一注册 ID 和默认输出系列键
description	agentcompass list analyzer 显示的说明文字
category	通过 AnalyzerCategory 声明的分类元数据；当前持久化和运行级汇总不会按该字段分组
datasets	可运行的 Benchmark ID；空列表匹配所有 Benchmark
data_requirements	用于检查 RunResult.json 的 JSONPath 表达式；缺少任一必需数据时跳过该次尝试的 Analyzer
conf	Analyzer 默认配置；execution.analysis_params 下与 <AnalyzerId> 对应的对象会覆盖该实例中的对应值
distribution_fields	使用 numeric_stats 或 value_counts 聚合的 details 字段
base_analyzer	专用实现可指定的基础系列 ID
priority	用于选择同一系列内的实现；数值越高，优先级越高
analysis()	为一次尝试返回 AnalysisResult 的异步方法

基类还提供 matches_dataset()、check_requirements()、should_skip() 和 is_threshold_badcase()。共享的 should_skip() 能识别 conf.only_incorrect；自定义配置仍由 Analyzer 自己处理。

datasets 必须使用准确的已注册 Benchmark ID。data_requirements 只应包含调用 analysis() 前确实必需的数据；可选字段应在方法内处理，避免因为缺失而静默移除整个 Analyzer 输出。

​

注册与导出

将实现放在 src/agentcompass/analyzers/ 下；确定性规则通常放在 analyzers/basic/。使用 @ANALYZERS.register() 装饰具体类，并通过各级软件包 __init__.py 导入其模块，确保导入 agentcompass.analyzers 时执行装饰器。

注册表会拒绝重复 ID。为了方便 Python 导入，可以选择在顶层重新导出名称，但用于触发注册的逐级模块导入不可省略。运行以下命令确认发现结果：

uv run agentcompass list analyzer

Analyzer 专属值通过 execution.analysis_params 传入；agentcompass config docs 当前只记录 Benchmark、Harness 和 Environment 配置数据类，不记录 Analyzer conf 字典。必须显式记录每个支持的 Analyzer 键及其默认值。

​

选择与系列解析

启用分析后，runtime 会为每次尝试执行以下步骤：

1. 如果存在 analyzers 允许列表，则只保留其中列出的 Analyzer；否则应用 exclude_analyzers 排除列表。
2. 构造每个剩余的已注册 Analyzer，并使用按 ID 提供的配置覆盖默认值。
3. 检查 datasets、data_requirements 和 only_incorrect 是否满足。
4. 按 base_analyzer 分组；未设置时使用自身 id 作为系列。
5. 选择各系列中 priority 严格最高的实现并调用其 analysis() 方法。

同一系列中符合条件的成员优先级相同时，较早注册的实现仍会入选。专用 Analyzer 只有在扩展同一套诊断契约和输出系列时，才应设置 base_analyzer = "<generic-id>"、更高的 priority 和范围更窄的 datasets。无关 Analyzer 应保留 base_analyzer = None，使它们可以独立运行。

这一优先级行为只属于 Analyzer。Recipe 的优先级当前不会影响 Recipe 应用顺序。

​

返回 AnalysisResult

analysis() 返回以下字段：

字段	含义
task_id	当前任务 ID；持久化任务记录已包含该标识
is_badcase	检测结果明确时使用 True 或 False；纯统计输出或结果不确定时使用 None
details	为每次尝试保留的可 JSON 序列化诊断数据
score	可选的 Analyzer 数值得分，与 Benchmark 得分分开聚合
error	无法完成分析时的可选说明
extra	可选的其他可 JSON 序列化元数据

runtime 将获选系列的结果保存到：

attempts.<attempt-index>.analysis_result.<analyzer-family>

保存的数据始终包含 is_badcase 和 details，并只在有值时包含 score、error 和 extra。AnalysisResult.task_id 不会在该系列数据中重复保存。如果 analysis() 抛出异常，runtime 会记录该系列的错误，将判断标记为不确定并继续执行，不会改变 Benchmark 已有结果。

只能声明支持的聚合方式：

distribution_fields = {
    "answer_characters": "numeric_stats",  # int 或 float
    "error_types": "value_counts",         # str 或 list[str]
}

只要至少一个持久化任务尝试包含可聚合的分析输出，运行级聚合就可以写入 analysis_summary.json 和 analysis_summary.md。若检测器显式返回 is_badcase，但异常样本与分析错误均为零，该结果仍会保留在对应任务尝试的详情记录中。此时，它不会进入运行级摘要。持久化格式见汇总与分析结果。

​

使用一个公开任务验证

完成 Benchmark 示例和 Harness 实现教程中的 example_exact_match 与 example_answer 后，使用示例 Analyzer 运行对应的确定性任务。该流程不需要 Model 端点或凭证：

uv run agentcompass run example_exact_match example_answer unused-model \
  --env host_process \
  --benchmark-params '{"sample_ids":["capital-france"]}' \
  --harness-params '{"answer":"Paris"}' \
  --task-concurrency 1 \
  --max-retries 0 \
  --enable-analysis \
  --analysis-params '{
    "analyzers": ["ExampleAnswerLengthAnalyzer"],
    "ExampleAnswerLengthAnalyzer": {"max_characters": 4}
  }' \
  --results-dir results-dev \
  --run-name analyzer-smoke

应验证：

• 该次尝试的 analysis_result 下只出现请求指定的系列；
• details.answer_characters 与已保存的 final_answer 一致；
• 配置的上限能覆盖类默认值，且不会修改后续 Analyzer 实例。五个字符的答案会被四字符上限标记为异常样本；
• 其他 Benchmark 会因为 datasets 被跳过；
• 缺少必需数据时跳过 Analyzer，而 analysis() 内部异常会产生系列错误；
• 输出可聚合时，analysis_summary.json 和 analysis_summary.md 包含声明的数值分布。

还应使用 agentcompass analysis 在已有结果的副本上重新运行 Analyzer，验证它与持久化 RunResult 重建逻辑兼容。完整代码仓库检查和 PR 证据见测试与验证。

​

完成检查表

• 新逻辑用于诊断已有结果，不替代 Benchmark 评分。
• ID、说明、类别、数据集范围、必需字段和配置默认值均已明确。
• 从 agentcompass.analyzers 导入时能够完成注册，且 agentcompass list analyzer 显示该 ID。
• 系列与优先级设置不会导致无关 Analyzer 被排除。
• AnalysisResult 和 details 可 JSON 序列化，声明的分布使用支持的值类型。
• 已在公开数据上检查运行期间分析、结果副本重新分析、跳过、错误和聚合输出。
• 面向用户的配置和输出字段均已用中英文记录。