feat(cli): 优化 log 子命令并引入 LogLevel 强类型解析,重构 commands.lua 注册表解析与校验逻辑

- 调整 LogLevel 的 FromStr 错误类型为 String，适配 clap 的 value_parser
- log 子命令直接绑定 LogLevel 枚举，消除硬编码校验与类型转换
- 规范化日志级别更新与配置读取逻辑
- handler 类型有 Function 改为 String

mirror-core/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "mirror-core"
+version = { workspace = true }
+edition = { workspace = true }
+
+[dependencies]
+anyhow = { workspace = true }
+mlua = { workspace = true }
+dunce = { workspace = true }
+tinyjson = { workspace = true }
+windows-sys = { workspace = true }
+serde = { workspace = true }
+# 日志
+tracing = { workspace = true }
+tracing-subscriber = { workspace = true }
+tracing-appender = { workspace = true }

mirror-core/src/error.rs

@@ -0,0 +1,25 @@
+// 构造一个带上下文的 FromLua 转换错误，便于定位配置问题
+/// 配置校验错误
+pub fn validation_error(message: impl Into<String>) -> mlua::Error {
+    mlua::Error::RuntimeError(message.into())
+}
+/// 将底层 Lua 语法错误转换为用户友好的提示
+pub fn syntax_error(err: mlua::Error) -> mlua::Error {
+    match &err {
+        mlua::Error::SyntaxError { message, .. } => {
+            if message.contains("invalid escape sequence") || message.contains("unfinished string")
+            {
+                return validation_error(format!(
+                    "配置文件语法错误：检测到非法的字符串转义。\n\
+                     提示：在 Windows 路径末尾或字符串中使用反斜杠 '\\' 时：\n\
+                     1. 请使用双反斜杠转义，例如: \"D:\\\\CNWei\\\\CNW\\\\Rust\\\\\"\n\
+                     2. 或使用 Lua 原始字符串 (Raw String)，例如: [[D:\\CNWei\\CNW\\Rust\\]]\n\
+                     底层错误: {}",
+                    message
+                ));
+            }
+        }
+        _ => {}
+    }
+    err
+}

mirror-core/src/layout.rs

@@ -0,0 +1,72 @@
+use anyhow::{Context, Result, bail};
+use std::env;
+use std::path::{Path, PathBuf};
+use tracing::debug;
+pub struct Layout {
+    pub base_dir: PathBuf,
+    pub bin_dir: PathBuf,
+    pub target_name: String,
+}
+
+impl Layout {
+    /// 自动解析目录布局：
+    /// 1. 优先使用环境变量 MIRROR_HOME
+    /// 2. 兜底回退到当前垫片可执行文件所在目录推断 (exe -> bin -> root)
+    pub fn from(current_exe: &Path) -> Result<Self> {
+        let target_name = current_exe
+            .file_stem()
+            .and_then(|s| s.to_str())
+            .with_context(|| format!("无法从路径 [{}] 提取有效的程序名称", current_exe.display()))?
+            .to_lowercase();
+
+        // 策略 1: 环境变量优先
+        if let Ok(home_val) = env::var("MIRROR_HOME") {
+            let trimmed = home_val.trim();
+            if !trimmed.is_empty() {
+
+                debug!(home = %trimmed, "检测到 MIRROR_HOME，采用环境变量配置");
+
+                return Self::from_base_dir(PathBuf::from(trimmed), target_name);
+            }
+        }
+
+        // 策略 2: 相对路径自动推断兜底
+        debug!("未配置 MIRROR_HOME，尝试从当前可执行文件路径推断根目录");
+        Self::from_executable(current_exe, target_name)
+    }
+
+    /// 基于确定的根目录构建完整布局
+    fn from_base_dir(base_dir: PathBuf, target_name: String) -> Result<Self> {
+        if !base_dir.is_dir() {
+            bail!("指定的根目录不存在或不是有效目录: [{}]", base_dir.display());
+        }
+
+        let bin_dir = base_dir.join("bin");
+
+        Ok(Self {
+            base_dir,
+            bin_dir,
+            target_name,
+        })
+    }
+
+    /// 从当前可执行文件解析 shim 安装目录布局
+    fn from_executable(exe_path: &Path, target_name: String) -> Result<Self> {
+        // let exe_path = exe_path.as_ref();
+        let bin_dir = exe_path
+            .parent()
+            .with_context(|| format!("无法获取程序 [{}] 的父级 bin 目录", exe_path.display()))?
+            .to_path_buf();
+
+        debug!("bin_dir目录 {}", bin_dir.display());
+
+        let base_dir = bin_dir
+            .parent()
+            .with_context(|| format!("无法获取 bin 目录 [{}] 的父级 root 目录", bin_dir.display()))?
+            .to_path_buf();
+
+        debug!("base_dir 目录 {}", base_dir.display());
+
+        Self::from_base_dir(base_dir, target_name)
+    }
+}

mirror-core/src/lib.rs

@@ -0,0 +1,14 @@
+pub mod error;
+mod layout;
+mod logger;
+mod mirror;
+mod runtime;
+mod utils;
+pub mod validators;
+
+pub use layout::Layout;
+pub use mirror::Mirror;
+pub use runtime::LuaRuntime;
+
+pub use logger::{init_logging_from, Logger,LogLevel};
+pub use utils::{lua_string_2_os_string, normalize_path_for_lua, parse_tokens};

mirror-core/src/logger.rs

@@ -0,0 +1,185 @@
+use crate::Layout;
+use serde::Deserialize;
+use std::fs;
+use std::path::PathBuf;
+use std::str::FromStr;
+use tracing_appender::non_blocking::{NonBlocking, WorkerGuard};
+use tracing_subscriber::layer::SubscriberExt;
+use tracing_subscriber::util::SubscriberInitExt;
+use tracing_subscriber::{EnvFilter, fmt};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, serde::Deserialize, Default)]
+#[serde(rename_all = "lowercase")]
+pub enum LogLevel {
+    Off,
+    Error,
+    #[default]
+    Warn,
+    Info,
+    Debug,
+    Trace,
+}
+
+impl std::fmt::Display for LogLevel {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", self.as_str())
+    }
+}
+
+impl LogLevel {
+    /// 是否需要激活写盘排查模式（Info 及以上更详细的级别）
+    pub fn is_verbose(&self) -> bool {
+        *self >= LogLevel::Info
+    }
+
+    pub fn as_str(&self) -> &'static str {
+        match self {
+            LogLevel::Off => "off",
+            LogLevel::Error => "error",
+            LogLevel::Warn => "warn",
+            LogLevel::Info => "info",
+            LogLevel::Debug => "debug",
+            LogLevel::Trace => "trace",
+        }
+    }
+}
+impl FromStr for LogLevel {
+    type Err = String;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        match s.to_ascii_lowercase().as_str() {
+            "off" => Ok(LogLevel::Off),
+            "error" => Ok(LogLevel::Error),
+            "warn" => Ok(LogLevel::Warn),
+            "info" => Ok(LogLevel::Info),
+            "debug" => Ok(LogLevel::Debug),
+            "trace" => Ok(LogLevel::Trace),
+            _ => Err(format!(
+                "无效的日志级别 '{s}'，可选值为: off, error, warn, info, debug, trace"
+            )),
+        }
+    }
+}
+
+#[derive(Debug, Deserialize, Default)]
+pub struct Logger {
+    #[serde(default)]
+    pub level: LogLevel,
+    pub log_dir: Option<PathBuf>,
+}
+impl Logger {
+    /// 零依赖解析 ini / key-value 文本内容
+    pub fn parse_ini(content: &str) -> Self {
+        let mut logger = Self::default();
+
+        for line in content.lines() {
+            let line = line.trim();
+            // 跳过空行、注释行 (# 或 ;) 和 section 头 ([...])
+            if line.is_empty()
+                || line.starts_with('#')
+                || line.starts_with(';')
+                || line.starts_with('[')
+            {
+                continue;
+            }
+
+            if let Some((key, val)) = line.split_once('=') {
+                let key = key.trim();
+                let val = val.trim().trim_matches('"').trim_matches('\'');
+
+                match key {
+                    "level" => {
+                        if let Ok(lvl) = LogLevel::from_str(val) {
+                            logger.level = lvl;
+                        }
+                    }
+                    "log_dir" => {
+                        if !val.is_empty() {
+                            logger.log_dir = Some(PathBuf::from(val));
+                        }
+                    }
+                    _ => {}
+                }
+            }
+        }
+
+        logger
+    }
+}
+/// 基于 Layout 自动寻址 mirror.toml 并初始化日志系统。
+/// 仅在开启详细日志（如 info/debug/trace）时激活异步文件记录并返回 `WorkerGuard`。
+pub fn init_logging_from(layout: &Layout) -> Option<WorkerGuard> {
+    // 1. 在 layout.base_dir 目录下寻找 log.toml
+    // let config_path = layout.base_dir.join("mirror.toml");
+    let config_path = layout.base_dir.join("../../mirror.ini");
+
+    // 读取配置文件（如不存在或解析失败，降级回退到默认设置）
+    let config = if config_path.exists() {
+        fs::read_to_string(&config_path)
+            .map(|s| Logger::parse_ini(&s))
+            // .ok()
+            // .and_then(|s| toml::from_str::<Logger>(&s).ok())
+            .unwrap_or_default()
+    } else {
+        Logger::default()
+    };
+
+    // 1. 优先读取环境变量 MIRROR_LOG_LEVEL，解析失败或未设置则退回到 config.level
+    let effective_level = std::env::var("MIRROR_LOG_LEVEL")
+        .ok()
+        .and_then(|val| LogLevel::from_str(&val).ok())
+        .unwrap_or(config.level);
+    if effective_level == LogLevel::Off {
+        return None;
+    }
+    let filter = EnvFilter::new(effective_level.as_str());
+    // 基础终端输出层
+    let stderr_layer = fmt::layer().with_writer(std::io::stderr).with_target(false);
+
+    // 2. 根据强类型枚举判断是否激活落盘模式
+    if effective_level.is_verbose() {
+        let (non_blocking, guard) = create_file_appender(layout, config.log_dir);
+        let file_layer = fmt::layer()
+            .with_writer(non_blocking)
+            .with_ansi(false)
+            .with_target(false);
+
+        let _ = tracing_subscriber::registry()
+            .with(filter)
+            .with(stderr_layer)
+            .with(file_layer)
+            .try_init();
+
+        Some(guard)
+    } else {
+        let _ = tracing_subscriber::registry()
+            .with(filter)
+            .with(stderr_layer)
+            .try_init();
+
+        None
+    }
+}
+
+fn create_file_appender(
+    layout: &Layout,
+    log_dir_override: Option<PathBuf>,
+) -> (NonBlocking, WorkerGuard) {
+    let output_dir = match log_dir_override {
+        Some(user_path) => {
+            if user_path.is_relative() {
+                layout.base_dir.join(user_path)
+            } else {
+                user_path
+            }
+        }
+        None => layout.base_dir.join("logs"),
+    };
+
+    if let Err(err) = fs::create_dir_all(&output_dir) {
+        eprintln!("[WARN] 创建日志目录 {} 失败: {}", output_dir.display(), err);
+    }
+
+    let file_appender = tracing_appender::rolling::daily(output_dir, "mirror.log");
+    tracing_appender::non_blocking(file_appender)
+}

mirror-core/src/mirror.rs

@@ -0,0 +1,156 @@
+use crate::error::validation_error;
+use crate::validators::LuaValidator;
+use crate::{Layout, LuaRuntime};
+use anyhow::{Context, Result, bail};
+use mlua::{FromLua, Lua, Table, Value};
+use std::collections::HashMap;
+use std::env;
+use std::ffi::OsString;
+use std::path::PathBuf;
+use std::process::Command;
+use tracing::{debug, trace};
+#[derive(Debug, Clone, Default)]
+pub struct Mirror {
+    pub target: PathBuf,
+    pub args: Vec<OsString>,
+    pub aliases: HashMap<String, Vec<OsString>>,
+    pub env: HashMap<String, OsString>,
+}
+
+impl Mirror {
+    pub fn load(layout: &Layout) -> Result<Self> {
+        // 策略 1: 尝试加载全局配置文件 mirror.lua
+        let global_config = layout.base_dir.join("../../mirror.lua");
+
+        if !global_config.is_file() {
+            bail!("主配置文件不存在: {}", global_config.display());
+        }
+
+        let runtime = LuaRuntime::new(layout)?;
+
+        let root_table: Table = runtime.eval_script(&global_config)?;
+
+        let target_name = layout.target_name.as_str();
+
+        // 检查 mirror.lua 中是否存在以 target_name 命名的 Table 节点
+        let target_val: Mirror = root_table
+            .get::<Option<Mirror>>(target_name)
+            .with_context(|| format!("读取目标配置 [{}] 失败", target_name))?
+            .ok_or_else(|| {
+                anyhow::anyhow!(
+                    "在 'mirror.lua' 中未找到目标程序 [{}] 的配置注册",
+                    target_name
+                )
+            })?;
+        debug!(
+            target = %target_name,
+            source = %global_config.display(),
+            "成功从全局配置文件中匹配到目标工具"
+        );
+
+        Ok(target_val)
+    }
+
+    /// 1. 核心参数路由解析（Delegation 到 Spec 的路由逻辑）
+    fn resolve_args<I, S>(&self, args: I) -> Vec<OsString>
+    where
+        I: IntoIterator<Item = S>,
+        S: AsRef<std::ffi::OsStr>,
+    {
+        let arg_iter = args.into_iter();
+
+        // 1. 预分配容量：利用迭代器的下限提示，避免多次 Realloc
+        let (lower_bound, _) = arg_iter.size_hint();
+        let mut expanded_args: Vec<OsString> = Vec::with_capacity(lower_bound);
+
+        for i in arg_iter {
+            let os_str = i.as_ref();
+
+            let arg_str = os_str.to_string_lossy();
+
+            // 检查参数是否带有 mr: 前缀
+            if let Some(alias_key) = arg_str.strip_prefix("mr:") {
+                // 如果在加载期打平好的字典中找到了对应的别名，直接展开追加
+                if let Some(alias_values) = self.aliases.get(alias_key) {
+                    expanded_args.extend(alias_values.iter().cloned());
+                } else {
+                    // 如果找不到对应的别名，按原样参数追加
+                    expanded_args.push(os_str.to_os_string());
+                }
+            } else {
+                // 普通参数，直接追加
+                expanded_args.push(os_str.to_os_string());
+            }
+        }
+        expanded_args
+    }
+
+    pub fn to_command<I, S>(&self, combined_args: I) -> Command
+    where
+        I: IntoIterator<Item = S>,
+        S: AsRef<std::ffi::OsStr>,
+    {
+        let mut cmd = Command::new(&self.target);
+
+        // 2. 传入预打平的别名字典，查表并展开所有以 `mr:` 为前缀的别名
+        let final_args = self.resolve_args(combined_args);
+        debug!("拼接后的命令行参数{:?}", final_args);
+        // 3. 将解析展开后的无环参数一次性注入 Command
+        cmd.args(&final_args);
+
+        // 4. 注入配置好的环境变量
+        for (key, val) in &self.env {
+            // 直接应用环境变量（Lua 端已经处理好字符串拼接或列表合并）
+            cmd.env(key, val);
+        }
+
+        cmd
+    }
+}
+impl FromLua for Mirror {
+    fn from_lua(value: Value, _lua: &Lua) -> mlua::Result<Self> {
+        // 脚本返回必须是一个 Table 变体
+        let table = match value {
+            Value::Table(t) => t,
+            _ => {
+                return Err(validation_error(format!(
+                    "期望得到一个 Lua Table 配置对象，实际是 {}",
+                    value.type_name()
+                )));
+            }
+        };
+
+        // 必填字段: target（严格限定为字符串，避免数字被 mlua 宽松转为字符串后掩盖错误）
+        let target = match table.get::<Option<Value>>("target")? {
+            None | Some(Value::Nil) => {
+                return Err(validation_error("缺少必填字段 target（应为字符串路径）"));
+            }
+            Some(target_val) => LuaValidator::parse_target(&target_val)?,
+        };
+
+        // 可选字段: args（缺失或 nil 时默认空列表；保留空字符串参数，与提权路径的 "" 语义一致）
+        let args = match table.get::<Option<Value>>("args")? {
+            None | Some(Value::Nil) => Vec::new(),
+            Some(args_val) => LuaValidator::parse_args(&args_val)?,
+        };
+
+        // 可选字段: env（只允许缺失/nil，其他类型由 Option<Table> 转换报错，不再静默忽略）
+        let env = match table.get::<Option<Value>>("env")? {
+            None | Some(Value::Nil) => HashMap::new(),
+            Some(env_val) => LuaValidator::parse_env(&env_val)?,
+        };
+
+        // 可选字段: aliases（只允许缺失/nil，其他类型由 Option<Table> 转换报错，不再静默忽略）
+        let aliases = match table.get::<Option<Value>>("aliases")? {
+            None | Some(Value::Nil) => HashMap::new(),
+            Some(env_val) => LuaValidator::parse_aliases(&env_val)?,
+        };
+        // println!("环境变量结果：{:?}", env);
+        Ok(Self {
+            target,
+            args,
+            aliases,
+            env,
+        })
+    }
+}

mirror-core/src/runtime.rs

@@ -0,0 +1,333 @@
+use crate::Layout;
+use crate::error::syntax_error;
+use crate::utils::normalize_path_for_lua;
+use anyhow::{Context, Result};
+use mlua::{FromLua, Lua, StdLib, Table, Value};
+use std::path::Path;
+use std::{env, fs};
+use tracing::{debug, trace, warn};
+
+const MIRROR_DIR: &str = "__MIRROR_DIR__";
+
+pub struct LuaRuntime {
+    lua: Lua,
+}
+
+impl LuaRuntime {
+    /// 初始化限定权限的 Lua 沙箱环境
+    pub fn new(layout: &Layout) -> Result<Self> {
+        // 只加载安全的标准库，剥离 os / io 等风险模块
+        let lua = Lua::new_with(
+            StdLib::TABLE | StdLib::STRING | StdLib::MATH | StdLib::PACKAGE,
+            mlua::LuaOptions::default(),
+        )
+        .context("初始化 Lua 失败")?;
+
+        // 统一使用 POSIX 风格路径规范化路径字符串
+        let base_dir = normalize_path_for_lua(&layout.base_dir);
+        // let tools_dir = normalize_path_for_lua(&layout.tools_dir);
+
+        // 1. 注入锚点变量 __MIRROR_DIR__（shim 安装根目录）
+        Self::register_mirror_dir(&lua, &base_dir)?;
+
+        // 2. 安全暴露 get_env 供配置读取环境变量
+        // 返回按平台路径分隔符拆分后的段数组（自动剥离引号包裹），
+        // 便于 PATH 等列表变量直接嵌入数组：PATH = { prefix, get_env("PATH") }
+        Self::register_get_env(&lua)?;
+        // 3. 初始化并配置安全/容错的 require 机制
+        Self::setup_require(&lua, &base_dir)?;
+
+        Ok(Self { lua })
+    }
+
+    /// 执行指定脚本文件，直接返回完整的 Lua Table
+    pub fn eval_script<T: FromLua>(&self, path: impl AsRef<Path>) -> Result<T> {
+        let path = path.as_ref();
+
+        let bytes =
+            fs::read(path).with_context(|| format!("无法读取配置文件: {}", path.display()))?;
+
+        let code = String::from_utf8(bytes).with_context(|| {
+            format!(
+                "{} 不是有效的 UTF-8 文件（请将 Lua 配置文件保存为 UTF-8 编码）",
+                path.display()
+            )
+        })?;
+        debug!("code {:?}", code);
+        // 使用 @<path> 格式标记 Chunk 名称，确保 Lua 报错时能精确回溯到对应的源文件名与行号。
+        let chunk_name = format!("@{}", path.display());
+
+        self.lua
+            .load(&code)
+            .set_name(&chunk_name)
+            .eval::<T>()
+            .map_err(syntax_error)
+            .with_context(|| format!("执行 {} 配置文件失败: {}", chunk_name,path.display()))
+    }
+
+    /// 传入注册表的 handler key 与命令行原始参数，内部完成调用
+    pub fn call_handler(
+        &self,
+        handler_key: &mlua::RegistryKey,
+        args: Vec<String>,
+    ) -> Result<()> {
+        let handler: mlua::Function = self.lua.registry_value(handler_key)?;
+        let lua_args = self.lua.create_sequence_from(args)?;
+
+        if let Err(err) = handler.call::<()>(lua_args) {
+            let msg = err.to_string();
+            // 内部消化类似 argparse 的帮助退出信号
+            if msg.contains("__ARGPARSE_HELP__") {
+                return Ok(());
+            }
+            anyhow::bail!("{msg}");
+        }
+
+        Ok(())
+    }
+
+    pub fn require_and_run(&self, module_name: &str, raw_args: Vec<String>) -> Result<()> {
+        let require: mlua::Function = self.lua.globals().get("require")?;
+        let handler_val: mlua::Value = require.call(module_name)?;
+
+        let func = match handler_val {
+            mlua::Value::Function(f) => f,
+            other => anyhow::bail!("模块 '{module_name}' 必须返回一个函数，实际为 {}", other.type_name()),
+        };
+
+        let lua_args = self.lua.create_sequence_from(raw_args)?;
+        func.call::<()>(lua_args)?;
+        Ok(())
+    }
+
+}
+impl LuaRuntime {
+    /// 注入全局锚点变量
+    fn register_mirror_dir(lua: &Lua, base_dir: &str) -> Result<()> {
+        lua.globals()
+            .set(MIRROR_DIR, base_dir)
+            .context(format!("设置 {MIRROR_DIR} 环境变量失败"))?;
+        Ok(())
+    }
+
+    ///注入 get_env 供配置读取环境变量
+    fn register_get_env(lua: &Lua) -> Result<()> {
+        let globals = lua.globals();
+        let get_env = lua
+            .create_function(|lua, key: String| -> mlua::Result<Table> {
+                // 缺失变量视为空字符串，拆分后得到空表（不贡献任何路径段）
+                let value = env::var_os(key).unwrap_or_default();
+                // 空输入返回空表；否则按平台分隔符拆分（split_paths 会剥离引号包裹）
+                if value.is_empty() {
+                    return lua.create_table();
+                }
+                let table = lua.create_table()?;
+                for (i, p) in env::split_paths(&value).enumerate() {
+                    // 3. 跨平台提取原始字节并转为 LuaString，保证 100% 无损
+                    #[cfg(unix)]
+                    let lua_str = {
+                        use std::os::unix::ffi::OsStrExt;
+                        lua.create_string(p.as_os_str().as_bytes())?
+                    };
+
+                    #[cfg(windows)]
+                    let lua_str = {
+                        // Windows 路径是 UTF-16，转成字符串或保持其字节表达
+                        let s = p.to_string_lossy();
+                        lua.create_string(s.as_bytes())?
+                    };
+
+                    table.set(i + 1, lua_str)?;
+                }
+
+                Ok(table)
+            })
+            .context("注册 get_env 函数失败")?;
+
+        globals
+            .set("get_env", get_env)
+            .context("挂载 get_env 全局函数失败")?;
+        Ok(())
+    }
+
+    /// 配置 package.path 并包装 require，拦截加载失败以提高容错性
+    fn setup_require(lua: &Lua, base_dir: &str) -> Result<()> {
+        let globals = lua.globals();
+
+        // 1. 安全加固并拓展 package 搜索路径
+        let package = globals.get::<Table>("package")?;
+
+        let _ = package.set("cpath", "");
+        let _ = package.set("loadlib", Value::Nil);
+
+        let commands_dir = format!("{}/commands", base_dir);
+        let vendor_dir = format!("{}/vendor", base_dir);
+
+        let path = package.get::<String>("path")?;
+        let new_path = format!(
+            "{};{}/?.lua;{}/?/init.lua;{}/?.lua;{}/?/init.lua;{}/?.lua;{}/?/init.lua;",
+            path, base_dir, base_dir, commands_dir, commands_dir, vendor_dir, vendor_dir
+        );
+
+        debug!("重新写入的 package 查找路径");
+        package.set("path", new_path)?;
+
+        // 2. 获取原生 require 并通过闭包直接持有（无需向全局表注入备份变量）
+        let original_require: mlua::Function = globals
+            .get("require")
+            .context("获取内置 require 函数失败")?;
+
+        let wrapped_require = lua
+            .create_function(move |_lua, module: String| -> mlua::Result<Value> {
+                match original_require.call::<Value>(module.as_str()) {
+                    Ok(value) => Ok(value),
+                    Err(e) => {
+                        warn!(
+                            module = %module,
+                            error = %e,
+                            "配置模块加载失败，已跳过该条目（可在独立配置文件中定义）"
+                        );
+                        Ok(Value::Nil)
+                    }
+                }
+            })
+            .context("创建包装版 require 函数失败")?;
+
+        // 3. 覆盖全局 require
+        globals
+            .set("require", wrapped_require)
+            .context("重载 require 函数失败")?;
+
+        Ok(())
+    }
+}
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::{Layout, Mirror};
+
+    fn test_layout() -> Layout {
+        let root = std::env::temp_dir().join("rshim-test-layout");
+        Layout {
+            base_dir: root.clone(),
+            bin_dir: root.join("bin"),
+            target_name: "muna".to_string(),
+        }
+    }
+
+    #[test]
+    fn missing_module_require_returns_nil() {
+        let runtime = LuaRuntime::new(&test_layout()).unwrap();
+        let value: Value = runtime
+            .lua
+            .load(r#"return require("rshim_test_no_such_module")"#)
+            .eval()
+            .unwrap();
+        assert!(matches!(value, Value::Nil));
+    }
+
+    #[test]
+    fn builtin_module_require_still_works() {
+        let runtime = LuaRuntime::new(&test_layout()).unwrap();
+        let value: Value = runtime
+            .lua
+            .load(r#"return pcall(require, "string")"#)
+            .eval()
+            .unwrap();
+        assert!(matches!(value, Value::Boolean(true)));
+    }
+
+    #[test]
+    fn get_env_returns_split_table() {
+        let runtime = LuaRuntime::new(&test_layout()).unwrap();
+        let value: Value = runtime
+            .lua
+            .load(r#"return get_env("PATH")"#)
+            .eval()
+            .unwrap();
+        let table = match value {
+            Value::Table(t) => t,
+            other => panic!("expected table, got {}", other.type_name()),
+        };
+        assert!(
+            table.raw_len() >= 1,
+            "PATH should have at least one segment"
+        );
+
+        // split_paths 会剥离引号包裹，拆分段不应再含双引号
+        for i in 1..=table.raw_len() {
+            let seg: String = table.raw_get(i).unwrap();
+            assert!(
+                !seg.contains('"'),
+                "segment should not contain quote: {seg:?}"
+            );
+        }
+    }
+
+    #[test]
+    fn get_env_missing_returns_empty_table() {
+        let runtime = LuaRuntime::new(&test_layout()).unwrap();
+        let value: Value = runtime
+            .lua
+            .load(r#"return get_env("RSHIM_TEST_NO_SUCH_VAR_12345")"#)
+            .eval()
+            .unwrap();
+        match value {
+            Value::Table(t) => assert_eq!(t.raw_len(), 0),
+            other => panic!("expected table, got {}", other.type_name()),
+        }
+    }
+
+    #[test]
+    fn path_with_get_env_joins_without_quote_error() {
+        // 复现用户场景：PATH = { base_dir .. "/tools/numa", get_env("PATH") }
+        // 宿主 PATH 即使含双引号，也应拆分后正常拼接，而不是报错
+        let runtime = LuaRuntime::new(&test_layout()).unwrap();
+        let cfg: Mirror = runtime
+            .lua
+            .load(
+                r#"
+                return {
+                    target = __SHIM_DIR__ .. "/tools/numa/numa.exe",
+                    args = { "--help" },
+                    env = {
+                        PATH = { __SHIM_DIR__ .. "/tools/numa", get_env("PATH") }
+                    }
+                }
+                "#,
+            )
+            .eval()
+            .unwrap();
+
+        let path = cfg.env.get("PATH").unwrap().to_str().unwrap();
+        let prefix = std::env::temp_dir()
+            .join("rshim-test-layout")
+            .to_string_lossy()
+            .replace('\\', "/")
+            + "/tools/numa;";
+        assert!(path.starts_with(&prefix), "unexpected PATH: {path}");
+
+        // 宿主 PATH 的段应被附加在配置前缀之后
+        let host = std::env::var("PATH").unwrap_or_default();
+        if !host.is_empty() {
+            let host_first = std::env::split_paths(&host)
+                .next()
+                .unwrap()
+                .to_string_lossy()
+                .into_owned();
+            assert!(
+                path.contains(&host_first),
+                "missing host PATH segment: {host_first}"
+            );
+        }
+
+        // 宿主 PATH 里引号包裹的畸形段（如 "D:\\...\\bin;"）应被原样保留，
+        // 而不是让整个配置加载失败
+        if host.contains('"') {
+            assert!(
+                path.contains('"'),
+                "quoted host segments should be preserved"
+            );
+        }
+    }
+}

mirror-core/src/utils.rs

@@ -0,0 +1,233 @@
+use mlua::LuaString;
+use std::ffi::OsString;
+use std::path::Path;
+
+/// 将 Path 转换为适合 Lua 使用的安全字符串路径
+pub fn normalize_path_for_lua(path: &Path) -> String {
+    // 自动将 Windows UNC 规范路径转回传统路径
+    let simplified = dunce::simplified(path);
+    simplified.to_string_lossy().replace('\\', "/")
+}
+
+/// 将 Lua 字符串转为 Rust 字符串；非 UTF-8 按系统默认的 ANSI/OEM (如 GBK) 进行安全解码
+pub fn lua_string_2_os_string(s: &LuaString) -> mlua::Result<OsString> {
+    let raw_bytes = &s.as_bytes();
+    // 1. Unix 平台：直接零拷贝透传原始字节（无损支持任意编码）
+    #[cfg(unix)]
+    {
+        use std::os::unix::ffi::OsStrExt;
+        Ok(OsStr::from_bytes(raw_bytes).to_os_string())
+    }
+    // 2. Windows 平台：优先按 UTF-8 解码，失败则按当前系统本地代码页 (ANSI/GBK) 转换
+    #[cfg(windows)]
+    {
+        // 先尝试标准的 UTF-8
+        if let Ok(utf8_str) = std::str::from_utf8(raw_bytes) {
+            return Ok(OsString::from(utf8_str));
+        }
+
+        unsafe {
+            use std::os::windows::ffi::OsStringExt;
+            use windows_sys::Win32::Globalization::{
+                CP_ACP, MB_ERR_INVALID_CHARS, MultiByteToWideChar,
+            };
+
+            if raw_bytes.is_empty() {
+                return Ok(OsString::new());
+            }
+
+            let len = MultiByteToWideChar(
+                CP_ACP,
+                MB_ERR_INVALID_CHARS,
+                raw_bytes.as_ptr(),
+                raw_bytes.len() as i32,
+                std::ptr::null_mut(),
+                0,
+            );
+
+            if len <= 0 {
+                // 构造一个带上下文的 FromLua 转换错误，便于定位配置问题
+                return Err(mlua::Error::FromLuaConversionError {
+                    from: "LuaString",
+                    to: "OsString".to_string(),
+                    message: Some(
+                        format!("字符串{:?}包含无效或当前系统无法识别的编码字节", s).to_string(),
+                    ),
+                });
+            }
+
+            let mut buf = vec![0u16; len as usize];
+            MultiByteToWideChar(
+                CP_ACP,
+                MB_ERR_INVALID_CHARS,
+                raw_bytes.as_ptr(),
+                raw_bytes.len() as i32,
+                buf.as_mut_ptr(),
+                len,
+            );
+
+            Ok(OsString::from_wide(&buf))
+        }
+    }
+}
+
+/// 将输入的字符串按 Shell 规则切分为独立的 CLI 参数 Token
+/// - 自动过滤连续空格
+/// - 支持单引号 `'...'` 和双引号 `"..."` 包裹包含空格的参数
+pub fn parse_tokens(input: &str) -> Vec<OsString> {
+    let mut tokens = Vec::new();
+    let mut current_token = String::new();
+    let mut in_quote: Option<char> = None;
+    let mut chars = input.chars().peekable();
+
+    while let Some(ch) = chars.next() {
+        match (ch, in_quote) {
+            // 处理转义字符 (例如 \")
+            ('\\', _quote) => {
+                if let Some(&next_ch) = chars.peek() {
+                    let should_escape = if cfg!(windows) {
+                        // Windows 策略：只有在转义引号、反斜杠本身时才剥离 \
+                        // （如果在双引号内部，空格也不应该被 \ 转义）
+                        next_ch == '"' || next_ch == '\'' || next_ch == '\\'
+                    } else {
+                        // Unix 策略：标准 Shell 转义（引号、反斜杠、空格等）
+                        next_ch == '"'
+                            || next_ch == '\''
+                            || next_ch == '\\'
+                            || next_ch.is_whitespace()
+                    };
+
+                    if should_escape {
+                        chars.next(); // 消耗掉下一个字符
+                        current_token.push(next_ch);
+                    } else {
+                        // 保留 Windows 路径分隔符或未知转义中的 \
+                        current_token.push('\\');
+                    }
+                } else {
+                    // 结尾孤立的 \
+                    current_token.push('\\');
+                }
+            }
+            // 遇到引号：开启或关闭引号包裹
+            ('"' | '\'', None) => {
+                in_quote = Some(ch);
+            }
+            ('"' | '\'', Some(q)) if q == ch => {
+                in_quote = None;
+            }
+            // 引号外部遇到空白字符：切分出一个完整的 Token
+            (ch, None) if ch.is_whitespace() => {
+                if !current_token.is_empty() {
+                    tokens.push(OsString::from(std::mem::take(&mut current_token)));
+                }
+            }
+            // 其他字符或引号内部字符：直接追加
+            (ch, _) => {
+                current_token.push(ch);
+            }
+        }
+    }
+
+    // 收尾最后一个 Token
+    if !current_token.is_empty() {
+        tokens.push(OsString::from(current_token));
+    }
+
+    tokens
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::ffi::OsString;
+    /// 辅助宏：简化声明与断言对比
+    macro_rules! assert_tokens {
+        ($input:expr, $expected:expr) => {
+            let actual = parse_tokens($input);
+            let expected_os: Vec<OsString> = $expected.into_iter().map(OsString::from).collect();
+            assert_eq!(
+                actual, expected_os,
+                "\n测试输入: {:?}\n期望输出: {:?}\n实际输出: {:?}",
+                $input, expected_os, actual
+            );
+        };
+    }
+    #[test]
+    fn test_parse_tokens_basic_split() {
+        // 场景 1：基础多参数拆分（空格分隔）
+        assert_tokens!("cargo run --verbose", vec!["cargo", "run", "--verbose"]);
+        assert_tokens!("git status", vec!["git", "status"]);
+    }
+
+    #[test]
+    fn test_parse_tokens_multi_alias_ref() {
+        // 场景 2：多别名混合与组合引用
+        assert_tokens!(
+            "mr:run --bin mr:base_flags",
+            vec!["mr:run", "--bin", "mr:base_flags"]
+        );
+        assert_tokens!(
+            "mr:app1 mr:app2 --flag",
+            vec!["mr:app1", "mr:app2", "--flag"]
+        );
+    }
+
+    #[test]
+    fn test_parse_tokens_continuous_whitespaces() {
+        // 场景 3：连续多空格与制表符过滤
+        assert_tokens!(
+            "mr:run    --bin \t  my_app",
+            vec!["mr:run", "--bin", "my_app"]
+        );
+        assert_tokens!("   cargo   build   ", vec!["cargo", "build"]);
+    }
+
+    #[test]
+    fn test_parse_tokens_double_quotes() {
+        // 场景 4：双引号包裹包含空格的参数
+        assert_tokens!(
+            "git commit -m \"fix a bug\"",
+            vec!["git", "commit", "-m", "fix a bug"]
+        );
+        assert_tokens!("echo \"hello world\"", vec!["echo", "hello world"]);
+    }
+
+    #[test]
+    fn test_parse_tokens_single_quotes() {
+        // 场景 5：单引号包裹包含空格的参数
+        assert_tokens!(
+            "gcc -O2 'my file.c' -o app",
+            vec!["gcc", "-O2", "my file.c", "-o", "app"]
+        );
+        assert_tokens!(
+            "python 'script with space.py'",
+            vec!["python", "script with space.py"]
+        );
+    }
+
+    #[test]
+    fn test_parse_tokens_escaped_characters() {
+        // 场景 6：反斜杠转义字符
+        assert_tokens!("echo hello\\ world", vec!["echo", "hello\\", "world"]);
+        assert_tokens!(
+            "echo \"hello \\\"world\\\"\"",
+            vec!["echo", "hello \"world\""]
+        );
+    }
+
+    #[test]
+    fn test_parse_tokens_single_scalar_and_edge_cases() {
+        // 场景 7：单标量参数与边界情况
+        assert_tokens!("git", vec!["git"]);
+        assert_tokens!("8000", vec!["8000"]);
+        assert_tokens!("", Vec::<&str>::new());
+        assert_tokens!("    ", Vec::<&str>::new());
+    }
+
+    #[test]
+    fn test_parse_tokens_unclosed_quotes() {
+        // 场景 8：未闭合引号的容错处理（会尽量追加到当前 Token 中）
+        assert_tokens!("echo \"hello world", vec!["echo", "hello world"]);
+    }
+}

mirror-core/src/validators.rs

@@ -0,0 +1,706 @@
+use crate::error::validation_error;
+use crate::{lua_string_2_os_string, parse_tokens};
+use anyhow::{Context, Result, anyhow};
+use mlua::{LuaString, Table, Value};
+use std::collections::{HashMap, HashSet};
+use std::ffi::OsString;
+use std::fmt;
+use std::path::PathBuf;
+use std::str::FromStr;
+use tinyjson::JsonValue;
+use tracing::debug;
+
+/// Lua 值校验器：针对不同上下文定义校验规则
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum LuaValidator {
+    /// 目标程序路径：必须是字符串路径
+    Target,
+    /// 命令行参数元素：仅支持一维基础标量，禁止嵌套 Table
+    Args,
+    /// 环境变量值：支持基础标量及多维嵌套 Table（递归展平）
+    Env,
+    Aliases,
+}
+
+impl fmt::Display for LuaValidator {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Target => write!(f, "目标路径 (target)"),
+            Self::Args => write!(f, "命令行参数 (args)"),
+            Self::Env => write!(f, "环境变量 (env)"),
+            Self::Aliases => write!(f, "命令行别名 (aliases)"),
+        }
+    }
+}
+impl LuaValidator {
+    fn parse_sequence(&self, index: i64, item: &Value) -> mlua::Result<()> {
+        match item {
+            Value::String(_) | Value::Integer(_) | Value::Number(_) | Value::Boolean(_) => Ok(()),
+            Value::Table(tbl) => match self {
+                Self::Env | Self::Aliases => self.validate_sequence_table(tbl),
+                Self::Args => Err(validation_error(format!(
+                    "{} 仅支持一维数组，不能包含嵌套 Table,索引位置: {index}",
+                    self
+                ))),
+                Self::Target => Err(validation_error(format!("{} 仅支持字符串", self))),
+            },
+            other => Err(validation_error(format!(
+                "{} 第 {} 个元素类型无效: {}",
+                self,
+                index,
+                other.type_name()
+            ))),
+        }
+    }
+
+    /// 校验 Table 是否为严格连续的纯数组，并递归校验其内部元素
+    fn validate_sequence_table(&self, tbl: &Table) -> mlua::Result<()> {
+        let mut index = 1i64;
+
+        // 1. 顺序遍历连续整数索引 1..N
+        loop {
+            let item: Value = tbl.raw_get(index)?;
+            if matches!(&item, Value::Nil) {
+                break;
+            }
+            self.parse_sequence(index, &item)?;
+
+            index += 1;
+        }
+
+        // 2. 查漏：校验是否存在空洞索引或字典键 (Key-Value 键值对)
+        for pair in tbl.pairs::<Value, Value>() {
+            let (key, _) = pair?;
+            match key {
+                Value::Integer(i) if i >= 1 && i < index => {} // 已遍历放行
+                Value::Integer(_) => {
+                    return Err(validation_error(format!(
+                        "{} 第 {} 个元素为 nil 或不存在（请检查漏写引号或变量未定义）",
+                        self, index
+                    )));
+                }
+                _ => {
+                    return Err(validation_error(format!(
+                        "{} 必须是纯列表，不能包含键值对/字典结构",
+                        self
+                    )));
+                }
+            }
+        }
+
+        Ok(())
+    }
+
+    /// 底层 NUL 字符跨平台安全检查
+    fn ensure_no_nul(context: &impl fmt::Display, os_str: &std::ffi::OsStr) -> mlua::Result<()> {
+        #[cfg(unix)]
+        {
+            use std::os::unix::ffi::OsStrExt;
+            if os_str.as_bytes().contains(&0) {
+                return Err(conversion_error(format!(
+                    "{} 的值不能包含 NUL 字符",
+                    context
+                )));
+            }
+        }
+        #[cfg(windows)]
+        {
+            use std::os::windows::ffi::OsStrExt;
+            if os_str.encode_wide().any(|c| c == 0) {
+                return Err(validation_error(format!(
+                    "{} 的值不能包含 NUL 字符",
+                    context
+                )));
+            }
+        }
+        Ok(())
+    }
+
+    /// 【纯粹数据转换与展开】将已通过校验的 Value 递归解析为 OsString 动态数组
+    fn collect_value_into(&self, value: &Value, out: &mut Vec<OsString>) -> mlua::Result<()> {
+        match value {
+            Value::Nil => {}
+            Value::String(s) => {
+                let os_str = lua_string_2_os_string(s)?;
+                match self {
+                    Self::Args | Self::Aliases => {
+                        if let Some(str_ref) = os_str.to_str() {
+                            // 使用 Tokenizer 切分空格与引号
+                            out.extend(parse_tokens(str_ref));
+                        } else {
+                            // 对于无法转为 UTF-8 的特殊二进制数据，作为整体追加
+                            out.push(os_str);
+                        }
+                    }
+                    Self::Env => {
+                        out.push(os_str);
+                    }
+                    Self::Target => {}
+                }
+            }
+            Value::Integer(i) => out.push(OsString::from(i.to_string())),
+            Value::Number(n) => {
+                tracing::warn!(%self, value = %n, "浮点数将按十进制格式转换为字符串");
+                out.push(OsString::from(n.to_string()));
+            }
+            Value::Boolean(b) => {
+                tracing::warn!(%self, value = %b, "布尔值将转换为字符串");
+                out.push(OsString::from(b.to_string()));
+            }
+            Value::Table(tbl) => {
+                let mut index = 1i64;
+                loop {
+                    let item: Value = tbl.raw_get(index)?;
+                    if matches!(item, Value::Nil) {
+                        break;
+                    }
+
+                    Self::collect_value_into(self, &item, out)?;
+                    index += 1;
+                }
+            }
+            _ => unreachable!("传入收集器的 Value 应已通过 validate 校验"),
+        }
+        Ok(())
+    }
+    fn parse_name(name: &Value) -> mlua::Result<String> {
+        let name_str = match name {
+            Value::String(s) => match s.to_str() {
+                Ok(str_ref) => str_ref.to_string(),
+                Err(_) => return Err(validation_error("环境变量名必须是合法的 UTF-8 字符串")),
+            },
+            other => {
+                return Err(validation_error(format!(
+                    "环境变量键名类型错误：期望 string，实际是 {}",
+                    other.type_name()
+                )));
+            }
+        };
+        if name_str.is_empty() {
+            return Err(validation_error("环境变量名不能为空"));
+        }
+        if name_str.contains('=') {
+            return Err(validation_error(format!(
+                "环境变量名 [{}] 不能包含 '='",
+                name_str
+            )));
+        }
+        if name_str.contains('\0') {
+            return Err(validation_error(format!(
+                "环境变量名 [{}] 不能包含 NUL 字符",
+                name_str
+            )));
+        }
+        Ok(name_str)
+    }
+    fn parse_val(&self, name: &str, value: &Value) -> mlua::Result<()> {
+        match value {
+            Value::Nil
+            | Value::String(_)
+            | Value::Integer(_)
+            | Value::Number(_)
+            | Value::Boolean(_) => Ok(()),
+            Value::Table(tbl) => self.validate_sequence_table(tbl),
+            other => Err(validation_error(format!(
+                "{} [{}]不支持 {} 类型, 仅支持 string/number/boolean 或嵌套数组",
+                self,
+                name,
+                other.type_name()
+            ))),
+        }
+    }
+}
+impl LuaValidator {
+    /// 解析并校验 `target`
+    pub fn parse_target(value: &Value) -> mlua::Result<PathBuf> {
+        let ctx = Self::Target;
+        match value {
+            Value::String(s) => {
+                let os_str = lua_string_2_os_string(&s)?;
+                Self::ensure_no_nul(&ctx, &os_str)?;
+                Ok(PathBuf::from(os_str))
+            }
+            Value::Nil => Err(validation_error("缺少必填字段 target（应为字符串路径）")),
+            other => Err(validation_error(format!(
+                "{} 需为有效的路径且类型必须是字符串，实际类型是 {}",
+                ctx,
+                other.type_name()
+            ))),
+        }
+    }
+
+    /// 解析并校验 `args`
+    pub fn parse_args(value: &Value) -> mlua::Result<Vec<OsString>> {
+        {
+            debug!("args 配置已关闭 ");
+            #[cfg(not(feature = "args"))]
+            Ok(Vec::new())
+        }
+        #[cfg(feature = "args")]
+        {
+            debug!("args 配置已开启");
+            let ctx = Self::Args;
+            match value {
+                Value::Table(tbl) => {
+                    ctx.validate_sequence_table(tbl)?;
+
+                    let capacity = tbl.raw_len().min(128);
+
+                    let mut raw_parts = Vec::with_capacity(capacity);
+
+                    Self::collect_value_into(&ctx, value, &mut raw_parts)?;
+
+                    for part in &raw_parts {
+                        Self::ensure_no_nul(&ctx, &part)?;
+                    }
+                    Ok(raw_parts)
+                }
+                other => Err(validation_error(format!(
+                    "{} 必须是数组列表，实际类型是 {}",
+                    ctx,
+                    other.type_name()
+                )))?,
+            }
+        }
+    }
+
+    /// 校验环境变量名的合法性（Windows 约束：非空、不含 '='、不含 NUL）
+    fn parse_env_name(name: &Value) -> mlua::Result<String> {
+        Self::parse_name(name)
+    }
+
+    /// 解析、校验并拼接单个环境变量键值对 (`key`, `value`) -> (`OsString`)
+    fn parse_env_val(
+        context: &LuaValidator,
+        name: &str,
+        raw_val: &Value,
+    ) -> mlua::Result<OsString> {
+        context.parse_val(name, raw_val)?;
+
+        // let ctx = format!("{} [{}]", context, name);
+        let capacity = match raw_val {
+            Value::Table(t) => t.raw_len().min(128),
+            Value::Nil => 0,
+            _ => 1,
+        };
+
+        let mut parts = Vec::with_capacity(capacity);
+
+        Self::collect_value_into(&context, raw_val, &mut parts)?;
+        // context.collect_value_into(raw_val, &mut parts)?;
+
+        // 校验每个展开元素的 NUL 字符
+        for part in &parts {
+            Self::ensure_no_nul(&name, part)?;
+        }
+        // 3. 使用系统路径分隔符拼接数组列表
+        let joined_os_str = std::env::join_paths(parts).map_err(|e| {
+            validation_error(format!("{} 的值无法用系统路径分隔符拼接: {}", context, e))
+        })?;
+        Ok(joined_os_str)
+    }
+
+    /// 解析整个 `env` Table，直接返回安全的环境变量 Map
+    pub fn parse_env(value: &Value) -> mlua::Result<HashMap<String, OsString>> {
+        let ctx = Self::Env;
+
+        let Value::Table(tbl) = value else {
+            // 这里作为防御性校验，外部虽然 match 过了，但内层仍保持强类型安全
+            return Err(validation_error(format!(
+                "{} 必须是键值表 (table)，实际类型是 {}",
+                ctx,
+                value.type_name()
+            )));
+        };
+
+        let mut env_map = HashMap::new();
+        let mut n = 0i32;
+
+        for pair in tbl.pairs::<Value, Value>() {
+            n += 1;
+
+            let (raw_key, raw_val) = pair?;
+            debug!("env {} {}", n, raw_val.type_name());
+
+            // 1. 解析并校验 Key，拿到安全的 String
+            let key = Self::parse_env_name(&raw_key)?;
+
+            // 2. 借用 &name 传递给 Value 解析器作为上下文
+            let val = Self::parse_env_val(&ctx, &key, &raw_val)?;
+
+            env_map.insert(key, val);
+        }
+
+        Ok(env_map)
+    }
+}
+
+impl LuaValidator {
+    /// 校验环境变量名的合法性（Windows 约束：非空、不含 '='、不含 NUL）
+    fn parse_aliases_name(name: &Value) -> mlua::Result<String> {
+        Self::parse_name(name)
+    }
+    fn parse_aliases_val(
+        context: &LuaValidator,
+        name: &str,
+        raw_val: &Value,
+    ) -> mlua::Result<Vec<OsString>> {
+        context.parse_val(name, raw_val)?;
+
+        // let ctx = format!("{} [{}]", context, name);
+        // 预估容量：标量为 1，表取其实际长度（设置上限以防止异常输入）
+        let capacity = match raw_val {
+            Value::Table(t) => (t.raw_len() as usize).min(16),
+            Value::Nil => 0,
+            _ => 1,
+        };
+
+        let mut parts = Vec::with_capacity(capacity);
+        Self::collect_value_into(context, raw_val, &mut parts)?;
+        Ok(parts)
+    }
+    /// 解析并打平别名表 (aliases)
+    /// - 支持输入为 Nil / None / Table
+    /// - 别名的值支持：String, Number, Boolean, Nil, " " 空白串, Table(连续数组)
+    /// - 字符串作为整体参数保存，仅做 trim() 清理首尾空格，不按空格拆分
+    /// - 包含拓扑展开与死环检测
+    pub fn parse_aliases(value: &Value) -> mlua::Result<HashMap<String, Vec<OsString>>> {
+        let ctx = Self::Aliases;
+        // 1. 处理 nil / None 的情况，直接返回空 HashMap
+        let Value::Table(table) = value else {
+            return Err(validation_error(format!(
+                "{} 必须是键值表 (table) ，当前类型: {}",
+                ctx,
+                value.type_name()
+            )));
+        };
+
+        // 阶段一：提取原始别名映射 (Raw Extraction)
+        let mut raw_aliases: HashMap<String, Vec<OsString>> = HashMap::new();
+
+        for pair in table.pairs::<Value, Value>() {
+            let (raw_key, raw_val) = pair?;
+            let key = Self::parse_aliases_name(&raw_key)?;
+            let val = Self::parse_aliases_val(&ctx, &key, &raw_val)?;
+
+            raw_aliases.insert(key, val);
+        }
+        // 阶段二：递归拓扑打平与循环引用检测 (Flattening & Cycle Detection)
+        let mut visited_stack = HashSet::new();
+
+        for key in raw_aliases.keys() {
+            visited_stack.clear();
+            Self::detect_alias_cycle(key, &raw_aliases, &mut visited_stack)?;
+        }
+
+        // 阶段三：无环前提下的高效展开
+        let mut flattened_aliases: HashMap<String, Vec<OsString>> =
+            HashMap::with_capacity(raw_aliases.len());
+
+        let mut resolved_args = Vec::new();
+
+        for key in raw_aliases.keys() {
+            resolved_args.clear();
+            Self::expand_alias_dfs(key, &raw_aliases, &mut resolved_args);
+            flattened_aliases.insert(key.clone(), resolved_args.clone());
+        }
+
+        Ok(flattened_aliases)
+    }
+
+    /// 仅用于校验别名依赖图中是否存在死循环（不消耗额外的参数拼接内存）
+    fn detect_alias_cycle(
+        current_key: &str,
+        raw_aliases: &HashMap<String, Vec<OsString>>,
+        visited_stack: &mut HashSet<String>,
+    ) -> mlua::Result<()> {
+        // 递归栈中再次遇到相同的 Key，说明存在死循环
+        if visited_stack.contains(current_key) {
+            return Err(validation_error(format!(
+                "配置加载失败: 检测到别名循环嵌套依赖 'mr:{}'",
+                current_key
+            )));
+        }
+
+        if let Some(args) = raw_aliases.get(current_key) {
+            // 压栈
+            visited_stack.insert(current_key.to_string());
+
+            for arg in args {
+                let arg_str = arg.to_string_lossy();
+                if let Some(sub_key) = arg_str.strip_prefix("mr:") {
+                    // 如果引用的子别名在映射表中存在，则深度优先校验
+                    if raw_aliases.contains_key(sub_key) {
+                        Self::detect_alias_cycle(sub_key, raw_aliases, visited_stack)?;
+                    }
+                }
+            }
+
+            // 出栈（回溯）
+            visited_stack.remove(current_key);
+        }
+
+        Ok(())
+    }
+    /// 安全拓扑展开：在保证绝对无环的前提下递归展开 mr: 前缀参数
+    fn expand_alias_dfs(
+        current_key: &str,
+        raw_aliases: &HashMap<String, Vec<OsString>>,
+        out: &mut Vec<OsString>,
+    ) {
+        if let Some(args) = raw_aliases.get(current_key) {
+            for arg in args {
+                let arg_str = arg.to_string_lossy();
+                if let Some(sub_key) = arg_str.strip_prefix("mr:") {
+                    if raw_aliases.contains_key(sub_key) {
+                        // 安全地直接递归展开，无需再检查死循环
+                        Self::expand_alias_dfs(sub_key, raw_aliases, out);
+                    } else {
+                        // 找不到对应的别名，按原样参数输出
+                        out.push(arg.clone());
+                    }
+                } else {
+                    // 普通参数，直接输出
+                    out.push(arg.clone());
+                }
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::Mirror;
+    use mlua::{FromLua, Lua};
+
+    fn parse(src: &str) -> mlua::Result<Mirror> {
+        let lua = Lua::new();
+        // 模拟 runtime 注入的 get_env：返回按平台分隔符拆分的段数组（空变量返回空表）
+        let get_env = lua
+            .create_function(|lua, key: String| -> mlua::Result<Table> {
+                let value = std::env::var(key).unwrap_or_default();
+                let segments: Vec<String> = if value.is_empty() {
+                    Vec::new()
+                } else {
+                    std::env::split_paths(std::ffi::OsStr::new(&value))
+                        .map(|p| p.to_string_lossy().into_owned())
+                        .collect()
+                };
+                lua.create_sequence_from(segments)
+            })
+            .unwrap();
+        lua.globals().set("get_env", get_env).unwrap();
+
+        let value = lua.load(src).eval::<Value>()?;
+        let t = Mirror::from_lua(value, &lua);
+        println!("读取出的数据：{:?}", t.clone()?);
+        t
+    }
+
+    #[test]
+    fn parses_basic_config() {
+        let cfg = parse(
+            r#"
+            return {
+                target = "C:/tools/git.exe",
+                args = { "--no-pager",2},
+                env = {
+                    PATH = { "C:/tools/git/bin", "C:/Windows", get_env("PATH")},
+                    HOME = "C:/tools/home",
+                    CONST = 3,
+                    BOOL = true,
+                },
+                aliases = {
+                    -- 1. 整体字符串（会自动 trim 首尾空格，保留为单个参数）
+                    st = "status -s",
+
+                    -- 2. 连续数组表 (Sequence Table)
+                    lg = { "log", "--oneline", "-n", 10 },
+
+                    -- 3. 标量数字与布尔值支持
+                    v = 1,
+                    quiet = true,
+
+                    -- 4. 嵌套别名组合（加载期会自动展开并进行死环检测）
+                    base_log = "log --graph",
+                    all_log = { "mr:base_log", "--all","D:\\CNWei\\CNW\\Rust","D:/CNWei/CNW/Rust/" ,[[D:\CNWei\CNW\Rust\]]},
+
+                    -- 5. nil 或空字符串（解析为空参数列表）
+                    empty_alias = nil,
+                    blank = "   "
+                }
+            }
+            "#,
+        )
+        .unwrap();
+        assert_eq!(cfg.target, PathBuf::from("C:/tools/git.exe"));
+        // assert_eq!(cfg.args, vec!["--no-pager", "2"]);
+        assert_eq!(cfg.env.get("HOME").unwrap().to_str(), Some("C:/tools/home"));
+        // PATH 前缀来自配置，随后附加 get_env("PATH") 拆出的宿主 PATH 段
+        let path = cfg.env.get("PATH").unwrap().to_str().unwrap();
+        assert!(
+            path == "C:/tools/git/bin;C:/Windows"
+                || path.starts_with("C:/tools/git/bin;C:/Windows;"),
+            "unexpected PATH: {path}"
+        );
+        // ==================== aliases 断言校验 ====================
+
+        // 1. 整体字符串：保留原样（trim 后），不切分空格
+        assert_eq!(
+            cfg.aliases.get("st").unwrap(),
+            &vec![OsString::from("status"), OsString::from("-s")]
+        );
+
+        // 2. 连续数组表：按顺序转为 OsString 列表
+        assert_eq!(
+            cfg.aliases.get("lg").unwrap(),
+            &vec![
+                OsString::from("log"),
+                OsString::from("--oneline"),
+                OsString::from("-n"),
+                OsString::from("10")
+            ]
+        );
+
+        // 3. 标量数字与布尔值支持
+        assert_eq!(cfg.aliases.get("v").unwrap(), &vec![OsString::from("1")]);
+        assert_eq!(
+            cfg.aliases.get("quiet").unwrap(),
+            &vec![OsString::from("true")]
+        );
+
+        // 4. 嵌套别名组合：加载期递归拓扑打平
+        // base_log 本身为 "log --graph"
+        assert_eq!(
+            cfg.aliases.get("base_log").unwrap(),
+            &vec![OsString::from("log"), OsString::from("--graph")]
+        );
+        // all_log 展开 mr:base_log 替换为 "log --graph"，追加 "--all"
+        assert_eq!(
+            cfg.aliases.get("all_log").unwrap(),
+            &vec![
+                OsString::from("log"),
+                OsString::from("--graph"),
+                OsString::from("--all"),
+                OsString::from("D:\\CNWei\\CNW\\Rust"),
+                OsString::from("D:/CNWei/CNW/Rust/"),
+                OsString::from("D:\\CNWei\\CNW\\Rust\\"),
+            ]
+        );
+
+        // 5. nil 与纯空白字符串：解析为空 Vec
+        assert_eq!(cfg.aliases.get("blank").unwrap(), &Vec::<OsString>::new());
+        // nil 键在遍历表时会被当作空或不存在，不产生 key 或值为空 Vec
+        assert!(
+            cfg.aliases
+                .get("empty_alias")
+                .map_or(true, |v| v.is_empty())
+        );
+    }
+
+    #[test]
+    fn missing_args_and_env_are_empty() {
+        let cfg = parse(r#"return { target = "t.exe" }"#).unwrap();
+        assert!(cfg.args.is_empty());
+        assert!(cfg.env.is_empty());
+    }
+
+    #[test]
+    fn keeps_empty_args() {
+        let cfg = parse(r#"return { target = "t.exe", args = { "" } }"#).unwrap();
+        assert_eq!(cfg.args, vec![""]);
+    }
+
+    #[test]
+    fn keeps_empty_env_value() {
+        let cfg = parse(r#"return { target = "t.exe", env = { FOO = "" } }"#).unwrap();
+        assert_eq!(cfg.env.get("FOO").unwrap().to_str(), Some(""));
+    }
+
+    #[test]
+    fn empty_array_clears_env_var() {
+        let cfg = parse(r#"return { target = "t.exe", env = { PATH = {} } }"#).unwrap();
+        assert_eq!(cfg.env.get("PATH").unwrap().to_str(), Some(""));
+    }
+
+    #[test]
+    fn expands_nested_env_array() {
+        // get_env("PATH") 现在返回拆分后的段数组，嵌套表应被递归展开
+        let cfg = parse(
+            r#"return { target = "t.exe", env = { PATH = { "C:/a", { "C:/b", "C:/c" } } } }"#,
+        )
+        .unwrap();
+        assert_eq!(
+            cfg.env.get("PATH").unwrap().to_str(),
+            Some("C:/a;C:/b;C:/c")
+        );
+    }
+
+    #[test]
+    fn rejects_wrong_env_type() {
+        assert!(parse(r#"return { target = "t.exe", env = "PATH=C:/x" }"#).is_err());
+    }
+
+    #[test]
+    fn rejects_sparse_env_array() {
+        assert!(parse(r#"return { target = "t.exe", env = { P = { "a", nil, "b" } } }"#).is_err());
+    }
+
+    #[test]
+    fn rejects_mixed_key_env_array() {
+        assert!(parse(r#"return { target = "t.exe", env = { P = { a = "b" } } }"#).is_err());
+    }
+
+    #[test]
+    fn rejects_invalid_env_key() {
+        assert!(parse(r#"return { target = "t.exe", env = { ["FOO=1"] = "x" } }"#).is_err());
+        assert!(parse(r#"return { target = "t.exe", env = { [""] = "x" } }"#).is_err());
+    }
+
+    #[test]
+    fn rejects_nul_in_env_value() {
+        assert!(parse(r#"return { target = "t.exe", env = { P = { string.char(0) } } }"#).is_err());
+    }
+
+    #[test]
+    fn rejects_quote_in_env_value() {
+        // Windows 的 join_paths 对含双引号的路径元素返回错误
+        assert!(
+            parse(r#"return { target = "t.exe", env = { P = { string.char(34) } } }"#).is_err()
+        );
+    }
+
+    #[test]
+    fn rejects_unsupported_env_value_type() {
+        assert!(parse(r#"return { target = "t.exe", env = { F = function() end } }"#).is_err());
+    }
+
+    #[test]
+    fn missing_target_is_error() {
+        assert!(parse(r#"return { args = { "x" } }"#).is_err());
+    }
+
+    #[test]
+    fn rejects_non_string_target() {
+        assert!(parse(r#"return { target = 123 }"#).is_err());
+        assert!(parse(r#"return { target = false }"#).is_err());
+    }
+
+    #[test]
+    fn rejects_non_string_args_element() {
+        // ValueShunt::Args 允许基础标量（数字/布尔）转字符串，仅禁止嵌套表
+        let cfg = parse(r#"return { target = "t.exe", args = { 1, true } }"#).unwrap();
+        assert_eq!(cfg.args, vec!["1", "true"]);
+    }
+
+    #[test]
+    fn rejects_sparse_args() {
+        assert!(parse(r#"return { target = "t.exe", args = { "a", nil, "b" } }"#).is_err());
+    }
+
+    #[test]
+    fn rejects_non_table_args() {
+        assert!(parse(r#"return { target = "t.exe", args = "-B" }"#).is_err());
+    }
+}