> ## Documentation Index
> Fetch the complete documentation index at: https://agent-compass.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# agentcompass analysis

执行后置错误案例检测、统计、延迟检查和定性轨迹诊断。

`agentcompass analysis` 对已有 AgentCompass 结果目录重新运行分析器，而不重新执行 agent：

```bash theme={"system"}
agentcompass analysis --input <run-directory> [OPTIONS]
```

分析器会检查轨迹、指标、错误、延迟、model 输出和工具调用，并把结果写入 `analysis_result.<analyzer-family>`；字段结构见[任务结果](/zh/user_guide/other_features/results/task_results#分析结果)。

当 Benchmark 得分只能说明“什么失败了”而不能解释“为什么失败”时，请使用分析器。

## 分析器的作用

<CardGroup cols={2}>
  <Card title="Badcase 检测" icon="badge-alert">
    标记异常、截断、JSON 错误、重复、空输出、延迟异常和终端误用。
  </Card>

  <Card title="统计" icon="chart-no-axes-combined">
    计算步骤数、工具调用数、耗时、词元长度、值分布和数值摘要。
  </Card>

  <Card title="定性诊断" icon="sparkles">
    使用由 LLM 驱动分析器标注轨迹阶段、总结行为并生成报告。
  </Card>

  <Card title="聚合" icon="table">
    将分析器输出聚合为 `analysis_summary.json` 和 `analysis_summary.md`。
  </Card>
</CardGroup>

分析器不会重新运行 agent，也不会重新判定 Benchmark 正确性；它们只读取已经完成的任务结果。

## 随评测运行

```bash theme={"system"}
agentcompass run \
  terminal_bench_2 \
  terminus2 \
  "$MODEL_NAME" \
  --env <env-provider> \
  --benchmark-params '{"sample_ids":["<task-id>"]}' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY" \
  --enable-analysis \
  --analysis-params '{"analyzers":["ExceptionAnalyzer","TruncationAnalyzer"]}'
```

如果已确定评测期间应运行哪些分析器，请使用此方式。

## 重新分析已有结果

```bash theme={"system"}
agentcompass analysis \
  --input results/terminal_bench_2/$MODEL_NAME/20260703_120000 \
  --analysis-params '{
    "analyzers": ["ExceptionAnalyzer", "QualitativeAnalyzer"],
    "QualitativeAnalyzer": {"render_mode": "file"}
  }' \
  --task_concurrency 8
```

默认情况下，`analysis` 会把输入运行复制到带有新时间戳的同级目录。使用 `--output` 指定复制目标；只有明确需要原地修改时才使用 `--override`。

## 参数

| 参数                             | 作用                                              |
| ------------------------------ | ----------------------------------------------- |
| `INPUT` / `--input`            | 包含 `run_info.json` 和 `details/` 的已有运行目录，必填。     |
| `--override`                   | 替换输入目录中的分析器字段和摘要，默认关闭。                          |
| `--output <path>`              | 将运行复制到该路径并分析副本；仅在未启用 `--override` 时使用。          |
| `--task_concurrency <n>`       | 重新分析时的任务并发数；默认沿用原始运行值。                          |
| `--analysis-params <json>`     | 选择分析器并提供分析器专属配置。                                |
| `--benchmark-params <json>`    | 通过 `sample_ids` 限制重新分析范围；此命令不使用其他 Benchmark 字段。 |
| `--config <path>`              | 加载额外配置覆盖，可重复传入。                                 |
| `--log-level <level>`          | 设置分析操作的终端日志级别。                                  |
| `--progress auto\|plain\|none` | 选择分析进度渲染器。                                      |

默认复制可以避免意外修改已测量运行。只有确实希望替换已有分析数据，且没有不可变归档依赖该目录时，才使用 `--override`。

## 选择规则

| 字段                  | 含义                         |
| ------------------- | -------------------------- |
| `analyzers`         | 白名单；设置后只考虑列出的分析器 ID。       |
| `exclude_analyzers` | 黑名单；即使其他条件兼容，被排除的分析器也会跳过。  |
| `<AnalyzerId>`      | 每个分析器的配置，例如阈值或定性 model 设置。 |
| `only_incorrect`    | 基础逻辑支持时，只分析错误样本的分析器配置。     |

## 支持的分析器系列

使用 `agentcompass list analyzer` 查看当前版本注册的分析器。常见系列包括：

| 系列   | 示例                                                                                                                          |
| ---- | --------------------------------------------------------------------------------------------------------------------------- |
| 基础统计 | `BasicMetricAnalyzer`、`TrajectoryTimeCostAnalyzer`、`CompletionLengthAnalyzer`                                               |
| 错误检测 | `ExceptionAnalyzer`、`TerminalBench2ExceptionAnalyzer`、`TruncationAnalyzer`、`JSONErrorAnalyzer`、`EmptyContentAnalyzer`       |
| 效率   | `LLMInferLatencyAnalyzer`、`ToolExecutionLatencyAnalyzer`                                                                    |
| 行为模式 | `ContentRepetitionAnalyzer`、`ReasoningRepetitionAnalyzer`、`NetworkOperationAnalyzer`、`TerminalBench2CommandRunningAnalyzer` |
| 定性分析 | `QualitativeAnalyzer`、`MultiQualitativeAnalyzer`                                                                            |

## 输出结构

每个任务详情将分析器输出保存在：

```text theme={"system"}
analysis_result.<analyzer-family>
```

键可以是分析器自身的 ID，也可以是多个实现共用的分析器系列 ID。聚合摘要按类别和分析器系列输出：

* 分析的任务总数；
* 错误案例数量和比例；
* 分析器提供得分时的平均值；
* 值数量分布；
* 数值的数量、最小值、平均值、p50、p90、p95 和最大值。

逐任务字段见[任务结果](/zh/user_guide/other_features/results/task_results#分析结果)，两个分析摘要文件的完整结构见[汇总与分析结果](/zh/user_guide/other_features/results/summary_analysis#analysis_summaryjson)。

## 相关页面

* [汇总与分析结果](/zh/user_guide/other_features/results/summary_analysis)
* [`agentcompass summary`](/zh/user_guide/using_agentcompass/cli/summary)
* [`agentcompass list`](/zh/user_guide/using_agentcompass/cli/list)
* [CLI 概览](/zh/user_guide/using_agentcompass/cli/overview)
* [配置](/zh/user_guide/using_agentcompass/cli/config#覆盖顺序)