8.1 KiB

Raw Blame History

NAC Lint编译辅助检查器 - 集成指南

概述

NAC Lint是一个编译前置检查工具，自动检测违反NAC原则的代码。本指南介绍如何将NAC Lint集成到您的开发工作流程中。

快速开始

1. 基本使用

# 检查单个文件
python3 memory/tools/nac_lint.py check --path src/main.rs

# 检查整个目录
python3 memory/tools/nac_lint.py check --path src/

# 列出所有规则
python3 memory/tools/nac_lint.py list-rules

# 生成JSON报告
python3 memory/tools/nac_lint.py check --path src/ --output json --output-file report.json

2. 检查结果解读

❌ CRITICAL: 3 violation(s)
  - 阻止编译，必须修复

⚠️  HIGH: 2 violation(s)
  - 强烈建议修复，但不阻止编译

ℹ️  MEDIUM: 1 violation(s)
  - 建议修复

💡 LOW: 0 violation(s)
  - 可选修复

集成方式

方式1: Git Pre-commit Hook（推荐）

优点: 在提交前自动检查，防止违规代码进入仓库

安装步骤:

# 1. 复制pre-commit脚本
cp memory/tools/pre-commit .git/hooks/pre-commit

# 2. 设置可执行权限
chmod +x .git/hooks/pre-commit

# 3. 测试（尝试提交一个违规文件）
git add src/test.rs
git commit -m "test"
# 如果有违规，提交会被阻止

工作流程:

开发者执行 git commit
Git自动运行pre-commit hook
NAC Lint检查staged文件
如果发现CRITICAL违规，阻止提交
开发者修复违规后重新提交

方式2: Cargo Build Script

优点: 在cargo build时自动检查

安装步骤:

# 1. 复制build.rs模板到项目根目录
cp memory/tools/build.rs.template build.rs

# 2. 在Cargo.toml中添加（如果还没有）
# [build-dependencies]
# （build.rs不需要额外依赖）

# 3. 测试
cargo build
# 如果有违规，构建会失败

工作流程:

开发者执行 cargo build
Cargo运行build.rs
build.rs调用NAC Lint检查src/
如果发现CRITICAL违规，panic阻止构建
开发者修复违规后重新构建

注意:

只在debug模式下运行检查（加快release构建）
可以通过环境变量 SKIP_NAC_LINT=1 跳过检查

方式3: Makefile集成

优点: 统一的命令接口，易于使用

安装步骤:

# 1. 将Makefile.template内容添加到项目Makefile
cat memory/tools/Makefile.template >> Makefile

# 2. 使用
make lint          # 运行检查
make build         # 先检查再构建
make test          # 先检查再测试
make install-hooks # 安装Git hooks

可用命令:

make lint - 运行NAC Lint检查
make lint-json - 生成JSON报告
make lint-rules - 列出所有规则
make build - 先检查再构建
make test - 先检查再测试
make install-hooks - 安装Git hooks

方式4: GitHub Actions CI/CD

优点: 在PR和push时自动检查，团队协作友好

安装步骤:

# 1. 创建GitHub Actions工作流目录
mkdir -p .github/workflows

# 2. 复制工作流文件
cp memory/tools/nac-lint.yml.template .github/workflows/nac-lint.yml

# 3. 提交并推送
git add .github/workflows/nac-lint.yml
git commit -m "Add NAC Lint CI"
git push

工作流程:

开发者push代码或创建PR
GitHub Actions自动运行NAC Lint
生成检查报告并上传为artifact
如果是PR，自动在PR中评论检查结果
如果有CRITICAL违规，CI失败

方式5: 手动集成

适用场景: 自定义构建流程

# 在任何脚本中调用
python3 memory/tools/nac_lint.py check --path src/
if [ $? -ne 0 ]; then
    echo "NAC Lint check failed"
    exit 1
fi

配置文件

.naclintrc

在项目根目录创建 .naclintrc 配置文件：

# 复制模板
cp memory/tools/.naclintrc.template .naclintrc

# 编辑配置
vim .naclintrc

配置选项:

{
  "version": "1.0",
  "enabled": true,                    // 是否启用检查
  "severity_threshold": "high",       // 严重性阈值
  "exclude_paths": [                  // 排除路径
    "target/",
    "node_modules/",
    "*.test.rs"
  ],
  "rules": {
    "terminology": {
      "enabled": true,
      "severity": "critical"
    },
    "naming": {
      "enabled": true,
      "severity": "high"
    }
  },
  "fail_on_critical": true,           // CRITICAL时失败
  "fail_on_high": false,              // HIGH时不失败
  "output_format": "console",         // 输出格式
  "verbose": true                     // 详细输出
}

检查规则

当前规则（23条）

CRITICAL级别（必须修复）

TERM_001-010: 术语检查
- Token → Asset
- Contract → Certificate
- Balance → Holdings
- PoW/PoS → CBPP
- P2P → CSNP
- RPC → NAC Lens
- EVM → NVM
- SHA256 → Blake3
- Governance Token → XIC
- Stablecoin → XTZH
TERM_011-020: 协议和工具检查
- ERC-20 → ACC-20
- Wallet → Asset Vault
- Transaction → Asset Transfer
- Block Explorer → Quantum Holographic Explorer

HIGH级别（强烈建议修复）

ARCH_002: OpCode命名必须使用UPPER_CASE
ARCH_003: 必须使用Blake3哈希算法
ARCH_004: 禁止使用#[allow(unused)]

常见问题

Q1: 如何跳过某个文件的检查？

方法1: 在.naclintrc中添加排除路径

{
  "exclude_paths": [
    "src/legacy/old_code.rs"
  ]
}

方法2: 在文件顶部添加注释（未实现，计划中）

// nac-lint: disable

Q2: 如何临时禁用检查？

# 环境变量
SKIP_NAC_LINT=1 cargo build

# 或在Git提交时
git commit --no-verify

Q3: 检查太慢怎么办？

# 只检查修改的文件
git diff --name-only | xargs python3 memory/tools/nac_lint.py check --path

# 使用快速模式（只检查CRITICAL）
python3 memory/tools/nac_lint.py check --path src/ --severity critical

Q4: 如何添加自定义规则？

创建 memory/rules/custom_rules.json:

{
  "rule_id": "CUSTOM_001",
  "category": "custom",
  "severity": "medium",
  "title": "自定义规则",
  "pattern": "your_regex_pattern",
  "suggestion": "建议修复方式"
}

然后在.naclintrc中引用：

{
  "custom_rules": [
    "memory/rules/custom_rules.json"
  ]
}

最佳实践

1. 团队协作

✅ 在项目README中说明NAC Lint的使用
✅ 在onboarding时安装Git hooks
✅ 在CI/CD中强制执行检查
✅ 定期更新规则库

2. 开发流程

# 开发前
make install-hooks  # 安装Git hooks

# 开发中
# ... 编写代码 ...

# 提交前（自动运行）
git commit -m "..."

# 如果被阻止
make lint           # 查看详细违规
# ... 修复违规 ...
git commit -m "..."

# 构建前（自动运行）
make build

3. CI/CD流程

# .github/workflows/nac-lint.yml
- name: NAC Lint
  run: make lint-json
  
- name: Upload Report
  uses: actions/upload-artifact@v3
  with:
    name: lint-report
    path: lint-report.json

故障排除

问题1: Python找不到

# 检查Python版本
python3 --version

# 如果没有Python 3，安装
sudo apt install python3

问题2: 规则文件找不到

# 确保记忆系统目录结构完整
ls -la memory/principles/
ls -la memory/tools/

# 如果缺失，重新创建
# （参考记忆系统安装指南）

问题3: Git hook不工作

# 检查hook是否可执行
ls -la .git/hooks/pre-commit

# 设置可执行权限
chmod +x .git/hooks/pre-commit

# 测试hook
.git/hooks/pre-commit

更新日志

v1.0.0 (2026-02-07)

✅ 初始版本
✅ 23条检查规则
✅ Git Hook集成
✅ Cargo集成
✅ Makefile集成
✅ GitHub Actions集成
✅ 配置文件支持

计划中的功能

自动修复（--fix选项）
IDE集成（VS Code插件）
实时检查（保存时检查）
AI辅助检查
检查报告仪表板

支持

如有问题，请查看：

记忆系统文档: memory/README.md
快速参考卡: memory/QUICK_REFERENCE.md
设计文档: memory/tools/LINT_CHECKER_DESIGN.md

NAC Lint - 确保代码符合NAC原则，避免以太坊遗留

8.1 KiB Raw Blame History Unescape Escape

NAC Lint编译辅助检查器 - 集成指南

概述

快速开始

1. 基本使用

2. 检查结果解读

集成方式

方式1: Git Pre-commit Hook（推荐）

方式2: Cargo Build Script

方式3: Makefile集成

方式4: GitHub Actions CI/CD

方式5: 手动集成

配置文件

.naclintrc

检查规则

当前规则（23条）

CRITICAL级别（必须修复）

HIGH级别（强烈建议修复）

常见问题

Q1: 如何跳过某个文件的检查？

Q2: 如何临时禁用检查？

Q3: 检查太慢怎么办？

Q4: 如何添加自定义规则？

最佳实践

1. 团队协作

2. 开发流程

3. CI/CD流程

故障排除

问题1: Python找不到

问题2: 规则文件找不到

问题3: Git hook不工作

更新日志

v1.0.0 (2026-02-07)

计划中的功能

支持

8.1 KiB

Raw Blame History