mihomo-cli 1.1.0 → 1.2.1

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## [1.2.1] - 2026-04-05
+
+### 优化
+
+- 简化帮助中的命令列表，统一一行格式
+
+### 文档
+
+- README 添加覆写配置和自动重启说明
+- CLAUDE.md 精简和完善，增加发布检查清单
+
+---
+
+## [1.2.0] - 2026-04-05
+
+### 新增功能
+
+#### 配置变更自动重启
+- **sub use 自动重启**：切换默认订阅后，如果 mihomo 正在运行则自动重启
+- **ow on/off 自动重启**：启用/禁用覆写配置后，如果 mihomo 正在运行则自动重启
+- **状态检查**：操作前检查是否已是目标状态，避免重复操作
+
+### 重构
+
+#### 命名规范统一
+- **函数重命名**：统一使用全称单数
+  - `findSubsFuzzy` → `findSubscriptionFuzzy`
+  - `pickSingleSub` → `pickSingleSubscription`
+  - `printSubList` → `printSubscriptionList`
+  - `cmdSub` → `cmdSubscription`
+  - `cmdDirs` → `cmdDirectory`
+  - `DIR_TARGETS` → `DIRECTORY_TARGETS`
+- **帮助文档统一**：
+  - 示例统一使用 `mihomo` 而非 `mihomo-cli`
+  - 命令列表使用全称单数 `directory` 而非 `directories`
+  - 提示语中的命令示例添加 `mihomo` 前缀
+
+### 修复
+
+- 修复缺失的 `path` 模块导入
+- 统一引号风格（命令示例使用双引号）
+
 ## [1.1.0] - 2026-04-05
 
 ### 新增功能

package/README.md

@@ -7,6 +7,8 @@
 - 🌐 **订阅管理** - 添加/更新订阅，支持流量统计和到期时间显示
 - 🔄 **自动更新** - 启动时自动检查并更新过期订阅
 - 🔍 **模糊匹配** - `sub use` / `sub web` 支持订阅名称模糊匹配
+- 📝 **覆写配置** - 在订阅基础上进行自定义覆写，支持强制覆盖、数组合并
+- 🔄 **智能重启** - `sub use` 切换订阅、`ow on/off` 切换覆写后自动重启
 - 🚀 **进程管理** - 启动/停止/切换模式，自动清理残留进程
 - 🔄 **双模式支持** - Mixed 模式和 TUN 透明代理模式
 - 📊 **状态监控** - 查看运行状态、内存占用
@@ -94,16 +96,25 @@ mihomo ui yacd     # YACD
 | `mihomo sub add <url> [name]` | 添加订阅 |
 | `mihomo sub update` | 更新所有订阅 |
 | `mihomo sub update <name>` | 更新指定订阅（支持模糊匹配） |
-| `mihomo sub use <name>` | 设置默认订阅（支持模糊匹配） |
+| `mihomo sub use <name>` | 设置默认订阅（支持模糊匹配，自动重启） |
 | `mihomo sub web [name]` | 打开订阅页面（无参打开默认） |
 
+### 覆写配置
+
+| 命令 | 说明 |
+|------|------|
+| `mihomo ow` / `mihomo ow list` | 查看覆写配置状态和文件列表 |
+| `mihomo ow on` | 启用覆写配置（自动重启） |
+| `mihomo ow off` | 禁用覆写配置（自动重启） |
+
 ### 其他命令
 
 | 命令 | 说明 |
 |------|------|
 | `mihomo kernel [镜像\|--no-mirror]` | 更新内核 |
 | `mihomo ui [zash\|dash\|yacd]` | 打开 Web UI |
-| `mihomo dirs` | 显示数据目录位置 |
+| `mihomo dir` | 显示数据目录位置 |
+| `mihomo dir open [target]` | 打开指定目录（`root`, `subs`, `logs`, `overwrites` 等） |
 | `mihomo reset [--full]` | 重置用户数据 (--full 同时删除内核) |
 | `mihomo version` | 显示版本信息 |
 | `mihomo help` | 显示帮助信息 |
@@ -165,6 +176,7 @@ mihomo kernel --no-mirror
 ├── subscriptions/
 │   ├── cache.json        # 订阅动态缓存（更新时间、流量、到期时间等）
 │   └── <name>.yaml       # 订阅原始配置
+├── overwrites/           # 覆写配置（按文件名排序加载）
 ├── core/
 │   └── mihomo            # mihomo 内核二进制
 ├── logs/
@@ -178,6 +190,44 @@ mihomo kernel --no-mirror
 
 可通过环境变量 `MIHOMO_CLI_DIR` 自定义数据目录位置。
 
+## 覆写配置
+
+覆写配置允许你在订阅配置基础上进行自定义修改，而不会影响订阅本身。
+
+### 使用方法
+
+1. 在 `~/.mihomo-cli/overwrites/` 目录下创建 `.yaml` 或 `.yml` 文件
+2. 文件按**文件名顺序**加载，后面的文件会覆盖前面的配置
+3. 使用 `mihomo ow on` 启用覆写配置（会自动重启）
+
+### 特殊语法
+
+覆写配置支持以下特殊操作符：
+
+| 语法 | 作用 | 示例 |
+|------|------|------|
+| `key!` | 强制覆盖整个对象（不深度合并） | `dns!`: { ... } |
+| `+key` | 数组前置插入 | `+proxies`: [...] |
+| `key+` | 数组追加 | `rules+`: [...] |
+| `<+key>` | 键名以 `+` 开头时转义 | `<+.google.cn>`: ... |
+
+### 示例
+
+```yaml
+# ~/.mihomo-cli/overwrites/01-custom.yaml
+
+# 强制覆盖 dns 配置
+dns!:
+  enable: true
+  enhanced-mode: fake-ip
+  nameserver:
+    - 223.5.5.5
+
+# 追加规则
+rules+:
+  - "DOMAIN-SUFFIX,example.com,DIRECT"
+```
+
 ## Web UI
 
 内置三个常用 Web UI：

package/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+const path = require('path');
 const { spawn } = require('child_process');
 
 const config = require('./src/config');
@@ -60,7 +61,7 @@ function printShortHelp() {
     '  subscription update      更新订阅\n' +
     '  subscription use <name>  切换默认订阅\n' +
     '  overwrite [on|off]       覆写配置（别名 ow）\n' +
-    '  directories              数据目录（别名 dir）\n' +
+    '  directory                数据目录（别名 dir）\n' +
     '  kernel                   更新内核\n' +
     '  reset                    重置配置\n' +
     '  version                  版本信息\n');
@@ -72,7 +73,7 @@ function printHelp() {
     '命令别名: mihomo, mmc, mh\n' +
     '\n' +
     '用法:\n' +
-    '  mihomo-cli <命令> [选项]\n' +
+    '  mihomo <命令> [选项]\n' +
     '\n' +
     '控制:\n' +
     '  start [tun|mixed]            启动/切换代理 (默认 mixed)\n' +
@@ -85,14 +86,11 @@ function printHelp() {
     '  logs [编号] [-n N] [-o]      日志列表（0=当前，1+=归档）\n' +
     '\n' +
     '订阅:\n' +
-    '  subscription add <url> [name]  添加订阅（别名 sub）\n' +
-    '  subscription update [name]     更新订阅（无参更新所有）\n' +
-    '  subscription use <name>        设置默认订阅\n' +
-    '  subscription web [name]        打开订阅页面\n' +
+    '  subscription [add|update|use|web]  订阅管理（别名 sub）\n' +
     '\n' +
     '配置:\n' +
     '  overwrite [on|off]           覆写配置（别名 ow）\n' +
-    '  directories [open]           数据目录（别名 dir）\n' +
+    '  directory [open]             数据目录（别名 dir）\n' +
     '\n' +
     '系统:\n' +
     '  kernel [镜像|--no-mirror]    更新内核\n' +
@@ -101,10 +99,10 @@ function printHelp() {
     '  version, -v                  显示版本\n' +
     '\n' +
     '示例:\n' +
-    '  mihomo-cli start              # 启动/重启 Mixed 模式\n' +
-    '  mihomo-cli start tun          # 切换到 TUN 透明代理模式\n' +
-    '  mihomo-cli sub add <url>      # 添加订阅 (sub 是 subscription 别名)\n' +
-    '  mihomo-cli ui                 # 打开 Web UI\n' +
+    '  mihomo start              # 启动/重启 Mixed 模式\n' +
+    '  mihomo start tun          # 切换到 TUN 透明代理模式\n' +
+    '  mihomo sub add <url>      # 添加订阅 (sub 是 subscription 别名)\n' +
+    '  mihomo ui                 # 打开 Web UI\n' +
     '\n' +
     '模式说明:\n' +
     '  mixed  HTTP + SOCKS5 混合端口 (默认)\n' +
@@ -189,7 +187,7 @@ function getActiveSubscription() {
   return subs[0];
 }
 
-function findSubsFuzzy(subs, pattern) {
+function findSubscriptionFuzzy(subs, pattern) {
   const lowerPattern = pattern.toLowerCase();
   let exact = [];
   let prefix = [];
@@ -211,7 +209,7 @@ function findSubsFuzzy(subs, pattern) {
   return includes;
 }
 
-function pickSingleSub(subs, pattern, actionName) {
+function pickSingleSubscription(subs, pattern, actionName) {
   if (subs.length === 0) {
     console.error('错误: 未找到匹配 "' + pattern + '" 的订阅');
     process.exit(1);
@@ -297,7 +295,7 @@ function viewLogWithTail(logPath, options) {
 
 async function cmdStart(args) {
   if (!config.hasKernel()) {
-    console.error('错误: 未找到内核，请运行 \'mihomo-cli kernel\'');
+    console.error('错误: 未找到内核，请运行 "mihomo kernel"');
     process.exit(1);
   }
 
@@ -422,7 +420,7 @@ function cmdLogs(args) {
 
     if (!logPath) {
       console.error('错误: 未找到日志 "' + targetName + '"');
-      console.log('使用 "mihomo-cli logs" 查看可用日志列表');
+      console.log('使用 "mihomo logs" 查看可用日志列表');
       process.exit(1);
     }
 
@@ -461,16 +459,16 @@ function cmdLogs(args) {
     console.log(' ' + num + '. ' + name);
     console.log('    时间: ' + time + '  大小: ' + size);
     if (!log.isCurrent) {
-      console.log('    查看: mihomo-cli logs ' + idx + '  或  mihomo-cli logs -o ' + idx);
+      console.log('    查看: mihomo logs ' + idx + '  或  mihomo logs -o ' + idx);
     }
     console.log('');
   });
 
   console.log('用法:');
-  console.log('  mihomo-cli logs 0          # 查看当前日志 (最后 100 行)');
-  console.log('  mihomo-cli logs 1          # 查看第 1 个归档日志');
-  console.log('  mihomo-cli logs 1 -n 200   # 查看 200 行');
-  console.log('  mihomo-cli logs 1 -o        # 用系统默认程序打开');
+  console.log('  mihomo logs 0          # 查看当前日志 (最后 100 行)');
+  console.log('  mihomo logs 1          # 查看第 1 个归档日志');
+  console.log('  mihomo logs 1 -n 200   # 查看 200 行');
+  console.log('  mihomo logs 1 -o        # 用系统默认程序打开');
   console.log('');
 }
 
@@ -549,10 +547,10 @@ async function cmdKernel(args) {
   });
 
   console.log('\n用法:');
-  console.log('  mihomo-cli kernel                    # 使用默认镜像');
-  console.log('  mihomo-cli kernel hk.gh-proxy.org    # 使用指定镜像');
-  console.log('  mihomo-cli kernel --mirror hk.gh-proxy.org');
-  console.log('  mihomo-cli kernel --no-mirror         # 直连，不使用镜像');
+  console.log('  mihomo kernel                    # 使用默认镜像');
+  console.log('  mihomo kernel hk.gh-proxy.org    # 使用指定镜像');
+  console.log('  mihomo kernel --mirror hk.gh-proxy.org');
+  console.log('  mihomo kernel --no-mirror         # 直连，不使用镜像');
   console.log('');
 
   try {
@@ -576,7 +574,7 @@ async function cmdKernel(args) {
   }
 }
 
-async function printSubList() {
+async function printSubscriptionList() {
   const updateResult = await subscription.autoUpdateStaleSubscriptions();
   if (updateResult.total > 0) {
     console.log('');
@@ -586,7 +584,7 @@ async function printSubList() {
   if (subs.length === 0) {
     console.log('没有订阅');
     console.log('');
-    console.log('添加订阅: mihomo-cli sub add <url> [name]');
+    console.log('添加订阅: mihomo sub add <url> [name]');
     console.log('');
     return;
   }
@@ -620,17 +618,17 @@ async function printSubList() {
     }
   });
   console.log('');
-  console.log('切换默认: sub use <name>');
-  console.log('更新订阅: sub update [name]');
-  console.log('打开页面: sub web [name]');
+  console.log('切换默认: mihomo sub use <name>');
+  console.log('更新订阅: mihomo sub update [name]');
+  console.log('打开页面: mihomo sub web [name]');
   console.log('');
 }
 
-async function cmdSub(args) {
+async function cmdSubscription(args) {
   const action = args[1];
 
   if (!action || action === 'list') {
-    await printSubList();
+    await printSubscriptionList();
     return;
   }
 
@@ -656,7 +654,7 @@ async function cmdSub(args) {
       process.exit(1);
     }
     console.log('');
-    await printSubList();
+    await printSubscriptionList();
     return;
   }
 
@@ -686,12 +684,12 @@ async function cmdSub(args) {
       });
       if (ok === 0) process.exit(1);
       console.log('');
-      await printSubList();
+      await printSubscriptionList();
       return;
     }
 
-    const matches = findSubsFuzzy(subs, name);
-    const target = pickSingleSub(matches, name, '更新');
+    const matches = findSubscriptionFuzzy(subs, name);
+    const target = pickSingleSubscription(matches, name, '更新');
 
     console.log('更新订阅: ' + target.name);
     try {
@@ -705,7 +703,7 @@ async function cmdSub(args) {
       process.exit(1);
     }
     console.log('');
-    await printSubList();
+    await printSubscriptionList();
     return;
   }
 
@@ -722,8 +720,24 @@ async function cmdSub(args) {
       process.exit(1);
     }
 
-    const matches = findSubsFuzzy(subs, name);
-    const target = pickSingleSub(matches, name, '切换');
+    const matches = findSubscriptionFuzzy(subs, name);
+    const target = pickSingleSubscription(matches, name, '切换');
+
+    // 检查是否已是当前默认订阅
+    const currentDefault = getActiveSubscription();
+    const isAlreadyDefault = currentDefault && currentDefault.name === target.name;
+
+    if (isAlreadyDefault) {
+      console.log('"' + target.name + '" 已是当前默认订阅');
+      console.log('');
+      await printSubscriptionList();
+      return;
+    }
+
+    // 检查当前运行状态和模式
+    const status = processMgr.getStatus();
+    const cfgInfo = config.getConfigInfo();
+    const currentMode = cfgInfo && cfgInfo.tun ? 'tun' : 'mixed';
 
     const success = config.setDefaultSubscription(target.name);
     if (success) {
@@ -732,8 +746,16 @@ async function cmdSub(args) {
       console.error('错误: 未找到订阅 "' + name + '"');
       process.exit(1);
     }
+
+    // 如果正在运行，自动重启
+    if (status.running) {
+      console.log('');
+      await cmdStart(['start', currentMode]);
+      return;
+    }
+
     console.log('');
-    await printSubList();
+    await printSubscriptionList();
     return;
   }
 
@@ -748,8 +770,8 @@ async function cmdSub(args) {
 
     let target;
     if (name) {
-      const matches = findSubsFuzzy(subs, name);
-      target = pickSingleSub(matches, name, '打开');
+      const matches = findSubscriptionFuzzy(subs, name);
+      target = pickSingleSubscription(matches, name, '打开');
     } else {
       target = subs[0];
     }
@@ -782,7 +804,7 @@ async function cmdSub(args) {
   }
 
   console.error('错误: 未知的订阅命令');
-  console.log('用法: mihomo-cli sub [list|add|update|use|web]');
+  console.log('用法: mihomo sub [list|add|update|use|web]');
   process.exit(1);
 }
 
@@ -829,7 +851,6 @@ async function cmdReset(args) {
 
 function printOverwriteList() {
   const info = overwrite.listOverwriteFiles();
-  console.log('');
   console.log('状态: ' + (info.enabled ? '已启用' : '已禁用'));
   console.log('目录: ' + info.dir);
   console.log('');
@@ -850,38 +871,87 @@ function printOverwriteList() {
     });
     console.log('');
   }
-  console.log('启用覆写: ow on');
-  console.log('禁用覆写: ow off');
+  console.log('启用覆写: mihomo ow on');
+  console.log('禁用覆写: mihomo ow off');
   console.log('');
 }
 
-function cmdOverwrite(args) {
+async function cmdOverwrite(args) {
   const action = args && args[1];
 
+  // 检查当前运行状态和模式
+  const status = processMgr.getStatus();
+  const cfgInfo = config.getConfigInfo();
+  const currentMode = cfgInfo && cfgInfo.tun ? 'tun' : 'mixed';
+
   if (action === 'on' || action === 'enable') {
+    // 如果已经启用，提示后直接返回
+    if (overwrite.isOverwriteEnabled()) {
+      console.log('覆写配置已是启用状态');
+      console.log('');
+      printOverwriteList();
+      return;
+    }
+
     overwrite.setOverwriteEnabled(true);
     console.log('已启用覆写配置');
+
+    // 如果正在运行，自动重启
+    if (status.running) {
+      console.log('');
+      await cmdStart(['start', currentMode]);
+      return;
+    }
+
     console.log('');
     printOverwriteList();
     return;
   }
 
   if (action === 'off' || action === 'disable') {
+    // 如果已经禁用，提示后直接返回
+    if (!overwrite.isOverwriteEnabled()) {
+      console.log('覆写配置已是禁用状态');
+      console.log('');
+      printOverwriteList();
+      return;
+    }
+
     overwrite.setOverwriteEnabled(false);
     console.log('已禁用覆写配置');
+
+    // 如果正在运行，自动重启
+    if (status.running) {
+      console.log('');
+      await cmdStart(['start', currentMode]);
+      return;
+    }
+
     console.log('');
     printOverwriteList();
     return;
   }
 
   // 无参数、list、ls 都显示文件列表
+  console.log('');
   printOverwriteList();
 }
 
-function cmdDirs(args) {
+// 目录目标映射（精确匹配）
+const DIRECTORY_TARGETS = {
+  'root': { path: null, label: '根目录' },
+  'subs': { path: config.DIRS.subscriptions, label: '订阅目录' },
+  'logs': { path: config.DIRS.logs, label: '日志目录' },
+  'data': { path: config.DIRS.data, label: 'mihomo 数据目录' },
+  'runtime': { path: config.DIRS.runtime, label: '运行时目录' },
+  'overwrites': { path: config.DIRS.overwrites, label: '覆写目录' },
+  'settings': { path: config.PATHS.settingsFile, label: '设置文件' },
+  'kernel': { path: config.DIRS.core, label: '内核目录' },
+};
+
+function cmdDirectory(args) {
   const action = args && args[1];
 
-  // dirs open [root|subs|logs|data|runtime|config|kernel]
   if (action === 'open') {
     const target = args[2];
 
@@ -890,23 +960,10 @@ function cmdDirs(args) {
       return;
     }
 
-    const dirMap = {
-      'subs': { path: config.DIRS.subscriptions, label: '订阅目录' },
-      'subscriptions': { path: config.DIRS.subscriptions, label: '订阅目录' },
-      'logs': { path: config.DIRS.logs, label: '日志目录' },
-      'data': { path: config.DIRS.data, label: 'mihomo 数据目录' },
-      'runtime': { path: config.DIRS.runtime, label: '运行时目录' },
-    };
-
-    const fileMap = {
-      'config': { path: config.PATHS.settingsFile, label: '设置文件' },
-      'settings': { path: config.PATHS.settingsFile, label: '设置文件' },
-      'kernel': { path: config.DIRS.core, label: '内核目录' },
-    };
-
-    const targetInfo = dirMap[target] || fileMap[target];
+    const targetInfo = DIRECTORY_TARGETS[target.toLowerCase()];
     if (targetInfo) {
-      openDir(targetInfo.path, targetInfo.label);
+      const path = targetInfo.path || config.USER_DATA_DIR;
+      openDir(path, targetInfo.label);
       return;
     }
 
@@ -918,7 +975,8 @@ function cmdDirs(args) {
     console.log('  logs          日志目录');
     console.log('  data          mihomo 数据目录');
     console.log('  runtime       运行时目录');
-    console.log('  config        设置文件 (settings.json)');
+    console.log('  overwrites    覆写目录');
+    console.log('  settings      设置文件 (settings.json)');
     console.log('  kernel        内核目录');
     console.log('');
     process.exit(1);
@@ -941,10 +999,13 @@ function cmdDirs(args) {
   console.log('    - cache.db, Geo*.dat 等 (mihomo 自行管理)');
   console.log('');
   console.log('打开目录:');
-  console.log('  mihomo-cli dirs open               打开根目录');
-  console.log('  mihomo-cli dirs open subscriptions 打开订阅目录');
-  console.log('  mihomo-cli dirs open logs          打开日志目录');
-  console.log('  mihomo-cli dirs open config        打开设置文件');
+  console.log('  mihomo dir open                打开根目录');
+  console.log('  mihomo dir open subs           打开订阅目录');
+  console.log('  mihomo dir open logs           打开日志目录');
+  console.log('  mihomo dir open runtime        打开运行时目录');
+  console.log('  mihomo dir open overwrites     打开覆写目录');
+  console.log('  mihomo dir open settings       打开设置文件');
+  console.log('  mihomo dir open kernel         打开内核目录');
   console.log('');
   console.log('环境变量:');
   console.log('  MIHOMO_CLI_DIR: 自定义根目录位置');
@@ -998,24 +1059,24 @@ async function main() {
     case 'sub':
     case 'subscription':
     case 'subscriptions':
-      await cmdSub(args);
+      await cmdSubscription(args);
       break;
     case 'dir':
     case 'dirs':
     case 'directory':
     case 'directories':
-      cmdDirs(args);
+      cmdDirectory(args);
       break;
     case 'reset':
       await cmdReset(args);
       break;
-    case 'overwrite':
     case 'ow':
-      cmdOverwrite(args);
+    case 'overwrite':
+      await cmdOverwrite(args);
       break;
     default:
       console.error('未知命令: ' + cmd);
-      console.error('使用 "mihomo-cli help" 查看帮助');
+      console.error('使用 "mihomo help" 查看帮助');
       process.exit(1);
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mihomo-cli",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "A terminal-based mihomo (Clash.Meta) client for macOS",
   "main": "index.js",
   "bin": {

package/src/overwrite.js

@@ -247,12 +247,8 @@ function listOverwriteFiles() {
 }
 
 module.exports = {
-  parseOverrideKey,
-  deepMergeWithOverrides,
-  getOverwritesDir,
   isOverwriteEnabled,
   setOverwriteEnabled,
-  loadOverwriteFiles,
   applyOverwrites,
   listOverwriteFiles,
 };