@lancewu602/mihomo-dash 0.0.0-stage → 0.6.1

package/server/src/shared/paths.js

@@ -0,0 +1,72 @@
+/** 常量与目录：状态目录（MIHOMO_DASH_DIR）与内核配置目录（MIHOMO_DIR）。 */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+// 面板默认监听
+export const DEFAULT_HOST = '127.0.0.1';
+export const DEFAULT_PORT = 8981;
+
+// 状态目录（内核管理用；面板本身不写 pid / 日志文件，进程由系统服务管理器托管）
+// 兼容旧变量 MIHOMO_CLI_DIR（命令改名前的写法），仅在没设新变量时生效
+export const CLI_DIR =
+  process.env.MIHOMO_DASH_DIR ||
+  process.env.MIHOMO_CLI_DIR ||
+  path.join(os.homedir(), '.config', 'mihomo-dash');
+
+// 内核（面板自有安装）相关文件，只在面板「内核」页装/升/卸与启停时产生：
+//   bin/                面板自有内核唯一的落点（外面怎么装的与我们无关）
+//   data/               内核配置目录（config.yaml / providers / cache.db / GEO 数据）的推荐落点
+//   kernels.json        安装台账：版本 / 资产名 / sha256 / 备份文件
+//   kernel-run.json     start 写的运行时元数据（pid / 二进制 / 配置目录；supervised = 由系统服务管理器拉起）
+//   kernel.pid          自有内核 pid，stop 只杀这一个
+//   kernel.log          自有内核的 stdout/stderr
+export const KERNEL_BIN_DIR = path.join(CLI_DIR, 'bin');
+export const KERNEL_BIN = path.join(
+  KERNEL_BIN_DIR,
+  process.platform === 'win32' ? 'mihomo.exe' : 'mihomo',
+);
+// 面板自有内核的配置目录（data/）：跟 bin/ 一起放在状态目录里。
+// **2026-11 起面板的「内核配置目录」就钉在它上面**（见 detectMihomoDir）：以前是「候选表里第一个含
+// config.yaml 的胜出」，结果卸载自有内核后（data/ 被删）面板会悄悄转去管别的目录（实测落到了
+// /opt/homebrew/etc/mihomo，用户看到「内核都卸载了怎么还有配置文件」）—— 这种「看着像自己的其实不是」
+// 最误导人，所以候选表整个去掉了。要管别处的配置：把它放进来，或显式设 MIHOMO_DIR。
+export const KERNEL_CONFIG_DIR = path.join(CLI_DIR, 'data');
+export const KERNEL_LEDGER_FILE = path.join(CLI_DIR, 'kernels.json');
+export const KERNEL_META_FILE = path.join(CLI_DIR, 'kernel-run.json');
+export const KERNEL_PID_FILE = path.join(CLI_DIR, 'kernel.pid');
+export const KERNEL_LOG_FILE = path.join(CLI_DIR, 'kernel.log');
+
+export function ensureCliDir() {
+  fs.mkdirSync(CLI_DIR, { recursive: true });
+  return CLI_DIR;
+}
+
+let cachedMihomoDir;
+
+/** 清掉探测缓存（目录来源变了之后重来一次；现在来源只有环境变量与状态目录，留着是给调用方一个统一收口） */
+export function resetMihomoDirCache() {
+  cachedMihomoDir = undefined;
+}
+
+/**
+ * 内核配置目录：**`MIHOMO_DIR` 显式覆盖 > 面板自有落点 `MIHOMO_DASH_DIR/data`**。
+ * 不再扫 ~/.config/mihomo、/etc/mihomo、/opt/homebrew/etc/mihomo 这类地方（理由见上面 `KERNEL_CONFIG_DIR`）。
+ * 目录或 config.yaml 不存在也照常返回这个路径 —— 页面据此显示「还没有配置」，写盘时会按需建目录。
+ * @returns {string}
+ */
+export function detectMihomoDir() {
+  if (cachedMihomoDir !== undefined) return cachedMihomoDir;
+  cachedMihomoDir = process.env.MIHOMO_DIR || KERNEL_CONFIG_DIR;
+  return cachedMihomoDir;
+}
+
+export function configPath() {
+  return path.join(detectMihomoDir(), 'config.yaml');
+}
+
+/** 建好配置目录（写 config.yaml / providers 之前调；目录已存在则什么都不做） */
+export function ensureConfigDir(dir = detectMihomoDir()) {
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}

package/server/src/shared/service.js

@@ -0,0 +1,552 @@
+/**
+ * 开机自启：把「面板」与「面板自有内核」交给系统服务管理器监管。
+ *
+ * 支持 macOS（LaunchAgent，`~/Library/LaunchAgents`，用户级、不需要 sudo）与 Linux
+ * （`systemd --user` 单元，落在 `~/.config/systemd/user`）；Windows 与其它平台只提示。
+ *
+ * 三条硬约定，改动前先读：
+ * 1. **只开机拉起一次，不保活**：launchd 故意不写 `KeepAlive`、systemd 写 `Restart=no`。
+ *    好处是语义干净 —— 服务管理器 stop / 侧栏的「停止内核」就是真停，不会被拉回来，也不会因为
+ *    配置写坏（内核起不来）造成「每 10 秒重启一次」的风暴；代价是崩了不会自愈，想再起来重新登录，
+ *    或 `launchctl kickstart -k gui/<uid>/…` / `systemctl --user start …` 手动拉一次。
+ * 2. **固定 argv，不经 shell**：plist / unit 里的可执行文件与参数都在这里拼好，
+ *    路径只来自 `MIHOMO_DASH_DIR` 与 `process.execPath`，不把外部字符串拼进命令。
+ * 3. **安装 / 卸载都不动正在跑的进程**：`bootout` / `disable --now` 会当场把面板（或内核）杀掉，
+ *    而用户很可能正开着页面在用它；已装载的 job 只更新磁盘上的定义（下次登录生效），卸载也只删定义
+ *    （要停进程去服务管理器 stop / 侧栏的「停止内核」）。
+ *    「安装」仍会真的 bootstrap / `enable --now`（否则页面上的「已装载」就是假的）；进程正在手动跑的
+ *    job 在 Linux 上退化为只 `enable`（免得留一个注定失败的单元），而那个必然立刻退出的第二实例
+ *    由 CLI 补一句 `notes` 说明。只有 `start()`（手动拉起）会真的去拉进程。
+ *
+ * 用户侧入口是 CLI 的 `mihomo-dash service print|install|uninstall|status`（面板里没有「自启」页）。
+ * 服务定义里写的是两个真实入口：`server/src/index.js`（panel job）与 `server/src/kernel/run.js`（kernel job）——
+ * 没有额外的中转脚本，也没有 pid / meta 文件：job 状态直接问 launchctl / `systemctl --user`，
+ * 面板存活靠 `shared/panel.js` 探 `/api/health`。
+ *
+ * `run` 可注入：测试用桩函数断言真实 argv，不会碰本机的 launchd / systemd。
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { defaultRun } from './exec.js';
+import { CLI_DIR, DEFAULT_HOST, DEFAULT_PORT } from './paths.js';
+
+/** 两个 job 各自的入口脚本（plist / unit 里的第二个参数；都在 server/ 内，随包发布） */
+export const SERVICE_ENTRIES = {
+  panel: path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../index.js'),
+  kernel: path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../kernel/run.js'),
+};
+
+/** 面板 / 内核两个 agent 共用的 bundle 标识：只是给「登录项」UI 认领用的，不是真的 app bundle */
+export const BUNDLE_ID = 'com.mihomo-dash';
+
+/** 两个受监管的 job：面板与面板自有内核 */
+const JOBS = {
+  panel: {
+    label: 'com.mihomo-dash.panel',
+    unit: 'mihomo-dash-panel.service',
+    description: 'mihomo-dash 面板（Web UI + REST 转发）',
+    args: (opts) => ['--port', String(opts.port), '--host', opts.host],
+    log: (cliDir) => path.join(cliDir, 'daemon.log'),
+  },
+  kernel: {
+    label: 'com.mihomo-dash.kernel',
+    unit: 'mihomo-dash-kernel.service',
+    description: 'mihomo-dash 自有内核（用配置目录里的 config.yaml）',
+    args: () => [],
+    log: (cliDir) => path.join(cliDir, 'kernel.log'),
+  },
+};
+
+export const SERVICE_JOBS = Object.keys(JOBS);
+
+function jobOf(job) {
+  const def = JOBS[job];
+  if (!def) throw new Error(`未知服务: ${job}（只能是 ${SERVICE_JOBS.join(' / ')}）`);
+  return def;
+}
+
+/** plist / unit 里出现的路径都要过一遍 XML 转义（家目录带 & 之类也不是不可能） */
+export function xmlEscape(text) {
+  return String(text)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+/** systemd 的 ExecStart 参数：含空格/引号时加引号，其余原样 */
+export function systemdQuote(arg) {
+  const text = String(arg);
+  if (!/[\s"\\]/.test(text)) return text;
+  return `"${text.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+/**
+ * macOS LaunchAgent 定义。故意**不写 KeepAlive**（见文件头注释：只开机起一次）。
+ * @param {'panel'|'kernel'} job
+ * @param {{ node: string, entries: Record<'panel'|'kernel', string>, entry?: string, cliDir: string, port?: number, host?: string }} opts
+ */
+export function renderPlist(job, opts) {
+  const def = jobOf(job);
+  const port = opts.port ?? DEFAULT_PORT;
+  const host = opts.host ?? DEFAULT_HOST;
+  const entry = opts.entry ?? opts.entries[job];
+  const argv = [opts.node, entry, ...def.args({ port, host })];
+  const args = argv.map((a) => `    <string>${xmlEscape(a)}</string>`).join('\n');
+  const log = def.log(opts.cliDir);
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${xmlEscape(def.label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${args}
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${xmlEscape(opts.cliDir)}</string>
+  <!-- 只开机拉起一次：不写 KeepAlive，崩了不自动重拉，stop 就是真停 -->
+  <key>RunAtLoad</key>
+  <true/>
+  <key>ProcessType</key>
+  <string>Background</string>
+  <!-- 「登录项 → 允许在后台」靠这个键把两个服务归到 mihomo-dash 名下；
+       不写的话系统按被拉起进程的签名归属，会显示成 node 的发行方 Node.js Foundation -->
+  <key>AssociatedBundleIdentifiers</key>
+  <array>
+    <string>${BUNDLE_ID}</string>
+  </array>
+  <key>StandardOutPath</key>
+  <string>${xmlEscape(log)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xmlEscape(log)}</string>
+</dict>
+</plist>
+`;
+}
+
+/**
+ * Linux systemd --user 单元定义。`Restart=no` 与 launchd 侧「不设 KeepAlive」对应。
+ * @param {'panel'|'kernel'} job
+ * @param {{ node: string, entries: Record<'panel'|'kernel', string>, entry?: string, cliDir: string, port?: number, host?: string, scope?: 'system'|'user' }} opts
+ */
+export function renderUnit(job, opts) {
+  const scope = opts.scope === 'system' ? 'system' : 'user';
+  const wantedBy = scope === 'system' ? 'multi-user.target' : 'default.target';
+  const def = jobOf(job);
+  const port = opts.port ?? DEFAULT_PORT;
+  const host = opts.host ?? DEFAULT_HOST;
+  const entry = opts.entry ?? opts.entries[job];
+  const argv = [opts.node, entry, ...def.args({ port, host })];
+  const log = def.log(opts.cliDir);
+  return `# 由 \`mihomo-dash service install\` 生成（server/src/shared/service.js），勿手改 —— 重新安装会覆盖
+# 作用域：${scope === 'system' ? 'system（/etc/systemd/system，以 root 运行，开机即起）' : 'user（~/.config/systemd/user，登录后启动 or linger）'}
+[Unit]
+Description=${def.description}
+After=network-online.target
+
+[Service]
+Type=simple
+# 只开机拉起一次：崩了不自动重拉，侧栏的「停止内核」/ 服务管理器 stop 就是真停
+Restart=no
+WorkingDirectory=${opts.cliDir}
+ExecStart=${argv.map(systemdQuote).join(' ')}
+StandardOutput=append:${log}
+StandardError=append:${log}
+
+[Install]
+WantedBy=${wantedBy}
+`;
+}
+
+/** `launchctl print` 输出里取 job 自己的状态（第一处 state / pid 就是主进程的） */
+export function parseLaunchctlPrint(text) {
+  const s = String(text);
+  const state = s.match(/^\s*state = (.+)$/m);
+  const pid = s.match(/^\s*pid = (\d+)$/m);
+  return { state: state ? state[1].trim() : null, pid: pid ? Number(pid[1]) : 0 };
+}
+
+/** systemd 的 is-enabled / is-active 输出归一化 */
+export function parseSystemctlState(enabled, active) {
+  const e = String(enabled).trim();
+  const a = String(active).trim();
+  return {
+    installed: e !== 'not-found',
+    enabled: e === 'enabled' || e === 'enabled-runtime',
+    active: a === 'active',
+    state: a || e,
+  };
+}
+
+function serviceDir({ platform, home, scope = 'user', systemDir }) {
+  if (platform === 'darwin') return path.join(home, 'Library', 'LaunchAgents');
+  return scope === 'system'
+    ? systemDir || '/etc/systemd/system'
+    : path.join(home, '.config', 'systemd', 'user');
+}
+
+/**
+ * 服务管理器（每个平台一份实现，对外一套方法）。
+ *
+ * 方法都返回结果对象、不自行退出（退出码由 CLI 决定），并且**只走固定 argv**。
+ *
+ * Linux 的 `scope`：`system`（**默认当 root 时**）写 `/etc/systemd/system`、`systemctl enable --now`，
+ * 开机即起、不依赖 linger；`user` 写 `~/.config/systemd/user`、`systemctl --user`，不需要 root，
+ * 但要开机即起得靠 `loginctl enable-linger`。macOS 固定用户级 LaunchAgent，没有 system 域。
+ * @param {{
+ *   run?: typeof defaultRun,
+ *   platform?: string,
+ *   home?: string,
+ *   cliDir?: string,
+ *   node?: string,
+ *   entries?: Record<'panel'|'kernel', string>,
+ *   scope?: 'system' | 'user',
+ *   systemDir?: string,
+ *   uid?: number,
+ *   user?: string,
+ * }} [options]
+ */
+export function createServiceManager(options = {}) {
+  const run = options.run || defaultRun;
+  const platform = options.platform || process.platform;
+  const home = options.home || os.homedir();
+  const cliDir = options.cliDir || CLI_DIR;
+  const node = options.node || process.execPath;
+  const entries = options.entries || SERVICE_ENTRIES;
+  const uid = options.uid ?? process.getuid?.() ?? 0;
+  const user = options.user || os.userInfo().username;
+  const supported = platform === 'darwin' || platform === 'linux';
+  // Linux 默认 system（与 NAS 上 deck 的部署形态一致，开机即起且不依赖 linger）；
+  // 非 root 时默认退成 user，避免一上手就写 /etc 失败。
+  const isRoot = platform !== 'win32' && uid === 0;
+  const scope = platform === 'linux' ? (options.scope ?? (isRoot ? 'system' : 'user')) : 'user';
+  /** systemd 的公共参数：system 作用域不带 `--user` */
+  const systemdArgs = scope === 'system' ? [] : ['--user'];
+  /** launchd 的域：GUI 会话固定在 gui/<uid>，只有 SSH 时会话里退到 user/<uid> */
+  const domains = [`gui/${uid}`, `user/${uid}`];
+  const dir = serviceDir({ platform, home, scope, systemDir: options.systemDir });
+  const file = (job) =>
+    path.join(dir, platform === 'darwin' ? `${jobOf(job).label}.plist` : jobOf(job).unit);
+  const installed = (job) => fs.existsSync(file(job));
+
+  /**
+   * 渲染某个 job 的服务定义。node / cliDir / 端口没传时用 manager 自己的默认值
+   * （CLI 的 `service print` 只关心端口，不重复拼这些路径）。
+   */
+  const render = (job, opts = {}) =>
+    (platform === 'darwin' ? renderPlist : renderUnit)(job, {
+      node: opts.node ?? node,
+      cliDir: opts.cliDir ?? cliDir,
+      scope: opts.scope ?? scope,
+      port: opts.port ?? DEFAULT_PORT,
+      host: opts.host ?? DEFAULT_HOST,
+      entry: entries[job],
+    });
+  const renderOpts = (opts = {}) => ({
+    node,
+    cliDir,
+    scope,
+    port: opts.port ?? DEFAULT_PORT,
+    host: opts.host ?? DEFAULT_HOST,
+  });
+
+  const hint =
+    platform === 'win32'
+      ? 'Windows 没有 launchd / systemd：请把 mihomo-dash 的快捷方式放进「启动」文件夹（shell:startup），或用任务计划程序'
+      : `暂不支持在 ${platform} 上装开机自启`;
+
+  /**
+   * Linux：`systemctl --user` 到底能不能用（探一次缓存住，顺便留住失败原因给提示用）。
+   * 非 systemd 发行版（Alpine / OpenRC…）根本没这个命令；容器 / 没有用户会话的环境里
+   * 命令在但连不上用户实例（`Failed to connect to bus`）—— 两种都装不了服务，一并算不可用。
+   * 缓存的是 **Promise**（并发调用只探一次，不需要额外的 inflight 标记）。
+   */
+  let systemdProbe;
+  function probeSystemd() {
+    if (!systemdProbe) {
+      systemdProbe = (async () => {
+        const r = await run('systemctl', [...systemdArgs, 'is-system-running']);
+        const reason = String(r.stderr || '').trim();
+        // 注意：systemd 在 degraded / starting 时也返回非 0，但那是 stdout 里的状态词；
+        // 这里只认「命令不存在」「连不上总线」这类硬失败
+        const broken =
+          /ENOENT|not found|No such file|command not found|Failed to connect to bus/i.test(reason);
+        return { ok: !broken, reason: broken ? reason : '' };
+      })();
+    }
+    return systemdProbe;
+  }
+
+  /** 干不了活的原因（null = 可以）；unsupported 平台与「Linux 上没有可用 systemd」共用一套判定 */
+  async function unavailable() {
+    if (!supported) return hint;
+    // 只有 Linux 才探 systemd：macOS 上白跑一条 systemctl 是多余的进程（测试也盯着这点）
+    if (platform === 'linux') {
+      const probe = await probeSystemd();
+      if (!probe.ok) {
+        const { reason } = probe;
+        return scope === 'system'
+          ? `本机没有可用的 systemd${reason ? `（${reason}）` : ''}：非 systemd 发行版请用发行版自己的开机自启方式`
+          : `本机没有可用的 systemd 用户实例${reason ? `（${reason}）` : ''}：` +
+              '要么先在有用户会话的环境里跑，要么用 service install --system（system 单元要 root）';
+      }
+    }
+    return null;
+  }
+
+  /** Linux：用户 linger 是否开着（决定是「开机即起」还是「登录后启动」）；问不到返回 null */
+  async function readLinger() {
+    const r = await run('loginctl', ['show-user', user, '-p', 'Linger']);
+    const m = /Linger=(\w+)/.exec(r.stdout || '');
+    return m ? m[1] === 'yes' : null;
+  }
+
+  /** 已装载的域（找不到返回 null） */
+  async function loadedDomain(job) {
+    for (const d of domains) {
+      const r = await run('launchctl', ['print', `${d}/${jobOf(job).label}`]);
+      if (r.ok) return d;
+    }
+    return null;
+  }
+
+  /**
+   * 安装：写两个 plist / unit 并装载启用。
+   *
+   * - 已装载的 job **不 bootout**（那会当场杀掉它），只更新磁盘上的定义 —— 新定义下次登录生效；
+   * - 其余一律 bootstrap / `enable --now`：「安装」就该当场装载上（页面上的「已装载」才是真的）。
+   *   进程正在手动跑着的 job，服务拉起的第二个实例会因端口被占 / pid 文件活着而立刻退出 ——
+   *   那是预期内的，调用方（CLI 的 `service install`）会就这件事补一句说明。
+   * - `manualRunning` 只影响 Linux：这类 job 只 `enable` 不 `--now`，免得 systemd 里留一个
+   *   注定失败（端口被占）的 failed 单元。
+   * @param {{ port?: number, host?: string, manualRunning?: string[] }} [opts]
+   */
+  async function install(opts = {}) {
+    const why = await unavailable();
+    if (why) {
+      return { supported: false, hint: why, files: [], actions: [], errors: [], notes: [] };
+    }
+    const manualRunning = new Set(opts.manualRunning || []);
+    fs.mkdirSync(dir, { recursive: true });
+    const files = [];
+    const actions = [];
+    const errors = [];
+    const notes = [];
+    const loadedIn = {};
+    for (const job of SERVICE_JOBS) {
+      const target = file(job);
+      fs.writeFileSync(target, render(job, renderOpts(opts)));
+      files.push(target);
+      if (platform === 'darwin') {
+        const loaded = await loadedDomain(job);
+        if (loaded) {
+          loadedIn[job] = loaded;
+          notes.push(`${job}: 已在 ${loaded} 装载，只更新了定义（下次登录生效）`);
+          continue;
+        }
+        let ok = false;
+        const failures = [];
+        for (const d of domains) {
+          const r = await run('launchctl', ['bootstrap', d, target], { timeout: 10000 });
+          if (r.ok) {
+            ok = true;
+            loadedIn[job] = d;
+            actions.push(`launchctl bootstrap ${d} ${target}`);
+            break;
+          }
+          // gui 域失败但 user 域成功是正常情况（SSH 会话），只有全都失败才算错
+          failures.push(`${d}: ${r.stderr.trim() || `退出码 ${r.status}`}`);
+        }
+        if (!ok) {
+          errors.push(
+            `${job}: launchctl bootstrap 失败（${failures.join('；')}）；plist 已写好，下次登录仍会启动`,
+          );
+        }
+      } else {
+        const r1 = await run('systemctl', [...systemdArgs, 'daemon-reload']);
+        if (!r1.ok && r1.stderr) errors.push(`daemon-reload: ${r1.stderr.trim()}`);
+        // 手动跑着的只 enable（不开机就拉起第二个必然失败的实例）
+        const args = manualRunning.has(job)
+          ? [...systemdArgs, 'enable', jobOf(job).unit]
+          : [...systemdArgs, 'enable', '--now', jobOf(job).unit];
+        if (manualRunning.has(job)) {
+          notes.push(`${job}: 进程正在手动运行，本次只启用不拉起（下次登录由服务管理器接管）`);
+        }
+        const r2 = await run('systemctl', args);
+        if (r2.ok) actions.push(`systemctl ${args.join(' ')}`);
+        else errors.push(`${job}: ${r2.stderr.trim() || 'systemctl enable 失败'}`);
+      }
+    }
+    const hints = [];
+    if (platform === 'darwin') {
+      hints.push(
+        `plist 里的 Node 固定为 ${node}：换 Node 版本（nvm use 等）后要重新点一次「安装」`,
+      );
+    } else if (scope === 'system') {
+      hints.push('system 单元以 root 运行：开机即起，不依赖登录与 linger');
+    } else {
+      hints.push(
+        '用户级单元：服务器/无桌面登录场景还要 sudo loginctl enable-linger <用户>，否则退出登录后单元会被停掉；' +
+          '有 root 时也可改用系统级（service install --system）',
+      );
+    }
+    return {
+      supported: true,
+      platform,
+      scope,
+      dir,
+      files,
+      actions,
+      errors,
+      notes,
+      loadedIn,
+      hints,
+    };
+  }
+
+  /**
+   * 卸载：删服务定义与 enable 状态，**不杀正在跑的进程**（见文件头第 3 条）。
+   *
+   * Linux 侧要 `disable`（不 `--now`）：enable 的符号链接与 unit 文件是两回事，不 disable 的话
+   * systemd 下次登录还会照着符号链接把它拉起来。launchd 只要 plist 没了，下次登录就不会拉 ——
+   * 但**本会话里那个 job 还挂在 launchd 上**（不 bootout 是为了不杀进程），页面会把它标成「残留」。
+   */
+  async function uninstall() {
+    const why = await unavailable();
+    if (why) {
+      return { supported: false, hint: why, removed: [], actions: [], errors: [], notes: [] };
+    }
+    const removed = [];
+    const actions = [];
+    const errors = [];
+    const notes = [
+      '服务定义已删除；正在跑的进程没动（要停它们：服务管理器 stop / 侧栏的「停止内核」）',
+    ];
+    for (const job of SERVICE_JOBS) {
+      const target = file(job);
+      // 删文件前先看一眼：launchd 的加载状态与文件无关，删了也照样挂着
+      const stillLoaded = platform === 'darwin' && !!(await loadedDomain(job));
+      if (platform === 'linux') {
+        const r = await run('systemctl', [...systemdArgs, 'disable', jobOf(job).unit]);
+        if (r.ok) actions.push(`systemctl --user disable ${jobOf(job).unit}`);
+        else if (r.stderr && !/not loaded|does not exist|No such file/i.test(r.stderr)) {
+          errors.push(`${job}: ${r.stderr.trim()}`);
+        }
+      }
+      try {
+        fs.rmSync(target, { force: true });
+        removed.push(target);
+      } catch (err) {
+        errors.push(`${target}: ${err?.message || err}`);
+      }
+      if (stillLoaded) {
+        notes.push(
+          `${job}: plist 已删，但 launchd 里这个 job 还挂着（本会话内 launchctl 仍能看到）` +
+            '—— 卸载不 bootout 是为了不杀掉进程，重新登录后它就没了',
+        );
+      }
+    }
+    if (platform === 'linux') await run('systemctl', [...systemdArgs, 'daemon-reload']);
+    return { supported: true, platform, removed, actions, errors, notes };
+  }
+
+  async function status() {
+    const why = await unavailable();
+    if (why) return { supported: false, platform, hint: why, jobs: [] };
+    const statuses = await Promise.all(
+      SERVICE_JOBS.map(async (job) => {
+        const filePath = file(job);
+        if (platform === 'darwin') {
+          const d = await loadedDomain(job);
+          const r = d ? await run('launchctl', ['print', `${d}/${jobOf(job).label}`]) : null;
+          const parsed = r?.ok ? parseLaunchctlPrint(r.stdout) : { state: null, pid: 0 };
+          return {
+            job,
+            file: filePath,
+            installed: fs.existsSync(filePath),
+            loaded: !!d,
+            domain: d,
+            running: parsed.state === 'running',
+            pid: parsed.pid,
+            state: parsed.state,
+          };
+        }
+        const enabled = await run('systemctl', [...systemdArgs, 'is-enabled', jobOf(job).unit]);
+        const active = await run('systemctl', [...systemdArgs, 'is-active', jobOf(job).unit]);
+        const parsed = parseSystemctlState(enabled.stdout || '', active.stdout || '');
+        return {
+          job,
+          file: filePath,
+          installed: fs.existsSync(filePath) && parsed.installed,
+          loaded: parsed.installed,
+          domain: 'systemd --user',
+          running: parsed.active,
+          pid: 0,
+          state: parsed.state,
+        };
+      }),
+    );
+    // linger 只对「用户级」有意义：system 单元本来就开机即起
+    return {
+      supported: true,
+      platform,
+      scope,
+      dir,
+      jobs: statuses,
+      linger: platform === 'linux' && scope === 'user' ? await readLinger() : null,
+    };
+  }
+
+  /**
+   * 手动拉起已安装的服务：「只开机拉起一次、不保活」，所以停掉之后靠这个或重新登录。
+   * launchd：未装载就先 bootstrap，已装载就 kickstart；systemd：直接 `--user start`。
+   * @param {'panel'|'kernel'} [job] 缺省时两个都拉
+   */
+  async function start(job) {
+    const why = await unavailable();
+    if (why) return { supported: false, hint: why, started: [], errors: [] };
+    const want = job ? [job] : SERVICE_JOBS;
+    const started = [];
+    const errors = [];
+    for (const j of want) {
+      jobOf(j);
+      if (!installed(j)) {
+        errors.push(`${j}: 还没安装开机自启（先点「安装」）`);
+        continue;
+      }
+      if (platform === 'darwin') {
+        const d = await loadedDomain(j);
+        if (!d) {
+          let ok = false;
+          const failures = [];
+          for (const dom of domains) {
+            const r = await run('launchctl', ['bootstrap', dom, file(j)], { timeout: 10000 });
+            if (r.ok) {
+              ok = true;
+              started.push(`launchctl bootstrap ${dom} ${file(j)}`);
+              break;
+            }
+            failures.push(`${dom}: ${r.stderr.trim() || `退出码 ${r.status}`}`);
+          }
+          if (!ok) errors.push(`${j}: launchctl bootstrap 失败（${failures.join('；')}）`);
+          continue;
+        }
+        const r = await run('launchctl', ['kickstart', `${d}/${jobOf(j).label}`]);
+        if (r.ok) started.push(`launchctl kickstart ${d}/${jobOf(j).label}`);
+        else errors.push(`${j}: ${r.stderr.trim() || 'launchctl kickstart 失败'}`);
+      } else {
+        const r = await run('systemctl', [...systemdArgs, 'start', jobOf(j).unit]);
+        if (r.ok) started.push(`systemctl --user start ${jobOf(j).unit}`);
+        else errors.push(`${j}: ${r.stderr.trim() || 'systemctl start 失败'}`);
+      }
+    }
+    return { supported: true, platform, started, errors };
+  }
+
+  return { platform, supported, hint, scope, dir, file, render, install, uninstall, status, start };
+}