From a7f1627df0b7ef6d9e28fdb0a10e869799f1319c Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Mon, 28 Apr 2025 16:00:48 +0800
Subject: [PATCH] =?UTF-8?q?=E5=A2=9E=E5=8A=A0=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .run/Main.run.xml                             |  2 +-
 .../{Main.java => cli/SnowCompiler.java}      | 14 +---
 .../lexer/{ => base}/TokenScanner.java        |  3 +-
 .../lexer/{ => core}/LexerContext.java        |  6 +-
 .../lexer/{ => core}/LexerEngine.java         |  3 +-
 .../jcnc/snow/compiler/lexer/doc/README.md    | 67 +++++++++++--------
 .../lexer/scanners/AbstractTokenScanner.java  |  4 +-
 .../lexer/scanners/CommentTokenScanner.java   |  2 +-
 .../scanners/IdentifierTokenScanner.java      |  2 +-
 .../lexer/scanners/NewlineTokenScanner.java   |  2 +-
 .../lexer/scanners/NumberTokenScanner.java    |  2 +-
 .../lexer/scanners/OperatorTokenScanner.java  |  2 +-
 .../lexer/scanners/StringTokenScanner.java    |  2 +-
 .../lexer/scanners/SymbolTokenScanner.java    |  2 +-
 .../lexer/scanners/UnknownTokenScanner.java   |  2 +-
 .../scanners/WhitespaceTokenScanner.java      |  2 +-
 .../jcnc/snow/compiler/parser/doc/README.md   | 59 ++++++++++++++++
 .../jcnc/snow/compiler/semantic/doc/README.md | 56 ++++++++++++++++
 18 files changed, 176 insertions(+), 56 deletions(-)
 rename src/main/java/org/jcnc/snow/compiler/{Main.java => cli/SnowCompiler.java} (69%)
 rename src/main/java/org/jcnc/snow/compiler/lexer/{ => base}/TokenScanner.java (91%)
 rename src/main/java/org/jcnc/snow/compiler/lexer/{ => core}/LexerContext.java (95%)
 rename src/main/java/org/jcnc/snow/compiler/lexer/{ => core}/LexerEngine.java (96%)
 create mode 100644 src/main/java/org/jcnc/snow/compiler/parser/doc/README.md
 create mode 100644 src/main/java/org/jcnc/snow/compiler/semantic/doc/README.md

diff --git a/.run/Main.run.xml b/.run/Main.run.xml
index 96e97f6..4bbf319 100644
--- a/.run/Main.run.xml
+++ b/.run/Main.run.xml
@@ -1,6 +1,6 @@
 <component name="ProjectRunConfigurationManager">
   <configuration default="false" name="Main" type="Application" factoryName="Application" nameIsGenerated="true">
-    <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.compiler.Main" />
+    <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.compiler.cli.SnowCompiler" />
     <module name="SCompiler" />
     <option name="PROGRAM_PARAMETERS" value="test" />
     <extension name="coverage">
diff --git a/src/main/java/org/jcnc/snow/compiler/Main.java b/src/main/java/org/jcnc/snow/compiler/cli/SnowCompiler.java
similarity index 69%
rename from src/main/java/org/jcnc/snow/compiler/Main.java
rename to src/main/java/org/jcnc/snow/compiler/cli/SnowCompiler.java
index 5571248..ae076f5 100644
--- a/src/main/java/org/jcnc/snow/compiler/Main.java
+++ b/src/main/java/org/jcnc/snow/compiler/cli/SnowCompiler.java
@@ -1,27 +1,19 @@
-package org.jcnc.snow.compiler;
+package org.jcnc.snow.compiler.cli;
 
-import org.jcnc.snow.compiler.lexer.LexerEngine;
+import org.jcnc.snow.compiler.lexer.core.LexerEngine;
 import org.jcnc.snow.compiler.lexer.token.Token;
-import org.jcnc.snow.compiler.lexer.utils.TokenPrinter;
 import org.jcnc.snow.compiler.parser.core.ParserEngine;
-import org.jcnc.snow.compiler.parser.ast.ModuleNode;
 import org.jcnc.snow.compiler.parser.context.ParserContext;
 import org.jcnc.snow.compiler.parser.ast.base.Node;
-import org.jcnc.snow.compiler.parser.function.ASTPrinter;
-import org.jcnc.snow.compiler.semantic.core.SemanticAnalyzer;
 import org.jcnc.snow.compiler.semantic.core.SemanticAnalyzerRunner;
-import org.jcnc.snow.compiler.semantic.error.SemanticError;
-import org.jcnc.snow.compiler.semantic.utils.SemanticAnalysisReporter;
 
 import java.io.IOException;
 import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
 import java.nio.file.Path;
-import java.util.ArrayList;
 import java.util.List;
-import java.util.stream.Collectors;
 
-public class Main {
+public class SnowCompiler {
     public static void main(String[] args) throws IOException {
         // 读取源文件
         String source = Files.readString(Path.of(args[0]), StandardCharsets.UTF_8);
diff --git a/src/main/java/org/jcnc/snow/compiler/lexer/TokenScanner.java b/src/main/java/org/jcnc/snow/compiler/lexer/base/TokenScanner.java
similarity index 91%
rename from src/main/java/org/jcnc/snow/compiler/lexer/TokenScanner.java
rename to src/main/java/org/jcnc/snow/compiler/lexer/base/TokenScanner.java
index 913afad..e5f369b 100644
--- a/src/main/java/org/jcnc/snow/compiler/lexer/TokenScanner.java
+++ b/src/main/java/org/jcnc/snow/compiler/lexer/base/TokenScanner.java
@@ -1,5 +1,6 @@
-package org.jcnc.snow.compiler.lexer;
+package org.jcnc.snow.compiler.lexer.base;
 
+import org.jcnc.snow.compiler.lexer.core.LexerContext;
 import org.jcnc.snow.compiler.lexer.token.Token;
 
 import java.util.List;
diff --git a/src/main/java/org/jcnc/snow/compiler/lexer/LexerContext.java b/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerContext.java
similarity index 95%
rename from src/main/java/org/jcnc/snow/compiler/lexer/LexerContext.java
rename to src/main/java/org/jcnc/snow/compiler/lexer/core/LexerContext.java
index 2f3356b..d0491a7 100644
--- a/src/main/java/org/jcnc/snow/compiler/lexer/LexerContext.java
+++ b/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerContext.java
@@ -1,10 +1,12 @@
-package org.jcnc.snow.compiler.lexer;
+package org.jcnc.snow.compiler.lexer.core;
+
+import org.jcnc.snow.compiler.lexer.base.TokenScanner;
 
 /**
  * {@code LexerContext} 是词法分析中的状态管理器，负责追踪当前字符位置、
  * 行号、列号，并提供字符读取、匹配等功能。
  * <p>
- * 它是 {@link LexerEngine} 和 {@link org.jcnc.snow.compiler.lexer.TokenScanner}
+ * 它是 {@link LexerEngine} 和 {@link TokenScanner}
  * 之间共享的上下文对象，用于读取字符并记录位置信息。
  */
 public class LexerContext {
diff --git a/src/main/java/org/jcnc/snow/compiler/lexer/LexerEngine.java b/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java
similarity index 96%
rename from src/main/java/org/jcnc/snow/compiler/lexer/LexerEngine.java
rename to src/main/java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java
index f39d564..8f586fd 100644
--- a/src/main/java/org/jcnc/snow/compiler/lexer/LexerEngine.java
+++ b/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java
@@ -1,5 +1,6 @@
-package org.jcnc.snow.compiler.lexer;
+package org.jcnc.snow.compiler.lexer.core;
 
+import org.jcnc.snow.compiler.lexer.base.TokenScanner;
 import org.jcnc.snow.compiler.lexer.scanners.*;
 import org.jcnc.snow.compiler.lexer.token.Token;
 
diff --git a/src/main/java/org/jcnc/snow/compiler/lexer/doc/README.md b/src/main/java/org/jcnc/snow/compiler/lexer/doc/README.md
index 0fa4261..38cee87 100644
--- a/src/main/java/org/jcnc/snow/compiler/lexer/doc/README.md
+++ b/src/main/java/org/jcnc/snow/compiler/lexer/doc/README.md
@@ -1,42 +1,51 @@
 # Snow Compiler - Lexer 模块
 
-🎯 这是 `Snow Compiler` 项目的词法分析模块，负责将源代码解析为一系列结构化的 Token，为后续的语法分析（Parser）或解释器（Interpreter）做准备。
+> Snow 编译器的前端模块 —— 负责将源代码扫描并生成 Token 流
 
----
+## 项目简介
 
-## 🧠 核心模块职责
+**Lexer** 是 [Snow 编译器]() 项目的子模块，承担编译器前端的词法分析阶段任务。  
+它负责将源代码输入，根据 Snow 语言的语法规则，识别并划分为有意义的 Token 流，为后续语法解析（Parser）提供标准输入。
 
-| 模块                   | 说明                                                  |
-|----------------------|-----------------------------------------------------|
-| `LexerEngine`        | 主引擎，接收字符流，分发给各个 `TokenScanner` 处理                   |
-| `LexerContext`       | 封装源码字符流和当前扫描状态（如 `peek()`、`advance()`）              |
-| `TokenScanner`       | 扫描器接口，所有扫描器需实现该接口进行识别与处理                            |
-| `scanners/`          | 各类扫描器实现                                             |
-| `token/`             | Token 结构、类型定义、工厂方法                                  |
-| `utils/TokenPrinter` | Token 输出辅助类，格式化打印 Token 序列                          |
+该模块采用模块化设计，每类 Token 类型（如标识符、运算符、数字、字符串等）由独立的扫描器（Scanner）负责识别，提高了扩展性和可维护性。
 
----
+## 核心功能
 
-## 🔍 支持的 Token 类型
+- **词法分析引擎**：从源代码提取标准化 Token 流
+- **模块化扫描器体系**：按需扩展不同类型的 Token 识别
+- **灵活的上下文管理**：跟踪源代码位置，支持错误处理
+- **统一的 Token 工厂**：集中创建 Token 实例
+- **工具支持**：Token 打印与调试辅助
 
-- 标识符（变量名、函数名）
-- 数字（整数、小数）
-- 字符串（支持转义）
-- 注释（单行、多行）
-- 运算符（==, !=, &&, ||, <, >= 等）
-- 符号（: , . + - * ( )）
-- 换行符
-- 空白符（自动跳过）
-- 未知字符（捕获非法或暂不支持的符号）
+## 模块结构
 
----
+```
+lexer/
+  ├── base/               // 公共基础接口
+  ├── core/               // 词法分析核心引擎与上下文
+  ├── scanners/           // 各类 Token 扫描器
+  ├── token/              // Token 定义、工厂与类型
+  ├── utils/              // 辅助工具（如 Token 打印）
+  └── doc/                // 项目文档
+```
 
-## 🚀 示例：使用 LexerEngine 分析源码
+## 快速上手
 
-```java
-String code = "let x = 42;\nprint(\"hello\")";
-LexerEngine lexer = new LexerEngine();
-List<Token> tokens = lexer.tokenize(code);
+```
+// 1. 创建词法分析引擎实例
+LexerEngine engine = new LexerEngine();
 
-// 输出 token 流
+// 2. 提供源代码输入
+String sourceCode = "let x = 5 + 3;";
+
+// 3. 执行分析，生成 Token 流
+List<Token> tokens = engine.tokenize(sourceCode);
+
+// 4. 可选：打印 Token 列表，便于调试
 TokenPrinter.print(tokens);
+```
+
+## 开发环境
+
+- JDK 21 或更高版本
+- 建议使用 Maven 进行构建管理
diff --git a/src/main/java/org/jcnc/snow/compiler/lexer/scanners/AbstractTokenScanner.java b/src/main/java/org/jcnc/snow/compiler/lexer/scanners/AbstractTokenScanner.java
index 10c2c04..4d8c2ea 100644
--- a/src/main/java/org/jcnc/snow/compiler/lexer/scanners/AbstractTokenScanner.java
+++ b/src/main/java/org/jcnc/snow/compiler/lexer/scanners/AbstractTokenScanner.java
@@ -1,7 +1,7 @@
 package org.jcnc.snow.compiler.lexer.scanners;
 
-import org.jcnc.snow.compiler.lexer.LexerContext;
-import org.jcnc.snow.compiler.lexer.TokenScanner;
+import org.jcnc.snow.compiler.lexer.core.LexerContext;
+import org.jcnc.snow.compiler.lexer.base.TokenScanner;
 import org.jcnc.snow.compiler.lexer.token.Token;
 
 import java.util.List;
diff --git a/src/main/java/org/jcnc/snow/compiler/lexer/scanners/CommentTokenScanner.java b/src/main/java/org/jcnc/snow/compiler/lexer/scanners/CommentTokenScanner.java
index 5933313..a8a3313 100644
--- a/src/main/java/org/jcnc/snow/compiler/lexer/scanners/CommentTokenScanner.java
+++ b/src/main/java/org/jcnc/snow/compiler/lexer/scanners/CommentTokenScanner.java
@@ -1,6 +1,6 @@
 package org.jcnc.snow.compiler.lexer.scanners;
 
-import org.jcnc.snow.compiler.lexer.LexerContext;
+import org.jcnc.snow.compiler.lexer.core.LexerContext;
 import org.jcnc.snow.compiler.lexer.token.Token;
 import org.jcnc.snow.compiler.lexer.token.TokenType;
 
diff --git a/src/main/java/org/jcnc/snow/compiler/lexer/scanners/IdentifierTokenScanner.java b/src/main/java/org/jcnc/snow/compiler/lexer/scanners/IdentifierTokenScanner.java
index 4eb119a..633d834 100644
--- a/src/main/java/org/jcnc/snow/compiler/lexer/scanners/IdentifierTokenScanner.java
+++ b/src/main/java/org/jcnc/snow/compiler/lexer/scanners/IdentifierTokenScanner.java
@@ -1,6 +1,6 @@
 package org.jcnc.snow.compiler.lexer.scanners;
 
-import org.jcnc.snow.compiler.lexer.LexerContext;
+import org.jcnc.snow.compiler.lexer.core.LexerContext;
 import org.jcnc.snow.compiler.lexer.token.Token;
 import org.jcnc.snow.compiler.lexer.token.TokenFactory;
 
diff --git a/src/main/java/org/jcnc/snow/compiler/lexer/scanners/NewlineTokenScanner.java b/src/main/java/org/jcnc/snow/compiler/lexer/scanners/NewlineTokenScanner.java
index 1481c9f..daea57c 100644
--- a/src/main/java/org/jcnc/snow/compiler/lexer/scanners/NewlineTokenScanner.java
+++ b/src/main/java/org/jcnc/snow/compiler/lexer/scanners/NewlineTokenScanner.java
@@ -1,6 +1,6 @@
 package org.jcnc.snow.compiler.lexer.scanners;
 
-import org.jcnc.snow.compiler.lexer.LexerContext;
+import org.jcnc.snow.compiler.lexer.core.LexerContext;
 import org.jcnc.snow.compiler.lexer.token.Token;
 import org.jcnc.snow.compiler.lexer.token.TokenType;
 
diff --git a/src/main/java/org/jcnc/snow/compiler/lexer/scanners/NumberTokenScanner.java b/src/main/java/org/jcnc/snow/compiler/lexer/scanners/NumberTokenScanner.java
index 17d9b6d..859b848 100644
--- a/src/main/java/org/jcnc/snow/compiler/lexer/scanners/NumberTokenScanner.java
+++ b/src/main/java/org/jcnc/snow/compiler/lexer/scanners/NumberTokenScanner.java
@@ -1,6 +1,6 @@
 package org.jcnc.snow.compiler.lexer.scanners;
 
-import org.jcnc.snow.compiler.lexer.LexerContext;
+import org.jcnc.snow.compiler.lexer.core.LexerContext;
 import org.jcnc.snow.compiler.lexer.token.Token;
 import org.jcnc.snow.compiler.lexer.token.TokenType;
 
diff --git a/src/main/java/org/jcnc/snow/compiler/lexer/scanners/OperatorTokenScanner.java b/src/main/java/org/jcnc/snow/compiler/lexer/scanners/OperatorTokenScanner.java
index 373bd94..6b8dde9 100644
--- a/src/main/java/org/jcnc/snow/compiler/lexer/scanners/OperatorTokenScanner.java
+++ b/src/main/java/org/jcnc/snow/compiler/lexer/scanners/OperatorTokenScanner.java
@@ -1,6 +1,6 @@
 package org.jcnc.snow.compiler.lexer.scanners;
 
-import org.jcnc.snow.compiler.lexer.LexerContext;
+import org.jcnc.snow.compiler.lexer.core.LexerContext;
 import org.jcnc.snow.compiler.lexer.token.Token;
 import org.jcnc.snow.compiler.lexer.token.TokenType;
 
diff --git a/src/main/java/org/jcnc/snow/compiler/lexer/scanners/StringTokenScanner.java b/src/main/java/org/jcnc/snow/compiler/lexer/scanners/StringTokenScanner.java
index 5a80e57..a8643e4 100644
--- a/src/main/java/org/jcnc/snow/compiler/lexer/scanners/StringTokenScanner.java
+++ b/src/main/java/org/jcnc/snow/compiler/lexer/scanners/StringTokenScanner.java
@@ -1,6 +1,6 @@
 package org.jcnc.snow.compiler.lexer.scanners;
 
-import org.jcnc.snow.compiler.lexer.LexerContext;
+import org.jcnc.snow.compiler.lexer.core.LexerContext;
 import org.jcnc.snow.compiler.lexer.token.Token;
 import org.jcnc.snow.compiler.lexer.token.TokenType;
 
diff --git a/src/main/java/org/jcnc/snow/compiler/lexer/scanners/SymbolTokenScanner.java b/src/main/java/org/jcnc/snow/compiler/lexer/scanners/SymbolTokenScanner.java
index 27a0516..eb2718d 100644
--- a/src/main/java/org/jcnc/snow/compiler/lexer/scanners/SymbolTokenScanner.java
+++ b/src/main/java/org/jcnc/snow/compiler/lexer/scanners/SymbolTokenScanner.java
@@ -1,6 +1,6 @@
 package org.jcnc.snow.compiler.lexer.scanners;
 
-import org.jcnc.snow.compiler.lexer.LexerContext;
+import org.jcnc.snow.compiler.lexer.core.LexerContext;
 import org.jcnc.snow.compiler.lexer.token.Token;
 import org.jcnc.snow.compiler.lexer.token.TokenType;
 
diff --git a/src/main/java/org/jcnc/snow/compiler/lexer/scanners/UnknownTokenScanner.java b/src/main/java/org/jcnc/snow/compiler/lexer/scanners/UnknownTokenScanner.java
index 2f4e5cd..31c4e8a 100644
--- a/src/main/java/org/jcnc/snow/compiler/lexer/scanners/UnknownTokenScanner.java
+++ b/src/main/java/org/jcnc/snow/compiler/lexer/scanners/UnknownTokenScanner.java
@@ -1,6 +1,6 @@
 package org.jcnc.snow.compiler.lexer.scanners;
 
-import org.jcnc.snow.compiler.lexer.LexerContext;
+import org.jcnc.snow.compiler.lexer.core.LexerContext;
 import org.jcnc.snow.compiler.lexer.token.Token;
 import org.jcnc.snow.compiler.lexer.token.TokenType;
 
diff --git a/src/main/java/org/jcnc/snow/compiler/lexer/scanners/WhitespaceTokenScanner.java b/src/main/java/org/jcnc/snow/compiler/lexer/scanners/WhitespaceTokenScanner.java
index 9b6e318..36c9768 100644
--- a/src/main/java/org/jcnc/snow/compiler/lexer/scanners/WhitespaceTokenScanner.java
+++ b/src/main/java/org/jcnc/snow/compiler/lexer/scanners/WhitespaceTokenScanner.java
@@ -1,6 +1,6 @@
 package org.jcnc.snow.compiler.lexer.scanners;
 
-import org.jcnc.snow.compiler.lexer.LexerContext;
+import org.jcnc.snow.compiler.lexer.core.LexerContext;
 import org.jcnc.snow.compiler.lexer.token.Token;
 
 /**
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/doc/README.md b/src/main/java/org/jcnc/snow/compiler/parser/doc/README.md
new file mode 100644
index 0000000..f3d2bea
--- /dev/null
+++ b/src/main/java/org/jcnc/snow/compiler/parser/doc/README.md
@@ -0,0 +1,59 @@
+# Snow Compiler - Parser 模块
+
+> Snow 编译器的前端模块 —— 负责将 Token 流解析为抽象语法树（AST）
+
+## 项目简介
+
+**Parser** 是 [Snow 编译器]() 项目的子模块，承担编译器前端的解析阶段任务。  
+它负责将词法分析得到的 Token 流，按照 Snow 语言的语法规则，解析为标准的抽象语法树（AST）。
+
+框架使用了 Pratt 解析算法处理表达式，同时采用模块化设计，支持声明、函数、条件语句、循环语句等各类结构的解析。
+
+## 核心功能
+
+- **抽象语法树（AST）生成**：定义丰富的 AST 节点类型
+- **表达式解析器**：基于 Pratt 解析，支持优先级、调用、成员访问等
+- **语句解析器**：支持 Snow 语言中的声明、控制流等
+- **模块解析器**：处理 `import` 导入声明
+- **函数解析器**：支持函数定义与调用
+- **灵活的解析上下文管理**：错误处理与流式 Token 管理
+- **工具支持**：AST JSON 序列化，便于调试与前后端通信
+
+## 模块结构
+
+```
+parser/
+  ├── ast/                // AST 节点定义
+  ├── base/               // 顶层解析器接口
+  ├── context/            // 解析上下文与异常处理
+  ├── core/               // 核心解析引擎
+  ├── expression/         // 表达式解析模块
+  ├── factory/            // 解析器工厂
+  ├── function/           // 函数解析及 AST 打印
+  ├── module/             // 模块导入解析
+  ├── statement/          // 各类语句解析器
+  └── utils/              // JSON 序列化、辅助方法
+```
+
+## 快速上手
+
+```
+// 1. 创建解析引擎实例
+ParserEngine engine = new ParserEngine();
+
+// 2. 准备 Token 流（通常由词法分析器生成）
+TokenStream tokenStream = ...; 
+
+// 3. 执行解析，生成 AST
+ModuleNode ast = engine.parse(tokenStream);
+
+// 4. 可选：将 AST 序列化为 JSON 格式，便于调试
+String astJson = ASTJsonSerializer.serialize(ast);
+System.out.println(astJson);
+```
+
+## 开发环境
+
+- JDK 21 或更高版本
+- 建议使用 Maven 进行构建管理
+
diff --git a/src/main/java/org/jcnc/snow/compiler/semantic/doc/README.md b/src/main/java/org/jcnc/snow/compiler/semantic/doc/README.md
new file mode 100644
index 0000000..ccb57e0
--- /dev/null
+++ b/src/main/java/org/jcnc/snow/compiler/semantic/doc/README.md
@@ -0,0 +1,56 @@
+# Snow Compiler - Semantic 模块
+
+> Snow 编译器的前端模块 —— 负责语义分析与符号表管理
+
+## 项目简介
+
+**Semantic** 是 [Snow 编译器]() 项目的子模块，承担编译器前端的语义分析阶段任务。  
+它负责在抽象语法树（AST）基础上，进行符号绑定、类型检查、作用域管理等操作，确保程序符合语义规则，并为后续中间代码生成（IR）阶段提供准备。
+
+该模块采用模块化设计，针对不同类型的表达式与语句提供独立的分析器，同时内置完整的符号表和类型系统支持。
+
+## 核心功能
+
+- **表达式与语句语义分析**：根据 Snow 语言规范校验各类 AST 节点
+- **符号表管理**：支持作用域嵌套、符号绑定与查找
+- **类型系统**：内建基础类型与函数类型推导
+- **语义错误报告**：标准化错误收集与输出
+- **可扩展的分析器体系**：按节点类型组织，便于维护与扩展
+
+## 模块结构
+
+```
+semantic/
+  ├── analyzers/          // 各类表达式和语句分析器
+  │    ├── base/          // 基础分析器接口
+  │    ├── expression/    // 表达式分析器
+  │    └── statement/     // 语句分析器
+  ├── core/               // 核心分析引擎与上下文管理
+  ├── error/              // 语义错误定义
+  ├── symbol/             // 符号表系统
+  ├── type/               // 类型系统
+  └── utils/              // 辅助工具
+```
+
+## 快速上手
+
+```
+// 1. 创建语义分析引擎实例
+SemanticAnalyzerRunner runner = new SemanticAnalyzerRunner();
+
+// 2. 准备待分析的 AST（通常由 Parser 生成）
+ModuleNode ast = ...;
+
+// 3. 执行语义分析
+runner.analyze(ast);
+
+// 4. 可选：检查并输出语义分析报告
+SemanticAnalysisReporter.report(runner.getErrors());
+```
+
+## 开发环境
+
+- JDK 21 或更高版本
+- 建议使用 Maven 进行构建管理
+
+---
\ No newline at end of file