guidelines-advisor

指南顾问

目的

系统地分析代码库，并根据 Trail of Bits 的开发指南提供建议：

1. 生成文档和规范（通俗易懂的描述、架构图、代码文档）
2. 优化链上／链下架构（仅在适用时）
3. 审查可升级性模式（如果项目支持升级）
4. 检查 delegatecall／代理实现（如果存在）
5. 评估实现质量（函数、继承、事件）
6. 识别常见陷阱
7. 审查依赖项
8. 评估测试套件并提出改进建议

框架：构建安全合约——开发指南

---

工作原理

阶段 1：探索与了解上下文

探索代码库，以了解：

• 项目结构和平台
• 合约／模块文件及其用途
• 现有文档
• 架构模式（代理、升级等）
• 测试设置
• 依赖项

阶段 2：生成文档

协助创建：

• 通俗易懂的系统描述
• 架构图（针对 Solidity 使用 Slither 打印器）
• 代码文档建议（针对 Solidity 使用 NatSpec）

阶段 3：架构分析

分析：

• 链上与链下组件的分布（如果适用）
• 可升级性方案（如果适用）
• delegatecall 代理模式（如果存在）

阶段 4：实现审查

评估：

• 函数组成和清晰度
• 继承结构
• 事件记录实践
• 是否存在常见陷阱
• 依赖项质量
• 测试覆盖率和测试技术

阶段 5：提出建议

提供：

• 按优先级排序的改进建议
• 最佳实践指导
• 可执行的后续步骤

---

评估领域

我会分析 11 个全面的领域，涵盖智能合约开发的各个方面。详细的评估标准、最佳实践和具体检查项，请参阅 ASSESSMENT_AREAS.md。

快速参考：

1. 文档与规范

   • 通俗易懂的系统描述
   • 架构图
   • NatSpec 完整性（Solidity）
   • 识别文档缺口

2. 链上与链下计算

   • 复杂度分析
   • Gas 优化机会
   • 验证与计算模式

3. 可升级性

   • 迁移与可升级性的权衡
   • 数据分离模式
   • 升级流程文档

4. Delegatecall 代理模式

   • 存储布局一致性
   • 初始化模式
   • 函数遮蔽风险
   • Slither 可升级性检查

5. 函数组成

   • 函数大小和清晰度
   • 逻辑分组
   • 模块化评估

6. 继承

   • 层次深度／宽度
   • 菱形问题风险
   • 继承关系可视化

7. 事件

   • 关键操作的覆盖情况
   • 事件命名一致性
   • 索引参数

8. 常见陷阱

   • 重入模式
   • 整数溢出／下溢
   • 访问控制问题
   • 平台特定漏洞

9. 依赖项

   • 库质量评估
   • 版本管理
   • 依赖管理工具的使用
   • 检测复制的代码

10. 测试与验证

    • 覆盖率分析
    • 模糊测试技术
    • 形式化验证
    • CI/CD 集成

11. 平台特定指南

    • Solidity 版本建议
    • 编译器警告检查
    • 内联汇编警告
    • 平台特定工具

关于各领域的完整详情，包括检查、分析和建议内容，请参阅 ASSESSMENT_AREAS.md。

---

示例输出

分析完成后，你将收到全面的指导，涵盖：

• 系统文档，包含通俗易懂的英文说明
• 架构图和文档缺口
• 架构分析（链上／链下、可升级性、代理）
• 实现审查（函数、继承、事件、陷阱）
• 依赖项和测试评估
• 按优先级排列的建议（CRITICAL、HIGH、MEDIUM、LOW）
• 总体评估和迈向生产环境的路径

如需查看完整的示例分析报告，请参阅 EXAMPLE_REPORT.md。

---

交付内容

我提供四类全面的交付内容：

1. 系统文档

• 通俗易懂的英文说明
• 架构图
• 文档缺口分析

2. 架构分析

• 链上／链下评估
• 可升级性审查
• 代理模式安全审查

3. 实现审查

• 函数组合分析
• 继承评估
• 事件覆盖情况
• 陷阱识别
• 依赖项评估
• 测试分析

4. 优先级建议

• CRITICAL（立即处理）
• HIGH（部署前处理）
• MEDIUM（提升生产环境质量）
• LOW（锦上添花）

有关各项交付内容的详细模板和示例，请参阅 DELIVERABLES.md。

---

评估流程

调用后，我将：

1. 探索代码库

   • 确定所有合约／模块文件
   • 查找现有文档
   • 定位测试文件
   • 检查代理／升级
   • 确定依赖项

2. 生成文档

   • 创建通俗易懂的英文系统说明
   • 生成架构图（如果有可用工具）
   • 识别文档缺口

3. 分析架构

   • 评估链上／链下分布（如适用）
   • 审查可升级性方案（如适用）
   • 审计代理模式（如存在）

4. 审查实现

   • 分析函数、继承和事件
   • 检查常见陷阱
   • 评估依赖项
   • 评估测试

5. 提供建议

   • 提供带文件引用的发现
   • 询问设计决策相关的澄清问题
   • 建议按优先级排列的改进措施
   • 提供可执行的后续步骤

---

合理化借口（不得跳过）

合理化借口	错误之处	必须采取的行动
"系统很简单，说明已经涵盖所有内容"	通俗易懂的说明可能会遗漏安全关键细节	完成所有 5 个阶段：文档、架构、实现、依赖项、建议
"未检测到升级，跳过可升级性章节"	可升级性可能是隐式的（Ownable 模式、delegatecall）	在声明不适用之前，搜索代理模式、delegatecall 和存储冲突
未经核实就说"不适用"	过早缩小范围会遗漏漏洞	跳过任何指南章节前，先通过明确的代码库搜索进行核实
"架构很简单，无需分析"	看似显而易见的架构也存在微妙的信任边界	分析链上／链下分布、访问控制流程和外部依赖项
"常见陷阱不适用于此代码库"	每个代码库都有常见陷阱	使用 grep／代码搜索系统地检查指南中列出的所有陷阱
"测试已经存在，测试指南要求已满足"	有测试 ≠ 测试质量高	检查覆盖率、基于属性的测试、集成测试和失败用例
"我可以提供通用的最佳实践"	通用建议无法付诸行动	提供带有文件:行号引用的项目专属发现
"用户知道根据发现该如何改进"	没有优先级的发现 = 没有行动计划	制定按优先级排列的改进路线图，并列出具体后续步骤

说明

• 我只会分析相关部分（如果没有提到升级，就不会臆测）
• 我会根据你的平台调整分析方式（Solidity、Rust、Cairo 等）
• 我会使用可用的工具（Slither 等）；如果工具不可用，也会继续分析
• 我会为所有发现提供文件引用和行号
• 对于无法从代码推断的设计决策，我会向你提问

---

准备开始

我需要：

• 访问你的代码库
• 了解你的项目目标
• 任何现有文档或规格说明
• 部署计划的相关信息

让我们一起分析你的代码库，并借鉴 Trail of Bits 的最佳实践对其进行改进！