From 22c7ec46f88180bc9a6d193e4656fd906ebb1ca8 Mon Sep 17 00:00:00 2001
From: zhangxun <1958638841@qq.com>
Date: Sat, 28 Jun 2025 10:20:11 +0800
Subject: [PATCH 01/37] =?UTF-8?q?style:=20TokenStream.isAtEnd=20=E8=BF=94?=
 =?UTF-8?q?=E5=9B=9E=E5=80=BC=E7=AC=A6=E5=90=88=E6=96=87=E6=A1=A3=E8=AF=B4?=
 =?UTF-8?q?=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../org/jcnc/snow/compiler/parser/context/TokenStream.java  | 2 +-
 .../org/jcnc/snow/compiler/parser/core/ParserEngine.java    | 6 +++---
 .../compiler/parser/expression/PrattExpressionParser.java   | 2 +-
 3 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/main/java/org/jcnc/snow/compiler/parser/context/TokenStream.java b/src/main/java/org/jcnc/snow/compiler/parser/context/TokenStream.java
index 5841b7b..2788300 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/context/TokenStream.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/context/TokenStream.java
@@ -120,7 +120,7 @@ public class TokenStream {
      * @return 若当前位置 Token 为 EOF，则返回 true，否则 false
      */
     public boolean isAtEnd() {
-        return peek().getType() != TokenType.EOF;
+        return peek().getType() == TokenType.EOF;
     }
 
 
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/core/ParserEngine.java b/src/main/java/org/jcnc/snow/compiler/parser/core/ParserEngine.java
index 7d0854f..14dc783 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/core/ParserEngine.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/core/ParserEngine.java
@@ -17,7 +17,7 @@ public record ParserEngine(ParserContext ctx) {
         List<String> errs = new ArrayList<>();
         TokenStream ts = ctx.getTokens();
 
-        while (ts.isAtEnd()) {
+        while (!ts.isAtEnd()) {
             // 跳过空行
             if (ts.peek().getType() == TokenType.NEWLINE) {
                 ts.next();
@@ -46,7 +46,7 @@ public record ParserEngine(ParserContext ctx) {
      * 错误同步：跳到下一行或下一个已注册顶层关键字
      */
     private void synchronize(TokenStream ts) {
-        while (ts.isAtEnd()) {
+        while (!ts.isAtEnd()) {
             if (ts.peek().getType() == TokenType.NEWLINE) {
                 ts.next();
                 break;
@@ -57,7 +57,7 @@ public record ParserEngine(ParserContext ctx) {
             ts.next();
         }
         // 连续空行全部吃掉
-        while (ts.isAtEnd() && ts.peek().getType() == TokenType.NEWLINE) {
+        while (!ts.isAtEnd() && ts.peek().getType() == TokenType.NEWLINE) {
             ts.next();
         }
     }
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/expression/PrattExpressionParser.java b/src/main/java/org/jcnc/snow/compiler/parser/expression/PrattExpressionParser.java
index 4f79274..c5529d4 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/expression/PrattExpressionParser.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/expression/PrattExpressionParser.java
@@ -92,7 +92,7 @@ public class PrattExpressionParser implements ExpressionParser {
 
         ExpressionNode left = prefix.parse(ctx, token);
 
-        while (ctx.getTokens().isAtEnd()
+        while (!ctx.getTokens().isAtEnd()
                 && prec.ordinal() < nextPrecedence(ctx)) {
             String lex = ctx.getTokens().peek().getLexeme();
             InfixParselet infix = infixes.get(lex);

From 0d8e26d2cceb284cf99fd169238f595bcc1d7c55 Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Sun, 29 Jun 2025 18:23:58 +0800
Subject: [PATCH 02/37] =?UTF-8?q?chore:=20=E5=A2=9E=E5=8A=A0=20Demo11=20?=
 =?UTF-8?q?=E9=85=8D=E7=BD=AE=E6=96=87=E4=BB=B6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .run/Demo11.run.xml | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)
 create mode 100644 .run/Demo11.run.xml

diff --git a/.run/Demo11.run.xml b/.run/Demo11.run.xml
new file mode 100644
index 0000000..e6748fb
--- /dev/null
+++ b/.run/Demo11.run.xml
@@ -0,0 +1,17 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="Demo11" type="Application" factoryName="Application" folderName="Demo" activateToolWindowBeforeRun="false">
+    <option name="ALTERNATIVE_JRE_PATH" value="graalvm-ce-23" />
+    <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
+    <module name="Snow" />
+    <option name="PROGRAM_PARAMETERS" value="compile run -d playground/Demo11 -o target/Demo11" />
+    <extension name="coverage">
+      <pattern>
+        <option name="PATTERN" value="org.jcnc.snow.compiler.parser.preprocessor.lexer.impl.api.*" />
+        <option name="ENABLED" value="true" />
+      </pattern>
+    </extension>
+    <method v="2">
+      <option name="Make" enabled="true" />
+    </method>
+  </configuration>
+</component>
\ No newline at end of file

From 5e0d31f3adc325e701664e28d10ee3a3d998d138 Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Sun, 29 Jun 2025 18:24:34 +0800
Subject: [PATCH 03/37] =?UTF-8?q?test:=20=E5=A2=9E=E5=8A=A0=20Bug1=20?=
 =?UTF-8?q?=E8=87=B3=20BugFarm?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 playground/BugFarm/Bug1/Main.snow |  7 +++++++
 playground/BugFarm/Bug1/README.md | 12 ++++++++++++
 playground/Demo11/Main.snow       |  7 +++++++
 3 files changed, 26 insertions(+)
 create mode 100644 playground/BugFarm/Bug1/Main.snow
 create mode 100644 playground/BugFarm/Bug1/README.md
 create mode 100644 playground/Demo11/Main.snow

diff --git a/playground/BugFarm/Bug1/Main.snow b/playground/BugFarm/Bug1/Main.snow
new file mode 100644
index 0000000..d9a3e6e
--- /dev/null
+++ b/playground/BugFarm/Bug1/Main.snow
@@ -0,0 +1,7 @@
+function: main
+    return_type: int
+    body:
+        3 L
+        return 65537
+    end body
+end function
\ No newline at end of file
diff --git a/playground/BugFarm/Bug1/README.md b/playground/BugFarm/Bug1/README.md
new file mode 100644
index 0000000..b34d14d
--- /dev/null
+++ b/playground/BugFarm/Bug1/README.md
@@ -0,0 +1,12 @@
+## 编译器输出
+### Snow 源代码
+#### Main.snow
+```snow
+function: main
+    return_type: int
+    body:
+        3 L
+        return 65537
+    end body
+end function
+```
\ No newline at end of file
diff --git a/playground/Demo11/Main.snow b/playground/Demo11/Main.snow
new file mode 100644
index 0000000..d9a3e6e
--- /dev/null
+++ b/playground/Demo11/Main.snow
@@ -0,0 +1,7 @@
+function: main
+    return_type: int
+    body:
+        3 L
+        return 65537
+    end body
+end function
\ No newline at end of file

From cb4faf0632fb351d4b8dca7fd29fdaa204462cf6 Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Sun, 29 Jun 2025 18:28:43 +0800
Subject: [PATCH 04/37] =?UTF-8?q?chore:=20=E5=A2=9E=E5=8A=A0=20Bug1=20?=
 =?UTF-8?q?=E9=85=8D=E7=BD=AE=E6=96=87=E4=BB=B6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .run/Bug1.run.xml  | 17 +++++++++++++++++
 .run/Demo1.run.xml |  2 +-
 2 files changed, 18 insertions(+), 1 deletion(-)
 create mode 100644 .run/Bug1.run.xml

diff --git a/.run/Bug1.run.xml b/.run/Bug1.run.xml
new file mode 100644
index 0000000..46f5bc6
--- /dev/null
+++ b/.run/Bug1.run.xml
@@ -0,0 +1,17 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="Bug1" type="Application" factoryName="Application" folderName="BugFarm" activateToolWindowBeforeRun="false">
+    <option name="ALTERNATIVE_JRE_PATH" value="graalvm-ce-23" />
+    <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
+    <module name="Snow" />
+    <option name="PROGRAM_PARAMETERS" value="compile run -d playground/BugFarm/Bug1 -o target/Bug1" />
+    <extension name="coverage">
+      <pattern>
+        <option name="PATTERN" value="org.jcnc.snow.compiler.parser.preprocessor.lexer.impl.api.*" />
+        <option name="ENABLED" value="true" />
+      </pattern>
+    </extension>
+    <method v="2">
+      <option name="Make" enabled="true" />
+    </method>
+  </configuration>
+</component>
\ No newline at end of file
diff --git a/.run/Demo1.run.xml b/.run/Demo1.run.xml
index 867e2f7..55005c8 100644
--- a/.run/Demo1.run.xml
+++ b/.run/Demo1.run.xml
@@ -3,7 +3,7 @@
     <option name="ALTERNATIVE_JRE_PATH" value="graalvm-ce-23" />
     <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
     <module name="Snow" />
-    <option name="PROGRAM_PARAMETERS" value="compile run -d playground/Demo1" />
+    <option name="PROGRAM_PARAMETERS" value="compile run -d playground/Demo1 -o target/Demo1" />
     <extension name="coverage">
       <pattern>
         <option name="PATTERN" value="org.jcnc.snow.compiler.parser.preprocessor.lexer.impl.api.*" />

From 6a247f456c603d11367b42119272c22f77baa62a Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Sun, 29 Jun 2025 23:56:21 +0800
Subject: [PATCH 05/37] =?UTF-8?q?feat:=20NumberTokenScanner=20=E5=A2=9E?=
 =?UTF-8?q?=E5=8A=A0=E8=A7=84=E5=88=99=E7=BA=A6=E6=9D=9F?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../compiler/lexer/core/LexerContext.java     | 107 ++++++++-------
 .../lexer/scanners/NumberTokenScanner.java    | 124 ++++++++++--------
 2 files changed, 130 insertions(+), 101 deletions(-)

diff --git a/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerContext.java b/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerContext.java
index dbfe62f..4462fca 100644
--- a/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerContext.java
+++ b/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerContext.java
@@ -3,60 +3,72 @@ package org.jcnc.snow.compiler.lexer.core;
 import org.jcnc.snow.compiler.lexer.base.TokenScanner;
 
 /**
- * {@code LexerContext} 是词法分析阶段的上下文状态管理器。
+ * {@code LexerContext} —— 词法分析阶段的上下文状态管理器。<br>
  * <p>
- * 该类提供对源代码字符流的读取访问，追踪当前行号与列号，
- * 并支持字符匹配、回看与指针推进等操作，是 {@link TokenScanner} 实现进行词法识别的重要支撑工具。
+ * 提供对源代码字符流的读取访问、行列号追踪、指针推进与字符匹配等操作，
+ * 是 {@link TokenScanner} 实现进行词法识别的基础设施。
  * </p>
  * <p>
- * 所有源代码输入在构造时统一将 Windows 风格的换行符（\r\n）转换为 Unix 风格（\n），
- * 保证换行行为一致性。
+ * 设计要点：
+ * <ul>
+ *     <li>构造时统一将 Windows 换行符 (<code>\r\n</code>) 转换为 Unix 风格 (<code>\n</code>)。</li>
+ *     <li>所有坐标均以 <strong>1</strong> 为起始行／列号，更贴合人类直觉。</li>
+ *     <li>提供 {@link #peekAhead(int)} 方法以支持“向前多字符查看”而不移动游标。</li>
+ * </ul>
  * </p>
  */
 public class LexerContext {
 
-    /** 源代码字符串，换行符已标准化为 \n */
+    /* ───────────────────────────────── 私有字段 ───────────────────────────────── */
+
+    /** 源代码字符串（换行符已标准化为 \n） */
     private final String source;
 
-    /** 当前扫描位置（从 0 开始的偏移） */
+    /** 当前扫描位置（自 0 起算的全局偏移量） */
     private int pos = 0;
 
-    /** 当前行号，从 1 开始 */
+    /** 当前行号（从 1 开始） */
     private int line = 1;
 
-    /** 当前列号，从 1 开始 */
+    /** 当前列号（从 1 开始） */
     private int col = 1;
 
-    /** 上一个字符对应的列号（用于位置精确记录） */
+    /** 上一个字符对应的列号（用于异常定位） */
     private int lastCol = 1;
 
+    /* ──────────────────────────────── 构造 & 基本信息 ─────────────────────────────── */
+
     /**
-     * 构造一个新的 {@code LexerContext} 实例，并标准化换行符。
+     * 创建新的 {@code LexerContext}，并完成换行符标准化。
      *
-     * @param source 原始源代码字符串
+     * @param rawSource 原始源代码文本
      */
-    public LexerContext(String source) {
-        this.source = source.replace("\r\n", "\n");
+    public LexerContext(String rawSource) {
+        this.source = rawSource.replace("\r\n", "\n");
     }
 
     /**
-     * 判断是否已读取到源代码末尾。
+     * 判断是否已到达源代码结尾。
      *
-     * @return 若已结束，返回 {@code true}；否则返回 {@code false}
+     * @return 若游标位于终点之后返回 {@code true}
      */
     public boolean isAtEnd() {
         return pos >= source.length();
     }
 
+    /* ──────────────────────────────── 指针推进与查看 ─────────────────────────────── */
+
     /**
-     * 消费当前字符并前进一个位置，自动更新行列信息。
+     * 消费 <em>当前</em> 字符并前进一个位置，同时更新行列号。
      *
-     * @return 当前字符，若已结束则返回空字符（'\0'）
+     * @return 被消费的字符；若已结束则返回空字符 {@code '\0'}
      */
     public char advance() {
         if (isAtEnd()) return '\0';
+
         char c = source.charAt(pos++);
         lastCol = col;
+
         if (c == '\n') {
             line++;
             col = 1;
@@ -67,9 +79,9 @@ public class LexerContext {
     }
 
     /**
-     * 查看当前位置的字符，但不前进。
+     * 查看当前位置字符，但不移动游标。
      *
-     * @return 当前字符，若结束则返回空字符
+     * @return 当前字符；若越界则返回 {@code '\0'}
      */
     public char peek() {
         return isAtEnd() ? '\0' : source.charAt(pos);
@@ -78,17 +90,29 @@ public class LexerContext {
     /**
      * 查看下一个字符，但不改变位置。
      *
-     * @return 下一个字符，若结束则返回空字符
+     * @return 下一字符；若越界则返回 {@code '\0'}
      */
     public char peekNext() {
         return pos + 1 >= source.length() ? '\0' : source.charAt(pos + 1);
     }
 
     /**
-     * 若当前字符与期望字符相同，则前进并返回 {@code true}，否则不动并返回 {@code false}。
+     * 向前查看 <em>offset</em> 个字符（不移动游标）。offset=1 等价于 {@link #peekNext()}。
      *
-     * @param expected 期待匹配的字符
-     * @return 是否匹配成功并消费
+     * @param offset 偏移量 (≥ 1)
+     * @return 指定偏移处的字符；若越界返回 {@code '\0'}
+     */
+    public char peekAhead(int offset) {
+        if (offset <= 0) return peek();
+        int idx = pos + offset;
+        return idx >= source.length() ? '\0' : source.charAt(idx);
+    }
+
+    /**
+     * 若当前位置字符等于 {@code expected}，则消费并返回 {@code true}；否则保持原位返回 {@code false}。
+     *
+     * @param expected 期望匹配的字符
+     * @return 是否匹配并消费
      */
     public boolean match(char expected) {
         if (isAtEnd() || source.charAt(pos) != expected) return false;
@@ -96,30 +120,17 @@ public class LexerContext {
         return true;
     }
 
-    /**
-     * 获取当前位置的行号。
-     *
-     * @return 当前行号（从 1 开始）
-     */
-    public int getLine() {
-        return line;
-    }
+    /* ──────────────────────────────── 坐标查询 ─────────────────────────────── */
 
-    /**
-     * 获取当前位置的列号。
-     *
-     * @return 当前列号（从 1 开始）
-     */
-    public int getCol() {
-        return col;
-    }
+    /** @return 当前行号 (1-based) */
+    public int getLine()    { return line; }
 
-    /**
-     * 获取上一个字符所在的列号。
-     *
-     * @return 上一个字符对应的列位置
-     */
-    public int getLastCol() {
-        return lastCol;
-    }
+    /** @return 当前列号 (1-based) */
+    public int getCol()     { return col;  }
+
+    /** @return 上一个字符的列号 */
+    public int getLastCol() { return lastCol; }
+
+    /** @return 当前指针在源文件中的全局偏移 (0-based) */
+    public int getPos()     { return pos;  }
 }
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 517509f..ac598de 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,92 +1,110 @@
 package org.jcnc.snow.compiler.lexer.scanners;
 
 import org.jcnc.snow.compiler.lexer.core.LexerContext;
+import org.jcnc.snow.compiler.lexer.core.LexicalException;
 import org.jcnc.snow.compiler.lexer.token.Token;
 import org.jcnc.snow.compiler.lexer.token.TokenType;
 
 /**
- * 数字扫描器：识别整数、小数以及带有<strong>类型后缀</strong>的数字字面量。
+ * 数字扫描器：识别整数、小数以及带有 <strong>类型后缀</strong> 的数字字面量。<br>
  * <p>
- * 支持的格式示例：
+ * 支持格式示例：
  * <ul>
- *     <li>整数：123、0、45678</li>
- *     <li>小数：3.14、0.5、12.0</li>
- *     <li>带类型后缀：2.0f、42L、7s、255B</li>
+ *     <li>整数：<code>123</code>、<code>0</code>、<code>45678</code></li>
+ *     <li>小数：<code>3.14</code>、<code>0.5</code>、<code>12.0</code></li>
+ *     <li>带后缀：<code>2.0f</code>、<code>42L</code>、<code>7s</code>、<code>255B</code></li>
  * </ul>
+ * </p>
  * <p>
- * 语法允许在数字 (整数或小数) 末尾添加以下<strong>单字符后缀</strong>来显式指定常量类型：
- * <pre>b | s | l | f | d   // 分别对应 byte、short、long、float、double
- * B | S | L | F | D   // 同上，大小写皆可</pre>
- * 生成的 Token 类型始终为 {@code NUMBER_LITERAL}，词法单元将携带完整的文本（含后缀，若存在）。
+ * 单字符类型后缀：
+ * <pre>
+ * b | s | l | f | d   // byte, short, long, float, double
+ * B | S | L | F | D   // 同上（大小写均可）
+ * </pre>
+ * </p>
+ * <p>
+ * 规则约束：<br>
+ * 若数字主体之后出现以下情况，将在词法阶段抛出 {@link LexicalException}：
+ * <ul>
+ *     <li>空白 + 字母（如 <code>3&nbsp;L</code>）</li>
+ *     <li>未知字母紧邻（如 <code>3E</code>）</li>
+ *     <li><code>'/'</code> 紧邻（如 <code>3/</code>、<code>3/*</code>）</li>
+ * </ul>
+ * 以避免编译器陷入死循环。
+ * </p>
  */
 public class NumberTokenScanner extends AbstractTokenScanner {
 
-    /**
-     * 可选类型后缀字符集合 (大小写均可)。
-     * 与 {@code ExpressionBuilder} 内的后缀解析逻辑保持一致。
-     */
+    /** 合法类型后缀字符集合 */
     private static final String SUFFIX_CHARS = "bslfdBSLFD";
 
-    /**
-     * 判断是否可以处理当前位置的字符。
-     * <p>当字符为数字时，表示可能是数字字面量的起始。</p>
-     *
-     * @param c   当前字符
-     * @param ctx 当前词法上下文
-     * @return 如果为数字字符，则返回 true
-     */
     @Override
     public boolean canHandle(char c, LexerContext ctx) {
         return Character.isDigit(c);
     }
 
-    /**
-     * 执行数字扫描逻辑。
-     * <ol>
-     *     <li>连续读取数字字符，允许出现<strong>一个</strong>小数点，用于识别整数或小数。</li>
-     *     <li>读取完主体后，<strong>一次性</strong>检查下一个字符，若属于合法类型后缀则吸收。</li>
-     * </ol>
-     * 这样可以保证诸如 {@code 2.0f} 被视为一个整体的 {@code NUMBER_LITERAL}，
-     * 而不是拆分成 "2.0" 与 "f" 两个 Token。
-     *
-     * @param ctx  词法上下文
-     * @param line 当前行号
-     * @param col  当前列号
-     * @return 表示数字字面量的 Token
-     */
     @Override
     protected Token scanToken(LexerContext ctx, int line, int col) {
-        StringBuilder sb = new StringBuilder();
-        boolean hasDot = false; // 标识是否已经遇到过小数点
+        StringBuilder literal = new StringBuilder();
+        boolean hasDot = false; // 是否已遇到小数点
 
-        /*
-         * 1️⃣ 扫描整数或小数主体
-         * 允许出现一个小数点，其余必须是数字。
-         */
+        /* 1. 读取数字主体（整数 / 小数） */
         while (!ctx.isAtEnd()) {
             char c = ctx.peek();
             if (c == '.' && !hasDot) {
                 hasDot = true;
-                sb.append(ctx.advance());
+                literal.append(ctx.advance());
             } else if (Character.isDigit(c)) {
-                sb.append(ctx.advance());
+                literal.append(ctx.advance());
             } else {
-                break; // 遇到非数字/第二个点 => 主体结束
+                break;
             }
         }
 
-        /*
-         * 2️⃣ 可选类型后缀
-         * 如果下一字符是合法后缀字母，则一起纳入当前 Token。
-         */
+        /* 2. 处理后缀或非法跟随字符 */
         if (!ctx.isAtEnd()) {
-            char suffix = ctx.peek();
-            if (SUFFIX_CHARS.indexOf(suffix) >= 0) {
-                sb.append(ctx.advance());
+            char next = ctx.peek();
+
+            /* 2-A: 合法类型后缀，直接吸收 */
+            if (SUFFIX_CHARS.indexOf(next) >= 0) {
+                literal.append(ctx.advance());
             }
+            /* 2-B: 未知字母紧邻 → 抛异常 */
+            else if (Character.isLetter(next)) {
+                throw new LexicalException(
+                        "Unknown numeric suffix '" + next + "'",
+                        line, col
+                );
+            }
+            /* 2-C: 数字后空白（非换行）→ 若空白后跟字母，抛异常 */
+            else if (Character.isWhitespace(next) && next != '\n') {
+                int off = 1;
+                char look;
+                do {
+                    look = ctx.peekAhead(off);
+                    if (look == '\n' || look == '\0') break;
+                    if (!Character.isWhitespace(look)) break;
+                    off++;
+                } while (true);
+
+                if (Character.isLetter(look)) {
+                    throw new LexicalException(
+                            "Whitespace between numeric literal and an alphabetic character is not allowed",
+                            line, col
+                    );
+                }
+            }
+            /* 2-D: 紧邻字符为 '/' → 抛异常以避免死循环 */
+            else if (next == '/') {
+                throw new LexicalException(
+                        "Unexpected '/' after numeric literal",
+                        line, col
+                );
+            }
+            /* 其余字符（运算符、分隔符等）留给后续扫描器处理 */
         }
 
-        // 构造并返回 NUMBER_LITERAL Token，文本内容形如 "123", "3.14f" 等。
-        return new Token(TokenType.NUMBER_LITERAL, sb.toString(), line, col);
+        /* 3. 返回 NUMBER_LITERAL Token */
+        return new Token(TokenType.NUMBER_LITERAL, literal.toString(), line, col);
     }
 }

From 3eacdf6d392c10c4a01d3d70375bb7c8fb93a2c4 Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Mon, 30 Jun 2025 16:21:01 +0800
Subject: [PATCH 06/37] =?UTF-8?q?fix:=20=E6=95=B0=E5=AD=97=E5=AD=97?=
 =?UTF-8?q?=E9=9D=A2=E9=87=8F=E4=B8=8E=E4=BD=8D=E5=AE=BD=E7=AC=A6=E5=8F=B7?=
 =?UTF-8?q?=E4=B9=8B=E9=97=B4=E4=B8=8D=E5=85=81=E8=AE=B8=E6=9C=89=E7=A9=BA?=
 =?UTF-8?q?=E7=99=BD=E7=AC=A6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 playground/BugFarm/Bug1/Main.snow             |  4 +-
 playground/Demo1/Math.snow                    |  4 +-
 src/main/java/org/jcnc/snow/cli/SnowCLI.java  |  2 +-
 .../snow/compiler/lexer/core/LexerEngine.java | 61 +++++++++++++++----
 .../compiler/lexer/core/LexicalError.java     | 20 ++++++
 .../compiler/lexer/core/LexicalException.java | 15 ++++-
 .../lexer/scanners/NumberTokenScanner.java    | 30 +++++----
 .../utils/SemanticAnalysisReporter.java       |  2 +-
 8 files changed, 106 insertions(+), 32 deletions(-)
 create mode 100644 src/main/java/org/jcnc/snow/compiler/lexer/core/LexicalError.java

diff --git a/playground/BugFarm/Bug1/Main.snow b/playground/BugFarm/Bug1/Main.snow
index d9a3e6e..3dae6e6 100644
--- a/playground/BugFarm/Bug1/Main.snow
+++ b/playground/BugFarm/Bug1/Main.snow
@@ -1,7 +1,7 @@
 function: main
     return_type: int
     body:
-        3 L
-        return 65537
+       declare num1 :int =  3.1 G
+       return 65537
     end body
 end function
\ No newline at end of file
diff --git a/playground/Demo1/Math.snow b/playground/Demo1/Math.snow
index bfe8605..973f7c9 100644
--- a/playground/Demo1/Math.snow
+++ b/playground/Demo1/Math.snow
@@ -1,8 +1,8 @@
 module: Math
     function: factorial
         parameter:
-            declare n1: long
-            declare n2: long
+            declare n1: int
+            declare n2: int
         return_type: long
         body:
            return n1+n2
diff --git a/src/main/java/org/jcnc/snow/cli/SnowCLI.java b/src/main/java/org/jcnc/snow/cli/SnowCLI.java
index 03a4391..0afa4e4 100644
--- a/src/main/java/org/jcnc/snow/cli/SnowCLI.java
+++ b/src/main/java/org/jcnc/snow/cli/SnowCLI.java
@@ -91,7 +91,7 @@ public class SnowCLI {
             System.exit(exitCode);
         } catch (Exception e) {
             // 捕获命令执行过程中的异常并打印错误消息
-            System.err.println("Error: " + e.getMessage());
+//            System.err.println("Error: " + e.getMessage());
             System.exit(1);
         }
     }
diff --git a/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java b/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java
index 4d06999..060d3c3 100644
--- a/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java
+++ b/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java
@@ -4,6 +4,7 @@ import org.jcnc.snow.compiler.lexer.base.TokenScanner;
 import org.jcnc.snow.compiler.lexer.scanners.*;
 import org.jcnc.snow.compiler.lexer.token.Token;
 
+import java.io.File;
 import java.util.ArrayList;
 import java.util.List;
 
@@ -24,6 +25,7 @@ public class LexerEngine {
      */
     private final List<Token> tokens = new ArrayList<>();
 
+    private final String absPath;
     /**
      * 词法上下文，提供字符流读取与位置信息
      */
@@ -34,6 +36,8 @@ public class LexerEngine {
      */
     private final List<TokenScanner> scanners;
 
+    private final List<LexicalError> errors = new ArrayList<>();
+
     /**
      * 构造词法分析器（假定输入源自标准输入，文件名默认为 <stdin>）
      *
@@ -43,6 +47,7 @@ public class LexerEngine {
         this(source, "<stdin>");
     }
 
+
     /**
      * 构造词法分析器，并指定源文件名（用于诊断信息）。
      * 构造时立即进行全量扫描。
@@ -51,6 +56,7 @@ public class LexerEngine {
      * @param sourceName 文件名或来源描述（如"Main.snow"）
      */
     public LexerEngine(String source, String sourceName) {
+        this.absPath = new File(sourceName).getAbsolutePath();
         this.context = new LexerContext(source);
         this.scanners = List.of(
                 new WhitespaceTokenScanner(), // 跳过空格、制表符等
@@ -68,15 +74,28 @@ public class LexerEngine {
         try {
             scanAllTokens();
         } catch (LexicalException le) {
-            // 输出：文件名:行:列: 错误信息，简洁明了
+            // 输出：绝对路径: 行 x, 列 y: 错误信息
             System.err.printf(
-                    "%s:%d:%d: %s%n",
-                    sourceName,
-                    le.getLine(),      // 获取出错行号
-                    le.getColumn(),    // 获取出错列号
-                    le.getMessage()    // 错误描述
+                    "%s: 行 %d, 列 %d: %s%n",
+                    absPath,
+                    le.getLine(),
+                    le.getColumn(),
+                    le.getReason()
             );
-            System.exit(65); // 65 = EX_DATAERR，标准数据错误退出码
+            System.exit(65); // 65 = EX_DATAERR
+        }
+        LexerEngine.report(this.getErrors());
+    }
+
+    /**
+     * 静态报告方法
+     */
+    public static void report(List<LexicalError> errors) {
+        if (errors != null && !errors.isEmpty()) {
+            System.err.println("\n词法分析发现 " + errors.size() + " 个错误：");
+            errors.forEach(err -> System.err.println("  " + err));
+        } else {
+            System.out.println("## 词法分析通过，没有发现错误\n");
         }
     }
 
@@ -88,15 +107,28 @@ public class LexerEngine {
     private void scanAllTokens() {
         while (!context.isAtEnd()) {
             char currentChar = context.peek();
-            // 依次查找能处理当前字符的扫描器
+            boolean handled = false;
             for (TokenScanner scanner : scanners) {
                 if (scanner.canHandle(currentChar, context)) {
-                    scanner.handle(context, tokens);
-                    break; // 已处理，跳到下一个字符
+                    try {
+                        scanner.handle(context, tokens);
+                    } catch (LexicalException le) {
+                        // 收集词法错误，不直接退出
+                        errors.add(new LexicalError(
+                                absPath, le.getLine(), le.getColumn(), le.getReason()
+                        ));
+                        // 跳过当前字符，防止死循环
+                        context.advance();
+                    }
+                    handled = true;
+                    break;
                 }
             }
+            if (!handled) {
+                // 万一没有任何扫描器能处理，跳过一个字符防止死循环
+                context.advance();
+            }
         }
-        // 末尾补一个 EOF 标记
         tokens.add(Token.eof(context.getLine()));
     }
 
@@ -108,4 +140,11 @@ public class LexerEngine {
     public List<Token> getAllTokens() {
         return List.copyOf(tokens);
     }
+
+    /**
+     * 返回全部词法错误
+     */
+    public List<LexicalError> getErrors() {
+        return List.copyOf(errors);
+    }
 }
diff --git a/src/main/java/org/jcnc/snow/compiler/lexer/core/LexicalError.java b/src/main/java/org/jcnc/snow/compiler/lexer/core/LexicalError.java
new file mode 100644
index 0000000..81ac9ee
--- /dev/null
+++ b/src/main/java/org/jcnc/snow/compiler/lexer/core/LexicalError.java
@@ -0,0 +1,20 @@
+package org.jcnc.snow.compiler.lexer.core;
+
+public class LexicalError {
+    private final String file;
+    private final int line;
+    private final int column;
+    private final String message;
+
+    public LexicalError(String file, int line, int column, String message) {
+        this.file = file;
+        this.line = line;
+        this.column = column;
+        this.message = message;
+    }
+
+    @Override
+    public String toString() {
+        return file + ": 行 " + line + ", 列 " + column + ": " + message;
+    }
+}
diff --git a/src/main/java/org/jcnc/snow/compiler/lexer/core/LexicalException.java b/src/main/java/org/jcnc/snow/compiler/lexer/core/LexicalException.java
index 96cfc0c..cdd01cb 100644
--- a/src/main/java/org/jcnc/snow/compiler/lexer/core/LexicalException.java
+++ b/src/main/java/org/jcnc/snow/compiler/lexer/core/LexicalException.java
@@ -19,6 +19,8 @@ public class LexicalException extends RuntimeException {
     private final int line;
     /** 错误发生的列号（从1开始） */
     private final int column;
+    /** 错误原因 */
+    private final String reason;
 
     /**
      * 构造词法异常
@@ -27,13 +29,14 @@ public class LexicalException extends RuntimeException {
      * @param column  出错列号
      */
     public LexicalException(String reason, int line, int column) {
-        // 构造出错消息，并禁止异常堆栈打印
-        super(String.format("Lexical error: %s at %d:%d", reason, line, column),
-                null, false, false);
+        // 错误描述直接为 reason，禁止异常堆栈打印
+        super(reason, null, false, false);
+        this.reason = reason;
         this.line   = line;
         this.column = column;
     }
 
+
     /**
      * 屏蔽异常堆栈填充（始终不打印堆栈信息）
      */
@@ -51,4 +54,10 @@ public class LexicalException extends RuntimeException {
      * @return 列号
      */
     public int getColumn() { return column; }
+
+    /**
+     * 获取出错的描述
+     * @return 出错描述
+     */
+    public String getReason() { return reason; }
 }
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 ac598de..084c8f7 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
@@ -35,51 +35,56 @@ import org.jcnc.snow.compiler.lexer.token.TokenType;
  */
 public class NumberTokenScanner extends AbstractTokenScanner {
 
-    /** 合法类型后缀字符集合 */
+    /** 合法类型后缀字符集合（单字符，大小写均可） */
     private static final String SUFFIX_CHARS = "bslfdBSLFD";
 
     @Override
     public boolean canHandle(char c, LexerContext ctx) {
+        // 仅当遇到数字时，本扫描器才处理
         return Character.isDigit(c);
     }
 
     @Override
     protected Token scanToken(LexerContext ctx, int line, int col) {
         StringBuilder literal = new StringBuilder();
-        boolean hasDot = false; // 是否已遇到小数点
+        boolean hasDot = false; // 标记是否已出现过小数点
 
-        /* 1. 读取数字主体（整数 / 小数） */
+        /* 1. 读取数字主体部分（包括整数、小数） */
         while (!ctx.isAtEnd()) {
             char c = ctx.peek();
             if (c == '.' && !hasDot) {
+                // 遇到第一个小数点
                 hasDot = true;
                 literal.append(ctx.advance());
             } else if (Character.isDigit(c)) {
+                // 吸收数字字符
                 literal.append(ctx.advance());
             } else {
+                // 非数字/非小数点，终止主体读取
                 break;
             }
         }
 
-        /* 2. 处理后缀或非法跟随字符 */
+        /* 2. 检查数字字面量后的字符，决定是否继续吸收或抛出异常 */
         if (!ctx.isAtEnd()) {
             char next = ctx.peek();
 
-            /* 2-A: 合法类型后缀，直接吸收 */
+            /* 2-A: 合法类型后缀，直接吸收（如 42L、3.0F） */
             if (SUFFIX_CHARS.indexOf(next) >= 0) {
                 literal.append(ctx.advance());
             }
-            /* 2-B: 未知字母紧邻 → 抛异常 */
+            /* 2-B: 若紧跟未知字母（如 42X），抛出词法异常 */
             else if (Character.isLetter(next)) {
                 throw new LexicalException(
-                        "Unknown numeric suffix '" + next + "'",
+                        "未知的数字类型后缀 '" + next + "'",
                         line, col
                 );
             }
-            /* 2-C: 数字后空白（非换行）→ 若空白后跟字母，抛异常 */
+            /* 2-C: 若数字后有空白，且空白后紧跟字母（如 3 L），也为非法 */
             else if (Character.isWhitespace(next) && next != '\n') {
                 int off = 1;
                 char look;
+                // 跳过所有空白字符，找到第一个非空白字符
                 do {
                     look = ctx.peekAhead(off);
                     if (look == '\n' || look == '\0') break;
@@ -88,20 +93,21 @@ public class NumberTokenScanner extends AbstractTokenScanner {
                 } while (true);
 
                 if (Character.isLetter(look)) {
+                    // 抛出：数字字面量与位宽符号之间不允许有空白符
                     throw new LexicalException(
-                            "Whitespace between numeric literal and an alphabetic character is not allowed",
+                            "数字字面量与位宽符号之间不允许有空白符",
                             line, col
                     );
                 }
             }
-            /* 2-D: 紧邻字符为 '/' → 抛异常以避免死循环 */
+            /* 2-D: 若紧跟 '/'，抛出异常防止死循环 */
             else if (next == '/') {
                 throw new LexicalException(
-                        "Unexpected '/' after numeric literal",
+                        "数字字面量后不允许直接出现 '/'",
                         line, col
                 );
             }
-            /* 其余字符（运算符、分隔符等）留给后续扫描器处理 */
+            // 其余情况（如分号、括号、运算符），交由其他扫描器处理
         }
 
         /* 3. 返回 NUMBER_LITERAL Token */
diff --git a/src/main/java/org/jcnc/snow/compiler/semantic/utils/SemanticAnalysisReporter.java b/src/main/java/org/jcnc/snow/compiler/semantic/utils/SemanticAnalysisReporter.java
index dc2b336..91b4487 100644
--- a/src/main/java/org/jcnc/snow/compiler/semantic/utils/SemanticAnalysisReporter.java
+++ b/src/main/java/org/jcnc/snow/compiler/semantic/utils/SemanticAnalysisReporter.java
@@ -28,7 +28,7 @@ public final class SemanticAnalysisReporter {
             System.err.println("语义分析发现 " + errors.size() + " 个错误：");
             errors.forEach(err -> System.err.println("  " + err));
         } else {
-//            System.out.println("## 语义分析通过，没有发现错误\n");
+            System.out.println("\n## 语义分析通过，没有发现错误\n");
         }
     }
 

From dc32f00ead1139eae9d2d6a3a21c1b7b3ae463a7 Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Mon, 30 Jun 2025 16:21:48 +0800
Subject: [PATCH 07/37] =?UTF-8?q?test:=20=E4=BF=AE=E5=A4=8D=20demo1?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 playground/Demo1/Math.snow | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/playground/Demo1/Math.snow b/playground/Demo1/Math.snow
index 973f7c9..bfe8605 100644
--- a/playground/Demo1/Math.snow
+++ b/playground/Demo1/Math.snow
@@ -1,8 +1,8 @@
 module: Math
     function: factorial
         parameter:
-            declare n1: int
-            declare n2: int
+            declare n1: long
+            declare n2: long
         return_type: long
         body:
            return n1+n2

From 67d2b582315e27ab79ca5f555b67bef63cfd55dd Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Mon, 30 Jun 2025 16:52:53 +0800
Subject: [PATCH 08/37] =?UTF-8?q?feat:=20=E9=BB=98=E8=AE=A4=E5=90=AF?=
 =?UTF-8?q?=E5=8A=A8=E6=8A=A5=E5=91=8A?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java   | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java b/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java
index 060d3c3..09daf38 100644
--- a/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java
+++ b/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java
@@ -3,6 +3,7 @@ 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;
+import org.jcnc.snow.compiler.lexer.utils.TokenPrinter;
 
 import java.io.File;
 import java.util.ArrayList;
@@ -84,6 +85,7 @@ public class LexerEngine {
             );
             System.exit(65); // 65 = EX_DATAERR
         }
+        TokenPrinter.print(this.tokens);
         LexerEngine.report(this.getErrors());
     }
 
@@ -95,7 +97,7 @@ public class LexerEngine {
             System.err.println("\n词法分析发现 " + errors.size() + " 个错误：");
             errors.forEach(err -> System.err.println("  " + err));
         } else {
-            System.out.println("## 词法分析通过，没有发现错误\n");
+            System.out.println("\n## 词法分析通过，没有发现错误\n");
         }
     }
 

From ce4106743aa4667b66c59e776da476a71325af86 Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Mon, 30 Jun 2025 17:51:01 +0800
Subject: [PATCH 09/37] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=84=20LexerEngine.?=
 =?UTF-8?q?java=20=E7=9A=84=E6=B3=A8=E9=87=8A?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../snow/compiler/lexer/core/LexerEngine.java | 43 +++++++++++++------
 1 file changed, 30 insertions(+), 13 deletions(-)

diff --git a/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java b/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java
index 09daf38..351f94b 100644
--- a/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java
+++ b/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java
@@ -22,25 +22,34 @@ import java.util.List;
  */
 public class LexerEngine {
     /**
-     * 扫描生成的 Token 序列（包含文件结束符 EOF）
+     * 扫描生成的 Token 序列（包含文件结束符 EOF）。
+     * 每个 Token 表示源代码中的一个词法单元。
      */
     private final List<Token> tokens = new ArrayList<>();
 
-    private final String absPath;
     /**
-     * 词法上下文，提供字符流读取与位置信息
+     * 当前源文件的绝对路径，用于错误信息定位。
+     */
+    private final String absPath;
+
+    /**
+     * 词法上下文，负责字符流读取与位置信息维护。
      */
     private final LexerContext context;
 
     /**
-     * Token 扫描器集合，按优先级顺序组织，用于识别不同类别的 Token
+     * Token 扫描器集合，按优先级顺序排列，
+     * 用于识别不同类别的 Token（如空白、注释、数字、标识符等）。
      */
     private final List<TokenScanner> scanners;
 
+    /**
+     * 词法分析过程中收集到的全部词法错误。
+     */
     private final List<LexicalError> errors = new ArrayList<>();
 
     /**
-     * 构造词法分析器（假定输入源自标准输入，文件名默认为 <stdin>）
+     * 构造词法分析器（假定输入源自标准输入，文件名默认为 &lt;stdin&gt;）。
      *
      * @param source 源代码文本
      */
@@ -48,10 +57,9 @@ public class LexerEngine {
         this(source, "<stdin>");
     }
 
-
     /**
      * 构造词法分析器，并指定源文件名（用于诊断信息）。
-     * 构造时立即进行全量扫描。
+     * 构造时立即进行全量扫描，扫描结束后打印所有 Token 并报告词法错误。
      *
      * @param source     源代码文本
      * @param sourceName 文件名或来源描述（如"Main.snow"）
@@ -90,7 +98,12 @@ public class LexerEngine {
     }
 
     /**
-     * 静态报告方法
+     * 静态报告方法。
+     * <p>
+     * 打印所有词法分析过程中收集到的错误信息。
+     * 如果无错误，输出词法分析通过的提示。
+     *
+     * @param errors 词法错误列表
      */
     public static void report(List<LexicalError> errors) {
         if (errors != null && !errors.isEmpty()) {
@@ -102,9 +115,11 @@ public class LexerEngine {
     }
 
     /**
-     * 主扫描循环，将源代码转为 Token 序列
-     * 依次尝试每个扫描器，直到找到可处理当前字符的扫描器为止
-     * 扫描到结尾后补充 EOF Token
+     * 主扫描循环，将源代码转为 Token 序列。
+     * <p>
+     * 依次尝试每个扫描器，直到找到可处理当前字符的扫描器为止。
+     * 扫描到结尾后补充 EOF Token。
+     * 若遇到词法异常则收集错误并跳过当前字符，避免死循环。
      */
     private void scanAllTokens() {
         while (!context.isAtEnd()) {
@@ -135,7 +150,7 @@ public class LexerEngine {
     }
 
     /**
-     * 获取全部 Token（包含 EOF），返回只读列表
+     * 获取全部 Token（包含 EOF），返回只读列表。
      *
      * @return 词法分析结果 Token 列表
      */
@@ -144,7 +159,9 @@ public class LexerEngine {
     }
 
     /**
-     * 返回全部词法错误
+     * 返回全部词法错误（返回只读列表）。
+     *
+     * @return 词法错误列表
      */
     public List<LexicalError> getErrors() {
         return List.copyOf(errors);

From f9a65531c19b899d328d3b18fd995a4ccdd865d1 Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Mon, 30 Jun 2025 17:52:37 +0800
Subject: [PATCH 10/37] =?UTF-8?q?refactor:=20=E9=87=8D=E6=9E=84=E4=B8=BA?=
 =?UTF-8?q?=E5=9F=BA=E4=BA=8E=E6=9C=89=E9=99=90=E7=8A=B6=E6=80=81=E6=9C=BA?=
 =?UTF-8?q?=EF=BC=88FSM=EF=BC=89=E7=9A=84=E6=95=B0=E5=AD=97=E5=AD=97?=
 =?UTF-8?q?=E9=9D=A2=E9=87=8F=E8=A7=A3=E6=9E=90=E5=99=A8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../lexer/scanners/NumberTokenScanner.java    | 194 ++++++++++++------
 1 file changed, 133 insertions(+), 61 deletions(-)

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 084c8f7..5e1bd7d 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
@@ -6,111 +6,183 @@ import org.jcnc.snow.compiler.lexer.token.Token;
 import org.jcnc.snow.compiler.lexer.token.TokenType;
 
 /**
- * 数字扫描器：识别整数、小数以及带有 <strong>类型后缀</strong> 的数字字面量。<br>
+ * NumberTokenScanner —— 基于有限状态机（FSM）的数字字面量解析器。
  * <p>
- * 支持格式示例：
- * <ul>
- *     <li>整数：<code>123</code>、<code>0</code>、<code>45678</code></li>
- *     <li>小数：<code>3.14</code>、<code>0.5</code>、<code>12.0</code></li>
- *     <li>带后缀：<code>2.0f</code>、<code>42L</code>、<code>7s</code>、<code>255B</code></li>
- * </ul>
- * </p>
+ * 该扫描器负责将源码中的数字字符串切分为 NUMBER_LITERAL token，当前支持：
+ * <ol>
+ *   <li>十进制整数（如 0，42，123456）</li>
+ *   <li>十进制小数（如 3.14，0.5）</li>
+ *   <li>单字符类型后缀（如 2.0f，255B，合法集合见 SUFFIX_CHARS）</li>
+ * </ol>
  * <p>
- * 单字符类型后缀：
+ * 如果后续需要支持科学计数法、下划线分隔符、不同进制等，只需扩展现有状态机的转移规则。
  * <pre>
- * b | s | l | f | d   // byte, short, long, float, double
- * B | S | L | F | D   // 同上（大小写均可）
+ * 状态机简述：
+ *   INT_PART   --'.'-->  DEC_POINT
+ *      |                 |
+ *      |                 v
+ *     else------------> END
+ *      |
+ *      v
+ *   DEC_POINT  --digit--> FRAC_PART
+ *                         |
+ *                         v
+ *                     else--> END
  * </pre>
- * </p>
- * <p>
- * 规则约束：<br>
- * 若数字主体之后出现以下情况，将在词法阶段抛出 {@link LexicalException}：
+ * 状态说明：
  * <ul>
- *     <li>空白 + 字母（如 <code>3&nbsp;L</code>）</li>
- *     <li>未知字母紧邻（如 <code>3E</code>）</li>
- *     <li><code>'/'</code> 紧邻（如 <code>3/</code>、<code>3/*</code>）</li>
+ *   <li>INT_PART   ：读取整数部分，遇到 '.' 进入 DEC_POINT，否则结束。</li>
+ *   <li>DEC_POINT  ：已读到小数点，必须下一个字符是数字，否则报错。</li>
+ *   <li>FRAC_PART  ：读取小数部分，遇非法字符则结束主体。</li>
+ *   <li>END        ：主体扫描结束，进入后缀/尾随字符判定。</li>
  * </ul>
- * 以避免编译器陷入死循环。
- * </p>
+ * 错误处理策略：
+ * <ol>
+ *   <li>数字后跟未知字母（如 42X）—— 抛出 LexicalException</li>
+ *   <li>数字与合法后缀间有空白（如 3 L）—— 抛出 LexicalException</li>
+ *   <li>数字后直接出现 '/'（如 3/ 或 3/*）—— 抛出 LexicalException，避免死循环</li>
+ *   <li>小数点后缺失数字（如 1.）—— 抛出 LexicalException</li>
+ * </ol>
+ * 支持的单字符类型后缀包括：b, s, l, f, d 及其大写形式。若需支持多字符后缀，可将该集合扩展为 Set<String>。
  */
 public class NumberTokenScanner extends AbstractTokenScanner {
 
-    /** 合法类型后缀字符集合（单字符，大小写均可） */
+    /**
+     * 支持的单字符类型后缀集合。
+     * 包含：b, s, l, f, d 及其大写形式。
+     * 对于多字符后缀，可扩展为 Set<String> 并在扫描尾部做贪婪匹配。
+     */
     private static final String SUFFIX_CHARS = "bslfdBSLFD";
 
+    /**
+     * 判断是否由该扫描器处理。
+     * 仅当首字符为数字时，NumberTokenScanner 介入处理。
+     *
+     * @param c   当前待判断字符
+     * @param ctx 当前 LexerContext（可用于进一步判断）
+     * @return 如果为数字返回 true，否则返回 false
+     */
     @Override
     public boolean canHandle(char c, LexerContext ctx) {
-        // 仅当遇到数字时，本扫描器才处理
         return Character.isDigit(c);
     }
 
+    /**
+     * 按照有限状态机读取完整数字字面量，并对尾随字符进行合法性校验。
+     * <p>
+     * 主体流程：
+     * 1. 整数部分、可选小数点和小数部分扫描。
+     * 2. 检查合法的类型后缀。
+     * 3. 检查非法尾随字符，如未知字母、空白后缀或非法 '/'。
+     * 4. 生成并返回 NUMBER_LITERAL Token。
+     *
+     * @param ctx  当前 LexerContext（提供游标、前瞻等功能）
+     * @param line 源码起始行号（1 基）
+     * @param col  源码起始列号（1 基）
+     * @return NUMBER_LITERAL 类型的 Token
+     * @throws LexicalException 如果遇到非法格式或未受支持的尾随字符
+     */
     @Override
     protected Token scanToken(LexerContext ctx, int line, int col) {
         StringBuilder literal = new StringBuilder();
-        boolean hasDot = false; // 标记是否已出现过小数点
+        State state = State.INT_PART;
 
-        /* 1. 读取数字主体部分（包括整数、小数） */
-        while (!ctx.isAtEnd()) {
-            char c = ctx.peek();
-            if (c == '.' && !hasDot) {
-                // 遇到第一个小数点
-                hasDot = true;
-                literal.append(ctx.advance());
-            } else if (Character.isDigit(c)) {
-                // 吸收数字字符
-                literal.append(ctx.advance());
-            } else {
-                // 非数字/非小数点，终止主体读取
-                break;
+        // 1. 主体扫描 —— 整数 / 小数
+        mainLoop:
+        while (!ctx.isAtEnd() && state != State.END) {
+            char ch = ctx.peek();
+            switch (state) {
+                case INT_PART:
+                    if (Character.isDigit(ch)) {
+                        literal.append(ctx.advance());
+                    } else if (ch == '.') {
+                        state = State.DEC_POINT;
+                        literal.append(ctx.advance());
+                    } else {
+                        state = State.END; // 整数已结束
+                    }
+                    break;
+
+                case DEC_POINT:
+                    if (Character.isDigit(ch)) {
+                        state = State.FRAC_PART;
+                        literal.append(ctx.advance());
+                    } else {
+                        // 如 "1." —— 语言规范不允许尾点数字
+                        throw new LexicalException("小数点后必须跟数字", line, col);
+                    }
+                    break;
+
+                case FRAC_PART:
+                    if (Character.isDigit(ch)) {
+                        literal.append(ctx.advance());
+                    } else {
+                        state = State.END; // 小数字符串结束
+                    }
+                    break;
+
+                default:
+                    break mainLoop; // 理论不会到达
             }
         }
 
-        /* 2. 检查数字字面量后的字符，决定是否继续吸收或抛出异常 */
+        // 2. 后缀及非法尾随字符检查
         if (!ctx.isAtEnd()) {
             char next = ctx.peek();
 
-            /* 2-A: 合法类型后缀，直接吸收（如 42L、3.0F） */
+            // 2‑A. 合法单字符后缀
             if (SUFFIX_CHARS.indexOf(next) >= 0) {
                 literal.append(ctx.advance());
             }
-            /* 2-B: 若紧跟未知字母（如 42X），抛出词法异常 */
+            // 2‑B. 紧跟未知字母（如 42X）
             else if (Character.isLetter(next)) {
-                throw new LexicalException(
-                        "未知的数字类型后缀 '" + next + "'",
-                        line, col
-                );
+                throw new LexicalException("未知的数字类型后缀 '" + next + "'", line, col);
             }
-            /* 2-C: 若数字后有空白，且空白后紧跟字母（如 3 L），也为非法 */
+            // 2‑C. 数字后出现空白 + 字母（如 3 L）
             else if (Character.isWhitespace(next) && next != '\n') {
                 int off = 1;
                 char look;
-                // 跳过所有空白字符，找到第一个非空白字符
-                do {
+                while (true) {
                     look = ctx.peekAhead(off);
-                    if (look == '\n' || look == '\0') break;
+                    if (look == '\n' || look == '\0') break; // 行尾或 EOF
                     if (!Character.isWhitespace(look)) break;
                     off++;
-                } while (true);
-
+                }
                 if (Character.isLetter(look)) {
-                    // 抛出：数字字面量与位宽符号之间不允许有空白符
-                    throw new LexicalException(
-                            "数字字面量与位宽符号之间不允许有空白符",
-                            line, col
-                    );
+                    throw new LexicalException("数字字面量与类型后缀之间不允许有空白符", line, col);
                 }
             }
-            /* 2-D: 若紧跟 '/'，抛出异常防止死循环 */
+            // 2‑D. 紧跟 '/'（如 3/ 或 3/*）
             else if (next == '/') {
-                throw new LexicalException(
-                        "数字字面量后不允许直接出现 '/'",
-                        line, col
-                );
+                throw new LexicalException("数字字面量后不允许直接出现 '/'", line, col);
             }
-            // 其余情况（如分号、括号、运算符），交由其他扫描器处理
+            // 其他字符（分号、运算符、括号等）留给外层扫描流程处理
         }
 
-        /* 3. 返回 NUMBER_LITERAL Token */
+        // 3. 生成并返回 Token
         return new Token(TokenType.NUMBER_LITERAL, literal.toString(), line, col);
     }
+
+    /**
+     * FSM 内部状态。
+     * 每次读取一个字符后，根据“当前状态 + 当前字符”决定转移。
+     */
+    private enum State {
+        /**
+         * 整数部分（尚未读到小数点）
+         */
+        INT_PART,
+        /**
+         * 已读到小数点，但还未读到第一位小数数字
+         */
+        DEC_POINT,
+        /**
+         * 小数部分（小数点右侧）
+         */
+        FRAC_PART,
+        /**
+         * 主体结束，准备处理后缀或交还控制权
+         */
+        END
+    }
 }

From e9939e73c1c1f2d9b0ae958d32bd3ac166f61be1 Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Mon, 30 Jun 2025 17:54:30 +0800
Subject: [PATCH 11/37] =?UTF-8?q?fix:=20=E5=88=A0=E9=99=A4=20LexerEngine.j?=
 =?UTF-8?q?ava=20=E7=9A=84=E5=86=97=E4=BD=99=E4=BB=A3=E7=A0=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../org/jcnc/snow/compiler/lexer/core/LexerEngine.java   | 9 ---------
 1 file changed, 9 deletions(-)

diff --git a/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java b/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java
index 351f94b..6ce7b77 100644
--- a/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java
+++ b/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java
@@ -48,15 +48,6 @@ public class LexerEngine {
      */
     private final List<LexicalError> errors = new ArrayList<>();
 
-    /**
-     * 构造词法分析器（假定输入源自标准输入，文件名默认为 &lt;stdin&gt;）。
-     *
-     * @param source 源代码文本
-     */
-    public LexerEngine(String source) {
-        this(source, "<stdin>");
-    }
-
     /**
      * 构造词法分析器，并指定源文件名（用于诊断信息）。
      * 构造时立即进行全量扫描，扫描结束后打印所有 Token 并报告词法错误。

From f4568f82a4fd30ce4741ad0b593400f6c0faa8dc Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Mon, 30 Jun 2025 23:42:14 +0800
Subject: [PATCH 12/37] =?UTF-8?q?fix:=20=E7=BC=96=E8=AF=91=E9=81=87?=
 =?UTF-8?q?=E5=88=B0=E8=AF=8D=E6=B3=95=E9=94=99=E8=AF=AF=E7=AB=8B=E5=8D=B3?=
 =?UTF-8?q?=E7=BB=88=E6=AD=A2?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java    | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java b/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java
index 6ce7b77..970ec59 100644
--- a/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java
+++ b/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java
@@ -86,6 +86,9 @@ public class LexerEngine {
         }
         TokenPrinter.print(this.tokens);
         LexerEngine.report(this.getErrors());
+        if (!errors.isEmpty()) {
+            throw new LexicalException("Lexing failed with " + errors.size() + " error(s).", this.context.getLine(), this.context.getCol());
+        }
     }
 
     /**

From 2a085f6906ca8840610c87e879a3f114f36c07a1 Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Mon, 30 Jun 2025 23:42:34 +0800
Subject: [PATCH 13/37] =?UTF-8?q?docs:=20=E4=BF=AE=E5=A4=8D=E6=B3=A8?=
 =?UTF-8?q?=E9=87=8A=E6=A0=BC=E5=BC=8F?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../compiler/lexer/scanners/NumberTokenScanner.java    | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

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 5e1bd7d..eea6458 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
@@ -71,10 +71,12 @@ public class NumberTokenScanner extends AbstractTokenScanner {
      * 按照有限状态机读取完整数字字面量，并对尾随字符进行合法性校验。
      * <p>
      * 主体流程：
-     * 1. 整数部分、可选小数点和小数部分扫描。
-     * 2. 检查合法的类型后缀。
-     * 3. 检查非法尾随字符，如未知字母、空白后缀或非法 '/'。
-     * 4. 生成并返回 NUMBER_LITERAL Token。
+     * <ol>
+     * <li>整数部分、可选小数点和小数部分扫描。</li>
+     * <li>检查合法的类型后缀。</li>
+     * <li>检查非法尾随字符，如未知字母、空白后缀或非法 '/'。</li>
+     * <li>生成并返回 NUMBER_LITERAL Token。</li>
+     * </ol>
      *
      * @param ctx  当前 LexerContext（提供游标、前瞻等功能）
      * @param line 源码起始行号（1 基）

From 30b89c0f3d031934018218bc132ba9f4bdbc7469 Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Mon, 30 Jun 2025 23:42:52 +0800
Subject: [PATCH 14/37] =?UTF-8?q?fix:=20=E7=BB=9F=E4=B8=80=E5=93=A8?=
 =?UTF-8?q?=E5=85=B5=E5=80=BC?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../org/jcnc/snow/vm/commands/function/RetCommand.java    | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/src/main/java/org/jcnc/snow/vm/commands/function/RetCommand.java b/src/main/java/org/jcnc/snow/vm/commands/function/RetCommand.java
index af37032..1299bf5 100644
--- a/src/main/java/org/jcnc/snow/vm/commands/function/RetCommand.java
+++ b/src/main/java/org/jcnc/snow/vm/commands/function/RetCommand.java
@@ -14,7 +14,9 @@ import org.jcnc.snow.vm.module.*;
  */
 public class RetCommand implements Command {
 
-    /** Sentinel value that tells the VM loop to terminate gracefully. */
+    /**
+     * Sentinel value that tells the VM loop to terminate gracefully.
+     */
     private static final int PROGRAM_END = Integer.MAX_VALUE;
 
     @Override
@@ -32,8 +34,8 @@ public class RetCommand implements Command {
         StackFrame topFrame = callStack.peekFrame();
 
         /* ----- Root frame: do NOT pop, just end program ----- */
-        if (topFrame.getReturnAddress() == 0) {
-            System.out.println("Return 0");
+        if (topFrame.getReturnAddress() == PROGRAM_END) {
+            System.out.println("Return <root>");
             return PROGRAM_END;          // VM main loop should break
         }
 

From c88404fada081eddc9c9184764383e1a6e9f1cd8 Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Tue, 1 Jul 2025 00:15:14 +0800
Subject: [PATCH 15/37] =?UTF-8?q?refactor:=20=E9=87=8D=E6=9E=84=E4=B8=BA?=
 =?UTF-8?q?=E5=9F=BA=E4=BA=8E=E6=9C=89=E9=99=90=E7=8A=B6=E6=80=81=E6=9C=BA?=
 =?UTF-8?q?=EF=BC=88FSM=EF=BC=89=E7=9A=84=E6=B3=A8=E9=87=8A=E8=A7=A3?=
 =?UTF-8?q?=E6=9E=90=E5=99=A8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../lexer/scanners/CommentTokenScanner.java   | 78 +++++++++++--------
 1 file changed, 45 insertions(+), 33 deletions(-)

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 a8a3313..328dee7 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,29 +1,31 @@
 package org.jcnc.snow.compiler.lexer.scanners;
 
 import org.jcnc.snow.compiler.lexer.core.LexerContext;
+import org.jcnc.snow.compiler.lexer.core.LexicalException;
 import org.jcnc.snow.compiler.lexer.token.Token;
 import org.jcnc.snow.compiler.lexer.token.TokenType;
 
 /**
- * 注释扫描器：处理源代码中的注释部分，包括：
+ * {@code CommentTokenScanner} —— 注释解析器，基于有限状态机（FSM）。
+ *
+ * <p>负责将源码中的两种注释形式切分为 {@link TokenType#COMMENT COMMENT} token：</p>
+ * <ol>
+ *   <li>单行注释：以 {@code //} 开头，直至行尾或文件末尾。</li>
+ * 多行注释：以 {@code /*} 开头，以 <code>*&#47;</code> 结束，可跨多行。
+ * </ol>
+ *
+ * <p>本扫描器遵循“发现即捕获”原则：
+ * 注释文本被完整保留在 Token 中，供后续的文档提取、源映射等分析使用。</p>
+ *
+ * <p>错误处理策略</p>
  * <ul>
- *     <li>单行注释（以 "//" 开头，直到行尾）</li>
- *     <li>多行注释（以 "/*" 开头，以 "*&#47;" 结尾）</li>
+ *   <li>未终止的多行注释：若文件结束时仍未遇到 <code>*&#47;</code>，抛出 {@link LexicalException}。</li>
  * </ul>
- * <p>
- * 本扫描器会识别注释并生成 {@code TokenType.COMMENT} 类型的 Token，
- * 不会丢弃注释内容，而是将完整注释文本保留在 Token 中，便于后续分析（如文档提取、保留注释等场景）。
- * </p>
  */
 public class CommentTokenScanner extends AbstractTokenScanner {
 
     /**
-     * 判断是否可以处理当前位置的字符。
-     * <p>当当前位置字符为 '/' 且下一个字符为 '/' 或 '*' 时，表示可能是注释的起始。</p>
-     *
-     * @param c   当前字符
-     * @param ctx 当前词法上下文
-     * @return 如果是注释的起始符，则返回 true
+     * 仅当当前字符为 {@code '/'} 且下一个字符为 {@code '/'} 或 {@code '*'} 时，由本扫描器处理。
      */
     @Override
     public boolean canHandle(char c, LexerContext ctx) {
@@ -31,44 +33,54 @@ public class CommentTokenScanner extends AbstractTokenScanner {
     }
 
     /**
-     * 实现注释的扫描逻辑。
-     * <p>支持两种注释格式：</p>
-     * <ul>
-     *     <li><b>单行注释：</b> 以 "//" 开头，直到遇到换行符</li>
-     *     <li><b>多行注释：</b> 以 "/*" 开头，直到遇到 "*&#47;" 结束</li>
-     * </ul>
+     * 执行注释扫描，生成 {@code COMMENT} Token。
      *
      * @param ctx  词法上下文
-     * @param line 当前行号（用于 Token 位置信息）
-     * @param col  当前列号（用于 Token 位置信息）
-     * @return 包含完整注释内容的 COMMENT 类型 Token
+     * @param line 起始行号（1 基）
+     * @param col  起始列号（1 基）
+     * @return 包含完整注释文本的 Token
+     * @throws LexicalException 若遇到未终止的多行注释
      */
     @Override
     protected Token scanToken(LexerContext ctx, int line, int col) {
-        // 消费第一个 '/' 字符
-        ctx.advance();
-        StringBuilder sb = new StringBuilder("/");
+        StringBuilder literal = new StringBuilder();
 
-        // 处理单行注释 //
+        /*
+         * 1. 读取注释起始符
+         *    - 已由 canHandle 保证当前位置一定是 '/'
+         */
+        literal.append(ctx.advance()); // 消费首个 '/'
+
+        // -------- 单行注释 (//) --------
         if (ctx.match('/')) {
-            sb.append('/');
+            literal.append('/');
             while (!ctx.isAtEnd() && ctx.peek() != '\n') {
-                sb.append(ctx.advance());
+                literal.append(ctx.advance());
             }
+            // 行尾或文件尾时退出，换行符留给上层扫描器处理。
         }
-        // 处理多行注释 /* ... */
+        // -------- 多行注释 (/* ... */) --------
         else if (ctx.match('*')) {
-            sb.append('*');
+            literal.append('*');
+            boolean terminated = false;
             while (!ctx.isAtEnd()) {
                 char ch = ctx.advance();
-                sb.append(ch);
+                literal.append(ch);
                 if (ch == '*' && ctx.peek() == '/') {
-                    sb.append(ctx.advance()); // 消费 '/'
+                    literal.append(ctx.advance()); // 追加 '/'
+                    terminated = true;
                     break;
                 }
             }
+            if (!terminated) {
+                // 文件结束仍未闭合，抛 LexicalException
+                throw new LexicalException("未终止的多行注释", line, col);
+            }
         }
 
-        return new Token(TokenType.COMMENT, sb.toString(), line, col);
+        /*
+         * 2. 生成并返回 Token
+         */
+        return new Token(TokenType.COMMENT, literal.toString(), line, col);
     }
 }

From 6ae6d6e893ca39d12002748896732373fd2a3951 Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Tue, 1 Jul 2025 09:34:38 +0800
Subject: [PATCH 16/37] =?UTF-8?q?chore:=20IDEA=20=E7=82=B9=E5=87=BB?=
 =?UTF-8?q?=E8=BF=90=E8=A1=8C=E5=90=8E"Run=20tool=20=E7=AA=97=E5=8F=A3"?=
 =?UTF-8?q?=E4=BC=9A=E5=87=BA=E7=8E=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .run/Bug1.run.xml   | 2 +-
 .run/Demo1.run.xml  | 2 +-
 .run/Demo10.run.xml | 2 +-
 .run/Demo11.run.xml | 2 +-
 .run/Demo2.run.xml  | 2 +-
 .run/Demo3.run.xml  | 2 +-
 .run/Demo4.run.xml  | 2 +-
 .run/Demo5.run.xml  | 2 +-
 .run/Demo6.run.xml  | 2 +-
 .run/Demo7.run.xml  | 2 +-
 .run/Demo8.run.xml  | 2 +-
 .run/Demo9.run.xml  | 2 +-
 12 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/.run/Bug1.run.xml b/.run/Bug1.run.xml
index 46f5bc6..f9c6da7 100644
--- a/.run/Bug1.run.xml
+++ b/.run/Bug1.run.xml
@@ -1,5 +1,5 @@
 <component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="Bug1" type="Application" factoryName="Application" folderName="BugFarm" activateToolWindowBeforeRun="false">
+  <configuration default="false" name="Bug1" type="Application" factoryName="Application" folderName="BugFarm">
     <option name="ALTERNATIVE_JRE_PATH" value="graalvm-ce-23" />
     <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
     <module name="Snow" />
diff --git a/.run/Demo1.run.xml b/.run/Demo1.run.xml
index 55005c8..653910c 100644
--- a/.run/Demo1.run.xml
+++ b/.run/Demo1.run.xml
@@ -1,5 +1,5 @@
 <component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="Demo1" type="Application" factoryName="Application" folderName="Demo" activateToolWindowBeforeRun="false">
+  <configuration default="false" name="Demo1" type="Application" factoryName="Application" folderName="Demo">
     <option name="ALTERNATIVE_JRE_PATH" value="graalvm-ce-23" />
     <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
     <module name="Snow" />
diff --git a/.run/Demo10.run.xml b/.run/Demo10.run.xml
index 19c1c9c..3d2b22a 100644
--- a/.run/Demo10.run.xml
+++ b/.run/Demo10.run.xml
@@ -1,5 +1,5 @@
 <component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="Demo10" type="Application" factoryName="Application" folderName="Demo" activateToolWindowBeforeRun="false">
+  <configuration default="false" name="Demo10" type="Application" factoryName="Application" folderName="Demo">
     <option name="ALTERNATIVE_JRE_PATH" value="graalvm-ce-23" />
     <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
     <module name="Snow" />
diff --git a/.run/Demo11.run.xml b/.run/Demo11.run.xml
index e6748fb..07d914d 100644
--- a/.run/Demo11.run.xml
+++ b/.run/Demo11.run.xml
@@ -1,5 +1,5 @@
 <component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="Demo11" type="Application" factoryName="Application" folderName="Demo" activateToolWindowBeforeRun="false">
+  <configuration default="false" name="Demo11" type="Application" factoryName="Application" folderName="Demo">
     <option name="ALTERNATIVE_JRE_PATH" value="graalvm-ce-23" />
     <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
     <module name="Snow" />
diff --git a/.run/Demo2.run.xml b/.run/Demo2.run.xml
index 2661fde..0711740 100644
--- a/.run/Demo2.run.xml
+++ b/.run/Demo2.run.xml
@@ -1,5 +1,5 @@
 <component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="Demo2" type="Application" factoryName="Application" folderName="Demo" activateToolWindowBeforeRun="false">
+  <configuration default="false" name="Demo2" type="Application" factoryName="Application" folderName="Demo">
     <option name="ALTERNATIVE_JRE_PATH" value="graalvm-ce-23" />
     <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
     <module name="Snow" />
diff --git a/.run/Demo3.run.xml b/.run/Demo3.run.xml
index 57994d1..a2b72da 100644
--- a/.run/Demo3.run.xml
+++ b/.run/Demo3.run.xml
@@ -1,5 +1,5 @@
 <component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="Demo3" type="Application" factoryName="Application" folderName="Demo" activateToolWindowBeforeRun="false">
+  <configuration default="false" name="Demo3" type="Application" factoryName="Application" folderName="Demo">
     <option name="ALTERNATIVE_JRE_PATH" value="graalvm-ce-23" />
     <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
     <module name="Snow" />
diff --git a/.run/Demo4.run.xml b/.run/Demo4.run.xml
index 083127e..491197e 100644
--- a/.run/Demo4.run.xml
+++ b/.run/Demo4.run.xml
@@ -1,5 +1,5 @@
 <component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="Demo4" type="Application" factoryName="Application" folderName="Demo" activateToolWindowBeforeRun="false">
+  <configuration default="false" name="Demo4" type="Application" factoryName="Application" folderName="Demo">
     <option name="ALTERNATIVE_JRE_PATH" value="graalvm-ce-23" />
     <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
     <module name="Snow" />
diff --git a/.run/Demo5.run.xml b/.run/Demo5.run.xml
index 2c2bbf8..d3f69a3 100644
--- a/.run/Demo5.run.xml
+++ b/.run/Demo5.run.xml
@@ -1,5 +1,5 @@
 <component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="Demo5" type="Application" factoryName="Application" folderName="Demo" activateToolWindowBeforeRun="false">
+  <configuration default="false" name="Demo5" type="Application" factoryName="Application" folderName="Demo">
     <option name="ALTERNATIVE_JRE_PATH" value="graalvm-ce-23" />
     <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
     <module name="Snow" />
diff --git a/.run/Demo6.run.xml b/.run/Demo6.run.xml
index 9c76927..b7eb743 100644
--- a/.run/Demo6.run.xml
+++ b/.run/Demo6.run.xml
@@ -1,5 +1,5 @@
 <component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="Demo6" type="Application" factoryName="Application" folderName="Demo" activateToolWindowBeforeRun="false">
+  <configuration default="false" name="Demo6" type="Application" factoryName="Application" folderName="Demo">
     <option name="ALTERNATIVE_JRE_PATH" value="graalvm-ce-23" />
     <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
     <module name="Snow" />
diff --git a/.run/Demo7.run.xml b/.run/Demo7.run.xml
index d78ab8c..afa8cd9 100644
--- a/.run/Demo7.run.xml
+++ b/.run/Demo7.run.xml
@@ -1,5 +1,5 @@
 <component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="Demo7" type="Application" factoryName="Application" folderName="Demo" activateToolWindowBeforeRun="false">
+  <configuration default="false" name="Demo7" type="Application" factoryName="Application" folderName="Demo">
     <option name="ALTERNATIVE_JRE_PATH" value="graalvm-ce-23" />
     <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
     <module name="Snow" />
diff --git a/.run/Demo8.run.xml b/.run/Demo8.run.xml
index 0857919..8bff503 100644
--- a/.run/Demo8.run.xml
+++ b/.run/Demo8.run.xml
@@ -1,5 +1,5 @@
 <component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="Demo8" type="Application" factoryName="Application" folderName="Demo" activateToolWindowBeforeRun="false">
+  <configuration default="false" name="Demo8" type="Application" factoryName="Application" folderName="Demo">
     <option name="ALTERNATIVE_JRE_PATH" value="graalvm-ce-23" />
     <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
     <module name="Snow" />
diff --git a/.run/Demo9.run.xml b/.run/Demo9.run.xml
index 97cff0d..8e63237 100644
--- a/.run/Demo9.run.xml
+++ b/.run/Demo9.run.xml
@@ -1,5 +1,5 @@
 <component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="Demo9" type="Application" factoryName="Application" folderName="Demo" activateToolWindowBeforeRun="false">
+  <configuration default="false" name="Demo9" type="Application" factoryName="Application" folderName="Demo">
     <option name="ALTERNATIVE_JRE_PATH" value="graalvm-ce-23" />
     <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
     <module name="Snow" />

From 4507e3589fcaa909e4e139044dcd696c084a31a9 Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Tue, 1 Jul 2025 09:55:21 +0800
Subject: [PATCH 17/37] =?UTF-8?q?fix:=20NumberTokenScanner=20=E7=A7=BB?=
 =?UTF-8?q?=E9=99=A4=E6=95=B0=E5=AD=97=E5=AD=97=E9=9D=A2=E9=87=8F=E5=90=8E?=
 =?UTF-8?q?=E7=9B=B4=E6=8E=A5=E8=B7=9F=20/=20=E7=9A=84=E8=A7=84=E5=88=99?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java  | 2 +-
 .../snow/compiler/lexer/scanners/NumberTokenScanner.java     | 5 -----
 2 files changed, 1 insertion(+), 6 deletions(-)

diff --git a/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java b/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java
index 970ec59..5df39fa 100644
--- a/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java
+++ b/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java
@@ -136,7 +136,7 @@ public class LexerEngine {
                 }
             }
             if (!handled) {
-                // 万一没有任何扫描器能处理，跳过一个字符防止死循环
+                // 没有任何扫描器能处理，跳过一个字符防止死循环
                 context.advance();
             }
         }
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 eea6458..11eefa5 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
@@ -40,7 +40,6 @@ import org.jcnc.snow.compiler.lexer.token.TokenType;
  * <ol>
  *   <li>数字后跟未知字母（如 42X）—— 抛出 LexicalException</li>
  *   <li>数字与合法后缀间有空白（如 3 L）—— 抛出 LexicalException</li>
- *   <li>数字后直接出现 '/'（如 3/ 或 3/*）—— 抛出 LexicalException，避免死循环</li>
  *   <li>小数点后缺失数字（如 1.）—— 抛出 LexicalException</li>
  * </ol>
  * 支持的单字符类型后缀包括：b, s, l, f, d 及其大写形式。若需支持多字符后缀，可将该集合扩展为 Set<String>。
@@ -154,10 +153,6 @@ public class NumberTokenScanner extends AbstractTokenScanner {
                     throw new LexicalException("数字字面量与类型后缀之间不允许有空白符", line, col);
                 }
             }
-            // 2‑D. 紧跟 '/'（如 3/ 或 3/*）
-            else if (next == '/') {
-                throw new LexicalException("数字字面量后不允许直接出现 '/'", line, col);
-            }
             // 其他字符（分号、运算符、括号等）留给外层扫描流程处理
         }
 

From 7b9bd3790043282697666a346db6b85a8e9fd74d Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Tue, 1 Jul 2025 10:45:56 +0800
Subject: [PATCH 18/37] =?UTF-8?q?feat:=20=E6=94=AF=E6=8C=81=E8=A1=8C?=
 =?UTF-8?q?=E5=86=85=E6=B3=A8=E9=87=8A?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../compiler/parser/context/TokenStream.java  | 82 ++++++++++++++-----
 .../compiler/parser/core/ParserEngine.java    |  6 +-
 .../expression/PrattExpressionParser.java     |  2 +-
 3 files changed, 65 insertions(+), 25 deletions(-)

diff --git a/src/main/java/org/jcnc/snow/compiler/parser/context/TokenStream.java b/src/main/java/org/jcnc/snow/compiler/parser/context/TokenStream.java
index 2788300..c064476 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/context/TokenStream.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/context/TokenStream.java
@@ -6,37 +6,49 @@ import org.jcnc.snow.compiler.lexer.token.TokenType;
 import java.util.List;
 
 /**
- * {@code TokenStream} 封装了一个 Token 列表并维护当前解析位置，
- * 是语法分析器读取词法单元的核心工具类。
- * <p>
- * 提供前瞻（peek）、消费（next）、匹配（match）、断言（expect）等常用操作，
- * 支持前向查看和异常处理，适用于递归下降解析等常见语法构建策略。
- * </p>
+ * {@code TokenStream} 封装了一个 Token 列表并维护当前解析位置，是语法分析器读取词法单元的核心工具类。
+ *
+ * <p>提供前瞻（peek）、消费（next）、匹配（match）、断言（expect）等常用操作，
+ * 支持前向查看和异常处理，适用于递归下降解析等常见语法构建策略。</p>
+ *
  */
 public class TokenStream {
 
-    /** 源 Token 列表 */
+    /**
+     * 源 Token 列表。
+     */
     private final List<Token> tokens;
 
-    /** 当前解析位置索引 */
+    /**
+     * 当前解析位置索引。
+     */
     private int pos = 0;
 
     /**
      * 使用 Token 列表构造 TokenStream。
      *
      * @param tokens 由词法分析器产生的 Token 集合
+     * @throws NullPointerException 如果 tokens 为 null
      */
     public TokenStream(List<Token> tokens) {
+        if (tokens == null) {
+            throw new NullPointerException("Token list cannot be null.");
+        }
         this.tokens = tokens;
     }
 
     /**
      * 向前查看指定偏移量处的 Token（不移动位置）。
+     * 会在 offset==0 时自动跳过当前位置的所有注释（COMMENT）token。
      *
-     * @param offset 相对当前位置的偏移量（0 表示当前）
+     * @param offset 相对当前位置的偏移量（0 表示当前 token）
      * @return 指定位置的 Token；若越界则返回自动构造的 EOF Token
      */
     public Token peek(int offset) {
+        // 只在 offset==0 时跳注释，向前多步 peek 由调用方控制
+        if (offset == 0) {
+            skipTrivia();
+        }
         int idx = pos + offset;
         if (idx >= tokens.size()) {
             return Token.eof(tokens.size() + 1);
@@ -47,28 +59,30 @@ public class TokenStream {
     /**
      * 查看当前位置的 Token，等效于 {@code peek(0)}。
      *
-     * @return 当前 Token
+     * @return 当前有效 Token（已跳过注释）
      */
     public Token peek() {
+        skipTrivia();
         return peek(0);
     }
 
     /**
-     * 消费当前位置的 Token 并返回，位置前移。
+     * 消费当前位置的 Token 并返回，位置前移。注释 token 会被自动跳过。
      *
-     * @return 当前 Token
+     * @return 被消费的有效 Token（已跳过注释）
      */
     public Token next() {
-        Token t = peek();
-        pos++;
+        Token t = peek();   // peek() 已跳过注释
+        pos++;              // 指针指向下一个 raw token
+        skipTrivia();       // 立即吞掉紧随其后的注释（若有）
         return t;
     }
 
     /**
-     * 匹配当前 Token 的词素与指定字符串，若匹配则消费。
+     * 匹配当前 Token 的词素与指定字符串，若匹配则消费该 token 并前移指针。
      *
-     * @param lexeme 待匹配词素
-     * @return 若成功匹配则返回 true
+     * @param lexeme 待匹配的词素字符串
+     * @return 匹配成功返回 true，否则返回 false
      */
     public boolean match(String lexeme) {
         if (peek().getLexeme().equals(lexeme)) {
@@ -80,6 +94,7 @@ public class TokenStream {
 
     /**
      * 断言当前 Token 的词素与指定值相符，否则抛出 {@link ParseException}。
+     * 匹配成功会消费该 token 并前移指针。
      *
      * @param lexeme 期望的词素值
      * @return 匹配成功的 Token
@@ -98,6 +113,7 @@ public class TokenStream {
 
     /**
      * 断言当前 Token 类型为指定类型，否则抛出 {@link ParseException}。
+     * 匹配成功会消费该 token 并前移指针。
      *
      * @param type 期望的 Token 类型
      * @return 匹配成功的 Token
@@ -115,13 +131,37 @@ public class TokenStream {
     }
 
     /**
-     * 判断是否“已经”到达 EOF。
+     * 判断是否“已经”到达文件末尾（EOF）。
      *
-     * @return 若当前位置 Token 为 EOF，则返回 true，否则 false
+     * @return 若当前位置 Token 为 EOF，则返回 true，否则返回 false
      */
     public boolean isAtEnd() {
         return peek().getType() == TokenType.EOF;
     }
 
-
-}
\ No newline at end of file
+    /**
+     * 跳过所有连续的注释（COMMENT）token。
+     *
+     * <p>
+     * 此方法会检查当前指针 <code>pos</code> 所指向的 token，
+     * 如果其类型为 <code>TokenType.COMMENT</code>，则直接将指针递增，
+     * 直到遇到非 COMMENT 类型或到达 token 列表末尾。
+     * </p>
+     *
+     * <p>
+     * 注意：此方法<strong>只会跳过注释</strong>，不会递归或调用任何
+     * 会产生递归的方法（如 peek()/next()），以避免堆栈溢出。
+     * </p>
+     *
+     * <p>
+     * 使用场景：词法分析产物中允许出现注释 token，语法分析时需要自动跳过它们，
+     * 保证 parser 只处理有效语法 token。
+     * </p>
+     */
+    private void skipTrivia() {
+        while (pos < tokens.size()
+                && tokens.get(pos).getType() == TokenType.COMMENT) {
+            pos++; // 直接跳过 COMMENT 类型
+        }
+    }
+}
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/core/ParserEngine.java b/src/main/java/org/jcnc/snow/compiler/parser/core/ParserEngine.java
index 14dc783..7d0854f 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/core/ParserEngine.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/core/ParserEngine.java
@@ -17,7 +17,7 @@ public record ParserEngine(ParserContext ctx) {
         List<String> errs = new ArrayList<>();
         TokenStream ts = ctx.getTokens();
 
-        while (!ts.isAtEnd()) {
+        while (ts.isAtEnd()) {
             // 跳过空行
             if (ts.peek().getType() == TokenType.NEWLINE) {
                 ts.next();
@@ -46,7 +46,7 @@ public record ParserEngine(ParserContext ctx) {
      * 错误同步：跳到下一行或下一个已注册顶层关键字
      */
     private void synchronize(TokenStream ts) {
-        while (!ts.isAtEnd()) {
+        while (ts.isAtEnd()) {
             if (ts.peek().getType() == TokenType.NEWLINE) {
                 ts.next();
                 break;
@@ -57,7 +57,7 @@ public record ParserEngine(ParserContext ctx) {
             ts.next();
         }
         // 连续空行全部吃掉
-        while (!ts.isAtEnd() && ts.peek().getType() == TokenType.NEWLINE) {
+        while (ts.isAtEnd() && ts.peek().getType() == TokenType.NEWLINE) {
             ts.next();
         }
     }
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/expression/PrattExpressionParser.java b/src/main/java/org/jcnc/snow/compiler/parser/expression/PrattExpressionParser.java
index c5529d4..4f79274 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/expression/PrattExpressionParser.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/expression/PrattExpressionParser.java
@@ -92,7 +92,7 @@ public class PrattExpressionParser implements ExpressionParser {
 
         ExpressionNode left = prefix.parse(ctx, token);
 
-        while (!ctx.getTokens().isAtEnd()
+        while (ctx.getTokens().isAtEnd()
                 && prec.ordinal() < nextPrecedence(ctx)) {
             String lex = ctx.getTokens().peek().getLexeme();
             InfixParselet infix = infixes.get(lex);

From 0a218f995e3f94a63a34eefbaf5867eff5aa0a2d Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Tue, 1 Jul 2025 11:07:30 +0800
Subject: [PATCH 19/37] =?UTF-8?q?fix:=20=E4=BF=AE=E5=A4=8D=E5=BE=AA?=
 =?UTF-8?q?=E7=8E=AF=E6=9D=A1=E4=BB=B6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../org/jcnc/snow/compiler/parser/context/TokenStream.java     | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/main/java/org/jcnc/snow/compiler/parser/context/TokenStream.java b/src/main/java/org/jcnc/snow/compiler/parser/context/TokenStream.java
index c064476..0f28737 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/context/TokenStream.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/context/TokenStream.java
@@ -10,7 +10,6 @@ import java.util.List;
  *
  * <p>提供前瞻（peek）、消费（next）、匹配（match）、断言（expect）等常用操作，
  * 支持前向查看和异常处理，适用于递归下降解析等常见语法构建策略。</p>
- *
  */
 public class TokenStream {
 
@@ -136,7 +135,7 @@ public class TokenStream {
      * @return 若当前位置 Token 为 EOF，则返回 true，否则返回 false
      */
     public boolean isAtEnd() {
-        return peek().getType() == TokenType.EOF;
+        return peek().getType() != TokenType.EOF;
     }
 
     /**

From 3bff750fc9dcbe0a3380415a8fd98fae9d8494c0 Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Tue, 1 Jul 2025 11:17:49 +0800
Subject: [PATCH 20/37] =?UTF-8?q?fix:=20=20NumberTokenScanner.java=20?=
 =?UTF-8?q?=E4=B8=AD=E4=BF=AE=E5=A4=8D=E4=BA=86=20=E2=80=9C=E6=95=B0?=
 =?UTF-8?q?=E5=AD=97=E5=AD=97=E9=9D=A2=E9=87=8F=E4=B8=8E=E7=B1=BB=E5=9E=8B?=
 =?UTF-8?q?=E5=90=8E=E7=BC=80=E4=B9=8B=E9=97=B4=E4=B8=8D=E5=85=81=E8=AE=B8?=
 =?UTF-8?q?=E6=9C=89=E7=A9=BA=E7=99=BD=E7=AC=A6=E2=80=9D=20=E7=9A=84?=
 =?UTF-8?q?=E8=AF=AF=E5=88=A4=E9=80=BB=E8=BE=91?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../lexer/scanners/NumberTokenScanner.java    | 28 +++++++------------
 1 file changed, 10 insertions(+), 18 deletions(-)

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 11eefa5..1a9b8bb 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
@@ -25,9 +25,6 @@ import org.jcnc.snow.compiler.lexer.token.TokenType;
  *      |
  *      v
  *   DEC_POINT  --digit--> FRAC_PART
- *                         |
- *                         v
- *                     else--> END
  * </pre>
  * 状态说明：
  * <ul>
@@ -139,17 +136,21 @@ public class NumberTokenScanner extends AbstractTokenScanner {
             else if (Character.isLetter(next)) {
                 throw new LexicalException("未知的数字类型后缀 '" + next + "'", line, col);
             }
-            // 2‑C. 数字后出现空白 + 字母（如 3 L）
+            // 2‑C. 数字后出现空白 + 类型后缀（如 3 f） —— 不允许
             else if (Character.isWhitespace(next) && next != '\n') {
+                // 允许数字后与普通标识符/关键字间存在空白；
+                // 仅当空白后的首个非空字符是合法的类型后缀时才报错。
                 int off = 1;
                 char look;
+                // 跳过任意空白（不含换行）
                 while (true) {
                     look = ctx.peekAhead(off);
                     if (look == '\n' || look == '\0') break; // 行尾或 EOF
                     if (!Character.isWhitespace(look)) break;
                     off++;
                 }
-                if (Character.isLetter(look)) {
+                // 如果紧跟类型后缀字符，中间存在空白则视为非法
+                if (SUFFIX_CHARS.indexOf(look) >= 0) {
                     throw new LexicalException("数字字面量与类型后缀之间不允许有空白符", line, col);
                 }
             }
@@ -162,24 +163,15 @@ public class NumberTokenScanner extends AbstractTokenScanner {
 
     /**
      * FSM 内部状态。
-     * 每次读取一个字符后，根据“当前状态 + 当前字符”决定转移。
      */
     private enum State {
-        /**
-         * 整数部分（尚未读到小数点）
-         */
+        /** 整数部分（小数点左侧） */
         INT_PART,
-        /**
-         * 已读到小数点，但还未读到第一位小数数字
-         */
+        /** 已读到小数点，但还未读到第一位小数数字 */
         DEC_POINT,
-        /**
-         * 小数部分（小数点右侧）
-         */
+        /** 小数部分（小数点右侧） */
         FRAC_PART,
-        /**
-         * 主体结束，准备处理后缀或交还控制权
-         */
+        /** 主体结束，准备处理后缀或交还控制权 */
         END
     }
 }

From 114958d99237b364eeeb94e919e6978c03a33ab5 Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Tue, 1 Jul 2025 11:28:42 +0800
Subject: [PATCH 21/37] =?UTF-8?q?chore:=20IDEA=20=E9=85=8D=E7=BD=AE?=
 =?UTF-8?q?=E6=96=87=E4=BB=B6=E4=BF=AE=E6=94=B9,=E8=AE=A9.water=E6=96=87?=
 =?UTF-8?q?=E4=BB=B6=E8=BF=9B=E5=85=A5target=E6=96=87=E4=BB=B6=E5=A4=B9?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .run/Demo10.run.xml | 2 +-
 .run/Demo2.run.xml  | 2 +-
 .run/Demo3.run.xml  | 2 +-
 .run/Demo4.run.xml  | 2 +-
 .run/Demo5.run.xml  | 2 +-
 .run/Demo6.run.xml  | 2 +-
 .run/Demo7.run.xml  | 2 +-
 .run/Demo8.run.xml  | 2 +-
 .run/Demo9.run.xml  | 2 +-
 9 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/.run/Demo10.run.xml b/.run/Demo10.run.xml
index 3d2b22a..46332d1 100644
--- a/.run/Demo10.run.xml
+++ b/.run/Demo10.run.xml
@@ -3,7 +3,7 @@
     <option name="ALTERNATIVE_JRE_PATH" value="graalvm-ce-23" />
     <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
     <module name="Snow" />
-    <option name="PROGRAM_PARAMETERS" value="compile run -d playground/Demo10" />
+    <option name="PROGRAM_PARAMETERS" value="compile run -d playground/Demo10 -o target/Demo10" />
     <extension name="coverage">
       <pattern>
         <option name="PATTERN" value="org.jcnc.snow.compiler.parser.preprocessor.lexer.impl.api.*" />
diff --git a/.run/Demo2.run.xml b/.run/Demo2.run.xml
index 0711740..464e671 100644
--- a/.run/Demo2.run.xml
+++ b/.run/Demo2.run.xml
@@ -3,7 +3,7 @@
     <option name="ALTERNATIVE_JRE_PATH" value="graalvm-ce-23" />
     <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
     <module name="Snow" />
-    <option name="PROGRAM_PARAMETERS" value="compile run -d playground/Demo2" />
+    <option name="PROGRAM_PARAMETERS" value="compile run -d playground/Demo2 -o target/Demo2" />
     <extension name="coverage">
       <pattern>
         <option name="PATTERN" value="org.jcnc.snow.compiler.parser.preprocessor.lexer.impl.api.*" />
diff --git a/.run/Demo3.run.xml b/.run/Demo3.run.xml
index a2b72da..846b27a 100644
--- a/.run/Demo3.run.xml
+++ b/.run/Demo3.run.xml
@@ -3,7 +3,7 @@
     <option name="ALTERNATIVE_JRE_PATH" value="graalvm-ce-23" />
     <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
     <module name="Snow" />
-    <option name="PROGRAM_PARAMETERS" value="compile run -d playground/Demo3" />
+    <option name="PROGRAM_PARAMETERS" value="compile run -d playground/Demo3 -o target/Demo3" />
     <extension name="coverage">
       <pattern>
         <option name="PATTERN" value="org.jcnc.snow.compiler.parser.preprocessor.lexer.impl.api.*" />
diff --git a/.run/Demo4.run.xml b/.run/Demo4.run.xml
index 491197e..8f5ba76 100644
--- a/.run/Demo4.run.xml
+++ b/.run/Demo4.run.xml
@@ -3,7 +3,7 @@
     <option name="ALTERNATIVE_JRE_PATH" value="graalvm-ce-23" />
     <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
     <module name="Snow" />
-    <option name="PROGRAM_PARAMETERS" value="compile run -d playground/Demo4" />
+    <option name="PROGRAM_PARAMETERS" value="compile run -d playground/Demo4 -o target/Demo4" />
     <extension name="coverage">
       <pattern>
         <option name="PATTERN" value="org.jcnc.snow.compiler.parser.preprocessor.lexer.impl.api.*" />
diff --git a/.run/Demo5.run.xml b/.run/Demo5.run.xml
index d3f69a3..50e1218 100644
--- a/.run/Demo5.run.xml
+++ b/.run/Demo5.run.xml
@@ -3,7 +3,7 @@
     <option name="ALTERNATIVE_JRE_PATH" value="graalvm-ce-23" />
     <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
     <module name="Snow" />
-    <option name="PROGRAM_PARAMETERS" value="compile run -d playground/Demo5" />
+    <option name="PROGRAM_PARAMETERS" value="compile run -d playground/Demo5 -o target/Demo5" />
     <extension name="coverage">
       <pattern>
         <option name="PATTERN" value="org.jcnc.snow.compiler.parser.preprocessor.lexer.impl.api.*" />
diff --git a/.run/Demo6.run.xml b/.run/Demo6.run.xml
index b7eb743..8d0f410 100644
--- a/.run/Demo6.run.xml
+++ b/.run/Demo6.run.xml
@@ -3,7 +3,7 @@
     <option name="ALTERNATIVE_JRE_PATH" value="graalvm-ce-23" />
     <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
     <module name="Snow" />
-    <option name="PROGRAM_PARAMETERS" value="compile run -d playground/Demo6" />
+    <option name="PROGRAM_PARAMETERS" value="compile run -d playground/Demo6 -o target/Demo6" />
     <extension name="coverage">
       <pattern>
         <option name="PATTERN" value="org.jcnc.snow.compiler.parser.preprocessor.lexer.impl.api.*" />
diff --git a/.run/Demo7.run.xml b/.run/Demo7.run.xml
index afa8cd9..2a2132e 100644
--- a/.run/Demo7.run.xml
+++ b/.run/Demo7.run.xml
@@ -3,7 +3,7 @@
     <option name="ALTERNATIVE_JRE_PATH" value="graalvm-ce-23" />
     <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
     <module name="Snow" />
-    <option name="PROGRAM_PARAMETERS" value="compile run -d playground/Demo7" />
+    <option name="PROGRAM_PARAMETERS" value="compile run -d playground/Demo7 -o target/Demo7" />
     <extension name="coverage">
       <pattern>
         <option name="PATTERN" value="org.jcnc.snow.compiler.parser.preprocessor.lexer.impl.api.*" />
diff --git a/.run/Demo8.run.xml b/.run/Demo8.run.xml
index 8bff503..877a106 100644
--- a/.run/Demo8.run.xml
+++ b/.run/Demo8.run.xml
@@ -3,7 +3,7 @@
     <option name="ALTERNATIVE_JRE_PATH" value="graalvm-ce-23" />
     <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
     <module name="Snow" />
-    <option name="PROGRAM_PARAMETERS" value="compile run -d playground/Demo8" />
+    <option name="PROGRAM_PARAMETERS" value="compile run -d playground/Demo8 -o target/Demo8" />
     <extension name="coverage">
       <pattern>
         <option name="PATTERN" value="org.jcnc.snow.compiler.parser.preprocessor.lexer.impl.api.*" />
diff --git a/.run/Demo9.run.xml b/.run/Demo9.run.xml
index 8e63237..764e4f2 100644
--- a/.run/Demo9.run.xml
+++ b/.run/Demo9.run.xml
@@ -3,7 +3,7 @@
     <option name="ALTERNATIVE_JRE_PATH" value="graalvm-ce-23" />
     <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
     <module name="Snow" />
-    <option name="PROGRAM_PARAMETERS" value="compile run -d playground/Demo9" />
+    <option name="PROGRAM_PARAMETERS" value="compile run -d playground/Demo9 -o target/Demo9" />
     <extension name="coverage">
       <pattern>
         <option name="PATTERN" value="org.jcnc.snow.compiler.parser.preprocessor.lexer.impl.api.*" />

From ded31578d7df8ad468c213d60e64d08bf7fc743c Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Tue, 1 Jul 2025 14:52:33 +0800
Subject: [PATCH 22/37] =?UTF-8?q?refactor:=20CommentTokenScanner=20?=
 =?UTF-8?q?=E9=87=8D=E6=9E=84=E4=B8=BA=E7=8A=B6=E6=80=81=E6=9C=BA?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../lexer/scanners/CommentTokenScanner.java   | 86 ++++++++++++-------
 1 file changed, 53 insertions(+), 33 deletions(-)

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 328dee7..90204ce 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
@@ -11,11 +11,10 @@ import org.jcnc.snow.compiler.lexer.token.TokenType;
  * <p>负责将源码中的两种注释形式切分为 {@link TokenType#COMMENT COMMENT} token：</p>
  * <ol>
  *   <li>单行注释：以 {@code //} 开头，直至行尾或文件末尾。</li>
- * 多行注释：以 {@code /*} 开头，以 <code>*&#47;</code> 结束，可跨多行。
+ *   <li>多行注释：以 {@code /*} 开头，以 <code>*&#47;</code> 结束，可跨多行。</li>
  * </ol>
  *
- * <p>本扫描器遵循“发现即捕获”原则：
- * 注释文本被完整保留在 Token 中，供后续的文档提取、源映射等分析使用。</p>
+ * <p>本扫描器遵循“发现即捕获”原则：注释文本被完整保留在 Token 中，供后续的文档提取、源映射等分析使用。</p>
  *
  * <p>错误处理策略</p>
  * <ul>
@@ -44,43 +43,64 @@ public class CommentTokenScanner extends AbstractTokenScanner {
     @Override
     protected Token scanToken(LexerContext ctx, int line, int col) {
         StringBuilder literal = new StringBuilder();
+        State currentState = State.INITIAL;
 
-        /*
-         * 1. 读取注释起始符
-         *    - 已由 canHandle 保证当前位置一定是 '/'
-         */
+        // 读取注释起始符
         literal.append(ctx.advance()); // 消费首个 '/'
 
-        // -------- 单行注释 (//) --------
-        if (ctx.match('/')) {
-            literal.append('/');
-            while (!ctx.isAtEnd() && ctx.peek() != '\n') {
-                literal.append(ctx.advance());
-            }
-            // 行尾或文件尾时退出，换行符留给上层扫描器处理。
-        }
-        // -------- 多行注释 (/* ... */) --------
-        else if (ctx.match('*')) {
-            literal.append('*');
-            boolean terminated = false;
-            while (!ctx.isAtEnd()) {
-                char ch = ctx.advance();
-                literal.append(ch);
-                if (ch == '*' && ctx.peek() == '/') {
-                    literal.append(ctx.advance()); // 追加 '/'
-                    terminated = true;
+        while (!ctx.isAtEnd()) {
+            switch (currentState) {
+                case INITIAL:
+                    if (ctx.match('/')) {
+                        literal.append('/');
+                        currentState = State.SINGLE_LINE;
+                    } else if (ctx.match('*')) {
+                        literal.append('*');
+                        currentState = State.MULTI_LINE;
+                    }
                     break;
-                }
-            }
-            if (!terminated) {
-                // 文件结束仍未闭合，抛 LexicalException
-                throw new LexicalException("未终止的多行注释", line, col);
+
+                case SINGLE_LINE:
+                    // 单行注释处理：读取直到行尾
+                    if (ctx.isAtEnd() || ctx.peek() == '\n') {
+                        // 如果遇到换行符，停止读取并返回注释内容
+                        return new Token(TokenType.COMMENT, literal.toString(), line, col);
+                    } else {
+                        literal.append(ctx.advance());  // 继续读取注释内容
+                    }
+                    break;
+
+
+                case MULTI_LINE:
+                    // 多行注释处理
+                    char ch = ctx.advance();
+                    literal.append(ch);
+                    if (ch == '*' && ctx.peek() == '/') {
+                        literal.append(ctx.advance()); // 追加 '/'
+                        currentState = State.MULTI_LINE_END;
+                    }
+                    break;
+
+                case MULTI_LINE_END:
+                    // 已经读取了闭合的 "*/"
+                    return new Token(TokenType.COMMENT, literal.toString(), line, col);
             }
         }
 
-        /*
-         * 2. 生成并返回 Token
-         */
+        // 如果未终止的多行注释，抛出异常
+        if (currentState == State.MULTI_LINE) {
+            throw new LexicalException("未终止的多行注释", line, col);
+        }
+
+        // 在正常情况下返回生成的注释 Token
         return new Token(TokenType.COMMENT, literal.toString(), line, col);
     }
+
+    // 定义状态
+    private enum State {
+        INITIAL,    // 初始状态
+        SINGLE_LINE, // 单行注释状态
+        MULTI_LINE,  // 多行注释状态
+        MULTI_LINE_END // 多行注释结束状态
+    }
 }

From b43245b1f58814937abac26a9ee1a31bf38f8485 Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Tue, 1 Jul 2025 17:02:01 +0800
Subject: [PATCH 23/37] =?UTF-8?q?refactor:=20IdentifierTokenScanner=20?=
 =?UTF-8?q?=E9=87=8D=E6=9E=84=E4=B8=BA=E7=8A=B6=E6=80=81=E6=9C=BA?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../scanners/IdentifierTokenScanner.java      | 82 ++++++++++++++-----
 1 file changed, 63 insertions(+), 19 deletions(-)

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 633d834..1e18cbb 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,30 +1,34 @@
 package org.jcnc.snow.compiler.lexer.scanners;
 
 import org.jcnc.snow.compiler.lexer.core.LexerContext;
+import org.jcnc.snow.compiler.lexer.core.LexicalException;
 import org.jcnc.snow.compiler.lexer.token.Token;
 import org.jcnc.snow.compiler.lexer.token.TokenFactory;
+import org.jcnc.snow.compiler.lexer.token.TokenType;
 
 /**
- * 标识符扫描器：处理标识符的识别，如变量名、函数名等。
- * <p>
- * 识别规则如下：
+ * {@code IdentifierTokenScanner} —— 标识符扫描器，负责识别源代码中的标识符（如变量名、函数名等）。
+ *
+ * <p>标识符的识别遵循以下规则：</p>
  * <ul>
- *     <li>必须以字母或下划线（_）开头</li>
- *     <li>后续字符可以是字母、数字或下划线</li>
+ *     <li>标识符必须以字母（A-Z，a-z）或下划线（_）开头。</li>
+ *     <li>标识符的后续字符可以是字母、数字（0-9）或下划线。</li>
  * </ul>
- * <p>
- * 扫描完成后会调用 {@link TokenFactory} 自动判断是否为关键字，
- * 并返回对应类型的 {@link Token}。
+ *
+ * <p>在扫描过程中，标识符会被处理为一个 {@link Token} 对象。如果该标识符是一个关键字，
+ * 扫描器会通过 {@link TokenFactory} 自动识别并返回相应的 {@link TokenType}。</p>
+ *
+ * <p>本扫描器实现了一个有限状态机（FSM），它能够在不同状态之间转换，确保标识符的正确识别。</p>
  */
 public class IdentifierTokenScanner extends AbstractTokenScanner {
 
     /**
-     * 判断是否可以处理当前位置的字符。
-     * <p>如果字符为字母或下划线，则认为是标识符的起始。</p>
+     * 判断当前字符是否可以作为标识符的起始字符。
+     * <p>如果字符为字母或下划线，则认为是标识符的开始。</p>
      *
      * @param c   当前字符
      * @param ctx 当前词法上下文
-     * @return 如果是标识符起始字符，则返回 true
+     * @return 如果字符是标识符的起始字符，则返回 {@code true}；否则返回 {@code false}。
      */
     @Override
     public boolean canHandle(char c, LexerContext ctx) {
@@ -32,17 +36,57 @@ public class IdentifierTokenScanner extends AbstractTokenScanner {
     }
 
     /**
-     * 执行标识符的扫描逻辑。
-     * <p>连续读取满足标识符规则的字符序列，交由 {@code TokenFactory} 创建对应的 Token。</p>
+     * 执行标识符扫描。
+     * <p>使用状态机模式扫描标识符。首先从初始状态开始，读取标识符的起始字符（字母或下划线）。
+     * 然后，进入标识符状态，继续读取标识符字符（字母、数字或下划线）。一旦遇到不符合标识符规则的字符，
+     * 标识符扫描结束，返回一个 {@link Token}。</p>
      *
-     * @param ctx  词法上下文
-     * @param line 当前行号
-     * @param col  当前列号
-     * @return 标识符或关键字类型的 Token
+     * @param ctx  词法上下文，用于获取字符流
+     * @param line 当前行号（1 基）
+     * @param col  当前列号（1 基）
+     * @return 返回一个包含标识符或关键字的 {@link Token} 对象。
+     * @throws LexicalException 如果标识符以非法字符（如点号）开头，则抛出异常
      */
     @Override
     protected Token scanToken(LexerContext ctx, int line, int col) {
-        String lexeme = readWhile(ctx, ch -> Character.isLetterOrDigit(ch) || ch == '_');
-        return TokenFactory.create(lexeme, line, col);
+        StringBuilder lexeme = new StringBuilder(); // 用于构建标识符的字符串
+        State currentState = State.INITIAL; // 初始状态
+
+        // 遍历字符流，直到遇到不合法的字符或流结束
+        while (!ctx.isAtEnd()) {
+            char currentChar = ctx.peek(); // 获取当前字符
+            switch (currentState) {
+                case INITIAL:
+                    // 初始状态，标识符开始
+                    if (Character.isLetter(currentChar) || currentChar == '_') {
+                        lexeme.append(ctx.advance()); // 接受当前字符
+                        currentState = State.IDENTIFIER; // 进入标识符状态
+                    } else {
+                        return null; // 当前字符不符合标识符的规则，返回 null
+                    }
+                    break;
+
+                case IDENTIFIER:
+                    // 标识符状态，继续读取合法标识符字符
+                    if (Character.isLetterOrDigit(currentChar) || currentChar == '_') {
+                        lexeme.append(ctx.advance()); // 继续接受合法字符
+                    } else {
+                        // 当前字符不符合标识符的规则，标识符结束，返回 token
+                        return TokenFactory.create(lexeme.toString(), line, col);
+                    }
+                    break;
+            }
+        }
+
+        // 如果字符流结束，返回标识符 token
+        return TokenFactory.create(lexeme.toString(), line, col);
+    }
+
+    /**
+     * 枚举类型表示标识符扫描的状态。
+     */
+    private enum State {
+        INITIAL,  // 初始状态，等待标识符的开始
+        IDENTIFIER // 标识符状态，继续读取标识符字符
     }
 }

From e83244df61f3791da4e24b866e5f40b7d496acc1 Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Tue, 1 Jul 2025 17:02:35 +0800
Subject: [PATCH 24/37] =?UTF-8?q?feat:=20LexerEngine=20=E5=A2=9E=E5=8A=A0?=
 =?UTF-8?q?=E5=90=8E=E7=BD=AE=E6=95=B4=E4=BD=93=E6=A0=A1=E9=AA=8C?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../snow/compiler/lexer/core/LexerEngine.java | 221 +++++++++---------
 1 file changed, 106 insertions(+), 115 deletions(-)

diff --git a/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java b/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java
index 5df39fa..6d6bb2f 100644
--- a/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java
+++ b/src/main/java/org/jcnc/snow/compiler/lexer/core/LexerEngine.java
@@ -3,6 +3,7 @@ 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;
+import org.jcnc.snow.compiler.lexer.token.TokenType;
 import org.jcnc.snow.compiler.lexer.utils.TokenPrinter;
 
 import java.io.File;
@@ -10,154 +11,144 @@ import java.util.ArrayList;
 import java.util.List;
 
 /**
- * {@code LexerEngine} 是编译器前端的词法分析器核心实现。
- * <p>
- * 负责将源代码字符串按顺序扫描并转换为一系列 {@link Token} 实例，
- * 每个 Token 表示语法上可识别的最小单位（如标识符、关键字、常量、运算符等）。
- * <p>
- * 分析流程通过注册多个 {@link TokenScanner} 扫描器实现类型识别，
- * 并由 {@link LexerContext} 提供字符流与位置信息支持。
- * 支持文件名传递，遇到非法字符时会以“文件名:行:列:错误信息”输出简洁诊断。
- * </p>
+ * Snow 语言词法分析器核心实现。
+ * <p>采用“<b>先扫描 → 后批量校验 → 统一报告</b>”策略：
+ * <ol>
+ *   <li>{@link #scanAllTokens()}— 用扫描器链把字符流拆成 {@link Token}</li>
+ *   <li>{@link #validateTokens()}— 基于 token 序列做轻量上下文校验</li>
+ *   <li>{@link #report(List)}— 一次性输出所有词法错误</li>
+ * </ol></p>
  */
 public class LexerEngine {
-    /**
-     * 扫描生成的 Token 序列（包含文件结束符 EOF）。
-     * 每个 Token 表示源代码中的一个词法单元。
-     */
-    private final List<Token> tokens = new ArrayList<>();
+
+    private final List<Token> tokens  = new ArrayList<>();   // 扫描结果
+    private final List<LexicalError> errors  = new ArrayList<>();
+    private final String  absPath;                           // 绝对路径
+    private final LexerContext context;                      // 字符流
+    private final List<TokenScanner> scanners;               // 扫描器链
 
     /**
-     * 当前源文件的绝对路径，用于错误信息定位。
-     */
-    private final String absPath;
-
-    /**
-     * 词法上下文，负责字符流读取与位置信息维护。
-     */
-    private final LexerContext context;
-
-    /**
-     * Token 扫描器集合，按优先级顺序排列，
-     * 用于识别不同类别的 Token（如空白、注释、数字、标识符等）。
-     */
-    private final List<TokenScanner> scanners;
-
-    /**
-     * 词法分析过程中收集到的全部词法错误。
-     */
-    private final List<LexicalError> errors = new ArrayList<>();
-
-    /**
-     * 构造词法分析器，并指定源文件名（用于诊断信息）。
-     * 构造时立即进行全量扫描，扫描结束后打印所有 Token 并报告词法错误。
-     *
+     * 创建并立即执行扫描-校验-报告流程。
      * @param source     源代码文本
-     * @param sourceName 文件名或来源描述（如"Main.snow"）
+     * @param sourceName 文件名（诊断用）
      */
     public LexerEngine(String source, String sourceName) {
-        this.absPath = new File(sourceName).getAbsolutePath();
-        this.context = new LexerContext(source);
+        this.absPath  = new File(sourceName).getAbsolutePath();
+        this.context  = new LexerContext(source);
         this.scanners = List.of(
-                new WhitespaceTokenScanner(), // 跳过空格、制表符等
-                new NewlineTokenScanner(),    // 处理换行符，生成 NEWLINE Token
-                new CommentTokenScanner(),    // 处理单行/多行注释
-                new NumberTokenScanner(),     // 识别整数与浮点数字面量
-                new IdentifierTokenScanner(), // 识别标识符和关键字
-                new StringTokenScanner(),     // 处理字符串常量
-                new OperatorTokenScanner(),   // 识别运算符
-                new SymbolTokenScanner(),     // 识别括号、分号等符号
-                new UnknownTokenScanner()     // 捕捉无法识别的字符，最后兜底
+                new WhitespaceTokenScanner(),
+                new NewlineTokenScanner(),
+                new CommentTokenScanner(),
+                new NumberTokenScanner(),
+                new IdentifierTokenScanner(),
+                new StringTokenScanner(),
+                new OperatorTokenScanner(),
+                new SymbolTokenScanner(),
+                new UnknownTokenScanner()
         );
 
-        // 主扫描流程，遇到非法字符立即输出错误并终止进程
-        try {
-            scanAllTokens();
-        } catch (LexicalException le) {
-            // 输出：绝对路径: 行 x, 列 y: 错误信息
-            System.err.printf(
-                    "%s: 行 %d, 列 %d: %s%n",
-                    absPath,
-                    le.getLine(),
-                    le.getColumn(),
-                    le.getReason()
-            );
-            System.exit(65); // 65 = EX_DATAERR
-        }
-        TokenPrinter.print(this.tokens);
-        LexerEngine.report(this.getErrors());
+        /* 1. 扫描 */
+        scanAllTokens();
+        /* 2. 后置整体校验 */
+        validateTokens();
+        /* 3. 打印 token */
+        TokenPrinter.print(tokens);
+        /* 4. 统一报告错误 */
+        report(errors);
         if (!errors.isEmpty()) {
-            throw new LexicalException("Lexing failed with " + errors.size() + " error(s).", this.context.getLine(), this.context.getCol());
+            throw new LexicalException(
+                    "Lexing failed with " + errors.size() + " error(s).",
+                    context.getLine(), context.getCol()
+            );
         }
     }
 
-    /**
-     * 静态报告方法。
-     * <p>
-     * 打印所有词法分析过程中收集到的错误信息。
-     * 如果无错误，输出词法分析通过的提示。
-     *
-     * @param errors 词法错误列表
-     */
     public static void report(List<LexicalError> errors) {
-        if (errors != null && !errors.isEmpty()) {
-            System.err.println("\n词法分析发现 " + errors.size() + " 个错误：");
-            errors.forEach(err -> System.err.println("  " + err));
-        } else {
+        if (errors == null || errors.isEmpty()) {
             System.out.println("\n## 词法分析通过，没有发现错误\n");
+            return;
         }
+        System.err.println("\n词法分析发现 " + errors.size() + " 个错误：");
+        errors.forEach(e -> System.err.println("  " + e));
     }
 
+    public List<Token> getAllTokens() { return List.copyOf(tokens); }
+    public List<LexicalError> getErrors() { return List.copyOf(errors); }
+
     /**
-     * 主扫描循环，将源代码转为 Token 序列。
-     * <p>
-     * 依次尝试每个扫描器，直到找到可处理当前字符的扫描器为止。
-     * 扫描到结尾后补充 EOF Token。
-     * 若遇到词法异常则收集错误并跳过当前字符，避免死循环。
+     * 逐字符扫描：依次尝试各扫描器；扫描器抛出的
+     * {@link LexicalException} 被捕获并转为 {@link LexicalError}。
      */
     private void scanAllTokens() {
         while (!context.isAtEnd()) {
-            char currentChar = context.peek();
+            char ch = context.peek();
             boolean handled = false;
-            for (TokenScanner scanner : scanners) {
-                if (scanner.canHandle(currentChar, context)) {
-                    try {
-                        scanner.handle(context, tokens);
-                    } catch (LexicalException le) {
-                        // 收集词法错误，不直接退出
-                        errors.add(new LexicalError(
-                                absPath, le.getLine(), le.getColumn(), le.getReason()
-                        ));
-                        // 跳过当前字符，防止死循环
-                        context.advance();
-                    }
-                    handled = true;
-                    break;
+
+            for (TokenScanner s : scanners) {
+                if (!s.canHandle(ch, context)) continue;
+
+                try {
+                    s.handle(context, tokens);
+                } catch (LexicalException le) {
+                    errors.add(new LexicalError(
+                            absPath, le.getLine(), le.getColumn(), le.getReason()
+                    ));
+                    context.advance();           // 跳过问题字符
                 }
+                handled = true;
+                break;
             }
-            if (!handled) {
-                // 没有任何扫描器能处理，跳过一个字符防止死循环
-                context.advance();
-            }
+
+            if (!handled) context.advance();     // 理论不会走到，保险
         }
         tokens.add(Token.eof(context.getLine()));
     }
 
     /**
-     * 获取全部 Token（包含 EOF），返回只读列表。
-     *
-     * @return 词法分析结果 Token 列表
+     * 目前包含三条规则：<br>
+     * 1. Dot-Prefix'.' 不能作标识符前缀<br>
+     * 2. Declare-Ident declare 后必须紧跟合法标识符，并且只能一个<br>
+     * 3. Double-Ident declare 后若出现第二个 IDENTIFIER 视为多余<br>
+     * <p>发现问题仅写入 {@link #errors}，不抛异常。</p>
      */
-    public List<Token> getAllTokens() {
-        return List.copyOf(tokens);
+    private void validateTokens() {
+        for (int i = 0; i < tokens.size(); i++) {
+            Token tok = tokens.get(i);
+
+            /* ---------- declare 规则 ---------- */
+            if (tok.getType() == TokenType.KEYWORD
+                    && "declare".equalsIgnoreCase(tok.getLexeme())) {
+
+                // 第一个非 NEWLINE token
+                Token id1 = findNextNonNewline(i);
+                if (id1 == null || id1.getType() != TokenType.IDENTIFIER) {
+                    errors.add(err(
+                            (id1 == null ? tok : id1),
+                            "declare 后必须跟合法标识符 (以字母或 '_' 开头)"
+                    ));
+                    continue; // 若首标识符就错，后续检查可略
+                }
+
+                // 检查是否有第二个 IDENTIFIER
+                Token id2 = findNextNonNewline(tokens.indexOf(id1));
+                if (id2 != null && id2.getType() == TokenType.IDENTIFIER) {
+                    errors.add(err(id2, "declare 声明中出现多余的标识符"));
+                }
+            }
+        }
     }
 
-    /**
-     * 返回全部词法错误（返回只读列表）。
-     *
-     * @return 词法错误列表
-     */
-    public List<LexicalError> getErrors() {
-        return List.copyOf(errors);
+    /** index 右侧最近非 NEWLINE token；无则 null */
+    private Token findNextNonNewline(int index) {
+        for (int j = index + 1; j < tokens.size(); j++) {
+            Token t = tokens.get(j);
+            if (t.getType() != TokenType.NEWLINE) return t;
+        }
+        return null;
+    }
+
+    /** 构造统一的 LexicalError */
+    private LexicalError err(Token t, String msg) {
+        return new LexicalError(absPath, t.getLine(), t.getCol(), "非法的标记序列：" + msg);
     }
 }

From 51f5ba9884f3c0365c1967840c4a79ec8eb0b4ea Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Tue, 1 Jul 2025 17:09:52 +0800
Subject: [PATCH 25/37] =?UTF-8?q?test:=20=E6=9B=B4=E6=96=B0demo11?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 playground/Demo11/Main.snow | 1 -
 1 file changed, 1 deletion(-)

diff --git a/playground/Demo11/Main.snow b/playground/Demo11/Main.snow
index d9a3e6e..3dd121d 100644
--- a/playground/Demo11/Main.snow
+++ b/playground/Demo11/Main.snow
@@ -1,7 +1,6 @@
 function: main
     return_type: int
     body:
-        3 L
         return 65537
     end body
 end function
\ No newline at end of file

From dbc3ea0a33dd6aecca66d2d8083b516f366d1452 Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Tue, 1 Jul 2025 17:10:11 +0800
Subject: [PATCH 26/37] =?UTF-8?q?feat:=20NewlineTokenScanner=20=E9=87=8D?=
 =?UTF-8?q?=E6=9E=84=E4=B8=BA=E7=8A=B6=E6=80=81=E6=9C=BA?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../lexer/scanners/NewlineTokenScanner.java   | 27 ++++++++++++++++---
 1 file changed, 23 insertions(+), 4 deletions(-)

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 daea57c..0f63e70 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
@@ -7,10 +7,19 @@ import org.jcnc.snow.compiler.lexer.token.TokenType;
 /**
  * 换行符扫描器：将源代码中的换行符（\n）识别为 {@code NEWLINE} 类型的 Token。
  * <p>
- * 通常用于记录行的分界，辅助语法分析阶段进行行敏感的判断或保持结构清晰。
+ * 用于记录行的分界，辅助语法分析阶段进行行敏感的判断或保持结构清晰。
  */
 public class NewlineTokenScanner extends AbstractTokenScanner {
 
+    // 定义状态枚举
+    private enum State {
+        INITIAL,
+        NEWLINE
+    }
+
+    // 当前状态
+    private State currentState = State.INITIAL;
+
     /**
      * 判断是否可以处理当前位置的字符。
      * <p>当字符为换行符（\n）时返回 true。</p>
@@ -21,7 +30,8 @@ public class NewlineTokenScanner extends AbstractTokenScanner {
      */
     @Override
     public boolean canHandle(char c, LexerContext ctx) {
-        return c == '\n';
+        // 只有当处于 INITIAL 状态，并且遇到换行符时，才可以处理
+        return currentState == State.INITIAL && c == '\n';
     }
 
     /**
@@ -35,7 +45,16 @@ public class NewlineTokenScanner extends AbstractTokenScanner {
      */
     @Override
     protected Token scanToken(LexerContext ctx, int line, int col) {
+        // 状态转换为 NEWLINE
+        currentState = State.NEWLINE;
+
+        // 执行换行符扫描，生成 token
         ctx.advance();
-        return new Token(TokenType.NEWLINE, "\n", line, col);
+        Token newlineToken = new Token(TokenType.NEWLINE, "\n", line, col);
+
+        // 扫描完成后，恢复状态为 INITIAL
+        currentState = State.INITIAL;
+
+        return newlineToken;
     }
-}
\ No newline at end of file
+}

From 367ae8653ed43af506b22ca5ba9efad165529abf Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Tue, 1 Jul 2025 17:14:40 +0800
Subject: [PATCH 27/37] =?UTF-8?q?feat:=20OperatorTokenScanner=20=E9=87=8D?=
 =?UTF-8?q?=E6=9E=84=E4=B8=BA=E7=8A=B6=E6=80=81=E6=9C=BA?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../lexer/scanners/OperatorTokenScanner.java  | 56 ++++++++++---------
 1 file changed, 30 insertions(+), 26 deletions(-)

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 ec2f2bf..951b1c5 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
@@ -45,80 +45,84 @@ public class OperatorTokenScanner extends AbstractTokenScanner {
     @Override
     protected Token scanToken(LexerContext ctx, int line, int col) {
         char c = ctx.advance();
-        String lexeme;
-        TokenType type;
+        String lexeme = String.valueOf(c);
+        TokenType type = TokenType.UNKNOWN;
+
+        // 当前状态
+        State currentState = State.OPERATOR;
 
         switch (c) {
             case '=':
                 if (ctx.match('=')) {
                     lexeme = "==";
-                    type   = TokenType.DOUBLE_EQUALS;
+                    type = TokenType.DOUBLE_EQUALS;
                 } else {
-                    lexeme = "=";
-                    type   = TokenType.EQUALS;
+                    type = TokenType.EQUALS;
                 }
                 break;
 
             case '!':
                 if (ctx.match('=')) {
                     lexeme = "!=";
-                    type   = TokenType.NOT_EQUALS;
+                    type = TokenType.NOT_EQUALS;
                 } else {
-                    lexeme = "!";
-                    type   = TokenType.NOT;
+                    type = TokenType.NOT;
                 }
                 break;
 
             case '>':
                 if (ctx.match('=')) {
                     lexeme = ">=";
-                    type   = TokenType.GREATER_EQUAL;
+                    type = TokenType.GREATER_EQUAL;
                 } else {
-                    lexeme = ">";
-                    type   = TokenType.GREATER_THAN;
+                    type = TokenType.GREATER_THAN;
                 }
                 break;
 
             case '<':
                 if (ctx.match('=')) {
                     lexeme = "<=";
-                    type   = TokenType.LESS_EQUAL;
+                    type = TokenType.LESS_EQUAL;
                 } else {
-                    lexeme = "<";
-                    type   = TokenType.LESS_THAN;
+                    type = TokenType.LESS_THAN;
                 }
                 break;
 
             case '%':
-                lexeme = "%";
-                type   = TokenType.MODULO;
+                type = TokenType.MODULO;
                 break;
 
             case '&':
                 if (ctx.match('&')) {
                     lexeme = "&&";
-                    type   = TokenType.AND;
-                } else {
-                    lexeme = "&";
-                    type   = TokenType.UNKNOWN;
+                    type = TokenType.AND;
                 }
                 break;
 
             case '|':
                 if (ctx.match('|')) {
                     lexeme = "||";
-                    type   = TokenType.OR;
-                } else {
-                    lexeme = "|";
-                    type   = TokenType.UNKNOWN;
+                    type = TokenType.OR;
                 }
                 break;
 
             default:
-                lexeme = String.valueOf(c);
-                type   = TokenType.UNKNOWN;
+                currentState = State.UNKNOWN;
+                break;
+        }
+
+        // 执行完扫描后，重置状态为初始状态
+        if (currentState != State.UNKNOWN) {
+            currentState = State.START;
         }
 
         return new Token(type, lexeme, line, col);
     }
+
+    // 定义状态枚举
+    private enum State {
+        START,        // 初始状态
+        OPERATOR,     // 当前字符是运算符的一部分
+        UNKNOWN       // 无法识别的状态
+    }
 }

From bb4c4f6ce4b49661c9621ca3605b7cf73052ebff Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Tue, 1 Jul 2025 17:17:23 +0800
Subject: [PATCH 28/37] =?UTF-8?q?feat:=20StringTokenScanner=20=E9=87=8D?=
 =?UTF-8?q?=E6=9E=84=E4=B8=BA=E7=8A=B6=E6=80=81=E6=9C=BA?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../lexer/scanners/StringTokenScanner.java    | 44 ++++++++++++++++---
 1 file changed, 38 insertions(+), 6 deletions(-)

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 a8643e4..a610d06 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
@@ -29,7 +29,7 @@ public class StringTokenScanner extends AbstractTokenScanner {
      */
     @Override
     public boolean canHandle(char c, LexerContext ctx) {
-        return c == '"';
+        return c == '"';  // 只处理字符串开始符号
     }
 
     /**
@@ -45,19 +45,51 @@ public class StringTokenScanner extends AbstractTokenScanner {
     @Override
     protected Token scanToken(LexerContext ctx, int line, int col) {
         StringBuilder sb = new StringBuilder();
-        sb.append(ctx.advance()); // 起始双引号
+        // 当前状态
+        State currentState = State.START;  // 初始状态为开始扫描字符串
 
+        // 开始扫描字符串
         while (!ctx.isAtEnd()) {
             char c = ctx.advance();
             sb.append(c);
 
-            if (c == '\\') {
-                sb.append(ctx.advance()); // 添加转义字符后的实际字符
-            } else if (c == '"') {
-                break;
+            switch (currentState) {
+                case START:
+                    // 开始状态，遇到第一个双引号
+                    currentState = State.STRING;
+                    break;
+
+                case STRING:
+                    if (c == '\\') {
+                        // 遇到转义字符，进入 ESCAPE 状态
+                        currentState = State.ESCAPE;
+                    } else if (c == '"') {
+                        // 遇到结束的双引号，结束扫描
+                        currentState = State.END;
+                    }
+                    break;
+
+                case ESCAPE:
+                    // 在转义状态下，处理转义字符
+                    sb.append(ctx.advance());  // 加入转义字符后的字符
+                    currentState = State.STRING;  // 返回字符串状态
+                    break;
+
+                case END:
+                    // 结束状态，字符串扫描完成
+                    return new Token(TokenType.STRING_LITERAL, sb.toString(), line, col);
             }
         }
 
+        // 如果没有结束的双引号，则表示错误，或者未正确处理
         return new Token(TokenType.STRING_LITERAL, sb.toString(), line, col);
     }
+
+    // 定义状态枚举
+    private enum State {
+        START,    // 开始状态，寻找字符串的开始双引号
+        STRING,   // 字符串扫描状态，处理字符串中的字符
+        ESCAPE,   // 处理转义字符状态
+        END       // 字符串结束状态
+    }
 }

From b730b53f7b643b56853748f5db46ce35091c88c9 Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Thu, 3 Jul 2025 21:56:33 +0800
Subject: [PATCH 29/37] =?UTF-8?q?style:=20=E4=BF=AE=E5=A4=8D=E4=BB=A3?=
 =?UTF-8?q?=E7=A0=81=E7=BC=A9=E8=BF=9B=E5=BC=82=E5=B8=B8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../org/jcnc/snow/compiler/parser/ast/CallExpressionNode.java | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/main/java/org/jcnc/snow/compiler/parser/ast/CallExpressionNode.java b/src/main/java/org/jcnc/snow/compiler/parser/ast/CallExpressionNode.java
index 22f47bc..d7dbce9 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/ast/CallExpressionNode.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/ast/CallExpressionNode.java
@@ -67,5 +67,7 @@ public record CallExpressionNode(
      *
      * @return 当前表达式所在的文件名。
      */
-    public String file()   { return file;   }
+    public String file() {
+        return file;
+    }
 }

From f1086a1ef925b898bf413fff1403adff881e3859 Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Thu, 3 Jul 2025 23:49:26 +0800
Subject: [PATCH 30/37] =?UTF-8?q?feat:=20=E7=BB=9F=E4=B8=80=20parser=20?=
 =?UTF-8?q?=E7=9A=84=E5=BC=82=E5=B8=B8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../compiler/parser/context/MissingToken.java |  11 ++
 .../parser/context/ParseException.java        |  21 ++-
 .../compiler/parser/context/TokenStream.java  |  10 +-
 .../parser/context/UnexpectedToken.java       |  11 ++
 .../parser/context/UnsupportedFeature.java    |  11 ++
 .../compiler/parser/core/ParserEngine.java    |  59 ++++++--
 .../expression/PrattExpressionParser.java     |   8 +-
 .../compiler/parser/module/ModuleParser.java  |   5 +-
 .../statement/ExpressionStatementParser.java  |   5 +-
 .../parser/top/ScriptTopLevelParser.java      |   3 +-
 .../parser/utils/FlexibleSectionParser.java   |   5 +-
 .../compiler/parser/utils/JSONParser.java     | 131 ++++++++++++------
 12 files changed, 205 insertions(+), 75 deletions(-)
 create mode 100644 src/main/java/org/jcnc/snow/compiler/parser/context/MissingToken.java
 create mode 100644 src/main/java/org/jcnc/snow/compiler/parser/context/UnexpectedToken.java
 create mode 100644 src/main/java/org/jcnc/snow/compiler/parser/context/UnsupportedFeature.java

diff --git a/src/main/java/org/jcnc/snow/compiler/parser/context/MissingToken.java b/src/main/java/org/jcnc/snow/compiler/parser/context/MissingToken.java
new file mode 100644
index 0000000..b56ae02
--- /dev/null
+++ b/src/main/java/org/jcnc/snow/compiler/parser/context/MissingToken.java
@@ -0,0 +1,11 @@
+package org.jcnc.snow.compiler.parser.context;
+
+/**
+ * 当语法结构缺失必须出现的 Token 时抛出。
+ */
+public final class MissingToken extends ParseException {
+
+    public MissingToken(String message) {
+        super(message);
+    }
+}
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/context/ParseException.java b/src/main/java/org/jcnc/snow/compiler/parser/context/ParseException.java
index 0313d7a..0262868 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/context/ParseException.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/context/ParseException.java
@@ -1,22 +1,19 @@
 package org.jcnc.snow.compiler.parser.context;
 
 /**
- * {@code ParseException} 表示语法分析阶段发生的错误。
- * <p>
- * 当语法分析器遇到非法的语法结构或无法继续处理的标记序列时，
- * 应抛出该异常以中断当前解析流程，并向调用方报告错误信息。
- * </p>
- * <p>
- * 该异常通常由 {@code ParserContext} 或各类语法规则处理器主动抛出，
- * 用于提示编译器前端或 IDE 系统进行错误提示与恢复。
- * </p>
+ * {@code ParseException}——语法分析阶段所有错误的基类。
+ *
+ * <p>声明为 <em>sealed</em>，仅允许 {@link UnexpectedToken}、
+ * {@link MissingToken}、{@link UnsupportedFeature} 三个受信子类继承，
+ * 以便调用方根据异常类型进行精确处理。</p>
  */
-public class ParseException extends RuntimeException {
+public sealed class ParseException extends RuntimeException
+        permits UnexpectedToken, MissingToken, UnsupportedFeature {
 
     /**
-     * 构造一个带有错误描述信息的解析异常实例。
+     * 构造解析异常并附带错误消息。
      *
-     * @param message 错误描述文本，用于指明具体的语法错误原因
+     * @param message 错误描述
      */
     public ParseException(String message) {
         super(message);
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/context/TokenStream.java b/src/main/java/org/jcnc/snow/compiler/parser/context/TokenStream.java
index 0f28737..9169318 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/context/TokenStream.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/context/TokenStream.java
@@ -31,7 +31,7 @@ public class TokenStream {
      */
     public TokenStream(List<Token> tokens) {
         if (tokens == null) {
-            throw new NullPointerException("Token list cannot be null.");
+            throw new NullPointerException("Token 列表不能为空");
         }
         this.tokens = tokens;
     }
@@ -103,8 +103,8 @@ public class TokenStream {
         Token t = peek();
         if (!t.getLexeme().equals(lexeme)) {
             throw new ParseException(
-                    "Expected lexeme '" + lexeme + "' but got '" + t.getLexeme() +
-                            "' at " + t.getLine() + ":" + t.getCol()
+                    "期望的词素是'" + lexeme + "'，但得到的是'" + t.getLexeme() +
+                            "在" + t.getLine() + ":" + t.getCol()
             );
         }
         return next();
@@ -122,8 +122,8 @@ public class TokenStream {
         Token t = peek();
         if (t.getType() != type) {
             throw new ParseException(
-                    "Expected token type " + type + " but got " + t.getType() +
-                            " ('" + t.getLexeme() + "') at " + t.getLine() + ":" + t.getCol()
+                    "期望的标记类型为 " + type + " 但实际得到的是 " + t.getType() +
+                            " ('" + t.getLexeme() + "') 在 " + t.getLine() + ":" + t.getCol()
             );
         }
         return next();
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/context/UnexpectedToken.java b/src/main/java/org/jcnc/snow/compiler/parser/context/UnexpectedToken.java
new file mode 100644
index 0000000..bfa5ecd
--- /dev/null
+++ b/src/main/java/org/jcnc/snow/compiler/parser/context/UnexpectedToken.java
@@ -0,0 +1,11 @@
+package org.jcnc.snow.compiler.parser.context;
+
+/**
+ * 当解析过程中遇到意料之外或无法识别的 Token 时抛出。
+ */
+public final class UnexpectedToken extends ParseException {
+
+    public UnexpectedToken(String message) {
+        super(message);
+    }
+}
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/context/UnsupportedFeature.java b/src/main/java/org/jcnc/snow/compiler/parser/context/UnsupportedFeature.java
new file mode 100644
index 0000000..558f32a
--- /dev/null
+++ b/src/main/java/org/jcnc/snow/compiler/parser/context/UnsupportedFeature.java
@@ -0,0 +1,11 @@
+package org.jcnc.snow.compiler.parser.context;
+
+/**
+ * 当源码使用了当前编译器尚未支持的语言特性或语法时抛出。
+ */
+public final class UnsupportedFeature extends ParseException {
+
+    public UnsupportedFeature(String message) {
+        super(message);
+    }
+}
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/core/ParserEngine.java b/src/main/java/org/jcnc/snow/compiler/parser/core/ParserEngine.java
index 7d0854f..c5bfb36 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/core/ParserEngine.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/core/ParserEngine.java
@@ -1,24 +1,58 @@
 package org.jcnc.snow.compiler.parser.core;
 
 import org.jcnc.snow.compiler.lexer.token.TokenType;
+import org.jcnc.snow.compiler.parser.ast.base.Node;
 import org.jcnc.snow.compiler.parser.base.TopLevelParser;
 import org.jcnc.snow.compiler.parser.context.ParserContext;
 import org.jcnc.snow.compiler.parser.context.TokenStream;
+import org.jcnc.snow.compiler.parser.context.UnexpectedToken;
 import org.jcnc.snow.compiler.parser.factory.TopLevelParserFactory;
-import org.jcnc.snow.compiler.parser.ast.base.Node;
 
 import java.util.ArrayList;
 import java.util.List;
+import java.util.StringJoiner;
 
+/**
+ * 语法解析引擎（ParserEngine）。
+ * <p>
+ * 负责驱动 Snow 源码的顶层语法结构解析，将源码 TokenStream
+ * 递交给各类 TopLevelParser，并收集语法树节点与异常。
+ * 支持容错解析，能够批量报告所有语法错误，并提供同步恢复功能。
+ * </p>
+ *
+ * <p>
+ * 典型用法：
+ * <pre>
+ *     ParserEngine engine = new ParserEngine(context);
+ *     List&lt;Node&gt; ast = engine.parse();
+ * </pre>
+ * </p>
+ *
+ * @param ctx 解析器上下文，负责持有 TokenStream 及所有全局状态。
+ */
 public record ParserEngine(ParserContext ctx) {
 
+    /**
+     * 解析输入 TokenStream，生成语法树节点列表。
+     *
+     * <p>
+     * 调用各类顶级语句解析器（如 module, func, import），
+     * 遇到错误时会自动跳过到下一行或已知结构关键字，继续后续分析，
+     * 最终汇总所有错误。如果解析出现错误，将以
+     * {@link UnexpectedToken} 抛出所有语法错误信息。
+     * </p>
+     *
+     * @return AST 节点列表，每个节点对应一个顶层语法结构
+     * @throws UnexpectedToken 如果解析期间发现语法错误
+     */
     public List<Node> parse() {
         List<Node> nodes = new ArrayList<>();
         List<String> errs = new ArrayList<>();
         TokenStream ts = ctx.getTokens();
 
+        // 主循环：直到全部 token 处理完毕
         while (ts.isAtEnd()) {
-            // 跳过空行
+            // 跳过所有空行
             if (ts.peek().getType() == TokenType.NEWLINE) {
                 ts.next();
                 continue;
@@ -30,22 +64,31 @@ public record ParserEngine(ParserContext ctx) {
                 nodes.add(parser.parse(ctx));
             } catch (Exception ex) {
                 errs.add(ex.getMessage());
-                synchronize(ts);         // 错误恢复
+                synchronize(ts);         // 错误恢复：同步到下一个语句
             }
         }
 
+        // 批量报告所有解析错误
         if (!errs.isEmpty()) {
-            throw new IllegalStateException("解析过程中检测到 "
-                    + errs.size() + " 处错误:\n - "
-                    + String.join("\n - ", errs));
+            StringJoiner sj = new StringJoiner("\n - ", "", "");
+            errs.forEach(sj::add);
+            throw new UnexpectedToken("解析过程中检测到 "
+                    + errs.size() + " 处错误:\n - " + sj);
         }
         return nodes;
     }
 
     /**
-     * 错误同步：跳到下一行或下一个已注册顶层关键字
+     * 错误同步机制：跳过当前 TokenStream，直到遇到下一行
+     * 或下一个可识别的顶级结构关键字，以保证后续解析不会被卡住。
+     * <p>
+     * 同时会跳过连续空行。
+     * </p>
+     *
+     * @param ts 当前 TokenStream
      */
     private void synchronize(TokenStream ts) {
+        // 跳到下一行或下一个顶层结构关键字
         while (ts.isAtEnd()) {
             if (ts.peek().getType() == TokenType.NEWLINE) {
                 ts.next();
@@ -56,7 +99,7 @@ public record ParserEngine(ParserContext ctx) {
             }
             ts.next();
         }
-        // 连续空行全部吃掉
+        // 吃掉后续所有空行
         while (ts.isAtEnd() && ts.peek().getType() == TokenType.NEWLINE) {
             ts.next();
         }
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/expression/PrattExpressionParser.java b/src/main/java/org/jcnc/snow/compiler/parser/expression/PrattExpressionParser.java
index 4f79274..c0a869e 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/expression/PrattExpressionParser.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/expression/PrattExpressionParser.java
@@ -4,6 +4,7 @@ import org.jcnc.snow.compiler.lexer.token.Token;
 import org.jcnc.snow.compiler.lexer.token.TokenType;
 import org.jcnc.snow.compiler.parser.ast.base.ExpressionNode;
 import org.jcnc.snow.compiler.parser.context.ParserContext;
+import org.jcnc.snow.compiler.parser.context.UnsupportedFeature;
 import org.jcnc.snow.compiler.parser.expression.base.ExpressionParser;
 import org.jcnc.snow.compiler.parser.expression.base.InfixParselet;
 import org.jcnc.snow.compiler.parser.expression.base.PrefixParselet;
@@ -87,7 +88,7 @@ public class PrattExpressionParser implements ExpressionParser {
         Token token = ctx.getTokens().next();
         PrefixParselet prefix = prefixes.get(token.getType().name());
         if (prefix == null) {
-            throw new IllegalStateException("没有为该 Token 类型注册前缀解析器: " + token.getType());
+            throw new UnsupportedFeature("没有为该 Token 类型注册前缀解析器: " + token.getType());
         }
 
         ExpressionNode left = prefix.parse(ctx, token);
@@ -96,7 +97,10 @@ public class PrattExpressionParser implements ExpressionParser {
                 && prec.ordinal() < nextPrecedence(ctx)) {
             String lex = ctx.getTokens().peek().getLexeme();
             InfixParselet infix = infixes.get(lex);
-            if (infix == null) break;
+            if (infix == null) {
+                throw new UnsupportedFeature(
+                        "没有为该 Token 类型注册中缀解析器: " + token.getType());
+            }
             left = infix.parse(ctx, left);
         }
         return left;
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/module/ModuleParser.java b/src/main/java/org/jcnc/snow/compiler/parser/module/ModuleParser.java
index ac9e05d..bcf2555 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/module/ModuleParser.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/module/ModuleParser.java
@@ -7,6 +7,7 @@ import org.jcnc.snow.compiler.parser.context.TokenStream;
 import org.jcnc.snow.compiler.parser.ast.ImportNode;
 import org.jcnc.snow.compiler.parser.ast.ModuleNode;
 import org.jcnc.snow.compiler.parser.ast.FunctionNode;
+import org.jcnc.snow.compiler.parser.context.UnexpectedToken;
 import org.jcnc.snow.compiler.parser.function.FunctionParser;
 
 import java.util.ArrayList;
@@ -33,7 +34,7 @@ public class ModuleParser implements TopLevelParser {
      *
      * @param ctx 当前解析器上下文，包含词法流、状态信息等。
      * @return 返回一个 {@link ModuleNode} 实例，表示完整模块的语法结构。
-     * @throws IllegalStateException 当模块体中出现未识别的语句时抛出。
+     * @throws UnexpectedToken 当模块体中出现未识别的语句时抛出。
      */
     @Override
     public ModuleNode parse(ParserContext ctx) {
@@ -86,7 +87,7 @@ public class ModuleParser implements TopLevelParser {
                 functions.add(funcParser.parse(ctx));
             } else {
                 // 遇到无法识别的语句开头，抛出异常并提供详细提示
-                throw new IllegalStateException("Unexpected token in module: " + lex);
+                throw new UnexpectedToken("Unexpected token in module: " + lex);
             }
         }
 
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/statement/ExpressionStatementParser.java b/src/main/java/org/jcnc/snow/compiler/parser/statement/ExpressionStatementParser.java
index 526dbf0..3c14a90 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/statement/ExpressionStatementParser.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/statement/ExpressionStatementParser.java
@@ -7,6 +7,7 @@ import org.jcnc.snow.compiler.parser.ast.ExpressionStatementNode;
 import org.jcnc.snow.compiler.parser.ast.base.StatementNode;
 import org.jcnc.snow.compiler.parser.context.ParserContext;
 import org.jcnc.snow.compiler.parser.context.TokenStream;
+import org.jcnc.snow.compiler.parser.context.UnexpectedToken;
 import org.jcnc.snow.compiler.parser.expression.PrattExpressionParser;
 
 /**
@@ -39,7 +40,7 @@ public class ExpressionStatementParser implements StatementParser {
      *
      * @param ctx 当前解析上下文，提供词法流与状态信息。
      * @return 返回 {@link AssignmentNode} 或 {@link ExpressionStatementNode} 表示的语法节点。
-     * @throws IllegalStateException 若表达式起始为关键字或语法非法。
+     * @throws UnexpectedToken 若表达式起始为关键字或语法非法。
      */
     @Override
     public StatementNode parse(ParserContext ctx) {
@@ -47,7 +48,7 @@ public class ExpressionStatementParser implements StatementParser {
 
         // 快速检查：若遇空行或关键字开头，不可作为表达式语句
         if (ts.peek().getType() == TokenType.NEWLINE || ts.peek().getType() == TokenType.KEYWORD) {
-            throw new IllegalStateException("Cannot parse expression starting with keyword: " + ts.peek().getLexeme());
+            throw new UnexpectedToken("无法解析以关键字开头的表达式: " + ts.peek().getLexeme());
         }
 
         // 获取当前 token 的行号、列号和文件名
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/top/ScriptTopLevelParser.java b/src/main/java/org/jcnc/snow/compiler/parser/top/ScriptTopLevelParser.java
index f669c8e..3403dcf 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/top/ScriptTopLevelParser.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/top/ScriptTopLevelParser.java
@@ -19,7 +19,6 @@ public class ScriptTopLevelParser implements TopLevelParser {
     public Node parse(ParserContext ctx) {
         String first = ctx.getTokens().peek().getLexeme();
         StatementParser sp = StatementParserFactory.get(first);
-        StatementNode stmt = sp.parse(ctx);
-        return stmt;   // StatementNode 亦是 Node
+        return sp.parse(ctx);
     }
 }
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/utils/FlexibleSectionParser.java b/src/main/java/org/jcnc/snow/compiler/parser/utils/FlexibleSectionParser.java
index c319d4f..90cbc2c 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/utils/FlexibleSectionParser.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/utils/FlexibleSectionParser.java
@@ -3,6 +3,7 @@ package org.jcnc.snow.compiler.parser.utils;
 import org.jcnc.snow.compiler.lexer.token.TokenType;
 import org.jcnc.snow.compiler.parser.context.ParserContext;
 import org.jcnc.snow.compiler.parser.context.TokenStream;
+import org.jcnc.snow.compiler.parser.context.UnexpectedToken;
 
 import java.util.Map;
 import java.util.function.BiConsumer;
@@ -45,7 +46,7 @@ public class FlexibleSectionParser {
      * @param ctx                当前解析上下文，提供语法环境与作用域信息
      * @param tokens             当前 token 流
      * @param sectionDefinitions 各个区块的定义映射（key 为关键字，value 为判断 + 解析逻辑组合）
-     * @throws RuntimeException 若出现无法识别的关键字或未满足的匹配条件
+     * @throws UnexpectedToken 若出现无法识别的关键字或未满足的匹配条件
      */
     public static void parse(ParserContext ctx,
                              TokenStream tokens,
@@ -70,7 +71,7 @@ public class FlexibleSectionParser {
             if (definition != null && definition.condition().test(tokens)) {
                 definition.parser().accept(ctx, tokens); // 执行解析逻辑
             } else {
-                throw new RuntimeException("未识别的关键字或条件不满足: " + keyword);
+                throw new UnexpectedToken("未识别的关键字或条件不满足: " + keyword);
             }
         }
     }
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/utils/JSONParser.java b/src/main/java/org/jcnc/snow/compiler/parser/utils/JSONParser.java
index ce30193..6d77478 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/utils/JSONParser.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/utils/JSONParser.java
@@ -1,5 +1,7 @@
 package org.jcnc.snow.compiler.parser.utils;
 
+import org.jcnc.snow.compiler.parser.context.UnexpectedToken;
+
 import java.util.*;
 import java.util.Map.Entry;
 
@@ -10,26 +12,28 @@ import java.util.Map.Entry;
  * - 序列化：将 Java 原生对象转换为符合 JSON 标准的字符串
  * <p>
  * 设计要点：
- *  1. 使用静态方法作为唯一入口，避免状态共享导致的线程安全问题
- *  2. 解析器内部使用 char[] 缓冲区，提高访问性能
- *  3. 维护行列号信息，抛出异常时能精确定位错误位置
- *  4. 序列化器基于 StringBuilder，预分配容量，减少中间字符串创建
+ * 1. 使用静态方法作为唯一入口，避免状态共享导致的线程安全问题
+ * 2. 解析器内部使用 char[] 缓冲区，提高访问性能
+ * 3. 维护行列号信息，抛出异常时能精确定位错误位置
+ * 4. 序列化器基于 StringBuilder，预分配容量，减少中间字符串创建
  */
 public class JSONParser {
 
-    private JSONParser() {}
+    private JSONParser() {
+    }
 
     /**
      * 将 JSON 文本解析为对应的 Java 对象
+     *
      * @param input JSON 格式字符串
      * @return 对应的 Java 原生对象：
-     *         - JSON 对象 -> Map<String, Object>
-     *         - JSON 数组 -> List<Object>
-     *         - JSON 字符串 -> String
-     *         - JSON 数值 -> Long 或 Double
-     *         - JSON 布尔 -> Boolean
-     *         - JSON null -> null
-     * @throws RuntimeException 如果遇到语法错误或多余字符，异常消息中包含行列信息
+     * - JSON 对象 -> Map<String, Object>
+     * - JSON 数组 -> List<Object>
+     * - JSON 字符串 -> String
+     * - JSON 数值 -> Long 或 Double
+     * - JSON 布尔 -> Boolean
+     * - JSON null -> null
+     * @throws UnexpectedToken 如果遇到语法错误或多余字符，异常消息中包含行列信息
      */
     public static Object parse(String input) {
         return new Parser(input).parseInternal();
@@ -37,6 +41,7 @@ public class JSONParser {
 
     /**
      * 将 Java 原生对象序列化为 JSON 字符串
+     *
      * @param obj 支持的类型：Map、Collection、String、Number、Boolean 或 null
      * @return 符合 JSON 规范的字符串
      */
@@ -45,21 +50,31 @@ public class JSONParser {
     }
 
     // ======= 内部解析器 =======
+
     /**
      * 负责将 char[] 缓冲区中的 JSON 文本解析为 Java 对象
      */
     private static class Parser {
-        /** 输入缓冲区 */
+        /**
+         * 输入缓冲区
+         */
         private final char[] buf;
-        /** 当前解析到的位置索引 */
+        /**
+         * 当前解析到的位置索引
+         */
         private int pos;
-        /** 当前字符所在行号，从 1 开始 */
+        /**
+         * 当前字符所在行号，从 1 开始
+         */
         private int line;
-        /** 当前字符所在列号，从 1 开始 */
+        /**
+         * 当前字符所在列号，从 1 开始
+         */
         private int col;
 
         /**
          * 构造解析器，初始化缓冲区和行列信息
+         *
          * @param input 待解析的 JSON 文本
          */
         Parser(String input) {
@@ -115,7 +130,9 @@ public class JSONParser {
             while (true) {
                 skipWhitespace();
                 String key = parseString(); // 解析键
-                skipWhitespace(); expect(':'); skipWhitespace();
+                skipWhitespace();
+                expect(':');
+                skipWhitespace();
                 Object val = parseValue(); // 解析值
                 map.put(key, val);
                 skipWhitespace();
@@ -123,7 +140,8 @@ public class JSONParser {
                     advance(); // 跳过 '}'
                     break;
                 }
-                expect(','); skipWhitespace();
+                expect(',');
+                skipWhitespace();
             }
             return map;
         }
@@ -149,7 +167,8 @@ public class JSONParser {
                     advance();
                     break;
                 }
-                expect(','); skipWhitespace();
+                expect(',');
+                skipWhitespace();
             }
             return list;
         }
@@ -170,18 +189,35 @@ public class JSONParser {
                     advance(); // 跳过 '\'
                     c = currentChar();
                     switch (c) {
-                        case '"': sb.append('"'); break;
-                        case '\\': sb.append('\\'); break;
-                        case '/': sb.append('/'); break;
-                        case 'b': sb.append('\b'); break;
-                        case 'f': sb.append('\f'); break;
-                        case 'n': sb.append('\n'); break;
-                        case 'r': sb.append('\r'); break;
-                        case 't': sb.append('\t'); break;
+                        case '"':
+                            sb.append('"');
+                            break;
+                        case '\\':
+                            sb.append('\\');
+                            break;
+                        case '/':
+                            sb.append('/');
+                            break;
+                        case 'b':
+                            sb.append('\b');
+                            break;
+                        case 'f':
+                            sb.append('\f');
+                            break;
+                        case 'n':
+                            sb.append('\n');
+                            break;
+                        case 'r':
+                            sb.append('\r');
+                            break;
+                        case 't':
+                            sb.append('\t');
+                            break;
                         case 'u': // 解析 Unicode 转义
-                            String hex = new String(buf, pos+1, 4);
+                            String hex = new String(buf, pos + 1, 4);
                             sb.append((char) Integer.parseInt(hex, 16));
-                            pos += 4; col += 4;
+                            pos += 4;
+                            col += 4;
                             break;
                         default:
                             error("无效转义字符 '\\" + c + "'");
@@ -250,7 +286,8 @@ public class JSONParser {
         private void advance() {
             if (pos < buf.length) {
                 if (buf[pos] == '\n') {
-                    line++; col = 1;
+                    line++;
+                    col = 1;
                 } else {
                     col++;
                 }
@@ -292,16 +329,19 @@ public class JSONParser {
          * 抛出带行列定位的解析错误
          */
         private void error(String msg) {
-            throw new RuntimeException("Error at line " + line + ", column " + col + ": " + msg);
+            throw new UnexpectedToken("在第 " + line + " 行，第 " + col + " 列出现错误: " + msg);
         }
     }
 
     // ======= 内部序列化器 =======
+
     /**
      * 负责高效地将 Java 对象写为 JSON 文本
      */
     private static class Writer {
-        /** 默认 StringBuilder 初始容量，避免频繁扩容 */
+        /**
+         * 默认 StringBuilder 初始容量，避免频繁扩容
+         */
         private static final int DEFAULT_CAPACITY = 1024;
 
         /**
@@ -344,8 +384,8 @@ public class JSONParser {
                 }
                 sb.append(']');
             } else {
-                // 其他类型，使用 toString 并加引号
-                quote(obj.toString(), sb);
+                throw new UnsupportedOperationException(
+                        "不支持的 JSON 字符串化类型: " + obj.getClass());
             }
         }
 
@@ -356,12 +396,23 @@ public class JSONParser {
             sb.append('"');
             for (char c : s.toCharArray()) {
                 switch (c) {
-                    case '\\': sb.append("\\\\"); break;
-                    case '"': sb.append("\\\""); break;
-                    case '\n': sb.append("\\n");    break;
-                    case '\r': sb.append("\\r");    break;
-                    case '\t': sb.append("\\t");    break;
-                    default:     sb.append(c);
+                    case '\\':
+                        sb.append("\\\\");
+                        break;
+                    case '"':
+                        sb.append("\\\"");
+                        break;
+                    case '\n':
+                        sb.append("\\n");
+                        break;
+                    case '\r':
+                        sb.append("\\r");
+                        break;
+                    case '\t':
+                        sb.append("\\t");
+                        break;
+                    default:
+                        sb.append(c);
                 }
             }
             sb.append('"');

From b6262087715c3c149e6a8aab93c821bb94757278 Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Thu, 3 Jul 2025 23:51:00 +0800
Subject: [PATCH 31/37] =?UTF-8?q?chore:=20=E5=A2=9E=E5=8A=A0=E6=B5=8B?=
 =?UTF-8?q?=E8=AF=95=E9=85=8D=E7=BD=AE=E6=96=87=E4=BB=B6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .run/测试.run.xml | 15 +++++++++++++++
 1 file changed, 15 insertions(+)
 create mode 100644 .run/测试.run.xml

diff --git a/.run/测试.run.xml b/.run/测试.run.xml
new file mode 100644
index 0000000..43d3751
--- /dev/null
+++ b/.run/测试.run.xml
@@ -0,0 +1,15 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="测试" type="CompoundRunConfigurationType">
+    <toRun name="Demo1" type="Application" />
+    <toRun name="Demo10" type="Application" />
+    <toRun name="Demo11" type="Application" />
+    <toRun name="Demo2" type="Application" />
+    <toRun name="Demo3" type="Application" />
+    <toRun name="Demo4" type="Application" />
+    <toRun name="Demo6" type="Application" />
+    <toRun name="Demo7" type="Application" />
+    <toRun name="Demo8" type="Application" />
+    <toRun name="Demo9" type="Application" />
+    <method v="2" />
+  </configuration>
+</component>
\ No newline at end of file

From 169523bc3370f30b931dc57395d69a6067154257 Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Fri, 4 Jul 2025 23:58:58 +0800
Subject: [PATCH 32/37] =?UTF-8?q?style:=20=E4=BF=AE=E6=94=B9=E4=BB=A3?=
 =?UTF-8?q?=E7=A0=81=E7=BC=A9=E8=BF=9B?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../jcnc/snow/compiler/parser/context/ParserContext.java  | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/src/main/java/org/jcnc/snow/compiler/parser/context/ParserContext.java b/src/main/java/org/jcnc/snow/compiler/parser/context/ParserContext.java
index 5ff228a..b9c9852 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/context/ParserContext.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/context/ParserContext.java
@@ -15,10 +15,14 @@ import java.util.List;
  */
 public class ParserContext {
 
-    /** 当前语法分析所使用的 Token 流 */
+    /**
+     * 当前语法分析所使用的 Token 流
+     */
     private final TokenStream tokens;
 
-    /** 当前语法分析所使用的资源文件名 */
+    /**
+     * 当前语法分析所使用的资源文件名
+     */
     private final String sourceName;
 
 

From e33f6b0ce292bdca99086e453ec20b968cdd9a07 Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Sat, 5 Jul 2025 14:20:43 +0800
Subject: [PATCH 33/37] =?UTF-8?q?fix:=20=E4=BF=AE=E5=A4=8D=E6=95=B0?=
 =?UTF-8?q?=E5=AD=97=E5=90=8E=E7=A9=BA=E6=A0=BC=E5=90=8E=E6=8E=A5=E4=B8=8A?=
 =?UTF-8?q?=E9=9D=9E=E6=B3=95=E5=90=8E=E7=BC=80=E8=BF=9B=E5=85=A5=E6=AD=BB?=
 =?UTF-8?q?=E5=BE=AA=E7=8E=AF=E7=9A=84=E9=94=99=E8=AF=AF?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../lexer/scanners/NumberTokenScanner.java    | 35 ++++++-----
 .../compiler/parser/core/ParserEngine.java    | 61 +++++--------------
 .../parser/factory/TopLevelParserFactory.java | 24 ++++++--
 3 files changed, 54 insertions(+), 66 deletions(-)

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 1a9b8bb..eef90ae 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
@@ -128,33 +128,30 @@ public class NumberTokenScanner extends AbstractTokenScanner {
         if (!ctx.isAtEnd()) {
             char next = ctx.peek();
 
-            // 2‑A. 合法单字符后缀
+            // 2-A. 合法单字符后缀（紧邻，不允许空格）
             if (SUFFIX_CHARS.indexOf(next) >= 0) {
                 literal.append(ctx.advance());
             }
-            // 2‑B. 紧跟未知字母（如 42X）
+            // 未知单字符后缀 —— 直接报错
             else if (Character.isLetter(next)) {
                 throw new LexicalException("未知的数字类型后缀 '" + next + "'", line, col);
             }
-            // 2‑C. 数字后出现空白 + 类型后缀（如 3 f） —— 不允许
+            // “数字 + 空格 + 字母” —— 一律非法
             else if (Character.isWhitespace(next) && next != '\n') {
-                // 允许数字后与普通标识符/关键字间存在空白；
-                // 仅当空白后的首个非空字符是合法的类型后缀时才报错。
                 int off = 1;
                 char look;
-                // 跳过任意空白（不含换行）
+                // 跳过空白（不含换行）
                 while (true) {
                     look = ctx.peekAhead(off);
-                    if (look == '\n' || look == '\0') break; // 行尾或 EOF
+                    if (look == '\n' || look == '\0') break;
                     if (!Character.isWhitespace(look)) break;
                     off++;
                 }
-                // 如果紧跟类型后缀字符，中间存在空白则视为非法
-                if (SUFFIX_CHARS.indexOf(look) >= 0) {
-                    throw new LexicalException("数字字面量与类型后缀之间不允许有空白符", line, col);
+                if (Character.isLetter(look)) {
+                    throw new LexicalException("数字字面量后不允许出现空格再跟标识符/后缀", line, col);
                 }
             }
-            // 其他字符（分号、运算符、括号等）留给外层扫描流程处理
+            // 其他符号由外层扫描器处理
         }
 
         // 3. 生成并返回 Token
@@ -165,13 +162,21 @@ public class NumberTokenScanner extends AbstractTokenScanner {
      * FSM 内部状态。
      */
     private enum State {
-        /** 整数部分（小数点左侧） */
+        /**
+         * 整数部分（小数点左侧）
+         */
         INT_PART,
-        /** 已读到小数点，但还未读到第一位小数数字 */
+        /**
+         * 已读到小数点，但还未读到第一位小数数字
+         */
         DEC_POINT,
-        /** 小数部分（小数点右侧） */
+        /**
+         * 小数部分（小数点右侧）
+         */
         FRAC_PART,
-        /** 主体结束，准备处理后缀或交还控制权 */
+        /**
+         * 主体结束，准备处理后缀或交还控制权
+         */
         END
     }
 }
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/core/ParserEngine.java b/src/main/java/org/jcnc/snow/compiler/parser/core/ParserEngine.java
index c5bfb36..f278b41 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/core/ParserEngine.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/core/ParserEngine.java
@@ -14,61 +14,34 @@ import java.util.StringJoiner;
 
 /**
  * 语法解析引擎（ParserEngine）。
- * <p>
- * 负责驱动 Snow 源码的顶层语法结构解析，将源码 TokenStream
- * 递交给各类 TopLevelParser，并收集语法树节点与异常。
- * 支持容错解析，能够批量报告所有语法错误，并提供同步恢复功能。
- * </p>
- *
- * <p>
- * 典型用法：
- * <pre>
- *     ParserEngine engine = new ParserEngine(context);
- *     List&lt;Node&gt; ast = engine.parse();
- * </pre>
- * </p>
- *
- * @param ctx 解析器上下文，负责持有 TokenStream 及所有全局状态。
+ * <p>驱动顶层解析，并在捕获异常后通过同步机制恢复，防止死循环。</p>
  */
 public record ParserEngine(ParserContext ctx) {
 
-    /**
-     * 解析输入 TokenStream，生成语法树节点列表。
-     *
-     * <p>
-     * 调用各类顶级语句解析器（如 module, func, import），
-     * 遇到错误时会自动跳过到下一行或已知结构关键字，继续后续分析，
-     * 最终汇总所有错误。如果解析出现错误，将以
-     * {@link UnexpectedToken} 抛出所有语法错误信息。
-     * </p>
-     *
-     * @return AST 节点列表，每个节点对应一个顶层语法结构
-     * @throws UnexpectedToken 如果解析期间发现语法错误
-     */
+    /** 解析整份 TokenStream，返回顶层 AST 节点列表。 */
     public List<Node> parse() {
         List<Node> nodes = new ArrayList<>();
-        List<String> errs = new ArrayList<>();
-        TokenStream ts = ctx.getTokens();
+        List<String> errs  = new ArrayList<>();
+        TokenStream   ts   = ctx.getTokens();
 
-        // 主循环：直到全部 token 处理完毕
+        // 主循环至 EOF
         while (ts.isAtEnd()) {
-            // 跳过所有空行
+            // 跳过空行
             if (ts.peek().getType() == TokenType.NEWLINE) {
                 ts.next();
                 continue;
             }
 
             TopLevelParser parser = TopLevelParserFactory.get(ts.peek().getLexeme());
-
             try {
                 nodes.add(parser.parse(ctx));
             } catch (Exception ex) {
                 errs.add(ex.getMessage());
-                synchronize(ts);         // 错误恢复：同步到下一个语句
+                synchronize(ts);                 // 出错后同步恢复
             }
         }
 
-        // 批量报告所有解析错误
+        // 聚合并抛出全部语法错误
         if (!errs.isEmpty()) {
             StringJoiner sj = new StringJoiner("\n - ", "", "");
             errs.forEach(sj::add);
@@ -79,27 +52,21 @@ public record ParserEngine(ParserContext ctx) {
     }
 
     /**
-     * 错误同步机制：跳过当前 TokenStream，直到遇到下一行
-     * 或下一个可识别的顶级结构关键字，以保证后续解析不会被卡住。
-     * <p>
-     * 同时会跳过连续空行。
-     * </p>
-     *
-     * @param ts 当前 TokenStream
+     * 同步：跳过当前行或直到遇到 **显式注册** 的顶层关键字。
+     * 这样可避免因默认脚本解析器导致指针停滞而进入死循环。
      */
     private void synchronize(TokenStream ts) {
-        // 跳到下一行或下一个顶层结构关键字
         while (ts.isAtEnd()) {
             if (ts.peek().getType() == TokenType.NEWLINE) {
                 ts.next();
                 break;
             }
-            if (TopLevelParserFactory.get(ts.peek().getLexeme()) != null) {
-                break;
+            if (TopLevelParserFactory.isRegistered(ts.peek().getLexeme())) {
+                break;                           // 仅在已注册关键字处停下
             }
-            ts.next();
+            ts.next();                          // 继续丢弃 token
         }
-        // 吃掉后续所有空行
+        // 清掉后续连续空行
         while (ts.isAtEnd() && ts.peek().getType() == TokenType.NEWLINE) {
             ts.next();
         }
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/factory/TopLevelParserFactory.java b/src/main/java/org/jcnc/snow/compiler/parser/factory/TopLevelParserFactory.java
index 7fa779c..82c486f 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/factory/TopLevelParserFactory.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/factory/TopLevelParserFactory.java
@@ -8,22 +8,38 @@ import org.jcnc.snow.compiler.parser.top.ScriptTopLevelParser;
 import java.util.Map;
 import java.util.HashMap;
 
+/**
+ * {@code TopLevelParserFactory} 用于根据源码中顶层关键字取得对应的解析器。
+ * <p>
+ * 若关键字未注册，则回退到脚本模式解析器 {@link ScriptTopLevelParser}。
+ */
 public class TopLevelParserFactory {
 
+    /** 关键字 → 解析器注册表 */
     private static final Map<String, TopLevelParser> registry = new HashMap<>();
-    private static final TopLevelParser DEFAULT = new ScriptTopLevelParser(); // ← 默认解析器
+
+    /** 缺省解析器：脚本模式（单条语句可执行） */
+    private static final TopLevelParser DEFAULT = new ScriptTopLevelParser();
 
     static {
-        // 顶层结构解析器
+        // 在此注册所有受支持的顶层结构关键字
         registry.put("module",   new ModuleParser());
         registry.put("function", new FunctionParser());
-        // 也可按需继续注册其它关键字
+        // 若未来新增顶层结构，可继续在此处注册
     }
 
     /**
-     * 根据关键字获取解析器；若未注册，回退到脚本语句解析。
+     * 依据关键字返回解析器；若未注册则返回脚本解析器。
      */
     public static TopLevelParser get(String keyword) {
         return registry.getOrDefault(keyword, DEFAULT);
     }
+
+    /**
+     * 判断某关键字是否已显式注册为顶层结构，
+     * 供同步恢复逻辑使用，避免死循环。
+     */
+    public static boolean isRegistered(String keyword) {
+        return registry.containsKey(keyword);
+    }
 }

From e11d519627aa5b4ce6bab8873992cddba35c7b2f Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Sat, 5 Jul 2025 17:02:45 +0800
Subject: [PATCH 34/37] =?UTF-8?q?refactor:=20=E9=87=8D=E6=9E=84=E8=AF=AD?=
 =?UTF-8?q?=E6=B3=95=E5=88=86=E6=9E=90=E6=A8=A1=E5=9D=97=E5=B9=B6=E4=BC=98?=
 =?UTF-8?q?=E5=8C=96=E9=94=99=E8=AF=AF=E5=A4=84=E7=90=86=E6=9C=BA=E5=88=B6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 优化了 ExpressionStatementParser、FlexibleSectionParser 和 JSONParser 的代码结构
- 改进了模块解析器 (ModuleParser) 的实现
- 重构了语法异常 (ParseException) 类，增加了错误位置信息
- 新增 ParseError 类用于收集和展示语法错误信息
- 改进了同步机制以更好地恢复解析过程
---
 playground/BugFarm/Bug1/Main.snow             |   4 +-
 src/main/java/org/jcnc/snow/cli/SnowCLI.java  |   2 +-
 .../compiler/parser/context/MissingToken.java |  17 +-
 .../compiler/parser/context/ParseError.java   |  45 +++++
 .../parser/context/ParseException.java        |  72 ++++++-
 .../compiler/parser/context/TokenStream.java  |  92 ++++-----
 .../parser/context/UnexpectedToken.java       |  16 +-
 .../parser/context/UnsupportedFeature.java    |  16 +-
 .../compiler/parser/core/ParserEngine.java    |  67 ++++---
 .../expression/PrattExpressionParser.java     | 108 +++++-----
 .../compiler/parser/module/ModuleParser.java  |  75 ++++---
 .../statement/ExpressionStatementParser.java  |  65 +++---
 .../parser/utils/FlexibleSectionParser.java   |  73 +++----
 .../compiler/parser/utils/JSONParser.java     | 186 +++++++-----------
 14 files changed, 457 insertions(+), 381 deletions(-)
 create mode 100644 src/main/java/org/jcnc/snow/compiler/parser/context/ParseError.java

diff --git a/playground/BugFarm/Bug1/Main.snow b/playground/BugFarm/Bug1/Main.snow
index 3dae6e6..0065669 100644
--- a/playground/BugFarm/Bug1/Main.snow
+++ b/playground/BugFarm/Bug1/Main.snow
@@ -1,7 +1,7 @@
 function: main
-    return_type: int
+    return_type: int 111
     body:
-       declare num1 :int =  3.1 G
+
        return 65537
     end body
 end function
\ No newline at end of file
diff --git a/src/main/java/org/jcnc/snow/cli/SnowCLI.java b/src/main/java/org/jcnc/snow/cli/SnowCLI.java
index 0afa4e4..0ce6ba0 100644
--- a/src/main/java/org/jcnc/snow/cli/SnowCLI.java
+++ b/src/main/java/org/jcnc/snow/cli/SnowCLI.java
@@ -91,7 +91,7 @@ public class SnowCLI {
             System.exit(exitCode);
         } catch (Exception e) {
             // 捕获命令执行过程中的异常并打印错误消息
-//            System.err.println("Error: " + e.getMessage());
+            System.err.println(e.getMessage());
             System.exit(1);
         }
     }
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/context/MissingToken.java b/src/main/java/org/jcnc/snow/compiler/parser/context/MissingToken.java
index b56ae02..3610426 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/context/MissingToken.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/context/MissingToken.java
@@ -1,11 +1,22 @@
 package org.jcnc.snow.compiler.parser.context;
 
 /**
- * 当语法结构缺失必须出现的 Token 时抛出。
+ * 表示在语法分析过程中，必须出现的 Token 缺失时抛出的异常。
+ * <p>
+ * 当分析器检测到输入流中缺少某个预期 Token 时，会抛出此异常，以便准确地指明语法错误位置。
+ * 该异常包含了缺失 Token 的名称以及发生缺失的位置（行号和列号），便于错误定位和后续处理。
+ * </p>
  */
 public final class MissingToken extends ParseException {
 
-    public MissingToken(String message) {
-        super(message);
+    /**
+     * 构造一个表示缺失 Token 的异常。
+     *
+     * @param expected 预期但未出现的 Token 名称
+     * @param line     发生异常的行号
+     * @param column   发生异常的列号
+     */
+    public MissingToken(String expected, int line, int column) {
+        super("缺失 Token: " + expected, line, column);
     }
 }
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/context/ParseError.java b/src/main/java/org/jcnc/snow/compiler/parser/context/ParseError.java
new file mode 100644
index 0000000..24c1d27
--- /dev/null
+++ b/src/main/java/org/jcnc/snow/compiler/parser/context/ParseError.java
@@ -0,0 +1,45 @@
+package org.jcnc.snow.compiler.parser.context;
+
+/**
+ * 语法错误的数据传输对象（DTO）。
+ * <p>
+ * 用于收集和展示语法分析过程中检测到的错误信息，便于错误定位和报告。
+ * 包含出错文件、行号、列号和具体错误信息等字段。
+ * </p>
+ */
+public class ParseError {
+
+    /** 出错的文件名 */
+    private final String file;
+    /** 出错的行号 */
+    private final int line;
+    /** 出错的列号 */
+    private final int column;
+    /** 错误信息描述 */
+    private final String message;
+
+    /**
+     * 构造一个语法错误数据对象。
+     *
+     * @param file    出错文件名
+     * @param line    出错行号
+     * @param column  出错列号
+     * @param message 错误信息描述
+     */
+    public ParseError(String file, int line, int column, String message) {
+        this.file    = file;
+        this.line    = line;
+        this.column  = column;
+        this.message = message;
+    }
+
+    /**
+     * 返回该错误对象的字符串表示。
+     *
+     * @return 格式化后的错误描述字符串
+     */
+    @Override
+    public String toString() {
+        return file + ": 行 " + line + ", 列 " + column + ": " + message;
+    }
+}
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/context/ParseException.java b/src/main/java/org/jcnc/snow/compiler/parser/context/ParseException.java
index 0262868..97ceb33 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/context/ParseException.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/context/ParseException.java
@@ -1,21 +1,75 @@
 package org.jcnc.snow.compiler.parser.context;
 
 /**
- * {@code ParseException}——语法分析阶段所有错误的基类。
+ * 语法分析阶段所有错误的基类。
+ * <p>
+ * 本异常作为语法分析相关错误的统一父类，屏蔽了堆栈信息，确保在命令行界面（CLI）输出时只占用一行，方便用户快速定位问题。
+ * 通过 {@code permits} 关键字，限定了可被继承的异常类型，增强类型安全性。
+ * </p>
  *
- * <p>声明为 <em>sealed</em>，仅允许 {@link UnexpectedToken}、
- * {@link MissingToken}、{@link UnsupportedFeature} 三个受信子类继承，
- * 以便调用方根据异常类型进行精确处理。</p>
+ * <p>
+ * 该异常携带错误发生的行号、列号和具体原因信息，用于语法错误的精确报告和输出展示。
+ * </p>
  */
 public sealed class ParseException extends RuntimeException
-        permits UnexpectedToken, MissingToken, UnsupportedFeature {
+        permits MissingToken, UnexpectedToken, UnsupportedFeature {
+
+    /** 出错行号（从 1 开始） */
+    private final int line;
+    /** 出错列号（从 1 开始） */
+    private final int column;
+    /** 错误原因描述 */
+    private final String reason;
 
     /**
-     * 构造解析异常并附带错误消息。
+     * 构造语法分析异常。
      *
-     * @param message 错误描述
+     * @param reason  错误原因描述
+     * @param line    出错行号（从 1 开始）
+     * @param column  出错列号（从 1 开始）
      */
-    public ParseException(String message) {
-        super(message);
+    public ParseException(String reason, int line, int column) {
+        // 禁用 cause / suppression / stackTrace，确保 CLI 输出简洁
+        super(reason, null, false, false);
+        this.reason = reason;
+        this.line   = line;
+        this.column = column;
+    }
+
+    /**
+     * 禁用堆栈信息的生成，保证异常始终为单行输出。
+     *
+     * @return 当前异常对象自身
+     */
+    @Override
+    public synchronized Throwable fillInStackTrace() {
+        return this;
+    }
+
+    /**
+     * 获取出错行号（从 1 开始）。
+     *
+     * @return 行号
+     */
+    public int getLine() {
+        return line;
+    }
+
+    /**
+     * 获取出错列号（从 1 开始）。
+     *
+     * @return 列号
+     */
+    public int getColumn() {
+        return column;
+    }
+
+    /**
+     * 获取错误原因描述。
+     *
+     * @return 错误原因
+     */
+    public String getReason() {
+        return reason;
     }
 }
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/context/TokenStream.java b/src/main/java/org/jcnc/snow/compiler/parser/context/TokenStream.java
index 9169318..07a4ffb 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/context/TokenStream.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/context/TokenStream.java
@@ -6,27 +6,29 @@ import org.jcnc.snow.compiler.lexer.token.TokenType;
 import java.util.List;
 
 /**
- * {@code TokenStream} 封装了一个 Token 列表并维护当前解析位置，是语法分析器读取词法单元的核心工具类。
- *
- * <p>提供前瞻（peek）、消费（next）、匹配（match）、断言（expect）等常用操作，
- * 支持前向查看和异常处理，适用于递归下降解析等常见语法构建策略。</p>
+ * {@code TokenStream} 封装了 Token 序列并维护当前解析位置，是语法分析器读取词法单元的核心工具类。
+ * <p>
+ * 该类提供前瞻（peek）、消费（next）、匹配（match）、断言（expect）等常用操作，
+ * 支持前向查看和异常处理，适用于递归下降等常见语法解析策略。
+ * 设计上自动跳过注释（COMMENT）token，并对越界情况提供自动构造的 EOF（文件结束）token，
+ * 有效提升语法处理的健壮性与易用性。
+ * </p>
  */
 public class TokenStream {
 
     /**
-     * 源 Token 列表。
+     * 源 Token 列表
      */
     private final List<Token> tokens;
-
     /**
-     * 当前解析位置索引。
+     * 当前解析位置索引
      */
     private int pos = 0;
 
     /**
      * 使用 Token 列表构造 TokenStream。
      *
-     * @param tokens 由词法分析器产生的 Token 集合
+     * @param tokens 词法分析器输出的 Token 集合
      * @throws NullPointerException 如果 tokens 为 null
      */
     public TokenStream(List<Token> tokens) {
@@ -37,14 +39,13 @@ public class TokenStream {
     }
 
     /**
-     * 向前查看指定偏移量处的 Token（不移动位置）。
-     * 会在 offset==0 时自动跳过当前位置的所有注释（COMMENT）token。
+     * 向前查看指定偏移量处的 Token（不移动当前位置）。
+     * 在 {@code offset == 0} 时自动跳过所有连续的注释（COMMENT）token。
      *
-     * @param offset 相对当前位置的偏移量（0 表示当前 token）
+     * @param offset 相对当前位置的偏移量（0 表示当前位置 token）
      * @return 指定位置的 Token；若越界则返回自动构造的 EOF Token
      */
     public Token peek(int offset) {
-        // 只在 offset==0 时跳注释，向前多步 peek 由调用方控制
         if (offset == 0) {
             skipTrivia();
         }
@@ -56,9 +57,9 @@ public class TokenStream {
     }
 
     /**
-     * 查看当前位置的 Token，等效于 {@code peek(0)}。
+     * 查看当前位置的有效 Token（已跳过注释）。
      *
-     * @return 当前有效 Token（已跳过注释）
+     * @return 当前 Token，等效于 {@code peek(0)}
      */
     public Token peek() {
         skipTrivia();
@@ -66,21 +67,21 @@ public class TokenStream {
     }
 
     /**
-     * 消费当前位置的 Token 并返回，位置前移。注释 token 会被自动跳过。
+     * 消费当前位置的有效 Token 并前移指针，自动跳过注释 token。
      *
-     * @return 被消费的有效 Token（已跳过注释）
+     * @return 被消费的有效 Token
      */
     public Token next() {
-        Token t = peek();   // peek() 已跳过注释
-        pos++;              // 指针指向下一个 raw token
-        skipTrivia();       // 立即吞掉紧随其后的注释（若有）
+        Token t = peek();
+        pos++;
+        skipTrivia();
         return t;
     }
 
     /**
-     * 匹配当前 Token 的词素与指定字符串，若匹配则消费该 token 并前移指针。
+     * 若当前 Token 的词素等于指定字符串，则消费该 Token 并前移，否则不变。
      *
-     * @param lexeme 待匹配的词素字符串
+     * @param lexeme 目标词素字符串
      * @return 匹配成功返回 true，否则返回 false
      */
     public boolean match(String lexeme) {
@@ -92,75 +93,60 @@ public class TokenStream {
     }
 
     /**
-     * 断言当前 Token 的词素与指定值相符，否则抛出 {@link ParseException}。
-     * 匹配成功会消费该 token 并前移指针。
+     * 断言当前位置 Token 的词素等于指定值，否则抛出 {@link ParseException}。
+     * 匹配成功时消费该 Token 并前移。
      *
-     * @param lexeme 期望的词素值
+     * @param lexeme 期望的词素字符串
      * @return 匹配成功的 Token
-     * @throws ParseException 若词素不符
+     * @throws ParseException 若词素不匹配
      */
     public Token expect(String lexeme) {
         Token t = peek();
         if (!t.getLexeme().equals(lexeme)) {
             throw new ParseException(
-                    "期望的词素是'" + lexeme + "'，但得到的是'" + t.getLexeme() +
-                            "在" + t.getLine() + ":" + t.getCol()
+                    "期望的词素是 '" + lexeme + "'，但得到的是 '" + t.getLexeme() + "'",
+                    t.getLine(), t.getCol()
             );
         }
         return next();
     }
 
     /**
-     * 断言当前 Token 类型为指定类型，否则抛出 {@link ParseException}。
-     * 匹配成功会消费该 token 并前移指针。
+     * 断言当前位置 Token 类型为指定类型，否则抛出 {@link ParseException}。
+     * 匹配成功时消费该 Token 并前移。
      *
      * @param type 期望的 Token 类型
      * @return 匹配成功的 Token
-     * @throws ParseException 若类型不匹配
+     * @throws ParseException 若类型不符
      */
     public Token expectType(TokenType type) {
         Token t = peek();
         if (t.getType() != type) {
             throw new ParseException(
-                    "期望的标记类型为 " + type + " 但实际得到的是 " + t.getType() +
-                            " ('" + t.getLexeme() + "') 在 " + t.getLine() + ":" + t.getCol()
+                    "期望的标记类型为 " + type + "，但实际得到的是 " + t.getType() +
+                            " ('" + t.getLexeme() + "')",
+                    t.getLine(), t.getCol()
             );
         }
         return next();
     }
 
     /**
-     * 判断是否“已经”到达文件末尾（EOF）。
+     * 判断是否已到达文件末尾（EOF）。
      *
-     * @return 若当前位置 Token 为 EOF，则返回 true，否则返回 false
+     * @return 若当前位置 Token 为 EOF，则返回 true；否则返回 false
      */
     public boolean isAtEnd() {
-        return peek().getType() != TokenType.EOF;
+        return peek().getType() == TokenType.EOF;
     }
 
     /**
-     * 跳过所有连续的注释（COMMENT）token。
-     *
-     * <p>
-     * 此方法会检查当前指针 <code>pos</code> 所指向的 token，
-     * 如果其类型为 <code>TokenType.COMMENT</code>，则直接将指针递增，
-     * 直到遇到非 COMMENT 类型或到达 token 列表末尾。
-     * </p>
-     *
-     * <p>
-     * 注意：此方法<strong>只会跳过注释</strong>，不会递归或调用任何
-     * 会产生递归的方法（如 peek()/next()），以避免堆栈溢出。
-     * </p>
-     *
-     * <p>
-     * 使用场景：词法分析产物中允许出现注释 token，语法分析时需要自动跳过它们，
-     * 保证 parser 只处理有效语法 token。
-     * </p>
+     * 跳过所有连续的注释（COMMENT）token，使解析器总是定位在第一个有效 Token 上。
      */
     private void skipTrivia() {
         while (pos < tokens.size()
                 && tokens.get(pos).getType() == TokenType.COMMENT) {
-            pos++; // 直接跳过 COMMENT 类型
+            pos++;
         }
     }
 }
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/context/UnexpectedToken.java b/src/main/java/org/jcnc/snow/compiler/parser/context/UnexpectedToken.java
index bfa5ecd..ebaaef7 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/context/UnexpectedToken.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/context/UnexpectedToken.java
@@ -1,11 +1,21 @@
 package org.jcnc.snow.compiler.parser.context;
 
 /**
- * 当解析过程中遇到意料之外或无法识别的 Token 时抛出。
+ * 表示在语法分析过程中遇到意料之外或无法识别的 Token 时抛出的异常。
+ * <p>
+ * 当分析器检测到实际遇到的 Token 不符合语法规则，或与预期类型不符时会抛出本异常，便于错误定位和报告。
+ * </p>
  */
 public final class UnexpectedToken extends ParseException {
 
-    public UnexpectedToken(String message) {
-        super(message);
+    /**
+     * 构造一个“意外的 Token”异常。
+     *
+     * @param actual 实际遇到的 Token 描述
+     * @param line   发生异常的行号
+     * @param column 发生异常的列号
+     */
+    public UnexpectedToken(String actual, int line, int column) {
+        super("意外的 Token: " + actual, line, column);
     }
 }
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/context/UnsupportedFeature.java b/src/main/java/org/jcnc/snow/compiler/parser/context/UnsupportedFeature.java
index 558f32a..a1288bb 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/context/UnsupportedFeature.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/context/UnsupportedFeature.java
@@ -1,11 +1,21 @@
 package org.jcnc.snow.compiler.parser.context;
 
 /**
- * 当源码使用了当前编译器尚未支持的语言特性或语法时抛出。
+ * 表示在语法分析过程中使用了尚未支持的语法或语言特性时抛出的异常。
+ * <p>
+ * 当用户使用了当前编译器实现尚不支持的语法、关键字或特性时，语法分析器将抛出此异常，用于清晰提示和错误报告。
+ * </p>
  */
 public final class UnsupportedFeature extends ParseException {
 
-    public UnsupportedFeature(String message) {
-        super(message);
+    /**
+     * 构造一个“暂未支持的语法/特性”异常。
+     *
+     * @param feature 未被支持的语法或特性描述
+     * @param line    发生异常的行号
+     * @param column  发生异常的列号
+     */
+    public UnsupportedFeature(String feature, int line, int column) {
+        super("暂未支持的语法/特性: " + feature, line, column);
     }
 }
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/core/ParserEngine.java b/src/main/java/org/jcnc/snow/compiler/parser/core/ParserEngine.java
index f278b41..93f3547 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/core/ParserEngine.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/core/ParserEngine.java
@@ -3,9 +3,7 @@ package org.jcnc.snow.compiler.parser.core;
 import org.jcnc.snow.compiler.lexer.token.TokenType;
 import org.jcnc.snow.compiler.parser.ast.base.Node;
 import org.jcnc.snow.compiler.parser.base.TopLevelParser;
-import org.jcnc.snow.compiler.parser.context.ParserContext;
-import org.jcnc.snow.compiler.parser.context.TokenStream;
-import org.jcnc.snow.compiler.parser.context.UnexpectedToken;
+import org.jcnc.snow.compiler.parser.context.*;
 import org.jcnc.snow.compiler.parser.factory.TopLevelParserFactory;
 
 import java.util.ArrayList;
@@ -14,18 +12,36 @@ import java.util.StringJoiner;
 
 /**
  * 语法解析引擎（ParserEngine）。
- * <p>驱动顶层解析，并在捕获异常后通过同步机制恢复，防止死循环。</p>
+ * <p>
+ * 负责驱动顶层语法解析，并统一处理、收集所有语法异常，防止死循环，确保整体解析流程的健壮性与鲁棒性。
+ * 支持基于同步点的错误恢复，适用于命令式和脚本式语法环境。
+ * </p>
+ *
+ * <p>
+ * 本引擎以异常收集为核心设计，所有捕获到的 {@link ParseException} 会被聚合，在分析结束后一次性统一抛出。
+ * 同时，在解析出错时会通过同步（synchronize）机制，跳过错误片段以恢复到有效解析点，避免因指针停滞导致的死循环。
+ * </p>
  */
 public record ParserEngine(ParserContext ctx) {
 
-    /** 解析整份 TokenStream，返回顶层 AST 节点列表。 */
+    /**
+     * 解析整个 TokenStream，返回顶层 AST 节点列表。
+     * <p>
+     * 过程中如遇语法异常，均会被收集并在最后聚合抛出，避免单点失败导致整个解析中断。
+     * </p>
+     *
+     * @return 解析所得的顶层 AST 节点列表
+     * @throws UnexpectedToken 当存在语法错误时，统一抛出聚合异常
+     */
     public List<Node> parse() {
         List<Node> nodes = new ArrayList<>();
-        List<String> errs  = new ArrayList<>();
-        TokenStream   ts   = ctx.getTokens();
+        List<ParseError> errs = new ArrayList<>();
+
+        TokenStream ts = ctx.getTokens();
+        String file = ctx.getSourceName();
 
         // 主循环至 EOF
-        while (ts.isAtEnd()) {
+        while (!ts.isAtEnd()) {
             // 跳过空行
             if (ts.peek().getType() == TokenType.NEWLINE) {
                 ts.next();
@@ -35,39 +51,46 @@ public record ParserEngine(ParserContext ctx) {
             TopLevelParser parser = TopLevelParserFactory.get(ts.peek().getLexeme());
             try {
                 nodes.add(parser.parse(ctx));
-            } catch (Exception ex) {
-                errs.add(ex.getMessage());
-                synchronize(ts);                 // 出错后同步恢复
+            } catch (ParseException ex) {
+                // 收集错误并尝试同步
+                errs.add(new ParseError(file, ex.getLine(), ex.getColumn(), ex.getReason()));
+                synchronize(ts);
             }
         }
 
-        // 聚合并抛出全部语法错误
+        /* ───── 统一抛出聚合异常 ───── */
         if (!errs.isEmpty()) {
             StringJoiner sj = new StringJoiner("\n - ", "", "");
-            errs.forEach(sj::add);
-            throw new UnexpectedToken("解析过程中检测到 "
-                    + errs.size() + " 处错误:\n - " + sj);
+            errs.forEach(e -> sj.add(e.toString()));
+
+            String msg = "解析过程中检测到 " + errs.size() + " 处错误:\n - " + sj;
+            throw new UnexpectedToken(msg, 0, 0);
         }
         return nodes;
     }
 
     /**
-     * 同步：跳过当前行或直到遇到 **显式注册** 的顶层关键字。
-     * 这样可避免因默认脚本解析器导致指针停滞而进入死循环。
+     * 同步：跳过当前行或直到遇到显式注册的顶层关键字。
+     * <p>
+     * 该机制用于语法出错后恢复到下一个可能的有效解析点，防止指针停滞导致死循环或重复抛错。
+     * 同步过程中会优先跳过本行所有未识别 token，并在遇到换行或注册关键字时停止，随后跳过连续空行。
+     * </p>
+     *
+     * @param ts 词法 token 流
      */
     private void synchronize(TokenStream ts) {
-        while (ts.isAtEnd()) {
+        while (!ts.isAtEnd()) {
             if (ts.peek().getType() == TokenType.NEWLINE) {
                 ts.next();
                 break;
             }
             if (TopLevelParserFactory.isRegistered(ts.peek().getLexeme())) {
-                break;                           // 仅在已注册关键字处停下
+                break; // 仅在已注册关键字处停下
             }
-            ts.next();                          // 继续丢弃 token
+            ts.next(); // 继续丢弃 token
         }
-        // 清掉后续连续空行
-        while (ts.isAtEnd() && ts.peek().getType() == TokenType.NEWLINE) {
+        // 清理后续连续空行
+        while (!ts.isAtEnd() && ts.peek().getType() == TokenType.NEWLINE) {
             ts.next();
         }
     }
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/expression/PrattExpressionParser.java b/src/main/java/org/jcnc/snow/compiler/parser/expression/PrattExpressionParser.java
index c0a869e..df2ee36 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/expression/PrattExpressionParser.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/expression/PrattExpressionParser.java
@@ -13,64 +13,57 @@ import java.util.HashMap;
 import java.util.Map;
 
 /**
- * {@code PrattExpressionParser} 是基于 Pratt 算法实现的表达式解析器。
+ * {@code PrattExpressionParser} 基于 Pratt 算法的表达式解析器实现。
  * <p>
- * 它支持灵活的运算符优先级控制，结合前缀（PrefixParselet）和中缀（InfixParselet）解析器，
- * 可高效解析复杂表达式结构，包括：
- * <ul>
- *     <li>字面量（数字、字符串）</li>
- *     <li>标识符</li>
- *     <li>函数调用、成员访问</li>
- *     <li>带括号的表达式、二元运算符</li>
- * </ul>
- * 本类提供统一注册机制和递归表达式解析入口。
+ * 该类通过前缀（PrefixParselet）和中缀（InfixParselet）解析器注册表，
+ * 支持灵活扩展的表达式语法，包括字面量、变量、函数调用、成员访问和各种运算符表达式。
+ * </p>
+ * <p>
+ * 运算符优先级通过枚举控制，结合递归解析实现高效的优先级处理和语法结构解析。
+ * 未注册的语法类型或运算符会统一抛出 {@link UnsupportedFeature} 异常。
  * </p>
  */
 public class PrattExpressionParser implements ExpressionParser {
 
-    /**
-     * 前缀解析器注册表：按 Token 类型映射
-     */
+    /** 前缀解析器注册表（按 Token 类型名索引） */
     private static final Map<String, PrefixParselet> prefixes = new HashMap<>();
-
-    /**
-     * 中缀解析器注册表：按运算符词素映射
-     */
+    /** 中缀解析器注册表（按运算符词素索引） */
     private static final Map<String, InfixParselet> infixes = new HashMap<>();
 
     static {
-        // 注册前缀解析器
-        prefixes.put(TokenType.NUMBER_LITERAL.name(), new NumberLiteralParselet());
-        prefixes.put(TokenType.IDENTIFIER.name(), new IdentifierParselet());
-        prefixes.put(TokenType.LPAREN.name(), new GroupingParselet());
-        prefixes.put(TokenType.STRING_LITERAL.name(), new StringLiteralParselet());
-        prefixes.put(TokenType.BOOL_LITERAL.name(), new BoolLiteralParselet());
+        // 前缀解析器注册
+        prefixes.put(TokenType.NUMBER_LITERAL.name(),   new NumberLiteralParselet());
+        prefixes.put(TokenType.IDENTIFIER.name(),       new IdentifierParselet());
+        prefixes.put(TokenType.LPAREN.name(),           new GroupingParselet());
+        prefixes.put(TokenType.STRING_LITERAL.name(),   new StringLiteralParselet());
+        prefixes.put(TokenType.BOOL_LITERAL.name(),     new BoolLiteralParselet());
 
-        // 注册一元前缀运算
+        // 一元前缀运算符
         prefixes.put(TokenType.MINUS.name(), new UnaryOperatorParselet());
-        prefixes.put(TokenType.NOT.name(), new UnaryOperatorParselet());
+        prefixes.put(TokenType.NOT.name(),   new UnaryOperatorParselet());
 
-        // 注册中缀解析器
-        infixes.put("+", new BinaryOperatorParselet(Precedence.SUM, true));
-        infixes.put("-", new BinaryOperatorParselet(Precedence.SUM, true));
-        infixes.put("*", new BinaryOperatorParselet(Precedence.PRODUCT, true));
-        infixes.put("/", new BinaryOperatorParselet(Precedence.PRODUCT, true));
-        infixes.put("%", new BinaryOperatorParselet(Precedence.PRODUCT, true));
-        infixes.put(">", new BinaryOperatorParselet(Precedence.SUM, true));
-        infixes.put("<", new BinaryOperatorParselet(Precedence.SUM, true));
-        infixes.put("==", new BinaryOperatorParselet(Precedence.SUM, true));
-        infixes.put("!=", new BinaryOperatorParselet(Precedence.SUM, true));
-        infixes.put(">=", new BinaryOperatorParselet(Precedence.SUM, true));
-        infixes.put("<=", new BinaryOperatorParselet(Precedence.SUM, true));
-        infixes.put("(", new CallParselet());
-        infixes.put(".", new MemberParselet());
+        // 中缀解析器注册
+        infixes.put("+",  new BinaryOperatorParselet(Precedence.SUM,     true));
+        infixes.put("-",  new BinaryOperatorParselet(Precedence.SUM,     true));
+        infixes.put("*",  new BinaryOperatorParselet(Precedence.PRODUCT, true));
+        infixes.put("/",  new BinaryOperatorParselet(Precedence.PRODUCT, true));
+        infixes.put("%",  new BinaryOperatorParselet(Precedence.PRODUCT, true));
+        infixes.put(">",  new BinaryOperatorParselet(Precedence.SUM,     true));
+        infixes.put("<",  new BinaryOperatorParselet(Precedence.SUM,     true));
+        infixes.put("==", new BinaryOperatorParselet(Precedence.SUM,     true));
+        infixes.put("!=", new BinaryOperatorParselet(Precedence.SUM,     true));
+        infixes.put(">=", new BinaryOperatorParselet(Precedence.SUM,     true));
+        infixes.put("<=", new BinaryOperatorParselet(Precedence.SUM,     true));
+        infixes.put("(",  new CallParselet());
+        infixes.put(".",  new MemberParselet());
     }
 
     /**
-     * 表达式解析入口，使用最低优先级启动递归解析。
+     * 表达式解析统一入口。
+     * 以最低优先级启动递归下降，适配任意表达式复杂度。
      *
-     * @param ctx 当前语法解析上下文
-     * @return 表达式抽象语法树节点
+     * @param ctx 当前解析上下文
+     * @return 解析后的表达式 AST 节点
      */
     @Override
     public ExpressionNode parse(ParserContext ctx) {
@@ -78,28 +71,41 @@ public class PrattExpressionParser implements ExpressionParser {
     }
 
     /**
-     * 根据指定优先级解析表达式。
+     * 按指定优先级解析表达式。Pratt 算法主循环。
+     * <p>
+     * 先根据当前 Token 类型查找前缀解析器进行初始解析，
+     * 然后根据优先级不断递归处理中缀运算符和右侧表达式。
+     * </p>
      *
-     * @param ctx  当前上下文
-     * @param prec 当前优先级阈值
+     * @param ctx  解析上下文
+     * @param prec 当前运算符优先级阈值
      * @return 构建完成的表达式节点
+     * @throws UnsupportedFeature 若遇到未注册的前缀或中缀解析器
      */
     ExpressionNode parseExpression(ParserContext ctx, Precedence prec) {
         Token token = ctx.getTokens().next();
         PrefixParselet prefix = prefixes.get(token.getType().name());
         if (prefix == null) {
-            throw new UnsupportedFeature("没有为该 Token 类型注册前缀解析器: " + token.getType());
+            throw new UnsupportedFeature(
+                    "没有为该 Token 类型注册前缀解析器: " + token.getType(),
+                    token.getLine(),
+                    token.getCol()
+            );
         }
 
         ExpressionNode left = prefix.parse(ctx, token);
 
-        while (ctx.getTokens().isAtEnd()
+        while (!ctx.getTokens().isAtEnd()
                 && prec.ordinal() < nextPrecedence(ctx)) {
             String lex = ctx.getTokens().peek().getLexeme();
             InfixParselet infix = infixes.get(lex);
             if (infix == null) {
+                Token t = ctx.getTokens().peek();
                 throw new UnsupportedFeature(
-                        "没有为该 Token 类型注册中缀解析器: " + token.getType());
+                        "没有为该运算符注册中缀解析器: '" + lex + "'",
+                        t.getLine(),
+                        t.getCol()
+                );
             }
             left = infix.parse(ctx, left);
         }
@@ -107,10 +113,10 @@ public class PrattExpressionParser implements ExpressionParser {
     }
 
     /**
-     * 获取下一个中缀解析器的优先级，用于判断是否继续解析。
+     * 获取下一个中缀解析器的优先级（Pratt 算法核心）。
      *
-     * @param ctx 当前上下文
-     * @return 优先级枚举 ordinal 值；若无解析器则为 -1
+     * @param ctx 当前解析上下文
+     * @return 下一个中缀运算符的优先级序号；若无解析器则为 -1
      */
     private int nextPrecedence(ParserContext ctx) {
         InfixParselet infix = infixes.get(ctx.getTokens().peek().getLexeme());
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/module/ModuleParser.java b/src/main/java/org/jcnc/snow/compiler/parser/module/ModuleParser.java
index bcf2555..8a21e70 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/module/ModuleParser.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/module/ModuleParser.java
@@ -1,12 +1,12 @@
 package org.jcnc.snow.compiler.parser.module;
 
 import org.jcnc.snow.compiler.lexer.token.TokenType;
+import org.jcnc.snow.compiler.parser.ast.FunctionNode;
+import org.jcnc.snow.compiler.parser.ast.ImportNode;
+import org.jcnc.snow.compiler.parser.ast.ModuleNode;
 import org.jcnc.snow.compiler.parser.base.TopLevelParser;
 import org.jcnc.snow.compiler.parser.context.ParserContext;
 import org.jcnc.snow.compiler.parser.context.TokenStream;
-import org.jcnc.snow.compiler.parser.ast.ImportNode;
-import org.jcnc.snow.compiler.parser.ast.ModuleNode;
-import org.jcnc.snow.compiler.parser.ast.FunctionNode;
 import org.jcnc.snow.compiler.parser.context.UnexpectedToken;
 import org.jcnc.snow.compiler.parser.function.FunctionParser;
 
@@ -14,88 +14,85 @@ import java.util.ArrayList;
 import java.util.List;
 
 /**
- * {@code ModuleParser} 类负责解析源码中的模块定义结构，属于顶层结构解析器的一种。
+ * {@code ModuleParser} 负责解析源码中的模块结构，是顶层结构解析器实现之一。
  * <p>
- * 模块中可包含多个导入语句和函数定义，导入语句可在模块中任意位置出现，
- * 同时支持空行，空行将被自动忽略，不影响语法结构的正确性。
+ * 模块定义可包含多个导入（import）语句和函数定义（function），
+ * 导入语句可在模块中任意位置出现，且允许模块体中穿插任意数量的空行（空行会被自动忽略，不影响语法结构）。
+ * </p>
+ *
+ * <p>
+ * 典型模块语法结构：
+ * <pre>
+ * module: mymod
+ *   import ...
+ *   function ...
+ *   ...
+ * end module
+ * </pre>
+ * </p>
  */
 public class ModuleParser implements TopLevelParser {
 
     /**
-     * 解析一个模块定义块，返回构建好的 {@link ModuleNode} 对象。
+     * 解析一个模块定义块，返回完整的 {@link ModuleNode} 语法树节点。
      * <p>
-     * 本方法的语法流程包括：
+     * 解析过程包括：
      * <ol>
-     *     <li>匹配模块声明开头 {@code module: IDENTIFIER}。</li>
-     *     <li>收集模块体中的 import 语句与 function 定义，允许穿插空行。</li>
-     *     <li>模块结尾必须为 {@code end module}，且后接换行符。</li>
+     *     <li>匹配模块声明起始 {@code module: IDENTIFIER}。</li>
+     *     <li>收集模块体内所有 import 和 function 语句，允许穿插空行。</li>
+     *     <li>匹配模块结束 {@code end module}。</li>
      * </ol>
-     * 所有语法错误将在解析过程中抛出异常，以便准确反馈问题位置和原因。
+     * 若遇到未识别的语句，将抛出 {@link UnexpectedToken} 异常，定位错误位置和原因。
+     * </p>
      *
-     * @param ctx 当前解析器上下文，包含词法流、状态信息等。
-     * @return 返回一个 {@link ModuleNode} 实例，表示完整模块的语法结构。
-     * @throws UnexpectedToken 当模块体中出现未识别的语句时抛出。
+     * @param ctx 当前解析上下文（包含词法流等状态）
+     * @return 解析得到的 {@link ModuleNode} 实例
+     * @throws UnexpectedToken 当模块体中出现未识别的顶层语句时抛出
      */
     @Override
     public ModuleNode parse(ParserContext ctx) {
-        // 获取当前上下文中提供的词法流
         TokenStream ts = ctx.getTokens();
 
-        // 获取当前 token 的行号、列号和文件名
-        int line = ctx.getTokens().peek().getLine();
-        int column = ctx.getTokens().peek().getCol();
+        int line = ts.peek().getLine();
+        int column = ts.peek().getCol();
         String file = ctx.getSourceName();
 
-        // 期望模块声明以关键字 "module:" 开始
         ts.expect("module");
         ts.expect(":");
-
-        // 读取模块名称（要求为标识符类型的词法单元）
         String name = ts.expectType(TokenType.IDENTIFIER).getLexeme();
-
-        // 模块声明必须以换行符结束
         ts.expectType(TokenType.NEWLINE);
 
-        // 初始化模块的导入节点列表与函数节点列表
         List<ImportNode> imports = new ArrayList<>();
         List<FunctionNode> functions = new ArrayList<>();
 
-        // 创建 import 与 function 的子解析器
         ImportParser importParser = new ImportParser();
         FunctionParser funcParser = new FunctionParser();
 
-        // 进入模块主体内容解析循环
         while (true) {
-            // 跳过所有空行（即连续的 NEWLINE）
             if (ts.peek().getType() == TokenType.NEWLINE) {
                 ts.next();
                 continue;
             }
-
-            // 若遇到 "end"，则表明模块定义结束
             if ("end".equals(ts.peek().getLexeme())) {
                 break;
             }
-
-            // 根据当前行首关键字决定解析器的选择
             String lex = ts.peek().getLexeme();
             if ("import".equals(lex)) {
-                // 调用导入语句解析器，解析多个模块导入节点
                 imports.addAll(importParser.parse(ctx));
             } else if ("function".equals(lex)) {
-                // 调用函数定义解析器，解析单个函数结构
                 functions.add(funcParser.parse(ctx));
             } else {
-                // 遇到无法识别的语句开头，抛出异常并提供详细提示
-                throw new UnexpectedToken("Unexpected token in module: " + lex);
+                throw new UnexpectedToken(
+                        "Unexpected token in module: " + lex,
+                        ts.peek().getLine(),
+                        ts.peek().getCol()
+                );
             }
         }
 
-        // 确保模块体以 "end module" 结束
         ts.expect("end");
         ts.expect("module");
 
-        // 构建并返回完整的模块语法树节点
         return new ModuleNode(name, imports, functions, line, column, file);
     }
-}
\ No newline at end of file
+}
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/statement/ExpressionStatementParser.java b/src/main/java/org/jcnc/snow/compiler/parser/statement/ExpressionStatementParser.java
index 3c14a90..f824b6b 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/statement/ExpressionStatementParser.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/statement/ExpressionStatementParser.java
@@ -2,8 +2,8 @@ package org.jcnc.snow.compiler.parser.statement;
 
 import org.jcnc.snow.compiler.lexer.token.TokenType;
 import org.jcnc.snow.compiler.parser.ast.AssignmentNode;
-import org.jcnc.snow.compiler.parser.ast.base.ExpressionNode;
 import org.jcnc.snow.compiler.parser.ast.ExpressionStatementNode;
+import org.jcnc.snow.compiler.parser.ast.base.ExpressionNode;
 import org.jcnc.snow.compiler.parser.ast.base.StatementNode;
 import org.jcnc.snow.compiler.parser.context.ParserContext;
 import org.jcnc.snow.compiler.parser.context.TokenStream;
@@ -11,66 +11,57 @@ import org.jcnc.snow.compiler.parser.context.UnexpectedToken;
 import org.jcnc.snow.compiler.parser.expression.PrattExpressionParser;
 
 /**
- * {@code ExpressionStatementParser} 负责解析通用表达式语句，包括赋值语句和单一表达式语句。
+ * {@code ExpressionStatementParser} 用于解析通用表达式语句（赋值或普通表达式）。
  * <p>
- * 支持的语法结构如下：
+ * 支持以下两种语法结构：
  * <pre>{@code
  * x = 1 + 2        // 赋值语句
- * doSomething()    // 函数调用等普通表达式语句
+ * doSomething()    // 一般表达式语句
  * }</pre>
  * <ul>
- *     <li>若以标识符开头，且后接等号 {@code =}，则视为赋值语句，解析为 {@link AssignmentNode}。</li>
+ *     <li>以标识符开头且后接 {@code =} 时，解析为 {@link AssignmentNode}。</li>
  *     <li>否则视为普通表达式，解析为 {@link ExpressionStatementNode}。</li>
- *     <li>所有表达式语句必须以换行符 {@code NEWLINE} 结束。</li>
+ *     <li>所有表达式语句必须以换行符（{@code NEWLINE}）结尾。</li>
  * </ul>
- * 不允许以关键字或空行作为表达式的起始，若遇到非法开头，将抛出解析异常。
+ * 若语句起始为关键字或空行，将直接抛出异常，防止非法语法进入表达式解析流程。
  */
 public class ExpressionStatementParser implements StatementParser {
 
     /**
-     * 解析一个表达式语句，根据上下文决定其为赋值或一般表达式。
-     * <p>
-     * 具体逻辑如下：
-     * <ol>
-     *     <li>若当前行为标识符后接等号，则作为赋值处理。</li>
-     *     <li>否则解析整个表达式作为单独语句。</li>
-     *     <li>所有语句都必须以换行符结束。</li>
-     *     <li>若表达式以关键字或空行开头，将立即抛出异常，避免非法解析。</li>
-     * </ol>
+     * 解析单行表达式语句，根据上下文判断其为赋值语句或普通表达式语句。
      *
-     * @param ctx 当前解析上下文，提供词法流与状态信息。
-     * @return 返回 {@link AssignmentNode} 或 {@link ExpressionStatementNode} 表示的语法节点。
-     * @throws UnexpectedToken 若表达式起始为关键字或语法非法。
+     * @param ctx 当前解析上下文，提供词法流与环境信息
+     * @return {@link AssignmentNode} 或 {@link ExpressionStatementNode} 语法节点
+     * @throws UnexpectedToken 若遇到非法起始（关键字、空行等）
      */
     @Override
     public StatementNode parse(ParserContext ctx) {
         TokenStream ts = ctx.getTokens();
 
-        // 快速检查：若遇空行或关键字开头，不可作为表达式语句
         if (ts.peek().getType() == TokenType.NEWLINE || ts.peek().getType() == TokenType.KEYWORD) {
-            throw new UnexpectedToken("无法解析以关键字开头的表达式: " + ts.peek().getLexeme());
+            throw new UnexpectedToken(
+                    "无法解析以关键字开头的表达式: " + ts.peek().getLexeme(),
+                    ts.peek().getLine(),
+                    ts.peek().getCol()
+            );
         }
 
-        // 获取当前 token 的行号、列号和文件名
-        int line = ctx.getTokens().peek().getLine();
-        int column = ctx.getTokens().peek().getCol();
+        int line = ts.peek().getLine();
+        int column = ts.peek().getCol();
         String file = ctx.getSourceName();
 
-        // 处理赋值语句：格式为 identifier = expression
-        if (ts.peek().getType() == TokenType.IDENTIFIER
-                && ts.peek(1).getLexeme().equals("=")) {
-
-            String varName = ts.next().getLexeme(); // 消耗标识符
-            ts.expect("=");                         // 消耗等号
-            ExpressionNode value = new PrattExpressionParser().parse(ctx); // 解析表达式
-            ts.expectType(TokenType.NEWLINE);       // 语句必须以换行符结束
-            return new AssignmentNode(varName, value, line, column, file); // 返回赋值节点
+        // 赋值语句：IDENTIFIER = expr
+        if (ts.peek().getType() == TokenType.IDENTIFIER && "=".equals(ts.peek(1).getLexeme())) {
+            String varName = ts.next().getLexeme();
+            ts.expect("=");
+            ExpressionNode value = new PrattExpressionParser().parse(ctx);
+            ts.expectType(TokenType.NEWLINE);
+            return new AssignmentNode(varName, value, line, column, file);
         }
 
-        // 处理普通表达式语句，如函数调用、字面量、运算表达式等
+        // 普通表达式语句
         ExpressionNode expr = new PrattExpressionParser().parse(ctx);
-        ts.expectType(TokenType.NEWLINE);           // 语句必须以换行符结束
-        return new ExpressionStatementNode(expr, line, column, file);   // 返回表达式语句节点
+        ts.expectType(TokenType.NEWLINE);
+        return new ExpressionStatementNode(expr, line, column, file);
     }
-
 }
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/utils/FlexibleSectionParser.java b/src/main/java/org/jcnc/snow/compiler/parser/utils/FlexibleSectionParser.java
index 90cbc2c..692e5a4 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/utils/FlexibleSectionParser.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/utils/FlexibleSectionParser.java
@@ -10,84 +10,78 @@ import java.util.function.BiConsumer;
 import java.util.function.Predicate;
 
 /**
- * {@code FlexibleSectionParser} 是一个通用的语法块解析工具。
+ * {@code FlexibleSectionParser} 是一个通用的区块（Section）解析工具。
  * <p>
- * 该工具支持解析由关键字标识的多段结构化区块内容，常用于解析函数、类、模块、循环等语法单元中的命名子结构。
- * 相比传统硬编码方式，提供更灵活、可组合的解析能力，允许解析器模块动态注册处理逻辑，而非将所有逻辑写死在主流程中。
+ * 支持通过注册表驱动的方式解析具有区块关键字标识的多段结构内容，
+ * 常用于函数、类、模块、循环等语法单元中的命名子结构。
+ * 通过外部注册解析逻辑，支持高度可扩展与复用。
+ * </p>
  *
- * <p>典型应用包括：
+ * <p>
+ * 典型用途包括：
  * <ul>
  *   <li>函数体解析中的 {@code params}、{@code returns}、{@code body} 等部分</li>
  *   <li>模块定义中的 {@code imports}、{@code functions} 等部分</li>
- *   <li>用户自定义 DSL 的可扩展语法结构</li>
+ *   <li>可扩展 DSL 的结构化语法区块</li>
  * </ul>
+ * </p>
  *
- * <p>该工具具备以下能力：
+ * <p>主要特性：</p>
  * <ul>
  *   <li>自动跳过注释与空行</li>
- *   <li>根据区块名称调用外部提供的解析器</li>
- *   <li>支持终止标志（如 {@code end}）来退出解析流程</li>
+ *   <li>区块入口通过关键字匹配和可选条件判断</li>
+ *   <li>解析逻辑由外部以函数式接口方式注册</li>
+ *   <li>支持遇到终止关键字（如 {@code end}）时自动停止</li>
  * </ul>
  */
 public class FlexibleSectionParser {
 
     /**
-     * 启动结构化区块的统一解析流程。
-     * <p>
-     * 每次调用会：
-     * <ol>
-     *   <li>从 token 流中跳过空行与注释</li>
-     *   <li>依照当前 token 判断是否匹配某个区块</li>
-     *   <li>调用对应 {@link SectionDefinition} 执行区块解析逻辑</li>
-     *   <li>若遇到 {@code end} 关键字，则终止解析过程</li>
-     *   <li>若当前 token 不匹配任何已注册区块，抛出异常</li>
-     * </ol>
+     * 解析并分派处理多区块结构。
      *
-     * @param ctx                当前解析上下文，提供语法环境与作用域信息
-     * @param tokens             当前 token 流
-     * @param sectionDefinitions 各个区块的定义映射（key 为关键字，value 为判断 + 解析逻辑组合）
-     * @throws UnexpectedToken 若出现无法识别的关键字或未满足的匹配条件
+     * @param ctx                解析上下文
+     * @param tokens             词法流
+     * @param sectionDefinitions 区块处理注册表，key 为区块关键字，value 为对应的处理定义
+     * @throws UnexpectedToken   遇到未注册或条件不符的关键字时抛出
      */
     public static void parse(ParserContext ctx,
                              TokenStream tokens,
                              Map<String, SectionDefinition> sectionDefinitions) {
 
-        // 跳过开头的注释或空行
         skipCommentsAndNewlines(tokens);
 
         while (true) {
-            // 跳过当前区块之间的空白与注释
             skipCommentsAndNewlines(tokens);
 
             String keyword = tokens.peek().getLexeme();
 
-            // 结束关键字表示解析流程终止
             if ("end".equals(keyword)) {
                 break;
             }
 
-            // 查找匹配的区块定义
             SectionDefinition definition = sectionDefinitions.get(keyword);
             if (definition != null && definition.condition().test(tokens)) {
-                definition.parser().accept(ctx, tokens); // 执行解析逻辑
+                definition.parser().accept(ctx, tokens);
             } else {
-                throw new UnexpectedToken("未识别的关键字或条件不满足: " + keyword);
+                throw new UnexpectedToken(
+                        "未识别的关键字或条件不满足: " + keyword,
+                        tokens.peek().getLine(),
+                        tokens.peek().getCol()
+                );
             }
         }
     }
 
     /**
-     * 跳过连续出现的注释行或空行（NEWLINE）。
-     * <p>
-     * 该方法用于在区块之间清理无效 token，避免影响结构判断。
+     * 跳过所有连续的注释（COMMENT）和空行（NEWLINE）token。
      *
-     * @param tokens 当前 token 流
+     * @param tokens 当前词法流
      */
     private static void skipCommentsAndNewlines(TokenStream tokens) {
         while (true) {
             TokenType type = tokens.peek().getType();
             if (type == TokenType.COMMENT || type == TokenType.NEWLINE) {
-                tokens.next(); // 跳过注释或换行
+                tokens.next();
                 continue;
             }
             break;
@@ -95,17 +89,10 @@ public class FlexibleSectionParser {
     }
 
     /**
-     * 表示一个结构区块的定义，包含匹配条件与解析器。
-     * <p>
-     * 每个区块由两部分组成：
-     * <ul>
-     *   <li>{@code condition}：用于判断当前 token 是否应进入该区块</li>
-     *   <li>{@code parser}：该区块对应的实际解析逻辑</li>
-     * </ul>
-     * 可实现懒加载、多语言支持或 DSL 的结构化扩展。
+     * 区块定义，包含进入区块的判断条件与具体解析逻辑。
      *
-     * @param condition 判断是否触发该区块的谓词函数
-     * @param parser    区块解析逻辑（消费语法上下文与 token 流）
+     * @param condition 匹配区块的前置条件
+     * @param parser    区块内容的具体解析操作
      */
     public record SectionDefinition(Predicate<TokenStream> condition,
                                     BiConsumer<ParserContext, TokenStream> parser) {
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/utils/JSONParser.java b/src/main/java/org/jcnc/snow/compiler/parser/utils/JSONParser.java
index 6d77478..41eb1fa 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/utils/JSONParser.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/utils/JSONParser.java
@@ -6,77 +6,61 @@ import java.util.*;
 import java.util.Map.Entry;
 
 /**
- * JSON 工具类，提供线程安全、可重用的解析与序列化功能
+ * JSON 工具类，提供线程安全、可重用的 JSON 解析与序列化能力。
  * <p>
- * - 解析：将合法的 JSON 文本转换为 Java 原生对象（Map、List、String、Number、Boolean 或 null）
- * - 序列化：将 Java 原生对象转换为符合 JSON 标准的字符串
- * <p>
- * 设计要点：
- * 1. 使用静态方法作为唯一入口，避免状态共享导致的线程安全问题
- * 2. 解析器内部使用 char[] 缓冲区，提高访问性能
- * 3. 维护行列号信息，抛出异常时能精确定位错误位置
- * 4. 序列化器基于 StringBuilder，预分配容量，减少中间字符串创建
+ * <b>主要功能：</b>
+ * <ul>
+ *   <li>解析：将合法的 JSON 文本转换为 Java 原生对象（Map、List、String、Number、Boolean 或 null）</li>
+ *   <li>序列化：将 Java 原生对象转换为符合 JSON 标准的字符串</li>
+ * </ul>
+ * </p>
+ *
+ * <b>设计要点：</b>
+ * <ol>
+ *   <li>仅提供静态方法入口，无状态，线程安全</li>
+ *   <li>解析器内部采用 char[] 缓冲区，支持高性能处理</li>
+ *   <li>精确维护行列号信息，异常可定位错误文本位置</li>
+ *   <li>序列化器使用 StringBuilder，默认预分配容量</li>
+ * </ol>
  */
 public class JSONParser {
 
-    private JSONParser() {
-    }
+    private JSONParser() {}
 
     /**
-     * 将 JSON 文本解析为对应的 Java 对象
+     * 解析 JSON 格式字符串为对应的 Java 对象。
      *
      * @param input JSON 格式字符串
-     * @return 对应的 Java 原生对象：
-     * - JSON 对象 -> Map<String, Object>
-     * - JSON 数组 -> List<Object>
-     * - JSON 字符串 -> String
-     * - JSON 数值 -> Long 或 Double
-     * - JSON 布尔 -> Boolean
-     * - JSON null -> null
-     * @throws UnexpectedToken 如果遇到语法错误或多余字符，异常消息中包含行列信息
+     * @return 解析得到的 Java 对象（Map、List、String、Number、Boolean 或 null）
+     * @throws UnexpectedToken 语法错误或多余字符，异常消息带行列定位
      */
     public static Object parse(String input) {
         return new Parser(input).parseInternal();
     }
 
     /**
-     * 将 Java 原生对象序列化为 JSON 字符串
+     * 将 Java 原生对象序列化为 JSON 字符串。
      *
-     * @param obj 支持的类型：Map、Collection、String、Number、Boolean 或 null
+     * @param obj 支持 Map、Collection、String、Number、Boolean 或 null
      * @return 符合 JSON 规范的字符串
+     * @throws UnsupportedOperationException 遇到不支持的类型时抛出
      */
     public static String toJson(Object obj) {
         return Writer.write(obj);
     }
 
-    // ======= 内部解析器 =======
+    // ======= 内部解析器实现 =======
 
     /**
-     * 负责将 char[] 缓冲区中的 JSON 文本解析为 Java 对象
+     * 负责将 char[] 缓冲区中的 JSON 文本解析为 Java 对象。
+     * 维护行列号，所有异常均带精确位置。
      */
     private static class Parser {
-        /**
-         * 输入缓冲区
-         */
         private final char[] buf;
-        /**
-         * 当前解析到的位置索引
-         */
         private int pos;
-        /**
-         * 当前字符所在行号，从 1 开始
-         */
         private int line;
-        /**
-         * 当前字符所在列号，从 1 开始
-         */
         private int col;
 
-        /**
-         * 构造解析器，初始化缓冲区和行列信息
-         *
-         * @param input 待解析的 JSON 文本
-         */
         Parser(String input) {
             this.buf = input.toCharArray();
             this.pos = 0;
@@ -85,7 +69,7 @@ public class JSONParser {
         }
 
         /**
-         * 入口方法，跳过空白后调用 parseValue，再校验尾部无多余字符
+         * 解析主入口，校验无多余字符。
          */
         Object parseInternal() {
             skipWhitespace();
@@ -98,7 +82,7 @@ public class JSONParser {
         }
 
         /**
-         * 根据下一个字符决定解析哪种 JSON 值
+         * 解析 JSON 值（null, true, false, string, number, object, array）
          */
         private Object parseValue() {
             skipWhitespace();
@@ -111,33 +95,31 @@ public class JSONParser {
             if (c == '[') return parseArray();
             if (c == '-' || isDigit(c)) return parseNumber();
             error("遇到意外字符 '" + c + "'");
-            return null; // 永不到达
+            return null;
         }
 
         /**
-         * 解析 JSON 对象，返回 Map<String, Object>
+         * 解析对象类型 { ... }
          */
         private Map<String, Object> parseObject() {
-            expect('{'); // 跳过 '{'
+            expect('{');
             skipWhitespace();
             Map<String, Object> map = new LinkedHashMap<>();
-            // 空对象 {}
             if (currentChar() == '}') {
-                advance(); // 跳过 '}'
+                advance();
                 return map;
             }
-            // 多成员对象解析
             while (true) {
                 skipWhitespace();
-                String key = parseString(); // 解析键
+                String key = parseString();
                 skipWhitespace();
                 expect(':');
                 skipWhitespace();
-                Object val = parseValue(); // 解析值
+                Object val = parseValue();
                 map.put(key, val);
                 skipWhitespace();
                 if (currentChar() == '}') {
-                    advance(); // 跳过 '}'
+                    advance();
                     break;
                 }
                 expect(',');
@@ -147,18 +129,16 @@ public class JSONParser {
         }
 
         /**
-         * 解析 JSON 数组，返回 List<Object>
+         * 解析数组类型 [ ... ]
          */
         private List<Object> parseArray() {
             expect('[');
             skipWhitespace();
             List<Object> list = new ArrayList<>();
-            // 空数组 []
             if (currentChar() == ']') {
-                advance(); // 跳过 ']'
+                advance();
                 return list;
             }
-            // 多元素数组解析
             while (true) {
                 skipWhitespace();
                 list.add(parseValue());
@@ -174,46 +154,38 @@ public class JSONParser {
         }
 
         /**
-         * 解析 JSON 字符串文字，处理转义字符
+         * 解析字符串类型，支持标准 JSON 转义。
          */
         private String parseString() {
-            expect('"'); // 跳过开头 '"'
+            expect('"');
             StringBuilder sb = new StringBuilder();
             while (true) {
                 char c = currentChar();
                 if (c == '"') {
-                    advance(); // 跳过结束 '"'
+                    advance();
                     break;
                 }
                 if (c == '\\') {
-                    advance(); // 跳过 '\'
+                    advance();
                     c = currentChar();
                     switch (c) {
                         case '"':
-                            sb.append('"');
-                            break;
+                            sb.append('"'); break;
                         case '\\':
-                            sb.append('\\');
-                            break;
+                            sb.append('\\'); break;
                         case '/':
-                            sb.append('/');
-                            break;
+                            sb.append('/'); break;
                         case 'b':
-                            sb.append('\b');
-                            break;
+                            sb.append('\b'); break;
                         case 'f':
-                            sb.append('\f');
-                            break;
+                            sb.append('\f'); break;
                         case 'n':
-                            sb.append('\n');
-                            break;
+                            sb.append('\n'); break;
                         case 'r':
-                            sb.append('\r');
-                            break;
+                            sb.append('\r'); break;
                         case 't':
-                            sb.append('\t');
-                            break;
-                        case 'u': // 解析 Unicode 转义
+                            sb.append('\t'); break;
+                        case 'u':
                             String hex = new String(buf, pos + 1, 4);
                             sb.append((char) Integer.parseInt(hex, 16));
                             pos += 4;
@@ -232,15 +204,14 @@ public class JSONParser {
         }
 
         /**
-         * 解析 JSON 数值，支持整数、浮点及科学计数法
+         * 解析数字类型（支持整数、小数、科学计数法）。
          */
         private Number parseNumber() {
             int start = pos;
             if (currentChar() == '-') advance();
             while (isDigit(currentChar())) advance();
             if (currentChar() == '.') {
-                do advance();
-                while (isDigit(currentChar()));
+                do { advance(); } while (isDigit(currentChar()));
             }
             if (currentChar() == 'e' || currentChar() == 'E') {
                 advance();
@@ -248,7 +219,6 @@ public class JSONParser {
                 while (isDigit(currentChar())) advance();
             }
             String num = new String(buf, start, pos - start);
-            // 判断返回 Long 还是 Double
             if (num.indexOf('.') >= 0 || num.indexOf('e') >= 0 || num.indexOf('E') >= 0) {
                 return Double.parseDouble(num);
             }
@@ -260,7 +230,7 @@ public class JSONParser {
         }
 
         /**
-         * 跳过所有空白字符，支持空格、制表符、回车、换行
+         * 跳过所有空白符（含换行），同时维护行/列号。
          */
         private void skipWhitespace() {
             while (pos < buf.length) {
@@ -273,21 +243,17 @@ public class JSONParser {
             }
         }
 
-        /**
-         * 获取当前位置字符，超出范围返回 '\0'
-         */
         private char currentChar() {
             return pos < buf.length ? buf[pos] : '\0';
         }
 
         /**
-         * 推进到下一个字符，并更新行列信息
+         * 指针前移并更新行/列号。
          */
         private void advance() {
             if (pos < buf.length) {
                 if (buf[pos] == '\n') {
-                    line++;
-                    col = 1;
+                    line++; col = 1;
                 } else {
                     col++;
                 }
@@ -296,7 +262,7 @@ public class JSONParser {
         }
 
         /**
-         * 验证当前位置字符等于预期字符，否则抛出错误
+         * 匹配下一个字符（或字符串），并前移指针。
          */
         private void expect(char c) {
             if (currentChar() != c) {
@@ -306,7 +272,7 @@ public class JSONParser {
         }
 
         /**
-         * 尝试匹配给定字符串，匹配成功则移动位置并返回 true
+         * 判断当前位置是否能完整匹配目标字符串，若能则移动指针。
          */
         private boolean match(String s) {
             int len = s.length();
@@ -318,35 +284,30 @@ public class JSONParser {
             return true;
         }
 
-        /**
-         * 判断字符是否为数字
-         */
         private boolean isDigit(char c) {
             return c >= '0' && c <= '9';
         }
 
         /**
-         * 抛出带行列定位的解析错误
+         * 抛出带行列号的解析异常。
          */
         private void error(String msg) {
-            throw new UnexpectedToken("在第 " + line + " 行，第 " + col + " 列出现错误: " + msg);
+            throw new UnexpectedToken(
+                    "在第 " + line + " 行，第 " + col + " 列出现错误: " + msg,
+                    line,
+                    col
+            );
         }
     }
 
-    // ======= 内部序列化器 =======
+    // ======= 内部序列化器实现 =======
 
     /**
-     * 负责高效地将 Java 对象写为 JSON 文本
+     * 负责将 Java 对象序列化为 JSON 字符串。
      */
     private static class Writer {
-        /**
-         * 默认 StringBuilder 初始容量，避免频繁扩容
-         */
         private static final int DEFAULT_CAPACITY = 1024;
 
-        /**
-         * 入口方法，根据 obj 类型分派写入逻辑
-         */
         static String write(Object obj) {
             StringBuilder sb = new StringBuilder(DEFAULT_CAPACITY);
             writeValue(obj, sb);
@@ -354,7 +315,7 @@ public class JSONParser {
         }
 
         /**
-         * 根据对象类型选择合适的写入方式
+         * 递归输出任意支持的 JSON 类型对象。
          */
         private static void writeValue(Object obj, StringBuilder sb) {
             if (obj == null) {
@@ -390,27 +351,22 @@ public class JSONParser {
         }
 
         /**
-         * 为字符串添加双引号并转义必须的字符
+         * JSON 字符串输出，处理所有必要的转义字符。
          */
         private static void quote(String s, StringBuilder sb) {
             sb.append('"');
             for (char c : s.toCharArray()) {
                 switch (c) {
                     case '\\':
-                        sb.append("\\\\");
-                        break;
+                        sb.append("\\\\"); break;
                     case '"':
-                        sb.append("\\\"");
-                        break;
+                        sb.append("\\\""); break;
                     case '\n':
-                        sb.append("\\n");
-                        break;
+                        sb.append("\\n"); break;
                     case '\r':
-                        sb.append("\\r");
-                        break;
+                        sb.append("\\r"); break;
                     case '\t':
-                        sb.append("\\t");
-                        break;
+                        sb.append("\\t"); break;
                     default:
                         sb.append(c);
                 }

From cb208bb8af610b20133d536bfac606d3e7db91c1 Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Sun, 6 Jul 2025 23:57:58 +0800
Subject: [PATCH 35/37] =?UTF-8?q?test:=20=E4=BF=AE=E6=94=B9=E4=B8=BA?=
 =?UTF-8?q?=E6=9C=80=E6=96=B0=E6=B5=8B=E8=AF=95=E4=BB=A3=E7=A0=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 playground/BugFarm/Bug1/Main.snow | 24 +++++++++++++++++-------
 1 file changed, 17 insertions(+), 7 deletions(-)

diff --git a/playground/BugFarm/Bug1/Main.snow b/playground/BugFarm/Bug1/Main.snow
index 0065669..4a13b7d 100644
--- a/playground/BugFarm/Bug1/Main.snow
+++ b/playground/BugFarm/Bug1/Main.snow
@@ -1,7 +1,17 @@
-function: main
-    return_type: int 111
-    body:
-
-       return 65537
-    end body
-end function
\ No newline at end of file
+module: Main
+    function: main
+        parameter:
+        return_type: int
+        body:
+           declare n1: int =1
+           declare n2: int =2
+           declare n3: int =1
+           if n1 ==1 then
+              if n2 ==2 then
+              n3 =3
+              end if
+           end if
+        return n3
+        end body
+    end function
+end module
\ No newline at end of file

From 0ea8cb352dc16b5da33e2a07ce3d4b56f080485f Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Mon, 7 Jul 2025 00:02:31 +0800
Subject: [PATCH 36/37] =?UTF-8?q?refactor:=20=E9=87=8D=E6=9E=84=E6=95=B0?=
 =?UTF-8?q?=E5=AD=97=E5=AD=97=E9=9D=A2=E9=87=8F=E6=89=AB=E6=8F=8F=E9=80=BB?=
 =?UTF-8?q?=E8=BE=91?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 优化了 NumberTokenScanner 类的代码结构
- 改进了数字字面量的扫描逻辑，包括整数和小数部分
- 调整了后缀和非法字符的检查策略
- 优化了错误处理和异常抛出的逻辑
- 移除了未使用的代码和不必要的注释
---
 .../lexer/scanners/NumberTokenScanner.java    | 76 ++++++-------------
 1 file changed, 24 insertions(+), 52 deletions(-)

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 eef90ae..88592b9 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
@@ -14,8 +14,9 @@ import org.jcnc.snow.compiler.lexer.token.TokenType;
  *   <li>十进制小数（如 3.14，0.5）</li>
  *   <li>单字符类型后缀（如 2.0f，255B，合法集合见 SUFFIX_CHARS）</li>
  * </ol>
- * <p>
+ *
  * 如果后续需要支持科学计数法、下划线分隔符、不同进制等，只需扩展现有状态机的转移规则。
+ *
  * <pre>
  * 状态机简述：
  *   INT_PART   --'.'-->  DEC_POINT
@@ -33,12 +34,14 @@ import org.jcnc.snow.compiler.lexer.token.TokenType;
  *   <li>FRAC_PART  ：读取小数部分，遇非法字符则结束主体。</li>
  *   <li>END        ：主体扫描结束，进入后缀/尾随字符判定。</li>
  * </ul>
+ *
  * 错误处理策略：
  * <ol>
  *   <li>数字后跟未知字母（如 42X）—— 抛出 LexicalException</li>
  *   <li>数字与合法后缀间有空白（如 3 L）—— 抛出 LexicalException</li>
  *   <li>小数点后缺失数字（如 1.）—— 抛出 LexicalException</li>
  * </ol>
+ *
  * 支持的单字符类型后缀包括：b, s, l, f, d 及其大写形式。若需支持多字符后缀，可将该集合扩展为 Set<String>。
  */
 public class NumberTokenScanner extends AbstractTokenScanner {
@@ -55,7 +58,7 @@ public class NumberTokenScanner extends AbstractTokenScanner {
      * 仅当首字符为数字时，NumberTokenScanner 介入处理。
      *
      * @param c   当前待判断字符
-     * @param ctx 当前 LexerContext（可用于进一步判断）
+     * @param ctx 当前 LexerContext
      * @return 如果为数字返回 true，否则返回 false
      */
     @Override
@@ -65,31 +68,24 @@ public class NumberTokenScanner extends AbstractTokenScanner {
 
     /**
      * 按照有限状态机读取完整数字字面量，并对尾随字符进行合法性校验。
-     * <p>
-     * 主体流程：
-     * <ol>
-     * <li>整数部分、可选小数点和小数部分扫描。</li>
-     * <li>检查合法的类型后缀。</li>
-     * <li>检查非法尾随字符，如未知字母、空白后缀或非法 '/'。</li>
-     * <li>生成并返回 NUMBER_LITERAL Token。</li>
-     * </ol>
      *
-     * @param ctx  当前 LexerContext（提供游标、前瞻等功能）
+     * @param ctx  当前 LexerContext
      * @param line 源码起始行号（1 基）
      * @param col  源码起始列号（1 基）
      * @return NUMBER_LITERAL 类型的 Token
      * @throws LexicalException 如果遇到非法格式或未受支持的尾随字符
      */
     @Override
-    protected Token scanToken(LexerContext ctx, int line, int col) {
+    protected Token scanToken(LexerContext ctx, int line, int col) throws LexicalException {
         StringBuilder literal = new StringBuilder();
         State state = State.INT_PART;
 
-        // 1. 主体扫描 —— 整数 / 小数
+        /* ───── 1. 主体扫描 —— 整数 / 小数 ───── */
         mainLoop:
         while (!ctx.isAtEnd() && state != State.END) {
             char ch = ctx.peek();
             switch (state) {
+                /* 整数部分 */
                 case INT_PART:
                     if (Character.isDigit(ch)) {
                         literal.append(ctx.advance());
@@ -97,86 +93,62 @@ public class NumberTokenScanner extends AbstractTokenScanner {
                         state = State.DEC_POINT;
                         literal.append(ctx.advance());
                     } else {
-                        state = State.END; // 整数已结束
+                        state = State.END;
                     }
                     break;
 
+                /* 已读到小数点，下一字符必须是数字 */
                 case DEC_POINT:
                     if (Character.isDigit(ch)) {
                         state = State.FRAC_PART;
                         literal.append(ctx.advance());
                     } else {
-                        // 如 "1." —— 语言规范不允许尾点数字
                         throw new LexicalException("小数点后必须跟数字", line, col);
                     }
                     break;
 
+                /* 小数部分 */
                 case FRAC_PART:
                     if (Character.isDigit(ch)) {
                         literal.append(ctx.advance());
                     } else {
-                        state = State.END; // 小数字符串结束
+                        state = State.END;
                     }
                     break;
 
                 default:
-                    break mainLoop; // 理论不会到达
+                    break mainLoop;
             }
         }
 
-        // 2. 后缀及非法尾随字符检查
+        /* ───── 2. 后缀及非法尾随字符检查 ───── */
         if (!ctx.isAtEnd()) {
             char next = ctx.peek();
 
-            // 2-A. 合法单字符后缀（紧邻，不允许空格）
+            /* 2-A. 合法单字符后缀（紧邻数字，不允许空格） */
             if (SUFFIX_CHARS.indexOf(next) >= 0) {
                 literal.append(ctx.advance());
             }
-            // 未知单字符后缀 —— 直接报错
+            /* 2-B. 未知紧邻字母后缀 —— 报错 */
             else if (Character.isLetter(next)) {
                 throw new LexicalException("未知的数字类型后缀 '" + next + "'", line, col);
             }
-            // “数字 + 空格 + 字母” —— 一律非法
-            else if (Character.isWhitespace(next) && next != '\n') {
-                int off = 1;
-                char look;
-                // 跳过空白（不含换行）
-                while (true) {
-                    look = ctx.peekAhead(off);
-                    if (look == '\n' || look == '\0') break;
-                    if (!Character.isWhitespace(look)) break;
-                    off++;
-                }
-                if (Character.isLetter(look)) {
-                    throw new LexicalException("数字字面量后不允许出现空格再跟标识符/后缀", line, col);
-                }
-            }
-            // 其他符号由外层扫描器处理
+            /* 其余情况交由外层扫描器处理（包括空白及其它符号） */
         }
 
-        // 3. 生成并返回 Token
+        /* ───── 3. 生成并返回 Token ───── */
         return new Token(TokenType.NUMBER_LITERAL, literal.toString(), line, col);
     }
 
-    /**
-     * FSM 内部状态。
-     */
+    /** FSM 内部状态定义 */
     private enum State {
-        /**
-         * 整数部分（小数点左侧）
-         */
+        /** 整数部分 */
         INT_PART,
-        /**
-         * 已读到小数点，但还未读到第一位小数数字
-         */
+        /** 已读到小数点，但还未读到第一位小数数字 */
         DEC_POINT,
-        /**
-         * 小数部分（小数点右侧）
-         */
+        /** 小数部分 */
         FRAC_PART,
-        /**
-         * 主体结束，准备处理后缀或交还控制权
-         */
+        /** 主体结束，准备处理后缀或交还控制权 */
         END
     }
 }

From 506bf193d542982eaece196ec9ab2f84a3d5d0c0 Mon Sep 17 00:00:00 2001
From: Luke <luke.k.xu@hotmail.com>
Date: Mon, 7 Jul 2025 00:26:36 +0800
Subject: [PATCH 37/37] =?UTF-8?q?chore:=20=E4=BF=AE=E6=94=B9IDEA=E9=85=8D?=
 =?UTF-8?q?=E7=BD=AE=E8=AE=A9.water=E8=BE=93=E5=87=BA=E5=88=B0target?=
 =?UTF-8?q?=E7=9B=AE=E5=BD=95=E5=90=8E=E4=B8=8D=E6=B1=A1=E6=9F=93=E6=A0=B9?=
 =?UTF-8?q?=E7=9B=AE=E5=BD=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .run/Demo10.run.xml | 2 +-
 .run/Demo2.run.xml  | 2 +-
 .run/Demo3.run.xml  | 2 +-
 .run/Demo4.run.xml  | 2 +-
 .run/Demo5.run.xml  | 2 +-
 .run/Demo6.run.xml  | 2 +-
 .run/Demo7.run.xml  | 2 +-
 .run/Demo8.run.xml  | 2 +-
 .run/Demo9.run.xml  | 2 +-
 9 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/.run/Demo10.run.xml b/.run/Demo10.run.xml
index 46332d1..94bfc43 100644
--- a/.run/Demo10.run.xml
+++ b/.run/Demo10.run.xml
@@ -1,5 +1,5 @@
 <component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="Demo10" type="Application" factoryName="Application" folderName="Demo">
+  <configuration default="false" name="Demo10" type="Application" factoryName="Application" folderName="Demo" activateToolWindowBeforeRun="false">
     <option name="ALTERNATIVE_JRE_PATH" value="graalvm-ce-23" />
     <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
     <module name="Snow" />
diff --git a/.run/Demo2.run.xml b/.run/Demo2.run.xml
index 464e671..882e77a 100644
--- a/.run/Demo2.run.xml
+++ b/.run/Demo2.run.xml
@@ -1,5 +1,5 @@
 <component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="Demo2" type="Application" factoryName="Application" folderName="Demo">
+  <configuration default="false" name="Demo2" type="Application" factoryName="Application" folderName="Demo" activateToolWindowBeforeRun="false">
     <option name="ALTERNATIVE_JRE_PATH" value="graalvm-ce-23" />
     <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
     <module name="Snow" />
diff --git a/.run/Demo3.run.xml b/.run/Demo3.run.xml
index 846b27a..a949e95 100644
--- a/.run/Demo3.run.xml
+++ b/.run/Demo3.run.xml
@@ -1,5 +1,5 @@
 <component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="Demo3" type="Application" factoryName="Application" folderName="Demo">
+  <configuration default="false" name="Demo3" type="Application" factoryName="Application" folderName="Demo" activateToolWindowBeforeRun="false">
     <option name="ALTERNATIVE_JRE_PATH" value="graalvm-ce-23" />
     <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
     <module name="Snow" />
diff --git a/.run/Demo4.run.xml b/.run/Demo4.run.xml
index 8f5ba76..57afa15 100644
--- a/.run/Demo4.run.xml
+++ b/.run/Demo4.run.xml
@@ -1,5 +1,5 @@
 <component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="Demo4" type="Application" factoryName="Application" folderName="Demo">
+  <configuration default="false" name="Demo4" type="Application" factoryName="Application" folderName="Demo" activateToolWindowBeforeRun="false">
     <option name="ALTERNATIVE_JRE_PATH" value="graalvm-ce-23" />
     <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
     <module name="Snow" />
diff --git a/.run/Demo5.run.xml b/.run/Demo5.run.xml
index 50e1218..cb543d1 100644
--- a/.run/Demo5.run.xml
+++ b/.run/Demo5.run.xml
@@ -1,5 +1,5 @@
 <component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="Demo5" type="Application" factoryName="Application" folderName="Demo">
+  <configuration default="false" name="Demo5" type="Application" factoryName="Application" folderName="Demo" activateToolWindowBeforeRun="false">
     <option name="ALTERNATIVE_JRE_PATH" value="graalvm-ce-23" />
     <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
     <module name="Snow" />
diff --git a/.run/Demo6.run.xml b/.run/Demo6.run.xml
index 8d0f410..b6c3fdc 100644
--- a/.run/Demo6.run.xml
+++ b/.run/Demo6.run.xml
@@ -1,5 +1,5 @@
 <component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="Demo6" type="Application" factoryName="Application" folderName="Demo">
+  <configuration default="false" name="Demo6" type="Application" factoryName="Application" folderName="Demo" activateToolWindowBeforeRun="false">
     <option name="ALTERNATIVE_JRE_PATH" value="graalvm-ce-23" />
     <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
     <module name="Snow" />
diff --git a/.run/Demo7.run.xml b/.run/Demo7.run.xml
index 2a2132e..6f25770 100644
--- a/.run/Demo7.run.xml
+++ b/.run/Demo7.run.xml
@@ -1,5 +1,5 @@
 <component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="Demo7" type="Application" factoryName="Application" folderName="Demo">
+  <configuration default="false" name="Demo7" type="Application" factoryName="Application" folderName="Demo" activateToolWindowBeforeRun="false">
     <option name="ALTERNATIVE_JRE_PATH" value="graalvm-ce-23" />
     <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
     <module name="Snow" />
diff --git a/.run/Demo8.run.xml b/.run/Demo8.run.xml
index 877a106..4bb76fe 100644
--- a/.run/Demo8.run.xml
+++ b/.run/Demo8.run.xml
@@ -1,5 +1,5 @@
 <component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="Demo8" type="Application" factoryName="Application" folderName="Demo">
+  <configuration default="false" name="Demo8" type="Application" factoryName="Application" folderName="Demo" activateToolWindowBeforeRun="false">
     <option name="ALTERNATIVE_JRE_PATH" value="graalvm-ce-23" />
     <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
     <module name="Snow" />
diff --git a/.run/Demo9.run.xml b/.run/Demo9.run.xml
index 764e4f2..a6bf203 100644
--- a/.run/Demo9.run.xml
+++ b/.run/Demo9.run.xml
@@ -1,5 +1,5 @@
 <component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="Demo9" type="Application" factoryName="Application" folderName="Demo">
+  <configuration default="false" name="Demo9" type="Application" factoryName="Application" folderName="Demo" activateToolWindowBeforeRun="false">
     <option name="ALTERNATIVE_JRE_PATH" value="graalvm-ce-23" />
     <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
     <module name="Snow" />