name: multiversx-project-culture
description: 基于文档、测试实践和代码卫生指标评估代码库的质量和成熟度。用于评估项目可靠性、估算审计工作量或入职新代码库时使用。
项目文化与代码成熟度评估
基于文档存在性、测试文化、代码卫生和开发实践评估 MultiversX 代码库的质量和可靠性。此评估有助于校准审计深度并识别关注领域。
何时使用
- 开始与新项目合作时
- 估算审计范围和工作量时
- 评估投资或集成风险时
- 提供开发实践反馈时
- 优先审查重点领域时
1. 文档质量
文档存在性检查清单
| 项目 |
位置 |
状态 |
| README.md |
项目根目录 |
[ ] 存在 [ ] 有用 |
| 构建说明 |
README 或 BUILDING.md |
[ ] 存在 [ ] 测试过 |
| API 文档 |
docs/ 或内联 |
[ ] 存在 [ ] 完整 |
| 架构概述 |
docs/ 或 specs/ |
[ ] 存在 |
| 部署指南 |
README 或 DEPLOY.md |
[ ] 存在 |
MultiversX 特定文档
| 项目 |
用途 |
状态 |
multiversx.json |
标准构建配置 |
[ ] 存在 |
sc-config.toml |
合约配置 |
[ ] 存在 |
multiversx.yaml |
附加配置 |
[ ] 可选 |
snippets.sh |
交互脚本 |
[ ] 有帮助 |
interaction/ |
部署/调用脚本 |
[ ] 非常有帮助 |
规范文档
| 文档 |
质量指标 |
| 白皮书 |
行为的形式规范 |
specs/ 目录 |
详细技术规格 |
| MIP 合规文档 |
标准遵循文档 |
| 安全考虑 |
威胁模型意识 |
文档质量评分
高质量：
- README 解释目的、构建、测试、部署
- 架构图存在
- API 完全文档化并带示例
- 安全模型文档化
中等质量：
- README 带有基本说明
- 部分内联文档
- 部分 API 覆盖
低质量：
- 最小化或无 README
- 无内联注释
- 无架构文档
2. 测试文化评估
测试存在性
# 检查 Rust 单元测试
grep -r "#\[test\]" src/
# 检查场景测试
ls -la scenarios/
# 检查集成测试
ls -la tests/
场景测试覆盖
| 覆盖级别 |
指标 |
| 优秀 |
每个端点都有场景，边缘情况测试，失败路径覆盖 |
| 良好 |
所有端点有基本场景，一些边缘情况 |
| 最小 |
只有 deploy.scen.json 或少量场景 |
| 无 |
无 scenarios/ 目录 |
测试质量指标
// 高质量：测试覆盖边缘情况
#[test]
fn test_deposit_zero_amount() { } // 边界
#[test]
fn test_deposit_max_amount() { } // 边界
#[test]
fn test_deposit_wrong_token() { } // 错误案例
#[test]
fn test_deposit_unauthorized() { } // 访问控制
// 低质量：只有快乐路径
#[test]
fn test_deposit() { } // 仅基本
持续集成
| CI 功能 |
状态 |
| 自动化构建 |
[ ] 存在 |
| 测试执行 |
[ ] 存在 |
| 覆盖率报告 |
[ ] 存在 |
| 检查/格式化 |
[ ] 存在 |
| 安全扫描 |
[ ] 存在 |
模拟测试
查找：
mx-chain-simulator-go 使用- 基于 Docker 的测试环境
- 集成测试脚本
3. 代码卫生评估
检查器合规性
# 运行 Clippy
cargo clippy -- -W clippy::all
# 检查格式化
cargo fmt --check
| Clippy 状态 |
解释 |
| 0 警告 |
优秀卫生 |
| < 10 警告 |
良好，小问题 |
| 10-50 警告 |
需要关注 |
| > 50 警告 |
差卫生 |
魔法数字
# 查找原始数字字面量
grep -rn "[^a-zA-Z_][0-9]\{2,\}[^a-zA-Z0-9_]" src/
差：
let seconds = 86400; // 这是什么？
let fee = amount * 3 / 100; // 魔法 3%
好：
const SECONDS_PER_DAY: u64 = 86400;
const FEE_PERCENT: u64 = 3;
const FEE_DENOMINATOR: u64 = 100;
let seconds = SECONDS_PER_DAY;
let fee = amount * FEE_PERCENT / FEE_DENOMINATOR;
错误处理
# 计算 unwrap 使用次数
grep -c "\.unwrap()" src/*.rs
# 计算 expect 使用次数
grep -c "\.expect(" src/*.rs
# 计算正确错误处理次数
grep -c "sc_panic!\|require!" src/*.rs
| 模式 |
质量指标 |
主要 require! 带消息 |
好 |
混合 require! 和 unwrap() |
需要审查 |
主要 unwrap() |
差 |
代码注释
| 方面 |
良好实践 |
| 复杂逻辑 |
有解释性注释 |
| 公共 API |
有文档注释 |
| 假设 |
内联文档化 |
| TODOs |
跟踪，不忽略 |
// 好：复杂逻辑解释
/// 使用复利公式计算奖励。
/// 公式：P * (1 + r/n)^(nt) 其中：
/// - P: 本金
/// - r: 年利率（以基点计）
/// - n: 复利频率
/// - t: 时间（年）
fn calculate_rewards(&self, principal: BigUint, time: u64) -> BigUint {
// ...
}
// 差：复杂逻辑无解释
fn calc(&self, p: BigUint, t: u64) -> BigUint {
// 密集、未解释的计算
}
4. 依赖管理
Cargo.lock 存在性
ls -la Cargo.lock
| 状态 |
解释 |
| 已提交 |
可重现构建 |
| 未提交 |
版本漂移风险 |
版本固定
# 好：特定版本
[dependencies.multiversx-sc]
version = "0.64.1" # 推荐 edition = "2024"
# 差：通配符版本
[dependencies.multiversx-sc]
version = "*"
# 可接受：插入符（小更新）
[dependencies.multiversx-sc]
version = "^0.54"
依赖审计
# 检查已知漏洞
cargo audit
5. 成熟度评分矩阵
分数计算
| 类别 |
权重 |
高 (3) |
中 (2) |
低 (1) |
| 文档 |
20% |
完整 |
部分 |
最小 |
| 测试 |
30% |
全面覆盖 |
基本覆盖 |
最小 |
| 代码卫生 |
20% |
清洁 Clippy |
少量警告 |
多问题 |
| 依赖 |
15% |
固定、审计过 |
固定 |
通配符 |
| CI/CD |
15% |
完整流水线 |
基本 |
无 |
解释
| 分数 |
成熟度 |
审计重点 |
| 2.5-3.0 |
高 |
业务逻辑、边缘情况 |
| 1.5-2.4 |
中 |
广泛审查、验证基础 |
| 1.0-1.4 |
低 |
所有方面，假设问题存在 |
6. 红旗
立即关注
| 红旗 |
风险 |
| 完全无测试 |
逻辑可能未测试 |
| 通配符依赖 |
供应链漏洞 |
unsafe 块无正当理由 |
内存安全问题 |
过多 unwrap() |
恐慌漏洞 |
| 无 README |
维护废弃？ |
| 过时框架版本 |
已知漏洞 |
黄旗
| 黄旗 |
关注点 |
| 少量场景测试 |
有限覆盖 |
| 一些 Clippy 警告 |
技术债务 |
| 不完整文档 |
知识孤岛 |
| 无 CI/CD |
回归风险 |
7. 评估报告模板
# 项目成熟度评估
**项目**: [名称]
**版本**: [版本]
**日期**: [日期]
**评估者**: [姓名]
## 摘要分数: [X/3.0] - [高/中/低] 成熟度
## 文档 (分数: X/3)
- README: [存在/缺失]
- 构建说明: [测试过/未测试/缺失]
- 架构文档: [完整/部分/缺失]
- API 文档: [完整/部分/缺失]
## 测试 (分数: X/3)
- 单元测试: [X 测试找到]
- 场景测试: [X 场景覆盖 Y 端点]
- 覆盖率估计: [X%]
- 边缘情况覆盖: [好/部分/最小]
## 代码卫生 (分数: X/3)
- Clippy 警告: [X 警告]
- 格式化: [一致/不一致]
- 魔法数字: [X 实例]
- 错误处理: [好/需要改进]
## 依赖 (分数: X/3)
- Cargo.lock: [已提交/缺失]
- 版本固定: [全部/部分/无]
- 已知漏洞: [无/X 找到]
## CI/CD (分数: X/3)
- 构建自动化: [是/否]
- 测试自动化: [是/否]
- 安全扫描: [是/否]
## 推荐
1. [最高优先级改进]
2. [第二优先级]
3. [第三优先级]
## 审计重点领域
基于此评估，审计应优先：
1. [基于弱点的领域]
2. [基于风险的领域]
8. 按级别改进推荐
对于低成熟度项目
- 添加基本 README 带构建说明
- 为所有端点创建场景测试
- 修复所有 Clippy 警告
- 固定依赖版本
- 设置基本 CI
对于中成熟度项目
- 扩展测试覆盖到边缘情况
- 添加架构文档
- 文档化安全考虑
- 添加覆盖率报告
- 实施安全扫描
对于高成熟度项目
- 考虑形式验证
- 模糊和属性测试
- 外部安全审计
- 漏洞赏金计划
- 事件响应文档