mihomo-cli 3.7.0 → 3.8.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [3.8.0] - 2026-09-01
+
+### 新增
+
+- **ssh 隧道出口（`tunnel` 子命令，别名 `ssh`）** - 管理 `ssh -D` 动态转发进程的生命周期，把可 ssh 登录的机器变成本地 SOCKS5 出口。分流仍交给覆写机制，本功能补的是「隧道断了 mihomo 不知情、会一直往死端口送流量」这一环
+
+  ```bash
+  mihomo tunnel add work --host m4 --port 1080
+  mihomo tunnel up|down|status [名字]
+  mihomo tunnel rm <名字>
+  ```
+
+  - **随 `start` 一并拉起**：默认带 `auto` 标记，`start` 顺带启动、`stop` 连带停止（`--no-tunnel` 跳过，`add --no-auto` 不参与）
+  - **隧道失败不影响内核启动**：只影响内网分流那部分规则，故仅打印显眼的黄色警告并附上 ssh 给出的原因，其余流量照常
+  - **`stop` 只停自己起的**：手动 `tunnel up` 起的隧道带 `manual` 标记，不会被 `mihomo stop` 带走，避免下次 start 又起一个而累积僵尸进程
+  - **`status` 真实探测端口**：能识别「进程还在但转发已死」的假活——那正是最误导的形态，此时 mihomo 仍在往死端口送流量
+  - **起之前先检测端口占用**，不盲启后失败
+  - **`add` 生成覆写模板** `overwrite.tunnel-<名字>.yaml`（已建好 socks5 节点与 select 分组，分流规则留白待填），生成后完全由用户维护，CLI 不再改写，`tunnel rm` 也不删它
+  - 新增 `reset tunnel` 目标（先停进程再删运行态，反序会导致 ssh 进程失联且再也停不掉）
+
+  安全边界：`-D` 恒绑 `127.0.0.1` 且不提供绑定地址开关（绑 `0.0.0.0` 会让同一 WiFi 下任何设备经本机进内网）；`--host` 拒绝 `-` 开头的值（`-oProxyCommand=...` 等同任意命令执行）；ssh 参数固定带 `ExitOnForwardFailure`/`BatchMode`/`ConnectTimeout`/`ServerAlive*`
+
+  暂不做自动重连保活：断线依靠 `ServerAliveInterval` 让进程自退，再用 `tunnel status` 查出来
+
+### 修复
+
+- **`reset --full` 会留下空的 `settings.json`** - 新增的 `tunnel` 目标其 `onAfter` 会 `writeSettings` 清空隧道列表，若排在 `settings` 之后就会把刚删掉的文件重建成 `{}`，与「已重置: 设置」矛盾。现移到 `settings` 之前（与 `subs` 同理），并加单测锁定该顺序约束——这是 v3.7.0 已修过一次的同类问题（当时是参数顺序），换个目标又复发了
+
 ## [3.7.0] - 2026-08-22
 
 ### 修复

package/README.md

@@ -14,6 +14,7 @@
 - 🔄 **智能重启** - `sub use` 切换订阅、`ow on/off` 切换覆写后自动重启
 - 🚀 **进程管理** - 启动/停止/切换模式，自动清理残留进程
 - 🛡️ **进程保活** - 基于 launchd（root），崩溃/开机自动拉起，代理后台常驻（`daemon on`）
+- 🔌 **ssh 隧道出口** - 管理 `ssh -D` 进程生命周期，把内网机器变成本地 SOCKS5 出口，随 `start` 一并拉起
 - 🔄 **双模式支持** - Mixed 模式和 TUN 透明代理模式
 - 📊 **状态监控** - 查看运行状态、内存占用、订阅流量与到期时间
 - 📝 **日志管理** - 实时日志 + 历史日志归档（自动轮转，保留7天）
@@ -126,11 +127,16 @@ mihomo ui yacd     # YACD
 | --------------------------------- | ------------------------------------------------------------------- |
 | `mihomo kernel [--mirror [镜像]]` | 更新内核（默认直连，`--mirror` 使用镜像；更新后运行中实例需重启生效） |
 | `mihomo daemon [on\|off\|status]` | 进程保活：开机自启 + 崩溃自动重启（仅 Mixed 模式，on/off 需管理员密码）  |
+| `mihomo tunnel`                   | 列出 ssh 隧道及真实状态（别名 `ssh`/`tunnels`）                     |
+| `mihomo tunnel add <名字> --host <主机> --port <端口> [--no-auto]` | 添加隧道并生成覆写模板（默认随 start 拉起） |
+| `mihomo tunnel up\|down [名字]`   | 启动/停止隧道（无参即全部）                                          |
+| `mihomo tunnel status [名字]`     | 查看隧道状态（真实探测端口，能识别「假活」）                          |
+| `mihomo tunnel rm <名字> [-y]`    | 删除隧道（不删覆写文件）                                             |
 | `mihomo update`                   | 更新 mihomo-cli（先查 npm 最新版，已是最新则跳过重装）              |
 | `mihomo ui [zash\|dash\|yacd]`    | 打开 Web UI                                                         |
 | `mihomo dir`                      | 显示数据目录位置                                                    |
 | `mihomo dir open [target]`        | 打开指定目录（`root`, `subs`, `logs`, `data`, `runtime`, `kernel`）  |
-| `mihomo reset [目标...] [--full] [-y]` | 重置用户数据（可用目标：`subs`, `logs`, `data`, `runtime`, `settings`, `kernel`, `overwrites`, `daemon`；`--full` 删全部，`-y` 跳过确认） |
+| `mihomo reset [目标...] [--full] [-y]` | 重置用户数据（可用目标：`subs`, `logs`, `data`, `runtime`, `settings`, `kernel`, `overwrites`, `daemon`, `tunnel`；`--full` 删全部，`-y` 跳过确认） |
 | `mihomo version`                  | 显示版本信息                                                        |
 | `mihomo help`                     | 显示帮助信息                                                        |
 
@@ -143,7 +149,7 @@ mihomo ui yacd     # YACD
 - `mhm`
 - `mh`
 
-子命令组亦有别名：`subscription` = `sub`/`subs`/`subscriptions`，`directory` = `dir`/`dirs`/`directories`，`overwrite` = `ow`
+子命令组亦有别名：`subscription` = `sub`/`subs`/`subscriptions`，`directory` = `dir`/`dirs`/`directories`，`overwrite` = `ow`，`tunnel` = `ssh`/`tunnels`（`tun` 已被 TUN 模式占用）
 
 ### 快捷命令
 
@@ -173,6 +179,54 @@ mihomo ui yacd     # YACD
 - 需要 sudo / 管理员权限
 - 首次使用会自动配置 DNS 和路由
 
+## ssh 隧道出口
+
+把一台可 ssh 登录的机器（如公司内网的机器）变成本地 SOCKS5 出口，配合覆写规则即可只让内网域名走它，其余流量照常走订阅节点。本功能负责的是 **ssh 进程的生命周期管理**——隧道断了 mihomo 并不知情，会一直往死端口送流量。
+
+```bash
+mihomo tunnel add work --host m4 --port 1080   # m4 是 ~/.ssh/config 里的别名
+mihomo tunnel up work                          # 启动
+mihomo tunnel status                           # 查看状态（真实探测端口）
+mihomo tunnel down work                        # 停止
+```
+
+`add` 会生成一份覆写模板 `overwrite.tunnel-<名字>.yaml`，其中已建好 socks5 节点与分组，
+**分流规则留白待你填写**（CLI 无从知道你的内网域名）：
+
+```yaml
+# 取消注释并改成你的内网域名/网段
++rules:
+  - DOMAIN-SUFFIX,example.internal,Tunnel-work
+  - IP-CIDR,10.0.0.0/8,Tunnel-work
+```
+
+该文件生成后**完全由你维护**，CLI 不会再改写；`tunnel rm` 也不会删它。改完执行 `mihomo start` 生效。
+
+### 与 start / stop 的联动
+
+隧道默认带 `auto` 标记，`mihomo start` 会顺带拉起、`mihomo stop` 会连带停止（`--no-tunnel` 可跳过；`add` 时加 `--no-auto` 则不参与）。
+
+- **隧道起不来不会让 `start` 失败**——它只影响内网分流那部分规则，其余流量正常，但会打印显眼的黄色警告并附上 ssh 给出的原因
+- **`stop` 只停自己起的**：手动 `tunnel up` 起的隧道不会被 `mihomo stop` 带走，避免下次 start 又起一个而累积僵尸进程
+
+### 状态的三种形态
+
+`tunnel status` 会**真实探测端口是否在监听**，而不是只看进程在不在：
+
+| 状态 | 含义 |
+| --- | --- |
+| 运行中 | 进程在且端口在监听，可正常使用 |
+| **假活** | 进程还在但端口不通——最需要警惕的形态，此时 mihomo 仍在往死端口送流量 |
+| 未运行 | 进程不在 |
+
+### 安全边界
+
+- `-D` **恒绑 `127.0.0.1`**，不提供绑定地址开关：绑 `0.0.0.0` 会让同一 WiFi 下任何设备都能经本机进入内网
+- ssh 参数固定带 `ExitOnForwardFailure`/`BatchMode`/`ConnectTimeout`/`ServerAlive*`，分别防「假活」、无 TTY 挂死、久等、断线后端口成僵尸
+- `--host` 拒绝以 `-` 开头的值（`-oProxyCommand=...` 会被 ssh 当选项解析，等同任意命令执行）
+
+> 暂不做自动重连保活。断线依靠 `ServerAliveInterval` 让 ssh 进程自行退出，再用 `tunnel status` 查出来。
+
 ## 进程保活
 
 默认情况下，mihomo 内核在后台独立运行，但如果内核崩溃、被系统 kill（如内存不足）、或重启/重新登录后，代理就会失效且不会自动恢复。进程保活用 macOS 原生的 **launchd** 解决这个问题。
@@ -279,6 +333,7 @@ mihomo test --timeout=3000   # 长选项 + 等号
 ├── settings.json         # 用户设置（订阅列表等）
 ├── overwrite.yaml        # 覆写配置（主文件，可选）
 ├── overwrite.*.yaml      # 覆写配置（扩展文件，如 overwrite.dns.yaml）
+├── overwrite.tunnel-*.yaml   # 隧道覆写（首次由 tunnel add 生成，此后由你维护）
 ├── subscriptions/
 │   ├── cache.json        # 订阅动态缓存（更新时间、流量、到期时间等）
 │   └── <name>.yaml       # 订阅原始配置
@@ -286,8 +341,11 @@ mihomo test --timeout=3000   # 长选项 + 等号
 │   └── mihomo            # mihomo 内核二进制
 ├── logs/
 │   ├── mihomo.log        # 当前日志
-│   └── mihomo.YYYY-MM-DD_HH-MM-SS.log  # 归档日志
+│   ├── mihomo.YYYY-MM-DD_HH-MM-SS.log  # 归档日志
+│   └── tunnel-<name>.log # 隧道 ssh 输出（每次启动覆写）
 ├── data/                 # mihomo 运行数据（GeoIP 等，由内核自行管理）
+├── tunnel/               # 隧道运行态（stop 不清除，故不放在 runtime/）
+│   └── <name>.json       # PID、谁启动的、启动时间
 └── runtime/              # 运行时临时文件（stop 自动清除）
     ├── pid               # 进程 PID
     ├── config.yaml       # 运行时生成的配置

package/dist/index.js

@@ -3182,7 +3182,11 @@ var DIRS = {
   subscriptions: path.join(USER_DATA_DIR, "subscriptions"),
   logs: path.join(USER_DATA_DIR, "logs"),
   data: path.join(USER_DATA_DIR, "data"),
-  runtime: path.join(USER_DATA_DIR, "runtime")
+  runtime: path.join(USER_DATA_DIR, "runtime"),
+  // 隧道运行态。刻意独立于 runtime/：clearRuntime() 会在 stop() 成功路径 rmrf 整个
+  // runtime 目录，隧道状态放那里会被 `mihomo stop` 连同 config.yaml 一起抹掉，
+  // 于是「谁起的」标记丢失、手动起的隧道再也无法被识别
+  tunnel: path.join(USER_DATA_DIR, "tunnel")
 };
 var PATHS = {
   mihomoBinary: path.join(DIRS.kernel, "mihomo"),
@@ -3764,10 +3768,40 @@ function parseIntArg(args, short, long, defaultValue) {
   }
   return defaultValue;
 }
-var VALUE_FLAGS = /* @__PURE__ */ new Set(["-t", "--timeout", "-j", "--concurrency", "-r", "--rounds", "-n", "--lines", "-u", "--update-timeout"]);
+function parseStringArg(args, long, short) {
+  if (!args) return null;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === long || short !== void 0 && args[i] === short) {
+      if (i + 1 < args.length && !args[i + 1].startsWith("-")) {
+        return args[i + 1];
+      }
+      throw new CliError(`\u9009\u9879 ${args[i]} \u7F3A\u5C11\u503C`, { hint: [`\u4F8B\u5982: ${long} <\u503C>`] });
+    }
+    if (args[i].startsWith(`${long}=`)) {
+      const value = args[i].slice(long.length + 1);
+      if (!value) throw new CliError(`\u9009\u9879 ${long} \u7F3A\u5C11\u503C`, { hint: [`\u4F8B\u5982: ${long}=<\u503C>`] });
+      return value;
+    }
+  }
+  return null;
+}
+var VALUE_FLAGS = /* @__PURE__ */ new Set([
+  "-t",
+  "--timeout",
+  "-j",
+  "--concurrency",
+  "-r",
+  "--rounds",
+  "-n",
+  "--lines",
+  "-u",
+  "--update-timeout",
+  "--host",
+  "--port"
+]);
 function extractStartOptions(args) {
   if (!args) return [];
-  const BOOL_FLAGS = /* @__PURE__ */ new Set(["-s", "--no-update", "--no-clean"]);
+  const BOOL_FLAGS = /* @__PURE__ */ new Set(["-s", "--no-update", "--no-clean", "--no-tunnel"]);
   const out = [];
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
@@ -4232,12 +4266,13 @@ ${colors.cyan(colors.bold(`mihomo-cli v${VERSION}`))}`, "", "\u547D\u4EE4\u522B\
     "  mihomo start -s           # \u8DF3\u8FC7\u81EA\u52A8\u66F4\u65B0\u8BA2\u9605",
     "  mihomo start -u 30000     # \u81EA\u52A8\u66F4\u65B0\u8D85\u65F6 30 \u79D2 (\u9ED8\u8BA4 10s)",
     "  mihomo daemon on          # \u5F00\u542F\u4FDD\u6D3B\uFF08\u5F00\u673A\u81EA\u542F + \u5D29\u6E83\u91CD\u542F\uFF09",
+    "  mihomo tunnel add work --host m4 --port 1080   # \u52A0 ssh \u96A7\u9053\u51FA\u53E3",
     "  mihomo sub add <url>      # \u6DFB\u52A0\u8BA2\u9605 (sub \u662F subscription \u522B\u540D)",
     "  mihomo ui                 # \u6253\u5F00 Web UI",
     "",
     `${colors.cyan("\u5FEB\u6377\u547D\u4EE4:")}`,
     "  tun = start tun   use = sub use   on/off = ow on/off   open = dir open",
-    "  up = start   down = stop   upd/upgrade = update",
+    "  up = start   down = stop   upd/upgrade = update   ssh = tunnel",
     "",
     `${colors.cyan("\u6A21\u5F0F\u8BF4\u660E:")}`,
     "  mixed  HTTP + SOCKS5 \u6DF7\u5408\u7AEF\u53E3 (\u9ED8\u8BA4)",
@@ -5734,8 +5769,373 @@ function formatTestSummary(summary) {
   return `\u7ED3\u679C: ${colors.green(`${summary.alive} \u5B58\u6D3B`)} / ${colors.red(`${summary.dead} \u5931\u8D25`)} / ${summary.total} \u603B\u8BA1`;
 }
 
+// src/tunnel.ts
+import { spawn as spawn2 } from "child_process";
+import fs7 from "fs";
+import net from "net";
+import path6 from "path";
+var PORT_PROBE_TIMEOUT_MS = 300;
+var STOP_WAIT_ATTEMPTS = 20;
+var STOP_WAIT_INTERVAL = 100;
+var START_WAIT_ATTEMPTS = 40;
+var START_WAIT_INTERVAL = 500;
+function getReservedPorts() {
+  const reserved = /* @__PURE__ */ new Map();
+  const mixedPort = Number(BASE_CONFIG["mixed-port"]);
+  if (Number.isInteger(mixedPort)) reserved.set(mixedPort, "mihomo \u6DF7\u5408\u4EE3\u7406\u7AEF\u53E3");
+  reserved.set(CONTROLLER_PORT, "mihomo \u63A7\u5236\u5668\u7AEF\u53E3");
+  const testPort = Number(TEST_CONFIG["mixed-port"]);
+  if (Number.isInteger(testPort)) reserved.set(testPort, "\u6D4B\u901F\u5B9E\u4F8B\u4EE3\u7406\u7AEF\u53E3");
+  const testController = Number(TEST_CONTROLLER_ADDR.split(":")[1]);
+  if (Number.isInteger(testController)) reserved.set(testController, "\u6D4B\u901F\u5B9E\u4F8B\u63A7\u5236\u5668\u7AEF\u53E3");
+  return reserved;
+}
+function validateTunnelName(name) {
+  if (!name || !SAFE_NAME_RE.test(name)) {
+    throw new CliError(`\u96A7\u9053\u540D\u79F0\u65E0\u6548: "${name}"\uFF0C\u53EA\u5141\u8BB8\u5B57\u6BCD\u3001\u6570\u5B57\u3001\u4E0B\u5212\u7EBF\u3001\u77ED\u6A2A\u7EBF\u548C\u4E2D\u6587\uFF08\u6700\u957F 64 \u5B57\u7B26\uFF09`);
+  }
+}
+var SAFE_HOST_RE = /^[A-Za-z0-9][A-Za-z0-9._@-]*$/;
+function validateTunnelHost(host) {
+  if (!host) {
+    throw new CliError("\u7F3A\u5C11 --host", { hint: ["\u4F8B\u5982: mihomo tunnel add work --host m4 --port 1080"] });
+  }
+  if (host.startsWith("-")) {
+    throw new CliError(`\u4E3B\u673A\u540D\u65E0\u6548: "${host}"`, {
+      label: "\u53C2\u6570\u9519\u8BEF",
+      hint: ['\u4E3B\u673A\u540D\u4E0D\u80FD\u4EE5 "-" \u5F00\u5934\u2014\u2014\u5B83\u4F1A\u88AB ssh \u5F53\u4F5C\u9009\u9879\u89E3\u6790\uFF08\u5982 -oProxyCommand=... \u53EF\u6267\u884C\u4EFB\u610F\u547D\u4EE4\uFF09\u3002']
+    });
+  }
+  if (!SAFE_HOST_RE.test(host)) {
+    throw new CliError(`\u4E3B\u673A\u540D\u65E0\u6548: "${host}"\uFF0C\u53EA\u5141\u8BB8\u5B57\u6BCD\u3001\u6570\u5B57\u3001\u70B9\u3001\u4E0B\u5212\u7EBF\u3001\u77ED\u6A2A\u7EBF\u548C @`, {
+      label: "\u53C2\u6570\u9519\u8BEF",
+      hint: ["\u53EF\u7528 ssh \u522B\u540D\uFF08~/.ssh/config \u91CC\u7684 Host\uFF09\u6216 user@hostname\u3002"]
+    });
+  }
+}
+function validateTunnelPort(port, exclude) {
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new CliError(`\u7AEF\u53E3\u65E0\u6548: ${port}\uFF0C\u9700\u4E3A 1-65535 \u7684\u6574\u6570`);
+  }
+  const reservedLabel = getReservedPorts().get(port);
+  if (reservedLabel) {
+    throw new CliError(`\u7AEF\u53E3 ${port} \u5DF2\u88AB ${reservedLabel} \u5360\u7528`, {
+      label: "\u7AEF\u53E3\u51B2\u7A81",
+      hint: ["\u8BF7\u6362\u4E00\u4E2A\u7AEF\u53E3\uFF0C\u4F8B\u5982 1080\u3002"]
+    });
+  }
+  const conflict = getTunnels().find((t) => t.port === port && t.name !== exclude);
+  if (conflict) {
+    throw new CliError(`\u7AEF\u53E3 ${port} \u5DF2\u88AB\u96A7\u9053 "${conflict.name}" \u4F7F\u7528`, { label: "\u7AEF\u53E3\u51B2\u7A81" });
+  }
+}
+function getTunnels() {
+  const settings = readSettings();
+  const tunnels = settings.tunnels;
+  if (!Array.isArray(tunnels)) {
+    if (tunnels !== void 0) {
+      console.warn("\u8B66\u544A: settings.json \u7684 tunnels \u4E0D\u662F\u5217\u8868\uFF0C\u5DF2\u5FFD\u7565\uFF08\u53EF\u7528 mihomo tunnel add \u91CD\u65B0\u6DFB\u52A0\uFF09");
+    }
+    return [];
+  }
+  return tunnels.filter((t) => t != null && typeof t === "object" && typeof t.name === "string" && typeof t.host === "string" && Number.isInteger(t.port));
+}
+function findTunnel(name) {
+  return getTunnels().find((t) => t.name === name);
+}
+function addTunnel(config) {
+  validateTunnelName(config.name);
+  validateTunnelHost(config.host);
+  validateTunnelPort(config.port);
+  const tunnels = [...getTunnels()];
+  if (tunnels.some((t) => t.name === config.name)) {
+    throw new CliError(`\u96A7\u9053 "${config.name}" \u5DF2\u5B58\u5728\uFF0C\u8BF7\u6362\u4E2A\u540D\u79F0\uFF0C\u6216\u5148\u5220\u9664\uFF08mihomo tunnel rm ${config.name}\uFF09`);
+  }
+  tunnels.push(config);
+  writeSettings({ tunnels });
+}
+function removeTunnel(name) {
+  const tunnels = [...getTunnels()];
+  const idx = tunnels.findIndex((t) => t.name === name);
+  if (idx < 0) return false;
+  tunnels.splice(idx, 1);
+  writeSettings({ tunnels });
+  clearTunnelRuntime(name);
+  return true;
+}
+function getTunnelRuntimePath(name) {
+  validateTunnelName(name);
+  return path6.join(DIRS.tunnel, `${name}.json`);
+}
+function readTunnelRuntime(name) {
+  try {
+    const raw = fs7.readFileSync(getTunnelRuntimePath(name), "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    const r = parsed;
+    if (!Number.isInteger(r.pid) || r.pid <= 0) return null;
+    return {
+      pid: r.pid,
+      started_by: r.started_by === "manual" ? "manual" : "auto",
+      started_at: typeof r.started_at === "string" ? r.started_at : "",
+      port: Number.isInteger(r.port) ? r.port : 0
+    };
+  } catch {
+    return null;
+  }
+}
+function writeTunnelRuntime(name, runtime) {
+  ensureDirs();
+  atomicWriteFileSync(getTunnelRuntimePath(name), JSON.stringify(runtime, null, 2), { mode: 384 });
+}
+function clearTunnelRuntime(name) {
+  try {
+    fs7.rmSync(getTunnelRuntimePath(name), { force: true });
+  } catch {
+  }
+}
+function buildSshArgs(tunnel) {
+  return [
+    "-D",
+    `127.0.0.1:${tunnel.port}`,
+    "-N",
+    "-o",
+    "ExitOnForwardFailure=yes",
+    "-o",
+    "BatchMode=yes",
+    "-o",
+    "ServerAliveInterval=30",
+    "-o",
+    "ServerAliveCountMax=3",
+    "-o",
+    "ConnectTimeout=15",
+    tunnel.host
+  ];
+}
+function commandNeedle(port) {
+  return `-D 127.0.0.1:${port}`;
+}
+function getTunnelLogPath(name) {
+  validateTunnelName(name);
+  return path6.join(DIRS.logs, `tunnel-${name}.log`);
+}
+function isTunnelProcessAlive(pid, port) {
+  return isProcessRunning(pid) && isProcessCommandMatching(pid, commandNeedle(port));
+}
+function isPortListening(port, timeoutMs = PORT_PROBE_TIMEOUT_MS) {
+  return new Promise((resolve) => {
+    const socket = new net.Socket();
+    let settled = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolve(result);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.once("connect", () => finish(true));
+    socket.once("timeout", () => finish(false));
+    socket.once("error", () => finish(false));
+    socket.connect(port, "127.0.0.1");
+  });
+}
+async function getTunnelStatus(config) {
+  const runtime = readTunnelRuntime(config.name);
+  const alive = runtime !== null && isTunnelProcessAlive(runtime.pid, runtime.port || config.port);
+  if (!alive) {
+    return { config, state: "stopped", pid: null, started_by: null, started_at: null };
+  }
+  const listening = await isPortListening(config.port);
+  return {
+    config,
+    state: listening ? "running" : "dead-port",
+    pid: runtime.pid,
+    started_by: runtime.started_by,
+    started_at: runtime.started_at || null
+  };
+}
+async function getAllTunnelStatus() {
+  return Promise.all(getTunnels().map(getTunnelStatus));
+}
+async function startTunnel(name, options) {
+  const config = findTunnel(name);
+  if (!config) {
+    throw new CliError(`\u672A\u627E\u5230\u96A7\u9053 "${name}"`, { hint: ["\u67E5\u770B\u5168\u90E8\u96A7\u9053: mihomo tunnel"] });
+  }
+  const existing = readTunnelRuntime(name);
+  if (existing && isTunnelProcessAlive(existing.pid, existing.port || config.port)) {
+    if (options.startedBy === "manual" && existing.started_by === "auto") {
+      writeTunnelRuntime(name, { ...existing, started_by: "manual" });
+    }
+    return { alreadyRunning: true, pid: existing.pid };
+  }
+  if (existing) clearTunnelRuntime(name);
+  if (await isPortListening(config.port)) {
+    throw new CliError(`\u7AEF\u53E3 ${config.port} \u5DF2\u88AB\u5360\u7528`, {
+      label: "\u65E0\u6CD5\u542F\u52A8\u96A7\u9053",
+      hint: [`\u53EF\u80FD\u5DF2\u6709\u96A7\u9053\u6216\u5176\u4ED6\u7A0B\u5E8F\u5728\u76D1\u542C 127.0.0.1:${config.port}\u3002`, `\u67E5\u770B\u5360\u7528: lsof -nP -iTCP:${config.port} -sTCP:LISTEN`]
+    });
+  }
+  ensureDirs();
+  const logPath = getTunnelLogPath(name);
+  const logFd = fs7.openSync(logPath, "w");
+  const child = spawn2("ssh", buildSshArgs(config), {
+    detached: true,
+    stdio: ["ignore", logFd, logFd]
+  });
+  child.on("error", () => {
+  });
+  fs7.closeSync(logFd);
+  child.unref();
+  const pid = child.pid;
+  if (!pid) {
+    throw new CliError("\u65E0\u6CD5\u521B\u5EFA ssh \u8FDB\u7A0B", { label: "\u542F\u52A8\u96A7\u9053\u5931\u8D25", hint: ["\u8BF7\u786E\u8BA4\u5DF2\u5B89\u88C5 ssh \u5BA2\u6237\u7AEF\u3002"] });
+  }
+  writeTunnelRuntime(name, {
+    pid,
+    started_by: options.startedBy,
+    started_at: (/* @__PURE__ */ new Date()).toISOString(),
+    port: config.port
+  });
+  for (let i = 0; i < START_WAIT_ATTEMPTS; i++) {
+    if (!isProcessRunning(pid)) break;
+    if (await isPortListening(config.port)) {
+      return { alreadyRunning: false, pid };
+    }
+    await new Promise((resolve) => setTimeout(resolve, START_WAIT_INTERVAL));
+  }
+  clearTunnelRuntime(name);
+  if (isProcessRunning(pid)) {
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch {
+    }
+  }
+  throw new CliError("ssh \u96A7\u9053\u672A\u80FD\u5EFA\u7ACB", {
+    label: "\u542F\u52A8\u96A7\u9053\u5931\u8D25",
+    hint: [...readLogTail(logPath), `\u5B8C\u6574\u65E5\u5FD7: ${logPath}`]
+  });
+}
+function readLogTail(logPath, maxLines = 5) {
+  try {
+    const content = fs7.readFileSync(logPath, "utf8").trim();
+    if (!content) return [];
+    return content.split("\n").slice(-maxLines).map((line) => `  ${line.trim()}`);
+  } catch {
+    return [];
+  }
+}
+function stopTunnel(name) {
+  const config = findTunnel(name);
+  const runtime = readTunnelRuntime(name);
+  if (!runtime) {
+    clearTunnelRuntime(name);
+    return { notRunning: true, pid: null };
+  }
+  const port = runtime.port || config?.port || 0;
+  const { pid } = runtime;
+  if (!isTunnelProcessAlive(pid, port)) {
+    clearTunnelRuntime(name);
+    return { notRunning: true, pid: null };
+  }
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch {
+  }
+  for (let i = 0; i < STOP_WAIT_ATTEMPTS; i++) {
+    if (!isProcessRunning(pid)) break;
+    sleepSync(STOP_WAIT_INTERVAL);
+  }
+  if (isProcessRunning(pid) && isProcessCommandMatching(pid, commandNeedle(port))) {
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch {
+    }
+    for (let i = 0; i < STOP_WAIT_ATTEMPTS; i++) {
+      if (!isProcessRunning(pid)) break;
+      sleepSync(STOP_WAIT_INTERVAL);
+    }
+  }
+  clearTunnelRuntime(name);
+  return { notRunning: false, pid };
+}
+async function startAutoTunnels() {
+  const outcomes = [];
+  for (const tunnel of getTunnels()) {
+    if (!tunnel.auto) continue;
+    try {
+      const result = await startTunnel(tunnel.name, { startedBy: "auto" });
+      outcomes.push({ name: tunnel.name, ok: true, alreadyRunning: result.alreadyRunning });
+    } catch (e) {
+      outcomes.push({
+        name: tunnel.name,
+        ok: false,
+        error: e instanceof CliError ? e : new CliError(e.message)
+      });
+    }
+  }
+  return outcomes;
+}
+function stopAutoTunnels() {
+  const stopped = [];
+  for (const tunnel of getTunnels()) {
+    const runtime = readTunnelRuntime(tunnel.name);
+    if (runtime?.started_by !== "auto") continue;
+    const result = stopTunnel(tunnel.name);
+    if (!result.notRunning) stopped.push(tunnel.name);
+  }
+  return stopped;
+}
+function stopAllTunnels() {
+  const stopped = [];
+  for (const tunnel of getTunnels()) {
+    const result = stopTunnel(tunnel.name);
+    if (!result.notRunning) stopped.push(tunnel.name);
+  }
+  return stopped;
+}
+function getTunnelOverwritePath(name) {
+  validateTunnelName(name);
+  return path6.join(USER_DATA_DIR, `overwrite.tunnel-${name}.yaml`);
+}
+function renderTunnelOverwrite(tunnel) {
+  const proxyName = `Tunnel-${tunnel.name}-Host`;
+  const groupName = `Tunnel-${tunnel.name}`;
+  return `# mihomo-cli \u96A7\u9053\u8986\u5199\uFF08tunnel: ${tunnel.name}\uFF09
+# \u672C\u6587\u4EF6\u7531 mihomo-cli \u9996\u6B21\u521B\u5EFA\uFF0C\u4E4B\u540E\u5B8C\u5168\u7531\u4F60\u7EF4\u62A4\u2014\u2014CLI \u4E0D\u4F1A\u518D\u6539\u5199\u6216\u5220\u9664\u5B83\u3002
+#
+# ~ \u662F\u300C\u6309 name \u5C31\u5730\u5408\u5E76\u300D\u8BED\u4E49\uFF1A\u4E0E\u5176\u4ED6\u8986\u5199\u6587\u4EF6\u4E2D\u7684\u540C\u540D\u8282\u70B9/\u5206\u7EC4\u5408\u5E76\uFF0C
+# \u4E0D\u4F9D\u8D56\u6587\u4EF6\u52A0\u8F7D\u987A\u5E8F\uFF08+proxies \u5219\u4F9D\u8D56\u5B57\u6BCD\u5E8F\uFF0C\u4F1A\u88AB\u540E\u6765\u7684\u6587\u4EF6\u538B\u8FC7\u53BB\uFF09\u3002
+
+~proxies:
+  - name: ${proxyName}
+    type: socks5
+    server: 127.0.0.1
+    port: ${tunnel.port}
+
+~proxy-groups:
+  - name: ${groupName}
+    type: select
+    proxies:
+      - ${proxyName}
+      - DIRECT
+
+# \u53D6\u6D88\u6CE8\u91CA\u5E76\u586B\u5165\u9700\u8981\u8D70\u96A7\u9053\u7684\u5185\u7F51\u57DF\u540D/\u7F51\u6BB5\uFF08CLI \u65E0\u4ECE\u77E5\u9053\u4F60\u7684\u5185\u7F51\u5730\u5740\uFF09\uFF1A
+# +rules:
+#   - DOMAIN-SUFFIX,example.internal,${groupName}
+#   - IP-CIDR,10.0.0.0/8,${groupName}
+`;
+}
+function ensureTunnelOverwriteFile(tunnel) {
+  const filePath = getTunnelOverwritePath(tunnel.name);
+  if (fs7.existsSync(filePath)) return false;
+  ensureDirs();
+  atomicWriteFileSync(filePath, renderTunnelOverwrite(tunnel), { mode: 384 });
+  return true;
+}
+
 // src/commands/status.ts
-function printStatus() {
+async function printStatus() {
   const status = getStatus();
   const state = getRunningState();
   const info = getConfigInfo();
@@ -5802,6 +6202,17 @@ function printStatus() {
   if (isDaemonEnabled()) {
     console.log(`${colors.gray("\u4FDD\u6D3B: ")}${colors.green("\u5DF2\u542F\u7528")} ${colors.gray("(\u5F00\u673A\u81EA\u542F + \u5D29\u6E83\u91CD\u542F)")}`);
   }
+  const tunnels = getTunnels();
+  if (tunnels.length > 0) {
+    const statuses = await getAllTunnelStatus();
+    const parts = statuses.map((s) => {
+      const label = `${s.config.name}:${s.config.port}`;
+      if (s.state === "running") return colors.green(label);
+      if (s.state === "dead-port") return colors.yellow(`${label} \u5047\u6D3B`);
+      return colors.gray(label);
+    });
+    console.log(`${colors.gray("\u96A7\u9053: ")}${parts.join(", ")}`);
+  }
   console.log("");
 }
 
@@ -5811,23 +6222,51 @@ function handleStopResult(result) {
     throw new CliError(result.remaining.join(", "), { label: "\u90E8\u5206\u8FDB\u7A0B\u672A\u7EC8\u6B62", hint: "\u8BF7\u624B\u52A8\u8FD0\u884C: sudo pkill -9 mihomo" });
   }
 }
-async function cmdStop() {
+function stopAutoTunnelsWithLog() {
+  const stopped = stopAutoTunnels();
+  if (stopped.length > 0) {
+    console.log(`${colors.green("\u5DF2\u505C\u6B62\u96A7\u9053")}: ${stopped.join(", ")}`);
+  }
+}
+async function cmdStop(args) {
   if (isDaemonEnabled()) {
     console.log(colors.yellow("\u4FDD\u6D3B\u5DF2\u542F\u7528\uFF0C\u4EE3\u7406\u7531 launchd \u6258\u7BA1"));
     console.log("\u76F4\u63A5\u505C\u6B62\u4F1A\u88AB\u81EA\u52A8\u91CD\u65B0\u62C9\u8D77\uFF0C\u8BF7\u7528: mihomo daemon off");
     return;
   }
+  const skipTunnel = hasFlag(args, "--no-tunnel");
   const pids = getMihomoPids();
   if (pids.length === 0) {
     console.log(colors.yellow("\u4E0D\u5728\u8FD0\u884C"));
+    if (!skipTunnel) stopAutoTunnelsWithLog();
     return;
   }
   console.log(`\u505C\u6B62 ${pids.length} \u4E2A\u8FDB\u7A0B...`);
   handleStopResult(stop());
   console.log(colors.green("\u5DF2\u505C\u6B62\u8FDB\u7A0B"));
+  if (!skipTunnel) stopAutoTunnelsWithLog();
 }
 
 // src/commands/start.ts
+async function startAutoTunnelsWithWarning() {
+  const outcomes = await startAutoTunnels();
+  if (outcomes.length === 0) return;
+  const started = outcomes.filter((o) => o.ok && !o.alreadyRunning);
+  if (started.length > 0) {
+    console.log(`${colors.green("\u5DF2\u542F\u52A8\u96A7\u9053")}: ${started.map((o) => o.name).join(", ")}`);
+  }
+  for (const failed of outcomes.filter((o) => !o.ok)) {
+    console.log("");
+    console.log(colors.yellow(`\u8B66\u544A: \u96A7\u9053 "${failed.name}" \u542F\u52A8\u5931\u8D25`));
+    console.log(colors.gray(`  ${failed.error?.message ?? "\u672A\u77E5\u9519\u8BEF"}`));
+    for (const line of failed.error?.hint ?? []) {
+      if (line.trim()) console.log(colors.gray(line.startsWith("  ") ? line : `  ${line}`));
+    }
+    console.log(colors.gray("  \u5185\u7F51\u5206\u6D41\u89C4\u5219\u5C06\u4E0D\u53EF\u7528\uFF0C\u5176\u4F59\u6D41\u91CF\u6B63\u5E38"));
+    console.log(colors.gray(`  \u6392\u67E5: mihomo tunnel status ${failed.name}`));
+    console.log("");
+  }
+}
 async function cmdStart(args) {
   const modeToken = args[1] && !args[1].startsWith("-") ? args[1].toLowerCase() : void 0;
   if (modeToken !== void 0 && modeToken !== "tun" && modeToken !== "mixed") {
@@ -5846,6 +6285,7 @@ async function cmdStart(args) {
   const concurrency = parseIntArg(args, "-j", "--concurrency", DEFAULT_TEST_CONCURRENCY);
   const skipUpdate = hasFlag(args, "-s", "--no-update");
   const skipClean = hasFlag(args, "--no-clean");
+  const skipTunnel = hasFlag(args, "--no-tunnel");
   const updateTimeout = parseIntArg(args, "-u", "--update-timeout", DEFAULT_AUTO_UPDATE_TIMEOUT);
   const sub = requireActiveSubscription("\u6CA1\u6709\u8BA2\u9605\uFF0C\u8BF7\u5148\u6DFB\u52A0\u8BA2\u9605");
   if (!skipUpdate) {
@@ -5887,6 +6327,9 @@ async function cmdStart(args) {
     const lines = e.message.split("\n");
     throw new CliError(lines[0], { label: "\u542F\u52A8\u5931\u8D25", hint: lines.slice(1) });
   }
+  if (!skipTunnel) {
+    await startAutoTunnelsWithWarning();
+  }
   const cleanThreshold = isGithubUrl(sub.url) ? AUTO_CLEAN_THRESHOLD_GITHUB : AUTO_CLEAN_THRESHOLD;
   if (!skipClean && configInfo.proxies > cleanThreshold) {
     const cache = readSubscriptionCache();
@@ -5926,7 +6369,7 @@ async function cmdStart(args) {
       saveSubscriptionCache(sub.name, { last_auto_clean_at: (/* @__PURE__ */ new Date()).toISOString() });
     }
   }
-  printStatus();
+  await printStatus();
 }
 
 // src/commands/shared.ts
@@ -6133,8 +6576,8 @@ async function cmdDirectory(args) {
 
 // src/kernel.ts
 import { spawnSync as spawnSync4 } from "child_process";
-import fs7 from "fs";
-import path6 from "path";
+import fs8 from "fs";
+import path7 from "path";
 
 // node_modules/compare-versions/lib/esm/utils.js
 var semver = /^[v^~<>=]*?(\d+)(?:\.([x*]|\d+)(?:\.([x*]|\d+)(?:\.([x*]|\d+))?(?:-([\da-z\-]+(?:\.[\da-z\-]+)*))?(?:\+[\da-z\-]+(?:\.[\da-z\-]+)*)?)?)?$/i;
@@ -6260,10 +6703,10 @@ async function checkUpdate(mirror) {
 }
 function findBinaryInDir(dir, maxDepth = 4) {
   if (maxDepth <= 0) return null;
-  const files = fs7.readdirSync(dir);
+  const files = fs8.readdirSync(dir);
   for (const f of files) {
-    const fullPath = path6.join(dir, f);
-    const stat = fs7.statSync(fullPath);
+    const fullPath = path7.join(dir, f);
+    const stat = fs8.statSync(fullPath);
     if (stat.isDirectory()) {
       const found = findBinaryInDir(fullPath, maxDepth - 1);
       if (found) return found;
@@ -6289,7 +6732,7 @@ async function downloadKernel(progressCallback, mirror, releaseInfo) {
   \u5E73\u53F0: ${platform}, \u67B6\u6784: ${arch}${hint}`);
   }
   const downloadUrl = withMirror(asset.browser_download_url, mirror);
-  const tempPath = path6.join(DIRS.kernel, path6.basename(asset.name));
+  const tempPath = path7.join(DIRS.kernel, path7.basename(asset.name));
   const sizeMB = (asset.size / 1024 / 1024).toFixed(2);
   if (mirror && progressCallback) {
     progressCallback("\u63D0\u793A: \u7ECF\u7B2C\u4E09\u65B9\u955C\u50CF\u4E2D\u8F6C\u4E0B\u8F7D\uFF0C\u65E0\u6CD5\u9A8C\u8BC1\u6765\u6E90\u5B8C\u6574\u6027\uFF0C\u5EFA\u8BAE\u76F4\u8FDE\u6216\u81EA\u884C\u6821\u9A8C\u4EA7\u7269");
@@ -6310,12 +6753,12 @@ async function downloadKernel(progressCallback, mirror, releaseInfo) {
   }
   if (curlResult.status !== 0) {
     try {
-      fs7.unlinkSync(tempPath);
+      fs8.unlinkSync(tempPath);
     } catch {
     }
     throw new Error(`\u4E0B\u8F7D\u5931\u8D25 (curl \u9000\u51FA\u7801 ${curlResult.status})`);
   }
-  if (!fs7.existsSync(tempPath)) {
+  if (!fs8.existsSync(tempPath)) {
     throw new Error("\u4E0B\u8F7D\u5931\u8D25: \u6587\u4EF6\u672A\u751F\u6210");
   }
   if (progressCallback) {
@@ -6338,17 +6781,17 @@ async function downloadKernel(progressCallback, mirror, releaseInfo) {
       if (tarResult.error) throw tarResult.error;
       if (tarResult.status !== 0) throw new Error(`tar \u9000\u51FA\u7801 ${tarResult.status}`);
     } else if (tempPath.endsWith(".gz")) {
-      const baseName = path6.basename(tempPath, ".gz");
-      const outputPath = path6.join(extractPath, baseName);
+      const baseName = path7.basename(tempPath, ".gz");
+      const outputPath = path7.join(extractPath, baseName);
       const gzipResult = spawnSync4("gzip", ["-dc", tempPath], { maxBuffer: 256 * 1024 * 1024, timeout: 6e4 });
       if (gzipResult.error) throw gzipResult.error;
       if (gzipResult.status !== 0) throw new Error(`gzip \u9000\u51FA\u7801 ${gzipResult.status}`);
-      fs7.writeFileSync(outputPath, gzipResult.stdout, { mode: 493 });
+      fs8.writeFileSync(outputPath, gzipResult.stdout, { mode: 493 });
       extractedBinary = outputPath;
     }
   } catch (e) {
     try {
-      fs7.unlinkSync(tempPath);
+      fs8.unlinkSync(tempPath);
     } catch {
     }
     throw new Error(`\u89E3\u538B\u5931\u8D25: ${e.message}`);
@@ -6356,23 +6799,23 @@ async function downloadKernel(progressCallback, mirror, releaseInfo) {
   const foundBinary = extractedBinary || findBinaryInDir(extractPath);
   if (!foundBinary) {
     try {
-      fs7.unlinkSync(tempPath);
+      fs8.unlinkSync(tempPath);
     } catch {
     }
     throw new Error("\u89E3\u538B\u540E\u672A\u627E\u5230\u53EF\u6267\u884C\u6587\u4EF6");
   }
   const targetPath = PATHS.mihomoBinary;
   if (foundBinary !== targetPath) {
-    if (fs7.existsSync(targetPath)) {
-      fs7.chmodSync(targetPath, 493);
+    if (fs8.existsSync(targetPath)) {
+      fs8.chmodSync(targetPath, 493);
       try {
-        fs7.unlinkSync(targetPath);
+        fs8.unlinkSync(targetPath);
       } catch {
       }
     }
-    fs7.renameSync(foundBinary, targetPath);
+    fs8.renameSync(foundBinary, targetPath);
   }
-  fs7.chmodSync(targetPath, 493);
+  fs8.chmodSync(targetPath, 493);
   if (progressCallback) {
     progressCallback("\u6821\u9A8C\u5185\u6838...");
   }
@@ -6380,11 +6823,11 @@ async function downloadKernel(progressCallback, mirror, releaseInfo) {
   const checkOutput = `${check.stdout || ""}${check.stderr || ""}`.trim();
   if (check.error || check.status !== 0 || !/v?\d+\.\d+\.\d+/.test(checkOutput)) {
     try {
-      fs7.unlinkSync(targetPath);
+      fs8.unlinkSync(targetPath);
     } catch {
     }
     try {
-      fs7.unlinkSync(tempPath);
+      fs8.unlinkSync(tempPath);
     } catch {
     }
     throw new Error(`\u5185\u6838\u81EA\u68C0\u5931\u8D25\uFF08\u53EF\u80FD\u4E0B\u8F7D\u635F\u574F\u6216\u67B6\u6784\u4E0D\u5339\u914D\uFF09\uFF0C\u5DF2\u5220\u9664
@@ -6392,7 +6835,7 @@ async function downloadKernel(progressCallback, mirror, releaseInfo) {
   \u8F93\u51FA: ${checkOutput || "(\u7A7A)"}`);
   }
   try {
-    fs7.unlinkSync(tempPath);
+    fs8.unlinkSync(tempPath);
   } catch {
   }
   clearKernelVersionCache();
@@ -6527,7 +6970,7 @@ function cmdLogs(args) {
 }
 
 // src/commands/overwrite.ts
-import path7 from "path";
+import path8 from "path";
 function printOverwriteList() {
   const info = listOverwriteFile();
   const statusText = info.enabled ? colors.green("\u5DF2\u542F\u7528") : colors.yellow("\u5DF2\u7981\u7528");
@@ -6537,8 +6980,8 @@ function printOverwriteList() {
   if (info.files.length === 0) {
     console.log("\u6682\u65E0\u8986\u5199\u6587\u4EF6");
     console.log("");
-    console.log(`\u7528\u6CD5\u793A\u4F8B: \u521B\u5EFA\u6587\u4EF6 ${path7.join(info.dir, "overwrite.yaml")}`);
-    console.log(`         \u6216        ${path7.join(info.dir, "overwrite.dns.yaml")}`);
+    console.log(`\u7528\u6CD5\u793A\u4F8B: \u521B\u5EFA\u6587\u4EF6 ${path8.join(info.dir, "overwrite.yaml")}`);
+    console.log(`         \u6216        ${path8.join(info.dir, "overwrite.dns.yaml")}`);
     console.log("");
   } else {
     console.log(`${colors.cyan("\u8986\u5199\u6587\u4EF6")} (${info.files.length} \u4E2A\uFF0C\u6309\u987A\u5E8F\u52A0\u8F7D):`);
@@ -6602,7 +7045,7 @@ async function cmdOverwrite(args) {
 }
 
 // src/commands/reset.ts
-import fs8 from "fs";
+import fs9 from "fs";
 var RESET_TARGETS = [
   {
     id: "subs",
@@ -6635,6 +7078,21 @@ var RESET_TARGETS = [
     paths: () => [DIRS.runtime],
     needsStop: true
   },
+  {
+    // 隧道要在删 pid 文件之前先停进程（onBefore）：文件一删就再也找不到那些 ssh 进程，
+    // 它们会继续占着端口跑下去，且 CLI 无任何路径能停掉。
+    // **必须排在 settings 之前**：onAfter 会 writeSettings 重建 settings.json，
+    // 排在 settings 之后会让 `reset --full` 留下一个 {}（同 subs 的处理，见执行顺序注释）
+    id: "tunnel",
+    aliases: ["tunnel", "tunnels", "ssh"],
+    label: "\u96A7\u9053",
+    paths: () => [DIRS.tunnel],
+    needsStop: false,
+    onBefore: () => stopAllTunnels(),
+    // 同步清空 settings 里的隧道列表：只删运行态会留下「列表在但状态没了」的半重置状态。
+    // 覆写文件不动——那是用户维护的资产，由 overwrites target 负责
+    onAfter: () => writeSettings({ tunnels: void 0 })
+  },
   {
     id: "settings",
     aliases: ["setting", "settings", "config"],
@@ -6662,8 +7120,8 @@ var RESET_TARGETS = [
     label: "\u8986\u5199",
     paths: () => {
       const dir = USER_DATA_DIR;
-      if (!fs8.existsSync(dir)) return [];
-      return fs8.readdirSync(dir).filter(isOverwriteFilename).map((f) => `${dir}/${f}`);
+      if (!fs9.existsSync(dir)) return [];
+      return fs9.readdirSync(dir).filter(isOverwriteFilename).map((f) => `${dir}/${f}`);
     },
     needsStop: false
   },
@@ -6726,7 +7184,7 @@ async function cmdReset(args) {
     }
     targets = matched;
   } else {
-    targets = RESET_TARGETS.filter((t) => !["settings", "kernel", "overwrites", "daemon"].includes(t.id));
+    targets = RESET_TARGETS.filter((t) => !["settings", "kernel", "overwrites", "daemon", "tunnel"].includes(t.id));
   }
   for (const t of targets) {
     if (t.checkEmpty?.()) {
@@ -6786,8 +7244,9 @@ async function cmdReset(args) {
     }
   }
   for (const t of targets) {
+    t.onBefore?.();
     for (const p of t.paths()) {
-      if (fs8.existsSync(p)) {
+      if (fs9.existsSync(p)) {
         try {
           rmrf(p);
         } catch (e) {
@@ -6805,9 +7264,9 @@ async function cmdReset(args) {
 }
 
 // src/test-instance.ts
-import { spawn as spawn2 } from "child_process";
-import fs9 from "fs";
-import path8 from "path";
+import { spawn as spawn3 } from "child_process";
+import fs10 from "fs";
+import path9 from "path";
 function isProxyValid(proxy) {
   if (proxy === null || typeof proxy !== "object") return false;
   if (!proxy.name || !proxy.server || !proxy.port) return false;
@@ -6818,20 +7277,20 @@ function isProxyValid(proxy) {
   }
   return true;
 }
-var TEST_DIR = path8.join(USER_DATA_DIR, "test");
+var TEST_DIR = path9.join(USER_DATA_DIR, "test");
 var TEST_DIRS = {
-  data: path8.join(TEST_DIR, "data"),
-  runtime: path8.join(TEST_DIR, "runtime")
+  data: path9.join(TEST_DIR, "data"),
+  runtime: path9.join(TEST_DIR, "runtime")
 };
 var TEST_PATHS = {
-  configFile: path8.join(TEST_DIRS.runtime, "config.yaml"),
-  pidFile: path8.join(TEST_DIRS.runtime, "pid"),
-  logFile: path8.join(TEST_DIR, "test.log")
+  configFile: path9.join(TEST_DIRS.runtime, "config.yaml"),
+  pidFile: path9.join(TEST_DIRS.runtime, "pid"),
+  logFile: path9.join(TEST_DIR, "test.log")
 };
 var TEST_API = `http://${TEST_CONFIG["external-controller"]}`;
 function ensureTestDirs() {
   for (const dir of Object.values(TEST_DIRS)) {
-    fs9.mkdirSync(dir, { recursive: true, mode: 448 });
+    fs10.mkdirSync(dir, { recursive: true, mode: 448 });
   }
 }
 function cleanupTestDir() {
@@ -6869,25 +7328,25 @@ function buildTestConfig(subName) {
     rules: ["MATCH,PROXY"]
   };
   const content = dumpYaml(config);
-  fs9.writeFileSync(TEST_PATHS.configFile, content, { mode: 384 });
+  fs10.writeFileSync(TEST_PATHS.configFile, content, { mode: 384 });
 }
 async function startTestInstance() {
   const binary = PATHS.mihomoBinary;
-  if (!fs9.existsSync(binary)) throw new CliError('\u672A\u627E\u5230 mihomo \u5185\u6838\uFF0C\u8BF7\u5148\u8FD0\u884C "mihomo kernel" \u4E0B\u8F7D');
+  if (!fs10.existsSync(binary)) throw new CliError('\u672A\u627E\u5230 mihomo \u5185\u6838\uFF0C\u8BF7\u5148\u8FD0\u884C "mihomo kernel" \u4E0B\u8F7D');
   stopTestInstance();
-  const logFd = fs9.openSync(TEST_PATHS.logFile, "a");
-  const child = spawn2(binary, ["-d", TEST_DIRS.data, "-f", TEST_PATHS.configFile], {
+  const logFd = fs10.openSync(TEST_PATHS.logFile, "a");
+  const child = spawn3(binary, ["-d", TEST_DIRS.data, "-f", TEST_PATHS.configFile], {
     detached: true,
     stdio: ["ignore", logFd, logFd]
   });
   child.on("error", () => {
   });
-  fs9.closeSync(logFd);
+  fs10.closeSync(logFd);
   child.unref();
   const pid = child.pid;
   if (!pid) throw new CliError("\u6D4B\u8BD5\u5B9E\u4F8B\u542F\u52A8\u5931\u8D25\uFF1A\u65E0\u6CD5\u521B\u5EFA\u8FDB\u7A0B\uFF08\u5185\u6838\u4E8C\u8FDB\u5236\u53EF\u80FD\u4E0D\u53EF\u6267\u884C\uFF09");
   spawnedTestPid = pid;
-  fs9.writeFileSync(TEST_PATHS.pidFile, pid.toString(), { mode: 384 });
+  fs10.writeFileSync(TEST_PATHS.pidFile, pid.toString(), { mode: 384 });
   const client = createHttpClient({ timeout: 2e3 });
   let ready = false;
   for (let i = 0; i < 60; i++) {
@@ -6903,7 +7362,7 @@ async function startTestInstance() {
   if (!isProcessRunning(pid)) {
     let errorDetail = "";
     try {
-      errorDetail = fs9.readFileSync(TEST_PATHS.logFile, "utf8").slice(-1e3);
+      errorDetail = fs10.readFileSync(TEST_PATHS.logFile, "utf8").slice(-1e3);
     } catch {
     }
     throw new CliError(`\u6D4B\u8BD5\u5B9E\u4F8B\u542F\u52A8\u5931\u8D25${errorDetail ? `
@@ -6917,7 +7376,7 @@ var spawnedTestPid = null;
 function stopTestInstance() {
   let pid = null;
   try {
-    const fromFile = parseInt(fs9.readFileSync(TEST_PATHS.pidFile, "utf8").trim(), 10);
+    const fromFile = parseInt(fs10.readFileSync(TEST_PATHS.pidFile, "utf8").trim(), 10);
     if (fromFile > 0) pid = fromFile;
   } catch {
   }
@@ -6932,7 +7391,7 @@ function stopTestInstance() {
   }
   spawnedTestPid = null;
   try {
-    fs9.unlinkSync(TEST_PATHS.pidFile);
+    fs10.unlinkSync(TEST_PATHS.pidFile);
   } catch {
   }
 }
@@ -7342,6 +7801,224 @@ async function cmdClean(args) {
   }
 }
 
+// src/commands/tunnel.ts
+function formatState(status) {
+  switch (status.state) {
+    case "running":
+      return colors.green(`\u8FD0\u884C\u4E2D (PID ${status.pid})`);
+    case "dead-port":
+      return colors.yellow(`\u5047\u6D3B (PID ${status.pid}\uFF0C\u7AEF\u53E3 ${status.config.port} \u4E0D\u901A)`);
+    default:
+      return colors.yellow("\u672A\u8FD0\u884C");
+  }
+}
+function getTunnelNameArg(args) {
+  return getNonFlagArg(args, 2);
+}
+function requireTunnelNameArg(args, usage) {
+  const name = getTunnelNameArg(args);
+  if (!name) {
+    const tunnels = getTunnels();
+    throw new CliError("\u8BF7\u6307\u5B9A\u96A7\u9053\u540D\u79F0", {
+      hint: [usage, ...tunnels.length > 0 ? ["", "\u53EF\u7528\u96A7\u9053:", ...tunnels.map((t) => `  ${t.name}`)] : []]
+    });
+  }
+  return name;
+}
+async function printTunnelList() {
+  const tunnels = getTunnels();
+  console.log("");
+  if (tunnels.length === 0) {
+    console.log("\u6CA1\u6709\u914D\u7F6E\u96A7\u9053");
+    console.log("");
+    console.log("\u6DFB\u52A0\u96A7\u9053: mihomo tunnel add <\u540D\u5B57> --host <ssh\u4E3B\u673A> --port <\u7AEF\u53E3>");
+    console.log(colors.gray("  \u4F8B\u5982: mihomo tunnel add work --host m4 --port 1080"));
+    console.log(colors.gray("  \u96A7\u9053\u628A\u5185\u7F51\u51FA\u53E3\u66B4\u9732\u4E3A\u672C\u5730 SOCKS5\uFF0C\u914D\u5408\u8986\u5199\u6587\u4EF6\u5206\u6D41\u5185\u7F51\u57DF\u540D"));
+    console.log("");
+    return;
+  }
+  const statuses = await getAllTunnelStatus();
+  console.log(colors.cyan("\u96A7\u9053\u5217\u8868:"));
+  console.log("");
+  for (const status of statuses) {
+    const { config } = status;
+    const autoLabel = config.auto ? colors.gray(" [auto]") : "";
+    console.log(`  ${colors.bold(config.name)}${autoLabel}`);
+    console.log(`    ${colors.gray("\u51FA\u53E3: ")}${config.host} \u2192 127.0.0.1:${config.port}`);
+    console.log(`    ${colors.gray("\u72B6\u6001: ")}${formatState(status)}`);
+    if (status.started_by) {
+      console.log(`    ${colors.gray("\u6765\u6E90: ")}${status.started_by === "auto" ? "\u968F start \u62C9\u8D77" : "\u624B\u52A8\u542F\u52A8"}`);
+    }
+  }
+  console.log("");
+  console.log("\u542F\u52A8: mihomo tunnel up [\u540D\u5B57]      \u505C\u6B62: mihomo tunnel down [\u540D\u5B57]");
+  console.log("\u72B6\u6001: mihomo tunnel status         \u5220\u9664: mihomo tunnel rm <\u540D\u5B57>");
+  console.log("");
+}
+async function tunnelAdd(args) {
+  const name = requireTunnelNameArg(args, "\u7528\u6CD5: mihomo tunnel add <\u540D\u5B57> --host <ssh\u4E3B\u673A> --port <\u7AEF\u53E3> [--no-auto]");
+  const host = parseStringArg(args, "--host");
+  if (!host) {
+    throw new CliError("\u7F3A\u5C11 --host", {
+      hint: ["\u7528\u6CD5: mihomo tunnel add <\u540D\u5B57> --host <ssh\u4E3B\u673A> --port <\u7AEF\u53E3>", "", "\u4E3B\u673A\u53EF\u7528 ~/.ssh/config \u91CC\u7684\u522B\u540D\uFF0C\u4F8B\u5982 --host m4"]
+    });
+  }
+  const portRaw = parseStringArg(args, "--port");
+  if (!portRaw) {
+    throw new CliError("\u7F3A\u5C11 --port", { hint: ["\u7528\u6CD5: mihomo tunnel add <\u540D\u5B57> --host <ssh\u4E3B\u673A> --port <\u7AEF\u53E3>"] });
+  }
+  if (!/^\d+$/.test(portRaw.trim())) {
+    throw new CliError(`\u7AEF\u53E3\u65E0\u6548: "${portRaw}"\uFF0C\u9700\u4E3A 1-65535 \u7684\u6574\u6570`);
+  }
+  const port = Number(portRaw.trim());
+  const auto = !hasFlag(args, "--no-auto");
+  const config = { name, host, port, auto };
+  addTunnel(config);
+  const created = ensureTunnelOverwriteFile(config);
+  const overwritePath = getTunnelOverwritePath(name);
+  console.log(`${colors.green("\u5DF2\u6DFB\u52A0\u96A7\u9053")} ${name} \xB7 ${host} \u2192 127.0.0.1:${port}${auto ? " \xB7 auto" : ""}`);
+  console.log("");
+  if (created) {
+    console.log(`\u5DF2\u751F\u6210\u8986\u5199\u6A21\u677F: ${overwritePath}`);
+    console.log(colors.gray("  \u6A21\u677F\u53EA\u5EFA\u597D socks5 \u8282\u70B9\u4E0E\u5206\u7EC4\uFF0C\u5206\u6D41\u89C4\u5219\u9700\u4F60\u586B\u5199\uFF08CLI \u65E0\u4ECE\u77E5\u9053\u4F60\u7684\u5185\u7F51\u57DF\u540D\uFF09"));
+    console.log(colors.gray("  \u7F16\u8F91\u540E\u6267\u884C mihomo start \u751F\u6548"));
+  } else {
+    console.log(`\u8986\u5199\u6587\u4EF6\u5DF2\u5B58\u5728\uFF0C\u672A\u6539\u52A8: ${overwritePath}`);
+  }
+  console.log("");
+  console.log(`\u542F\u52A8\u96A7\u9053: mihomo tunnel up ${name}`);
+  if (created) {
+    await restartToApply(args);
+  }
+}
+async function tunnelUp(args) {
+  const name = getTunnelNameArg(args);
+  const targets = name ? [resolveTunnel(name)] : getTunnels();
+  if (targets.length === 0) {
+    throw new CliError("\u6CA1\u6709\u914D\u7F6E\u96A7\u9053", { hint: ["\u6DFB\u52A0\u96A7\u9053: mihomo tunnel add <\u540D\u5B57> --host <ssh\u4E3B\u673A> --port <\u7AEF\u53E3>"] });
+  }
+  for (const config of targets) {
+    if (ensureTunnelOverwriteFile(config)) {
+      console.log(colors.gray(`\u5DF2\u8865\u5EFA\u8986\u5199\u6A21\u677F: ${getTunnelOverwritePath(config.name)}`));
+    }
+    const result = await startTunnel(config.name, { startedBy: "manual" });
+    if (result.alreadyRunning) {
+      console.log(`${colors.gray("\u5DF2\u5728\u8FD0\u884C")} ${config.name} (PID ${result.pid})`);
+    } else {
+      console.log(`${colors.green("\u5DF2\u542F\u52A8\u96A7\u9053")} ${config.name} \xB7 ${config.host} \u2192 127.0.0.1:${config.port} (PID ${result.pid})`);
+    }
+  }
+}
+function tunnelDown(args) {
+  const name = getTunnelNameArg(args);
+  const targets = name ? [resolveTunnel(name)] : getTunnels();
+  if (targets.length === 0) {
+    throw new CliError("\u6CA1\u6709\u914D\u7F6E\u96A7\u9053");
+  }
+  let stopped = 0;
+  for (const config of targets) {
+    const result = stopTunnel(config.name);
+    if (result.notRunning) {
+      console.log(`${colors.yellow("\u4E0D\u5728\u8FD0\u884C")} ${config.name}`);
+    } else {
+      console.log(`${colors.green("\u5DF2\u505C\u6B62\u96A7\u9053")} ${config.name} (PID ${result.pid})`);
+      stopped++;
+    }
+  }
+  if (stopped > 0) {
+    console.log("");
+    console.log(colors.gray("\u6CE8\u610F: \u8986\u5199\u6587\u4EF6\u4ECD\u5728\uFF0C\u914D\u7F6E\u91CC\u7684\u96A7\u9053\u8282\u70B9\u73B0\u5728\u6307\u5411\u672A\u76D1\u542C\u7684\u7AEF\u53E3"));
+  }
+}
+async function tunnelStatus(args) {
+  const name = getTunnelNameArg(args);
+  if (!name) {
+    await printTunnelList();
+    return;
+  }
+  const config = resolveTunnel(name);
+  const status = await getTunnelStatus(config);
+  console.log("");
+  console.log(`${colors.gray("\u96A7\u9053: ")}${config.name}${config.auto ? colors.gray(" [auto]") : ""}`);
+  console.log(`${colors.gray("\u51FA\u53E3: ")}${config.host} \u2192 127.0.0.1:${config.port}`);
+  console.log(`${colors.gray("\u72B6\u6001: ")}${formatState(status)}`);
+  if (status.started_by) {
+    console.log(`${colors.gray("\u6765\u6E90: ")}${status.started_by === "auto" ? "\u968F start \u62C9\u8D77" : "\u624B\u52A8\u542F\u52A8"}`);
+  }
+  console.log("");
+  if (status.state === "dead-port") {
+    console.log(colors.yellow("ssh \u8FDB\u7A0B\u8FD8\u5728\uFF0C\u4F46\u7AEF\u53E3\u6CA1\u6709\u76D1\u542C\u2014\u2014\u5185\u7F51\u5206\u6D41\u5F53\u524D\u4E0D\u53EF\u7528"));
+    console.log(`\u91CD\u542F\u96A7\u9053: mihomo tunnel down ${config.name} && mihomo tunnel up ${config.name}`);
+    console.log(colors.gray(`  \u65E5\u5FD7: ${getTunnelLogPath(config.name)}`));
+    console.log("");
+  } else if (status.state === "stopped") {
+    console.log(`\u542F\u52A8\u96A7\u9053: mihomo tunnel up ${config.name}`);
+    console.log("");
+  }
+}
+async function tunnelRemove(args) {
+  const name = requireTunnelNameArg(args, "\u7528\u6CD5: mihomo tunnel rm <\u540D\u5B57> [-y]");
+  const config = resolveTunnel(name);
+  const skipConfirm = hasFlag(args, "-y", "--yes");
+  if (!skipConfirm) {
+    if (!process.stdin.isTTY) {
+      throw new CliError("\u5220\u9664\u96A7\u9053\u9700\u8981\u786E\u8BA4", {
+        label: "\u5DF2\u53D6\u6D88",
+        hint: [`\u8DF3\u8FC7\u786E\u8BA4: mihomo tunnel rm ${config.name} -y`]
+      });
+    }
+    const confirmed = await confirmPrompt(`\u786E\u8BA4\u5220\u9664\u96A7\u9053 "${config.name}"?`);
+    if (!confirmed) {
+      console.log("\u5DF2\u53D6\u6D88");
+      return;
+    }
+  }
+  stopTunnel(config.name);
+  removeTunnel(config.name);
+  console.log(`${colors.green("\u5DF2\u5220\u9664\u96A7\u9053")} ${config.name}`);
+  console.log("");
+  console.log(`\u8986\u5199\u6587\u4EF6\u672A\u5220\u9664: ${getTunnelOverwritePath(config.name)}`);
+  console.log(colors.gray("  \u5B83\u4ECD\u4F1A\u5411\u914D\u7F6E\u6CE8\u5165\u6307\u5411\u8BE5\u7AEF\u53E3\u7684\u8282\u70B9\uFF0C\u5982\u4E0D\u518D\u9700\u8981\u8BF7\u81EA\u884C\u5220\u9664"));
+}
+function resolveTunnel(name) {
+  const config = findTunnel(name);
+  if (!config) {
+    const tunnels = getTunnels();
+    const suggestion = suggestSimilar(
+      name,
+      tunnels.map((t) => t.name)
+    );
+    throw new CliError(`\u672A\u627E\u5230\u96A7\u9053 "${name}"`, {
+      hint: [
+        ...suggestion.length > 0 ? [`\u662F\u5426\u60F3\u8F93\u5165: ${suggestion.join(" / ")}?`] : [],
+        ...tunnels.length > 0 ? ["", "\u53EF\u7528\u96A7\u9053:", ...tunnels.map((t) => `  ${t.name}`)] : ["", "\u6DFB\u52A0\u96A7\u9053: mihomo tunnel add <\u540D\u5B57> --host <ssh\u4E3B\u673A> --port <\u7AEF\u53E3>"]
+      ]
+    });
+  }
+  return config;
+}
+var SUBCOMMANDS5 = [
+  { name: "list", handler: printTunnelList },
+  { name: "add", handler: tunnelAdd },
+  { name: "up", aliases: ["start"], handler: tunnelUp },
+  { name: "down", aliases: ["stop"], handler: tunnelDown },
+  { name: "status", handler: tunnelStatus },
+  { name: "remove", aliases: ["rm", "delete"], handler: tunnelRemove }
+];
+async function cmdTunnel(args) {
+  await dispatchSubcommand(args, SUBCOMMANDS5, {
+    // 无 action → 列表；未知 action → 报错（不静默回落，否则 `tunnel upp` 会看似成功）
+    fallback: printTunnelList,
+    onUnknown: (action) => {
+      const names = SUBCOMMANDS5.flatMap((c) => [c.name, ...c.aliases ?? []]);
+      const suggestion = suggestSimilar(action, names);
+      throw new CliError(`\u672A\u77E5\u7684 tunnel \u5B50\u547D\u4EE4: ${action}`, {
+        hint: [...suggestion.length > 0 ? [`\u662F\u5426\u60F3\u8F93\u5165: ${suggestion.join(" / ")}?`] : [], "", "\u53EF\u7528\u5B50\u547D\u4EE4: list, add, up, down, status, rm"]
+      });
+    }
+  });
+}
+
 // src/commands/ui.ts
 function cmdUI(args) {
   const uiName = args[1] || "zash";
@@ -7366,7 +8043,7 @@ function cmdUI(args) {
 }
 
 // src/commands/update.ts
-import { execFile, spawn as spawn3 } from "child_process";
+import { execFile, spawn as spawn4 } from "child_process";
 import { promisify } from "util";
 var execFileAsync = promisify(execFile);
 var NPM_VIEW_TIMEOUT_MS = 15e3;
@@ -7397,7 +8074,7 @@ async function cmdUpdate() {
   console.log("\u6B63\u5728\u66F4\u65B0 mihomo-cli...");
   console.log("");
   await new Promise((resolve, reject) => {
-    const npm = spawn3("npm", ["install", "-g", PKG_NAME], { stdio: "inherit" });
+    const npm = spawn4("npm", ["install", "-g", PKG_NAME], { stdio: "inherit" });
     npm.on("close", (code) => {
       if (code === 0) {
         resolve();
@@ -7573,6 +8250,20 @@ var COMMANDS = [
     group: "system",
     usage: ["daemon on|off               \u5F00\u673A\u81EA\u542F + \u5D29\u6E83\u91CD\u542F\uFF08\u4EC5 Mixed\uFF0C\u9700\u7BA1\u7406\u5458\u5BC6\u7801\uFF09", "daemon status               \u67E5\u770B\u4FDD\u6D3B\u72B6\u6001"]
   },
+  {
+    // 别名不能用 tun——已被 TUN 模式快捷命令占用（注册表重复 token 会在模块加载期直接抛错）
+    name: "tunnel",
+    aliases: ["ssh", "tunnels"],
+    handler: cmdTunnel,
+    group: "system",
+    usage: [
+      "tunnel                      \u5217\u51FA ssh \u96A7\u9053\uFF08\u522B\u540D ssh\uFF09",
+      "tunnel add <\u540D\u5B57> --host <\u4E3B\u673A> --port <\u7AEF\u53E3> [--no-auto]",
+      "tunnel up|down [\u540D\u5B57]       \u542F\u52A8/\u505C\u6B62\u96A7\u9053\uFF08\u65E0\u53C2\u5373\u5168\u90E8\uFF09",
+      "tunnel status [\u540D\u5B57]        \u67E5\u770B\u96A7\u9053\u72B6\u6001\uFF08\u771F\u5B9E\u63A2\u6D4B\u7AEF\u53E3\uFF09",
+      "tunnel rm <\u540D\u5B57> [-y]       \u5220\u9664\u96A7\u9053\uFF08\u4E0D\u5220\u8986\u5199\u6587\u4EF6\uFF09"
+    ]
+  },
   {
     name: "update",
     aliases: ["upd", "upgrade"],
@@ -7678,7 +8369,7 @@ async function main() {
   if (args.length === 0) {
     assertSupportedPlatform("status");
     ensureDirs();
-    printStatus();
+    await printStatus();
     printShortHelp();
     return;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mihomo-cli",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "type": "module",
   "description": "A terminal-based mihomo (Clash.Meta) client for macOS",
   "bin": {