# Agent Defect Analyzer

从 Agent 的历史运行数据中反向推断系统性缺陷，输出结构化的缺陷报告和修复优先级。

## 研究理念

### 核心假设

> **Agent 的缺陷不是随机的，而是系统性的——它们会在历史数据中留下可检测的统计指纹。**

一个 Agent 框架的"质量"不应只看单次交互的成败，而应从宏观统计中识别出反复出现的模式。就像软件可靠性工程中的 SRE 理念：**不要问"这次为什么失败了"，而要问"这个失败模式出现了多少次、影响了多少用户、趋势是恶化还是改善"。**

### 分析哲学

1. **数据驱动，不靠猜测**。每个缺陷报告必须附带证据（具体会话 ID、错误消息、统计数字）和置信度评估。置信度低不是问题——标记出来让人类判断，比假装没看见好。

2. **多层缺陷模型**。Agent 的"缺陷"不是一个维度，而是四个正交层次：
   - **执行层**：工具调用失败、重试过多、超时（"想做但没做成"）
   - **策略层**：工具选择不当、冗余搜索、未充分利用工具集（"做错了"）
   - **效率层**：上下文膨胀、交互比过高、单轮工具调用过多（"太贵了"）
   - **体验层**：用户放弃、重复提问、极短会话（"用户不满意"）

3. **只读分析，零侵入**。分析脚本对生产数据库只做 SELECT，绝不写入。分析是观察行为，不应改变被观察的系统。

4. **启发式优先于 ML**。在数据规模有限（数百~数千会话）的情况下，精心设计的规则引擎比训练模型更可靠、更可解释。每个启发式规则都对应一个可人工验证的假设。

5. **置信度分级**。不是所有发现都同等可信。基于规则匹配的发现（如"调用了不存在的工具"）置信度高；基于相关性推断的发现（如"交互比高 = Agent 低效"）置信度低，需要人工确认因果关系。

### 分析框架

```
                    ┌─────────────┐
                    │ SQLite 数据 │  79K 消息 / 1K 会话
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              ▼            ▼            ▼
     ┌────────────┐ ┌────────────┐ ┌────────────┐
     │ 工具失败   │ │ 会话效率   │ │ 策略质量   │
     │ 模式分析   │ │ 生存分析   │ │ 编排分析   │
     └─────┬──────┘ └─────┬──────┘ └─────┬──────┘
           │              │              │
           └──────────┬───┘──────────────┘
                      ▼
              ┌──────────────┐
              │ 用户行为信号 │  放弃率、重复、消息长度
              └──────┬───────┘
                     ▼
           ┌─────────────────┐
           │ 缺陷报告聚合    │  严重度 × 置信度 → 优先级
           └─────────────────┘
```

每个分析模块独立运行，输出 `DefectReport[]`，最终按 `severity × confidence` 排序。

### 已实现的检测能力

| 检测项 | 方法 | 数据源 |
|--------|------|--------|
| 幻觉工具调用 | 正则匹配 `工具 'X' 不存在` | tool 消息 error |
| 重试循环 | 同会话同工具连续失败 ≥2 次 | tool 消息序列 |
| 连续失败链 | 按 thread 聚合错误序列 | tool 消息 |
| 死循环检测 | 同工具+同参数连续调用 ≥3 次 | assistant tool_use 序列 |
| 振荡循环 | A→B→A→B 交替模式 ≥4 次 | 工具名序列 |
| 无进展循环 | 同工具+结果等长连续 ≥3 次 | tool_use + tool_result |
| 超大出参 | 工具输出 >100KB | tool 消息 content 长度 |
| 超大入参 | 工具参数 >50KB | assistant tool_use input 长度 |
| 上下文膨胀 | 会话总出参 >500KB | 按 thread 聚合 |
| 工具多样性不足 | 长会话 ≤2 种工具 | assistant tool_use |
| 交互比异常 | 总消息/用户消息 >50 | 全消息统计 |
| 重复话题 | 标题前缀碰撞 | thread title |
| 会话生存曲线 | 消息数分桶分布 | thread message_count |

### 未来方向

- **语义级缺陷检测**：用 LLM 判断 Agent 回答是否偏题、是否遗漏关键信息（当前仅做结构分析）
- **时间序列趋势**：跟踪各缺陷指标随版本/时间的演变，评估修复效果
- **聚类分析**：对会话做无监督聚类，发现"Agent 在哪类任务上系统性表现差"
- **回归测试基准**：将缺陷报告作为回归测试用例，确保修复后不复发
- **Langfuse 联动**：结合 trace 数据做 token 级别的效率分析

## 使用方式

```bash
cd side-projects/agent-defect-analyzer

# 全量分析
bun src/main.ts

# 单模块分析
bun src/main.ts --focus errors       # 工具失败模式
bun src/main.ts --focus efficiency   # 会话效率
bun src/main.ts --focus strategy     # 策略质量
bun src/main.ts --focus loops       # 死循环 / 重复调用检测
bun src/main.ts --focus payload     # 超大入参/出参检测
```

默认读取 `~/.peri/threads/threads.db`（只读，不写入）。

## 项目结构

```
src/
├── main.ts                    # 入口 + 综合报告聚合
├── types.ts                   # 数据类型定义
├── analyzers/
│   ├── tool_errors.ts         # 工具失败模式分析
│   ├── session_efficiency.ts  # 会话效率与生存分析
│   ├── strategy_quality.ts    # 策略编排与重试检测
│   ├── death_loops.ts         # 死循环 / 重复调用检测
│   ├── payload_size.ts        # 超大入参/出参检测
│   └── user_behavior.ts       # 用户行为信号分析
└── utils/
    ├── data_loader.ts         # 只读 SQLite 加载层（bun:sqlite）
    └── report.ts              # 控制台报告渲染
```
