AI 技能AI 插件应用安全网络安全AI 评测【免费下载链接】skillsTrail of Bits Claude Code skills for security research, vulnerability detection, and audit workflows项目地址https://gitcode.com/gh_mirrors/skills8/skills点击查看免费下载导读本文聚焦 Trail of Bits 出品的dimensional-analysis插件的核心执行者之一 ——dimension-annotator维度标注 Agent它负责在源码锚点处为数值变量、结构体字段、常量、函数参数与返回值添加基于 Reserve Protocol 注释格式的维度标注如D18{tok}、D27{UoA/tok}。读完本文你将掌握该 Agent 的输入约定、逐文件覆盖率要求、只加注释不改代码的硬性边界、六类标注格式、五级标注优先级、歧义处理与报告输出规范并理解它在整个扫描 → 发现 → 标注 → 传播 → 验证流水线中的位置。一、定位dimension-annotator 在维度分析流水线中的角色dimensional-analysis插件面向所有执行混合单位、混合精度或混合缩放因子数值运算的代码库提供一套完整的自动分析流水线。根据插件 README.md流水线包含四个阶段Discover发现代码库的维度词汇表token、share、price 等Annotate用D18{tok}、D27{UoA/tok}这类维度注释为代码打标注Propagate沿算术与调用路径传播维度Validate校验维度一致性并检测 bug。整个编排逻辑位于 SKILL.md它将该技能定位为纯工作流控制器扫描交给arithmetic-scanner词汇发现交给dimension-discoverer锚点标注交给dimension-annotator传播交给dimension-propagatorbug 检测交给dimension-validator且明令主技能上下文不得越俎代庖替任一子 Agent 做专属推理。dimension-annotator 正是 Step 2锚点标注的执行者。它的职责是在常量、标准接口边界、状态变量等锚点位置添加维度注释为后续的传播Step 3与验证Step 4提供事实起点。其 Agent 定义文件即 dimension-annotator.md。二、Agent 输入约定五个信息源dimension-annotator 通过 prompt 接收五类输入见 dimension-annotator.md输入说明使用方式DIMENSIONAL_UNITS.md路径项目的维度词汇表基础单位、派生单位、精度前缀必须首先读取标注时只能使用该词汇表中的单位DIMENSIONAL_SCOPE.json路径大仓库的源清单可选但推荐用于核实分配文件是否在范围内并回报确定性状态分配的文件路径列表待标注文件按给定顺序排列顺序处理逐文件推进文件类别与匹配模式每个文件所含维度算术的类型背景指导标注策略math-library / oracle-integration / conversion / core-logic / peripheral先前批次的标注接口可选早前批次产生的接口标注用于跨调用边界传播维度DIMENSIONAL_UNITS.md由dimension-discoverer在 Step 1 生成并持久化到项目根目录固定包含Base Units、Derived Units、Precision Prefixes三个章节DIMENSIONAL_SCOPE.json则由arithmetic-scanner写入是 Step 2-4 的范围事实来源详见 SKILL.md 与 dimension-discoverer.md。三、覆盖率硬性要求逐文件回报禁止静默跳过Agent 定义中明确要求处理每一个分配的文件并返回每文件状态不允许无声跳过dimension-annotator.md。合法的每文件状态有三种ANNOTATED—— 至少添加或确认了一个锚点标注REVIEWED_NO_ANCHOR_CHANGES—— 已审查锚点无需改动BLOCKED—— 无法处理必须附带原因。这与 SKILL.md 的编排要求一致Step 2 结束后每个 in-scope 文件都必须落入恰好一个非PENDING状态BLOCKED文件要持久化step2_reason与step2_retry_count且只允许用聚焦 prompt 重试一次只要磁盘上的清单仍有PENDING就不允许进入 Step 3SKILL.md。四、CRITICAL 约束只加注释绝不改代码这是 dimension-annotator 最核心的行为边界dimension-annotator.md与 dimension-propagator 的约束完全一致见 dimension-propagator.md允许✅变量声明后添加// {tok}行内注释添加文档注释维度Solidity 用/// param amount {tok}、Rust 用/// amount: {tok}、Python 用# amount: {tok}在算术表达式上方添加// D27{UoA/tok} ...维度等式注释。禁止❌永不改动算术表达式如a * b / c改成a / c * b永不增删缩放因子* 1e18、/ 1e27永不修复 bug即使显而易见永不修改函数逻辑、控制流或变量赋值。若标注过程中发现疑似 bug保持代码原样最多以注释记录维度不一致之处修复留给验证阶段。Agent 的定义原则是你的工作是记录代码实际做了什么而不是它应该做什么。这一约束的意义在于标注必须零副作用保证dimension-validator在 Step 4 检测到的差异是真实的代码行为而非标注 Agent 引入的污染。五、标注格式六类锚点与完整示例标注格式源自 Reserve Protocol 的 Solidity 惯例注释语法按目标语言适配dimension-annotator.md。1. 状态变量行内注释// Before uint256 public totalAssets; uint256 public lastPoke; uint256 public tvlFee; // After uint256 public totalAssets; // {tok} uint256 public lastPoke; // {s} uint256 public tvlFee; // D18{1/s} demurrage fee on AUM2. 结构体字段逐字段标注struct RebalanceLimits { uint256 low; // D18{BU/share} (0, 1e27] uint256 spot; // D18{BU/share} (0, 1e27] uint256 high; // D18{BU/share} (0, 1e27] }3. 常量精度常量与其他常量uint256 constant D18 1e18; // D18 uint256 constant D27 1e27; // D27 uint256 constant MAX_FEE 0.1e18; // D18{1} 10%4. 函数参数NatSpecparam/// notice Deposits assets into the vault /// param assets {tok} The amount to deposit /// param receiver The address to receive shares /// return shares {share} The shares minted5. 函数返回值NatSpecreturn/// return price D27{UoA/tok} The current price6. 行内算术维度等式在复杂计算上方添加维度方程给出结果 操作数组合的完整推导// D27{buyTok/sellTok} D27{UoA/sellTok} * D27 / D27{UoA/buyTok} uint256 startPrice Math.mulDiv(sellPrices.high, D27, buyPrices.low);多步计算示例// {share} {tok} * D18{share/tok} / D18 uint256 shares Math.mulDiv(assets, totalSupply(), totalAssets());这些格式在插件的参考资料 annotate.md 中有更完整的展开包括变量声明采用行内或上方注释的取舍、函数签名 NatSpec 与行内注释两种写法以及 ERC-4626 Vault、AMM/DEX、Lending Protocol 三个完整标注范例。所有维度的代数规则乘法维度相乘、除法维度相除、加减要求同维度、精度相加/相减详见 dimension-algebra.md其正式语法为annotation : scale? { dimension } scale : D number dimension : base_dim | derived_dim | 1 derived_dim: dimension / dimension | dimension * dimension六、标注目标优先级从最高置信度到选择性标注dimension-annotator 按五级优先级决定先标注什么dimension-annotator.md优先级目标说明P1 常量D18、D27等精度常量语义已知的 max/min 边界费用常量最高置信度几乎无歧义P2 标准接口边界ERC20balanceOf、totalSupply、transfer、approve、ERC4626totalAssets、convertToShares、deposit、withdraw、SPL TokenRust/Anchor 的amount、mint_to、transfer、已知预言机接口Chainlink、Pyth、Switchboard 等接口语义由标准约定决定P3 状态变量语义名称清晰的变量从已标注源赋值的变量有意义的结构体字段P4 函数参数名称带有类型暗示的参数与已标注变量有数据流关系的参数public/external 函数边界P5 局部变量选择性仅标注关键中间值聚焦复杂算术涉及的值跳过明显场景如循环计数器低置信度宁缺毋滥各接口的维度语义在 common-dimensions.md 中有完整清单ERC20 的totalSupply()/balanceOf()为{tok}ERC4626 的totalAssets()为{tok}、convertToShares(assets)是{tok} → {share}Chainlink 的answer通常为D8{UoA/tok}。七、标注规则DO 与 DONT 清单应当标注DO每个 public/external 状态变量每个结构体字段每个精度常量关键函数参数与返回值复杂算术运算。不应标注DONT循环索引uint256 i布尔变量地址变量特殊情况除外返回值显而易见的 getter 函数非关键的内部辅助变量。保留既有标注绝不覆盖已有的维度标注仅当明显错误时才更新标注在既有 NatSpec 上追加而非替换。命名线索表来自 common-dimensions.md可作为标注判定的辅助*Balance/*Amount→{tok}*Shares→{share}*Price→{UoA/tok}*Rate→{1}或{1/s}*Time/*Timestamp→{s}*Ratio→{1}*Value→{UoA}。八、编辑流程逐文件、逐标注、精确匹配对每个文件/合约dimension-annotator 遵循固定流程dimension-annotator.md读取源码Read 工具按优先级识别标注目标使用 Edit 工具执行编辑一次只编辑一个标注old_string使用精确字符串匹配包含足够上下文保证匹配唯一跟踪变更用于报告记录行号与新注释设置每文件状态ANNOTATED/REVIEWED_NO_ANCHOR_CHANGES/BLOCKED。完整标注会话示例Contract: Vault.sol Constants Line 15: uint256 constant PRECISION 1e18; → Edit: uint256 constant PRECISION 1e18; // D18 State Variables Line 25: uint256 public totalDeposited; → Edit: uint256 public totalDeposited; // {tok} Line 26: uint256 public totalShares; → Edit: uint256 public totalShares; // {share} Function Parameters Line 45: /// param amount The deposit amount → Edit: /// param amount {tok} The deposit amount Inline Comments Line 67: uint256 shares amount * totalShares / totalDeposited; → Add above: // {share} {tok} * {share} / {tok} Total annotations: 6九、歧义处理UNCERTAIN 标记与人肉复核交接当维度不确定时按三步排查dimension-annotator.md检查上下文—— 什么数据流入/流出该变量检查用法—— 它如何参与算术检查命名—— 名称中是否有线索。仍无法确定时使用UNCERTAIN标记uint256 public mysteryValue; // UNCERTAIN: {???} needs human review这些标记会在验证阶段被标记为需要人工复核。该机制与传播阶段的置信度体系衔接dimension-propagator 将推理标注分为CERTAIN由两个确定操作数经代数规则直接算出、INFERRED至少一个操作数来自推断与UNCERTAIN存在多种解释或依赖命名启发式且置信度保守传播——任何UNCERTAIN输入都会产生UNCERTAIN输出dimension-propagator.md。十、输出报告结构化回传验证所需的全部信息完成一个合约的标注后Agent 需回报结构化报告dimension-annotator.md## Annotation Report: ContractName.sol ### State Variables (5 annotations) - Line 42: uint256 public totalAssets; // {tok} - Line 43: uint256 public totalShares; // {share} - Line 44: uint256 public pricePerShare; // D18{tok/share} ### Function Parameters (8 annotations) - deposit(uint256 assets) → /// param assets {tok} - withdraw(uint256 shares) → /// param shares {share} ### Constants (2 annotations) - Line 15: uint256 constant PRECISION 1e18; // D18 ... ### Uncertain Dimensions 1. Line 89: mysteryValue - unclear purpose 2. Line 112: ratio - could be {tok/share} or {share/tok} ### Ready for Review ### File Status - Status: ANNOTATED | REVIEWED_NO_ANCHOR_CHANGES | BLOCKED - Reason: One-line justification这份报告一方面让主技能上下文能把结果持久化进DIMENSIONAL_SCOPE.json另一方面为 Step 3 的 propagator 提供锚点标注摘要为 Step 4 的 validator 提供跨文件接口维度信息。十一、流水线衔接从锚点标注到 bug 检测锚点标注不是终点而是整个分析链条的燃料**Step 2本 Agent**产出锚点标注与 per-file 状态写入清单Step 3dimension-propagator 从锚点出发沿算术表达式乘法维度相乘、除法相除、加减须同维度、精度加减、函数调用实参→形参、返回值→接收变量、赋值与控制流多路径返回须同维度传播维度并沿途报告 mismatchdimension-propagator.mdStep 4dimension-validator 综合校验确认或驳斥 Step 3 的 mismatch并独立发现新 bug产出DIM-XXX编号发现SKILL.md。因此标注的质量直接决定下游传播与验证的覆盖面锚点标注得越完整、越准确传播阶段的推理起点就越可靠最终检测到的维度 bug 就越全面。而 dimension-annotator 的只注释、不改码约束则保证了这一过程对代码库零侵入——它是一套纯文档化的分析管线。结语dimension-annotator 是dimensional-analysis插件中最具实操价值的一环它以严格的注释格式、明确的优先级与硬性的零代码改动约束为混合单位/精度算术代码库建立了可机器消费的维度事实层。配合 dimension-algebra.md 的代数规则、common-dimensions.md 的词汇表和 annotate.md 的完整范例任何 DeFi 协议Solidity、Rust/Anchor、CosmWasm 等或进行混合精度算术的普通代码库都可以把单位混乱导致的算术 bug从潜在炸弹变成显式标注。该插件由 Trail of Bits 出品适用于安全研究、漏洞检测与审计工作流。赞分享AI 技能AI 插件应用安全网络安全AI 评测【免费下载链接】skillsTrail of Bits Claude Code skills for security research, vulnerability detection, and audit workflows项目地址https://gitcode.com/gh_mirrors/skills8/skills点击查看免费下载相关推荐Dimensional Analysis 插件实战用维度标注自动化发现 DeFi 代码库的单位错误Dimensional Analysis 插件实战用维度标注自动化发现 DeFi 代码库的单位错误 导读 Dimensional Analysis 插件 htAI 技能AI 插件应用安全网络安全AI 评测Valibot 源码注释规范JSDoc 与行内注释的完整编写指南Valibot 源码注释规范JSDoc 与行内注释的完整编写指南 Valibot 作为一套模块化、类型安全的 schema 校验库其 library/src后端前端DBeaver插件API文档生成终极指南Javadoc标签与注释规范完整教程DBeaver插件API文档生成终极指南Javadoc标签与注释规范完整教程 DBeaver作为一款功能强大的通用数据库管理工具其插件API文档生成对于开发数据库客户端桌面应用数据库上一篇Fast-GitHub 加速插件把 GitHub 克隆与下载流量转发到加速节点下一篇群晖 Audio Station 歌词插件安装教程3 分钟让 QQ 音乐双语歌词跑起来创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考