code-audit

代码审计技能

目的

对代码库或部分文件进行全面且与语言无关的审计，生成一份按严重程度排列问题的结构化报告。根据用户选择的格式（见下文“报告格式”），在项目根目录生成一份独立文件：遵循 references/report-template-html.md 的 HTML 文件，或遵循 references/report-template.md 的 Markdown 文件。

工作投入程度

阅读范围内代码的每一行。不要略读、抽样，也不要依靠启发式方法跳过文件。从外部输入开始，经过处理层，一直到输出和存储，追踪数据流。跨模块边界跟进调用链，以发现只有组件交互时才会出现的问题。当范围大到无法一次完成时，将工作拆分给多个并行子 Agent（分区策略见步骤 4）。

报告格式

审计会在项目根目录生成一份独立文件。格式决定文件扩展名和步骤 5 使用的模板。默认使用 HTML，因为它支持内嵌 SVG 数据流图、严重程度徽标、可折叠的意图简报主题，以及问题之间的交叉引用锚点；这些功能能显著改善篇幅较长的审计报告，而 Markdown 无法实现。

**在确定范围之前确定格式。** 这是硬性门槛——本次运行中，在格式确定之前，不得开始确定范围、发现意图、分析或执行任何其他工作。

首先，检查用户发起任务的消息中是否明确选择了格式。识别以下任一信号：

• HTML 信号：HTML、html、“as a webpage”、“browser-viewable”、“rendered report”。
• Markdown 信号：MD、md、Markdown、markdown、“plain text report”、“as Markdown”。

如果发起任务的消息中包含明确的格式信号，请将其作为门槛问题的答案并继续——无需再次请求形式上的确认。在说明已确定的范围时，简要说明所选格式。

如果发起任务的消息中未指定格式，请只提出以下问题（或含义相同的问题），然后等待用户答复再继续：

您希望使用哪种报告格式？HTML（默认，包含内嵌图表和严重程度徽标的独立文件）还是 MD（纯 Markdown）？

不要将此问题与任何其他内容一并输出。未询问前，不要自行假定默认格式。每次运行此技能时，都必须执行此门槛检查。

选择格式后，在本次运行的其余环节中始终使用该格式：

格式	模板	文件名
HTML	references/report-template-html.md	AUDIT-REPORT-YYYY-MM-DD.html
MD	references/report-template.md	AUDIT-REPORT-YYYY-MM-DD.md

生成 HTML 报告时，应将 references/report-template-html.md 中说明的 HTML 专属功能视为可用工具，并在能增加信息时使用，而非仅作装饰。若只是将 Markdown 内容包裹在 HTML 标签中，却不使用这些功能，就违背了选择 HTML 的初衷。

工作流程

步骤 1 — 确定范围

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

• 整个仓库或工作目录。
• 一个或多个目录（例如，src/、lib/api/）。
• 一组特定文件。
• 用自然语言描述的功能区域（例如，“身份验证流程”）。
• 文件中的特定函数、类或代码区域。在这种情况下，将分析范围限定为指定代码及其直接依赖项，不要审计整个文件。

如果用户指定的文件或目录不存在，请告知其缺失路径，并继续处理存在的文件。如果指定的路径都不存在，请停止并请求澄清。

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

如果用户要求重新审计，请在项目根目录搜索匹配 AUDIT-REPORT-*.md 和 AUDIT-REPORT-*.html 的文件。如果存在多份报告，则无论格式如何，都使用文件修改时间最新的一份。默认采用原始审计的相同范围。如果用户想要更快完成审计，可以提议将范围缩小到仅包含先前发现问题的文件，但不要擅自缩小范围——之前没有问题的文件中也可能出现新问题。如果存在先前的报告，请在新报告中注明哪些先前的问题已解决、哪些仍然存在，以便用户了解差异。新报告的格式应遵循当前运行的门控决定，不必与先前报告的格式相同。

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

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

步骤 2 — 选择并确认类别

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

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

本技能有意不包含安全分析。如果用户的请求涉及安全问题（漏洞、注入、身份验证、授权、机密、密码学、依赖项 CVE、OWASP 问题、IaC、CI/CD 审查），建议改用 security-audit 技能，也可以在本次审计之外同时运行该技能。如果在本次审计中偶然发现安全问题，只记录一条发现，简要指出问题并建议后续运行 security-audit；不要在此处深入分析。

同时考虑用户明确提出的要求，以及代码本身自然适用的审计类别。例如，如果代码库使用了异步模式，即使用户没有提及，也应纳入并发类别。

对于宽泛的请求（例如“审计此代码库”），默认涵盖所有类别并直接开始审计，无需征求确认。仅当所选类别并非显而易见时，才列出所选类别并请求确认——也就是说，Agent 根据代码分析选择了部分类别，或者用户的请求对适用类别含糊不清。

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

步骤 3 — 发现意图

开始分析前，扫描代码库中记录的意图，包括设计决策、权衡、惯例和已知限制。这有助于区分有意为之的设计与真正的问题，从而减少误报。

并行运行三个子 Agent：

• 文档扫描器 — 阅读整个项目中的所有文档文件（不论审计范围），提取其中说明的决策、权衡、约束和惯例。
• 代码意图扫描器 — 搜索范围内的源文件，查找表达代码选择“原因”的说明性注释、抑制指令和解释性块注释。
• 历史记录扫描器 — 从范围内文件的 Git 提交历史中提取意图信号，重点关注说明修改原因的提交信息。

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

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

如果意图发现没有产生任何条目，意图摘要应为空。分析照常进行，无需交叉参照；报告中的“上下文与意图”部分应说明未发现任何记录的意图信号。

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

步骤 4 — 系统分析

大型代码库分区

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

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

如果无法使用子 Agent，或者范围足够小，则由单个 Agent 按顺序执行所有阶段。如果即使分区分析也无法覆盖每一行代码，则优先深入检查对正确性和可靠性至关重要的路径：入口点、数据持久化、事务边界、错误处理中间件，以及外部 API 边界。

阶段 A — 文件级分析

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

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

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

阶段 B — 跨文件分析

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

• 从入口点（HTTP 处理程序、CLI 解析器、消息使用者、公共 API 接口）追踪数据，经过中间层，直到终端操作（数据库写入、文件 I/O、外部 API 调用、向用户返回响应）。
• 沿追踪路径评估是否在任何环节缺少类型／形状验证、前置条件检查、错误处理或资源清理，即使单独查看每个文件时似乎都没有问题。（授权检查和与安全相关的输入验证由 security-audit 技能评估。）
• 检查架构问题：模块间的循环依赖、各层错误处理策略不一致、会引入隐蔽错误的混合范式，以及多个模块访问的共享可变状态。
• 使用与阶段 A 相同的跳过／降级规则，将新的跨文件发现与 Intent Brief 交叉核对。

记录任何新发现，并更新那些在更广泛的上下文中被证实严重性更高或更低的文件级发现的严重性评估。

去重

进入报告生成前，先对发现进行去重：

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

步骤 5 — 生成报告

按照 Format Gate 中所选格式对应的模板生成最终报告：HTML 输出使用 references/report-template-html.md，Markdown 输出使用 references/report-template.md。以下内容规则适用于两种格式；模板定义结构呈现方式。

• 将报告日期设为当前日期。
• 在摘要表中填写已确认的范围、类别和各严重级别的发现数量。
• 在摘要表与 Critical 严重级别章节之间加入“Context & Intent”章节。该章节概述 Intent Brief，并列出影响本次审计的关键已记录决策。
• 从 AUDIT-001 开始按顺序分配 AUDIT-NNN 标识符。按严重性排序（Critical 优先），然后按类别排序；同一严重性和类别下按文件路径排序。
• 为每条发现填写所有必需字段：标识符、简短标题、类别、位置（file:line）、严重性、描述、影响和建议。
• 使用所选模板规定的文件名格式，将报告保存到项目根目录（HTML 使用 AUDIT-REPORT-YYYY-MM-DD.html，Markdown 使用 AUDIT-REPORT-YYYY-MM-DD.md）；如果同名文件已存在，则递增后缀。

选择 HTML 格式时，还需：

• 严格遵循 references/report-template-html.md 中的结构约定：必需的 ID、类和 data-* 属性不可省略。该脚手架可确保报告能够解析，并支持重新审计差异分析。
• 在能增加信息时使用 HTML 专属功能（内嵌 SVG 数据流图、可折叠的 Intent Brief 主题、发现之间的锚点交叉引用）。如果用文字表达同样清晰，则无需使用；目标是提高信息密度，而非装饰。

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