# Agent Tune Kit

简体中文 | [English](README.en.md)

[![PyPI](https://img.shields.io/pypi/v/agent-tune-kit.svg)](https://pypi.org/project/agent-tune-kit/)

Agent Tune Kit 是一个**本地 Codex 插件**，用于评测和调优你自己的本地 Agent。

如果你已经有一个能运行的 Agent，但不知道它在哪些样本上表现不好、原因是什么、下一步该怎么改，Agent Tune Kit 可以帮你把一轮调优闭环跑起来：批量测试、找异常样本、生成报告、让 Codex 调整 Agent，再用下一轮结果验证是否真的变好。

## 架构图

![Agent Tune Kit 架构图](docs/assets/arch.png)

## 适合谁

适合你，如果你有，或准备让 Codex 帮你补齐：

- 一个本地 Agent、聊天机器人、工具调用 Agent 或 RAG Agent。
- 一份小型评估数据，推荐 CSV；5 到 20 条样例就能开始。
- 一些可以判断好坏的输入、期望答案或人工可验收结果。
- 想让 Codex 协助定位弱点，并调 prompt、代码、参数或工具配置。

## 安装

一键运行：

```sh
uvx --from agent-tune-kit atk install
```

如果希望长期保留 `atk` 命令，可以改用：

```sh
uv tool install agent-tune-kit
atk install
```

或使用 `pipx`：

```sh
pipx install agent-tune-kit
atk install
```

安装完成后，在 Codex 中打开插件列表：

```text
/plugins
```

选择并启用 `Agent Tune Kit`。如果刚启用后当前会话里还看不到 `$atk-status` 等自动补全，请重启 Codex，或重新打开当前项目会话。

## 最小调优闭环

下面这些命令都在**你的 Agent 项目**里运行，不是在本仓库里运行。

理想情况下，你已经有一个 Codex 能读取和修改的本地 Agent 项目，以及一份评估数据集。数据集建议优先使用 CSV，字段名不必严格固定，Codex 会根据内容判断输入、期望结果和评测方式。如果其中一项还没有准备好，可以从第 0 步补齐；如果都已经有了，直接从第 1 步初始化开始。

### 0. 可选：补齐数据集或 Agent

如果你只有业务描述、少量样例或验收规则，还没有 CSV，可以先运行：

```text
$atk-build-dataset <你的业务描述、样例或规则>
```

Codex 会在信息不足时先问 1 到 3 个问题，确认输入字段、期望输出或验收标准，以及关键业务场景。生成结果会直接写入 `.atk/datasets/dataset.csv`，包含 `atk_id`；如果该文件已经存在，Codex 会先确认是否覆盖。它重点覆盖主流程、边界输入、缺失或含糊信息、拒答/不确定场景、输出格式约束和你描述的业务风险。
`$atk-build-dataset` 默认不会推测 `ground_truth` 列；只有当你明确给出 `ground_truth`、正确答案或“怎样算正确”的判定方案时，它才会写入规范 `ground_truth`。否则请保留为普通预期/验收字段，或在数据集创建后用 `$atk-build-ground-truth` 补齐。

如果你已经有评估数据集，但还没有 Agent 项目，可以先生成一个轻量、可运行、使用 OpenAI-compatible API 的 Python Agent：

```text
$atk-new-agent 数据集是 data/eval.csv
```

Codex 会先理解数据集并确认你的意图，生成最小 Agent 项目，并把采访和设计信息写入 `.atk/specs/agent_spec.md`。这个步骤不会写 `.atk/datasets/dataset.csv`；后续仍由 `$atk-init` 负责接入 Agent 时的数据集校验、规范化和 runner 生成。

如果 `.atk/datasets/dataset.csv` 已经存在，但缺少清晰的预期结果语义，导致后续异常判断不稳定，可以在跑评测前先补齐统一的 ground truth：

```text
$atk-build-ground-truth
```

Codex 会让你选择一种全局一致的 `ground_truth` 风格：精确答案，或自然语言验收标准。它会在保留原有列和 `atk_id` 的前提下就地更新 `.atk/datasets/dataset.csv`。这是 dataset-only / pre-results 步骤：不会运行 Agent，不会创建 `.atk/results/vN`，也不会写 `failure_cases.csv`。如果已有 `eval_results.csv` 是补齐 ground truth 之前生成的，请先重新运行 `$atk-run` 再找异常样本。
构建好数据集后，可以选择先浏览和质检它：

```text
$atk-visualize-dataset
```

它会把 `.atk/datasets/dataset.csv` 生成一个本地、单文件、离线的 HTML 浏览页：

```text
.atk/datasets/dataset.html
```

页面采用 Dataset Visualizer 风格的离线静态界面，提供「数据列表 / 字段特征分析」双标签、字段显示控制、搜索、分类过滤、排序分页和详情抽屉，突出输入与检测到的预期结果字段对照，并对空值、重复/缺失 `atk_id`、冲突样本、长度离群等问题自动打标签，便于快速确认预期结果是否符合预期。你可以在页面里对每行裁决（符合预期 / 存疑 / 需修正）并导出 `dataset_review.csv`；如需规范 `ground_truth`，请用明确判定方案运行 `$atk-build-ground-truth`。用户不需要安装任何前端依赖。

### 1. 初始化

告诉 Codex 你的 Agent 从哪里启动、评估数据在哪里：

```text
$atk-init 我的 Agent 入口是 scripts/agent.py，评估数据是 data/eval.csv
```

Codex 会生成测试脚本：

```text
.atk/runner/eval_runner.py
```

如果这个 Agent 是由 ATK new Agent 创建的，通常继续运行：

```text
$atk-init Agent 入口是 agent.py 的 run_agent，评估数据是 data/eval.csv
```

### 2. 跑评测

```text
$atk-run
```

结果会写入：

```text
.atk/results/v1/eval_results.csv
```

### 3. 找异常样本

让 Codex 判断哪些样本失败：

```text
$atk-find-failures
```

如果你有明确判定规则，可以先生成规则脚本，再按规则筛选：

```text
$atk-init-failure-rule 规则：当 expected 字段与 agent_output 字段不一致时判定为异常
$atk-find-failures-by-rule
```

异常样本会写入：

```text
.atk/results/v1/failure_cases.csv
```

### 4. 生成报告

```text
$atk-report
```

报告会写入：

```text
.atk/results/v1/report.md
```

它会总结测试结果、异常样本、可能原因和建议优先调优的问题。

### 5. 可选：浏览异常样本

```text
$atk-visualize-failures
```

会生成一个本地 HTML：

```text
.atk/results/v1/failure_cases.html
```

适合用来搜索、筛选和人工复核异常样本。

### 6. 让 Codex 调优

```text
$atk-tune
```

Codex 会基于报告修改你的 Agent，并记录本轮调优计划：

```text
.atk/results/v1/tuning_plan.md
```

## 验证是否变好

调优后再跑一轮：

```text
$atk-run --only-failures
$atk-find-failures
$atk-report
```

新结果会写入 `.atk/results/v2/`。`--only-failures` 会通过 `atk_id` 将上一轮 `failure_cases.csv` 映射回 `.atk/datasets/dataset.csv`，并只重跑这些行。从第二轮开始，报告会对比上一轮 `tuning_plan.md`，说明目标问题是已解决、部分解决、未解决，还是无法判断。

## 输出结构

```text
.atk/
├── datasets/
│   └── dataset.csv        # ATK 可运行数据集，包含 atk_id
├── runner/
│   ├── eval_runner.py
│   └── failure_rule.py
└── results/
    ├── v1/
    │   ├── eval_results.csv
    │   ├── failure_cases.csv
    │   ├── failure_cases.html
    │   ├── report.md
    │   └── tuning_plan.md
    └── v2/
        └── ...
```

常用输出文件：

- `eval_results.csv`：每条样本的实际输出。
- `failure_cases.csv`：筛选出的异常样本。
- `failure_cases.html`：可选的异常样本浏览页面。
- `report.md`：本轮问题分析和调优建议。
- `tuning_plan.md`：Codex 本轮改了什么、为什么改。

## 常用 Skill

- `$atk-status`：检查当前进度并提示下一步。
- `$atk-build-dataset`：从业务描述、样例或规则构建 `.atk/datasets/dataset.csv`。
- `$atk-build-ground-truth`：为现有 `.atk/datasets/dataset.csv` 补齐规范的 `ground_truth` 列。
- `$atk-visualize-dataset`：将 `.atk/datasets/dataset.csv` 生成本地 HTML 浏览页，便于快速查看数据并确认 ground_truth 是否符合预期。
- `$atk-new-agent`：当你只有数据集、还没有 Agent 项目时，生成一个轻量 OpenAI-compatible Agent。
- `$atk-init`：生成测试脚本。
- `$atk-run`：运行评测并生成新版本结果。
- `$atk-find-failures`：让 Codex 判断异常样本。
- `$atk-init-failure-rule`：创建或更新异常判定规则。
- `$atk-find-failures-by-rule`：按规则筛选异常样本。
- `$atk-report`：生成分析报告和跨轮验证结论。
- `$atk-visualize-failures`：生成异常样本 HTML 浏览页。
- `$atk-tune`：根据报告调优 Agent。
