feat: prefer bundled assets for mihomo runtime deps

.env

@@ -20,3 +20,6 @@ export MIHOMO_VERSION="v1.19.23"
 export CLASH_VERSION="v1.18.0"
 export YQ_VERSION="v4.52.4"
 export SUBCONVERTER_VERSION="v0.9.0"
+
+# 内置运行依赖（resources/bin），设为 false 可强制跳过内置文件并联网下载
+export CLASH_BUNDLED_ASSET_ENABLED="true"

.gitattributes

@@ -1,4 +1,7 @@
 *.sh text eol=lf
 *.yaml text eol=lf
 *.yml text eol=lf
-*.env text eol=lf
+*.env text eol=lf
+*.gz binary
+*.zip binary
+*.mmdb binary

README.md

@@ -218,10 +218,38 @@ YQ_VERSION=v4.44.3
 SUBCONVERTER_VERSION=v0.9.0
 MIHOMO_DOWNLOAD_BASE=https://github.com/MetaCubeX/mihomo/releases/download
 CLASH_DOWNLOAD_BASE=https://github.com/WindSpiritSR/clash/releases/download
+CLASH_BUNDLED_ASSET_ENABLED=true
 ```
 
 按需设置即可，不需要每项都写。
 
+### 内置运行依赖
+
+当前正式支持的架构为 `amd64`、`arm64`、`armv7`。超出这三种架构时会明确失败，不会伪装成已支持。
+
+如果安装环境访问 GitHub 很慢，可以把 Mihomo、yq、subconverter 的刚需文件跟随项目一起分发。安装和 `clashctl upgrade` 会优先读取 `resources/bin` 中与当前版本、架构对应的精确文件名；本地没有对应文件时，会回退到原来的远程下载逻辑，不影响后续升级内核。
+
+Clash 仅作为兼容内核处理，固定走远程下载，不会命中 `resources/bin` 中的本地资源。
+
+推荐路径直接放在分类目录下：
+
+```text
+resources/bin/mihomo/mihomo-linux-amd64-compatible-v1.19.23.gz
+resources/bin/mihomo/mihomo-linux-arm64-v1.19.23.gz
+resources/bin/mihomo/mihomo-linux-armv7-v1.19.23.gz
+resources/bin/yq/yq_linux_amd64.tar.gz
+resources/bin/yq/yq_linux_arm64.tar.gz
+resources/bin/yq/yq_linux_arm.tar.gz
+resources/bin/subconverter/subconverter_linux64.tar.gz
+resources/bin/subconverter/subconverter_aarch64.tar.gz
+resources/bin/subconverter/subconverter_armv7.tar.gz
+resources/geo/Country.mmdb
+```
+
+版本仍由 `.env` 中的 `MIHOMO_VERSION`、`CLASH_VERSION`、`YQ_VERSION`、`SUBCONVERTER_VERSION` 控制。脚本不会扫描目录，也不会自动选择最高版本；如果升级版本，请同步放入新版本对应文件，或让脚本回退到远程下载。
+
+也可以设置 `CLASH_BUNDLED_ASSET_ENABLED=false` 强制跳过内置文件，或用 `CLASH_BUNDLED_ASSET_DIR=/path/to/assets` 指向项目外的资源目录。Mihomo、yq、subconverter 兼容旧路径 `resources/bin/<category>/<version>/<file>`。
+
 ### `config/mixin.yaml`
 
 用于对最终运行配置做补丁：

resources/bin/README.md

@@ -0,0 +1,36 @@
+# 内置运行依赖
+
+如果安装时 GitHub 下载太慢，可以把 Mihomo、yq、subconverter 提前放到本目录。安装和 `clashctl upgrade` 会优先读取这里的文件；没有匹配文件时，仍会回退到原来的下载逻辑。
+
+Clash 是兼容内核，固定走远程下载，不使用本目录中的本地资源。
+
+默认目录结构：
+
+```text
+resources/bin/
+  mihomo/
+    mihomo-linux-amd64-compatible-v1.19.23.gz
+    mihomo-linux-arm64-v1.19.23.gz
+    mihomo-linux-armv7-v1.19.23.gz
+  yq/
+    yq_linux_amd64.tar.gz
+    yq_linux_arm64.tar.gz
+    yq_linux_arm.tar.gz
+  subconverter/
+    subconverter_linux64.tar.gz
+    subconverter_aarch64.tar.gz
+    subconverter_armv7.tar.gz
+```
+
+当前正式支持 `amd64`、`arm64`、`armv7`。版本号要和 `.env` 里的 `MIHOMO_VERSION`、`YQ_VERSION`、`SUBCONVERTER_VERSION` 对应。脚本只按当前目标文件名精确命中，不会扫描目录，也不会自动选择最高版本；如果本地没有对应文件，会继续联网下载。
+
+Mihomo、yq、subconverter 兼容旧路径 `resources/bin/<category>/<version>/<file>`，但默认推荐直接使用 `resources/bin/<category>/<file>`。
+
+可选开关：
+
+```bash
+export CLASH_BUNDLED_ASSET_ENABLED=false
+export CLASH_BUNDLED_ASSET_DIR=/path/to/assets
+```
+
+`Country.mmdb` 仍放在 `resources/geo/Country.mmdb` 或 `resources/geo/country.mmdb`。

scripts/core/common.sh

@@ -315,6 +315,55 @@ github_proxy_prefix() {
   echo "$prefix"
 }
 
+bundled_asset_enabled() {
+  case "${CLASH_BUNDLED_ASSET_ENABLED:-true}" in
+    true|1|yes|on) return 0 ;;
+    false|0|no|off) return 1 ;;
+    *) return 0 ;;
+  esac
+}
+
+bundled_asset_root() {
+  if [ -n "${CLASH_BUNDLED_ASSET_DIR:-}" ]; then
+    echo "$CLASH_BUNDLED_ASSET_DIR"
+    return 0
+  fi
+
+  [ -n "${RESOURCE_DIR:-}" ] || return 1
+  echo "$RESOURCE_DIR/bin"
+}
+
+copy_bundled_asset() {
+  local category="$1"
+  local version="$2"
+  local file="$3"
+  local out="$4"
+  local asset_name="${5:-$file}"
+  local root candidate
+
+  [ "$category" != "clash" ] || return 1
+  bundled_asset_enabled || return 1
+
+  root="$(bundled_asset_root 2>/dev/null || true)"
+  [ -n "${root:-}" ] || return 1
+
+  for candidate in \
+    "$root/$category/$file" \
+    "$root/$category/$version/$file" \
+    "$root/$file"; do
+    [ -s "$candidate" ] || continue
+
+    mkdir -p "$(dirname "$out")"
+    if [ "$candidate" != "$out" ]; then
+      cp -f "$candidate" "$out"
+    fi
+    success "${asset_name} 已使用内置资源：$candidate"
+    return 0
+  done
+
+  return 1
+}
+
 download_connect_timeout() {
   echo "${CLASH_DOWNLOAD_CONNECT_TIMEOUT:-8}"
 }
@@ -1061,6 +1110,7 @@ init_layout() {
     "$CONFIG_DIR" \
     "$RESOURCE_DIR" \
     "$RESOURCE_DIR/geo" \
+    "$RESOURCE_DIR/bin" \
     "$RESOURCE_DIR/dashboard" \
     "$PROJECT_DIR/scripts/core" \
     "$PROJECT_DIR/scripts/init" \

scripts/core/runtime.sh

@@ -26,7 +26,9 @@ resolve_yq() {
   tmp_dir="$(mktemp -d)"
   tmp_file="$tmp_dir/$file"
 
-  download_file "$url" "$tmp_file" "yq"
+  if ! copy_bundled_asset "yq" "$version" "$file" "$tmp_file" "yq"; then
+    download_file "$url" "$tmp_file" "yq"
+  fi
   tar -xzf "$tmp_file" -C "$tmp_dir"
 
   if [ -f "$tmp_dir/yq_linux_${arch}" ]; then
@@ -69,7 +71,9 @@ resolve_mihomo() {
   fi
   tmp_file="$(mktemp)"
 
-  download_file "$url" "$tmp_file" "mihomo（可在 .env 中设置 MIHOMO_DOWNLOAD_BASE / MIHOMO_DOWNLOAD_URL）"
+  if ! copy_bundled_asset "mihomo" "$version" "$file" "$tmp_file" "mihomo"; then
+    download_file "$url" "$tmp_file" "mihomo（可在 .env 中设置 MIHOMO_DOWNLOAD_BASE / MIHOMO_DOWNLOAD_URL）"
+  fi
   gzip -dc "$tmp_file" > "$(mihomo_bin)"
   chmod +x "$(mihomo_bin)"
   rm -f "$tmp_file"
@@ -242,7 +246,9 @@ resolve_subconverter() {
   tmp_file="$tmp_dir/$file"
   extract_dir="$tmp_dir/extract"
 
-  download_file "$url" "$tmp_file" "subconverter"
+  if ! copy_bundled_asset "subconverter" "$version" "$file" "$tmp_file" "subconverter"; then
+    download_file "$url" "$tmp_file" "subconverter"
+  fi
 
   package_type="$(detect_subconverter_package_type "$tmp_file")"
 

scripts/init/script.sh

@@ -302,12 +302,18 @@ wait_install_runtime_ready() {
   write_runtime_value "INSTALL_VERIFY_CONTROLLER_READY" "$controller_ready"
 }
 
+clashctl_command_available() {
+  [ -x "$(clashctl_entry_target)" ] \
+    || [ -x "$(clashctl_bin_entry_target)" ] \
+    || command -v clashctl >/dev/null 2>&1
+}
+
 post_install_verify() {
   local has_subscription="false"
   local runtime_ready="false"
   local controller_ready="false"
 
-  if command -v clashctl >/dev/null 2>&1; then
+  if clashctl_command_available; then
     write_runtime_value "INSTALL_VERIFY_COMMAND_READY" "true"
   else
     write_runtime_value "INSTALL_VERIFY_COMMAND_READY" "false"