> ## 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`**（侧边栏 → *analyze* → *audits*），由 `audits:read` / `audits:write` 权限控制。

***

## 运行如何工作

每次运行有两层 — 确定性基础层和代理调查层。

### 1. 策略检查（确定性）

在任何模型运行之前，审计对时间窗口执行小型 **SQL 策略检查**目录：受限的聚合查询，标记已知的不良模式并报告*有多少*事件 / *哪些*会话匹配 — 绝不报告匹配的文本本身。该目录包括：

* 事件负载中的**机密/凭证泄露** — AWS 访问密钥、`sk-…` API 密钥、PEM 私钥、JWT / bearer 令牌和 `KEY=…` 凭证分配。
* **提示注入标记** — "忽略之前的指令"、"揭示你的系统提示"等类似内容。
* **PII** — SSN 形式的数字（启发式）。
* **工具权限拒绝**和**失控工具调用循环**。

策略命中被持久化为发现项（类型 `policy`），**始终显示**（绝不会因运行限制而被修剪），并作为初始线索提交给 AI 代理。由于此层不需要模型，即使 AI 代理不可用，审计仍能产生其最重要的安全信号。

### 2. 代理调查（AI）

审计随后运行一个**自主可靠性代理**（与驱动仪表板助手的 Claude Agent SDK 服务相同，具有审计特定的提示）。给定审计的**范围**（选定的代理 × 环境）和**时间窗口**，该代理：

* 针对你的分析表运行只读 SQL 查询，
* 阅读数个代表性会话记录，
* 可选地在锁定的在线沙箱中编写和运行短小的 **Python 脚本**（无网络、无文件系统访问、机密已清理）进行 SQL 无法表达的分析 — 错误聚类、计算分布、扫描已获取的负载，
* 并记录它发现的每项有充分证据支持的**改进**。

它通过多条调查线 — 错误聚类、相对基线的漂移、记录中的目标失败、工具误用、质量/成本权衡和覆盖率缺口 — 按照审计的**灵敏度**（低 / 中 / 高）工作。每项改进**必须引用证据**：代理实际检查的会话 ID 和/或运行的 SQL。服务器验证引用的会话是否存在，**放弃任何没有存活证据的改进**，所以代理调查但从不凭空想象。

每项改进包括：

* **建议**（具体的改动 — 提示调整、工具架构修复、重试策略、防护栏、更多评估覆盖），
* **预期影响**和**工作量**估计（低 / 中 / 高），
* **规模** — `big`（应通知操作员）、`medium`（属于运行报告）或 `small`（仪表板上下文），
* 稳定的**指纹**（从问题的类别 + 范围而来，*不*来自此次运行的会话），以便同一问题即使证据改变也能跨运行跟踪，
* 以及在简单确定性监视器可以捕捉重复的情况下，**建议的告警**，你可以一键创建。

> **AI 层是可选但推荐的。** 如果没有为审计管道配置 AI 代理，运行仍会执行、持久化策略发现项，并诚实地报告 AI 层"分析不可用"，而不是默默通过。

### 失败模式

改进被分类到你组织的持久**失败模式目录**中（或提议新模式）。模式跨运行为模式赋予稳定的身份，并实现长期的重复追踪。

## 分类生命周期

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

| 操作                     | 效果                                                                |
| ---------------------- | ----------------------------------------------------------------- |
| **acknowledge**        | 保持发现项可见但将其优先级减半。                                                  |
| **resolve**            | 标记为已修复。如果模式后来确实返回，它作为**新**项重新打开 — 所以回归是明显的，而不是默默折叠到历史中。           |
| **mute** / **dismiss** | 持久抑制：模式的指纹被记住，永远不会再出现，即使跨运行也是如此。用 mute 表示"已知、已接受"；dismiss 表示"无用"。 |
| **reopen**             | 清除抑制/解决状态，并重新排列模式优先级。                                             |

低信号噪音通过每个审计的每运行发现项限制（`top_k`）来控制代理改进。策略发现项绕过限制（它们与安全相关，始终显示）。因限制而被削减的任何内容都计入运行的统计数据 — 没有任何内容被默默放弃。

## 调度

* **频率**（`schedule_interval_secs`）：每小时到每周；**每天是默认值**。审计故意比告警更粗糙 — 代理调查扫描整个窗口并运行数分钟。
* **窗口**：要么是固定的滚动回顾（例如"每次运行扫描过去 7 天"），要么是**自上次运行以来**（默认值） — 每次运行从上次成功运行结束的地方继续，有小范围重叠以确保边界事件不被遗漏。
* 下一次运行计划在前一次运行**完成**后的完整间隔内进行，所以慢运行永远不会堆积同一审计的第二个并发运行。
* 审计页面上的**立即运行**使其立即到期。

## 模型选择

创建审计时，你可以从**操作员为代理服务配置的模型列表**中选择调查使用的模型。配置了单个模型时，选择器将其显示为标题；配置了多个时，你可以选择。保持未设置使用已配置的默认值。

## 通知

当运行出现**新的**发现项时，审计通知你组织已配置的频道 — 与告警管道使用的相同 `alerts.enabled_channels` 门控和设置：

* **Slack** — 重要（`big`）新项的摘要，附带深度链接。
* **电子邮件** — 设计好的**审计报告**，列出新改进项（按严重性排序、每项建议、深度链接），在审计附加了**电子邮件**频道且至少有一项新发现时发送。

重复但已知的发现项不会重新通知。

## 配置参考

审计定义通过仪表板（`/audits/new`）或 API 进行管理。每个审计的设置包括计划频率和窗口、范围（`{"environments": [...], "agent_ids": [...]}`）、灵敏度（`low` / `medium` / `high`）、通知频道、每运行发现项限制（`top_k`）和模型（通过 `llm_budget.model`）。操作员级服务器设置（超时、沙箱、代理服务 URL）在 [deployment.md](/he/agenteye/deployment) 中记录。

## API

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

| 端点                                   | 权限                             | 目的                                                                                  |
| ------------------------------------ | ------------------------------ | ----------------------------------------------------------------------------------- |
| `GET /audits` · `POST /audits`       | `audits:read` / `audits:write` | 列出/创建审计定义。                                                                          |
| `GET` / `PUT` / `DELETE /audits/:id` | 读 / 写 / 写                      | 检查、编辑、删除审计。                                                                         |
| `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](/he/agenteye/troubleshooting#audits)。