# ngnc-longmen2-vm

**Repository Path**: ngnc/ngnc-longmen2-vm

## Basic Information

- **Project Name**: ngnc-longmen2-vm
- **Description**: **"泥土中的脊椎"攻关作战 - 100%状态可追溯的微型虚拟机**
- **Primary Language**: C
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-30
- **Last Updated**: 2026-01-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🏔️ NGNC龙门二虚拟机

> **"泥土中的脊椎"攻关作战 - 100%状态可追溯的微型虚拟机**

## 🎯 项目使命

用不超过5000行C代码，构建一个所有状态变更因果链100%可追溯、可差分调试的微型虚拟机/解释器。

**铁律**：林纳斯说过——"不准用任何取巧的黑魔法，代码必须丑陋到每一处复杂都清晰可见。"

## 📊 当前状态

| 阶段 | 状态 | 完成度 | 行数 |
|------|------|--------|------|
| 阶段一：宪法起草 | ✅ 完成 | 100% | 545行 |
| 阶段二：脊椎锻造 | 🚧 进行中 | 0% | 0行 |
| 阶段三：压力测试 | ⏳ 待开始 | 0% | 0行 |
| 阶段四：宪法封存 | ⏳ 待开始 | 0% | 0行 |

**总行数**: 545/5000 (10.9%)

## 🏗️ 架构概览

### 核心设计原则
1. **丑陋的透明** - 代码直接反映逻辑，无黑魔法
2. **100%状态追溯** - 任意时刻状态可重建
3. **新手友好** - 大二学生应能理解核心设计
4. **自解释代码** - 最小化注释，代码即文档

### 数据类型系统
- `vm_word`: 32位通用数据容器
- `vm_register`: 16个带时间戳的寄存器
- `vm_memory_cell`: 带访问历史的内存单元
- `vm_instruction`: 固定格式指令
- `vm_core_state`: 完整虚拟机状态

### 日志系统
- **快照+差异链策略**: 每1000周期完整快照，之间记录差异
- **10种事件类型**: 寄存器写入、内存访问、指令执行等
- **状态重建API**: `vm_reconstruct_state()`可重建任意时刻状态

## 🚀 快速开始

```bash
# 克隆仓库
git clone https://github.com/ngnc/longmen2-vm.git
cd longmen2-vm

# 构建（当前只有头文件，实现待完成）
make

# 运行测试
make test
```

## 📁 文件结构

```
├── include/          # 头文件 - 阶段一完成
│   ├── vm_core_types.h    # 核心数据类型 ✅
│   └── vm_log_system.h    # 日志系统 ✅
├── src/             # 源文件 - 阶段二进行中
├── tests/           # 测试代码
└── docs/            # 设计文档
```

## 🔧 构建要求

- C编译器 (GCC 9.0+ 或 Clang 10.0+)
- CMake 3.10+ (可选)
- Python 3.8+ (用于日志分析工具)

## 📚 设计文档

- [设计原则](DESIGN_PRINCIPLES.md) - 项目核心哲学
- [阶段一报告](docs/PHASE1_REPORT.md) - 数据类型和日志系统设计
- [日志格式](docs/LOG_FORMAT.md) - 状态追溯格式详解

## 👥 贡献指南

### 开发流程
1. **原则审查**: 所有代码必须通过PROSECUTOR审查
2. **新手测试**: NEWBIE-TORMENTOR验证可理解性
3. **行数限制**: 严格控制在5000行内
4. **状态追溯**: 确保100%状态可重建

### 代码风格
- 使用`.clang-format`配置
- 每行不超过80字符
- 所有结构体字段必须有自解释注释
- 禁止"聪明"的优化技巧

## 📝 许可证

本项目遵循NGNC开源宪法第2章：
- 代码必须保持透明
- 设计决策必须记录
- 新手友好性优先于性能优化

## 🆘 寻求帮助

- 问题讨论: GitHub Issues
- 设计决策: 参考设计文档
- 新手困惑: 查看测试报告中的常见问题

---

**龙门二特遣队**: ASM-POET · STATE-ARCH · NEWBIE-TORMENTOR · PROSECUTOR  
**作战开始**: 2025年 [作战记录已归档]