@lancewu602/mihomo-dash 0.0.0-stage → 0.6.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lancewu602
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,100 @@
-# Temporary Holding Version
+# mihomo-dash
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+管理本机 [mihomo](https://github.com/MetaCubeX/mihomo)（Clash.Meta）内核的一体化工具：**CLI + 守护进程 + Web 面板**，一个 npm 包搞定订阅、策略组、规则、日志与配置文件。
+
+> npm 包名是 **`@lancewu602/mihomo-dash`**（scoped），命令名仍是 **`mihomo-dash`**（装上后直接敲它）。
+
+- 运行时依赖只有 `express` 与 `js-yaml`，后端纯 JS + JSDoc、**零构建**直跑
+- 前端 React 18 + TypeScript + Vite + Ant Design 5，面板默认只监听 `127.0.0.1:8981`
+- 改配置走「校验 → 写盘 → 内核热重载」，文本级改写保留 YAML 注释（不留 `.bak`，重载失败只报错不改回文件）
+- 纯 JS 包，任何装了 Node ≥20 的平台都能跑；不发布原生二进制
+
+## 快速开始
+
+```bash
+npm i -g @lancewu602/mihomo-dash   # 或 npx @lancewu602/mihomo-dash
+
+mihomo-dash               # 无参数 = 总览（内核 / 面板 / 系统代理 / 开机自启）
+mihomo-dash service install   # 装成开机自启（macOS launchd / Debian systemd --user）
+mihomo-dash service status    # 查看自启状态
+```
+
+## 命令
+
+```bash
+mihomo-dash                    # 总览：内核 / 面板 / 系统代理 / 开机自启（= status）
+sudo mihomo-dash service install   # Debian：system 单元（默认），开机即起
+mihomo-dash service install        # macOS：用户级 LaunchAgent，不需要 root
+mihomo-dash service status         # 自启状态（作用域 / 定义目录 / 是否在跑）
+sudo mihomo-dash service uninstall # 卸载（不停进程）
+mihomo-dash service print          # 打印服务定义（plist / systemd unit），不写文件
+```
+
+面板的启动交给系统服务管理器，装好后由它拉起 `server/src/index.js`（面板）与
+`server/src/kernel/run.js`（内核）。**只开机拉起一次、不保活**（崩了不重拉，停了就是真停）；
+安装 / 卸载都**不动正在跑的进程**。
+
+作用域（Debian）：
+
+| 作用域                 | 落点                                                     | 要 root | 开机即起                               |
+| ---------------------- | -------------------------------------------------------- | ------- | -------------------------------------- |
+| `--system`（**默认**） | `/etc/systemd/system/mihomo-dash-{panel,kernel}.service` | 是      | 是（不依赖 linger）                    |
+| `--user`               | `~/.config/systemd/user/…`                               | 否      | 需 `sudo loginctl enable-linger $USER` |
+
+macOS 只有用户级 LaunchAgent（`~/Library/LaunchAgents`，`gui/<uid>` 域），没有 system 域。
+日志：macOS 在 `~/.config/mihomo-dash/{daemon,kernel}.log`，Debian 在 `journalctl`（`--user` 视作用域）。
+
+## 面板功能
+
+| 路由           | 页面     | 能力                                                                                                                       |
+| -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `/`            | 概览     | 内核信息条、代理概览（订阅/策略组/节点/可用节点）、累计流量 / 活动连接 / 内存占用读数、上下行速率 60s 趋势                 |
+| `/proxies`     | 节点     | 策略组切换与增删改、节点测速、订阅增删/更新/健康检查、每条订阅的「拉取出口」（走哪个策略组 / 节点去拉，直连常被墙）        |
+| `/connections` | 连接     | 连接表、单个/全部关闭、host 搜索                                                                                           |
+| `/rules`       | 规则     | 两张卡片：自定义规则（`DOMAIN-SUFFIX` 增删）+ 系统规则（固定 7 条 GEOSITE/MATCH 启停与选目标）                             |
+| `/logs`        | 日志     | 实时日志流（关键字 / 级别过滤、暂停、自动滚动）                                                                            |
+| `/config`      | 配置     | 快捷设置（allow-lan / log-level / unified-delay / tcp-concurrent / find-process-mode）、GEO 数据库展示与配置、系统代理开关 |
+| `/config-file` | 配置文件 | CodeMirror 直接编辑 `config.yaml` 源文件                                                                                   |
+| `/kernel`      | 内核     | 面板自有内核：上传安装包（.gz / .zip）安装与升级、卸载、日志（进程启停 / 重启在侧栏底部）                                  |
+
+设计要点：
+
+- **REST 走后端转发**：`/api/kernel/*` 透明转发内核控制接口，并从 `config.yaml` 读 `secret` 自动附加 `Authorization`，内核错误统一转 502。
+- **内核的装 / 升 / 卸只在面板**，且**面板不联网**：安装包要自己从官方 release 页面下好再上传。面板只认自己的落点 `bin/mihomo`，不去探测（也不会去碰）系统上别的位置的内核。
+- **WebSocket 直连内核**：前端直连内核 `ws://<内核>` 的 `/traffic` `/memory` `/logs` `/connections`，不经后端中转。
+- **配置写入只在后端**：订阅、策略组、快捷设置、自定义规则、`default-selected` 均文本级改写对应段落/键以保留注释；GEO 项不在内核 `PATCH /configs` schema 内，改完走整包热重载。
+- **顶层键按固定顺序落盘**：面板每次写 `config.yaml`（含「配置文件」页保存）都会把顶层键排一遍 —— 基础运行 → 控制接口 → GEO → 内核行为 → 代理与分组 → 规则；只搬整块、不动内容与注释，面板不认识的键排在 `rules` 前面。
+- **进程启停是进程级**：「启动 / 重启 / 停止内核」（侧栏底部）都 detached 拉起 / 停掉内核子进程，PID 会变；内核自带的 `POST /restart`（exec 重启、PID 不变）面板前端不再调用。
+- **开机自启在 CLI（`mihomo-dash service …`）**：只开机拉起一次、不保活（崩了不重拉，停了就是真停）；**安装 / 卸载都不动正在跑的进程**（否则会把正在服务这个页面的面板自己杀掉），已装载的服务只更新定义、下次登录生效。要停进程仍是侧栏的「停止内核」/ 服务管理器（`systemctl --user stop …` 或 launchd）。
+
+## 环境变量
+
+| 变量              | 说明                                                                                                                                  |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `MIHOMO_DIR`      | 内核配置目录的显式覆盖（不设就用 `~/.config/mihomo-dash/data`；面板不再自动扫别处的 mihomo 目录）                                     |
+| `MIHOMO_DASH_DIR` | 状态目录（默认 `~/.config/mihomo-dash`）：内核管理文件（`bin/`、`data/`、`kernels.json`、`kernel.pid`、`kernel.log`）与自启服务的日志 |
+
+## 开发
+
+```bash
+npm install            # 根：后端运行时 + 工具链
+npm --prefix web install  # 前端依赖（React / antd / vite / vitest）
+npm run setup          # 上面两条的合体
+npm run dev            # vite(5173) + 面板(8981)，vite 已代理 /api
+npm run build          # 构建前端 → web/dist
+npm test               # node --test（桩内核，不依赖真实 mihomo）
+npm run lint
+npm run format
+```
+
+架构与 API 细节见 [AGENTS.md](./AGENTS.md)。
+
+## 安全边界
+
+- 面板默认只监听 `127.0.0.1`，**没有任何鉴权**（token 鉴权未实现，也没有对应环境变量），因此仅适合本机使用；要暴露到局域网得自己在前面加一层带鉴权的反代。
+- **不校验 `Host` / `Origin`**（2026-11 明示决定：不加鉴权，也不加 Host 白名单）。这意味着本机上的任意网页都可能借 **DNS 重绑定**直接调这些 API —— 装开机自启、上传并执行内核二进制、开关系统代理都在其中。所以别在开着面板时停留/操作不可信页面；这台机器上但凡有人能让你打开一个网页，就能操作这个面板。
+- 文件读写限定在内核配置目录内（`MIHOMO_DIR` 覆盖 > `~/.config/mihomo-dash/data`），路径 resolve 白名单防目录穿越。
+
+## License
+
+[MIT](./LICENSE)

package/bin/mihomo-dash.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../server/src/cli/index.js';
+
+main(process.argv.slice(2));

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@lancewu602/mihomo-dash",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.6.1",
+  "description": "mihomo 管理工具：CLI + 守护进程 + Web 面板",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lancewu602/mihomo-dash.git"
+  },
+  "homepage": "https://github.com/lancewu602/mihomo-dash#readme",
+  "bugs": "https://github.com/lancewu602/mihomo-dash/issues",
+  "keywords": [
+    "mihomo",
+    "clash",
+    "clash-meta",
+    "proxy",
+    "cli",
+    "panel"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "mihomo-dash": "bin/mihomo-dash.js"
+  },
+  "files": [
+    "bin",
+    "server",
+    "web/dist"
+  ],
+  "scripts": {
+    "setup": "npm install && npm --prefix web install",
+    "dev": "npm --prefix server run dev & npm --prefix web run dev & wait",
+    "api": "npm --prefix server run dev",
+    "web": "npm --prefix web run dev",
+    "build": "npm --prefix web run build",
+    "serve": "npm run build && node bin/mihomo-dash-runner.js panel",
+    "test": "npm --prefix server test && npm --prefix web test",
+    "typecheck": "npm --prefix server run typecheck && npm --prefix web run typecheck",
+    "lint": "eslint . --max-warnings 0",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "check": "npm run format:check && npm run typecheck && npm run lint && npm test",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run check"
+  },
+  "dependencies": {
+    "express": "^4.21.2",
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.18.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.20.5",
+    "eslint": "^9.18.0",
+    "eslint-config-prettier": "^10.0.1",
+    "eslint-plugin-react-hooks": "^5.1.0",
+    "eslint-plugin-react-refresh": "^0.4.18",
+    "globals": "^15.14.0",
+    "prettier": "^3.4.2",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.21.0"
+  }
+}

package/server/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog — mihomo-dash-server
+
+本文件记录后端（CLI / HTTP / 内核管理）能力。跨端条目两端都写；前端见 `../web/CHANGELOG.md`。
+只维护一个 `## [Unreleased]` 段，每条一行，用现在时描述系统具备的能力。
+
+## [Unreleased]
+
+## [0.6.1] - 2026-10-31
+
+### 修复
+
+- CLI 与生成的服务定义里不再提「自启」页：`status` 的提示改为 `mihomo-dash service install`，
+  unit 头注释改为「由 `mihomo-dash service install` 生成」；`--help` 里 Debian 作用域不再只写 `--user`
+
+## [0.6.0] - 2026-10-31
+
+### 新功能
+
+- `/api/service` 下线：开机自启的装/卸/状态只在 CLI（`mihomo-dash service …`），面板不再提供「自启」页
+
+- 面板进程不再由自带守护进程管理：交给系统服务管理器（macOS launchd / Linux systemd --user），
+  服务定义直接指向两个入口（`server/src/index.js` 与 `server/src/kernel/run.js`），
+  在面板「自启」页一键安装；**升级后已装的自启服务要重装一次**
+- `GET /api/health` 返回进程事实（版本 / pid / uptime / 启动时间），供 `status`、`doctor`、
+  `open` 与面板「自启」页探活
+- CLI 面收敛成 `status` + `service`：新增 `service print|install|uninstall|status`；
+  **Debian 默认装 system 单元**（`/etc/systemd/system`，要 root，开机即起），`--user` 走
+  `~/.config/systemd/user`（不需要 root，开机即起靠 linger）；macOS 固定用户级 LaunchAgent；
+  安装 / 卸载都不停正在跑的进程；
+  `daemon` / `serve` / `doctor` / `open` 子命令全部移除；不带参数仍是 `status`
+- `status` 与 `doctor` 的面板那一行改探 `/api/health`：不再读 pid 文件，也就没有
+  「进程被 kill -9 后残留 pid」与「pid 复用误判」两种假象
+- `server/src/index.js` 成为后端入口（`runPanel()`）：手动起与服务管理器拉起走同一条代码路径
+
+### 工程
+
+- npm 包名改成 `@lancewu602/mihomo-dash`（scoped；命令名仍是 `mihomo-dash`）：workflow 的 publish 带
+  `--access public`；这是一个新包名，需要重新本地占名并给新包名配可信发布者
+
+- 目录按 deck 对齐：`bin/` + `server/src/{cli,http,kernel,shared}` + `server/tests/`；
+  `server/` 与 `web/` 各有一份 `package.json`（`private`，各自锁文件），根 `package.json` 只留
+  `express` / `js-yaml` 与工具链
+- 删除 `server/src/daemon/`（pid / meta / detached 拉起 / 日志那一层），内核启停保留在 `server/src/kernel/`
+- 删除 `bin/mihomo-dash-runner.js` 与 `server/src/cli/runner.js`：服务定义直接指向真实入口，
+  `bin/` 只剩 CLI（与 deck 一致）
+- 测试搬到 `server/tests/`，内核起停的等待间隔可用 `MIHOMO_DASH_READY_INTERVAL_MS` /
+  `MIHOMO_DASH_STOP_INTERVAL_MS` 调小（默认行为不变），装/卸内核的用例从等固定 100ms 改成轮询
+- 工具配置收在根一份：`eslint.config.mjs`（React 规则按 `files` 限定到 `web/**`）、
+  `.prettierrc.json` / `.prettierignore` / `.editorconfig`；`check` 脚本串起
+  格式检查 + 类型检查 + lint + 测试
+- `server/tsconfig.json`：JS + JSDoc 的编辑器解析配置（`checkJs` 关着，打开会有 900+ 条历史错误）

package/server/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "mihomo-dash-server",
+  "version": "0.6.1",
+  "private": true,
+  "type": "module",
+  "description": "mihomo-dash 后端源码（作为 mihomo-dash 的一部分发布，不单独发包）",
+  "scripts": {
+    "start": "node src/index.js",
+    "dev": "node --watch src/index.js",
+    "test": "node --test tests/*.test.js",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/server/src/cli/index.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/** mihomo-dash 入口：子命令分发与异常兜底。不带参数 = status。 */
+import { createRequire } from 'node:module';
+import { parseArgs } from '../shared/args.js';
+import { cmdStatus } from './status.js';
+import { cmdService, serviceHelp } from './service.js';
+
+const require = createRequire(import.meta.url);
+const { version: PKG_VERSION } = require('../../../package.json');
+
+/** `--port` / `--host` 指定要探的面板（默认 127.0.0.1:8981） */
+function panelTargetFromFlags(flags) {
+  const target = {};
+  const port = Number(flags.port);
+  if (Number.isFinite(port) && port > 0) target.port = port;
+  if (typeof flags.host === 'string') target.host = flags.host;
+  return target;
+}
+
+const HELP = `mihomo-dash —— mihomo 管理工具：CLI + Web 面板
+
+用法: mihomo-dash [命令]
+
+  status              总览：内核 / 面板 / 系统代理 / 开机自启（默认命令；内核不通时退出码 1）
+  service <子命令>    开机自启：print / install / uninstall / status（macOS launchd · Debian systemd）
+
+  -V, --version       版本
+  -h, --help          帮助
+
+  面板进程不再由自带的守护进程管理：交给系统服务管理器，服务定义指向 server/src/index.js（面板）
+  与 server/src/kernel/run.js（内核），开机自启用上面的 service 子命令。
+  内核的装 / 升 / 卸用面板的「内核」页，进程启停在侧栏底部；系统代理开关也不在 CLI（用面板顶栏的
+  胶囊开关或配置页的「系统代理」卡片）。（面板默认 http://127.0.0.1:8981）
+
+${serviceHelp()}`;
+
+export async function main(argv) {
+  const [cmd, ...rest] = argv;
+  const { positionals, flags } = parseArgs(rest);
+
+  if (cmd === '--version' || cmd === '-V' || flags.version === true) {
+    console.log(`mihomo-dash ${PKG_VERSION}`);
+    return;
+  }
+  if (flags.help || cmd === '--help' || cmd === '-h') {
+    console.log(HELP);
+    return;
+  }
+
+  try {
+    switch (cmd) {
+      case undefined:
+      case 'status':
+        await cmdStatus(panelTargetFromFlags(flags));
+        break;
+      case 'kernel':
+        console.error(
+          'kernel 子命令已移除：内核的装 / 升 / 卸改到面板的「内核」页，进程启停改到侧栏底部',
+        );
+        process.exit(2);
+        break;
+      case 'service': {
+        const code = await cmdService(positionals, flags);
+        if (code !== 0) process.exit(code);
+        break;
+      }
+      default:
+        console.error(`未知命令: ${cmd}\n\n${HELP}`);
+        process.exit(2);
+    }
+  } catch (err) {
+    console.error(`错误: ${err?.message || err}`);
+    process.exit(1);
+  }
+}

package/server/src/cli/service.js

@@ -0,0 +1,167 @@
+/**
+ * `mihomo-dash service <print|install|uninstall|status>`：开机自启的命令行入口。
+ *
+ * 与 deck 的 `deck service …` 思路一致（把「装服务定义」这件事从面板搬到脚本），
+ * 但平台面不一样，**不要照抄 deck 的实现**：
+ *
+ * - deck 只跑 Linux + **system** 单元（`/etc/systemd/system`，要 root）；
+ * - 这里要同时支持 **macOS（launchd 用户级）与 Debian（systemd system 与 --user 两种）**：
+ *   Debian 默认 system（要 root、开机即起），--user 是备选；macOS 只有用户级；
+ *   两个平台都交给 `createServiceManager()`（`server/src/shared/service.js`），CLI 只管打印结果。
+ * - 两个 job：`panel`（server/src/index.js）与 `kernel`（server/src/kernel/run.js）。
+ *
+ * 行为约定：**装/卸都不停正在跑的进程**（这个面板很可能正是被服务拉起来的），
+ * 「只开机拉起一次、不保活」（launchd 不写 KeepAlive、systemd 写 Restart=no）。
+ */
+import { ownKernelRunning } from '../kernel/lifecycle.js';
+import { parseArgs, parsePort } from '../shared/args.js';
+import { probePanel } from '../shared/panel.js';
+import { DEFAULT_HOST, DEFAULT_PORT } from '../shared/paths.js';
+import { SERVICE_JOBS, createServiceManager } from '../shared/service.js';
+
+const ACTIONS = ['print', 'install', 'uninstall', 'status'];
+
+const HELP = `用法: mihomo-dash service <子命令> [--port <端口>] [--host <地址>] [--system|--user]
+
+  print [panel|kernel]   打印服务定义（macOS 是 launchd plist，Debian 是 systemd 单元）
+  install                安装两个服务定义并装载（不会停正在跑的进程）
+  uninstall              卸载两个服务定义（不 --now、不 bootout，正在跑的进程不动）
+  status                 各 job 的定义/装载/运行状态
+
+  作用域（只对 Debian 有意义）：
+    --system             写 /etc/systemd/system，systemctl enable --now，**开机即起、不依赖 linger**
+                         ——这是默认值，**需要 root**
+    --user               写 ~/.config/systemd/user，不需要 root；要开机即起得 sudo loginctl enable-linger
+  macOS 只有用户级 LaunchAgent（gui/<uid> 域），没有 system 域。
+
+  日志：macOS 写 ~/.config/mihomo-dash/{daemon,kernel}.log · Debian 走 journalctl`;
+
+/**
+ * @param {string[]} positionals
+ * @param {Record<string, string|boolean>} flags
+ * 返回值是**退出码**（0 成功 / 1 平台不支持或有错误 / 2 参数不认识），不在这里 `process.exit`：
+ * 这样同进程里能测，退出由 `index.js` 统一做。
+ * @param {{ manager?: ReturnType<typeof createServiceManager>, out?: (line: string) => void }} [deps]
+ *   测试可注入桩 manager 与输出
+ * @returns {Promise<number>}
+ */
+export async function cmdService(positionals, flags, deps = {}) {
+  const [action, ...rest] = positionals;
+  const out = deps.out || ((line) => console.log(line));
+
+  // 作用域：--system / --user 二选一；不传时交给 manager 决定（Debian 是 root 就 system）
+  const wantSystem = flags.system === true;
+  const wantUser = flags.user === true;
+  if (wantSystem && wantUser) {
+    console.error('--system 与 --user 只能选一个');
+    return 2;
+  }
+  const scope = wantSystem ? 'system' : wantUser ? 'user' : undefined;
+  if (scope === 'system') {
+    const isRoot = (process.getuid?.() ?? -1) === 0;
+    if (process.platform === 'darwin') {
+      console.error('macOS 没有 system 域：开机自启固定用用户级 LaunchAgent（不要传 --system）');
+      return 2;
+    }
+    if (!isRoot) {
+      console.error(
+        '--system 要 root：sudo mihomo-dash service install --system（或去掉 --system 用用户级）',
+      );
+      return 1;
+    }
+  }
+
+  const manager = deps.manager || createServiceManager({ scope });
+
+  if (!ACTIONS.includes(action)) {
+    console.error(
+      `未知的 service 子命令：${action || '(缺省)'}；可用：${ACTIONS.join(' / ')}\n\n${HELP}`,
+    );
+    return 2;
+  }
+
+  const port = parsePort(flags.port, DEFAULT_PORT);
+  const host = typeof flags.host === 'string' ? flags.host : DEFAULT_HOST;
+
+  if (action === 'print') {
+    const only = rest[0];
+    if (only && !SERVICE_JOBS.includes(only)) {
+      console.error(`未知的 job：${only}（只能是 ${SERVICE_JOBS.join(' / ')}）`);
+      return 2;
+    }
+    const jobs = only ? [only] : SERVICE_JOBS;
+    for (const job of jobs) {
+      out(`# ${job}`);
+      out(manager.render(job, { port, host, scope: manager.scope }));
+    }
+    return 0;
+  }
+
+  if (action === 'install') {
+    // 正在手跑的 job 要告诉 manager：Linux 侧会只 enable 不 --now，免得留一个注定失败的单元
+    const manualRunning = [];
+    if ((await probePanel({ host, port })).running) manualRunning.push('panel');
+    if (ownKernelRunning().running) manualRunning.push('kernel');
+
+    const res = await manager.install({ port, host, manualRunning });
+    if (!res.supported) {
+      out(`本平台不支持：${res.hint}`);
+      return 1;
+    }
+    out(`平台：${manager.platform} · 作用域：${manager.scope} · 定义目录：${manager.dir}`);
+    for (const file of res.files) out(`已写入 ${file}`);
+    for (const action of res.actions) out(`· ${action}`);
+    for (const note of res.notes) out(`注意：${note}`);
+    for (const error of res.errors) out(`失败：${error}`);
+    if (res.errors.length > 0) return 1;
+    out('已安装。只开机拉起一次、不保活；要停止用面板侧栏的「停止内核」/ 服务管理器。');
+    return 0;
+  }
+
+  if (action === 'uninstall') {
+    const res = await manager.uninstall();
+    if (!res.supported) {
+      out(`本平台不支持：${res.hint}`);
+      return 1;
+    }
+    for (const file of res.removed) out(`已删除 ${file}`);
+    for (const action of res.actions) out(`· ${action}`);
+    for (const note of res.notes) out(`注意：${note}`);
+    for (const error of res.errors) out(`失败：${error}`);
+    return res.errors.length > 0 ? 1 : 0;
+  }
+
+  const res = await manager.status();
+  if (!res.supported) {
+    out(`本平台不支持：${res.hint}`);
+    return 1;
+  }
+  const statusScope = res.scope || 'user';
+  out(`平台：${res.platform} · 作用域：${statusScope} · 定义目录：${res.dir}`);
+  for (const job of res.jobs) {
+    const state = job.running ? 'running' : job.loaded ? 'loaded' : 'not loaded';
+    out(
+      `${job.job.padEnd(6)} ${job.installed ? '已安装' : '未安装'} · ${state}` +
+        (job.pid ? ` · pid ${job.pid}` : '') +
+        ` · ${job.file}`,
+    );
+  }
+  if (res.platform === 'linux' && statusScope === 'user') {
+    out(
+      res.linger
+        ? 'linger 已开启：开机即起（无需登录）'
+        : 'linger 未开启：只在登录后启动；要开机即起跑 sudo loginctl enable-linger $USER',
+    );
+  }
+  return 0;
+}
+
+/** 供 `--help` 复用 */
+export function serviceHelp() {
+  return HELP;
+}
+
+/** 解析 `service` 后面的参数（index.js 里只做分发，解析放这里便于单测） */
+export function parseServiceArgs(argv) {
+  return parseArgs(argv);
+}