@lancewu602/mihomo-dash 0.0.0-stage → 0.6.1

package/server/src/shared/system-proxy.js

@@ -0,0 +1,375 @@
+/**
+ * 系统代理开关：macOS 的系统代理（networksetup）与 Linux GNOME 的 gsettings 代理。
+ *
+ * 与内核是**两层独立的东西**，这决定了「停止代理」的正确操作：
+ * - 内核的 `mode`（direct / rule）决定流量走不走节点；
+ * - 系统代理决定「系统会不会把流量交给 127.0.0.1:<port>」。
+ *
+ * 所以关掉系统代理 = 系统直连（内核可以继续跑，端口照旧监听），这才是通常想说的「停止代理」；
+ * 想连进程一起停用：侧栏底部的「停止内核」。
+ *
+ * 实现约定：
+ * - 所有外部命令都是**固定 argv 直接 spawn，不经过 shell**；网络服务名从系统枚举里挑、
+ *   host / port 过白名单校验，绝不把外部字符串拼进命令。
+ * - macOS 只动「当前活动网络服务」（按默认路由的接口反查），不扫全部服务；实测普通用户
+ *   即可写这些设置，不需要 sudo。
+ * - `run` 可注入：测试用桩函数断言真实 argv，不会碰本机设置。
+ */
+import { defaultRun } from './exec.js';
+
+export { defaultRun };
+/** macOS 三个协议在 networksetup / scutil 里的名字对应关系 */
+const MAC_PROTOCOLS = [
+  {
+    key: 'http',
+    label: 'HTTP',
+    getter: '-getwebproxy',
+    setter: '-setwebproxy',
+    stateFlag: '-setwebproxystate',
+    enable: 'HTTPEnable',
+    host: 'HTTPProxy',
+    port: 'HTTPPort',
+  },
+  {
+    key: 'https',
+    label: 'HTTPS',
+    getter: '-getsecurewebproxy',
+    setter: '-setsecurewebproxy',
+    stateFlag: '-setsecurewebproxystate',
+    enable: 'HTTPSEnable',
+    host: 'HTTPSProxy',
+    port: 'HTTPSPort',
+  },
+  {
+    key: 'socks',
+    label: 'SOCKS',
+    getter: '-getsocksfirewallproxy',
+    setter: '-setsocksfirewallproxy',
+    stateFlag: '-setsocksfirewallproxystate',
+    enable: 'SOCKSEnable',
+    host: 'SOCKSProxy',
+    port: 'SOCKSPort',
+  },
+];
+const GNOME_PROXY = 'org.gnome.system.proxy';
+
+/**
+ * 开启系统代理时**固定补上**的绕过项：回环 + 私网 + link-local + 多播 + 本地域名。
+ * 这些交给代理没意义，反而会把本机 / 局域网服务绕坏。
+ * 语义是「只增不减」：与系统里已有的条目求并集，**绝不删**手工加的那些。
+ * `note` 只用于面板展示（得看每项到底绕过什么）。
+ * @type {{ value: string, note: string }[]}
+ */
+export const BYPASS_DEFAULTS = [
+  { value: 'localhost', note: '本机名' },
+  { value: '127.0.0.1', note: 'IPv4 回环' },
+  { value: '::1', note: 'IPv6 回环' },
+  { value: '10.0.0.0/8', note: 'IPv4 私网（10.x）' },
+  { value: '172.16.0.0/12', note: 'IPv4 私网（172.16–172.31）' },
+  { value: '192.168.0.0/16', note: 'IPv4 私网（192.168.x）' },
+  { value: '169.254.0.0/16', note: 'IPv4 link-local（DHCP 失败时的自分配地址）' },
+  { value: 'fe80::/10', note: 'IPv6 link-local' },
+  { value: 'fc00::/7', note: 'IPv6 私网（ULA）' },
+  { value: '224.0.0.0/4', note: 'IPv4 多播' },
+  { value: '*.local', note: 'Bonjour / mDNS 本地域名' },
+  { value: '*.lan', note: '常见内网域名后缀' },
+  { value: '*.home.arpa', note: '家庭网保留后缀（RFC 8375）' },
+  { value: '*.localdomain', note: '常见内网域名后缀' },
+  { value: '*.internal', note: '常见内网域名后缀' },
+];
+
+/** 固定项的字面量列表（mergeBypass 用；与 BYPASS_DEFAULTS 同序） */
+const BYPASS_VALUES = BYPASS_DEFAULTS.map((d) => d.value);
+
+/**
+ * 现有绕过列表 + {@link BYPASS_DEFAULTS}：顺序保留，缺失的追加在后面（大小写不敏感去重）。
+ * @param {string[]} [current]
+ * @returns {{ list: string[], added: string[] }}
+ */
+export function mergeBypass(current = []) {
+  const list = current.map((s) => String(s));
+  const have = new Set(list.map((s) => s.trim().toLowerCase()));
+  const added = BYPASS_VALUES.filter((d) => !have.has(d.toLowerCase()));
+  return { list: [...list, ...added], added };
+}
+
+/** 地址/端口白名单校验：只有这些字符能出现在 argv 里 */
+export function assertHostPort(host, port) {
+  const h = String(host ?? '').trim();
+  if (!/^[0-9A-Za-z.\-:[\]]+$/.test(h)) throw new Error(`代理地址不合法：${host}`);
+  const p = Number(port);
+  if (!Number.isInteger(p) || p < 1 || p > 65535) throw new Error(`代理端口不合法：${port}`);
+  return { host: h, port: p };
+}
+
+/** `scutil --proxy` 输出解析（含 ExceptionsList 数组） */
+export function parseScutilProxy(text) {
+  const scalars = {};
+  const bypass = [];
+  let inExceptions = false;
+  for (const raw of String(text).split('\n')) {
+    const line = raw.trim();
+    if (!line) continue;
+    if (/^ExceptionsList\s*:/.test(line)) {
+      inExceptions = true;
+      continue;
+    }
+    if (inExceptions) {
+      if (line === '}') {
+        inExceptions = false;
+        continue;
+      }
+      const item = line.match(/^\d+\s*:\s*(.+)$/);
+      if (item) bypass.push(item[1].trim());
+      continue;
+    }
+    const kv = line.match(/^([A-Za-z]\w*)\s*:\s*(.*)$/);
+    if (kv) scalars[kv[1]] = kv[2].trim();
+  }
+  const isOn = (v) => v === '1' || v === 'true' || v === 'yes';
+  const protocols = {};
+  for (const p of MAC_PROTOCOLS) {
+    protocols[p.key] = {
+      enabled: isOn(scalars[p.enable]),
+      host: scalars[p.host] || '',
+      port: Number.parseInt(scalars[p.port] || '0', 10) || 0,
+    };
+  }
+  return {
+    protocols,
+    autoProxy: {
+      enabled: isOn(scalars.ProxyAutoConfigEnable),
+      url: scalars.ProxyAutoConfigURLString || null,
+    },
+    autoDiscovery: isOn(scalars.ProxyAutoDiscoveryEnable),
+    bypass,
+  };
+}
+
+/** `networksetup -listnetworkserviceorder` → [{ name, device }]，顺序即优先级 */
+export function parseServiceOrder(text) {
+  const lines = String(text).split('\n');
+  const services = [];
+  for (let i = 0; i < lines.length; i++) {
+    const head = lines[i].match(/^\(\d+\)\s+(.+?)\s*$/);
+    if (!head) continue;
+    const device = lines[i + 1]?.match(/Device:\s*([^)]+)\)/);
+    services.push({ name: head[1], device: device ? device[1].trim() : null });
+  }
+  return services;
+}
+
+/** `route -n get default` → 默认路由的接口名（如 en0） */
+export function parseDefaultInterface(text) {
+  const m = String(text).match(/^\s*interface:\s*(\S+)/m);
+  return m ? m[1] : null;
+}
+
+/** macOS 实现：读 scutil --proxy，写 networksetup（只动活动服务） */
+function macOSProxy(run) {
+  const net = (args) => run('networksetup', args);
+  const readState = async () => parseScutilProxy((await run('scutil', ['--proxy'])).stdout);
+
+  /** 当前活动网络服务：默认路由接口对应的那个，退而求其次用顺序表里第一个启用的 */
+  async function activeService() {
+    const order = parseServiceOrder((await net(['-listnetworkserviceorder'])).stdout);
+    const all = (await net(['-listallnetworkservices'])).stdout;
+    const enabled = new Set(
+      all
+        .split('\n')
+        .slice(1)
+        .map((l) => l.trim())
+        .filter((l) => l && !l.startsWith('*')),
+    );
+    const usable = order.filter((s) => enabled.has(s.name));
+    const iface = parseDefaultInterface((await run('route', ['-n', 'get', 'default'])).stdout);
+    const hit = usable.find((s) => s.device === iface) || usable[0];
+    return { name: hit?.name || null, device: hit?.device || null };
+  }
+
+  async function read() {
+    const state = await readState();
+    const svc = await activeService();
+    return {
+      supported: true,
+      platform: 'darwin',
+      service: svc.name,
+      device: svc.device,
+      enabled:
+        state.protocols.http.enabled ||
+        state.protocols.https.enabled ||
+        state.protocols.socks.enabled,
+      protocols: state.protocols,
+      autoProxy: state.autoProxy,
+      autoDiscovery: state.autoDiscovery,
+      bypass: state.bypass,
+      hint: null,
+    };
+  }
+
+  async function setEnabled(enabled, target = {}) {
+    const svc = await activeService();
+    if (!svc.name) throw new Error('没找到可用的网络服务（networksetup 没列出任何服务？）');
+    const before = await readState();
+    const applied = [];
+    /** @type {string[]} 本次补进绕过列表的项 */
+    let bypassAdded = [];
+
+    if (!enabled) {
+      for (const p of MAC_PROTOCOLS) {
+        if (!before.protocols[p.key].enabled) continue;
+        const r = await net([p.stateFlag, svc.name, 'off']);
+        if (!r.ok) throw new Error(`关闭 ${p.label} 代理失败：${r.stderr || r.status}`);
+        applied.push(`关闭 ${p.label}`);
+      }
+      if (before.autoProxy.enabled) {
+        await net(['-setautoproxystate', svc.name, 'off']);
+        applied.push('关闭 PAC（自动代理配置）');
+      }
+      if (before.autoDiscovery) {
+        await net(['-setproxyautodiscovery', svc.name, 'off']);
+        applied.push('关闭自动代理发现');
+      }
+    } else {
+      const { host, port } = assertHostPort(target.host || '127.0.0.1', target.port ?? 7890);
+      for (const p of MAC_PROTOCOLS) {
+        // -set*proxy 一次就把地址与端口写好并启用（不带认证参数即无认证）
+        const r = await net([p.setter, svc.name, host, String(port)]);
+        if (!r.ok) throw new Error(`设置 ${p.label} 代理失败：${r.stderr || r.status}`);
+        applied.push(`${p.label} → ${host}:${port}`);
+      }
+      // 固定绕过项：补上缺的（已有的一个不动，所以只写回「并集」）
+      const { list, added } = mergeBypass(before.bypass);
+      if (added.length) {
+        const r = await net(['-setproxybypassdomains', svc.name, ...list]);
+        if (!r.ok) throw new Error(`设置绕过列表失败：${r.stderr || r.status}`);
+        applied.push(`绕过列表 +${added.length} 项`);
+      }
+      bypassAdded = added;
+    }
+    return { service: svc.name, applied, bypassAdded, state: await read() };
+  }
+
+  return { read, setEnabled };
+}
+
+/** GNOME 实现：gsettings（用户级，不需要 root） */
+function linuxProxy(run) {
+  const gs = (args) => run('gsettings', args);
+  const unquote = (v) =>
+    String(v ?? '')
+      .trim()
+      .replace(/^'(.*)'$/, '$1');
+
+  /** @returns {Promise<{ ok: boolean, value: string, stderr?: string }>} */
+  async function get(key) {
+    const r = await gs(['get', GNOME_PROXY, ...key.split(' ')]);
+    return { ok: r.ok, value: unquote(r.stdout), stderr: r.stderr };
+  }
+
+  async function read() {
+    const mode = await get('mode');
+    if (!mode.ok) {
+      return {
+        supported: false,
+        platform: 'linux',
+        hint: '没找到 gsettings（非 GNOME 桌面）：请用桌面环境自己的代理开关，或手工设 http_proxy 环境变量',
+      };
+    }
+    const protocols = {};
+    for (const key of ['http', 'https', 'socks']) {
+      const host = await get(`${key} host`);
+      const port = await get(`${key} port`);
+      protocols[key] = {
+        enabled: mode.value === 'manual',
+        host: host.value,
+        port: Number.parseInt(port.value, 10) || 0,
+      };
+    }
+    const ignore = await get('ignore-hosts');
+    return {
+      supported: true,
+      platform: 'linux',
+      service: 'GNOME',
+      device: null,
+      enabled: mode.value === 'manual' || mode.value === 'auto',
+      mode: mode.value,
+      protocols,
+      autoProxy: { enabled: mode.value === 'auto', url: null },
+      autoDiscovery: false,
+      bypass: (ignore.value.match(/'([^']*)'/g) || []).map(unquote),
+      hint: null,
+    };
+  }
+
+  async function setEnabled(enabled, target = {}) {
+    const state = await read();
+    if (!state.supported) throw new Error(state.hint);
+    const applied = [];
+    /** @type {string[]} 本次补进绕过列表的项 */
+    let bypassAdded = [];
+    if (!enabled) {
+      if (state.enabled) {
+        const r = await gs(['set', GNOME_PROXY, 'mode', 'none']);
+        if (!r.ok) throw new Error(`关闭系统代理失败：${r.stderr || r.status}`);
+        applied.push('mode → none');
+      }
+    } else {
+      const { host, port } = assertHostPort(target.host || '127.0.0.1', target.port ?? 7890);
+      for (const key of ['http', 'https', 'socks']) {
+        await gs(['set', `${GNOME_PROXY}.${key}`, 'host', host]);
+        await gs(['set', `${GNOME_PROXY}.${key}`, 'port', String(port)]);
+      }
+      // 固定绕过项（ignore-hosts）：补上缺的，已有的不动
+      const { list, added } = mergeBypass(state.bypass);
+      if (added.length) {
+        const r = await gs(['set', GNOME_PROXY, 'ignore-hosts', gvariantList(list)]);
+        if (!r.ok) throw new Error(`设置绕过列表失败：${r.stderr || r.status}`);
+        applied.push(`绕过列表 +${added.length} 项`);
+        bypassAdded = added;
+      }
+      const r = await gs(['set', GNOME_PROXY, 'mode', 'manual']);
+      if (!r.ok) throw new Error(`开启系统代理失败：${r.stderr || r.status}`);
+      applied.push(`mode → manual（http/https/socks → ${host}:${port}）`);
+    }
+    return { service: state.service, applied, bypassAdded, state: await read() };
+  }
+
+  return { read, setEnabled };
+}
+
+/** 不支持的平台：读返回提示，写直接拒 */
+function unsupportedProxy(platform) {
+  const hint =
+    platform === 'win32'
+      ? 'Windows 没有统一的系统代理命令行接口：请用「Internet 选项 → 连接 → 局域网设置」，或用代理客户端自己的开关'
+      : `暂不支持在 ${platform} 上改系统代理`;
+  return {
+    async read() {
+      return { supported: false, platform, hint };
+    },
+    async setEnabled() {
+      throw new Error(hint);
+    },
+  };
+}
+
+/** 逗号拼接前对单个值加引号并转义（gsettings 的 GVariant 字符串） */
+const gvariantItem = (v) => `'${String(v).replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+
+/** 字符串数组 → gsettings 吃的 GVariant：`['a', 'b']` */
+function gvariantList(items) {
+  return `[${items.map(gvariantItem).join(', ')}]`;
+}
+
+/**
+ * @param {{ run?: typeof defaultRun, platform?: string }} [options]
+ * @returns {{ read: () => Promise<Record<string, any>>, setEnabled: (enabled: boolean, target?: { host?: string, port?: number }) => Promise<{ service: string|null, applied: string[], bypassAdded: string[], state: Record<string, any> }> }}
+ */
+export function createSystemProxy(options = {}) {
+  const run = options.run || defaultRun;
+  const platform = options.platform || process.platform;
+  if (platform === 'darwin') return macOSProxy(run);
+  if (platform === 'linux') return linuxProxy(run);
+  return unsupportedProxy(platform);
+}

package/server/src/shared/text.js

@@ -0,0 +1,11 @@
+/** 终端文本对齐：中文按 2 列宽算、纯 ASCII 按 1 列（`doctor` 与 `status` 共用）。 */
+
+/** 显示宽度：CJK / 全角按 2 列，其余按 1 列 */
+export function displayWidth(text) {
+  let width = 0;
+  for (const ch of text) width += ch >= '\u1100' && ch <= '\uffe6' ? 2 : 1;
+  return width;
+}
+
+/** 右侧补空格到指定显示宽度（超长原样返回，不截断） */
+export const pad = (text, width) => text + ' '.repeat(Math.max(0, width - displayWidth(text)));

package/server/tests/cli-service.test.js

@@ -0,0 +1,153 @@
+/**
+ * `mihomo-dash service` 的 CLI 层测试：只验参数分发与输出，
+ * 平台实现（launchd / systemd）由 service.test.js 覆盖，这里用桩 manager 注入。
+ */
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { cmdService } from '../src/cli/service.js';
+
+/** 记录输出、替掉 manager；exit 用抛错模拟（cmdService 里 process.exit 不好在进程内测） */
+function harness(overrides = {}) {
+  const lines = [];
+  const calls = [];
+  const manager = {
+    platform: 'darwin',
+    dir: '/tmp/LaunchAgents',
+    render: (job, opts) => {
+      calls.push(['render', job, opts.port]);
+      return `[${job}] entry=${job === 'panel' ? 'server/src/index.js' : 'server/src/kernel/run.js'}`;
+    },
+    install: async (opts) => {
+      calls.push(['install', opts.manualRunning]);
+      return {
+        supported: true,
+        files: ['/tmp/LaunchAgents/a.plist', '/tmp/LaunchAgents/b.plist'],
+        actions: ['launchctl bootstrap gui/501 a.plist'],
+        notes: [],
+        errors: [],
+      };
+    },
+    uninstall: async () => {
+      calls.push(['uninstall']);
+      return {
+        supported: true,
+        removed: ['/tmp/LaunchAgents/a.plist'],
+        actions: [],
+        notes: [],
+        errors: [],
+      };
+    },
+    status: async () => {
+      calls.push(['status']);
+      return {
+        supported: true,
+        platform: 'linux',
+        dir: '/home/u/.config/systemd/user',
+        jobs: [
+          { job: 'panel', installed: true, loaded: true, running: true, pid: 42, file: '/a' },
+          { job: 'kernel', installed: false, loaded: false, running: false, pid: 0, file: '/b' },
+        ],
+        linger: null,
+      };
+    },
+    ...overrides,
+  };
+  return { manager, lines, calls, out: (line) => lines.push(line) };
+}
+
+test('print：默认打两个 job，可只打一个', async () => {
+  const h = harness();
+  await cmdService(['print'], {}, { manager: h.manager, out: h.out });
+  assert.deepEqual(h.calls, [
+    ['render', 'panel', 8981],
+    ['render', 'kernel', 8981],
+  ]);
+  assert.match(h.lines.join('\n'), /\[panel\] entry=server\/src\/index\.js/);
+
+  const one = harness();
+  await cmdService(['print', 'kernel'], { port: '9000' }, { manager: one.manager, out: one.out });
+  assert.deepEqual(one.calls, [['render', 'kernel', 9000]]);
+});
+
+test('print：未知 job 返回 2，且不渲染', async () => {
+  const h = harness();
+  assert.equal(await cmdService(['print', 'nope'], {}, { manager: h.manager, out: h.out }), 2);
+  assert.equal(h.calls.length, 0);
+});
+
+test('install：把正在跑的 job 传给 manager，并打印写入的文件', async () => {
+  const h = harness();
+  await cmdService(['install'], {}, { manager: h.manager, out: h.out });
+  // 探测的是真实面板端口：本机有没有面板在跑都会影响这个列表，所以只断言「传了数组」
+  assert.equal(h.calls[0][0], 'install');
+  assert.ok(Array.isArray(h.calls[0][1]));
+  assert.match(h.lines.join('\n'), /已写入 \/tmp\/LaunchAgents\/a\.plist/);
+  assert.match(h.lines.join('\n'), /只开机拉起一次、不保活/);
+});
+
+test('uninstall：打印删除的文件', async () => {
+  const h = harness();
+  await cmdService(['uninstall'], {}, { manager: h.manager, out: h.out });
+  assert.deepEqual(h.calls, [['uninstall']]);
+  assert.match(h.lines.join('\n'), /已删除 \/tmp\/LaunchAgents\/a\.plist/);
+});
+
+test('status：逐 job 打印安装/运行状态；Linux 提示 linger', async () => {
+  const h = harness();
+  await cmdService(['status'], {}, { manager: h.manager, out: h.out });
+  const text = h.lines.join('\n');
+  assert.match(text, /panel\s+已安装 · running · pid 42/);
+  assert.match(text, /kernel\s+未安装 · not loaded/);
+  assert.match(text, /linger 未开启/);
+});
+
+test('不支持平台：提示原因并返回非 0（不静默成功）', async () => {
+  const h = harness({
+    install: async () => ({ supported: false, hint: '暂不支持在 win32 上装开机自启' }),
+  });
+  const code = await cmdService(['install'], {}, { manager: h.manager, out: h.out });
+  assert.equal(code, 1);
+  assert.match(h.lines.join('\n'), /本平台不支持：暂不支持在 win32 上装开机自启/);
+});
+
+test('未知子命令返回 2，且不碰 manager', async () => {
+  const h = harness();
+  assert.equal(await cmdService(['nope'], {}, { manager: h.manager, out: h.out }), 2);
+  assert.equal(h.calls.length, 0);
+});
+
+test('--system 与 --user 同时给：返回 2，不碰 manager', async () => {
+  const h = harness();
+  const code = await cmdService(
+    ['install'],
+    { system: true, user: true },
+    {
+      manager: h.manager,
+      out: h.out,
+    },
+  );
+  assert.equal(code, 2);
+  assert.equal(h.calls.length, 0);
+});
+
+test('status 打印作用域；用户级才提示 linger', async () => {
+  const h = harness();
+  await cmdService(['status'], {}, { manager: h.manager, out: h.out });
+  // 桩 status 没给 scope → CLI 按用户级处理（并据此提示 linger）
+  assert.match(h.lines.join('\n'), /作用域：user/);
+  assert.match(h.lines.join('\n'), /linger 未开启/);
+
+  const sys = harness({
+    status: async () => ({
+      supported: true,
+      platform: 'linux',
+      scope: 'system',
+      dir: '/etc/systemd/system',
+      jobs: [{ job: 'panel', installed: true, loaded: true, running: true, pid: 1, file: '/x' }],
+      linger: null,
+    }),
+  });
+  await cmdService(['status'], {}, { manager: sys.manager, out: sys.out });
+  assert.match(sys.lines.join('\n'), /作用域：system/);
+  assert.doesNotMatch(sys.lines.join('\n'), /linger/);
+});

package/server/tests/config-dir.test.js

@@ -0,0 +1,133 @@
+/**
+ * 内核配置目录的「钉死」行为（server/src/shared/paths.js）与相关端点测试。
+ *
+ * 2026-11 定：`MIHOMO_DIR` 显式覆盖 > 面板自有落点 `MIHOMO_DASH_DIR/data`；**不再扫**
+ * ~/.config/mihomo、/etc/mihomo、/opt/homebrew/etc/mihomo 这些地方（以前是候选表第一个含
+ * config.yaml 的胜出，卸载自有内核后面板会悄悄转去管别处的配置）。配置文件页据此在「还没有
+ * config.yaml」时给提示，而不是显示别人的配置（默认配置只在首次安装内核时写）。
+ * 运行：npm test
+ */
+import assert from 'node:assert/strict';
+import { after, before, test } from 'node:test';
+import express from 'express';
+import fs from 'node:fs';
+import http from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+
+/** @type {Record<string, any>} */ let mods = {};
+/** @type {string} */ let tmpDir;
+/** @type {string} */ let cliDir;
+/** @type {string} */ let cfgDir;
+/** @type {import('node:http').Server} */ let kernel;
+/** @type {import('node:http').Server} */ let server;
+/** @type {string} */ let base;
+/** @type {number} */ let stubPort = 0;
+
+/** 桩内核：只响应 PUT /configs?force=true（热重载） */
+before(async () => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mihomo-dash-cfgdir-'));
+  cliDir = path.join(tmpDir, 'cli');
+  cfgDir = path.join(tmpDir, 'mihomo');
+  kernel = http.createServer((_req, res) => {
+    res.writeHead(200, { 'content-type': 'application/json' });
+    res.end('{}');
+  });
+  await new Promise((r) => kernel.listen(0, '127.0.0.1', r));
+  stubPort = kernel.address().port;
+
+  process.env.MIHOMO_DASH_DIR = cliDir;
+  process.env.MIHOMO_DIR = cfgDir;
+  mods.paths = await import('../src/shared/paths.js');
+  mods.files = await import('../src/http/config-files.js');
+
+  const app = express();
+  app.use(express.json());
+  // 只挂「配置文件」页用到的那几条（其余端点与本文件无关）
+  app.get('/api/file', (req, res) => {
+    try {
+      res.json(mods.files.readFileInfo(String(req.query.name || '')));
+    } catch (err) {
+      res.status(400).json({ error: String(err?.message || err) });
+    }
+  });
+  app.put('/api/file', (req, res) => {
+    try {
+      mods.files.saveFile(String(req.body?.name ?? ''), String(req.body?.content ?? ''));
+      res.json({ ok: true });
+    } catch (err) {
+      res.status(400).json({ error: String(err?.message || err) });
+    }
+  });
+  server = app.listen(0, '127.0.0.1');
+  await new Promise((r) => server.once('listening', r));
+  base = `http://127.0.0.1:${server.address().port}`;
+});
+
+after(async () => {
+  await new Promise((r) => server.close(r));
+  await new Promise((r) => kernel.close(r));
+  delete process.env.MIHOMO_DIR;
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+test('不设 MIHOMO_DIR：配置目录就是面板状态目录下的 data/（不存在也照返回，不去扫别处）', () => {
+  delete process.env.MIHOMO_DIR;
+  mods.paths.resetMihomoDirCache();
+  try {
+    const dir = mods.paths.detectMihomoDir();
+    assert.equal(dir, path.join(cliDir, 'data'));
+    assert.equal(mods.paths.configPath(), path.join(cliDir, 'data', 'config.yaml'));
+    // 老候选表里的目录一个都不该被选中
+    for (const old of [
+      '/etc/mihomo',
+      '/opt/homebrew/etc/mihomo',
+      path.join(os.homedir(), '.config', 'mihomo'),
+    ]) {
+      assert.notEqual(dir, old);
+    }
+  } finally {
+    mods.paths.resetMihomoDirCache();
+    process.env.MIHOMO_DIR = cfgDir;
+  }
+});
+
+test('设了 MIHOMO_DIR：就用它，且不回退（目录里没有 config.yaml 也认）', () => {
+  const elsewhere = path.join(tmpDir, 'elsewhere');
+  process.env.MIHOMO_DIR = elsewhere;
+  mods.paths.resetMihomoDirCache();
+  try {
+    assert.equal(mods.paths.detectMihomoDir(), elsewhere);
+    assert.equal(mods.paths.configPath(), path.join(elsewhere, 'config.yaml'));
+  } finally {
+    process.env.MIHOMO_DIR = cfgDir;
+    mods.paths.resetMihomoDirCache();
+  }
+});
+
+test('读文件：不存在不算错 —— 返回 exists:false + 空内容 + 路径', async () => {
+  const got = await (await fetch(`${base}/api/file?name=config.yaml`)).json();
+  assert.equal(got.exists, false);
+  assert.equal(got.content, '');
+  assert.equal(got.path, path.join(cfgDir, 'config.yaml'));
+});
+
+test('写盘会自动建目录（配置目录被删掉之后也能直接保存）', async () => {
+  const dir = path.join(cfgDir, 'providers');
+  fs.rmSync(dir, { recursive: true, force: true });
+  const res = await fetch(`${base}/api/file`, {
+    method: 'PUT',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ name: 'providers/sub.yaml', content: 'proxies: []\n' }),
+  });
+  assert.equal(res.status, 200);
+  assert.equal(fs.readFileSync(path.join(dir, 'sub.yaml'), 'utf8'), 'proxies: []\n');
+});
+
+test('MIHOMO_DIR 覆盖下的那份配置能被正常读写', () => {
+  fs.mkdirSync(cfgDir, { recursive: true });
+  const file = mods.paths.configPath();
+  fs.writeFileSync(file, `external-controller: 127.0.0.1:${stubPort}\nmixed-port: 7890\n`);
+  assert.equal(file, path.join(cfgDir, 'config.yaml'));
+  assert.match(mods.files.readFile('config.yaml'), /mixed-port: 7890/);
+});