Merge branch 'main' into dev

# Conflicts:
#	.run/Demo1.run.xml
#	.run/Demo10.run.xml
#	.run/Demo11.run.xml
#	.run/Demo12.run.xml
#	.run/Demo13.run.xml
#	.run/Demo14.run.xml
#	.run/Demo2.run.xml
#	.run/Demo3.run.xml
#	.run/Demo4.run.xml
#	.run/Demo5.run.xml
#	.run/Demo6.run.xml
#	.run/Demo7.run.xml
#	.run/Demo8.run.xml
#	.run/Demo9.run.xml
#	src/main/java/org/jcnc/snow/pkg/tasks/CompileTask.java

.gitee/ISSUE_TEMPLATE/bug.yml

@@ -69,7 +69,7 @@ body:
     attributes:
       label: 软件版本/分支
       options:
-        - v0.4.2
+        - v0.5.0
         - main
         - dev
         - 其他

.run/Snow.run.xml

@@ -0,0 +1,15 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="Snow" type="Application" factoryName="Application">
+    <option name="MAIN_CLASS_NAME" value="org.jcnc.snow.cli.SnowCLI" />
+    <module name="Snow" />
+    <extension name="coverage">
+      <pattern>
+        <option name="PATTERN" value="org.jcnc.snow.cli.SnowCLI" />
+        <option name="ENABLED" value="true" />
+      </pattern>
+    </extension>
+    <method v="2">
+      <option name="Make" enabled="true" />
+    </method>
+  </configuration>
+</component>

README.md

@@ -11,8 +11,8 @@
     <a href="https://gitee.com/jcnc-org/snow/blob/main/LICENSE">
         <img src="https://img.shields.io/badge/%20license-Apache--2.0%20-blue" alt="">
     </a>
-    <a href="https://gitee.com/jcnc-org/snow/tree/v0.4.2/">
+    <a href="https://gitee.com/jcnc-org/snow/tree/v0.5.0/">
-        <img src="https://img.shields.io/badge/version-v0.4.2-blue" alt="">
+        <img src="https://img.shields.io/badge/version-v0.5.0-blue" alt="">
     </a>
 </p>
 
@@ -53,12 +53,12 @@ Snow 语言受到 LLM 驱动代码生成趋势的启发,强调简单而清晰的
 
 | 类别       | 关键特性                                                                                              |
 |----------|---------------------------------------------------------------------------------------------------|
-| 语言层      | `module` / `import` / `function` / `loop` / `if–else` / Pratt 表达式解析<br>静态类型检查 & 作用域分析             |
+| 语言层      | module / import / function / loop / if–else / Pratt 表达式解析<br>静态类型检查 & 作用域分析                       |
-| 编译器前端    | **Lexer / Parser / Semantic Analyzer** 全栈自研，生成 JSON-AST                                           |
+| 编译器前端    | Lexer / Parser / Semantic Analyzer 全栈自研，生成 JSON-AST                                               |
 | IR & 后端  | 三地址式 IR ➜ 线性扫描寄存器分配 ➜ SnowVM 指令                                                                   |
 | 虚拟机      | 栈 + 寄存器混合架构、GUI 局部变量监视                                                                            |
 | snow pkg | - `.cloud` DSL 描述项目、依赖与构建<br>- 预设 `clean / compile / run / package / publish` 任务<br>- 离线缓存与远程仓库解析 |
-| CLI      | `snow init`, `snow compile`, `snow run`, `snow clean`, `snow build`, `snow generate`              |
+| CLI      | init, compile,  run, clean,  build, generate,debug                                                |
 
 ## Snow-Lang 官网
 
@@ -118,6 +118,59 @@ Snow 语言受到 LLM 驱动代码生成趋势的启发,强调简单而清晰的
             end body
         end function
     end module
+    line   col    type             lexeme
+    ----------------------------------------------------
+    1      1      KEYWORD          module
+    1      7      COLON            :
+    1      9      IDENTIFIER       Main
+    1      13     NEWLINE          \n
+    
+    2      5      KEYWORD          import
+    2      11     COLON            :
+    2      12     IDENTIFIER       Math
+    2      16     NEWLINE          \n
+    
+    3      5      KEYWORD          function
+    3      13     COLON            :
+    3      15     IDENTIFIER       main
+    3      19     NEWLINE          \n
+    
+    4      9      KEYWORD          return_type
+    4      20     COLON            :
+    4      22     TYPE             int
+    4      25     NEWLINE          \n
+    
+    5      9      KEYWORD          body
+    5      13     COLON            :
+    5      14     NEWLINE          \n
+    
+    6      13     IDENTIFIER       Math
+    6      17     DOT              .
+    6      18     IDENTIFIER       add
+    6      21     LPAREN           (
+    6      22     NUMBER_LITERAL   6
+    6      23     COMMA            ,
+    6      24     NUMBER_LITERAL   1
+    6      25     RPAREN           )
+    6      26     NEWLINE          \n
+    
+    7      13     KEYWORD          return
+    7      20     NUMBER_LITERAL   0
+    7      21     NEWLINE          \n
+    
+    8      9      KEYWORD          end
+    8      13     KEYWORD          body
+    8      17     NEWLINE          \n
+    
+    9      5      KEYWORD          end
+    9      9      KEYWORD          function
+    9      17     NEWLINE          \n
+    
+    10     1      KEYWORD          end
+    10     5      KEYWORD          module
+    10     1      EOF              
+    ## 词法分析通过，没有发现错误
+    
     #### Math.snow
     module: Math
         function: add
@@ -130,6 +183,65 @@ Snow 语言受到 LLM 驱动代码生成趋势的启发,强调简单而清晰的
             end body
         end function
     end module
+    line   col    type             lexeme
+    ----------------------------------------------------
+    1      1      KEYWORD          module
+    1      7      COLON            :
+    1      9      IDENTIFIER       Math
+    1      13     NEWLINE          \n
+    
+    2      5      KEYWORD          function
+    2      13     COLON            :
+    2      15     IDENTIFIER       add
+    2      18     NEWLINE          \n
+    
+    3      9      KEYWORD          parameter
+    3      18     COLON            :
+    3      19     NEWLINE          \n
+    
+    4      13     KEYWORD          declare
+    4      21     IDENTIFIER       n1
+    4      23     COLON            :
+    4      25     TYPE             int
+    4      28     NEWLINE          \n
+    
+    5      13     KEYWORD          declare
+    5      21     IDENTIFIER       n2
+    5      23     COLON            :
+    5      25     TYPE             int
+    5      28     NEWLINE          \n
+    
+    6      9      KEYWORD          return_type
+    6      20     COLON            :
+    6      22     TYPE             int
+    6      25     NEWLINE          \n
+    
+    7      9      KEYWORD          body
+    7      13     COLON            :
+    7      14     NEWLINE          \n
+    
+    8      12     KEYWORD          return
+    8      19     IDENTIFIER       n1
+    8      22     PLUS             +
+    8      24     IDENTIFIER       n2
+    8      26     NEWLINE          \n
+    
+    9      9      KEYWORD          end
+    9      13     KEYWORD          body
+    9      17     NEWLINE          \n
+    
+    10     5      KEYWORD          end
+    10     9      KEYWORD          function
+    10     17     NEWLINE          \n
+    
+    11     1      KEYWORD          end
+    11     5      KEYWORD          module
+    11     1      EOF        
+    
+    ## 词法分析通过，没有发现错误
+    
+    ## 语义分析通过，没有发现错误
+    
     ### AST
     [
       {
@@ -137,8 +249,8 @@ Snow 语言受到 LLM 驱动代码生成趋势的启发,强调简单而清晰的
         "name": "Main",
         "imports": [
           {
-            "module": "Math",
+            "type": "Import",
-            "type": "Import"
+            "module": "Math"
           }
         ],
         "functions": [
@@ -240,7 +352,6 @@ Snow 语言受到 LLM 驱动代码生成趋势的启发,强调简单而清晰的
       RET %2
     }
     
-
     ### VM code
     0000: I_PUSH     6
     0001: I_STORE    0
@@ -248,35 +359,41 @@ Snow 语言受到 LLM 驱动代码生成趋势的启发,强调简单而清晰的
     0003: I_STORE    1
     0004: I_LOAD     0
     0005: I_LOAD     1
-    0006: CALL       12 2
+    0006: CALL       13 2
     0007: I_STORE    2
     0008: I_PUSH     0
     0009: I_STORE    3
     0010: I_LOAD     3
     0011: HALT       
-    0012: I_LOAD     0
+    0012: HALT       
-    0013: I_LOAD     1
+    0013: I_LOAD     0
-    0014: I_ADD      
+    0014: I_LOAD     1
-    0015: I_STORE    2
+    0015: I_ADD      
-    0016: I_LOAD     2
+    0016: I_STORE    2
-    0017: RET        
+    0017: I_LOAD     2
+    0018: RET        
+    0019: RET        
     Written to D:\Devs\IdeaProjects\Snow\target\Demo1.water
     
     === Launching VM ===
-    Calling function at address: 12
+    
+    Calling function at address: 13
+    
     Return 7
+    
     Process has ended
 
     Operand Stack state:[0]
     
     --- Call Stack State ---
     
-
     ### VM Local Variable Table:
     0: 6
     1: 1
     2: 7
     3: 0
+    
+    === VM exited ===
     `````
     
 ## 编译 Snow 源代码
@@ -316,7 +433,7 @@ Snow 语言受到 LLM 驱动代码生成趋势的启发,强调简单而清晰的
     * **VM code**（虚拟机指令）会展示虚拟机的字节码指令。
 
 3. **默认执行模式:**
-   编译器会在 **DEBUG 模式** 下运行，显示详细的执行过程和状态，并且在虚拟机中执行编译后的代码，最后会打印出所有局部变量的值。
+   编译器会在 **RUN 模式** 下运行，**DEBUG 模式**显示详细的执行过程和状态，并且在虚拟机中执行编译后的代码，最后会打印出所有局部变量的值。
 
 ---
 
@@ -462,6 +579,12 @@ end module
 “SnowLang 项目”为由许轲（Luke）发起的独立开源项目。  
 未来，项目可能会成立正式的组织或实体，以进一步负责本项目的开发和管理。
 
+## 支持我们
+
+如果你喜欢我们的项目，欢迎给我们一个 Star！  
+你们的关注和支持，是我们团队持续进步的动力源泉！谢谢大家！
+
+
 ## 加入我们
 
 - 微信: `xuxiaolankaka`

docs/SnowVM-OpCode/SnowVM-OpCode.md

@@ -1,7 +1,8 @@
 # SnowVM-OpCode
 
-## 1. Byte8 区域（0x0000-0x001F）
+## Type Control (0x0000-0x00BF)
 
+### Byte8	 (0x0000-0x001F)
 | 指令名      | 十六进制   | 说明             |
 |----------|--------|----------------|
 | B\_ADD   | 0x0000 | byte8 加法       |
@@ -26,7 +27,7 @@
 
 ---
 
-## 2. Short16 区域（0x0020-0x003F）
+### Short16 (0x0020-0x003F)
 
 | 指令名      | 十六进制   | 说明               |
 |----------|--------|------------------|
@@ -52,7 +53,7 @@
 
 ---
 
-## 3. Int32 区域（0x0040-0x005F）
+### Int32 (0x0040-0x005F)
 
 | 指令名      | 十六进制   | 说明             |
 |----------|--------|----------------|
@@ -78,7 +79,7 @@
 
 ---
 
-## 4. Long64 区域（0x0060-0x007F）
+### Long64 区域（0x0060-0x007F）
 
 | 指令名      | 十六进制   | 说明              |
 |----------|--------|-----------------|
@@ -104,7 +105,7 @@
 
 ---
 
-## 5. Float32 区域（0x0080-0x009F）
+### Float32 区域（0x0080-0x009F）
 
 | 指令名      | 十六进制   | 说明               |
 |----------|--------|------------------|
@@ -127,7 +128,7 @@
 
 ---
 
-## 6. Double64 区域（0x00A0-0x00BF）
+### Double64 区域（0x00A0-0x00BF）
 
 | 指令名      | 十六进制   | 说明                |
 |----------|--------|-------------------|
@@ -150,7 +151,7 @@
 
 ---
 
-## 7. 类型转换（0x00C0-0x00DF）
+## Type Conversion (0x00C0-0x00DF)
 
 | 指令名 | 十六进制   | 说明                 |
 |-----|--------|--------------------|
@@ -185,11 +186,17 @@
 | D2L | 0x00DC | double64 转 long64  |
 | D2F | 0x00DD | double64 转 float32 |
 
-
-
 ---
+## Reference Control (0x00E0-0x00EF)
+| 指令名      | 十六进制   | 说明                        |
+|----------|--------|---------------------------|
+| R\_PUSH  | 0x00E0 | 将对象引用压入操作数栈               |
+| R\_LOAD  | 0x00E1 | 从本地变量表加载对象引用并压入操作数栈       |
+| R\_STORE | 0x00E2 | 将操作数栈顶的对象引用弹出并存入本地变量表指定槽位 |
 
-## 8. 栈控制（0x0100-0x01FF）
+
+
+## Stack Control (0x0100-0x01FF)
 
 | 指令名  | 十六进制   | 说明       |
 |------|--------|----------|
@@ -199,7 +206,7 @@
 
 ---
 
-## 9. 流程控制（0x0200-0x02FF）
+## Flow Control (0x0200-0x02FF)
 
 | 指令名  | 十六进制/十进制 | 说明    |
 |------|----------|-------|
@@ -209,7 +216,7 @@
 
 ---
 
-## 10. 寄存器控制（0x0300-0x03FF）
+##  Register Control (0x0300-0x03FF)
 
 | 指令名 | 十六进制   | 说明      |
 |-----|--------|---------|
@@ -217,7 +224,7 @@
 
 ---
 
-## 11. 系统控制（0x0400-0x04FF）
+## System Control (0x0400-0x04FF)
 
 | 指令名         | 十六进制   | 说明   |
 |-------------|--------|------|

pom.xml

@@ -7,7 +7,7 @@
 
     <groupId>org.jcnc.snow</groupId>
     <artifactId>Snow</artifactId>
-    <version>0.4.2</version>
+    <version>0.5.0</version>
 
     <properties>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

src/main/java/module-info.java

@@ -4,7 +4,6 @@ module org.jcnc.snow.compiler {
     uses CLICommand;
     requires java.desktop;
     requires java.logging;
-    requires org.graalvm.nativeimage;
     exports org.jcnc.snow.compiler.ir.core;
     exports org.jcnc.snow.compiler.ir.instruction;
 }

src/main/java/org/jcnc/snow/cli/SnowCLI.java

@@ -4,6 +4,8 @@ import org.jcnc.snow.cli.api.CLICommand;
 import org.jcnc.snow.cli.commands.*;
 import org.jcnc.snow.cli.utils.CLIUtils;
 import org.jcnc.snow.cli.utils.VersionUtils;
+import org.jcnc.snow.common.Mode;
+import org.jcnc.snow.common.SnowConfig;
 
 import java.util.Arrays;
 import java.util.Map;

src/main/java/org/jcnc/snow/cli/utils/CLIUtils.java

@@ -26,12 +26,21 @@ public class CLIUtils {
             "-v", "--version"
     );
 
+    /**
+     * 全局调试标志集合，支持 "-debug"、"--debug"。
+     */
+    public static final Set<String> GLOBAL_DEBUG_FLAGS = Set.of(
+            "--debug"
+    );
+
     /**
      * 全局选项列表，包括帮助和版本选项的描述。
      */
     public static final List<Option> GLOBAL_OPTIONS = List.of(
             new Option(List.of("-h", "--help"), "Show this help message and exit"),
-            new Option(List.of("-v", "--version"), "Print snow programming language version and exit")
+            new Option(List.of("-v", "--version"), "Print snow programming language version and exit"),
+            new Option(List.of("-debug", "--debug"), "Enable debug mode with verbose internal logs")
+
     );
 
     /**

src/main/java/org/jcnc/snow/vm/utils/VMUtils.java

@@ -1,6 +1,5 @@
 package org.jcnc.snow.vm.utils;
 
-import org.graalvm.nativeimage.ImageInfo;
 import org.jcnc.snow.vm.engine.VirtualMachineEngine;
 
 /**
@@ -52,9 +51,11 @@ public class VMUtils {
      */
     public static boolean isNativeImage() {
         try {
-            return ImageInfo.inImageCode();
+            Class<?> imageInfo = Class.forName("org.graalvm.nativeimage.ImageInfo");
+            return (Boolean) imageInfo.getMethod("inImageCode").invoke(null);
         } catch (Throwable t) {
             return false;
         }
     }
+
 }