前言¶
接手陌生代码库做安全审计时，常见做法是直接扫模式、追可疑调用。上一轮若没人把「函数假设什么、保证什么、依赖谁」写清楚，后续 findings 往往难以判断真假。Trail of Bits 把「先理解、再判罪」拆成独立阶段，并通过 Agent Skill 固化流程。下面介绍 audit-context-building 的定位、产出与用法。
这是什么¶
audit-context-building 是 Trail of Bits skills 市场里 Code Auditing 类插件下的 Skill。官方描述是：在代码库里找 bug 之前先理解代码——每个函数假设什么、保证什么、在别处依赖什么。适用于审计、威胁建模或架构评审的起点，以及任何漏洞狩猎 pass 之前。
Skill 元数据中的 allowed-tools 为：Workflow、Task、Read、Grep、Glob。
核心理念用一句话概括：Build understanding, not verdicts（建立理解，不下结论）。本阶段为后续狩猎提供上下文，不替代狩猎本身。
核心功能¶
阶段边界¶
适合做的：
- 审计、威胁建模或架构评审开始时，代码尚不熟悉；
- 上一轮已有 findings，但没人梳理系统如何拼在一起时。
明确不做：
- 不命名漏洞、不建议修复、不写 PoC、不评严重级别（这些属于下一阶段的 hunting）；
- 代码已充分理解时，不值得再耗 token。
当代码「指望某条件成立」而「没有任何地方检查」时，本 Skill 要求如实记录并继续，是否构成问题留给后续阶段。
工作流与派发¶
分析篇幅大，主上下文需要保留给后续使用，因此长分析通过子流程写出磁盘，主会话只收回紧凑记录。
- 整个代码库或多个函数 — 运行
/audit-context-building:audit-context <path>。该流程会定向分析，并为每个函数派生子 agent，写出audit-context/DOSSIER.md，并在audit-context/functions/下为每个函数生成一个文件。主上下文只返回紧凑记录。 - 单个函数 — 派发
audit-context-building:function-analyzeragent。分析正文写入磁盘，返回一条记录。
之后从索引、未强制执行的假设（unenforced assumptions）、开放问题入手；需要细节时再读对应函数文件。工作流通过绑定返回 schema 的子 agent 约束行为（不能返回长 prose），Skill 文本主要起路由作用。
产出内容与阅读方式¶
每条函数记录包含：
- 必须恒为真的条件（附对应行号）；
- 函数「默认成立」的假设（及依据，若无则标明）；
- 调用了哪些函数、各自需要从 callee 得到什么；
- 仍不清楚的事项。
DOSSIER.md 补充跨函数的规则、可达性、复杂区域聚集点。
阅读时优先关注两点：
nothing found的假设：代码依赖某条件为真，但全库找不到使其为真的依据——这是交给 hunting 阶段最有价值的输入。- 开放问题（open questions）：诚实列出未弄清之处，比武断闭合更重要；应带入后续阶段而非强行结案。
若两条记录矛盾，应并列引用，不悄悄合并——这反映的是代码或分析事实，而非分析缺陷。
格式与跨领域¶
resources/ANALYSIS_FORMAT.md定义记录格式；resources/FUNCTION_MICRO_ANALYSIS_EXAMPLE.md提供 C 与 Solidity 示例；resources/DOMAIN_NOTES.md说明智能合约、C/C++、反编译固件、Web 服务等目标下，各槽位如何填、哪些调用「看不见内部」。
最重要规则：follow the calls。函数是否正确往往取决于被调函数的行为；仅看 caller 容易误判。需读被调函数、走全路径（不只成功路径），说明每条假设由什么保证；若无，使用 nothing found。每条主张应引用行号，否则列入开放问题。
安装与启用¶
Skill 随 Trail of Bits 插件市场分发，需先添加市场再安装对应插件。
Claude Code
/plugin marketplace add trailofbits/skills
浏览并安装：
/plugin menu
在 Code Auditing 分类中选择 audit-context-building 插件（描述：Understand a codebase before looking for bugs in it, one function at a time）。
Codex
Codex 支持 Claude 插件市场兼容，无需该仓库单独的 Codex sidecar 元数据：
codex plugin marketplace add trailofbits/skills
codex plugin list
codex plugin add <plugin-name>@trailofbits
将 <plugin-name> 换为 audit-context-building 所在插件名（与市场列表一致）。
本地开发
在仓库父目录下添加本地市场路径，例如仓库在 ~/projects/skills 时：
cd /path/to/parent
/plugins marketplace add ./skills
官方 Skill 目录：
https://github.com/trailofbits/skills/tree/main/plugins/audit-context-building/skills/audit-context-building
典型用法¶
- 在 Claude Code 或兼容环境中加载
trailofbits/skills市场并启用audit-context-building插件。 - 对陌生代码库启动全库上下文构建：
/audit-context-building:audit-context <path>
将 <path> 换为目标代码路径。等待完成后查看 audit-context/DOSSIER.md 与 audit-context/functions/ 下各函数文件。
3. 若只需深化某一个函数，派发 audit-context-building:function-analyzer，读其落盘 prose 与返回的紧凑记录。
4. 从 dossier 与记录中整理 nothing found 假设与 open questions，再进入漏洞狩猎或其它 Trail of Bits 审计类 Skill。
适用场景与注意¶
适合谁
- 安全工程师、审计人员在陌生项目上做审计、威胁建模或架构评审；
- 团队希望把 Trail of Bits「先建上下文、再狩猎」的方法论嵌入 Agent 工作流。
限制与注意
- 本 Skill 不负责漏洞命名与严重度评估；与
c-review、differential-review等狩猎/评审类插件应分阶段使用。 - 大代码库分析依赖子 agent 与磁盘产物，主会话应依赖返回的索引与记录，避免把全文 prose 塞回上下文。
- 扩展格式或评估记录可信度时，应阅读仓库内
ANALYSIS_FORMAT.md与示例文档。
结尾¶
audit-context-building 把「函数假设、保证与依赖」系统化落盘，让后续漏洞狩猎站在同一张系统图上。官方地址：
https://github.com/trailofbits/skills/tree/main/plugins/audit-context-building/skills/audit-context-building
