前言¶
接手陌生代碼庫做安全審計時，常見做法是直接掃模式、追可疑調用。上一輪若沒人把「函數假設什麼、保證什麼、依賴誰」寫清楚，後續 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
