用途
spec-to-code-compliance 是一个面向区块链审计的规格到代码合规检查技能。它的目标是判定代码库是否在逻辑、不变量、流程、假设、数学和安全保证等方面，严格实现了文档所陈述的内容。
适用场景包括：验证代码是否精确实现文档规定；将智能合约与白皮书或设计文档对照审计；查找预期行为与实际实现之间的差距；识别未文档化的代码行为或未实现的规格声明；对区块链协议实现执行合规检查。
典型触发条件：用户同时提供规格文档和代码库；提出“这段代码是否符合规格”“实现中缺少了什么”之类的问题；需要规格与代码对齐分析的审计任务；将协议实现与白皮书进行核对。
不适用场景：没有对应规格文档的代码库；通用代码审查或漏洞挖掘（应改用 audit-context-building）；撰写或改进文档（本技能只做合规验证）；没有正式规格的非区块链项目。
主要能力
该技能以“规格到代码合规检查器”的角色运行，要求工作具备确定性、以证据为基础、可追溯、不产生幻觉且详尽。其全局规则包括：绝不推断未说明的行为；始终引用文档（章节/标题/引文）与代码（文件+行号）的确切证据；为映射提供 0–1 的置信度评分；对歧义进行分类而非猜测；严格区分抽取、对齐、分类与报告四个环节；不依赖对已知协议的既有知识，只使用所提供的材料；保持字面、苛刻、详尽。
技能还列出若干“不可跳过的合理化”反模式，例如“规格已经足够清楚”“代码显然匹配”“记为部分匹配即可”“未文档化行为没关系”“低置信度可以接受”“我来推断规格的意思”等，并给出对应的纠正要求。
使用方式
技能定义了七个阶段的工作流：
- 阶段 0 文档发现：识别所有代表文档的内容，即使未命名为“spec”，例如 whitepaper.pdf、Protocol.md、design_notes、Flow.pdf、README.md、启动会议记录、Notion 导出等，并依据架构描述、不变量、公式、变量含义、信任模型、工作流顺序、逻辑表格、图表等语义线索，抽取为统一的规格语料。
- 阶段 1 通用格式归一化：归一化 PDF、Markdown、DOCX、HTML、TXT、Notion 导出、会议记录等任意输入格式，保留标题层级、项目符号列表、公式、表格（转为纯文本）、代码片段、不变量定义，去除版式噪声、样式残留与水印，输出干净的规范 spec_corpus。
- 阶段 2 规格意图 IR：将全部预期行为抽取为 Spec-IR，每项包含 spec_excerpt、source_section、semantic_type、归一化表示与置信度评分。抽取内容包括协议目的、参与者/角色/信任边界、变量定义与预期关系、全部前置/后置条件、显式与隐式不变量、数学公式（规范符号形式）、预期流程与状态机转换、经济假设、顺序与时间约束、错误条件与预期回滚逻辑、安全要求（must/never/always）、边界情况行为。
- 阶段 3 代码行为 IR：对整个代码库进行结构化、确定性、逐行与逐块的语义分析。对每一行和每一块抽取文件与精确行号、局部变量更新、状态读写、条件分支与替代路径、不可达分支、回滚条件与自定义错误、外部调用（call、delegatecall、staticcall、create2）、事件发出、数学运算与舍入行为、隐式假设、块级前置/后置条件、局部强制的不变量、状态转换、副作用、对先前状态的依赖。对每个函数抽取签名与可见性、所应用的修饰器及其逻辑、基于实际行为的目的、输入/输出语义、读写集合、完整控制流结构、成功与回滚路径、内部/外部调用图、跨函数交互。同时捕获存储布局、初始化逻辑、授权图（角色到权限）、可升级机制（如存在）与隐藏假设，输出可完整追溯的 Code-IR。
- 阶段 4 对齐 IR：对 Spec-IR 中的每一项，在 Code-IR 中定位相关行为并生成对齐记录，包含 spec_excerpt、code_excerpt（含文件与行号）、match_type（full_match、partial_match、mismatch、missing_in_code、code_stronger_than_spec、code_weaker_than_spec）、推理轨迹、置信度评分（0–1）、歧义评级与证据链接。显式检查不变量与强制措施、公式与数学实现、流程与实际转换、参与者预期与实际权限映射、顺序约束与实际逻辑、回滚预期与实际检查、信任假设与实际外部调用行为。同时检测未文档化的代码行为、未实现的规格声明、规格内部矛盾、代码内部矛盾、多个规格文档之间的不一致。
- 阶段 5 偏差分类：按严重程度分类每处不一致。CRITICAL 包括规格说 X 而代码做 Y、缺失不变量导致可利用、涉及资金的数学偏差、信任边界不匹配；HIGH 包括部分/错误实现、访问控制不一致、危险的未文档化行为；MEDIUM 包括有安全影响的歧义、缺失回滚检查、边界情况处理不完整；LOW 包括文档漂移、次要语义不匹配。每项发现必须包含证据链接、严重程度理由、可利用性推理与建议修复。
- 阶段 6 最终审计级报告：输出结构化合规报告，包含执行摘要、已识别文档来源、规格意图分解（Spec-IR）、代码行为摘要（Code-IR）、完整对齐矩阵（规格→代码→状态）、偏差发现（含证据与严重程度，覆盖缺失不变量、错误逻辑、数学不一致、流程/状态机不匹配、访问控制漂移、未文档化行为）、歧义热点（规格与代码）、建议修复、文档更新建议与最终风险评估。
技能还提供资源文件：IR_EXAMPLES.md（含 DEX 交换模式的完整 IR 工作流示例）、OUTPUT_REQUIREMENTS.md（IR 产出标准、质量阈值、格式规则）、COMPLETENESS_CHECKLIST.md（各阶段验证清单）。此外，spec-compliance-checker 智能体可自主执行完整的七阶段规格到代码合规工作流，产出结构化 IR 工件与最终合规报告，可直接调用，例如“使用 spec-compliance-checker 智能体依据白皮书验证此代码库”。
适用场景
适用于需要将规格文档与代码库进行严格对齐分析的区块链审计任务，尤其是智能合约与白皮书、设计文档的对照验证，以及查找实现缺口、未文档化行为、未实现声明和各类不一致。
限制
仅当任务明确匹配上述范围时使用本技能。不得将输出视为环境特定验证、测试或专家评审的替代品。若缺少必要输入、权限、安全边界或成功标准，应停止并请求澄清。技能强调反幻觉要求：规格未提及则归类为 UNDOCUMENTED；代码新增行为则归类为 UNDOCUMENTED CODE PATH；不清楚则归类为 AMBIGUOUS；每项主张必须引用原文或行号；零推测。