feat: 目录结构迁移优化

- 将 MirrorRegistry MirrorTarget 迁移到 model.rs - TargetConfig 独立实现 FromLua，解耦反序列化与业务校验 - mirror—shim 新增 command.rs 并将 to_command 移动到 command.rs - 其他优化
2026-09-12 10:45:39 +08:00
parent 0bba69fd51
commit 53579f9c65
24 changed files with 1472 additions and 972 deletions
@@ -15,3 +15,9 @@ tracing = { workspace = true }
 tracing-subscriber = { workspace = true }
 tracing-appender = { workspace = true }
 thiserror = "2.0.20"
+
+
+
+[features]
+default = []
+args = []
@@ -0,0 +1,52 @@
+use crate::validators::LuaValidator;
+use anyhow::{Context, Result, bail};
+use crate::{conversion_err, validate_command_name, validation_error, TargetConfig};
+use mlua::{FromLua, Lua, Table, Value};
+use std::collections::HashMap;
+use std::env;
+use std::ffi::OsString;
+use std::path::{Path, PathBuf};
+use std::process::Command;
+use tracing::{debug, trace};
+use crate::model::MirrorTarget;
+
+/// 单个目标程序的代理规格配置
+
+impl MirrorTarget {
+    /// 1. 核心参数路由解析（Delegation 到 Spec 的路由逻辑）
+   pub 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
+    }
+
+}
+
+
@@ -4,7 +4,6 @@ use std::path::{Path, PathBuf};
 use tracing::debug;
 pub struct Layout {
    pub base_dir: PathBuf,
-    pub bin_dir: PathBuf,
    pub target_name: String,
 }

@@ -23,7 +22,6 @@ impl Layout {
        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);
@@ -41,11 +39,16 @@ impl Layout {
            bail!("指定的根目录不存在或不是有效目录: [{}]", base_dir.display());
        }

-        let bin_dir = base_dir.join("bin");
+        let mirror_file = base_dir.join("mirror.lua");
+        if !mirror_file.is_file() {
+            bail!(
+                "根目录 [{}] 下未找到核心配置文件 [mirror.lua]",
+                base_dir.display()
+            );
+        }

        Ok(Self {
            base_dir,
-            bin_dir,
            target_name,
        })
    }
@@ -53,20 +56,55 @@ impl Layout {
    /// 从当前可执行文件解析 shim 安装目录布局
    fn from_executable(exe_path: &Path, target_name: String) -> Result<Self> {
        // let exe_path = exe_path.as_ref();
-        let bin_dir = exe_path
+        let start_dir = exe_path
            .parent()
-            .with_context(|| format!("无法获取程序 [{}] 的父级 bin 目录", exe_path.display()))?
-            .to_path_buf();
+            .with_context(|| format!("无法获取程序 [{}] 的所在目录", exe_path.display()))?;

-        debug!("bin_dir目录 {}", bin_dir.display());
+        debug!("可执行程序所在目录: {}", start_dir.display());

-        let base_dir = bin_dir
-            .parent()
-            .with_context(|| format!("无法获取 bin 目录 [{}] 的父级 root 目录", bin_dir.display()))?
-            .to_path_buf();
+        // let base_dir = start_dir
+        //     .parent()
+        //     .with_context(|| format!("无法获取 bin 目录 [{}] 的父级 root 目录", bin_dir.display()))?
+        //     .to_path_buf();

-        debug!("base_dir 目录 {}", base_dir.display());
+        // 2. 向上回溯寻找 mirror.lua 锚点
+        let base_dir = find_base_dir_by_anchor(start_dir).ok_or_else(|| {
+            anyhow::anyhow!(
+                "路径推导失败：从 [{}] 向上逐级回溯均未找到 [mirror.lua]。\n\
+                提示: 请确保程序位于包含 mirror.lua 的项目内，或配置 MIRROR_HOME 环境变量。",
+                start_dir.display()
+            )
+        })?;
+        debug!("成功探测到 base_dir 目录 {}", base_dir.display());

-        Self::from_base_dir(base_dir, target_name)
+        // 此时 base_dir 下必然有 mirror.lua，直接构建
+        Ok(Self {
+            base_dir,
+            target_name,
+        })
    }
 }
+/// 向上查找包含 mirror.lua 的根目录
+fn find_base_dir_by_anchor(start_dir: &Path) -> Option<PathBuf> {
+    let mut current = Some(start_dir);
+
+    // 最大向上回溯层级（例如 3~4 层，防止死循环跑到磁盘根目录甚至网络挂载点）
+    let mut depth = 0;
+    const MAX_DEPTH: usize = 4;
+
+    while let Some(dir) = current {
+        if depth > MAX_DEPTH {
+            break;
+        }
+
+        // 只要当前目录下有 mirror.lua，这里就是真正的 base_dir！
+        if dir.join("mirror.lua").is_file() {
+            return Some(dir.to_path_buf());
+        }
+
+        current = dir.parent();
+        depth += 1;
+    }
+
+    None
+}
@@ -6,15 +6,16 @@ mod runtime;
 mod utils;
 mod validators;
 mod model;
+mod alias;

+pub use  model::{MirrorRegistry,MirrorTarget,TargetConfig};
 pub use layout::Layout;
 // pub use mirror_shim::mirror::Mirror;
 pub use runtime::LuaRuntime;

-pub use logger::{LogConfig, LogLevel, init_logging_from};
+pub use logger::{init_logging_from, LogConfig, LogLevel};
 pub use plugins::register_basics;
 pub use utils::normalize_path_for_lua;
 pub use validators::validate_command_name;
 // 把 Result 和 Error 提升到根命名空间，给外部带来极致便利
-pub use error::{Error, Result,validation_error,conversion_err,TargetExecutionError};
-pub use model::TargetConfig;
+pub use error::{conversion_err, validation_error, Error, Result, TargetExecutionError};
@@ -1,10 +1,115 @@
+use std::collections::HashMap;
 use std::ffi::OsString;
 use mlua::{FromLua, Lua, LuaString, Value};
 use std::path::PathBuf;
 use crate::utils::lua_string_2_os_string;
-use crate::validation_error;
-use crate::validators::ensure_no_nul;
+use crate::{conversion_err, validate_command_name, validation_error};
+use crate::validators::{ensure_no_nul, LuaValidator};
+pub struct MirrorRegistry {
+    pub targets: HashMap<String, MirrorTarget>,
+}
+impl FromLua for MirrorRegistry {
+    fn from_lua(value: Value, lua: &Lua) -> mlua::Result<Self> {
+        let root_tbl = match value {
+            Value::Table(t) => t,
+            other => {
+                return Err(conversion_err(
+                    other.type_name(),
+                    "MirrorRegistry",
+                    format!(
+                        "mirror 全局注册表顶层必须是 Table，实际检测到: {}",
+                        other.type_name()
+                    ),
+                ));
+            }
+        };
+        let mut targets = HashMap::new();
+        for pair in root_tbl.pairs::<Value, Value>() {
+            let (key, entry) = pair?;

+            let target_name = validate_command_name(&key)?;
+            // 2. 校验 entry 是否是 Table
+            if !entry.is_table() {
+                return Err(conversion_err(
+                    entry.type_name(),
+                    "MirrorRegistry",
+                    format!(
+                        "目标工具 '{target_name}' 的配置必须是 Table，实际检测到: {}",
+                        entry.type_name()
+                    ),
+                ));
+            }
+            // 3. 直接交由子命令解析，外层负责补充错误上下文
+            let target_spec = MirrorTarget::from_lua(entry, lua).map_err(|err| {
+                validation_error(format!("目标工具 '{target_name}' 配置解析失败:\n{err}"))
+            })?;
+
+            targets.insert(target_name, target_spec);
+        }
+        Ok(Self { targets })
+    }
+}
+#[derive(Debug, Clone, Default)]
+pub struct MirrorTarget {
+    /// 目标程序可执行文件路径
+    pub target: TargetConfig,
+    /// 默认预设参数列表
+    pub args: Vec<OsString>,
+    /// 参数别名映射表（用于展开以 mr: 为前缀的别名）
+    pub aliases: HashMap<String, Vec<OsString>>,
+    /// 注入/覆盖的环境变量
+    pub env: HashMap<String, OsString>,
+}
+impl FromLua for MirrorTarget {
+    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)?,
+            Some(target_val) => TargetConfig::from_lua(target_val, lua)?,
+        };
+
+        // 可选字段: 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,
+        })
+    }
+}
 /// 目标可执行文件的定位配置（支持静态路径与多版本 Table）
 #[derive(Debug, Clone)]
 pub enum TargetConfig{
@@ -1,7 +1,8 @@
 use crate::error::{Error, Result};
 use crate::{Layout, normalize_path_for_lua};
 use mlua::{Lua, Table, Value};
-use std::env;
+use std::path::PathBuf;
+use std::{env, fs};
 use tracing::{debug, warn};

 const MIRROR_DIR: &str = "__MIRROR_DIR__";
@@ -12,6 +13,7 @@ pub fn register_basics(lua: &Lua, layout: &Layout) -> Result<()> {
    register_mirror_dir(lua, &base_dir)?;
    register_get_env(lua)?;
    setup_require(lua, &base_dir)?;
+    register_mr_version(lua)?;
    Ok(())
 }

@@ -109,3 +111,52 @@ pub fn setup_require(lua: &Lua, base_dir: &str) -> Result<()> {

    Ok(())
 }
+
+/// 向 Lua 全局环境注册 `mr` 模块及其原生辅助函数
+pub fn register_mr_version(lua: &Lua) -> Result<()> {
+    // 1. 获取或创建全局 `mr` Table
+    let globals = lua.globals();
+    let mr_table = match globals.get::<Value>("mr")? {
+        Value::Table(t) => t,
+        _ => {
+            let t = lua.create_table()?;
+            globals.set("mr", t.clone())?;
+            t
+        }
+    };
+
+    // 2. 实现 mr.version(home, version_file) -> Option<String>
+    // 规则：
+    // - version_file 为可选参数，缺省默认使用 ".version"
+    // - 文件不存在、空内容或读取失败时，安全返回 nil，绝不让 Lua 脚本崩盘
+    // - 自动 trim 掉末尾的 \r\n，仅提取纯净版本号
+    let version_fn = lua.create_function(
+        |_lua, (home_str, version_file_opt): (String, Option<String>)| {
+            let version_filename = version_file_opt
+                .filter(|s| !s.trim().is_empty())
+                .unwrap_or_else(|| ".version".to_string());
+
+            let mut target_path = PathBuf::from(home_str);
+            target_path.push(version_filename);
+
+            // 读取文件并安全修剪
+            match fs::read_to_string(&target_path) {
+                Ok(content) => {
+                    let trimmed = content.trim();
+                    if trimmed.is_empty() {
+                        Ok(None::<String>) // 文件内容为空字符串时，视为未设置版本
+                    } else {
+                        Ok(Some(trimmed.to_string()))
+                    }
+                }
+                // 常见错误（NotFound 等）直接返回 nil，不抛出 Lua error
+                Err(_) => Ok(None::<String>),
+            }
+        },
+    )?;
+
+    // 3. 挂载到 mr 表
+    mr_table.set("version", version_fn)?;
+
+    Ok(())
+}
@@ -102,7 +102,7 @@ mod tests {
        let root = std::env::temp_dir().join("rshim-test-layout");
        Layout {
            base_dir: root.clone(),
-            bin_dir: root.join("bin"),
+            // bin_dir: root.join("bin"),
            target_name: "muna".to_string(),
        }
    }
@@ -68,4 +68,166 @@ pub fn lua_string_2_os_string(s: &LuaString) -> mlua::Result<OsString> {
            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"]);
+    }
+}
@@ -62,4 +62,535 @@ pub fn ensure_no_nul(context: &impl fmt::Display, os_str: &std::ffi::OsStr) -> m
        }
    }
    Ok(())
-}
+}
+use anyhow::{Context, Result, anyhow};
+use crate::{TargetConfig,};
+use mlua::{LuaString, Table, };
+use std::collections::{HashMap, HashSet};
+use std::ffi::OsString;
+
+use std::path::PathBuf;
+use std::str::FromStr;
+// use tinyjson::JsonValue;
+use crate::utils::{lua_string_2_os_string, parse_tokens};
+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<TargetConfig> {
+        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(TargetConfig::Static(PathBuf::from(os_str)))
+            }
+            // 分支 2：多版本动态工具 target = { home = "...", version_file = "...", current = "..." }
+            Value::Table(t) => {
+                // 1. 解析 home（必填）
+                let home_val = t.get::<Value>("home")?;
+                let home = match home_val {
+                    Value::String(ref s) => {
+                        let os_str = lua_string_2_os_string(s)?;
+                        Self::ensure_no_nul(&"target.home", &os_str)?;
+                        PathBuf::from(os_str)
+                    }
+                    Value::Nil => {
+                        return Err(validation_error("多版本 target 表缺少必填字段 'home'"));
+                    }
+                    other => {
+                        return Err(validation_error(format!(
+                            "target.home 需为有效路径字符串，实际类型是 {}",
+                            other.type_name()
+                        )));
+                    }
+                };
+
+                // 2. 解析 version_file（选填，默认为 None，后续业务可 fallback 到 .version）
+                let version_file = match t.get::<Option<Value>>("version_file")? {
+                    Some(Value::String(ref s)) => {
+                        let os_str = lua_string_2_os_string(s)?;
+                        Self::ensure_no_nul(&"target.version_file", &os_str)?;
+                        Some(os_str.to_string_lossy().into_owned())
+                    }
+                    Some(Value::Nil) | None => None,
+                    Some(other) => {
+                        return Err(validation_error(format!(
+                            "target.version_file 应为文件名字符串，实际类型是 {}",
+                            other.type_name()
+                        )));
+                    }
+                };
+
+                // 3. 解析 current（选填/可为 nil：未激活或找不到版本时允许为 None）
+                let current = match t.get::<Option<Value>>("current")? {
+                    Some(Value::String(ref s)) => {
+                        let os_str = lua_string_2_os_string(s)?;
+                        Self::ensure_no_nul(&"target.current", &os_str)?;
+                        Some(PathBuf::from(os_str))
+                    }
+                    // Lua 侧 ver 为 nil 时，current 计算结果即为 nil，合法放行
+                    Some(Value::Nil) | None => None,
+                    Some(other) => {
+                        return Err(validation_error(format!(
+                            "target.current 需为有效路径字符串或 nil，实际类型是 {}",
+                            other.type_name()
+                        )));
+                    }
+                };
+
+                Ok(TargetConfig::Versioned {
+                    home,
+                    version_file,
+                    current,
+                })
+            }
+            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());
+                }
+            }
+        }
+    }
+}