**交互式 x86 汇编模拟器与学习实验室**
一个完整的基于浏览器的学习 x86 汇编的环境：从零开始的逐步模拟器、可视化堆栈游乐场（含嵌套帧跟踪）、寄存器测验游戏、23 个教程章节（涵盖从基础到高级主题，如指针、调用约定、结构体、浮点数等），以及 7 个交互工具（指令参考、数字转换器、位运算计算器、字节序指南、ASCII 表、标志计算器、地址计算器）。无需后端、无需构建步骤、无依赖。
## 快速开始
### GitHub Pages
访问在线站点：**https://Real-Fruit-Snacks.github.io/x86-assembly-lab/**
### 本地运行
无需构建步骤、无依赖。直接打开 HTML 文件或运行服务：
```
# 选项 1：直接打开
open index.html
# 选项 2：本地服务器
python -m http.server 3456
# → http://localhost:3456
# 选项 3：Node
npx serve . -l 3456
```
## 功能特性
### 沙箱模拟器
粘贴任意 x86 汇编代码并逐步执行。支持标签、分支、循环、函数调用、内存操作以及 IDA 风格表示法。寄存器、标志和内存会实时更新，支持 DEC/HEX/BIN 显示模式。按类别组织的 24 个内置示例并带有教学注释。
```
Supported instructions:
MOV, MOVSX, MOVZX, ADD, SUB, INC, DEC, NEG, XCHG, LEA
AND, OR, XOR, NOT, TEST, CMP
SHL, SHR, SAR, ROL, ROR, MUL, IMUL, DIV, IDIV, CDQ
PUSH, POP, CALL, RET, LEAVE, NOP
JMP, JE, JNE, JB, JBE, JA, JAE, JL, JLE, JG, JGE
(+ all aliases: JZ, JNZ, JNA, JNBE, SAL, RETN, etc.)
```
在代码下方的可搜索固定参考面板中解释每个寄存器和标志。
### 堆栈游乐场
四种模式用于学习堆栈的实际工作方式，完全支持嵌套函数调用和基于帧的相对标签。
```
Explore Visual stack with 7 action buttons (PUSH, POP, CALL, RET,
PROLOGUE, ALLOC, LEAVE), 6 preset scenarios, quick-try chips,
key-facts card, and an EXECUTE input that accepts any x86
instruction from the sandbox
Step-Through 5 guided walkthroughs (full function call, prologue/epilogue,
reading arguments, locals, LIFO) with prev/next navigation,
progress bar, and per-step explanations
Puzzle Random stack-state prediction puzzles with scoring and
streak tracking
Errors 6 common stack bugs explained step-by-step (unbalanced POP,
missing prologue, missing caller cleanup, RET without return
address, LEAVE without frame, stack overflow)
```
每个单元格会自动标注其帧相对的 `[ebp±N]` 地址和语义含义（“参数 2”、“保存的 EBP”、“返回地址”、“局部变量 1”）。嵌套的调用帧使用彩色边框进行视觉区分（当前=蓝色、调用者=紫红色、更深层=绿色/桃色/蓝绿色），并始终显示调用链概览：`main → Stack1 → Stack2 (当前)`。以补码形式显示为负数的值会以有符号形式显示（例如 `-5 (4294967291)`）。
### 寄存器测验
带有三种难度等级的趣味练习。随机题目、计分、连续答题记录、最佳记录记忆以及每题计时器。每道题接受十进制、十六进制（`0x...` 或 `...h`）或负数形式的答案。
```
Easy (1 pt) 2-4 instructions, MOV/ADD/SUB/INC/DEC/NEG/XCHG
Medium (2 pt) 4-6 instructions, adds MUL/DIV/shifts/AND/OR/XOR/NOT
Hard (3 pt) 6-10 instructions, chained IMUL/DIV/remainder tracking
```
### 输入格式支持
所有输入均接受多种数字和表示法格式：
```
Decimal: mov eax, 42 mov eax, -5
Hex (0x): mov eax, 0xFF mov eax, -0xFF
Hex (IDA): mov eax, 0FFh mov eax, 0Ch
Binary: mov al, 0b11001100 mov al, 11001100b
Character: mov al, 'A'
IDA vars: mov eax, [ebp+var_4]
IDA args: mov eax, [ebp+arg_0]
Memory: mov dword ptr [ebp-8], 45
```
### 拼写纠错
检测拼写错误、英文单词等价词以及近似错误并提供建议：
```
"move eax, 10" → Did you mean "mov"?
"subtract eax, 5" → Did you mean "sub"?
"swap eax, ebx" → Did you mean "xchg"?
"xhcg eax, ebx" → Did you mean "xchg"? (fuzzy match via edit distance)
```
缺失的操作数或无效寄存器会生成带有使用示例的清晰错误信息。
### 教程
23 个学习章节，包含 23+ 个交互式迷你模拟器、前后寄存器快照、逐步演练、练习挑战以及纯英文参考表。所有技术术语（如 cdecl、IDA Pro、DWORD 等）在首次使用时都会在内联定义。
```
Fundamentals:
- Register Map Complete sub-register diagram, plain-English implicit-use table
- Two's Complement Step-by-step negation, ranges, key patterns
- Flags Worked CMP walkthrough, OF deep dive, concrete flag tracing
- Memory & Data Sizes Brackets vs no-brackets walkthrough, scaled array addressing
Instructions:
- Arithmetic MOV, ADD, SUB, INC, DEC, NEG, XCHG
- Bitwise Logic AND, OR, XOR, NOT, TEST with binary visualization
- Multiply & Divide EDX:EAX visual diagram, cheat sheet, before/after snapshots,
common mistakes, 4 mini-sims, 3 practice challenges
- Shifts SHL, SHR, SAR with negative-number SAR vs SHR comparison
- Branching Worked branch trace, signed vs unsigned JA/JG comparison,
plain-English jump table with memory aids
- Stack & Functions PUSH/POP LIFO walkthrough, full 9-step CALL sequence table
- Common Idioms XOR zeroing, LEA math breakdown, cdecl cleanup formula
Analysis:
- Functional Analysis How to read a function and describe it as f(a,b) = ...
- Control Structures If/else, loops, switch statements, jump tables
Advanced:
- Extension Instr. MOVSX/MOVZX sign vs zero extension, CBW/CWD/CDQ cheat sheet
- Pointers Read/write/double-deref patterns, LEA vs MOV, pass by ref
- Variables & Scope Local/argument/global/constant identification decision tree
- Calling Conventions cdecl/stdcall/fastcall/thiscall, volatile vs non-volatile regs
- Arrays Index-based vs pointer-advancing patterns, string instructions
- Strings ASCII/Unicode encoding, null-terminated patterns, hex decoding
- Structures Struct field access patterns, heterogeneous offsets, stack structs
- Dynamic Memory Stack vs heap, malloc/free patterns, Windows HeapAlloc API
- Floating Point FPU stack (ST0-ST7), FLD/FST/FADD, IEEE 754 basics
- Misc Instructions ROL/ROR rotation, INT 3 anti-debug, PUSHA/POPA packers
```
### 工具
七种可在解决问题时使用的交互工具：
```
Instruction Reference Searchable lookup with flag behavior, operand notation, examples
Number Converter Decimal ↔ Hex ↔ Binary, signed/unsigned, dynamic boundary table
Bitwise Calculator AND/OR/XOR/NOT with truth tables, color-coded bits, common uses
Endianness Guide Interactive byte-order explorer with step-by-step walkthrough
ASCII Table Clickable 128-character grid, bidirectional lookup (char/dec/hex)
Flags Calculator Enter an operation + values, see all flags + which jumps fire
Address Calculator Effective address math + stack frame offset calculator from EBP
```
### UI 细节优化
- **全程使用 Catppuccin Mocha 主题**，包括自定义滚动条
- **可折叠的侧边栏**以扩展工作区域；状态在刷新后保持
- **响应式布局**可自适应至移动设备宽度
- **可视化演练**包含前后寄存器快照、作弊表和常见错误章节
- **冗长的步骤描述**（例如：“无符号除法：EDX:EAX / ecx = 17÷5 = 3 余 2。良好实践：EDX 首先被清零”）
- **纯英文参考表**——每个表格都提供对初学者友好的列，所有术语在内联定义
## 架构
```
Assembly/
├── index.html # Single-page app with 34 sections
├── style.css # Catppuccin Mocha theme with custom scrollbars
├── simulator.js # x86 engine: registers, flags, memory, stack, branches
├── app.js # UI: sandbox, playground, quiz, mini-sims, tools
├── docs/assets/ # Dark + light mode logo SVGs
└── README.md
```
纯客户端 HTML、CSS 和 JavaScript。无框架、无构建步骤、无依赖。模拟器引擎直接在浏览器中解析并执行 x86 指令，包含寄存器文件、标志模型、字节寻址内存、标签解析和分支评估。
### 模拟器能力
| 功能 | 实现 |
|------|------|
| 寄存器 | EAX-EDX（含 8/16 位子寄存器 AL/AH/AX）、ESI、EDI、EBP、ESP |
| 标志 | ZF、CF、SF、OF（每条指令正确设置） |
| 内存 | 基于字节的读写，支持 BYTE/WORD/DWORD 大小 |
| 堆栈 | 基于 ESP 的 PUSH/POP，依赖真实内存 |
| 分支 | 标签解析、所有条件跳转、嵌套循环 |
| 函数 | CALL/RET 带返回地址栈、LEAVE、嵌套调用 |
| 帧跟踪 | 每帧 EBP 锚点、基于 argBoundary 的单元格分配、帧相对标签 |
| IDA 表示法 | `var_N` → `[ebp-N]`，`arg_N` → `[ebp+N+8]`，十六进制使用 `h` 后缀 |
| 错误处理 | 拼写检测、操作数验证、无限循环保护（10K 步） |
## 测试覆盖
自动化测试套件涵盖正确性、模糊鲁棒性以及端到端的每个示例/场景。
### 正确性（507 个测试）
| 类别 | 测试数 |
|------|--------:|
| 所有 21 个导航链接 + 所有 23 个沙箱示例 + 每条指令类型 | 73 |
| 寄存器测验：15 轮 × 3 个难度 + 错误答案 + 十六进制输入 | 53 |
| 堆栈游乐场所有 4 个模式：Explore、Step-Through、Puzzle、Errors | 96 |
| 深度嵌套（3 层及以上）、完整展开、复杂执行场景 | 16 |
| 数字转换器（8/16/32 位）、位运算计算器、字节序、参考搜索 | 75 |
| 模糊测试：垃圾输入、快速点击、空状态、边界情况 | 194 |
### 场景验证（203 个测试）
| 场景类型 | 数量 | 验证结果 |
|----------|------|----------|
| 沙箱示例 | 24 | 24 |
| Explore 模式场景 | 6 | 6 |
| Step-Through 演练 | 5 | 5 |
| 错误场景 | 6 | 6 |
| 谜题生成 | 30 | 30 |
| 教程中的迷你模拟器 | 24 | 24 |
每个示例、场景、演练和迷你模拟器都已验证其产生预期的寄存器/堆栈状态。
## 许可证
[MIT](LICENSE) -- Copyright 2026 Real-Fruit-Snacks