docs: 统一注释风格

src/main/java/org/jcnc/snow/pkg/lifecycle/LifecycleManager.java

@@ -6,9 +6,10 @@ import java.util.EnumMap;
 import java.util.Map;
 
 /**
- * 管理不同生命周期阶段与其对应任务的工具类。
+ * 生命周期任务管理器。<br>
+ * 用于管理不同生命周期阶段与其对应 {@link Task}，并支持顺序执行所有已注册任务。
  * <p>
- * 可为每个 {@link LifecyclePhase} 注册对应的 {@link Task}，并按阶段顺序执行所有任务。
+ * 可为每个 {@link LifecyclePhase} 注册对应的 {@link Task}，并在构建/部署流程中自动执行。
  * </p>
  *
  * <pre>
@@ -20,9 +21,7 @@ import java.util.Map;
  */
 public final class LifecycleManager {
 
-    /**
+    /** 生命周期阶段与对应任务的映射关系 */
-     * 存储生命周期阶段与对应任务的映射关系。
-     */
     private final Map<LifecyclePhase, Task> tasks = new EnumMap<>(LifecyclePhase.class);
 
     /**
@@ -45,11 +44,13 @@ public final class LifecycleManager {
 
     /**
      * 按 {@link LifecyclePhase} 声明顺序依次执行所有已注册任务。
-     * <p>
+     * <ul>
-     * 未注册任务的阶段将被跳过。任务执行前会打印阶段名。
+     *   <li>未注册任务的阶段会被自动跳过</li>
-     * </p>
+     *   <li>每个任务执行前会输出当前阶段名</li>
+     *   <li>执行中遇到异常将立即抛出并终止后续执行</li>
+     * </ul>
      *
-     * @throws Exception 若某个任务执行时抛出异常，将直接抛出并终止后续任务执行
+     * @throws Exception 若某个任务执行时抛出异常，将直接抛出
      */
     public void executeAll() throws Exception {
         for (LifecyclePhase phase : LifecyclePhase.values()) {

src/main/java/org/jcnc/snow/pkg/lifecycle/LifecyclePhase.java

@@ -1,7 +1,10 @@
 package org.jcnc.snow.pkg.lifecycle;
 
 /**
- * 定义了典型软件包生命周期的各个阶段。
+ * 定义典型软件包生命周期的各个阶段枚举。
+ * <p>
+ * 用于区分构建、依赖、发布等不同阶段的任务调度与管理。
+ * </p>
  */
 public enum LifecyclePhase {
     /** 初始化阶段 */

src/main/java/org/jcnc/snow/pkg/model/BuildConfiguration.java

@@ -6,16 +6,16 @@ import java.util.HashMap;
 /**
  * 构建配置对象，封装构建过程中的所有选项。
  * <p>
- * 支持基于模板变量（形如{@code @{key}}）的选项值替换。
+ * 支持模板变量（形如 <code>@{key}</code>）的值自动替换。
  * </p>
  */
 public final class BuildConfiguration {
 
-    /** 存储配置项的键值对 */
+    /** 存储所有配置项 */
     private final Map<String, String> options;
 
     /**
-     * 私有构造函数，用于初始化配置项。
+     * 私有构造函数，仅供工厂方法调用。
      *
      * @param options 配置项键值对
      */
@@ -24,14 +24,15 @@ public final class BuildConfiguration {
     }
 
     /**
-     * 基于原始配置项和变量属性创建配置对象。
+     * 基于原始配置项和属性集创建配置对象。
-     * <p>
+     * <ul>
-     * 会将原始配置中的所有值中的{@code @{key}}模板，替换为属性props中对应的值。
+     *   <li>会将所有值中的 <code>@{key}</code> 模板变量，替换为 props 中对应的值</li>
-     * </p>
+     *   <li>属性未匹配到时保留原模板</li>
+     * </ul>
      *
-     * @param flat  原始的配置项，值中可包含模板变量（如@{name}）
+     * @param flat  原始配置项，值中可包含模板变量
-     * @param props 用于替换模板变量的属性集
+     * @param props 变量替换用的属性集
-     * @return 构建完成的配置对象
+     * @return 处理后生成的配置对象
      */
     public static BuildConfiguration fromFlatMap(Map<String, String> flat, Map<String, String> props) {
         Map<String, String> resolved = new HashMap<>();
@@ -46,11 +47,11 @@ public final class BuildConfiguration {
     }
 
     /**
-     * 获取指定key对应的配置值。
+     * 获取指定配置项的值。
      *
      * @param key 配置项名称
-     * @param def 默认值（若未找到key则返回此值）
+     * @param def 默认值（未找到时返回）
-     * @return 配置项对应值，若不存在则返回默认值
+     * @return 配置项值，若不存在则返回默认值
      */
     public String get(String key, String def) {
         return options.getOrDefault(key, def);

src/main/java/org/jcnc/snow/pkg/model/Dependency.java

@@ -5,18 +5,23 @@ import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
 /**
- * group:artifact:version 依赖坐标。
+ * group:artifact:version 依赖坐标对象。
  * <p>
- * 支持通过占位符和属性映射进行动态变量替换，可用于构建工具或依赖管理场景。
+ * 支持占位符和属性映射进行动态变量替换，适用于 Snow 语言包管理和源码依赖场景。
  * </p>
  *
  * <pre>
- * 示例：
+ * 示例用法：
  * Dependency dep = Dependency.fromString(
  *     "core", "com.example:core:@{version}",
  *     Map.of("version", "1.2.3")
  * );
  * </pre>
+ *
+ * @param id       依赖唯一标识
+ * @param group    组织/分组名
+ * @param artifact 构件名
+ * @param version  版本号
  */
 public record Dependency(
         String id,
@@ -25,25 +30,23 @@ public record Dependency(
         String version
 ) {
 
-    /**
+    /** 匹配 group:artifact:version 格式的正则表达式。 */
-     * 用于匹配 group:artifact:version 格式的正则表达式。
-     */
     private static final Pattern GAV = Pattern.compile("([^:]+):([^:]+):(.+)");
 
     /**
      * 根据字符串坐标和属性映射创建依赖对象。
      * <p>
-     * 坐标中的占位符如 {@code @{key}} 会用 props 中对应的值替换。
+     * 坐标中的占位符（如 <code>@{key}</code>）会用 props 中对应的值替换。
      * </p>
      *
      * @param id         依赖唯一标识
-     * @param coordinate 依赖坐标字符串，格式为 group:artifact:version，支持变量占位符
+     * @param coordinate 坐标字符串，格式为 group:artifact:version，支持占位符
-     * @param props      占位符替换的属性映射
+     * @param props      占位符替换属性映射
      * @return 解析后的 Dependency 实例
-     * @throws IllegalArgumentException 如果坐标格式非法
+     * @throws IllegalArgumentException 坐标格式非法时抛出
      */
     public static Dependency fromString(String id, String coordinate, Map<String, String> props) {
-        // 替换 @{prop} 占位符
+        // 替换占位符
         String resolved = coordinate;
         for (Map.Entry<String, String> p : props.entrySet()) {
             resolved = resolved.replace("@{" + p.getKey() + "}", p.getValue());
@@ -57,23 +60,23 @@ public record Dependency(
     }
 
     /**
-     * 生成依赖对应的标准仓库 jar 路径。
+     * 生成依赖对应的源码文件路径。
      * <p>
-     * 路径格式通常为：groupId/artifactId/version/artifactId-version.jar<br>
+     * 路径格式：groupId/artifactId/version/artifactId.snow
-     * 例如：com/example/core/1.2.3/core-1.2.3.jar
+     * 例如：com/example/core/1.2.3/core.snow
      * </p>
      *
-     * @return 仓库 jar 文件的相对路径
+     * @return 仓库源码文件的相对路径
      */
     public String toPath() {
         String groupPath = group.replace('.', '/');
-        return groupPath + "/" + artifact + "/" + version + "/" + artifact + "-" + version + ".jar";
+        return groupPath + "/" + artifact + "/" + version + "/" + artifact + ".snow";
     }
 
     /**
      * 返回该依赖的 group:artifact:version 字符串表示。
      *
-     * @return Maven 坐标字符串
+     * @return 坐标字符串
      */
     @Override
     public String toString() {

src/main/java/org/jcnc/snow/pkg/model/Project.java

@@ -8,42 +8,41 @@ import java.util.Map;
 /**
  * 表示一个软件包/模块的项目信息，包括元数据、属性、仓库、依赖和构建配置等。
  * <p>
- * 本类为不可变对象，仅提供getter，无setter。
+ * 本类为不可变对象，仅提供 getter 方法，无 setter。<br>
- * 支持通过 {@link #fromFlatMap(Map)} 静态工厂方法从扁平Map快速创建。
+ * 支持通过 {@link #fromFlatMap(Map)} 静态工厂方法，从扁平 Map 快速创建实例。
  * </p>
  *
  * <pre>
- * Map&lt;String,String&gt; map = ...;
+ * Map&lt;String, String&gt; map = ...;
  * Project project = Project.fromFlatMap(map);
  * </pre>
  */
 public final class Project {
 
-    /** 组织/分组名（如com.example） */
+    /** 组织/分组名（如 com.example） */
     private final String group;
-    /** 构件/模块名（如app-core） */
+    /** 构件/模块名（如 app-core） */
     private final String artifact;
     /** 项目展示名称 */
     private final String name;
-    /** 版本号（如1.0.0） */
+    /** 版本号（如 1.0.0） */
     private final String version;
     /** 项目描述 */
     private final String description;
     /** 许可证标识 */
     private final String license;
-    /** 项目主页URL */
+    /** 项目主页 URL */
     private final String homepage;
 
     /** 额外属性（不影响主字段，可用于模板/占位符） */
     private final Map<String, String> properties;
-    /** 仓库列表（仓库ID -> 仓库对象） */
+    /** 仓库列表（仓库 ID -> 仓库对象） */
     private final Map<String, Repository> repositories;
     /** 依赖列表 */
     private final List<Dependency> dependencies;
     /** 构建配置 */
     private final BuildConfiguration build;
 
-
     /**
      * 构造函数（私有），请使用 {@link #fromFlatMap(Map)} 创建实例。
      */
@@ -74,7 +73,7 @@ public final class Project {
     }
 
     /**
-     * 通过扁平Map创建 Project 实例。约定key格式如下：
+     * 通过扁平 Map 创建 Project 实例。key 格式约定如下：
      * <ul>
      *   <li>project.*      —— 项目元数据</li>
      *   <li>properties.*   —— 额外属性</li>
@@ -83,12 +82,11 @@ public final class Project {
      *   <li>build.*        —— 构建配置</li>
      * </ul>
      *
-     * @param map 扁平的配置map
+     * @param map 扁平的配置 map
      * @return Project 实例
      */
     public static Project fromFlatMap(Map<String, String> map) {
-
+        // 1. 基本元数据
-        // 1. simple project metadata
         String group = map.getOrDefault("project.group", "unknown");
         String artifact = map.getOrDefault("project.artifact", "unknown");
         String name = map.getOrDefault("project.name", artifact);
@@ -123,14 +121,13 @@ public final class Project {
             }
         });
 
-        // 5. build.* simply hand the subtree map
+        // 5. build.*
         Map<String, String> buildMap = new LinkedHashMap<>();
         map.forEach((k, v) -> {
             if (k.startsWith("build.")) {
                 buildMap.put(k.substring("build.".length()), v);
             }
         });
-
         BuildConfiguration buildCfg = BuildConfiguration.fromFlatMap(buildMap, props);
 
         return new Project(group, artifact, name, version, description, license, homepage, props, repos, deps, buildCfg);
@@ -161,12 +158,12 @@ public final class Project {
         return description;
     }
 
-    /** @return 许可证 */
+    /** @return 许可证标识 */
     public String getLicense() {
         return license;
     }
 
-    /** @return 项目主页URL */
+    /** @return 项目主页 URL */
     public String getHomepage() {
         return homepage;
     }

src/main/java/org/jcnc/snow/pkg/model/Repository.java

@@ -3,16 +3,16 @@ package org.jcnc.snow.pkg.model;
 /**
  * 表示一个远程仓库的基本信息，通常用于依赖解析和发布。
  * <p>
- * 每个仓库由唯一的ID和对应的URL确定。
+ * 每个仓库由唯一的 ID 和对应的 URL 标识。
  * </p>
  *
  * <pre>
- * 示例:
+ * 示例用法：
  * Repository repo = new Repository("central", "https://");
  * </pre>
  *
  * @param id  仓库唯一标识
- * @param url 仓库地址（一般为HTTP(S)链接）
+ * @param url 仓库地址（通常为 HTTP(S) 链接）
  */
 public record Repository(String id, String url) {
 }

src/main/java/org/jcnc/snow/pkg/tasks/CleanTask.java

@@ -6,17 +6,27 @@ import java.nio.file.Path;
 import java.util.Comparator;
 
 /**
- * 清理构建输出目录（如 build 和 dist）的任务实现。
+ * 用于清理构建输出目录（如 {@code build} 和 {@code dist}）的任务实现类。
  * <p>
- * 实现 {@link Task} 接口，通常用于构建流程中的清理阶段。
+ * 实现 {@link Task} 接口，常用于自动化构建流程的清理阶段，负责递归删除指定的构建产物目录。
  * </p>
+ * <p>
+ * 本类为无状态实现，线程安全。
+ * </p>
+ *
+ * <p><b>示例用法：</b></p>
+ * <pre>{@code
+ * Task clean = new CleanTask();
+ * clean.run();
+ * }</pre>
  */
 public final class CleanTask implements Task {
 
     /**
-     * 执行清理任务，删除 "build" 和 "dist" 目录及其所有内容。
+     * 执行清理任务，递归删除当前目录下的 {@code build} 和 {@code dist} 目录及其所有内容。
+     * 如果目标目录不存在，则跳过不处理。
      *
-     * @throws IOException 删除目录过程中出现 IO 错误时抛出
+     * @throws IOException 删除目录或文件过程中发生 IO 错误时抛出
      */
     @Override
     public void run() throws IOException {
@@ -27,10 +37,15 @@ public final class CleanTask implements Task {
 
     /**
      * 递归删除指定目录及其所有子文件和子目录。
-     * 使用 try-with-resources 自动关闭文件流，避免资源泄漏。
+     * <p>
+     * 若目录不存在，则直接返回。
+     * </p>
+     * <p>
+     * 内部使用 try-with-resources 保证文件流自动关闭，避免资源泄漏。
+     * </p>
      *
      * @param dir 需要删除的目录路径
-     * @throws IOException 删除过程中出现 IO 错误时抛出
+     * @throws IOException 删除目录或文件过程中发生 IO 错误时抛出
      */
     private void deleteDir(Path dir) throws IOException {
         if (Files.notExists(dir)) return;

src/main/java/org/jcnc/snow/pkg/tasks/CompileTask.java

@@ -25,17 +25,16 @@ import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.*;
 
-
 /**
- * CLI 命令：将 .snow 源文件编译为 VM 字节码（.water 文件）。
+ * CLI 任务：编译 .snow 源文件为 VM 字节码（.water 文件）。
  * <p>
- * 支持递归目录、多文件编译，可选编译后立即运行。<br>
+ * 支持单文件、多文件和目录递归编译，并可在编译后立即运行虚拟机。<br>
- * 命令参数支持 run、-o、-d 等。
+ * 命令行参数支持 run、-o、-d 及直接指定源文件。
  * </p>
  *
  * <pre>
  * 用法示例：
- * $ snow compile [run] [-o &lt;name&gt;] [-d &lt;srcDir&gt;] [file1.snow file2.snow …]
+ * $ snow compile [run] [-o &lt;name&gt;] [-d &lt;srcDir&gt;] [file1.snow file2.snow ...]
  * </pre>
  */
 public final class CompileTask implements Task {
@@ -44,26 +43,49 @@ public final class CompileTask implements Task {
     /** 原始命令行参数 */
     private final String[] args;
 
+    /**
+     * 创建一个编译任务。
+     *
+     * @param project  项目信息对象
+     * @param args     命令行参数数组
+     */
     public CompileTask(Project project, String[] args) {
         this.project = project;
         this.args = args;
     }
 
+    /**
+     * 创建一个不带参数的编译任务。
+     *
+     * @param project 项目信息对象
+     */
     public CompileTask(Project project) {
         this(project, new String[0]);
     }
 
+    /**
+     * 执行编译任务。该方法会解析参数并调用 {@link #execute(String[])} 进行实际编译流程。
+     *
+     * @throws Exception 执行过程中出现任意异常时抛出
+     */
     @Override
     public void run() throws Exception {
-        // 将任务委托给原始 execute 实现
         execute(this.args);
     }
 
-    /* --------------------------------------------------------------------- */
+    /**
-    /* 执行 compile 子命令                                              */
+     * 编译 .snow 源文件为 VM 字节码，并可选择立即运行。
-    /* --------------------------------------------------------------------- */
+     * <ul>
+     *   <li>支持参数 run（编译后运行）、-o（输出文件名）、-d（递归目录）、直接指定多个源文件。</li>
+     *   <li>输出源代码、AST、IR、最终 VM code，并写出 .water 文件。</li>
+     * </ul>
+     *
+     * @param args 命令行参数数组
+     * @return 0 表示成功，非 0 表示失败
+     * @throws Exception 编译或写入过程中出现异常时抛出
+     */
     public int execute(String[] args) throws Exception {
-        /* ---------------- 解析命令行参数 ---------------- */
+        // ---------------- 解析命令行参数 ----------------
         boolean runAfterCompile = false;
         String outputName = null;
         Path dir = null;
@@ -101,7 +123,7 @@ public final class CompileTask implements Task {
             }
         }
 
-        /* --------- 如果指定了目录则递归收集所有 *.snow --------- */
+        // --------- 如果指定了目录则递归收集所有 *.snow ---------
         if (dir != null) {
             if (!Files.isDirectory(dir)) {
                 System.err.println("Not a directory: " + dir);
@@ -119,19 +141,17 @@ public final class CompileTask implements Task {
             return 1;
         }
 
-        /* 多文件但未指定 -o 且非目录编译 —— 提示必须指定输出名 */
+        // 多文件但未指定 -o 且非目录编译 —— 提示必须指定输出名
         if (sources.size() > 1 && outputName == null && dir == null) {
             System.err.println("Please specify output name using -o <name>");
             return 1;
         }
 
-        /* ----------------------------------------------------------------- */
+        // ---------------- 1. 词法/语法分析，并打印源代码 ----------------
-        /* 1. 词法 + 语法分析；同时打印源代码                                */
-        /* ----------------------------------------------------------------- */
         List<Node> allAst = new ArrayList<>();
 
         System.out.println("## 编译器输出");
-        System.out.println("### Snow 源代码");        // ========== 新增：二级标题 ==========
+        System.out.println("### Snow 源代码");
 
         for (Path p : sources) {
             if (!Files.exists(p)) {
@@ -141,38 +161,31 @@ public final class CompileTask implements Task {
 
             String code = Files.readString(p, StandardCharsets.UTF_8);
 
-            // ------- 打印每个文件的源码 -------
+            // 打印源码
             System.out.println("#### " + p.getFileName());
             System.out.println(code);
-            // --------------------------------------------------------
 
-            /* 词法 + 语法 */
+            // 词法、语法分析
             LexerEngine lexer = new LexerEngine(code, p.toString());
             ParserContext ctx = new ParserContext(lexer.getAllTokens(), p.toString());
             allAst.addAll(new ParserEngine(ctx).parse());
         }
 
-        /* ----------------------------------------------------------------- */
+        // ---------------- 2. 语义分析 ----------------
-        /* 2. 语义分析                                                       */
-        /* ----------------------------------------------------------------- */
         SemanticAnalyzerRunner.runSemanticAnalysis(allAst, false);
 
-        /* ----------------------------------------------------------------- */
+        // ---------------- 3. AST → IR，并将 main 函数移动至首位 ----------------
-        /* 3. AST → IR，并把 main 函数调到首位                                */
-        /* ----------------------------------------------------------------- */
         IRProgram program = new IRProgramBuilder().buildProgram(allAst);
         program = reorderForEntry(program);
 
-        /* ---------------- 打印 AST / IR ---------------- */
+        // 打印 AST 和 IR
         System.out.println("### AST");
         ASTPrinter.printJson(allAst);
 
         System.out.println("### IR");
         System.out.println(program);
 
-        /* ----------------------------------------------------------------- */
+        // ---------------- 4. IR → VM 指令 ----------------
-        /* 4. IR → VM 指令                                                   */
-        /* ----------------------------------------------------------------- */
         VMProgramBuilder builder = new VMProgramBuilder();
         List<InstructionGenerator<? extends IRInstruction>> generators =
                 InstructionGeneratorProvider.defaultGenerators();
@@ -187,16 +200,12 @@ public final class CompileTask implements Task {
         System.out.println("### VM code");
         finalCode.forEach(System.out::println);
 
-        /* ----------------------------------------------------------------- */
+        // ---------------- 5. 写出 .water 文件 ----------------
-        /* 5. 写出 .water 文件                                               */
-        /* ----------------------------------------------------------------- */
         Path outputFile = deriveOutputPath(sources, outputName, dir);
         Files.write(outputFile, finalCode, StandardCharsets.UTF_8);
         System.out.println("Written to " + outputFile.toAbsolutePath());
 
-        /* ----------------------------------------------------------------- */
+        // ---------------- 6. 可选：立即运行 VM ----------------
-        /* 6. 可选：立即运行 VM                                              */
-        /* ----------------------------------------------------------------- */
         if (runAfterCompile) {
             System.out.println("\n=== Launching VM ===");
             VMLauncher.main(new String[]{outputFile.toString()});
@@ -205,18 +214,19 @@ public final class CompileTask implements Task {
         return 0;
     }
 
-    /* --------------------------------------------------------------------- */
-    /* 辅助方法                                                              */
-    /* --------------------------------------------------------------------- */
-
     /**
-     * 根据输入情况推断 .water 输出文件名：
+     * 推断 .water 输出文件名。
      * <ul>
-     *   <li>若指定 -o，则直接使用</li>
+     *   <li>如果指定 -o，直接使用该名称。</li>
-     *   <li>目录编译：取目录名</li>
+     *   <li>目录编译时，取目录名。</li>
-     *   <li>单文件编译：取文件名去掉 .snow</li>
+     *   <li>单文件编译时，取文件名去掉 .snow 后缀。</li>
-     *   <li>其他情况兜底为 "program"</li>
+     *   <li>否则默认 "program"。</li>
      * </ul>
+     *
+     * @param sources   源文件路径列表
+     * @param outName   输出文件名（如有指定，否则为 null）
+     * @param dir       源码目录（如有指定，否则为 null）
+     * @return 推断出的输出文件路径（.water 文件）
      */
     private static Path deriveOutputPath(List<Path> sources, String outName, Path dir) {
         String base;
@@ -234,7 +244,10 @@ public final class CompileTask implements Task {
     }
 
     /**
-     * 把 main 函数交换到程序函数列表首位，确保 PC=0 即入口。
+     * 将 main 函数调整至函数列表首位，确保程序入口为 PC=0。
+     *
+     * @param in 原始 IRProgram
+     * @return 调整入口后的 IRProgram
      */
     private static IRProgram reorderForEntry(IRProgram in) {
         List<IRFunction> ordered = new ArrayList<>(in.functions());

src/main/java/org/jcnc/snow/pkg/tasks/GenerateTask.java

@@ -10,9 +10,10 @@ import java.nio.file.Paths;
 import java.util.List;
 
 /**
- * 任务：依据 {@link Project} 元数据创建标准项目目录。
+ * 项目脚手架生成任务。<br>
+ * 根据 {@link Project} 元数据自动创建标准项目目录结构，并生成示例入口文件 <code>src/main.snow</code>。
  * <p>
- * 生成内容：
+ * 生成内容包括：
  * <ul>
  *   <li>src/          —— 源码目录</li>
  *   <li>test/         —— 测试源码目录</li>
@@ -20,27 +21,44 @@ import java.util.List;
  *   <li>dist/         —— 打包输出目录</li>
  *   <li>src/main.snow —— “Hello, Snow!” 示例入口</li>
  * </ul>
+ * 如目录或入口文件已存在，则自动跳过，不会覆盖。
+ * </p>
  */
 public final class GenerateTask implements Task {
 
+    /** 项目信息元数据 */
     private final Project project;
 
+    /**
+     * 创建项目生成任务。
+     *
+     * @param project 项目信息元数据对象
+     */
     public GenerateTask(Project project) {
         this.project = project;
     }
 
+    /**
+     * 执行脚手架生成流程，创建标准目录和入口示例文件。
+     * <ul>
+     *   <li>若相关目录不存在则创建</li>
+     *   <li>若 <code>src/main.snow</code> 不存在则写入模板</li>
+     *   <li>生成过程输出进度信息</li>
+     * </ul>
+     *
+     * @throws IOException 创建目录或写入文件时发生 IO 错误时抛出
+     */
     @Override
     public void run() throws IOException {
         Path root = Paths.get(".").toAbsolutePath();
 
-        /* -------- 创建目录 -------- */
+        // 创建标准目录
         List<Path> dirs = List.of(
                 root.resolve("src"),
                 root.resolve("test"),
                 root.resolve("build"),
                 root.resolve("dist")
         );
-
         for (Path dir : dirs) {
             if (Files.notExists(dir)) {
                 Files.createDirectories(dir);
@@ -48,7 +66,7 @@ public final class GenerateTask implements Task {
             }
         }
 
-        /* -------- 创建示例入口文件 -------- */
+        // 创建 src/main.snow 示例入口文件
         Path mainSnow = root.resolve("src").resolve("main.snow");
         if (Files.notExists(mainSnow)) {
             Files.writeString(mainSnow, SnowExampleTemplate.getMainModule());

src/main/java/org/jcnc/snow/pkg/tasks/PackageTask.java

@@ -9,29 +9,38 @@ import java.util.zip.ZipEntry;
 import java.util.zip.ZipOutputStream;
 
 /**
- * 项目打包任务，将编译输出目录（如 build/classes）打包为 .ice 文件。
+ * 项目打包任务，将编译输出目录（如 <code>build/classes</code>）打包为 .ice 文件。
  * <p>
- * 实现 {@link Task} 接口，通常用于构建流程中的打包阶段。
+ * 实现 {@link Task} 接口，通常用于构建流程的打包阶段。<br>
+ * 只会打包 build/classes 目录下所有文件，不含其他目录。
+ * </p>
+ * <p>
+ * 输出文件位于 dist 目录，命名为 artifact-version.ice。
  * </p>
  */
 public final class PackageTask implements Task {
 
-    /** 目标项目 */
+    /** 目标项目元数据 */
     private final Project project;
 
     /**
-     * 创建 PackageTask 实例。
+     * 创建打包任务。
      *
-     * @param project 目标项目
+     * @param project 目标项目元数据
      */
     public PackageTask(Project project) {
         this.project = project;
     }
 
     /**
-     * 执行打包任务，将编译输出目录压缩为 artifact-version.ice 文件。
+     * 执行打包任务，将 build/classes 目录下所有文件压缩为 dist/artifact-version.ice。
+     * <ul>
+     *   <li>若输出目录 dist 不存在会自动创建</li>
+     *   <li>只打包 build/classes 下所有普通文件（保持相对目录结构）</li>
+     *   <li>如无 build/classes 则不会生成包</li>
+     * </ul>
      *
-     * @throws Exception 打包过程中出现 IO 或其他异常时抛出
+     * @throws Exception 打包过程中发生 IO 或其他异常时抛出
      */
     @Override
     public void run() throws Exception {
@@ -43,15 +52,15 @@ public final class PackageTask implements Task {
         Path packageFile = distDir.resolve(fileName);
 
         try (ZipOutputStream zos = new ZipOutputStream(Files.newOutputStream(packageFile))) {
-            // 仅将编译输出目录打包
+            // 仅将 build/classes 目录打包
             Path classesDir = Path.of("build/classes");
             if (Files.exists(classesDir)) {
-                // 使用 try-with-resources 正确关闭 Stream<Path>
+                // 遍历所有文件并写入 zip
                 try (Stream<Path> stream = Files.walk(classesDir)) {
                     stream.filter(Files::isRegularFile)
                             .forEach(p -> {
                                 try {
-                                    // 将文件以相对路径加入压缩包
+                                    // 以 classesDir 为根的相对路径存入 zip
                                     zos.putNextEntry(new ZipEntry(classesDir.relativize(p).toString()));
                                     Files.copy(p, zos);
                                     zos.closeEntry();

src/main/java/org/jcnc/snow/pkg/tasks/PublishTask.java

@@ -5,25 +5,26 @@ import org.jcnc.snow.pkg.model.Project;
 /**
  * 发布项目构件到远程仓库的任务实现。
  * <p>
- * 实现 {@link Task} 接口，通常用于构建流程中的发布阶段。目前仅为演示，尚未实现实际上传。
+ * 实现 {@link Task} 接口，通常用于构建流程中的发布阶段。
+ * 当前仅输出发布提示，尚未实现实际上传功能。
  * </p>
  */
 public final class PublishTask implements Task {
 
-    /** 目标项目 */
+    /** 目标项目元数据 */
     private final Project project;
 
     /**
-     * 创建 PublishTask 实例。
+     * 创建发布任务。
      *
-     * @param project 目标项目
+     * @param project 目标项目元数据
      */
     public PublishTask(Project project) {
         this.project = project;
     }
 
     /**
-     * 执行发布任务。当前仅打印发布提示，未实现实际上传逻辑。
+     * 执行发布任务。目前仅打印发布提示信息，未实现实际上传逻辑。
      *
      * @throws Exception 预留，未来实现上传逻辑时可能抛出异常
      */

src/main/java/org/jcnc/snow/pkg/tasks/RunTask.java

@@ -1,4 +1,3 @@
-
 package org.jcnc.snow.pkg.tasks;
 
 import org.jcnc.snow.vm.VMLauncher;
@@ -6,26 +5,32 @@ import org.jcnc.snow.vm.VMLauncher;
 /**
  * 任务：执行已编译的 VM 字节码文件（.water）。
  * <p>
- * 作为 CLI、IDE 插件或其他宿主环境启动虚拟机的统一入口，
+ * 作为 CLI、IDE 插件或其他宿主环境启动虚拟机的统一入口，<br>
- * 将调用 {@link VMLauncher#main(String[])} 执行。
+ * 通过调用 {@link VMLauncher#main(String[])} 启动 VM 并执行指定程序。
  * </p>
  */
 public final class RunTask implements Task {
 
-    /** 传递给 VM 的完整参数列表（第一个应为 .water 文件路径） */
+    /**
+     * 传递给虚拟机的完整参数列表（第一个应为 .water 文件路径）
+     */
     private final String[] args;
 
     /**
      * 创建运行任务。
      *
-     * @param args VM 参数数组（第一个为程序路径，其后为可选参数）
+     * @param args VM 参数数组（第一个为 .water 程序路径，其后为可选参数）
      */
     public RunTask(String... args) {
         this.args = args;
     }
 
     /**
-     * 执行运行任务，内部委托 {@link VMLauncher#main(String[])}。
+     * 执行运行任务。内部委托 {@link VMLauncher#main(String[])} 启动 VM。
+     * <ul>
+     *   <li>如果参数为空则抛出 {@link IllegalArgumentException}</li>
+     *   <li>异常由虚拟机本身抛出，直接透出</li>
+     * </ul>
      *
      * @throws Exception 虚拟机启动或运行期间抛出的异常
      */

src/main/java/org/jcnc/snow/pkg/tasks/Task.java

@@ -1,9 +1,9 @@
 package org.jcnc.snow.pkg.tasks;
 
 /**
- * 构建任务的通用接口，所有具体任务都应实现该接口。
+ * 构建任务的通用接口，所有具体任务（如编译、打包、清理等）都应实现该接口。
  * <p>
- * 用于统一生命周期内的任务行为，例如编译、打包、清理等。
+ * 用于统一不同阶段任务的生命周期与执行行为。
  * </p>
  */
 public interface Task {
@@ -11,7 +11,7 @@ public interface Task {
     /**
      * 执行具体任务的入口方法。
      *
-     * @throws Exception 任务执行过程中出现的异常
+     * @throws Exception 任务执行过程中出现的任意异常
      */
     void run() throws Exception;
 }

src/main/java/org/jcnc/snow/pkg/utils/SnowExampleTemplate.java

@@ -1,18 +1,24 @@
 package org.jcnc.snow.pkg.utils;
 
 /**
- * 提供示例 .snow 模块代码模板。
+ * 示例模块模板工具类，提供 main.snow 的标准示例代码字符串。
+ * <p>
+ * 用于项目脚手架生成或帮助用户快速上手 .snow 语言。
+ * </p>
  */
 public final class SnowExampleTemplate {
 
+    /**
+     * 工具类构造方法，禁止实例化。
+     */
     private SnowExampleTemplate() {
         // 工具类不允许实例化
     }
 
     /**
-     * 返回 main.snow 示例模块内容。
+     * 获取 main.snow 示例模块的内容字符串。
      *
-     * @return 示例模块代码字符串
+     * @return main.snow 示例模块的完整代码
      */
     public static String getMainModule() {
         return """