NAC_Blockchain/docs/reports/NAC-DevTools-README.md

# NAC Protocol Development Toolchain v1.0.0

**NAC原生公链协议开发工具链**

## 📦 包含内容

1. **nac-devtools** - 协议开发工具链
2. **nac-protocols** - 协议实现目录（已生成示例协议）
3. **memory** - 记忆系统（包含所有技术决策和规范）

## 🚀 快速开始

### 1. 解压

```bash
tar -xzf NAC-DevTools-v1.0.0.tar.gz
cd NAC_Clean_Dev
```

### 2. 编译工具链（如需要）

```bash
cd nac-devtools
cargo build --release
```

### 3. 使用工具

```bash
# 查看帮助
./nac-devtools/target/release/nac-devtools --help

# 生成协议
./nac-devtools/target/release/nac-devtools generate protocol \
  --id NAC-PROTOCOL-0008 \
  --layer 0 \
  --name GasProtocol

# 验证代码
./nac-devtools/target/release/nac-devtools validate file \
  nac-protocols/src/layer0/randomness_protocol.rs

# 验证整个项目
./nac-devtools/target/release/nac-devtools validate project nac-protocols

# 构建所有协议
./nac-devtools/target/release/nac-devtools build all

# 打包系统
./nac-devtools/target/release/nac-devtools package \
  --output NAC-Complete-System.tar.gz
```

## 📚 工具功能

### 1. 协议生成器 (generate)

- **单个协议生成**: `generate protocol`
- **批量生成**: `generate batch`
- **配置文件生成**: `generate from-config`

**特性**：
- ✅ 自动使用SHA3-384哈希算法
- ✅ 遵循GNACS 34位编码
- ✅ 强制NAC术语规范
- ✅ 自动生成测试文件
- ✅ 自动更新模块文件
- ✅ 记录到记忆系统

### 2. 代码验证器 (validate)

- **术语验证**: 检查是否使用禁止的以太坊术语
- **架构验证**: 检查是否遵循NAC架构原则
- **哈希验证**: 确保使用SHA3-384而非Blake3
- **编码验证**: 确保使用GNACS 34位编码

### 3. 测试框架 (test)

- **生成测试**: `test generate`
- **运行测试**: `test run`
- **性能测试**: `test benchmark`
- **覆盖率报告**: `test coverage`

### 4. 文档生成器 (doc)

- **API文档**: `doc api`
- **协议文档**: `doc protocol`
- **完整文档**: `doc all`

### 5. 构建系统 (build)

- **编译所有**: `build all`
- **编译层级**: `build layer`
- **清理缓存**: `build clean`

### 6. 打包发布 (package)

```bash
nac-devtools package --output NAC-System.tar.gz
```

## 📋 已生成的示例协议

- **NAC-PROTOCOL-0007**: RandomnessProtocol (Layer 0)
  - 文件: `nac-protocols/src/layer0/randomness_protocol.rs`
  - 测试: `nac-protocols/tests/layer0/randomness_protocol_test.rs`

## 🎯 开发134个协议的工作流

### 阶段1：准备工作

```bash
# 1. 查看记忆系统中的规范
cat memory/principles/terminology.json
cat memory/principles/architecture.json
cat memory/decisions/D002_Hash_Algorithm_SHA3_384.json

# 2. 查看协议清单
cat memory/documents/NAC_Protocol_Stack_v4.0.json
```

### 阶段2：生成协议

```bash
# 方式1：逐个生成
nac-devtools generate protocol --id NAC-PROTOCOL-0001 --layer 0 --name ConsensusProtocol
nac-devtools generate protocol --id NAC-PROTOCOL-0002 --layer 0 --name NetworkProtocol

# 方式2：配置文件批量生成
# 创建 config/protocols.yaml
nac-devtools generate from-config --config config/protocols.yaml
```

### 阶段3：验证和测试

```bash
# 验证代码规范
nac-devtools validate project nac-protocols

# 运行测试
nac-devtools test run

# 性能测试
nac-devtools test benchmark --protocol NAC-PROTOCOL-0007
```

### 阶段4：构建和打包

```bash
# 编译所有协议
nac-devtools build all

# 打包完整系统
nac-devtools package --output NAC-Complete-System-$(date +%Y%m%d).tar.gz
```

## 🔧 配置文件示例

创建 `config/protocols.yaml`:

```yaml
protocols:
  - id: NAC-PROTOCOL-0001
    layer: 0
    name: ConsensusProtocol
    priority: P0
    description: CBPP共识协议实现
    dependencies: []
    estimated_hours: 8
    
  - id: NAC-PROTOCOL-0002
    layer: 0
    name: NetworkProtocol
    priority: P0
    description: CSNP网络协议实现
    dependencies:
      - NAC-PROTOCOL-0001
    estimated_hours: 10
```

## 📊 记忆系统

所有生成的协议都会自动记录到记忆系统：

```bash
# 查看已生成的协议
cat memory/generated_protocols.json

# 查看技术决策
ls memory/decisions/

# 查看原则规范
ls memory/principles/
```

## ⚠️ 重要规则

### 1. 哈希算法

- ✅ **必须使用**: SHA3-384（48字节）
- ❌ **禁止使用**: Blake3, SHA256, Keccak256

### 2. 术语规范

| ❌ 禁止（以太坊） | ✅ 使用（NAC） |
|---|---|
| token | asset |
| contract | certificate |
| balance | holdings |
| wallet | vault |
| mint | issue |
| burn | redeem |

### 3. 编码标准

- ✅ **GNACS 34位编码**
- ❌ 不使用24字节旧版本

## 📈 开发进度追踪

工具会自动记录开发进度到 `memory/generated_protocols.json`:

```json
{
  "generated_protocols": [
    {
      "id": "NAC-PROTOCOL-0007",
      "layer": 0,
      "name": "RandomnessProtocol",
      "priority": "P0",
      "generated_at": "2026-02-09T19:44:00Z"
    }
  ],
  "total_count": 1,
  "last_updated": "2026-02-09T19:44:00Z"
}
```

## 🎓 最佳实践

1. **工作前必须激活记忆系统**
   ```bash
   cat memory/principles/terminology.json
   cat memory/decisions/*.json
   ```

2. **每次生成后立即验证**
   ```bash
   nac-devtools generate protocol ...
   nac-devtools validate file <生成的文件>
   ```

3. **定期运行测试**
   ```bash
   nac-devtools test run
   ```

4. **定期打包备份**
   ```bash
   nac-devtools package --output backup-$(date +%Y%m%d).tar.gz
   ```

## 🔗 相关文档

- NAC协议栈v4.0: `memory/documents/NAC_Protocol_Stack_v4.0.json`
- 核心组件分析: `memory/documents/NAC_Core_Components_Analysis.json`
- 完整开发记录: `memory/decisions/complete_development_record.md`

## 📞 技术支持

如有问题，请查阅记忆系统中的文档，或查看工具的详细帮助：

```bash
nac-devtools --help
nac-devtools generate --help
nac-devtools validate --help
```

---

**NAC原生公链 - 不是任何公链的继承、衍生或扩展**