> ## Documentation Index
> Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 审计 — 智能体改进检测

> AgentEye 审计 — 智能体改进检测文档。

审计是一种周期性任务，它会**跨会话**挖掘您的智能体日志，寻找值得改进的内容。告警负责近实时监控您已知的某个指标，而审计则负责**深度调查**：按照您设定的计划，在时间窗口内执行一次确定性策略扫描，然后让一个 **AI 可靠性智能体**对您的会话展开自主分析——该智能体会自行查询数据、阅读可疑转录记录，必要时运行小型分析脚本，最终输出带有证据支撑的**改进建议**。

使用审计来回答"我应该修复或改进智能体的哪些方面"，使用告警来在某个特定阈值被触发时立即收到通知。每条改进建议都链接到其背后的具体会话和查询，一键即可创建预填好的告警，以便捕获问题复发。

仪表板入口为 **`/<org-slug>/audits`**（侧边栏 → *分析* → *审计*），需要 `audits:read` / `audits:write` 权限。

***

## 运行机制

每次运行分为两层——确定性基础层和智能体调查层。

### 1. 策略扫描（确定性）

在任何模型运行之前，审计会在时间窗口内执行一组 **SQL 策略检查**：有界的聚合查询，用于标记已知的异常模式，并报告匹配的事件数量和会话列表——但不会返回匹配的具体文本内容。该检查目录包括：

* 事件负载中的**密钥 / 凭证泄露** — AWS 访问密钥、`sk-…` 格式的 API 密钥、PEM 私钥、JWT / Bearer Token，以及 `KEY=…` 格式的凭证赋值。
* **提示词注入标记** — "ignore previous instructions"、"reveal your system prompt" 等类似内容。
* **PII** — 符合 SSN 格式的数字（启发式识别）。
* **工具权限拒绝**和**工具调用失控循环**。

策略命中的结果会以 `policy` 类型的发现持久化，**始终显示**（不受单次运行上限限制），并作为线索提供给 AI 智能体。由于该层不依赖模型，即使 AI 智能体不可用，审计仍能输出最重要的安全信号。

### 2. 智能体调查（AI）

审计随后运行一个**自主可靠性智能体**（与驱动仪表板助手的 Claude Agent SDK 服务相同，但使用审计专用提示词）。根据审计的**范围**（所选智能体 × 环境）和**时间窗口**，该智能体会：

* 对您的分析表执行只读 SQL 查询，
* 阅读少量具有代表性的会话转录记录，
* 可选地在**隔离的 Pod 内沙箱**（无网络、无文件系统访问权限、密钥已清除）中编写并运行短小的 **Python 脚本**，用于 SQL 无法直接表达的分析——如聚类错误、计算分布、扫描已获取的负载，
* 并记录其发现的每条有充分证据支撑的**改进建议**。

智能体会沿多条调查路线展开工作——错误聚类、相对基线的漂移、转录记录中的目标失败、工具误用、质量/成本权衡以及覆盖缺口——调查深度由审计的**灵敏度**（低 / 中 / 高）决定。每条改进建议**必须引用证据**：智能体实际检查过的会话 ID 和/或其运行过的 SQL。服务器会验证引用的会话是否存在，**并丢弃任何无有效证据的改进建议**，因此智能体只负责调查，而不会凭空捏造。

每条改进建议包含以下内容：

* **建议措施**（具体的改进行动——提示词调整、工具 Schema 修复、重试策略、防护措施、更多评估覆盖），
* **预期影响**和**工作量**估算（低 / 中 / 高），
* **严重程度** — `big`（需要通知运维人员）、`medium`（应出现在运行报告中）或 `small`（仅作仪表板上下文），
* 稳定的**指纹**（基于问题的类别和范围，而非本次运行的会话），使得同一问题可在跨运行中持续追踪，即便证据发生变化，
* 以及针对可通过简单确定性监控捕获复发情况的问题，提供**建议告警**，一键即可创建。

> **AI 层为可选但推荐启用。** 如果审计管道未配置 AI 智能体，运行仍会正常执行，持久化策略发现，并如实报告智能体层"分析不可用"，而不是静默通过。

### 失败模式

改进建议会归类到您组织的持久化**失败模式目录**中（或提议创建新模式）。失败模式为各类问题模式提供了跨运行的稳定标识和长期复发追踪能力。

## 分类处理生命周期

在发现详情页（`/audits/<id>/findings/<finding-id>`）：

| 操作                        | 效果                                                                |
| ------------------------- | ----------------------------------------------------------------- |
| **确认（acknowledge）**       | 保持发现可见，但将其优先级降低一半。                                                |
| **解决（resolve）**           | 标记为已修复。如果该模式后来确实复现，将以**新发现**的形式重新打开——确保回归问题醒目呈现，而非悄悄归入历史记录。       |
| **静音（mute）/ 忽略（dismiss）** | 持久化抑制：该模式的指纹将被记录，此后不再出现，即使跨运行也不例外。静音用于"已知且已接受"的情况，忽略用于"无参考价值"的情况。 |
| **重新打开（reopen）**          | 清除抑制 / 解决状态，重新参与排名。                                               |

低价值噪音通过每次审计的单次运行发现上限（`top_k`）进行控制，该上限仅作用于智能体改进建议。策略发现不受此上限限制（属于安全相关内容，始终显示）。被上限截断的内容会计入运行统计数据——不会有任何结果被静默丢弃。

## 调度设置

* **频率**（`schedule_interval_secs`）：从每小时到每周不等；**默认为每天一次**。审计刻意比告警粗粒度——智能体调查需要扫描完整时间窗口，运行时间可达数分钟。
* **时间窗口**：固定的滚动回溯周期（例如"每次运行扫描过去 7 天"）或**从上次运行以来**（默认）——每次运行从上一次成功运行结束的位置继续，并保留少量重叠以确保边界事件不被遗漏。
* 下次运行在上次运行**完成**后整整一个间隔再调度，因此慢速运行不会触发同一审计的并发运行。
* 在审计页面点击**立即运行**可使其立即执行。

## 模型选择

创建审计时，您可以从**运维人员为智能体服务配置的模型列表**中选择调查所用的模型。若仅配置了单个模型，选择器会以说明文字的形式显示；若配置了多个，则由您自行选择。不选则使用配置的默认值。

## 通知

当运行发现**新的**问题时，审计会通知您组织配置的渠道——使用与告警管道相同的 `alerts.enabled_channels` 开关和设置：

* **Slack** — 发送一条包含重要（`big`）新问题摘要及深链接的消息。
* **Email** — 发送精心排版的**审计报告**，列出新的改进建议（按严重程度排序、含逐条建议及深链接），前提是审计已绑定 **email** 渠道，且至少存在一条新发现。

已知的重复性发现不会重复通知。

## 配置参考

审计定义可在仪表板（`/audits/new`）或通过 API 进行管理。每个审计的可配置项包括：调度频率和时间窗口、范围（`{"environments": [...], "agent_ids": [...]}`）、灵敏度（`low` / `medium` / `high`）、通知渠道、单次运行发现上限（`top_k`），以及模型（通过 `llm_budget.model` 指定）。运维层面的服务器设置（超时、沙箱、智能体服务 URL）请参阅 [deployment.md](/zh/agenteye/deployment)。

## API

所有端点均以组织为范围，并遵循标准 Bearer 密钥认证（参见 [api-keys.md](/zh/agenteye/api-keys)）。

| 端点                                   | 权限                             | 用途                                                                                    |
| ------------------------------------ | ------------------------------ | ------------------------------------------------------------------------------------- |
| `GET /audits` · `POST /audits`       | `audits:read` / `audits:write` | 列出 / 创建审计定义。                                                                          |
| `GET` / `PUT` / `DELETE /audits/:id` | read / write / write           | 查看、编辑、删除审计。                                                                           |
| `POST /audits/:id/run`               | `audits:write`                 | 使审计立即执行。                                                                              |
| `GET /audits/:id/runs`               | `audits:read`                  | 运行历史（时间窗口、状态、统计数据、发现数量）。                                                              |
| `GET /audits/findings`               | `audits:read`                  | 组织范围内的发现，可按 `audit_id`、`status` 筛选；按优先级排序。                                            |
| `GET /audits/findings/:fid`          | `audits:read`                  | 完整发现详情（建议、证据、优先级）。                                                                    |
| `POST /audits/findings/:fid/status`  | `audits:write`                 | 分类处理：`{"action": "ack" \| "mute" \| "dismiss" \| "resolve" \| "reopen" \| "assign"}`。 |

如遇"审计已运行但未发现任何问题"、"代码沙箱已禁用"或"审计邮件未送达"等情况，请参阅 [troubleshooting.md](/zh/agenteye/troubleshooting#audits)。