审计 — 代理改进检测

审计是定期的任务，用于挖掘跨会话的代理日志，找出值得改进的地方。告警监视你已经了解的单个指标并进行近实时通知，而审计调查：按照你设定的计划，它对时间窗口执行确定性策略检查，然后让一个 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>）上： 低信号噪音通过每个审计的每运行发现项限制（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 中记录。

​

API

所有端点均为组织范围，遵循标准 bearer 密钥认证（参见 api-keys.md）。 关于”审计运行但未找到任何内容”、“代码沙箱已禁用”和”审计电子邮件未送达”，参见 troubleshooting.md。