规范-代码合规检查：让白皮书里的每一条承诺都能在代码里找到落点
- 它是什么：
spec-to-code-compliance是一个面向区块链审计场景的 AI 技能，专职回答一个问题——代码是否精确实现了文档规范所说的内容。 - 它的方法论：严格分为文档发现 → 格式规范化 → 规范意图 IR → 代码行为 IR → 对齐 IR → 分歧分类 → 审计级报告六个阶段，不允许跳步。
- 它的硬性纪律：每条结论都要引用规范原文段落与代码文件行号，必须给出 0–1 的置信度分数，不允许推断、不允许凭经验“脑补”。
- 它的产出：一份包含 16 个部分的合规报告，覆盖对齐矩阵、缺失不变量、数学不一致、流程错配、访问控制漂移与未记录行为。
- 它不适合谁：没有规范文档的代码库、只想做通用代码审查或漏洞扫描的项目，不属于它的工作范围。
1. 该技能叫什么？如何一键安装 AI 技能提升开发效率？
技能中文名：规范-代码合规检查技能Skill 技能英文名：spec-to-code-compliance 技能 ID：13560
它解决的问题非常具体：在区块链与协议类项目中，白皮书、设计文档、启动记录里写着“必须、从不、始终”这些强约束，但真正落到代码里，可能漏了一条不变量、改了公式的舍入方向、把某个角色权限放大了一点。这类“规范与实现的缝隙”往往不是传统漏洞扫描能覆盖的，因为代码本身跑得通，只是跑得和文档说的不一样。这个技能就是把这条缝隙逐条摊开在桌面上。
关于“一键安装”的思路，可以按以下三步理解（具体命令与入口以官方说明为准）：
- 准备前提：你需要一个支持 AI 技能（Skill）机制的 AI 编程助手或代理环境；同时准备好两类材料——代表规范内容的文档（如白皮书 PDF、
Protocol.md、README.md、Notion 导出、会议记录等），以及待验证的代码库。缺任何一类，技能都无从对齐。 - 执行安装：在技能市场或技能管理入口中，按英文名
spec-to-code-compliance或技能 ID13560检索并安装；若你所在环境支持本地技能目录，也可将技能文件（含resources/下的说明文档）放置到对应目录后启用。安装方式与具体命令请以官方说明为准。 - 验证是否生效：安装完成后，在会话中提交一份规范文档和一段代码，并提出“这份代码是否匹配规范？”或“实现里缺少什么？”这类问题。如果技能被正确加载，它的回答会明显遵循“先提取规范意图、再逐行分析代码、最后给出带证据的对齐结论”的结构，而不是给出一段泛泛的代码点评。
之所以强调“一键安装”，是因为这个技能把一整套审计方法论（阶段划分、证据规范、反幻觉规则、完整性清单）封装成了可直接调用的能力。你不需要自己写几千字的提示词去约束 AI“不要瞎猜”“要引用行号”，装上就能用。
2. 该技能的主要功能和特点
- 六阶段确定性流程：阶段 0 文档发现、阶段 1 格式规范化、阶段 2 规范意图 IR、阶段 3 代码行为 IR、阶段 4 对齐 IR、阶段 5 分歧分类、阶段 6 最终报告。流程强制、不可跳过。
- 文档发现的“宽口径”：它不会只认名字叫“spec”的文件。白皮书、设计笔记、流程图、启动记录、Notion 导出、带公式的表格、甚至会议纪要，只要描述了逻辑、流程、假设或激励，都会被纳入统一的规范语料库。
- 三层中间表示（IR）：把规范抽成 Spec-IR，把代码抽成 Code-IR，再生成 Alignment-IR。每一层都要求可追踪，避免“凭感觉下结论”。
- 六种匹配类型：完全匹配、部分匹配、不匹配、代码中缺失、代码强于规范、代码弱于规范。特别是“部分匹配”被明确定性为潜在漏洞，必须继续调查到结论清晰为止。
- 四级严重性分类：严重（规范说 X 代码做 Y、缺失可被利用的不变量、涉及资金的数学分歧、信任边界错配）、高、中、低，每级都要附证据链接、严重性理由、可利用性推理与修复建议。
- 显式的反幻觉规则：规范沉默就标“未记录”，代码多出行为就标“未记录代码路径”，说不清就标“模糊”。禁止推断规范含义，禁止依赖对已知协议的先验知识，只使用你提供的材料。
- 置信度门槛：每个映射都要打 0–1 的置信度；低于 0.8 的发现要么继续调查，要么归类为模糊性，不允许含糊带过。
- 和普通审查工具的差别：普通工具问“这段代码有没有 bug”，它问“这段代码有没有做到文档承诺的事”。前者面向漏洞，后者面向契约一致性，两者互补而不重叠。
3. 如何使用该技能？
第 1 步：明确触发条件。 当你手上有“规范 + 代码”这一对材料，并想确认二者是否一致时再调用。典型问法包括：“此代码是否匹配规范？”“实现中缺少什么？”“请把白皮书条款和合约逐条对齐。”
第 2 步：整理并提交材料。 把规范类文档和代码库一并提供。如果文档分散在多个文件里，直接全部给出即可，技能会在阶段 0 自行识别并汇总成语料库。
示例输入（可直接参考）：
以下是我们协议的
Protocol.md（含手续费公式、清算阈值、角色权限表）与contracts/目录下的全部 Solidity 代码。请执行规范-代码合规检查，重点核对：手续费公式的舍入方向、清算触发条件、管理员权限是否超出文档描述。
第 3 步：等待阶段化处理。 技能会先规范化文档格式（保留标题层级、公式、不变量定义，去除版式噪声），再把规范中的前置条件、后置条件、显式与隐式不变量、公式、状态机流转、错误与回滚逻辑、安全要求抽取为 Spec-IR。
第 4 步：代码行为建模。 它会以逐行、逐块的方式分析代码，记录文件与行号、局部变量更新、状态读写、条件分支与不可达分支、外部调用（call / delegatecall / staticcall / create2）、事件、数学运算与舍入行为、修饰符逻辑、读写集与调用图，形成 Code-IR。
第 5 步：对齐与分类。 对 Spec-IR 中的每一项，在 Code-IR 中寻找对应行为，生成带 spec_excerpt、code_excerpt、匹配类型、推理轨迹、置信度与模糊性评级的对齐记录；随后按严重性分级，给出可利用性推理与修复建议。
第 6 步：阅读最终报告。 报告包含 16 个部分：执行摘要、文档来源、规范意图分解、代码行为摘要、完整对齐矩阵、分歧发现、缺失不变量、不正确逻辑、数学不一致、流程/状态机不匹配、访问控制漂移、未记录行为、模糊性热点、推荐修复、文档更新建议、最终风险评估。
使用注意：请勿在没有规范文档的场景下使用它，也不要指望它替代漏洞扫描或文档撰写。它的定位是合规对齐，边界清晰。
4. 同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
|---|---|---|---|---|---|
| 规范-代码合规检查技能（spec-to-code-compliance） | 规范与实现的契约一致性审计 | 六阶段流程、三层 IR、六种匹配类型、四级严重性、16 部分报告 | 需支持技能的 AI 环境；需同时提供规范文档与代码库；以官方说明为准 | 白皮书对齐审计、协议合规检查、上线前自查 | 优势：证据可追踪、反幻觉纪律强、结论可复核；不足：强依赖规范文档质量，报告篇幅较长，需人工消化 |
| 通用代码审计助手（审计上下文构建类技能） | 漏洞发现与代码质量审查 | 模式识别、常见漏洞提示、上下文梳理 | 门槛较低，仅需代码即可 | 日常代码审查、漏洞初筛 | 优势：上手快、覆盖面广；不足：不校验“是否实现了文档承诺”，缺少规范侧证据链 |
| 静态分析工具（如 Slither、Mythril 类） | 自动化缺陷检测 | 规则匹配、符号执行、已知漏洞模式告警 | 需本地环境与依赖配置 | CI 集成、批量扫描 | 优势：可自动化、速度快；不足：无法理解白皮书语义，难以发现“逻辑与文档不符”这类问题 |
| 人工第三方审计 | 综合安全评估 | 人工阅读规范与代码、渗透式验证、出具审计报告 | 成本高、周期长 | 主网上线前正式审计 | 优势：判断力强、具备行业公信力；不足：昂贵且排期长，难以在迭代中高频使用 |
从对比可以看出，这个技能填补的是“静态工具看不懂文档、人工审计又太贵太慢”的中间地带：它可以高频执行，且结论带有可追溯的证据链接，便于交给人工审计师做二次确认。
5. 该技能的典型应用场景与实际体验情况
场景一：协议上线前的白皮书对齐审计。 技术负责人手里有一份写得很漂亮的白皮书和一套赶工出来的合约。痛点是“我们自己也说不清哪条没实现”。使用方式是把白皮书与合约目录一并提交，要求输出对齐矩阵。实际体验是：报告会把每条规范声明映射到具体函数与行号，那些“文档写了但代码没做”的条目会集中出现在缺失不变量与未实现声明两个章节，非常适合作为上线前 checklist。
场景二：智能合约开发者的自查。 开发者改完手续费公式后，不确定舍入方向是否与文档一致。用这个技能做定点核对，输出的“数学不一致”章节会直接给出公式的规范形式与代码实现形式的差异，并附带置信度。体验上是上手难度中等——需要你先把文档整理清楚，但一旦跑通，比反复读文档高效得多。
场景三：投研与尽调方的独立核验。 分析师要判断一个协议“说的和做的”是否一致。以往只能靠人工读文档加读代码，现在可以把两者交给技能做第一轮筛查，重点关注“严重”与“高”两级的发现。需要注意的是，报告中的每一条结论都附有证据，务必按证据链接回看原文，不要只看结论标题。
场景四：安全团队正式审计前的预检。 在人工审计开始前先跑一遍合规检查，把“规范与实现不一致”的问题提前清理掉，让审计师把精力集中在真正的攻击面上。实际体验是能明显减少沟通成本，因为分歧点已经被结构化列出来了。
总体体验提示：上手难度中等偏上，门槛主要在材料准备而非操作；效果高度依赖规范文档的完整度，文档越结构化（有明确的不变量、公式、权限表），输出质量越高；注意“部分匹配”不等于通过，它被明确定义为潜在漏洞，应继续追查到底。
6. 该技能能为用户带来的价值
- 把“感觉一致”变成“证据一致”：每一条结论都能回溯到规范段落与代码行号，评审会上不再靠争论。
- 显著压缩人工比对时间：逐行读代码对照白皮书是典型的高耗时低产出工作，交给流程化技能处理，人只需要复核“严重/高”级别的发现。
- 降低审计门槛：小团队没有预算做完整第三方审计时，可以先跑一轮合规检查，把明显问题修掉，再决定是否投入正式审计。
- 提前拦截高风险分歧：涉及资金的数学分歧、缺失的不变量、信任边界错配都会被归入“严重”级别，越早发现，修复成本越低。
- 沉淀可复用的合规资产：对齐矩阵与文档更新建议本身就是下一版规范的输入，长期看能让文档与代码形成正向循环。
7. 常见问题 FAQ
Q1：这个技能怎么安装？
A：在支持 AI 技能的编程助手环境中，按英文名 spec-to-code-compliance 或技能 ID 13560 在技能入口检索并安装；若环境支持本地技能目录，也可将技能文件放入对应目录启用。具体命令与入口以官方说明为准。
Q2：它收费吗？ A：技能详情中未提及定价信息，是否收费取决于你所在平台与技能分发渠道的规则，请以官方说明为准。
Q3：它适合谁用？ A：适合区块链与协议类项目的技术负责人、智能合约开发者、安全审计团队与投研尽调人员。前提是你手上同时有规范文档和代码库；如果只有代码没有文档，它并不适用。
Q4：它和静态分析工具、人工审计是什么关系？ A：三者互补。静态分析工具做自动化缺陷告警，人工审计做综合安全判断，而这个技能做的是“规范与实现的对齐核验”。推荐用法是先用它做合规预检，再把结果交给人工审计做深度验证。
Q5：使用它最容易踩的坑是什么？ A：一是文档准备不充分，导致大量条目被归入“模糊”或“未记录”；二是把“部分匹配”当成通过——按技能自身的规则，部分匹配等同潜在漏洞，必须继续调查到完全匹配或不匹配为止。