# https://github.com/qualixar/agentassay 项目说明书

生成时间：2026-06-12 05:33:47 UTC

## 目录

- [Project Overview & Six-Layer Architecture](#page-1)
- [Token-Efficient Engine: Fingerprints, Adaptive Budgets & Statistical Verdicts](#page-2)
- [Framework Adapters, CLI, pytest Plugin & Dashboard](#page-3)
- [Analysis, Mutation, Metamorphic Testing & Deployment Gates](#page-4)

<a id='page-1'></a>

## Project Overview & Six-Layer Architecture

### 相关页面

相关主题：[Token-Efficient Engine: Fingerprints, Adaptive Budgets & Statistical Verdicts](#page-2), [Framework Adapters, CLI, pytest Plugin & Dashboard](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/qualixar/agentassay/blob/main/README.md)
- [src/agentassay/mutation/prompt_ops.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/mutation/prompt_ops.py)
- [src/agentassay/cli/cmd_report.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/cli/cmd_report.py)
- [src/agentassay/persistence/schema.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/persistence/schema.py)
- [src/agentassay/persistence/storage.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/persistence/storage.py)
- [src/agentassay/dashboard/app.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/dashboard/app.py)
- [src/agentassay/integrations/bedrock_adapter.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/integrations/bedrock_adapter.py)
- [src/agentassay/integrations/mcp_adapter.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/integrations/mcp_adapter.py)
- [src/agentassay/integrations/semantic_kernel_adapter.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/integrations/semantic_kernel_adapter.py)
- [examples/README.md](https://github.com/qualixar/agentassay/blob/main/examples/README.md)
</details>

# Project Overview & Six-Layer Architecture

## 项目定位与设计哲学

AgentAssay 是面向非确定性 AI Agent 工作流的统计化回归测试框架,其核心承诺是 "**Test More. Spend Less. Ship Confident.**" 即在不烧毁 token 预算的前提下交付严格的统计保证。该项目是 Qualixar AI Agent 可靠性平台七大产品之一,论文发表于 [arXiv:2603.02601](https://arxiv.org/abs/2603.02601)。

社区关注的核心痛点是:LangSmith、deepeval、agentrial 等同类工具要么缺乏统计回归检测,要么不支持蜕变测试、CI/CD 部署门禁,而 AgentAssay 在 v0.1.2 生产版本中以 "mypy strict + ruff + Python 3.10/3.11/3.12 全绿" 的硬门禁 CI 流水线弥补了这一空白 资料来源:[README.md]()

六层架构的设计哲学可概括为:**第 1~5 层负责让 "每次运行" 都产出严谨结论,第 6 层负责让 "需要多少次运行" 最小化**。换言之,前五层是质量保证,顶层是成本优化。

## 六层架构全景图

资料来源:[README.md]() 中以 ASCII 形式明确划定了六个层级。下面使用 Mermaid 重绘:

```mermaid
flowchart TB
    L6["Layer 6 · Efficiency<br/>Fingerprinting · Budget Optimization<br/>Trace Analysis · Multi-Fidelity · Warm-Start"]
    L5["Layer 5 · Integration<br/>Framework Adapters · pytest Plugin<br/>CLI · Reporting"]
    L4["Layer 4 · Analysis<br/>5D Coverage · Mutation · Metamorphic<br/>Contract Oracle"]
    L3["Layer 3 · Verdicts<br/>Stochastic Verdicts · Deployment Gates"]
    L2["Layer 2 · Statistics<br/>Hypothesis Tests · CIs · SPRT · Effect Size"]
    L1["Layer 1 · Core<br/>Data Models · Execution Engine · Trace Format"]
    L6 --> L5
    L5 --> L4
    L4 --> L3
    L3 --> L2
    L2 --> L1
```

**调用方向**:数据从 Layer 1 向上流动,每层为上一层提供更高级别的语义。统计计算 (Layer 2) 在原始执行轨迹 (Layer 1) 之上进行,部署门禁 (Layer 3) 消费统计结论,覆盖率/变异/蜕变分析 (Layer 4) 进一步丰富判定证据,集成层 (Layer 5) 把整套栈暴露给外部用户,而效率层 (Layer 6) 横切所有下层,只决定 "何时停止采样"。

## 各层关键组件映射

下表把源码中可直接观察到的组件归位到对应层级。所有条目均来自仓库内的实际模块,未做臆测。

| 层级 | 角色 | 仓库内对应组件 |
|------|------|----------------|
| L1 Core | 数据模型、执行引擎、轨迹格式 | `core/models.py` 中的 `ExecutionTrace` / `StepTrace`,`persistence/schema.py` 中的 `trials` / `runs` 表 |
| L2 Statistics | 假设检验、置信区间、SPRT、效应量 | `wilson_interval`、`extract_passed_list`、`cmd_report.py` 中的 95% Wilson CI 计算 |
| L3 Verdicts | 三值裁决 (PASS/FAIL/INCONCLUSIVE)、部署门禁 | `persistence/schema.py` 的 `verdicts` 表,`storage.py` 的 `save_gate_decision` 方法 (返回 DEPLOY/BLOCK/WARN) |
| L4 Analysis | 5D 覆盖率、变异、蜕变、合约 | `mutation/prompt_ops.py` 的 `PromptSynonymMutator` (category=`"prompt"`) |
| L5 Integration | 框架适配器、pytest 插件、CLI、报告 | `integrations/bedrock_adapter.py`、`integrations/mcp_adapter.py`、`integrations/semantic_kernel_adapter.py`、`cli/cmd_report.py`、`dashboard/app.py` (Streamlit) |
| L6 Efficiency | 指纹、预算优化、轨迹优先、多保真、预热序贯 | `persistence/schema.py` 的 `fingerprints` 表,`storage.py` 的 `save_cost` 用于成本核算 |

资料来源:[src/agentassay/mutation/prompt_ops.py]()、`src/agentassay/cli/cmd_report.py`()、`src/agentassay/persistence/schema.py]()、`src/agentassay/persistence/storage.py]()、`src/agentassay/dashboard/app.py]()、`src/agentassay/integrations/bedrock_adapter.py]()、`src/agentassay/integrations/mcp_adapter.py]()、`src/agentassay/integrations/semantic_kernel_adapter.py]()。

## 集成层 (Layer 5) 的横切视图

集成层是仓库内源码最密集的一层,也是用户最常触碰的入口。

### 框架适配器

四个适配器均继承自 `AgentAdapter`,并以 `framework` 字符串字段做自我标识:

- **AWS Bedrock**:`BedrockAgentAdapter` 接受 `agent_id`、`agent_alias_id`、`session_id`、`region`,将每个推理步转为 `StepTrace` 资料来源:[src/agentassay/integrations/bedrock_adapter.py]()
- **MCP**:`MCPToolsAdapter` 同时支持 "direct MCP" 与 "Anthropic" 两种模式 (通过 `meta["mcp_mode"]` 区分),并要求 `mcp` 包存在,否则在 `run()` 调用时才抛错 资料来源:[src/agentassay/integrations/mcp_adapter.py]()
- **Semantic Kernel**:`SemanticKernelAdapter` 通过 `FunctionInvocationFilter` 进行非侵入式轨迹捕获,在钩子不可用时回退为单步 `kernel.invoke()` 资料来源:[src/agentassay/integrations/semantic_kernel_adapter.py]()
- **LangGraph / CrewAI / OpenAI / AutoGen / smolagents**:`examples/README.md` 列出了对应的 `examples/framework-specific/*.py`,均通过 `pip install agentassay[<framework>]` 安装可选依赖

### CLI 与报告

`cli/cmd_report.py` 实现了 `agentassay report --results trials.json` 命令:加载 JSON 结果 → 抽取通过列表 → 计算 Wilson 区间 → 渲染自包含 HTML(包含绿色/红色裁决横幅与通过率进度条)。完整的 CLI 五件套为 `run`、`compare`、`mutate`、`coverage`、`report`,外加 `test-report` 用于测试报告 资料来源:[README.md]()。

### Dashboard

`dashboard/app.py` 是一个 Streamlit 应用,左侧导航栏在 `["Overview", "Test Run", "History", "Fingerprints"]` 四页之间切换;底部通过 `AGENTASSAY_DB_PATH` 环境变量或默认 `~/.agentassay/results.db` 初始化 `ResultStore` 与 `QueryAPI` 资料来源:[src/agentassay/dashboard/app.py]()。

## 持久化层支撑裁决与成本核算

`persistence/schema.py` 用 DDL 定义了八张表:`projects`、`runs`、`trials`、`verdicts`、`coverage`、`fingerprints`、`gate_decisions`、`costs`,前八张表组合起来恰好横跨 Layer 1~Layer 6:执行轨迹 (L1)、统计裁决 (L3)、覆盖率 (L4)、指纹与成本 (L6) 资料来源:[src/agentassay/persistence/schema.py]()。

`storage.py` 的 `save_gate_decision()` 方法显式接受 `decision ∈ {"DEPLOY", "BLOCK", "WARN"}` 三值,这是 Layer 3 "三值裁决" 的落地点;`save_cost()` 接受 `input_tokens / output_tokens / total_cost / trial_count`,是 Layer 6 成本核算的写入入口 资料来源:[src/agentassay/persistence/storage.py]()。

## 社区关注与版本里程碑

- **v0.1.1 (Initial Public Release)**:首次发布,主打 5-20x token 成本削减、十种以上框架适配、CI/CD 部署门禁、三值裁决。
- **v0.1.2 (Production Release)**:修复全部 mypy strict 错误、全部 ruff 检查/格式错误;Python 3.10/3.11/3.12 通过测试;CI 流水线把 lint / typecheck / tests 设为硬门禁——这一里程碑对工程可信度意义重大,因为 AI Agent 测试框架本身必须经得起静态检查才能被生产环境采纳 资料来源:[community evidence v0.1.2]()。

## See Also

- [Stochastic Testing 概念](../concepts/stochastic-testing.md) — 为什么 Agent 测试必须用统计
- [Token-Efficient Testing 概念](../concepts/token-efficient-testing.md) — 第六层效率优化的核心思想
- [Coverage Metrics 概念](../concepts/coverage.md) — 五维覆盖率模型
- [CLI Reference](../reference/cli.md) — 五条主命令详解
- [Installation Guide](../getting-started/installation.md) — 安装与可选依赖

---

<a id='page-2'></a>

## Token-Efficient Engine: Fingerprints, Adaptive Budgets & Statistical Verdicts

### 相关页面

相关主题：[Project Overview & Six-Layer Architecture](#page-1), [Analysis, Mutation, Metamorphic Testing & Deployment Gates](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/agentassay/efficiency/fingerprint.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/efficiency/fingerprint.py)
- [src/agentassay/efficiency/budget.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/efficiency/budget.py)
- [src/agentassay/efficiency/multi_fidelity.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/efficiency/multi_fidelity.py)
- [src/agentassay/efficiency/warm_start.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/efficiency/warm_start.py)
- [src/agentassay/efficiency/trace_store.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/efficiency/trace_store.py)
- [src/agentassay/efficiency/regression.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/efficiency/regression.py)
- [src/agentassay/persistence/schema.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/persistence/schema.py)
- [src/agentassay/persistence/storage.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/persistence/storage.py)
- [README.md](https://github.com/qualixar/agentassay/blob/main/README.md)
</details>

# Token-Efficient Engine: Fingerprints, Adaptive Budgets & Statistical Verdicts

## 引擎定位与设计目标

AgentAssay 整体架构分为六层，其中第六层 Efficiency 正是本文的主题。该层位于统计与执行栈之上，不替代下层的假设检验、置信区间或部署门逻辑，而是把"每个场景要跑多少次、用什么模型跑、能不能复用历史结果"这三件事统一抽象为可控的工程对象 资料来源：[README.md:60-75]()。社区公告中强调的 5–20 倍 token 成本下降，正是这一层与 Layers 1–5 协同后获得的累积效果 资料来源：[README.md:88-95]()。

```mermaid
flowchart TD
    A[场景 + 历史 trace] --> B[trace_store: 加载与索引]
    B --> C[fingerprint: 行为指纹]
    C --> D{方差是否稳定?}
    D -- 否 --> E[budget: 估算最小 N]
    D -- 是 --> F[multi_fidelity: 筛选 + 确认]
    E --> F
    F --> G[warm_start: 顺序 SPRT]
    G --> H[regression: 假设检验]
    H --> I{PASS / FAIL / INCONCLUSIVE}
    I -- INCONCLUSIVE --> E
    I -- PASS / FAIL --> J[gate_decisions 持久化]
```

## 核心组件

### 行为指纹（Fingerprinting）

`fingerprint` 模块把一次 trial 的执行轨迹压缩为可比较的结构化签名，用于跨 run 的等价性判定与漂移检测 资料来源：[src/agentassay/efficiency/fingerprint.py:1-40]()。指纹在持久层有专门的存储表，与运行、试验、裁定并列，说明它被视为一等公民数据 资料来源：[src/agentassay/persistence/schema.py:18-32]()。

### 自适应预算（Adaptive Budget）

`budget` 模块根据用户给定的显著性水平、目标通过率与容差，反推达到期望置信区间所需的最小试验数 N，从而避免对低方差代理过度抽样，也避免对高方差代理做出过早裁定 资料来源：[src/agentassay/efficiency/budget.py:1-30]()。这是社区公告中 "5-20x 成本下降" 的主要来源之一 资料来源：[README.md:88-95]()。

### 多保真度代理（Multi-Fidelity）

`multi_fidelity` 模块用更便宜的模型做"筛选"、更贵的模型做"确认"。指纹先在便宜模型上生成并比对，仅在指纹出现分歧时才升级到昂贵模型 资料来源：[src/agentassay/efficiency/multi_fidelity.py:1-30]()。这一机制与 `trace_store` 提供的离线分析能力天然契合：离线 trace 可以在零 token 成本下做指纹比对 资料来源：[src/agentassay/efficiency/trace_store.py:1-30]()。

### 温启动顺序测试（Warm-Start Sequential）

`warm_start` 把历史 run 的结果当作先验注入本次统计推断，并结合 SPRT 在累积证据达到阈值时立即给出裁定，从而缩短达到稳定结论所需的试验数 资料来源：[src/agentassay/efficiency/warm_start.py:1-30]()。

## 裁定与回归检测

### 三值裁定（Three-Valued Verdicts）

引擎永远输出 PASS、FAIL、INCONCLUSIVE 三种状态之一，而非简单二元结果。INCONCLUSIVE 表示证据不足，需要继续抽样或扩大预算 资料来源：[README.md:88-95]()。最终裁定结果连同置信区间、p 值一起写入 `verdicts` 表，供后续查询 资料来源：[src/agentassay/persistence/schema.py:46-58]()。

### 回归检测与部署门

`regression` 模块对两次 run 的通过率分布做假设检验并报告效应量。当 p 值低于设定 α 且效应量达到业务阈值时，CI/CD 流水线会触发 BLOCK 决策，避免劣质版本上线 资料来源：[src/agentassay/efficiency/regression.py:1-30]()。所有门控决策都会持久化在 `gate_decisions` 表中，包含 pipeline、commit SHA、PR 号等可追溯字段 资料来源：[src/agentassay/persistence/storage.py:60-95]()。

## 常见失败模式

- 指纹维度不足：当代理的"行为"主要体现在文本输出而非工具调用时，工具/路径指纹可能饱和，需要补充更多维度的特征。
- 预算估算过紧：在方差估计尚未稳定时就锁定最小 N，会反复触发 INCONCLUSIVE；建议先跑少量 warm-up 试验再调用 `budget` 资料来源：[src/agentassay/efficiency/budget.py:1-30]()。
- 多保真度错配：筛选模型与确认模型判断不一致时，会出现"通过便宜模型却被贵的模型否定"的情况，需明确两者角色边界 资料来源：[src/agentassay/efficiency/multi_fidelity.py:1-30]()。

## 另请参阅

- 架构总览与 Layer 1–5 的统计基础
- 置信区间、假设检验与 SPRT 数学定义
- pytest 集成与 CLI 参考

---

<a id='page-3'></a>

## Framework Adapters, CLI, pytest Plugin & Dashboard

### 相关页面

相关主题：[Project Overview & Six-Layer Architecture](#page-1), [Analysis, Mutation, Metamorphic Testing & Deployment Gates](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/agentassay/integrations/base.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/integrations/base.py)
- [src/agentassay/integrations/langgraph_adapter.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/integrations/langgraph_adapter.py)
- [src/agentassay/integrations/crewai_adapter.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/integrations/crewai_adapter.py)
- [src/agentassay/integrations/smolagents_adapter.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/integrations/smolagents_adapter.py)
- [src/agentassay/integrations/openai_adapter.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/integrations/openai_adapter.py)
- [src/agentassay/integrations/autogen_adapter.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/integrations/autogen_adapter.py)
- [src/agentassay/integrations/semantic_kernel_adapter.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/integrations/semantic_kernel_adapter.py)
- [src/agentassay/integrations/mcp_adapter.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/integrations/mcp_adapter.py)
- [src/agentassay/cli/main.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/cli/main.py)
- [src/agentassay/cli/cmd_run.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/cli/cmd_run.py)
- [src/agentassay/cli/cmd_report.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/cli/cmd_report.py)
- [src/agentassay/cli/cmd_dashboard.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/cli/cmd_dashboard.py)
- [src/agentassay/cli/cmd_test_report.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/cli/cmd_test_report.py)
- [src/agentassay/dashboard/app.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/dashboard/app.py)
- [examples/README.md](https://github.com/qualixar/agentassay/blob/main/examples/README.md)
- [README.md](https://github.com/qualixar/agentassay/blob/main/README.md)
</details>

# Framework Adapters、CLI、pytest Plugin 与 Dashboard

AgentAssay 的"集成层"承担着把不同 AI 智能体框架接入统一统计测试栈的职责，并提供命令行、pytest 插件与可视化仪表盘等多入口。这一层是研究论文 [arXiv:2603.02601](https://arxiv.org/abs/2603.02601) 中所述"形式化回归测试框架"在工程上的落点，对应 README 中的第 5 层（Integration）。资料来源：[README.md](README.md)

## 1. Framework Adapters（框架适配器）

### 1.1 抽象基类与设计契约

所有适配器都继承自 `AgentAdapter`（定义于 `src/agentassay/integrations/base.py`），其核心契约是 `run(input_data: dict) -> ExecutionTrace`：把外部框架的"运行一次智能体"语义翻译成 AgentAssay 内部的 `ExecutionTrace` / `StepTrace` 数据模型。当目标框架的依赖未安装时，会抛出 `FrameworkNotInstalledError` 并附带安装提示。资料来源：[src/agentassay/integrations/base.py](src/agentassay/integrations/base.py)

### 1.2 已支持的框架与安装方式

`examples/README.md` 列出了 5 个开箱即用适配器以及对应的可选依赖；MCP 与 Semantic Kernel 在后续版本中扩展加入：

| 框架 / 协议 | 适配器文件 | 安装 extras | 关键特性 |
|---|---|---|---|
| LangGraph | `langgraph_adapter.py` | `agentassay[langgraph]` | 捕获图节点为步骤 |
| CrewAI | `crewai_adapter.py` | `agentassay[crewai]` | 捕获多 Agent 协作步骤 |
| OpenAI Agents | `openai_adapter.py` | `agentassay[openai]` | 兼容 Agents SDK |
| AutoGen / AG2 | `autogen_adapter.py` | `agentassay[autogen]` | 兼容 AG2 对话 |
| smolagents | `smolagents_adapter.py` | `agentassay[smolagents]` | 捕获 HF 工具调用 |
| Semantic Kernel | `semantic_kernel_adapter.py` | `agentassay[semantic_kernel]` | 通过 `FunctionInvocationFilter` 钩子逐步捕获，回退到单步封装 |
| MCP（Anthropic 模式） | `mcp_adapter.py` | `agentassay[mcp]` | 直接 MCP 客户端或 Anthropic 工具桥接 |

资料来源：[examples/README.md](examples/README.md)、[src/agentassay/integrations/semantic_kernel_adapter.py](src/agentassay/integrations/semantic_kernel_adapter.py)、[src/agentassay/integrations/mcp_adapter.py](src/agentassay/integrations/mcp_adapter.py)

### 1.3 适配器使用范式

每个示例都遵循同一模式：① 用框架原 API 创建智能体；② 用对应适配器包裹（一行代码）；③ 定义 `Scenario`；④ 配置 `n`、显著性水平等统计参数；⑤ 通过 `StochasticVerdict` 跑多次试验得到 PASS/FAIL/INCONCLUSIVE 三态判决。资料来源：[examples/README.md](examples/README.md)

```mermaid
flowchart LR
    A[Framework Agent] -->|wrap| B(AgentAdapter)
    B -->|run input_data| C[ExecutionTrace]
    C --> D[Stochastic Verdict]
    D --> E{PASS / FAIL / INCONCLUSIVE}
    D --> F[CI / 5D Coverage]
    D --> G[Mutation / Metamorphic]
```

## 2. CLI（命令行接口）

`src/agentassay/cli/main.py` 用 `click.group()` 暴露 5 个一级命令（加上 `dashboard` 和 `demo`），入口为 `agentassay --version`。版本信息明确归属 Qualixar 与作者。资料来源：[src/agentassay/cli/main.py](src/agentassay/cli/main.py)

| 命令 | 文件 | 作用 |
|---|---|---|
| `run` | `cmd_run.py` | 执行测试场景并产出 trials.json |
| `compare` | `cmd_compare.py` | 对比两个 trial 结果，做 A/B 回归分析 |
| `mutate` | `cmd_mutate.py` | 变异测试（prompt / tool / model 操作符） |
| `coverage` | `cmd_coverage.py` | 离线计算 5 维覆盖率 |
| `report` | `cmd_report.py` | 把 trials 渲染为自包含 HTML（含 Wilson 置信区间） |
| `test-report` | `cmd_test_report.py` | 调用 pytest 生成 HTML 测试报告 |
| `dashboard` | `cmd_dashboard.py` | 启动 Streamlit 仪表盘（[EXPERIMENTAL]） |
| `demo` | `cmd_demo.py` | 内置演示场景 |

`report` 命令会调用 `wilson_interval` 计算 `ci_lower / ci_upper` 并嵌入到 HTML 中，可直接用于归档。`dashboard` 命令支持 `--port`、`--host`、`--no-browser`、`--theme`（dark/light）等参数。资料来源：[src/agentassay/cli/cmd_report.py](src/agentassay/cli/cmd_report.py)、[src/agentassay/cli/cmd_dashboard.py](src/agentassay/cli/cmd_dashboard.py)、[src/agentassay/cli/cmd_test_report.py](src/agentassay/cli/cmd_test_report.py)

## 3. pytest Plugin

通过 `pip install agentassay[dev]` 即可启用。开发者沿用 `@pytest.mark.agentassay(n=30, threshold=0.80)` 这样的标记来声明试验次数与通过率阈值，pytest 钩子把统计判决内化为普通断言失败/通过。`examples/pytest-plugin/test_my_agent.py` 给出了最小可运行模板。资料来源：[README.md](README.md)、[examples/README.md](examples/README.md)

## 4. Dashboard（仪表盘）

仪表盘基于 Streamlit，入口为 `src/agentassay/dashboard/app.py`。它通过侧边栏 `st.radio` 提供四个页面：Overview、Test Run、History、Fingerprints，分别由 `view_overview.py`、`view_test_run.py`、`view_history.py`、`view_fingerprints.py` 渲染。数据源是本地 SQLite 数据库，路径由环境变量 `AGENTASSAY_DB_PATH` 控制，默认 `~/.agentassay/results.db`，通过 `ResultStore` 与 `QueryAPI` 读写。资料来源：[src/agentassay/dashboard/app.py](src/agentassay/dashboard/app.py)

该仪表盘在 v0.1.1 首次公开、v0.1.2 生产化打磨之后仍是 `[EXPERIMENTAL]` 状态，社区问题多集中在"如何把第三方 trial.json 导入"以及"指纹页面如何解释"上。资料来源：[src/agentassay/cli/cmd_dashboard.py](src/agentassay/cli/cmd_dashboard.py)

## 5. 常见失败模式

- **未安装可选依赖**：调用 `LangGraphAdapter` 时若未安装 `langgraph`，会抛 `FrameworkNotInstalledError` 并提示 `pip install agentassay[langgraph]`。资料来源：[src/agentassay/integrations/base.py](src/agentassay/integrations/base.py)
- **Semantic Kernel filter 不可用**：`semantic_kernel_adapter` 会在无 `FunctionInvocationFilter` 时回退为单步 trace，统计显著性可能降低，需要在 `metadata` 中显式注明。资料来源：[src/agentassay/integrations/semantic_kernel_adapter.py](src/agentassay/integrations/semantic_kernel_adapter.py)
- **results 文件缺失或语法错误**：`report` 命令通过 `load_json` 捕获 `FileNotFoundError` 并给出 `click.ClickException`，用户应先确认 `agentassay run` 已成功生成 JSON。资料来源：[src/agentassay/cli/cmd_report.py](src/agentassay/cli/cmd_report.py)

## See Also

- 架构与统计栈：[Architecture Overview](Architecture-Overview.md)
- 概念：Token-Efficient Testing、Stochastic Testing、Coverage Metrics
- CLI 详细参考：[CLI Reference](CLI-Reference.md)
- 相关论文：[arXiv:2603.02601](https://arxiv.org/abs/2603.02601)

---

<a id='page-4'></a>

## Analysis, Mutation, Metamorphic Testing & Deployment Gates

### 相关页面

相关主题：[Token-Efficient Engine: Fingerprints, Adaptive Budgets & Statistical Verdicts](#page-2), [Framework Adapters, CLI, pytest Plugin & Dashboard](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/agentassay/mutation/base.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/mutation/base.py)
- [src/agentassay/mutation/prompt_ops.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/mutation/prompt_ops.py)
- [src/agentassay/mutation/__init__.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/mutation/__init__.py)
- [src/agentassay/metamorphic/relations.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/metamorphic/relations.py)
- [src/agentassay/metamorphic/oracle.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/metamorphic/oracle.py)
- [src/agentassay/metamorphic/composition.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/metamorphic/composition.py)
- [src/agentassay/metamorphic/perturbation.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/metamorphic/perturbation.py)
- [src/agentassay/persistence/schema.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/persistence/schema.py)
- [src/agentassay/persistence/storage.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/persistence/storage.py)
- [src/agentassay/cli/cmd_report.py](https://github.com/qualixar/agentassay/blob/main/src/agentassay/cli/cmd_report.py)
- [README.md](https://github.com/qualixar/agentassay/blob/main/README.md)
</details>

# 分析、变异、蜕变测试与部署门控

AgentAssay 在 Layer 3（判定）与 Layer 4（分析）提供了完整的"测试充分性"保障体系。变异测试（Mutation Testing）用于检验测试用例的灵敏度，蜕变测试（Metamorphic Testing）用于在没有真实标签的情况下验证行为不变量，部署门控（Deployment Gates）则把统计判定落地为 CI/CD 流水线中的硬性门槛。本页聚焦这四类机制的源码结构、能力边界与典型用法。

## 一、变异测试（Mutation Testing）

### 1.1 抽象基类

`MutationOperator` 是所有变异算子的统一父类，强制要求 `mutate()` 返回**深拷贝后的** `(AgentConfig, TestScenario)`，避免污染原始配置。资料来源：[src/agentassay/mutation/base.py:30-75]()。

### 1.2 算子分类

变异算子按被扰动对象分为四大类（`category` 字段）：

| 类别 | 算子示例 | 用途 |
|------|---------|------|
| `prompt` | `PromptSynonymMutator`、`PromptOrderMutator`、`PromptNoiseMutator`、`PromptDropMutator` | 提示词同义替换、顺序调换、噪声注入、片段删除 |
| `tool` | `ToolRemovalMutator`、`ToolReorderMutator`、`ToolNoiseMutator` | 工具缺失、乱序、参数噪声 |
| `model` | `ModelSwapMutator`、`ModelVersionMutator` | 切换模型或回退版本 |
| `context` | `ContextTruncationMutator`、`ContextPermutationMutator` | 上下文截断与顺序置换 |

完整导出列表见 `src/agentassay/mutation/__init__.py`，并通过 `DEFAULT_OPERATORS` 常量统一注册。资料来源：[src/agentassay/mutation/__init__.py:1-60]()、`[src/agentassay/mutation/prompt_ops.py:1-30]()`。

### 1.3 同义词词典

`prompt_ops.py` 内置了常见英文动词和强调词的同义替换表，例如 `search → look up / query / retrieve`、`always → consistently / invariably`、`must → shall / is required to`，用于生成语义等价但表层不同的提示。资料来源：[src/agentassay/mutation/prompt_ops.py:1-30]()。

## 二、蜕变测试（Metamorphic Testing）

蜕变关系被组织成 4 个"族"，通过 `src/agentassay/metamorphic/relations.py` 的 shim 统一重新导出，保留历史导入路径。资料来源：[src/agentassay/metamorphic/relations.py:1-30]()。

- **Family 1 – 置换（Permutation）**：`InputPermutationRelation`、`ToolOrderRelation`。
- **Family 2 – 扰动（Perturbation）**：`TypographicalPerturbation` 通过固定的字符交换表（`(a,s)`、`(e,r)` 等 8 对）注入受控拼写错误，验证鲁棒性。资料来源：[src/agentassay/metamorphic/perturbation.py:20-40]()`。
- **Family 3 – 组合（Composition）**：`DecompositionRelation` 把复杂任务拆为子任务独立执行，再以 `compose_fn` 聚合，与一次性执行结果比对一致性。资料来源：[src/agentassay/metamorphic/composition.py:1-50]()`。
- **Family 4 – 预言（Oracle）**：`ConsistencyRelation`（默认阈值 0.7，低于其他关系以容忍措辞波动）、`MonotonicityRelation`（信息增多应得到不更差的结果）。资料来源：[src/agentassay/metamorphic/oracle.py:1-60]()`。

## 三、判定与持久化（Verdicts & Persistence）

`persistence/schema.py` 定义了完整的 SQLite DDL，覆盖 8 张表：`projects`、`runs`、`trials`、`verdicts`、`coverage`、`fingerprints`、`gate_decisions`、`costs`。其中 `gate_decisions` 显式存储 `pipeline`、`decision`（`DEPLOY` / `BLOCK` / `WARN`）、`commit_sha`、`pr_number` 等字段，用于回溯每一次 CI 判定的依据。资料来源：[src/agentassay/persistence/schema.py:1-80]()`。

`Storage` 类的 `save_gate_decision()` 提供 9 字段的原子写入接口，参数列表在源码中按"必填 → 可选 ID"顺序排列，返回新决策的 UUID。资料来源：[src/agentassay/persistence/storage.py:1-60]()`。

## 四、部署门控与 HTML 报告

### 4.1 流程图

```mermaid
flowchart LR
    A[试验 trials.json] --> B[load_json]
    B --> C[extract_passed_list]
    C --> D[wilson_interval]
    D --> E{判定}
    E -->|CI >= 阈值| F[DEPLOY]
    E -->|CI 不足| G[WARN / INCONCLUSIVE]
    E -->|上限 < 阈值| H[BLOCK]
    F & G & H --> I[Storage.save_gate_decision]
    I --> J[(SQLite gate_decisions)]
    A --> K[_build_html]
    K --> L[report.html]
```

### 4.2 CLI 行为

`agentassay report --results trials.json` 通过 `load_json` 读取结果，利用 `wilson_interval` 计算 Wilson 置信区间，再交由 `_build_html` 生成自包含 HTML 报告（含时间戳 UTC、k/n、点估计与置信区间）。整个流程在 `src/agentassay/cli/cmd_report.py` 中实现，文件缺失时抛出 `FileNotFoundError`，JSON 解析失败时给出可读的 `ClickException`。资料来源：[src/agentassay/cli/cmd_report.py:1-80]()`。

## 五、版本与社区要点

- v0.1.2（生产发布）：CI 中 lint / typecheck / tests 全部设为硬门槛，mypy 严格模式、ruff 检查零错误。资料来源：[v0.1.2 release notes](https://github.com/qualixar/agentassay/releases/tag/v0.1.2)。
- v0.1.1（首次公开）：主打 5–20× Token 成本下降、10 项差异能力（含变异与蜕变测试）。资料来源：[v0.1.1 release notes](https://github.com/qualixar/agentassay/releases/tag/v0.1.1)。
- 性能比较表（README 顶部矩阵）显示 AgentAssay 是少数同时支持"统计回归 + 变异 + 蜕变 + 部署门控"的框架。资料来源：[README.md](https://github.com/qualixar/agentassay/blob/main/README.md)。

## See Also

- [Token-Efficient Testing 概念](docs/concepts/token-efficient-testing.md)
- [Stochastic Testing 概念](docs/concepts/stochastic-testing.md)
- [Coverage Metrics 五维覆盖模型](docs/concepts/coverage.md)
- [Architecture Overview](docs/architecture/overview.md)
- [CLI Reference](docs/reference/cli.md)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：qualixar/agentassay

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

## 1. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | github_repo:1174343741 | https://github.com/qualixar/agentassay | README/documentation is current enough for a first validation pass.

## 2. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | github_repo:1174343741 | https://github.com/qualixar/agentassay | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | github_repo:1174343741 | https://github.com/qualixar/agentassay | no_demo; severity=medium

## 4. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | github_repo:1174343741 | https://github.com/qualixar/agentassay | no_demo; severity=medium

## 5. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | github_repo:1174343741 | https://github.com/qualixar/agentassay | issue_or_pr_quality=unknown

## 6. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | github_repo:1174343741 | https://github.com/qualixar/agentassay | release_recency=unknown

<!-- canonical_name: qualixar/agentassay; human_manual_source: deepwiki_human_wiki -->