audit

代码审计技能

目的

对整个代码库或部分文件进行全面、与语言无关的审计，并生成按严重程度排序的结构化报告。按照 references/report-template.md 中的模板，将报告以 Markdown 文件形式放在项目根目录。

工作量级别

阅读范围内代码的每一行。不要略读、抽样，也不要依靠启发式方法跳过文件。追踪从外部输入经过处理层，再到输出和存储的数据流。跨模块边界跟进调用链，检测仅在组件交互时才会显现的问题。如果范围过大，无法一次完成审查，请拆分任务并交由多个并行子 Agent 处理（分区策略见步骤 4）。

工作流

步骤 1 — 确定范围

根据用户的提示确定审计范围。用户可能会指定：

• 整个代码仓库或工作目录。
• 一个或多个目录（例如 src/、lib/api/）。
• 特定文件列表。
• 用自然语言描述的功能领域（例如“身份验证流程”）。
• 文件中的特定函数、类或代码区域。此时，仅分析指定代码及其直接依赖项，不要审计整个文件。

如果用户指定的文件或目录不存在，请告知他们缺少哪些路径，并继续处理实际存在的文件。如果指定的路径都不存在，请停止并请求澄清。

如果提示中没有足够的信息来确定范围，请先提出一个澄清问题。不要猜测范围——边界不明确的审计会导致结果不可靠。

如果用户要求重新审计，请在项目根目录中搜索匹配 AUDIT-REPORT-*.md 的文件。如果存在多份报告，请使用日期最新的一份。默认采用原始审计的相同范围。如果用户希望加快审查速度，可以提议仅检查先前发现问题的文件，但不要擅自缩小范围——此前没有问题的文件中也可能出现新问题。如果存在先前的报告，请在新报告中说明先前的哪些问题已解决、哪些仍然存在，以便用户了解差异。

确定范围后，列出范围内的所有文件。除非用户明确要求包含生成文件，否则排除生成文件（例如锁文件、编译输出、供应商依赖项、压缩包）。对于已提交到源码中的生成代码（protobuf 存根、OpenAPI 客户端、ORM 模型），请检查修改标记——如果文件中包含手写内容，或已移除“DO NOT EDIT”标头，则将其纳入审计范围。虽然生成代码和供应商代码不纳入文件级分析，但在阶段 B 的跨文件分析中，应追踪流入这些排除代码的数据流，以确定其是否提供预期的验证或安全保障。在边界处报告问题，不要在排除的代码内部报告。

向用户说明最终确定的范围。如果范围明确无误，请立即继续，无需等待确认。

第 2 步 — 选择并确认类别

分析用户的请求和代码库，从以下完整列表中选择最相关的审计类别：

1. 安全漏洞
2. 竞态条件与并发
3. 死代码
4. 反模式与代码异味
5. 性能
6. 正确性
7. 错误处理缺陷
8. 测试质量

既要考虑用户明确提出的要求，也要考虑代码本身适合审计的方面。例如，如果代码库使用异步模式，即使用户没有提及，也应包括并发类别。

对于宽泛的请求（例如“审计此代码库”），默认选择所有类别并直接继续，无需询问确认。仅当选择不明显时，才展示已选类别并询问确认——也就是 Agent 根据代码分析选择了部分类别，或者用户的请求对适用类别表述不清时。

以 references/categories.md 中的检查清单为系统分析的依据。对于不适用于代码库所用语言、框架或范式的单项检查，予以跳过。如果代码库中没有测试文件，则报告一项说明缺少测试的发现，不要逐项评估测试质量检查清单中的内容。

第 3 步 — 了解意图

在开始分析前，扫描代码库中记录的意图，包括设计决策、权衡取舍、惯例和已知限制。此举可提供背景信息，帮助区分有意为之的选择与真正的问题，从而减少误报。

并行运行三个子 Agent：

• 文档扫描器 — 读取整个项目中的所有文档文件（无论审计范围如何），提取其中说明的决策、权衡取舍、约束和惯例。
• 代码意图扫描器 — 搜索范围内的源文件，查找说明代码选择背后“原因”的理由注释、抑制指令和解释性块注释。
• 历史记录扫描器 — 从范围内文件的 git 提交历史中提取意图线索，重点关注提交信息解释了为何进行某项更改的提交。

无论代码库规模如何，始终执行此步骤。对于采用第 4 步分区策略的大型代码库，所有分区子 Agent 都会共享同一份意图摘要。

输出应为按主题组织的结构化意图摘要（架构决策、有意的权衡取舍、惯例与标准、已知限制与技术债务、已抑制的警告与有意偏离），而非按来源类型组织。目标是不超过 100 条，并按与已确认审计类别的相关性排序。

如果意图发现没有产生任何条目，则意图摘要为空。分析照常进行，无需交叉引用；报告中的“背景与意图”部分应说明未发现任何已记录的意图线索。

详细的子 Agent 提示词、提取规则和意图摘要模板，请参阅 references/intent-discovery.md。

第 4 步 — 系统分析

大型代码库分区

当范围超过 50 个文件或 10,000 行代码时（满足任一阈值即可），使用并行子 Agent，避免分析流于表面。这些阈值特意采用“或”的关系：与文件较少但规模较大的项目一样，包含大量小文件的项目也能从并行处理中受益。

• 将范围划分为逻辑模块或目录子树。尽量让各分区规模大致相等。在包含多个独立服务的 monorepo 中，优先按服务划分——服务边界优先于分层边界。在单个服务内部，优先选择与架构分层（例如数据访问、业务逻辑、API 处理程序）相符的边界，而不是按文件数量任意拆分。
• 每个分区分配一个子 Agent。每个子 Agent 独立对其分区执行阶段 A（文件级分析），遵循相同的检查清单和记录格式。向每个子 Agent 提供代码库整体架构的简要说明、第 3 步中的意图简报，以及适用的检查清单。
• 所有子 Agent 完成后，对合并后的发现执行阶段 B（跨文件分析），重点关注分区之间的交互。特别留意信任边界——从一个分区流向另一个分区的数据，常常是验证遗漏和注入漏洞的来源。
• 对多个子 Agent 在共享或重叠代码中独立发现的问题进行去重。合并为严重性最高的版本，并列出所有受影响的位置。

如果无法使用子 Agent，或范围足够小，则由单个 Agent 按顺序执行所有阶段。如果即使分区分析也无法覆盖每一行代码，则优先深入分析安全关键和正确性关键路径：入口点、身份验证/授权流程、数据持久化，以及外部 API 边界。

阶段 A — 文件级分析

遍历范围内的每个文件。对每个文件：

• 完整阅读文件，不要略读或抽样。
• 逐项检查已确认类别中的检查清单，评估正在检查的代码是否存在所述问题。
• 记录发现之前，将其与意图简报交叉核对。如果简报在确切位置直接且明确地说明了被标记的确切模式，则跳过该问题。如果简报提供了一般背景，但未逐项确认，则降低严重性（以较低严重性报告，并注明所引用的意图来源）。
• 立即记录每项发现，包括文件路径、行号、类别、初步严重性（参见 references/severity-guide.md）、问题描述、影响和具体建议。
• 如果发现涉及超出当前文件的数据流或调用链，则标记以便在阶段 B 中进行跨文件跟进。

如果同一逻辑问题因共享模式（例如，各处都会使用的实用函数）而出现在多个文件中，请避免重复记录。只记录一次，并注明所有受影响的位置。

阶段 B — 跨文件分析

完成文件级审查后，重新检查标记为需要跨文件跟进的问题：

• 从入口点（HTTP 处理程序、CLI 解析器、消息使用者、公共 API 接口）追踪数据，经过中间层直到终端操作（数据库写入、文件 I/O、外部 API 调用、向用户返回响应）。
• 评估沿追踪路径的任何位置是否缺少输入验证、授权、错误处理或资源清理，即使单个文件单独看来都正确。
• 检查架构问题：模块之间的循环依赖、各层错误处理策略不一致、引入细微错误的范式混用，以及从多个模块访问的共享可变状态。
• 使用与阶段 A 相同的跳过／降级规则，将新的跨文件问题与意图简报交叉核对。

记录所有新问题，并更新在更广泛上下文中严重性有所变化的文件级问题的严重性评估。

去重

进入报告生成阶段前，请对问题进行去重：

• 将描述同一根本原因在多个位置表现出来的问题合并为一项。在该问题中列出所有受影响的位置。
• 移除跨文件分析中确认的误报（例如，某个文件中的输入看似未经过验证，但后来发现由中间件层进行了验证）。
• 将源自意图简报中同一项已记录取舍的问题合并为一项，并引用对应的意图条目，列出所有受影响的位置。
• 通过考虑最严重的现实影响，协调相互冲突的严重性评估。

步骤 5 — 生成报告

按照 references/report-template.md 中定义的结构和格式规则生成最终报告。具体要求：

• 将报告日期设为当前日期。
• 在摘要表中填写已确定的范围、已确认的类别以及各严重性级别的问题数量。
• 在摘要表和严重性为 Critical 的部分之间添加“上下文与意图”部分。该部分总结意图简报，并列出影响审计的关键已记录决策。
• 从 AUDIT-001 开始，按顺序分配 AUDIT-NNN 标识符。先按严重性排序（Critical 优先），再按类别排序；同一严重性和类别内按文件路径排序。
• 为每个问题填写所有必需字段：标识符、简短标题、类别、位置（file:line）、严重性、描述、影响和建议。
• 按模板中的文件名约定（AUDIT-REPORT-YYYY-MM-DD.md），将报告保存到项目根目录；如果已存在同名文件，则递增后缀。

保存报告后，告知用户文件路径，并简要总结结果。