维度分析
- 作者仓库星标 0
- 作者更新于 2026年8月24日 23:09
- 作者仓库 skills
- 领域
- 通用
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @trailofbits · 未声明许可证
- 上下文用量评级
- 较高消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
{
"mode": "full-auto",
"project_root": "<path>",
"vocabulary": {
"base_units": ["..."],
"derived_units": ["..."],
"precision_prefixes": ["..."]
},
"annotations": {
"total_added": 0,
"by_file": {}
},
"findings": {
"critical": 0,
"high": 0,
"medium": 0,
"details": []
},
"uncertainties_resolved": 0,
"coverage": {
"in_scope_files": 0,
"anchor_reviewed_files": "0/0",
"propagation_reviewed_files": "0/0",
"validation_reviewed_files": "0/0",
"annotated_functions": "0/0",
"annotated_variables": "0/0",
"unprocessed_files": [
{
"path": "/path/to/repo/contracts/LegacyMath.sol",
"blocked_step": "step3",
"reason": "Parser could not process generated source",
"retry_count": 1
}
]
}
}
如果缓存的工件无法重用,请将存储库扫描委托给`arithmetic-scanner`,将词汇发现委托给`dimension-discoverer`。不要直接在主要技能上下文中进行特定于步骤的分析。检查项目根目录中是否已存在`DIMENSIONAL_UNITS.md`和`DIMENSIONAL_SCOPE.json`。如果两者都存在,读取它们并确认: `DIMENSIONAL_SCOPE.json.project_root` 匹配当前的仓库根目录
主要技能上下文本身不得添加注释。使用 `Task` 工具为所有锚点注释工作生成 `dimension-annotator` 代理。有关完整示例和注释格式详细信息,请参阅`{baseDir}/references/annotate.md`。阅读`DIMENSIONAL_SCOPE.json`并从`in_scope_files`构建批次。每个范围内的文件(包括中优先级和低优先级文件)都必须收到第 2 步结果。
主要技能上下文本身不得执行传播推理。使用 `Task` 工具生成 `dimension-propagator` 代理,通过算术、函数调用和赋值来扩展注释。有关代数的详细信息,请参阅`{baseDir}/references/dimension-algebra.md`。阅读`DIMENSIONAL_SCOPE.json`并从`in_scope_files`构建传播批次。每个范围内的文件都必须收到第 3 步的结果。
主要技能上下文本身不得执行错误检测。使用`Task`工具生成`dimension-validator`代理来检测带注释的代码中的维度错误。例如,危险信号、合理化检查和标准词汇,请参阅`{baseDir}/references/bug-patterns.md`、`{baseDir}/references/common-dimensions.md`和`{baseDir}/references/dimension-algebra.md`。不要检测任何其他步骤中的错误。
# Dimensional Analysis Skill
This skill orchestrates a dimensional-analysis pipeline for codebases that perform numeric computations with mixed units, precisions, or scaling factors. The main skill context is a workflow controller only: it delegates scanning, vocabulary discovery, annotation, propagation, and validation to specialized subagents, then manages batching, persistence, retries, coverage gates, and final reporting.
## When to Use
- Annotating a codebase with unit/dimension comments (e.g., `D18{tok}`, `D27{UoA/tok}`)
- Performing dimensional analysis on DeFi protocols, financial code, or scientific computations
- Hunting for arithmetic bugs caused by unit mismatches, missing scaling, or precision loss
- Auditing codebases with mixed decimal precisions or fixed-point arithmetic
## When NOT to Use
- Codebases with no numeric arithmetic or unit conversions — there is nothing to annotate
- Pure integer counting logic (loop indices, array lengths) with no physical or financial dimensions
- When you only need a quick spot-check of a single formula — read the code directly instead of running the full pipeline
## Execution Mode
This skill runs in one mode only: `full-auto`.
This is a workflow-based skill that delegates step-specific work to specialized agents via the `Task` tool. You orchestrate the overall process, manage coverage and state persistence, and ensure that every in-scope file is processed through each step of the pipeline.
- Always run the full pipeline in this order: Step 1 -> Step 2 -> Step 3 -> Step 4.
- The main skill context must not perform repository-wide dimensional analysis, annotation, propagation, or bug validation itself when a dedicated subagent exists for that step.
- The main skill context may inspect artifacts, manifests, and subagent outputs only as needed to route work, build prompts, persist state, and determine completion.
- Any mode argument provided by the caller is ignored.
- Report all results at the end in a single summary.
When you start a step, report it:
```text
Starting Step: Step {n}
```
## Scope and Coverage Guarantees
This skill must audit **all in-scope arithmetic files**, including large repositories.
- In-scope files are defined by Step 1 scanner output (`files` array), across **all** priority tiers (CRITICAL, HIGH, MEDIUM, LOW).
- If Step 1 narrows inputs for vocabulary discovery (for example, CRITICAL/HIGH only), that narrowing applies to discovery only. It **never** reduces annotation or validation scope.
- `arithmetic-scanner` persists the in-scope file manifest to `DIMENSIONAL_SCOPE.json` in the project root, and that manifest is the source of truth for Steps 2-4.
- A file is considered fully covered only when all three statuses are present:
- `step2`: anchor annotation completed (or explicit no-anchor result)
- `step3`: propagation completed (or explicit no-propagation result)
- `step4`: validation completed
- `dimension-discoverer` persists the discovered dimensional vocabulary to `DIMENSIONAL_UNITS.md` in the project root for reuse by later steps and future runs.
- When a file ends in a terminal `BLOCKED` state, persist the blocking reason and retry count in `DIMENSIONAL_SCOPE.json` and reflect the same file in `coverage.unprocessed_files`.
- Do not finish while any in-scope file remains unprocessed in any step.
## Delegation Contract
- `arithmetic-scanner` owns repository scanning, arithmetic-file prioritization, and writing `DIMENSIONAL_SCOPE.json`.
- `dimension-discoverer` owns dimensional vocabulary discovery, unit inference, and writing `DIMENSIONAL_UNITS.md`.
- `dimension-annotator` owns annotation format decisions, anchor-point edits, and comment-writing behavior.
- `dimension-propagator` owns propagation logic, inferred annotations, and mismatch reporting during tracing.
- `dimension-validator` owns bug detection, red-flag evaluation, rationalization rejection, and confirmation or refutation of propagated mismatches.
- The main skill context must not substitute its own dimensional reasoning for skipped or unlaunched subagents. If a step requires specialized reasoning, launch the corresponding subagent.
- Use reference files as subagent support material. Pass them to the relevant step in prompts instead of treating them as instructions for the main skill context.
## Workflow
Follow these sections in order. Do not advance until the current step satisfies its completion gate.
### Shared Orchestration Rules
- `DIMENSIONAL_SCOPE.json` and `DIMENSIONAL_UNITS.md` live in the project root.
- The main skill context verifies Step 1 artifacts but does not write either Step 1 artifact itself.
- `DIMENSIONAL_SCOPE.json.in_scope_files` is the source of truth for Steps 2-4. Never derive later scope from discovery-only inputs.
- When a later step reaches terminal `BLOCKED`, persist the matching `step*_reason` and `step*_retry_count` fields on the file entry in `DIMENSIONAL_SCOPE.json`.
- `coverage.unprocessed_files` must be derived from terminal `BLOCKED` entries in `DIMENSIONAL_SCOPE.json` using `{ "path": "...", "blocked_step": "step2|step3|step4", "reason": "...", "retry_count": 1 }`.
- A step may retry a `BLOCKED` file once with a focused prompt. If it is still `BLOCKED`, keep the documented reason and continue. Do not finalize while any file remains `PENDING`.
### Step 1: Vocabulary and Scope Discovery
If cached artifacts cannot be reused, delegate repository scanning to `arithmetic-scanner` and vocabulary discovery to `dimension-discoverer`. Do not do that step-specific analysis directly in the main skill context.
1. Check whether `DIMENSIONAL_UNITS.md` and `DIMENSIONAL_SCOPE.json` already exist in the project root.
2. If both exist, read them and confirm:
- `DIMENSIONAL_SCOPE.json.project_root` matches the current repo root
- `DIMENSIONAL_SCOPE.json` contains `in_scope_files`, `discoverer_focus_files`, `recommended_discovery_order`, and per-file `step2`, `step3`, `step4` fields
- `DIMENSIONAL_UNITS.md` is a usable dimensional vocabulary for this repo
3. If either artifact is stale, malformed, missing required structure, or clearly for another repo, discard reuse and rerun the rest of Step 1.
4. If both artifacts are valid, reuse them directly. If `in_scope_files` is empty, skip Steps 2-4 and produce final output with zero findings.
5. Otherwise use the `Task` tool to spawn the `arithmetic-scanner` agent. Its prompt must include:
- project root path
- absolute output path for `DIMENSIONAL_SCOPE.json`
- instruction to write the Step 1 scope manifest to disk and return the same scope data in its report
6. The scanner owns Step 1 scope persistence. It must:
- identify dimensional-arithmetic files and prioritize them as usual
- write `DIMENSIONAL_SCOPE.json` with `project_root`, `in_scope_files`, `discoverer_focus_files`, and `recommended_discovery_order`
- initialize every in-scope file with `step2: "PENDING"`, `step3: "PENDING"`, and `step4: "PENDING"`
- still write an empty manifest when no arithmetic files are found
- still narrow `discoverer_focus_files` to CRITICAL/HIGH when more than 50 arithmetic files are found, while keeping all priorities in `in_scope_files`
7. After the scanner completes, read `DIMENSIONAL_SCOPE.json` from disk and confirm it exists and contains the required Step 1 fields before continuing.
8. Use the `Task` tool to spawn the `dimension-discoverer` agent. Its prompt must include:
- project root path
- absolute path to `DIMENSIONAL_SCOPE.json`
- absolute output path for `DIMENSIONAL_UNITS.md`
- prioritized `discoverer_focus_files` with each file's path, priority, score, and category
- `recommended_discovery_order`
9. The discoverer owns Step 1 vocabulary persistence. It must read `DIMENSIONAL_SCOPE.json` as the Step 1 source of truth and write `DIMENSIONAL_UNITS.md` with `Base Units`, `Derived Units`, and `Precision Prefixes` sections. If `in_scope_files` is empty, it must still write the same headings with empty sections.
10. Step 1 is complete only when both artifacts exist on disk, pass the reuse checks above, and correctly represent the zero-file case. If `in_scope_files` is empty after the discoverer writes `DIMENSIONAL_UNITS.md`, skip Steps 2-4 and produce final output with zero findings.
### Step 2: Anchor Annotation
The main skill context must not add annotations itself. Use the `Task` tool to spawn `dimension-annotator` agents for all anchor-point annotation work. For full examples and annotation format details, see `[{baseDir}/references/annotate.md]({baseDir}/references/annotate.md)`.
- Read `DIMENSIONAL_SCOPE.json` and build batches from `in_scope_files`. Every in-scope file, including MEDIUM and LOW priority files, must receive a Step 2 outcome.
- Batch files instead of spawning one agent per file:
- `<= 10` files: one batch
- `11-30` files: one batch per category
- `> 30` files: one batch per category, splitting categories larger than 10 files into sub-batches of about 8 files
- Launch categories in Step 1 recommended discovery order: math libraries, then oracles, then core logic, then peripheral. Batches inside the same category may run in parallel.
- Before launching annotators, set `step2 = "PENDING"` for every in-scope file and persist the updated `DIMENSIONAL_SCOPE.json`.
- Each annotator prompt must include:
- absolute path to `DIMENSIONAL_UNITS.md`
- absolute path to `DIMENSIONAL_SCOPE.json`
- assigned file paths in order
- each file's category and matched patterns from scanner output
- summary of previously annotated interfaces or types from earlier batches, when applicable
- required per-file status output: `ANNOTATED`, `REVIEWED_NO_ANCHOR_CHANGES`, or `BLOCKED` plus a one-line justification
- After each batch, immediately persist each assigned file to exactly one Step 2 status:
- `ANNOTATED`
- `REVIEWED_NO_ANCHOR_CHANGES`
- `BLOCKED`
- If a file is `BLOCKED`, also persist `step2_reason` and `step2_retry_count`. Retry each `BLOCKED` file once with a focused prompt.
- Do not continue to Step 3 while any file remains `PENDING` in on-disk manifest state.
### Step 3: Dimension Propagation
The main skill context must not perform propagation reasoning itself. Use the `Task` tool to spawn `dimension-propagator` agents to extend annotations through arithmetic, function calls, and assignments. For algebra details, see `[{baseDir}/references/dimension-algebra.md]({baseDir}/references/dimension-algebra.md)`.
- Read `DIMENSIONAL_SCOPE.json` and build propagation batches from `in_scope_files`. Every in-scope file must receive a Step 3 outcome.
- Use the same batching rules and category ordering as Step 2.
- Before launching propagators, confirm every file already has a non-pending Step 2 status.
- Then set `step3 = "PENDING"` for every in-scope file and persist the updated manifest.
- Each propagator prompt must include:
- absolute path to `DIMENSIONAL_UNITS.md`
- absolute path to `DIMENSIONAL_SCOPE.json`
- assigned file paths in order
- each file's category and matched patterns
- summary of Step 2 anchor annotations for the assigned files and any upstream interfaces they depend on
- required per-file status output: `PROPAGATED`, `REVIEWED_NO_PROPAGATION_CHANGES`, or `BLOCKED` plus a one-line justification
- After each batch, immediately persist each assigned file to exactly one Step 3 status:
- `PROPAGATED`
- `REVIEWED_NO_PROPAGATION_CHANGES`
- `BLOCKED`
- If a file is `BLOCKED`, also persist `step3_reason` and `step3_retry_count`. Retry each `BLOCKED` file once with a focused prompt.
- After all propagators complete, aggregate:
- annotations added by confidence level (`CERTAIN`, `INFERRED`, `UNCERTAIN`)
- mismatches found, with severities for validator deduplication
- coverage gaps that could not be inferred
- Do not continue to Step 4 while any file remains `PENDING` in on-disk manifest state.
### Step 4: Bug Detection
The main skill context must not perform bug detection itself. Use the `Task` tool to spawn `dimension-validator` agents to detect dimensional bugs in annotated code. For examples, red flags, rationalization checks, and standard vocabulary, see `[{baseDir}/references/bug-patterns.md]({baseDir}/references/bug-patterns.md)`, `[{baseDir}/references/common-dimensions.md]({baseDir}/references/common-dimensions.md)`, and `[{baseDir}/references/dimension-algebra.md]({baseDir}/references/dimension-algebra.md)`. DO NOT DETECT BUGS IN ANY OTHER STEP.
- Validate every file in `DIMENSIONAL_SCOPE.json.in_scope_files`.
- Use this priority order without skipping lower tiers:
1. files with CRITICAL or HIGH Step 3 mismatches
2. remaining CRITICAL and HIGH scanner-priority files
3. remaining MEDIUM and LOW files
- Before launching validators, confirm every file already has a non-pending Step 3 status.
- Then set `step4 = "PENDING"` for every in-scope file and persist the updated manifest.
- Spawn one `dimension-validator` agent per file. For large repos, run them in waves of roughly 10-30 files to keep orchestration stable.
- Each validator prompt must include:
- absolute path to `DIMENSIONAL_UNITS.md`
- absolute path to `DIMENSIONAL_SCOPE.json`
- the single file path to validate
- a summary of anchor and propagated annotations in the file
- Step 3 mismatch summaries for the file, including mismatch IDs
- cross-file function signatures or return dimensions needed for call-boundary checks
- required per-file status output: `VALIDATED` or `BLOCKED`
- After each wave, immediately persist each file to exactly one Step 4 status:
- `VALIDATED`
- `BLOCKED`
- If a file is `BLOCKED`, also persist `step4_reason` and `step4_retry_count`. Retry each `BLOCKED` file once with a focused prompt.
- Deduplicate findings:
- confirmed Step 3 mismatches keep their original IDs and severities
- refuted Step 3 mismatches are noted as false positives and excluded from final counts
- genuinely new findings receive new `DIM-XXX` IDs
- Aggregate confirmed findings, new findings, refuted findings, coverage summary, and final `coverage.unprocessed_files`.
- Step 4 is complete only when `DIMENSIONAL_SCOPE.json.in_scope_files` contains no `step4: "PENDING"` entries.
## Reference Documentation
Pass these references to the relevant subagent when a step needs them:
- `[{baseDir}/references/dimension-algebra.md]({baseDir}/references/dimension-algebra.md)` - Propagator and validator algebra rules
- `[{baseDir}/references/common-dimensions.md]({baseDir}/references/common-dimensions.md)` - Validator vocabulary reference
- `[{baseDir}/references/bug-patterns.md]({baseDir}/references/bug-patterns.md)` - Validator bug-pattern and red-flag reference
- `[{baseDir}/references/annotate.md]({baseDir}/references/annotate.md)` - Annotator format and example reference
## Final Output
At the end of the analysis, provide a structured summary unless some other output format has been specified:
```json
{
"mode": "full-auto",
"project_root": "<path>",
"vocabulary": {
"base_units": ["..."],
"derived_units": ["..."],
"precision_prefixes": ["..."]
},
"annotations": {
"total_added": 0,
"by_file": {}
},
"findings": {
"critical": 0,
"high": 0,
"medium": 0,
"details": []
},
"uncertainties_resolved": 0,
"coverage": {
"in_scope_files": 0,
"anchor_reviewed_files": "0/0",
"propagation_reviewed_files": "0/0",
"validation_reviewed_files": "0/0",
"annotated_functions": "0/0",
"annotated_variables": "0/0",
"unprocessed_files": [
{
"path": "/path/to/repo/contracts/LegacyMath.sol",
"blocked_step": "step3",
"reason": "Parser could not process generated source",
"retry_count": 1
}
]
}
}
```
## Completion Checklist
You are NOT done until all of these are true:
### File Coverage Gates
- [ ] `DIMENSIONAL_UNITS.md` exists in the project root
- [ ] `DIMENSIONAL_SCOPE.json` exists in the project root and is the source of truth for downstream coverage
- [ ] Every in-scope arithmetic file discovered in Step 1 appears in `DIMENSIONAL_SCOPE.json.in_scope_files`
- [ ] Every in-scope file has a non-`PENDING` Step 2 status (`ANNOTATED`, `REVIEWED_NO_ANCHOR_CHANGES`, or `BLOCKED`)
- [ ] Every in-scope file has a non-`PENDING` Step 3 status (`PROPAGATED`, `REVIEWED_NO_PROPAGATION_CHANGES`, or `BLOCKED`)
- [ ] Every in-scope file has a non-`PENDING` Step 4 status (`VALIDATED` or `BLOCKED`)
- [ ] No in-scope file remains `PENDING` in any step
- [ ] Any `BLOCKED` file has a documented reason in the final output
- [ ] `coverage.unprocessed_files` exactly matches the final set of terminal `BLOCKED` files after retries, using `path`, `blocked_step`, `reason`, and `retry_count`
### Summary Report
- [ ] Final summary JSON/report provided
- [ ] Final coverage counters match `DIMENSIONAL_SCOPE.json`
- [ ] List of modified files provided when edits occurred
- [ ] Any dimensional mismatches or bugs found are summarized
- [ ] Any remaining blocked or unprocessed files are called out with reasons
**If `DIMENSIONAL_SCOPE.json` and the final report disagree, reconcile the report or continue processing until they match.**
**Do not claim completion from agent intent alone; completion is determined by manifest coverage and final reported statuses.**
按说明文件中的顺序排列。
何时使用
何时不使用
执行模式
范围和覆盖范围保证
委托合同
文件/命令 -> D18{tok} · D27{UoA/tok} · full-auto · Task · files · arithmetic-scanner · DIMENSIONAL_SCOPE.json · step2
内容校验值 -> 58d6e3ade7bd
当前原文的自动摘译,尚未人工审校。
何时使用
使用单位/维度注释来注释代码库(例如,
D18{tok}、D27{UoA/tok}) 对 DeFi 协议、金融代码或科学计算执行维度分析 寻找因单位不匹配、缺少缩放或精度损失引起的算术错误 审计具有混合十进制精度或定点算术的代码库何时不使用
没有数值算术或单位转换的代码库 - 没有任何可注释的 纯整数计数逻辑(循环索引、数组长度),没有物理或财务维度 当您只需要快速抽查单个公式时 - 直接读取代码,而不是运行完整的管道
执行模式
该技能仅在一种模式下运行:
full-auto。这是一项基于工作流程的技能,通过Task工具将特定步骤的工作委托给专业代理。您可以编排整个流程,管理覆盖范围和状态持久性,并确保通过管道的每个步骤处理每个范围内的文件。始终按以下顺序运行完整管道:步骤 1 -> 步骤 2 -> 步骤 3 -> 步骤 4。当该步骤存在专用子代理时,主要技能上下文不得执行存储库范围的维度分析、注释、传播或错误验证本身。范围和覆盖范围保证
此技能必须审核所有范围内的算术文件,包括大型存储库。范围内文件由步骤 1 扫描仪输出(
files数组)定义,涵盖所有优先级(CRITICAL、HIGH、MEDIUM、LOW)。如果步骤 1 缩小了词汇发现的输入范围(例如,仅限 CRITICAL/HIGH),则该缩小范围仅适用于发现。它永远不会减少注释或验证范围。arithmetic-scanner将范围内文件清单保留到项目根目录中的DIMENSIONAL_SCOPE.json,并且该清单是步骤 2-4 的真实来源。委托合同
arithmetic-scanner拥有存储库扫描、算术文件优先级和写入DIMENSIONAL_SCOPE.json。dimension-discoverer拥有维度词汇发现、单位推理、写作DIMENSIONAL_UNITS.md。dimension-annotator拥有注释格式决策、锚点编辑和评论编写行为。dimension-propagator拥有传播逻辑、推断注释和跟踪期间的不匹配报告。