From d46dc90f2e97c201998fcd47290901bcd4cbbf6f Mon Sep 17 00:00:00 2001
From: LM <me@lonelyman.site>
Date: Fri, 23 Oct 2026 14:21:52 +0800
Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20feat(service):=20=E6=96=B0=E5=A2=9E?=
 =?UTF-8?q?=20sctl=20service=EF=BC=8C=E6=8A=8A=20serve=20=E6=B3=A8?=
 =?UTF-8?q?=E5=86=8C=E4=B8=BA=E7=94=A8=E6=88=B7=E7=BA=A7=E7=B3=BB=E7=BB=9F?=
 =?UTF-8?q?=E6=9C=8D=E5=8A=A1?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

sctl serve 只能前台运行，文档让用户自己配置服务管理器却不提供工具，手写定义还容易
和 CLI 的数据目录、监听地址对不上。

- sctl service install|uninstall|start|stop|restart|status：macOS launchd LaunchAgent、
  Linux systemd --user、Windows 登录触发的计划任务，不需要管理员权限
- install 固化当前生效的 --data-dir（绝对路径）、--listen-address、非默认 --log-level；
  二进制优先用 PATH 里的同一文件，Homebrew 升级后不失效
- 隐藏参数 serve --service：日志只写文件；Windows 上脱离独占的控制台
- 等 daemon 时以控制令牌变化识别新进程；安装前和 start 前遇到已在运行的 daemon 时不启动服务
- schtasks / launchctl 只把非零退出当作“不存在”，命令本身无法运行时如实报错
- spec：docs/specs/2026-10-23-service.md
---
 README.md                               |   4 +-
 docs/README_zh-CN.md                    |   4 +-
 docs/architecture.md                    |   6 +-
 docs/cli.md                             |  39 ++-
 docs/mcp.md                             |   4 +-
 docs/specs/2026-10-23-service.md        | 114 +++++++
 internal/cli/cli.go                     |   9 +-
 internal/cli/console_other.go           |   6 +
 internal/cli/console_windows.go         |  25 ++
 internal/cli/serve.go                   |  15 +-
 internal/cli/service.go                 | 265 ++++++++++++++++
 internal/cli/service_test.go            | 274 ++++++++++++++++
 internal/client/control/client.go       |  24 +-
 internal/client/service/launchd.go      | 188 +++++++++++
 internal/client/service/schtasks.go     | 203 ++++++++++++
 internal/client/service/service.go      | 161 ++++++++++
 internal/client/service/service_test.go | 400 ++++++++++++++++++++++++
 internal/client/service/systemd.go      | 100 ++++++
 internal/pkg/logging/logging.go         |  18 +-
 internal/pkg/logging/logging_test.go    |  69 ++++
 skills/sctl/SKILL.md                    |   4 +-
 21 files changed, 1911 insertions(+), 21 deletions(-)
 create mode 100644 docs/specs/2026-10-23-service.md
 create mode 100644 internal/cli/console_other.go
 create mode 100644 internal/cli/console_windows.go
 create mode 100644 internal/cli/service.go
 create mode 100644 internal/cli/service_test.go
 create mode 100644 internal/client/service/launchd.go
 create mode 100644 internal/client/service/schtasks.go
 create mode 100644 internal/client/service/service.go
 create mode 100644 internal/client/service/service_test.go
 create mode 100644 internal/client/service/systemd.go
 create mode 100644 internal/pkg/logging/logging_test.go

diff --git a/README.md b/README.md
index 76910e0..1cb76b8 100644
--- a/README.md
+++ b/README.md
@@ -64,7 +64,8 @@ The install script verifies the release archive's sha256 and installs `sctl` int
 1. **Start the daemon** and leave it running:
 
    ```bash
-   sctl serve
+   sctl serve              # in a terminal, or
+   sctl service install    # in the background, starting at login
    ```
 
 2. **Pair the extensions.** `sctl connect` prints a one-time code; each code pairs one extension, so run it once
@@ -119,6 +120,7 @@ browser's logins; see [`docs/cli.md`](./docs/cli.md#endpoint-for-playwright-and-
 | Group | What it does |
 |---|---|
 | `sctl serve` / `connect` / `status` / `mcp` | Run the daemon, pair an extension, show connection status, serve MCP over stdio. |
+| `sctl service` | Run the daemon in the background as a user service (launchd, systemd, Task Scheduler). |
 | `sctl get` / `grep` / `install` / `edit` / `enable` / `disable` / `delete` | Manage ScriptCat userscripts. |
 | `sctl browsers` | List paired sctl Browser instances, or forget one. |
 | `sctl tabs` / `windows` / `groups` | Tabs, windows, and tab groups. |
diff --git a/docs/README_zh-CN.md b/docs/README_zh-CN.md
index 5ccdd8d..8dad2b8 100644
--- a/docs/README_zh-CN.md
+++ b/docs/README_zh-CN.md
@@ -58,7 +58,8 @@ irm https://raw.githubusercontent.com/scriptscat/sctl/main/scripts/install.ps1 |
 1. **启动 daemon** 并保持运行：
 
    ```bash
-   sctl serve
+   sctl serve              # 在终端里运行，或者
+   sctl service install    # 在后台运行，登录后自动启动
    ```
 
 2. **配对扩展。** `sctl connect` 打印一次性配对码；一个码只能配对一个扩展，每个扩展各运行一次。
@@ -109,6 +110,7 @@ ln -s "$PWD/skills/sctl" ~/.claude/skills/sctl
 | 命令组 | 用途 |
 |---|---|
 | `sctl serve` / `connect` / `status` / `mcp` | 运行 daemon、配对扩展、查看连接状态、通过 stdio 提供 MCP。 |
+| `sctl service` | 以用户服务的形式在后台运行 daemon（launchd、systemd、任务计划程序）。 |
 | `sctl get` / `grep` / `install` / `edit` / `enable` / `disable` / `delete` | 管理 ScriptCat 用户脚本。 |
 | `sctl browsers` | 列出已配对的 sctl Browser 实例，或忘记其中一个。 |
 | `sctl tabs` / `windows` / `groups` | 标签页、窗口和标签组。 |
diff --git a/docs/architecture.md b/docs/architecture.md
index ce616b7..ca5a564 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -18,7 +18,9 @@ CLI verbs (sctl get / edit / install / browsers / tabs / windows / page / debug
 `/control/*` HTTP/JSON control API on the daemon's listener — same port as the extensions' WS surface, separate
 path, authenticated with the control token described in [threat-model.md](./threat-model.md#4-the-control-channel-internal-local-connection-in-detail).
 Frontends never start `serve`: run it
-explicitly in the foreground or let an external system service manager own its lifecycle.
+explicitly in the foreground or let the user's system service manager own its lifecycle — `sctl service`
+(`internal/client/service`) writes that service definition and drives the manager's own commands, without
+talking to the daemon.
 
 The daemon accepts two kinds of extension connection at once: exactly one active ScriptCat connection (a new
 one replaces the previous one), and any number of paired `sctl Browser` instances connecting simultaneously,
@@ -140,6 +142,7 @@ cmd/sctl/main.go            # cobra entry point (unwraps ExitError → os.Exit)
 internal/cli/               # subcommand definitions; spans both sides, hence top level
   cli.go                    #   root command, global flags (-o/--output, --log-level), output helpers
   serve.go                  #   bootstraps the cago app and mounts the daemon Component
+  service.go                #   sctl service install|uninstall|start|stop|restart|status
   mcp.go                    #   sctl mcp (serves all tools; --name is an audit label)
   connect.go status.go version.go
   get.go grep.go            #   read verbs
@@ -175,6 +178,7 @@ internal/daemon/            # ── sctl serve side ──
 internal/client/            # ── sctl mcp / CLI verb side ──
   control/                  #   control API client, shared DTOs, control token
   mcpserver/                #   go-sdk stdio MCP server: all tools (flat trust), progress while waiting
+  service/                  #   user service definitions (launchd, systemd --user, Task Scheduler) and their commands
 
 internal/pkg/               # ── shared by both sides ──
   protocol/                 #   protocol.json authority plus generated language and business-schema artifacts
diff --git a/docs/cli.md b/docs/cli.md
index 98089f4..d773f32 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -11,7 +11,8 @@ command line can use the skill in [`../skills/sctl/`](../skills/sctl/SKILL.md).
 
 | Command | Purpose |
 |---|---|
-| `sctl serve` | Run the local bridge daemon. |
+| `sctl serve` | Run the local bridge daemon in the foreground. |
+| `sctl service install\|uninstall\|start\|stop\|restart\|status` | Run `sctl serve` in the background as a user service; see [Background service](#background-service-sctl-service). |
 | `sctl connect` | Open a one-time enrollment window for ScriptCat or sctl Browser. |
 | `sctl mcp [--name <label>]` | Serve ScriptCat and sctl Browser tools over stdio MCP. |
 | `sctl status` | Show daemon and extension connection status. |
@@ -127,6 +128,42 @@ Chrome's retention limit), and note on stderr when more remain.
 
 `--since` and `--until` accept an RFC 3339 time or a duration ago such as `7d`, `12h`, or `30m`.
 
+## Background service: `sctl service`
+
+`sctl service install` registers `sctl serve` with the current user's service manager, so the daemon starts at login;
+launchd and systemd also restart it after a crash. It needs no administrator rights and installs one service per user:
+
+| Platform | Service manager | Definition |
+|---|---|---|
+| macOS | launchd LaunchAgent | `~/Library/LaunchAgents/com.scriptscat.sctl.plist` |
+| Linux | systemd user instance | `~/.config/systemd/user/sctl.service` (under `$XDG_CONFIG_HOME` when set); runs while you are logged in |
+| Windows | Task Scheduler, triggered at your logon | task `\sctl`; a console window flashes briefly when it starts. Task Scheduler's retry is not known to cover a daemon that crashes after starting: run `sctl service start` |
+
+- **`install`** writes the definition, enables it at login, and starts it. The service runs the `sctl` binary you ran
+  `install` with (the one on `PATH` when it is the same file, so a Homebrew upgrade keeps working) together with the
+  `--data-dir` (as an absolute path, also when it comes from `SCTL_DATA_DIR`), `--listen-address`, and a non-default
+  `--log-level` in effect for that command, so pass the same ones you use with the other commands. Running it again
+  rewrites the definition and restarts the service, which is how to pick up a new binary, path, or flag. It refuses
+  when the service is not installed yet but a daemon answers at the address, even one using another data directory:
+  stop that daemon first, or the service keeps failing on the busy port.
+- **`start`** and **`restart`** start the installed service; **`stop`** stops it until you start it again or log in
+  next. All three exit 3 when the service is not installed. `start` does nothing when a daemon is already reachable
+  at the address, whether it is the service or one you started yourself.
+- **`install`**, **`start`**, and **`restart`** wait up to 10 seconds for the newly started daemon to become reachable
+  (recognized by the fresh control token it writes, so another daemon holding the port does not count) and exit 3,
+  naming the log directory, when it does not.
+- **`uninstall`** stops the service and removes the definition; it succeeds when nothing is installed.
+- **`status`** reports whether the service is installed, where its definition is, and whether a daemon is reachable
+  at the address. It exits 0 either way; add `-o json` for scripts.
+
+On macOS, a process started by launchd cannot read `~/Documents`, `~/Desktop`, or `~/Downloads` without a privacy
+permission and hangs there instead of starting, so keep the `sctl` binary and the data directory outside those folders
+(the install script's `~/.local/bin` and Homebrew's prefix are fine).
+
+Under the service, the daemon writes its log only to the files in `<data dir>/logs/`; the service manager receives
+nothing but crash output (macOS: `<data dir>/logs/service.stderr.log`, Linux: the user journal). Use either the
+service or `brew services`, not both: they run the same daemon on the same port.
+
 ## Page automation: `sctl page`
 
 ### Target tab and debugger attachment
diff --git a/docs/mcp.md b/docs/mcp.md
index 165eca5..2cbb5d6 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -97,8 +97,8 @@ sctl serve
 ```
 
 `sctl serve` is the only process that owns the WebSocket connection to ScriptCat. CLI commands and `sctl mcp`
-never start it automatically. For long-running use, configure the operating system's user service manager to
-run this exact command; service-manager-specific installation is outside this guide.
+never start it automatically. For long-running use, `sctl service install` runs it in the background as a user
+service that starts at login; see [`cli.md`](./cli.md#background-service-sctl-service).
 
 Before enrollment, this command should reach the daemon and report that no extension is connected:
 
diff --git a/docs/specs/2026-10-23-service.md b/docs/specs/2026-10-23-service.md
new file mode 100644
index 0000000..77837b2
--- /dev/null
+++ b/docs/specs/2026-10-23-service.md
@@ -0,0 +1,114 @@
+# 把 sctl serve 注册为用户级系统服务
+
+<!-- File: docs/specs/2026-10-23-service.md -->
+
+> Status: Draft
+> Owner: sctl maintainers
+> Last updated: 2026-10-23
+
+**目标：** 用户用一条 `sctl service install` 把 `sctl serve` 交给本机的用户级服务管理器（macOS launchd、Linux systemd
+用户实例、Windows 任务计划程序），登录后自动启动、崩溃后自动拉起，不再需要一个一直开着的终端。
+
+**不可退化的约束：**
+
+- `sctl serve` 在前台运行的行为不变；前端（`sctl mcp` 和 CLI 动词）仍然不会自己拉起 daemon。
+- stdout 只属于 CLI；服务下运行的 daemon 也不向 stdout 写任何东西。
+- 服务只装在当前用户名下，不需要管理员权限，不写系统级位置。
+
+## 问题
+
+1. **后台运行没有现成办法。** 已验证。`sctl serve` 只能在前台运行（`internal/cli/serve.go` 的注释：“命令始终在前台运行，
+   生命周期由调用方管理”）。[architecture.md](../architecture.md) 和 [mcp.md](../mcp.md) 让用户“交给系统服务管理器”，
+   但 mcp.md 明说“具体的服务管理器配置不在本指南范围内”。用户得自己写 plist、unit 或计划任务，还得知道要把
+   `--data-dir`、`--listen-address` 原样带进去。
+2. **手写的服务定义容易和 CLI 对不上。** 已验证。daemon 和 CLI 必须用同一个数据目录和监听地址
+   （README “Every sctl process must use the same data directory and listener address”）。服务管理器启动的进程拿不到
+   用户 shell 里的 `SCTL_DATA_DIR`，路径不一致时 CLI 读不到控制令牌。
+
+## 角色与用户故事
+
+1. 作为日常使用 sctl 的用户，我希望运行一条命令后 daemon 就一直在后台，开机登录也自动起来，这样不用每次开终端跑 `sctl serve`。
+2. 作为用自定义数据目录或端口的用户，我希望服务自动沿用我当前的 `--data-dir` / `--listen-address`，这样 CLI 和 MCP 不用额外配置。
+3. 作为升级了 sctl 的用户，我希望有一条命令让服务换上新二进制，这样不用手动找服务定义。
+
+## 设计决策
+
+| # | 决策 | 依据与被否方案 |
+|---|---|---|
+| 1 | 由 sctl 生成并注册服务定义，交给系统自己的服务管理器托管，sctl 不自己做守护进程。 | 用户决定（方案 A）。服务管理器负责登录自启和崩溃拉起。被否：`serve --detach` 自己脱离终端——重启后不在、也不会拉起；前端自动拉起 daemon——违背“前端不启动 serve”的设计。 |
+| 2 | 只做用户级服务：launchd 的 LaunchAgent、systemd `--user`、Windows 当前用户登录时触发的计划任务。 | 浏览器扩展、数据目录和控制令牌都属于当前用户。被否：Windows 服务——跑在 SYSTEM 账户下，数据目录和令牌对不上；systemd 系统服务——需要 root。 |
+| 3 | 不引入第三方服务库，三份定义模板和命令序列自己写。 | `kardianos/service` 在 Windows 上只支持系统服务，与决策 2 冲突；模板各几十行，生成函数是纯函数，容易测。 |
+| 4 | 每个用户只有一个 sctl 服务，名字固定：launchd 标签 `com.scriptscat.sctl`、systemd 单元 `sctl.service`、计划任务 `sctl`。 | 一个用户一个 daemon 是常态。被否：按数据目录生成不同名字——命令要多一个参数，收益很小。 |
+| 5 | 服务的命令行在安装时固化：二进制的绝对路径，加上本次调用实际生效的 `--data-dir`（转成绝对路径，来自参数或 `SCTL_DATA_DIR`）、`--listen-address`、非默认的 `--log-level`，最后是 `serve --service`。 | 服务管理器不继承用户 shell 的环境（问题 2）。 |
+| 6 | 二进制路径优先用 `PATH` 里的 `sctl`，前提是它和当前进程是同一个文件；否则用当前进程的路径。 | Homebrew 的 `bin/sctl` 是指向带版本号目录的符号链接，固化解析后的路径会在 `brew upgrade` 删掉旧版本后失效。 |
+| 7 | 服务的运行状态以“daemon 能不能连上”为准，不解析服务管理器的输出。 | `schtasks` 的状态文字随系统语言变化，`launchctl print` 的格式不保证稳定。能不能连上本来就是用户关心的事。 |
+| 8 | 新增隐藏参数 `serve --service`：日志只写文件，不再同时写 stderr；在 Windows 上，进程是控制台唯一的进程时脱离控制台。 | 文件日志已按大小滚动；stderr 交给服务管理器后，launchd 的输出文件不滚动，重复写一份会无限增长。stderr 只剩 Go 运行时的崩溃信息。Windows 上计划任务启动控制台程序会弹出窗口，脱离后窗口关闭（登录时会闪一下）。被否：编译成 GUI 子系统——CLI 就没有控制台输出了；`conhost --headless`——未公开的参数。 |
+
+## 命令
+
+所有子命令只操作本机的服务管理器，不经过 daemon 的控制 API。出错时退出码 3，消息说明原因；`-o json` 输出结构化结果。
+
+- **`sctl service install`**
+  - 写入服务定义，启用并立即启动；已经装过时覆盖定义并重启（升级、换路径、换参数都用它）。
+  - 还没装过、却已经有 daemon 在这个地址上能连上时拒绝：说明有一个服务以外的 daemon 在运行，先停掉它。
+    否则新服务会因为端口被占用而反复重启。
+  - 启动后最多等 10 秒让 daemon 能连上：连上时输出 daemon 地址；等不到时退出码 3，并给出日志目录。
+  - 输出服务定义的位置和固化的命令行。
+- **`sctl service uninstall`**：停止服务、取消登录自启、删除服务定义。没装过时也成功，并如实说明。
+- **`sctl service start` / `stop` / `restart`**：启动、停止、重启已安装的服务。没装过时退出码 3，提示先 `install`。
+  `start`、`restart` 和 `install` 一样等 daemon 能连上。`stop` 后服务在下次登录时仍会自动启动。`start` 时已经有 daemon
+  能连上就什么都不做（它要么就是服务，要么是占着端口的前台 daemon，再启动服务只会反复重启）。
+- **“等 daemon 能连上”的判定：** 能回答健康检查，且本数据目录的控制令牌与操作前不同。daemon 绑定端口后才写新令牌，
+  令牌变了才说明是服务新启动的进程；只看健康检查会把占着端口的别的 daemon 当成服务已启动。
+- **“已有 daemon”的判定（install、start 前）：** 只看健康检查，不要求本数据目录有令牌，另一个数据目录的 daemon 同样占着端口。
+- **`sctl service status`**：是否已安装、服务定义的位置、daemon 当前能不能连上。没装过时退出码 0，如实说明。固化的命令行只在 `install` 时输出：读回 Windows 计划任务的定义要解析随系统语言变化的输出，不值得。
+
+不支持的系统（三种之外）上，所有子命令退出码 3，说明不支持。
+
+## 各平台的服务定义
+
+| 平台 | 位置 | 要点 |
+|---|---|---|
+| macOS | `~/Library/LaunchAgents/com.scriptscat.sctl.plist` | `RunAtLoad`；不设 `ProcessType=Background`（会被系统节流，而 daemon 服务的是交互请求）；`KeepAlive` 只在非正常退出时拉起；stdout 指向 `/dev/null`，stderr 写 `<数据目录>/logs/service.stderr.log`。用 `launchctl bootstrap` / `bootout` / `kickstart` 管理 `gui/<uid>` 域。 |
+| Linux | `$XDG_CONFIG_HOME/systemd/user/sctl.service`（默认 `~/.config/systemd/user/`） | `Restart=on-failure`、`RestartSec=5`、`WantedBy=default.target`；按单元文件的绝对路径 `enable`（调用者 shell 与 systemd 用户实例的 `XDG_CONFIG_HOME` 可能不同）；stderr 由 journal 接收。用 `systemctl --user` 管理。用户服务只在用户登录期间运行，这与浏览器的生命周期一致。 |
+| Windows | 计划任务 `\sctl`，定义保存在任务计划程序里 | 当前用户登录时触发、以当前用户的交互令牌运行、不需要提权；取消默认的 72 小时运行上限和电池相关的停止条件；失败后每分钟重试、最多 999 次（任务计划程序的 `RestartOnFailure`；它是否覆盖进程以非零码退出，未在真机上确认）；已在运行时 `/Run` 先停掉旧实例再启动（`StopExisting`），重启与覆盖安装都靠它，不先 `/End` 再赌时序。用 `schtasks /Create /XML`、`/Run`、`/End`、`/Delete`、`/Query` 管理。 |
+
+macOS 上 launchd 启动的进程没有隐私授权时读不了 `~/Documents`、`~/Desktop`、`~/Downloads`，会卡住而不是启动
+（真机验证中二进制放在 `~/Documents` 下时复现：进程在运行，但既不监听也不写日志）。文档提示把二进制和数据目录放在这些目录之外。
+
+服务定义中的路径和参数按各自格式转义（plist 和任务 XML 按 XML 转义，systemd 按 `ExecStart` 的引号与 `%` 规则）。
+
+## 安全与隐私
+
+- 服务定义里只有二进制路径、数据目录、监听地址和日志级别，不含密钥或令牌。定义文件写在当前用户的目录里，
+  能改它的人本来就能以这个用户身份运行程序，因此不进入[威胁模型](../threat-model.md)的凭据清单。
+- daemon 在服务下运行时的监听地址与前台运行相同（默认 127.0.0.1），威胁模型不变。
+
+## 不在本期范围
+
+- `serve --detach` 和前端自动拉起 daemon（决策 1）。
+- 系统级服务、Windows 服务（决策 2）。
+- Homebrew 的 `brew services`：需要改外部的 tap 仓库；与 `sctl service` 同时使用会争同一个端口，文档提示二选一。
+- 同一用户装多个 sctl 服务（决策 4）。
+
+## 文档
+
+- **[cli.md](../cli.md)：** `sctl service` 各子命令的行为、平台差异、与前台 `serve` 和 `brew services` 的关系。
+- **[mcp.md](../mcp.md)：** 去掉“服务管理器配置不在本指南范围内”，改为链接 `sctl service install`。
+- **[architecture.md](../architecture.md)：** 进程模型里“交给外部服务管理器”一句加上 `sctl service`；目录布局加上新文件。
+- **README.md 与 README_zh-CN.md：** 快速开始第 1 步提到 `sctl service install`；命令表加上 `sctl service`。
+
+## 测试决策
+
+| 测试层 | 验证什么 | 可参照的现有测试 |
+|---|---|---|
+| 服务包单元测试（纯函数 + 假的命令执行器） | 三种定义的生成内容（含路径里有空格、`%`、`&` 时的转义）；install / uninstall / start / stop / restart 发出的命令序列，以及“已加载 / 未加载”“未安装”这些分支；二进制路径选择（`PATH` 里是同一个文件 / 不是 / 找不到） | `internal/pkg/fsutil` 的测试风格 |
+| CLI 测试 | 固化的命令行（数据目录转绝对路径、只带非默认参数）；未安装时 start 退出码 3、status 退出码 0；install 前已有 daemon 时拒绝；等不到 daemon 时退出码 3 | `internal/cli/browsers_test.go` |
+| 日志单元测试 | 服务模式下日志不写 stderr、照常写文件；文件目录不可写时退回 stderr | `internal/pkg/logging` |
+| 一次性真机验证，放在 `e2e/scratch/`，不提交 | macOS 上 install → daemon 能连上 → kill 后被拉起 → stop → start → restart → uninstall 后定义删除；隔离数据目录与端口 | [verification.md](../verification.md) |
+
+Linux 和 Windows 的服务管理器无法在开发机上真机验证，只有单元测试覆盖生成内容和命令序列，PR 里如实说明。
+
+## 未决问题
+
+无。
diff --git a/internal/cli/cli.go b/internal/cli/cli.go
index 49f7b49..8b92f6d 100644
--- a/internal/cli/cli.go
+++ b/internal/cli/cli.go
@@ -25,6 +25,9 @@ var (
 	BuildDate = "unknown"
 )
 
+// defaultLogLevel 是 --log-level 的默认值;`sctl service install` 只固化与它不同的级别。
+const defaultLogLevel = "info"
+
 // 全局标志(绑定为包级变量,任意子命令直接读取)。
 var (
 	outputFormat  string
@@ -68,7 +71,8 @@ func NewRootCmd() *cobra.Command {
 		PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
 			paths.SetDataDir(dataDir)
 			control.SetAddress(listenAddress)
-			logging.Setup(logLevel)
+			// 服务管理器托管的 serve 只写文件日志,见 internal/pkg/logging。
+			logging.Setup(logLevel, !serveAsService)
 			switch outputFormat {
 			case outputTable, outputJSON, outputSource:
 			default:
@@ -82,12 +86,13 @@ func NewRootCmd() *cobra.Command {
 			return nil
 		},
 	}
-	root.PersistentFlags().StringVar(&logLevel, "log-level", "info", "log level: debug|info|warn|error (always written to stderr)")
+	root.PersistentFlags().StringVar(&logLevel, "log-level", defaultLogLevel, "log level: debug|info|warn|error (written to stderr and <data dir>/logs; only to the files under sctl service)")
 	root.PersistentFlags().StringVar(&dataDir, "data-dir", os.Getenv("SCTL_DATA_DIR"), "data directory for keys, control token and logs (env: SCTL_DATA_DIR)")
 	root.PersistentFlags().StringVar(&listenAddress, "listen-address", "", "address used by sctl serve and commands that connect to it (default 127.0.0.1:8643)")
 	root.PersistentFlags().StringVarP(&outputFormat, "output", "o", outputTable, "output format: table|json|source (source only valid for \"get <uuid>\")")
 	root.AddCommand(
 		newServeCmd(),
+		newServiceCmd(),
 		newMcpCmd(),
 		newConnectCmd(),
 		newStatusCmd(),
diff --git a/internal/cli/console_other.go b/internal/cli/console_other.go
new file mode 100644
index 0000000..65c0830
--- /dev/null
+++ b/internal/cli/console_other.go
@@ -0,0 +1,6 @@
+//go:build !windows
+
+package cli
+
+// detachConsole 只在 Windows 上有事可做:其他平台的服务管理器启动的进程本来就没有终端窗口。
+func detachConsole() {}
diff --git a/internal/cli/console_windows.go b/internal/cli/console_windows.go
new file mode 100644
index 0000000..9186bcf
--- /dev/null
+++ b/internal/cli/console_windows.go
@@ -0,0 +1,25 @@
+package cli
+
+import (
+	"unsafe"
+
+	"golang.org/x/sys/windows"
+)
+
+var (
+	kernel32                  = windows.NewLazySystemDLL("kernel32.dll")
+	procGetConsoleProcessList = kernel32.NewProc("GetConsoleProcessList")
+	procFreeConsole           = kernel32.NewProc("FreeConsole")
+)
+
+// detachConsole 在本进程独占控制台时脱离它:计划任务启动控制台程序会弹出一个窗口,脱离后窗口随之关闭。
+// 控制台里还有别的进程(用户从终端手动运行)时保持不动,免得关掉用户的终端。脱离失败只意味着窗口留着,
+// daemon 照常工作,所以不当作错误。
+func detachConsole() {
+	var pids [2]uint32
+	n, _, _ := procGetConsoleProcessList.Call(uintptr(unsafe.Pointer(&pids[0])), uintptr(len(pids)))
+	if n != 1 {
+		return
+	}
+	_, _, _ = procFreeConsole.Call()
+}
diff --git a/internal/cli/serve.go b/internal/cli/serve.go
index bbf1224..d694b07 100644
--- a/internal/cli/serve.go
+++ b/internal/cli/serve.go
@@ -13,16 +13,23 @@ import (
 	"github.com/scriptscat/sctl/internal/daemon"
 )
 
-// newServeCmd 引导 cago 应用并挂载桥接 Component。命令始终在前台运行,生命周期由调用方管理。
+// serveAsService 由隐藏参数 `serve --service` 设置,只出现在 `sctl service install` 写出的服务定义里。
+var serveAsService bool
+
+// newServeCmd 引导 cago 应用并挂载桥接 Component。命令始终在前台运行,生命周期由调用方
+// (用户的终端或 `sctl service` 注册的服务管理器)管理。
 //
 // 不使用 component.Core():cago 的 Core 把日志写 stdout,而桥接 daemon 的 stdout 需保持洁净;
 // 日志已由全局 stderr logger 承载。
 func newServeCmd() *cobra.Command {
-	return &cobra.Command{
+	cmd := &cobra.Command{
 		Use:   "serve",
 		Short: "Run the bridge daemon",
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()
+			if serveAsService {
+				detachConsole()
+			}
 			cfg, err := configs.NewConfig("sctl", configs.WithSource(emptyConfigSource{}))
 			if err != nil {
 				return err
@@ -33,6 +40,10 @@ func newServeCmd() *cobra.Command {
 				Start()
 		},
 	}
+	cmd.Flags().BoolVar(&serveAsService, "service", false, "run under a service manager: log to files only")
+	// 用户不需要直接使用;它属于 `sctl service install` 生成的服务定义。
+	_ = cmd.Flags().MarkHidden("service")
+	return cmd
 }
 
 // emptyConfigSource 是一个「无任何键」的 cago 配置源:所有 Scan 保持零值并返回 nil,
diff --git a/internal/cli/service.go b/internal/cli/service.go
new file mode 100644
index 0000000..088d0d7
--- /dev/null
+++ b/internal/cli/service.go
@@ -0,0 +1,265 @@
+package cli
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/spf13/cobra"
+
+	"github.com/scriptscat/sctl/internal/client/control"
+	"github.com/scriptscat/sctl/internal/client/service"
+	"github.com/scriptscat/sctl/internal/pkg/paths"
+)
+
+// 测试替换点:真实实现会调用系统的服务管理器、解析本进程路径、等真实 daemon 起来。
+var (
+	newServiceManager        = service.New
+	resolveServiceExecutable = service.ResolveExecutable
+	serviceReadyTimeout      = 10 * time.Second
+)
+
+// serviceStatus 是 `sctl service status -o json` 的输出。
+type serviceStatus struct {
+	Installed bool   `json:"installed"`
+	Location  string `json:"location"`
+	Address   string `json:"address"`
+	Running   bool   `json:"running"`
+}
+
+// newServiceCmd 构造 `sctl service`:把 serve 注册为当前用户的系统服务。只操作本机的服务管理器,
+// 不经过 daemon 的控制 API。
+func newServiceCmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "service",
+		Short: "Run sctl serve in the background as a user service (launchd, systemd --user, Task Scheduler)",
+	}
+	cmd.AddCommand(
+		&cobra.Command{
+			Use:   "install",
+			Short: "Install (or update) the service with the current --data-dir and --listen-address, then start it",
+			Args:  cobra.NoArgs,
+			RunE:  withServiceManager(runServiceInstall),
+		},
+		&cobra.Command{
+			Use:   "uninstall",
+			Short: "Stop the service and remove it",
+			Args:  cobra.NoArgs,
+			RunE:  withServiceManager(runServiceUninstall),
+		},
+		&cobra.Command{
+			Use:   "start",
+			Short: "Start the installed service",
+			Args:  cobra.NoArgs,
+			RunE:  withServiceManager(runServiceStart),
+		},
+		&cobra.Command{
+			Use:   "stop",
+			Short: "Stop the installed service (it starts again at the next login)",
+			Args:  cobra.NoArgs,
+			RunE: withServiceManager(func(cmd *cobra.Command, m service.Manager) error {
+				if err := m.Stop(cmd.Context()); err != nil {
+					return &ExitError{Code: exitError, Message: err.Error()}
+				}
+				fmt.Fprintln(os.Stdout, "service stopped")
+				return nil
+			}),
+		},
+		&cobra.Command{
+			Use:   "restart",
+			Short: "Restart the installed service",
+			Args:  cobra.NoArgs,
+			RunE: withServiceManager(func(cmd *cobra.Command, m service.Manager) error {
+				return serviceAction(cmd, m.Restart, "restarted")
+			}),
+		},
+		&cobra.Command{
+			Use:   "status",
+			Short: "Show whether the service is installed and whether the daemon is reachable",
+			Args:  cobra.NoArgs,
+			RunE:  withServiceManager(runServiceStatus),
+		},
+	)
+	return cmd
+}
+
+func withServiceManager(fn func(*cobra.Command, service.Manager) error) func(*cobra.Command, []string) error {
+	return func(cmd *cobra.Command, _ []string) error {
+		m, err := newServiceManager()
+		if err != nil {
+			return &ExitError{Code: exitError, Message: err.Error()}
+		}
+		return fn(cmd, m)
+	}
+}
+
+func runServiceInstall(cmd *cobra.Command, m service.Manager) error {
+	ctx := cmd.Context()
+	installed, err := m.Installed(ctx)
+	if err != nil {
+		return &ExitError{Code: exitError, Message: err.Error()}
+	}
+	address, err := control.Address()
+	if err != nil {
+		return &ExitError{Code: exitError, Message: err.Error()}
+	}
+	// 服务以外的 daemon 占着端口时,新服务只会因为端口冲突反复重启。只看健康检查:那个 daemon 的令牌
+	// 可能写在别的数据目录里。
+	if !installed && control.Healthy(ctx) {
+		return &ExitError{Code: exitError, Message: fmt.Sprintf("a daemon is already running at %s outside the service; stop it before installing", address)}
+	}
+	prog, err := serviceProgram()
+	if err != nil {
+		return &ExitError{Code: exitError, Message: err.Error()}
+	}
+	before := currentControlToken()
+	if err := m.Install(ctx, prog); err != nil {
+		return &ExitError{Code: exitError, Message: err.Error()}
+	}
+	if err := waitDaemon(ctx, address, before); err != nil {
+		return err
+	}
+	fmt.Fprintf(os.Stdout, "service installed: %s\ncommand: %s\ndaemon running at %s\n",
+		m.Location(), strings.Join(append([]string{prog.Executable}, prog.Args...), " "), address)
+	return nil
+}
+
+func runServiceUninstall(cmd *cobra.Command, m service.Manager) error {
+	existed, err := m.Uninstall(cmd.Context())
+	if err != nil {
+		return &ExitError{Code: exitError, Message: err.Error()}
+	}
+	if !existed {
+		fmt.Fprintln(os.Stdout, "service is not installed; nothing to remove")
+		return nil
+	}
+	fmt.Fprintf(os.Stdout, "service removed: %s\n", m.Location())
+	return nil
+}
+
+// runServiceStart 启动服务。已经有 daemon 能连上时什么都不做:它要么就是服务本身,要么是占着端口的
+// 前台 daemon——这时再启动服务只会让它因为端口冲突反复重启。
+func runServiceStart(cmd *cobra.Command, m service.Manager) error {
+	ctx := cmd.Context()
+	address, err := control.Address()
+	if err != nil {
+		return &ExitError{Code: exitError, Message: err.Error()}
+	}
+	if installed, err := m.Installed(ctx); err != nil {
+		return &ExitError{Code: exitError, Message: err.Error()}
+	} else if !installed {
+		return &ExitError{Code: exitError, Message: service.ErrNotInstalled.Error()}
+	}
+	if control.Healthy(ctx) {
+		fmt.Fprintf(os.Stdout, "a daemon is already running at %s; nothing started\n", address)
+		return nil
+	}
+	return serviceAction(cmd, m.Start, "started")
+}
+
+// serviceAction 执行 start / restart,并等新启动的 daemon 能连上。
+func serviceAction(cmd *cobra.Command, action func(context.Context) error, done string) error {
+	ctx := cmd.Context()
+	address, err := control.Address()
+	if err != nil {
+		return &ExitError{Code: exitError, Message: err.Error()}
+	}
+	before := currentControlToken()
+	if err := action(ctx); err != nil {
+		return &ExitError{Code: exitError, Message: err.Error()}
+	}
+	if err := waitDaemon(ctx, address, before); err != nil {
+		return err
+	}
+	fmt.Fprintf(os.Stdout, "service %s; daemon running at %s\n", done, address)
+	return nil
+}
+
+func runServiceStatus(cmd *cobra.Command, m service.Manager) error {
+	ctx := cmd.Context()
+	installed, err := m.Installed(ctx)
+	if err != nil {
+		return &ExitError{Code: exitError, Message: err.Error()}
+	}
+	address, err := control.Address()
+	if err != nil {
+		return &ExitError{Code: exitError, Message: err.Error()}
+	}
+	st := serviceStatus{Installed: installed, Location: m.Location(), Address: address, Running: control.Healthy(ctx)}
+	if outputFormat == outputJSON {
+		return printValueJSON(st)
+	}
+	if installed {
+		fmt.Fprintf(os.Stdout, "service: installed (%s)\n", st.Location)
+	} else {
+		fmt.Fprintln(os.Stdout, "service: not installed")
+	}
+	if st.Running {
+		fmt.Fprintf(os.Stdout, "daemon: running at %s\n", address)
+	} else {
+		fmt.Fprintf(os.Stdout, "daemon: not reachable at %s\n", address)
+	}
+	return nil
+}
+
+// serviceProgram 固化本次调用实际生效的全局参数:服务管理器不继承用户 shell 的 SCTL_DATA_DIR,
+// 相对路径也会相对于服务管理器的工作目录解析。
+func serviceProgram() (service.Program, error) {
+	exe, err := resolveServiceExecutable()
+	if err != nil {
+		return service.Program{}, err
+	}
+	var args []string
+	if dataDir != "" {
+		abs, err := filepath.Abs(dataDir)
+		if err != nil {
+			return service.Program{}, err
+		}
+		args = append(args, "--data-dir", abs)
+	}
+	if listenAddress != "" {
+		args = append(args, "--listen-address", listenAddress)
+	}
+	if logLevel != defaultLogLevel {
+		args = append(args, "--log-level", logLevel)
+	}
+	logDir, err := filepath.Abs(paths.LogsDir())
+	if err != nil {
+		return service.Program{}, err
+	}
+	return service.Program{Executable: exe, Args: append(args, "serve", "--service"), LogDir: logDir}, nil
+}
+
+// currentControlToken 读取本数据目录当前的控制令牌,没有时为空。
+func currentControlToken() string {
+	tok, err := control.ReadControlToken()
+	if err != nil {
+		return ""
+	}
+	return tok
+}
+
+// waitDaemon 等服务新启动的 daemon 能连上。daemon 绑定端口后才写出新的控制令牌,所以令牌变了才说明是新进程:
+// 端口被别的 daemon 占着时健康检查照样成功,而服务自己正因为端口冲突反复重启。等不到时指向日志目录。
+func waitDaemon(ctx context.Context, address, tokenBefore string) error {
+	deadline := time.Now().Add(serviceReadyTimeout)
+	for {
+		if tok := currentControlToken(); tok != "" && tok != tokenBefore && control.Healthy(ctx) {
+			return nil
+		}
+		if time.Now().After(deadline) {
+			break
+		}
+		select {
+		case <-ctx.Done():
+			return &ExitError{Code: exitError, Message: ctx.Err().Error()}
+		case <-time.After(200 * time.Millisecond):
+		}
+	}
+	return &ExitError{Code: exitError, Message: fmt.Sprintf(
+		"the service started but its daemon is not reachable at %s after %s; another daemon may hold that address, or check the logs in %s",
+		address, serviceReadyTimeout, paths.LogsDir())}
+}
diff --git a/internal/cli/service_test.go b/internal/cli/service_test.go
new file mode 100644
index 0000000..6c7bed3
--- /dev/null
+++ b/internal/cli/service_test.go
@@ -0,0 +1,274 @@
+package cli
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	. "github.com/smartystreets/goconvey/convey"
+
+	"github.com/scriptscat/sctl/internal/client/control"
+	"github.com/scriptscat/sctl/internal/client/service"
+)
+
+// fakeServiceManager 记录安装的命令行;onInstall / onStart 模拟服务启动后 daemon 变得可连。
+type fakeServiceManager struct {
+	installed bool
+	program   *service.Program
+	calls     []string
+	onStart   func()
+}
+
+func (f *fakeServiceManager) Location() string { return "/fake/sctl.plist" }
+
+func (f *fakeServiceManager) Installed(context.Context) (bool, error) { return f.installed, nil }
+
+func (f *fakeServiceManager) Install(_ context.Context, p service.Program) error {
+	f.calls = append(f.calls, "install")
+	f.installed = true
+	f.program = &p
+	if f.onStart != nil {
+		f.onStart()
+	}
+	return nil
+}
+
+func (f *fakeServiceManager) Uninstall(context.Context) (bool, error) {
+	f.calls = append(f.calls, "uninstall")
+	existed := f.installed
+	f.installed = false
+	return existed, nil
+}
+
+func (f *fakeServiceManager) Start(context.Context) error {
+	f.calls = append(f.calls, "start")
+	if !f.installed {
+		return service.ErrNotInstalled
+	}
+	if f.onStart != nil {
+		f.onStart()
+	}
+	return nil
+}
+
+func (f *fakeServiceManager) Stop(context.Context) error {
+	f.calls = append(f.calls, "stop")
+	if !f.installed {
+		return service.ErrNotInstalled
+	}
+	return nil
+}
+
+func (f *fakeServiceManager) Restart(context.Context) error {
+	f.calls = append(f.calls, "restart")
+	if !f.installed {
+		return service.ErrNotInstalled
+	}
+	if f.onStart != nil {
+		f.onStart()
+	}
+	return nil
+}
+
+// stubServiceEnv 换上假的服务管理器与可执行路径,并起一个健康检查可开关的假 daemon。返回管理器和开关。
+func stubServiceEnv(t *testing.T) (*fakeServiceManager, *atomic.Bool) {
+	t.Helper()
+	ready := &atomic.Bool{}
+	mux := http.NewServeMux()
+	mux.HandleFunc(control.PathHealth, func(w http.ResponseWriter, _ *http.Request) {
+		if ready.Load() {
+			w.WriteHeader(http.StatusOK)
+			return
+		}
+		w.WriteHeader(http.StatusServiceUnavailable)
+	})
+	srv := httptest.NewServer(mux)
+	t.Cleanup(srv.Close)
+	t.Setenv("SCTL_BRIDGE_ADDR", strings.TrimPrefix(srv.URL, "http://"))
+	dir := t.TempDir()
+	t.Setenv("SCTL_DATA_DIR", dir)
+	So(os.WriteFile(filepath.Join(dir, "control.token"), []byte("tok"), 0o600), ShouldBeNil)
+
+	// 真实 daemon 每次启动都重新生成控制令牌;模拟服务起来时同样换一份。
+	starts := 0
+	m := &fakeServiceManager{onStart: func() {
+		starts++
+		So(os.WriteFile(filepath.Join(dir, "control.token"), []byte(fmt.Sprintf("tok-%d", starts)), 0o600), ShouldBeNil)
+		ready.Store(true)
+	}}
+	oldNew, oldExe, oldTimeout := newServiceManager, resolveServiceExecutable, serviceReadyTimeout
+	newServiceManager = func() (service.Manager, error) { return m, nil }
+	resolveServiceExecutable = func() (string, error) { return "/opt/bin/sctl", nil }
+	serviceReadyTimeout = 300 * time.Millisecond
+	t.Cleanup(func() {
+		newServiceManager, resolveServiceExecutable, serviceReadyTimeout = oldNew, oldExe, oldTimeout
+	})
+	return m, ready
+}
+
+func TestServiceInstall(t *testing.T) {
+	Convey("sctl service install", t, func() {
+		m, ready := stubServiceEnv(t)
+		address := os.Getenv("SCTL_BRIDGE_ADDR")
+
+		Convey("固化当前生效的数据目录(转成绝对路径)和监听地址,等 daemon 能连上后报告", func() {
+			wd := t.TempDir()
+			t.Chdir(wd)
+			So(os.MkdirAll("rel-data", 0o700), ShouldBeNil)
+			m.onStart = func() {
+				So(os.WriteFile(filepath.Join(wd, "rel-data", "control.token"), []byte("new"), 0o600), ShouldBeNil)
+				ready.Store(true)
+			}
+			code, out, errOut := runCLICapture("--data-dir", "rel-data", "service", "install")
+
+			So(errOut, ShouldBeEmpty)
+			So(code, ShouldEqual, exitOK)
+			So(m.program, ShouldNotBeNil)
+			So(m.program.Executable, ShouldEqual, "/opt/bin/sctl")
+			So(m.program.Args, ShouldResemble, []string{
+				"--data-dir", filepath.Join(wd, "rel-data"),
+				"--listen-address", address,
+				"serve", "--service",
+			})
+			So(m.program.LogDir, ShouldEqual, filepath.Join(wd, "rel-data", "logs"))
+			So(out, ShouldContainSubstring, "/fake/sctl.plist")
+			So(out, ShouldContainSubstring, address)
+		})
+
+		Convey("非默认的日志级别一并固化", func() {
+			code, _ := runCLI("--log-level", "debug", "service", "install")
+			So(code, ShouldEqual, exitOK)
+			So(m.program.Args, ShouldContain, "--log-level")
+			So(m.program.Args, ShouldContain, "debug")
+		})
+
+		Convey("还没装过却已有 daemon 能连上时拒绝,不安装", func() {
+			ready.Store(true)
+			code, _, errOut, err := runCLIResult(strings.NewReader(""), "service", "install")
+			So(code, ShouldEqual, exitError)
+			So(err.Error()+errOut, ShouldContainSubstring, "already running")
+			So(m.calls, ShouldBeEmpty)
+		})
+
+		Convey("还没装过、daemon 能连上但令牌不在本数据目录(另一个数据目录的 daemon)时同样拒绝", func() {
+			ready.Store(true)
+			So(os.Remove(filepath.Join(os.Getenv("SCTL_DATA_DIR"), "control.token")), ShouldBeNil)
+			code, _ := runCLI("service", "install")
+			So(code, ShouldEqual, exitError)
+			So(m.calls, ShouldBeEmpty)
+		})
+
+		Convey("已经装过、端口被服务以外的 daemon 占着时:新服务起不来(令牌没变),不能误报成功", func() {
+			m.installed = true
+			ready.Store(true)
+			m.onStart = nil
+			code, _, _, err := runCLIResult(strings.NewReader(""), "service", "install")
+			So(code, ShouldEqual, exitError)
+			So(err.Error(), ShouldContainSubstring, "not reachable")
+		})
+
+		Convey("已经装过时允许覆盖安装,即使 daemon 正在运行", func() {
+			m.installed = true
+			ready.Store(true)
+			code, _ := runCLI("service", "install")
+			So(code, ShouldEqual, exitOK)
+			So(m.calls, ShouldResemble, []string{"install"})
+		})
+
+		Convey("等不到 daemon 时退出码 3,并给出日志目录", func() {
+			m.onStart = nil
+			code, _, _, err := runCLIResult(strings.NewReader(""), "service", "install")
+			So(code, ShouldEqual, exitError)
+			So(err.Error(), ShouldContainSubstring, filepath.Join(os.Getenv("SCTL_DATA_DIR"), "logs"))
+		})
+	})
+}
+
+func TestServiceLifecycleCommands(t *testing.T) {
+	Convey("sctl service start / stop / restart / uninstall", t, func() {
+		m, ready := stubServiceEnv(t)
+
+		Convey("未安装时 start 退出码 3,提示先 install", func() {
+			code, _, _, err := runCLIResult(strings.NewReader(""), "service", "start")
+			So(code, ShouldEqual, exitError)
+			So(err.Error(), ShouldContainSubstring, "sctl service install")
+		})
+
+		Convey("daemon 已经能连上时 start 不再启动服务,如实说明", func() {
+			m.installed = true
+			ready.Store(true)
+			code, out := runCLI("service", "start")
+			So(code, ShouldEqual, exitOK)
+			So(m.calls, ShouldBeEmpty)
+			So(out, ShouldContainSubstring, "already running")
+		})
+
+		Convey("已安装时 restart 后等 daemon 能连上", func() {
+			m.installed = true
+			code, out := runCLI("service", "restart")
+			So(code, ShouldEqual, exitOK)
+			So(m.calls, ShouldResemble, []string{"restart"})
+			So(out, ShouldContainSubstring, os.Getenv("SCTL_BRIDGE_ADDR"))
+		})
+
+		Convey("已安装时 stop 成功", func() {
+			m.installed = true
+			code, _ := runCLI("service", "stop")
+			So(code, ShouldEqual, exitOK)
+			So(m.calls, ShouldResemble, []string{"stop"})
+		})
+
+		Convey("未安装时 uninstall 成功并如实说明", func() {
+			code, out := runCLI("service", "uninstall")
+			So(code, ShouldEqual, exitOK)
+			So(out, ShouldContainSubstring, "not installed")
+		})
+
+		Convey("已安装时 uninstall 报告已删除", func() {
+			m.installed = true
+			code, out := runCLI("service", "uninstall")
+			So(code, ShouldEqual, exitOK)
+			So(out, ShouldContainSubstring, "removed")
+			So(m.installed, ShouldBeFalse)
+		})
+	})
+}
+
+func TestServiceStatus(t *testing.T) {
+	Convey("sctl service status", t, func() {
+		m, ready := stubServiceEnv(t)
+		address := os.Getenv("SCTL_BRIDGE_ADDR")
+
+		Convey("未安装时退出码 0,如实说明", func() {
+			code, out := runCLI("service", "status")
+			So(code, ShouldEqual, exitOK)
+			So(out, ShouldContainSubstring, "not installed")
+		})
+
+		Convey("已安装且 daemon 能连上时给出位置和地址", func() {
+			m.installed = true
+			ready.Store(true)
+			code, out := runCLI("service", "status")
+			So(code, ShouldEqual, exitOK)
+			So(out, ShouldContainSubstring, "/fake/sctl.plist")
+			So(out, ShouldContainSubstring, "running at "+address)
+		})
+
+		Convey("-o json 输出结构化结果", func() {
+			m.installed = true
+			code, out := runCLI("service", "status", "-o", "json")
+			So(code, ShouldEqual, exitOK)
+			var got serviceStatus
+			So(json.Unmarshal([]byte(out), &got), ShouldBeNil)
+			So(got, ShouldResemble, serviceStatus{Installed: true, Location: "/fake/sctl.plist", Address: address, Running: false})
+		})
+	})
+}
diff --git a/internal/client/control/client.go b/internal/client/control/client.go
index c9386ba..201bed1 100644
--- a/internal/client/control/client.go
+++ b/internal/client/control/client.go
@@ -65,15 +65,33 @@ func (c *Client) WithClientLabel(label string) *Client {
 	return &cp
 }
 
-func resolveBaseURL() (string, error) {
+// Address 返回前端连接的 daemon 地址(host:port):SetAddress 配置的地址,否则协议默认端口。
+func Address() (string, error) {
 	if configuredAddress != "" {
-		return "http://" + configuredAddress, nil
+		return configuredAddress, nil
 	}
 	p, err := protocol.Load()
 	if err != nil {
 		return "", err
 	}
-	return fmt.Sprintf("http://127.0.0.1:%d", p.Transport.DefaultPort), nil
+	return fmt.Sprintf("127.0.0.1:%d", p.Transport.DefaultPort), nil
+}
+
+func resolveBaseURL() (string, error) {
+	address, err := Address()
+	if err != nil {
+		return "", err
+	}
+	return "http://" + address, nil
+}
+
+// Healthy 报告配置的地址上是否有 daemon 回答健康检查,不读控制令牌:令牌在别的数据目录时也算。
+func Healthy(ctx context.Context) bool {
+	base, err := resolveBaseURL()
+	if err != nil {
+		return false
+	}
+	return (&Client{http: &http.Client{}, base: base}).healthOK(ctx)
 }
 
 func (c *Client) healthOK(ctx context.Context) bool {
diff --git a/internal/client/service/launchd.go b/internal/client/service/launchd.go
new file mode 100644
index 0000000..2931bf8
--- /dev/null
+++ b/internal/client/service/launchd.go
@@ -0,0 +1,188 @@
+package service
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+const launchdLabel = "com.scriptscat.sctl"
+
+// bootstrap 在 bootout 之后立刻执行时,旧进程可能还没退出,launchctl 会报 I/O 错误;daemon 关闭连接要一点时间,
+// 按 500ms 间隔最多等 10 秒。
+const launchdBootstrapAttempts = 20
+
+type launchd struct {
+	runner Runner
+	dir    string // ~/Library/LaunchAgents
+	uid    int
+	sleep  func() // bootstrap 重试之间的等待
+}
+
+func (l *launchd) Location() string { return filepath.Join(l.dir, launchdLabel+".plist") }
+
+func (l *launchd) domain() string { return fmt.Sprintf("gui/%d", l.uid) }
+
+func (l *launchd) target() string { return l.domain() + "/" + launchdLabel }
+
+func (l *launchd) Installed(context.Context) (bool, error) { return fileExists(l.Location()) }
+
+// loaded 报告服务当前是否加载在 launchd 里(stop 之后不在,但定义仍在)。
+func (l *launchd) loaded(ctx context.Context) (bool, error) {
+	_, err := l.runner.Run(ctx, "launchctl", "print", l.target())
+	if err == nil {
+		return true, nil
+	}
+	if exited(err) {
+		return false, nil
+	}
+	return false, fmt.Errorf("launchctl print %s: %w", l.target(), err)
+}
+
+func (l *launchd) bootstrap(ctx context.Context) error {
+	var err error
+	for i := range launchdBootstrapAttempts {
+		if i > 0 {
+			l.sleep()
+		}
+		if err = run(ctx, l.runner, "launchctl", "bootstrap", l.domain(), l.Location()); err == nil {
+			return nil
+		}
+	}
+	return err
+}
+
+func (l *launchd) Install(ctx context.Context, p Program) error {
+	if err := p.validate(); err != nil {
+		return err
+	}
+	if err := writeDefinition(l.Location(), launchdPlist(p)); err != nil {
+		return err
+	}
+	// 已加载的旧定义不会因为文件被覆盖而生效,必须先卸下再重新加载。
+	loaded, err := l.loaded(ctx)
+	if err != nil {
+		return err
+	}
+	if loaded {
+		if err := run(ctx, l.runner, "launchctl", "bootout", l.target()); err != nil {
+			return err
+		}
+	}
+	// 用户曾 `launchctl disable` 过时 bootstrap 会被拒绝;install 表达的就是要启用。
+	if err := run(ctx, l.runner, "launchctl", "enable", l.target()); err != nil {
+		return err
+	}
+	return l.bootstrap(ctx)
+}
+
+func (l *launchd) Uninstall(ctx context.Context) (bool, error) {
+	existed, err := l.Installed(ctx)
+	if err != nil {
+		return false, err
+	}
+	loaded, err := l.loaded(ctx)
+	if err != nil {
+		return false, err
+	}
+	if loaded {
+		if err := run(ctx, l.runner, "launchctl", "bootout", l.target()); err != nil {
+			return true, err
+		}
+	}
+	if !existed {
+		// plist 被手动删掉、服务却还加载着时,上面已经把它停了,这也算移除了东西。
+		return loaded, nil
+	}
+	return true, os.Remove(l.Location())
+}
+
+func (l *launchd) Start(ctx context.Context) error {
+	if err := l.requireInstalled(ctx); err != nil {
+		return err
+	}
+	loaded, err := l.loaded(ctx)
+	if err != nil {
+		return err
+	}
+	if loaded {
+		return run(ctx, l.runner, "launchctl", "kickstart", l.target())
+	}
+	return l.bootstrap(ctx)
+}
+
+// Stop 用 bootout 卸下服务:KeepAlive 下单纯杀进程会被 launchd 立刻拉起。定义保留,下次登录仍会启动。
+func (l *launchd) Stop(ctx context.Context) error {
+	if err := l.requireInstalled(ctx); err != nil {
+		return err
+	}
+	loaded, err := l.loaded(ctx)
+	if err != nil || !loaded {
+		return err
+	}
+	return run(ctx, l.runner, "launchctl", "bootout", l.target())
+}
+
+func (l *launchd) Restart(ctx context.Context) error {
+	if err := l.requireInstalled(ctx); err != nil {
+		return err
+	}
+	loaded, err := l.loaded(ctx)
+	if err != nil {
+		return err
+	}
+	if loaded {
+		return run(ctx, l.runner, "launchctl", "kickstart", "-k", l.target())
+	}
+	return l.bootstrap(ctx)
+}
+
+func (l *launchd) requireInstalled(ctx context.Context) error {
+	ok, err := l.Installed(ctx)
+	if err != nil {
+		return err
+	}
+	if !ok {
+		return ErrNotInstalled
+	}
+	return nil
+}
+
+// launchdPlist 生成 LaunchAgent 定义:登录即启动,只在非正常退出时拉起,stderr 落到日志目录
+// (daemon 在服务模式下只把 Go 运行时的崩溃信息写到 stderr)。
+func launchdPlist(p Program) string {
+	var b strings.Builder
+	b.WriteString(`<?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>` + launchdLabel + `</string>
+	<key>ProgramArguments</key>
+	<array>
+`)
+	for _, arg := range append([]string{p.Executable}, p.Args...) {
+		b.WriteString("\t\t<string>" + xmlEscape(arg) + "</string>\n")
+	}
+	b.WriteString(`	</array>
+	<key>RunAtLoad</key>
+	<true/>
+	<key>KeepAlive</key>
+	<dict>
+		<key>SuccessfulExit</key>
+		<false/>
+	</dict>
+	<key>StandardOutPath</key>
+	<string>/dev/null</string>
+	<key>StandardErrorPath</key>
+	<string>` + xmlEscape(filepath.Join(p.LogDir, "service.stderr.log")) + `</string>
+</dict>
+</plist>
+`)
+	return b.String()
+}
+
+// xmlEscape 转义元素文本里的 & < >。引号在元素文本里不需要转义,保持原样便于用户阅读定义。
+var xmlEscape = strings.NewReplacer("&", "&amp;", "<", "&lt;", ">", "&gt;").Replace
diff --git a/internal/client/service/schtasks.go b/internal/client/service/schtasks.go
new file mode 100644
index 0000000..92c8213
--- /dev/null
+++ b/internal/client/service/schtasks.go
@@ -0,0 +1,203 @@
+package service
+
+import (
+	"context"
+	"encoding/binary"
+	"fmt"
+	"os"
+	"strings"
+	"unicode/utf16"
+)
+
+const schtasksName = "sctl"
+
+type schtasks struct {
+	runner  Runner
+	tempDir string
+	user    string // DOMAIN\user:非管理员只能为自己创建登录触发的任务,触发器必须写明用户
+}
+
+func (w *schtasks) Location() string { return `Task Scheduler \` + schtasksName }
+
+// Installed 用 /Query 判断任务是否存在。不存在时它以非零码退出,但提示文字随系统语言变化,无法与其他非零退出
+// 区分;schtasks 本身无法运行时如实报错。
+func (w *schtasks) Installed(ctx context.Context) (bool, error) {
+	_, err := w.runner.Run(ctx, "schtasks", "/Query", "/TN", schtasksName)
+	if err == nil {
+		return true, nil
+	}
+	if exited(err) {
+		return false, nil
+	}
+	return false, fmt.Errorf("schtasks /Query: %w", err)
+}
+
+func (w *schtasks) requireInstalled(ctx context.Context) error {
+	ok, err := w.Installed(ctx)
+	if err != nil {
+		return err
+	}
+	if !ok {
+		return ErrNotInstalled
+	}
+	return nil
+}
+
+func (w *schtasks) Install(ctx context.Context, p Program) error {
+	if err := p.validate(); err != nil {
+		return err
+	}
+	f, err := os.CreateTemp(w.tempDir, "sctl-task-*.xml")
+	if err != nil {
+		return err
+	}
+	defer os.Remove(f.Name())
+	_, err = f.Write(encodeUTF16(schtasksXML(p, w.user)))
+	if cerr := f.Close(); err == nil {
+		err = cerr
+	}
+	if err != nil {
+		return err
+	}
+	if err := run(ctx, w.runner, "schtasks", "/Create", "/TN", schtasksName, "/F", "/XML", f.Name()); err != nil {
+		return err
+	}
+	// StopExisting 让 /Run 先停掉正在运行的旧进程,覆盖安装后新定义随之生效。
+	return run(ctx, w.runner, "schtasks", "/Run", "/TN", schtasksName)
+}
+
+func (w *schtasks) Uninstall(ctx context.Context) (bool, error) {
+	ok, err := w.Installed(ctx)
+	if err != nil || !ok {
+		return false, err
+	}
+	// 任务没在运行时 /End 以非零码退出;其他失败照样报。
+	if err := run(ctx, w.runner, "schtasks", "/End", "/TN", schtasksName); err != nil && !exited(err) {
+		return true, err
+	}
+	return true, run(ctx, w.runner, "schtasks", "/Delete", "/TN", schtasksName, "/F")
+}
+
+func (w *schtasks) Start(ctx context.Context) error {
+	if err := w.requireInstalled(ctx); err != nil {
+		return err
+	}
+	return run(ctx, w.runner, "schtasks", "/Run", "/TN", schtasksName)
+}
+
+func (w *schtasks) Stop(ctx context.Context) error {
+	if err := w.requireInstalled(ctx); err != nil {
+		return err
+	}
+	return run(ctx, w.runner, "schtasks", "/End", "/TN", schtasksName)
+}
+
+// Restart 只需 /Run:MultipleInstancesPolicy=StopExisting 让它先停掉正在运行的实例。先 /End 再 /Run 反而有竞态,
+// 旧实例还没结束时 /Run 可能被丢弃。
+func (w *schtasks) Restart(ctx context.Context) error {
+	if err := w.requireInstalled(ctx); err != nil {
+		return err
+	}
+	return run(ctx, w.runner, "schtasks", "/Run", "/TN", schtasksName)
+}
+
+// schtasksXML 生成计划任务定义。schtasks /Create 的命令行参数无法表达运行上限、电池条件和失败重试,
+// 只能用 XML:默认的 72 小时运行上限会杀掉 daemon,默认的电池条件会让笔记本拔电后停掉它。
+func schtasksXML(p Program, user string) string {
+	args := make([]string, 0, len(p.Args))
+	for _, a := range p.Args {
+		args = append(args, windowsQuoteArg(a))
+	}
+	u := xmlEscape(user)
+	return `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>sctl bridge daemon</Description>
+  </RegistrationInfo>
+  <Triggers>
+    <LogonTrigger>
+      <Enabled>true</Enabled>
+      <UserId>` + u + `</UserId>
+    </LogonTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <UserId>` + u + `</UserId>
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>StopExisting</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <AllowHardTerminate>true</AllowHardTerminate>
+    <StartWhenAvailable>false</StartWhenAvailable>
+    <RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>
+    <IdleSettings>
+      <StopOnIdleEnd>false</StopOnIdleEnd>
+      <RestartOnIdle>false</RestartOnIdle>
+    </IdleSettings>
+    <AllowStartOnDemand>true</AllowStartOnDemand>
+    <Enabled>true</Enabled>
+    <Hidden>false</Hidden>
+    <RunOnlyIfIdle>false</RunOnlyIfIdle>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <Priority>7</Priority>
+    <RestartOnFailure>
+      <Interval>PT1M</Interval>
+      <Count>999</Count>
+    </RestartOnFailure>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>` + xmlEscape(p.Executable) + `</Command>
+      <Arguments>` + xmlEscape(strings.Join(args, " ")) + `</Arguments>
+    </Exec>
+  </Actions>
+</Task>
+`
+}
+
+// encodeUTF16 按 XML 声明的编码写出带 BOM 的 UTF-16LE,schtasks /XML 对 UTF-8 文件的支持不可靠。
+func encodeUTF16(s string) []byte {
+	units := utf16.Encode([]rune(s))
+	out := make([]byte, 2+2*len(units))
+	out[0], out[1] = 0xFF, 0xFE
+	for i, u := range units {
+		binary.LittleEndian.PutUint16(out[2+2*i:], u)
+	}
+	return out
+}
+
+// windowsQuoteArg 按 CommandLineToArgvW 的规则给参数加引号(与 Windows 上的 syscall.EscapeArg 相同,
+// 但这里要在任何平台上生成并测试任务定义)。
+func windowsQuoteArg(s string) string {
+	if s == "" {
+		return `""`
+	}
+	if !strings.ContainsAny(s, " \t\"") {
+		return s
+	}
+	var b strings.Builder
+	b.WriteByte('"')
+	slashes := 0
+	for i := 0; i < len(s); i++ {
+		c := s[i]
+		switch c {
+		case '\\':
+			slashes++
+		case '"':
+			// 引号前的反斜杠要加倍,再给引号本身一个反斜杠。
+			b.WriteString(strings.Repeat(`\`, slashes+1))
+			slashes = 0
+		default:
+			slashes = 0
+		}
+		b.WriteByte(c)
+	}
+	// 结尾的反斜杠紧挨着收尾引号,同样要加倍。
+	b.WriteString(strings.Repeat(`\`, slashes))
+	b.WriteByte('"')
+	return b.String()
+}
diff --git a/internal/client/service/service.go b/internal/client/service/service.go
new file mode 100644
index 0000000..758a638
--- /dev/null
+++ b/internal/client/service/service.go
@@ -0,0 +1,161 @@
+// Package service 把 `sctl serve` 注册为当前用户的系统服务:macOS launchd LaunchAgent、Linux systemd
+// 用户单元、Windows 登录触发的计划任务。sctl 只生成定义并调用系统自带的管理命令,守护由服务管理器负责。
+package service
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"os/user"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"time"
+)
+
+// ErrNotInstalled 表示当前用户还没有安装 sctl 服务。
+var ErrNotInstalled = errors.New("the sctl service is not installed; run `sctl service install` first")
+
+// Program 是服务要运行的命令行。Executable 必须是绝对路径:服务管理器不继承用户 shell 的 PATH。
+type Program struct {
+	Executable string
+	Args       []string
+	// LogDir 收服务管理器接住的 stderr(目前只有 launchd 需要文件路径)。
+	LogDir string
+}
+
+func (p Program) validate() error {
+	// 换行和 NUL 在三种定义格式里都无法可靠转义,宁可拒绝也不写出被截断的命令行。
+	for _, s := range append([]string{p.Executable, p.LogDir}, p.Args...) {
+		if strings.ContainsAny(s, "\x00\r\n") {
+			return fmt.Errorf("service command line must not contain newlines or NUL: %q", s)
+		}
+	}
+	return nil
+}
+
+// Manager 管理当前用户名下唯一的 sctl 服务。
+type Manager interface {
+	// Location 是服务定义所在的位置(文件路径或计划任务名),用于给用户展示。
+	Location() string
+	// Installed 报告服务定义是否存在。
+	Installed(ctx context.Context) (bool, error)
+	// Install 写入(或覆盖)服务定义,启用登录自启并立即(重新)启动。
+	Install(ctx context.Context, p Program) error
+	// Uninstall 停止服务并删除定义;existed 为 false 表示本来就没装。
+	Uninstall(ctx context.Context) (existed bool, err error)
+	Start(ctx context.Context) error
+	Stop(ctx context.Context) error
+	Restart(ctx context.Context) error
+}
+
+// Runner 执行一条外部命令并返回合并后的输出。
+type Runner interface {
+	Run(ctx context.Context, name string, args ...string) ([]byte, error)
+}
+
+type execRunner struct{}
+
+func (execRunner) Run(ctx context.Context, name string, args ...string) ([]byte, error) {
+	return exec.CommandContext(ctx, name, args...).CombinedOutput()
+}
+
+// run 执行命令,失败时把命令行和输出带进错误,便于用户直接看到服务管理器的原话。
+func run(ctx context.Context, r Runner, name string, args ...string) error {
+	out, err := r.Run(ctx, name, args...)
+	if err != nil {
+		line := strings.Join(append([]string{name}, args...), " ")
+		if msg := strings.TrimSpace(string(out)); msg != "" {
+			return fmt.Errorf("%s: %w: %s", line, err, msg)
+		}
+		return fmt.Errorf("%s: %w", line, err)
+	}
+	return nil
+}
+
+// New 返回当前操作系统的 Manager;不支持的系统返回错误。
+func New() (Manager, error) {
+	r := execRunner{}
+	switch runtime.GOOS {
+	case "darwin":
+		home, err := os.UserHomeDir()
+		if err != nil {
+			return nil, err
+		}
+		return &launchd{
+			runner: r,
+			dir:    filepath.Join(home, "Library", "LaunchAgents"),
+			uid:    os.Getuid(),
+			sleep:  func() { time.Sleep(500 * time.Millisecond) },
+		}, nil
+	case "linux":
+		dir, err := os.UserConfigDir()
+		if err != nil {
+			return nil, err
+		}
+		return &systemd{runner: r, dir: filepath.Join(dir, "systemd", "user")}, nil
+	case "windows":
+		u, err := user.Current()
+		if err != nil {
+			return nil, err
+		}
+		return &schtasks{runner: r, tempDir: os.TempDir(), user: u.Username}, nil
+	default:
+		return nil, fmt.Errorf("sctl service is not supported on %s", runtime.GOOS)
+	}
+}
+
+// ResolveExecutable 返回服务应固化的 sctl 路径。
+func ResolveExecutable() (string, error) {
+	self, err := os.Executable()
+	if err != nil {
+		return "", err
+	}
+	return resolveExecutable(self, exec.LookPath), nil
+}
+
+// resolveExecutable 优先用 PATH 里与当前进程同一个文件的 sctl:Homebrew 的 bin/sctl 是指向带版本号目录的
+// 符号链接,固化解析后的真实路径会在 brew upgrade 删除旧版本后失效。
+func resolveExecutable(self string, lookPath func(string) (string, error)) string {
+	found, err := lookPath("sctl")
+	if err != nil {
+		return self
+	}
+	if abs, err := filepath.Abs(found); err == nil {
+		found = abs
+	}
+	a, errA := os.Stat(found)
+	b, errB := os.Stat(self)
+	if errA != nil || errB != nil || !os.SameFile(a, b) {
+		return self
+	}
+	return found
+}
+
+// exited 报告 err 是不是外部命令以非零码退出(*exec.ExitError)。只有这种失败能当作“不存在”“未加载”的回答;
+// 命令本身无法运行时要如实报错,否则会把“查不了”说成“没装”。
+func exited(err error) bool {
+	var e interface{ ExitCode() int }
+	return errors.As(err, &e)
+}
+
+func fileExists(path string) (bool, error) {
+	_, err := os.Stat(path)
+	if err == nil {
+		return true, nil
+	}
+	if errors.Is(err, os.ErrNotExist) {
+		return false, nil
+	}
+	return false, err
+}
+
+// writeDefinition 写服务定义。定义里没有任何秘密,且服务管理器要求所有者以外不可写,0644 即可。
+func writeDefinition(path, body string) error {
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		return err
+	}
+	return os.WriteFile(path, []byte(body), 0o644)
+}
diff --git a/internal/client/service/service_test.go b/internal/client/service/service_test.go
new file mode 100644
index 0000000..825c87d
--- /dev/null
+++ b/internal/client/service/service_test.go
@@ -0,0 +1,400 @@
+package service
+
+import (
+	"context"
+	"encoding/binary"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"unicode/utf16"
+
+	. "github.com/smartystreets/goconvey/convey"
+)
+
+// fakeRunner 记录收到的命令,按「命令行前缀 → 错误」表返回失败,其余成功;onRun 在每条命令执行时被调用。
+type fakeRunner struct {
+	calls []string
+	fail  map[string]error
+	onRun func(args []string)
+}
+
+func (f *fakeRunner) Run(_ context.Context, name string, args ...string) ([]byte, error) {
+	if f.onRun != nil {
+		f.onRun(args)
+	}
+	line := strings.Join(append([]string{name}, args...), " ")
+	f.calls = append(f.calls, line)
+	for prefix, err := range f.fail {
+		if strings.HasPrefix(line, prefix) {
+			return []byte("boom"), err
+		}
+	}
+	return nil, nil
+}
+
+func TestResolveExecutable(t *testing.T) {
+	Convey("服务固化的二进制路径", t, func() {
+		dir := t.TempDir()
+		real := filepath.Join(dir, "Cellar", "sctl", "0.2.0", "sctl")
+		So(os.MkdirAll(filepath.Dir(real), 0o755), ShouldBeNil)
+		So(os.WriteFile(real, []byte("bin"), 0o755), ShouldBeNil)
+		link := filepath.Join(dir, "bin", "sctl")
+		So(os.MkdirAll(filepath.Dir(link), 0o755), ShouldBeNil)
+		So(os.Symlink(real, link), ShouldBeNil)
+
+		Convey("PATH 里的 sctl 与当前进程是同一个文件时用 PATH 里的路径,升级后不失效", func() {
+			got := resolveExecutable(real, func(string) (string, error) { return link, nil })
+			So(got, ShouldEqual, link)
+		})
+
+		Convey("PATH 里的 sctl 是另一个文件时用当前进程的路径", func() {
+			other := filepath.Join(dir, "other-sctl")
+			So(os.WriteFile(other, []byte("other"), 0o755), ShouldBeNil)
+			got := resolveExecutable(real, func(string) (string, error) { return other, nil })
+			So(got, ShouldEqual, real)
+		})
+
+		Convey("PATH 里找不到 sctl 时用当前进程的路径", func() {
+			got := resolveExecutable(real, func(string) (string, error) { return "", errors.New("not found") })
+			So(got, ShouldEqual, real)
+		})
+	})
+}
+
+func TestProgramValidate(t *testing.T) {
+	Convey("参数里含换行或 NUL 时拒绝生成服务定义", t, func() {
+		So(Program{Executable: "/bin/sctl", Args: []string{"serve"}}.validate(), ShouldBeNil)
+		So(Program{Executable: "/bin/sctl", Args: []string{"--data-dir", "a\nb"}}.validate(), ShouldNotBeNil)
+		So(Program{Executable: "/bin/s\x00ctl"}.validate(), ShouldNotBeNil)
+	})
+}
+
+func TestLaunchd(t *testing.T) {
+	Convey("macOS launchd", t, func() {
+		dir := t.TempDir()
+		runner := &fakeRunner{fail: map[string]error{}}
+		l := &launchd{runner: runner, dir: dir, uid: 501, sleep: func() {}}
+		prog := Program{Executable: "/Users/a b/bin/sctl", Args: []string{"--data-dir", "/Users/a b/d&<x>", "serve", "--service"}, LogDir: "/Users/a b/d/logs"}
+		plist := filepath.Join(dir, "com.scriptscat.sctl.plist")
+
+		Convey("生成的 plist 按 XML 转义参数,登录即启动、只在非正常退出时拉起", func() {
+			body := launchdPlist(prog)
+			So(body, ShouldContainSubstring, "<string>/Users/a b/bin/sctl</string>")
+			So(body, ShouldContainSubstring, "<string>/Users/a b/d&amp;&lt;x&gt;</string>")
+			So(body, ShouldContainSubstring, "<key>RunAtLoad</key>\n\t<true/>")
+			So(body, ShouldContainSubstring, "<key>SuccessfulExit</key>\n\t\t<false/>")
+			So(body, ShouldContainSubstring, "<string>/Users/a b/d/logs/service.stderr.log</string>")
+			So(body, ShouldContainSubstring, "<key>StandardOutPath</key>\n\t<string>/dev/null</string>")
+			// Background 会让 macOS 节流 CPU 和 I/O,而 daemon 服务的是交互请求。
+			So(body, ShouldNotContainSubstring, "ProcessType")
+		})
+
+		Convey("首次安装:写入 plist,启用并 bootstrap", func() {
+			runner.fail["launchctl print"] = exitErr{}
+			So(l.Install(context.Background(), prog), ShouldBeNil)
+			b, err := os.ReadFile(plist)
+			So(err, ShouldBeNil)
+			So(string(b), ShouldEqual, launchdPlist(prog))
+			So(runner.calls, ShouldResemble, []string{
+				"launchctl print gui/501/com.scriptscat.sctl",
+				"launchctl enable gui/501/com.scriptscat.sctl",
+				"launchctl bootstrap gui/501 " + plist,
+			})
+		})
+
+		Convey("重复安装:已加载时先 bootout 再 bootstrap,让新定义生效", func() {
+			So(l.Install(context.Background(), prog), ShouldBeNil)
+			So(runner.calls, ShouldResemble, []string{
+				"launchctl print gui/501/com.scriptscat.sctl",
+				"launchctl bootout gui/501/com.scriptscat.sctl",
+				"launchctl enable gui/501/com.scriptscat.sctl",
+				"launchctl bootstrap gui/501 " + plist,
+			})
+		})
+
+		Convey("bootout 后服务尚未退出导致 bootstrap 失败时重试", func() {
+			attempts := 0
+			l.runner = runnerFunc(func(name string, args ...string) error {
+				if len(args) > 0 && args[0] == "bootstrap" {
+					attempts++
+					if attempts < 3 {
+						return errors.New("Bootstrap failed: 5: Input/output error")
+					}
+				}
+				return nil
+			})
+			So(l.Install(context.Background(), prog), ShouldBeNil)
+			So(attempts, ShouldEqual, 3)
+		})
+
+		Convey("bootstrap 一直失败时返回带输出的错误", func() {
+			runner.fail["launchctl bootstrap"] = errors.New("exit status 5")
+			err := l.Install(context.Background(), prog)
+			So(err, ShouldNotBeNil)
+			So(err.Error(), ShouldContainSubstring, "boom")
+		})
+
+		Convey("未安装时 start / stop / restart 返回 ErrNotInstalled", func() {
+			So(errors.Is(l.Start(context.Background()), ErrNotInstalled), ShouldBeTrue)
+			So(errors.Is(l.Stop(context.Background()), ErrNotInstalled), ShouldBeTrue)
+			So(errors.Is(l.Restart(context.Background()), ErrNotInstalled), ShouldBeTrue)
+			So(runner.calls, ShouldBeEmpty)
+		})
+
+		Convey("已安装", func() {
+			So(os.WriteFile(plist, []byte(launchdPlist(prog)), 0o644), ShouldBeNil)
+
+			Convey("已加载时 start 用 kickstart,restart 用 kickstart -k,stop 用 bootout", func() {
+				So(l.Start(context.Background()), ShouldBeNil)
+				So(l.Restart(context.Background()), ShouldBeNil)
+				So(l.Stop(context.Background()), ShouldBeNil)
+				So(runner.calls, ShouldResemble, []string{
+					"launchctl print gui/501/com.scriptscat.sctl",
+					"launchctl kickstart gui/501/com.scriptscat.sctl",
+					"launchctl print gui/501/com.scriptscat.sctl",
+					"launchctl kickstart -k gui/501/com.scriptscat.sctl",
+					"launchctl print gui/501/com.scriptscat.sctl",
+					"launchctl bootout gui/501/com.scriptscat.sctl",
+				})
+			})
+
+			Convey("未加载(stop 之后)时 start / restart 重新 bootstrap,stop 什么都不做", func() {
+				runner.fail["launchctl print"] = exitErr{}
+				So(l.Start(context.Background()), ShouldBeNil)
+				So(l.Restart(context.Background()), ShouldBeNil)
+				So(l.Stop(context.Background()), ShouldBeNil)
+				So(runner.calls, ShouldResemble, []string{
+					"launchctl print gui/501/com.scriptscat.sctl",
+					"launchctl bootstrap gui/501 " + plist,
+					"launchctl print gui/501/com.scriptscat.sctl",
+					"launchctl bootstrap gui/501 " + plist,
+					"launchctl print gui/501/com.scriptscat.sctl",
+				})
+			})
+
+			Convey("uninstall bootout 并删除 plist", func() {
+				existed, err := l.Uninstall(context.Background())
+				So(err, ShouldBeNil)
+				So(existed, ShouldBeTrue)
+				_, statErr := os.Stat(plist)
+				So(os.IsNotExist(statErr), ShouldBeTrue)
+				So(runner.calls, ShouldResemble, []string{
+					"launchctl print gui/501/com.scriptscat.sctl",
+					"launchctl bootout gui/501/com.scriptscat.sctl",
+				})
+			})
+		})
+
+		Convey("launchctl 本身无法运行时如实报错,不当作未加载", func() {
+			So(os.WriteFile(plist, []byte(launchdPlist(prog)), 0o644), ShouldBeNil)
+			runner.fail["launchctl print"] = errors.New("exec: launchctl: not found")
+			So(l.Start(context.Background()), ShouldNotBeNil)
+			So(runner.calls, ShouldResemble, []string{"launchctl print gui/501/com.scriptscat.sctl"})
+		})
+
+		Convey("plist 已被手动删除但服务仍加载时,uninstall 卸下它并报告确有东西被移除", func() {
+			existed, err := l.Uninstall(context.Background())
+			So(err, ShouldBeNil)
+			So(existed, ShouldBeTrue)
+			So(runner.calls, ShouldResemble, []string{
+				"launchctl print gui/501/com.scriptscat.sctl",
+				"launchctl bootout gui/501/com.scriptscat.sctl",
+			})
+		})
+
+		Convey("未安装时 uninstall 成功并报告不存在", func() {
+			runner.fail["launchctl print"] = exitErr{}
+			existed, err := l.Uninstall(context.Background())
+			So(err, ShouldBeNil)
+			So(existed, ShouldBeFalse)
+		})
+	})
+}
+
+func TestSystemd(t *testing.T) {
+	Convey("Linux systemd 用户服务", t, func() {
+		dir := t.TempDir()
+		runner := &fakeRunner{fail: map[string]error{}}
+		s := &systemd{runner: runner, dir: dir}
+		prog := Program{Executable: "/home/a b/bin/sctl", Args: []string{"--data-dir", `/home/a b/100%"$x\`, "serve", "--service"}}
+		unit := filepath.Join(dir, "sctl.service")
+
+		Convey("ExecStart 每个参数加引号,转义反斜杠、引号、% 和 $", func() {
+			body := systemdUnit(prog)
+			So(body, ShouldContainSubstring, `ExecStart="/home/a b/bin/sctl" "--data-dir" "/home/a b/100%%\"$$x\\" "serve" "--service"`)
+			So(body, ShouldContainSubstring, "Restart=on-failure")
+			So(body, ShouldContainSubstring, "WantedBy=default.target")
+		})
+
+		Convey("install 写入单元文件后 daemon-reload、enable、restart", func() {
+			So(s.Install(context.Background(), prog), ShouldBeNil)
+			b, err := os.ReadFile(unit)
+			So(err, ShouldBeNil)
+			So(string(b), ShouldEqual, systemdUnit(prog))
+			So(runner.calls, ShouldResemble, []string{
+				"systemctl --user daemon-reload",
+				// 按绝对路径 enable:用户 shell 与 systemd 用户实例的 XDG_CONFIG_HOME 可能不同。
+				"systemctl --user enable " + unit,
+				"systemctl --user restart sctl.service",
+			})
+		})
+
+		Convey("systemctl 失败时返回带输出的错误", func() {
+			runner.fail["systemctl --user daemon-reload"] = errors.New("exit status 1")
+			err := s.Install(context.Background(), prog)
+			So(err, ShouldNotBeNil)
+			So(err.Error(), ShouldContainSubstring, "boom")
+		})
+
+		Convey("未安装时 start / stop / restart 返回 ErrNotInstalled,uninstall 报告不存在", func() {
+			So(errors.Is(s.Start(context.Background()), ErrNotInstalled), ShouldBeTrue)
+			So(errors.Is(s.Stop(context.Background()), ErrNotInstalled), ShouldBeTrue)
+			So(errors.Is(s.Restart(context.Background()), ErrNotInstalled), ShouldBeTrue)
+			existed, err := s.Uninstall(context.Background())
+			So(err, ShouldBeNil)
+			So(existed, ShouldBeFalse)
+			So(runner.calls, ShouldBeEmpty)
+		})
+
+		Convey("已安装时 start / stop / restart 直接交给 systemctl,uninstall disable --now 后删除单元并 reload", func() {
+			So(os.WriteFile(unit, []byte(systemdUnit(prog)), 0o644), ShouldBeNil)
+			So(s.Start(context.Background()), ShouldBeNil)
+			So(s.Stop(context.Background()), ShouldBeNil)
+			So(s.Restart(context.Background()), ShouldBeNil)
+			existed, err := s.Uninstall(context.Background())
+			So(err, ShouldBeNil)
+			So(existed, ShouldBeTrue)
+			_, statErr := os.Stat(unit)
+			So(os.IsNotExist(statErr), ShouldBeTrue)
+			So(runner.calls, ShouldResemble, []string{
+				"systemctl --user start sctl.service",
+				"systemctl --user stop sctl.service",
+				"systemctl --user restart sctl.service",
+				"systemctl --user disable --now sctl.service",
+				"systemctl --user daemon-reload",
+			})
+		})
+	})
+}
+
+func TestSchtasks(t *testing.T) {
+	Convey("Windows 任务计划程序", t, func() {
+		dir := t.TempDir()
+		// /Create 执行时读出它拿到的 XML 文件:Install 返回后临时文件已被删除。
+		var created string
+		runner := &fakeRunner{fail: map[string]error{}, onRun: func(args []string) {
+			if len(args) > 0 && args[0] == "/Create" {
+				b, err := os.ReadFile(args[len(args)-1])
+				So(err, ShouldBeNil)
+				created = decodeUTF16(b)
+			}
+		}}
+		w := &schtasks{runner: runner, tempDir: dir, user: `PC\a&b`}
+		prog := Program{Executable: `C:\Program Files\sctl\sctl.exe`, Args: []string{"--data-dir", `C:\Users\a b\d`, "serve", "--service"}}
+
+		Convey("任务 XML 只对当前用户的登录触发,取消运行上限,失败重试,参数按 Windows 规则加引号", func() {
+			body := schtasksXML(prog, `PC\a&b`)
+			So(body, ShouldStartWith, `<?xml version="1.0" encoding="UTF-16"?>`)
+			So(strings.Count(body, `<UserId>PC\a&amp;b</UserId>`), ShouldEqual, 2)
+			So(body, ShouldContainSubstring, "<LogonType>InteractiveToken</LogonType>")
+			So(body, ShouldContainSubstring, "<RunLevel>LeastPrivilege</RunLevel>")
+			So(body, ShouldContainSubstring, "<ExecutionTimeLimit>PT0S</ExecutionTimeLimit>")
+			So(body, ShouldContainSubstring, "<DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>")
+			So(body, ShouldContainSubstring, "<StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>")
+			// /Run 遇到正在运行的实例时先停掉它再启动,重启和覆盖安装都靠它,不必先 /End 再赌时序。
+			So(body, ShouldContainSubstring, "<MultipleInstancesPolicy>StopExisting</MultipleInstancesPolicy>")
+			So(body, ShouldContainSubstring, "<RestartOnFailure>")
+			So(body, ShouldContainSubstring, `<Command>C:\Program Files\sctl\sctl.exe</Command>`)
+			So(body, ShouldContainSubstring, `<Arguments>--data-dir "C:\Users\a b\d" serve --service</Arguments>`)
+		})
+
+		Convey("安装:以 UTF-16 XML 创建(或覆盖)任务后立即运行,临时文件删除", func() {
+			So(w.Install(context.Background(), prog), ShouldBeNil)
+			So(created, ShouldEqual, schtasksXML(prog, `PC\a&b`))
+			So(len(runner.calls), ShouldEqual, 2)
+			So(runner.calls[0], ShouldStartWith, "schtasks /Create /TN sctl /F /XML "+dir)
+			So(runner.calls[1], ShouldEqual, "schtasks /Run /TN sctl")
+			entries, err := os.ReadDir(dir)
+			So(err, ShouldBeNil)
+			So(entries, ShouldBeEmpty)
+		})
+
+		Convey("schtasks 本身无法运行时如实报错,不当作未安装", func() {
+			runner.fail["schtasks /Query"] = errors.New("exec: schtasks: not found")
+			_, err := w.Installed(context.Background())
+			So(err, ShouldNotBeNil)
+			So(errors.Is(w.Start(context.Background()), ErrNotInstalled), ShouldBeFalse)
+		})
+
+		Convey("未安装时 start / stop / restart 返回 ErrNotInstalled,uninstall 报告不存在", func() {
+			runner.fail["schtasks /Query"] = exitErr{}
+			So(errors.Is(w.Start(context.Background()), ErrNotInstalled), ShouldBeTrue)
+			So(errors.Is(w.Stop(context.Background()), ErrNotInstalled), ShouldBeTrue)
+			So(errors.Is(w.Restart(context.Background()), ErrNotInstalled), ShouldBeTrue)
+			existed, err := w.Uninstall(context.Background())
+			So(err, ShouldBeNil)
+			So(existed, ShouldBeFalse)
+		})
+
+		Convey("已安装时 stop 结束、restart 直接 /Run(由 StopExisting 先停旧实例),uninstall 结束后删除(结束失败不影响)", func() {
+			runner.fail["schtasks /End"] = exitErr{}
+			So(w.Start(context.Background()), ShouldBeNil)
+			So(w.Stop(context.Background()), ShouldNotBeNil)
+			So(w.Restart(context.Background()), ShouldBeNil)
+			existed, err := w.Uninstall(context.Background())
+			So(err, ShouldBeNil)
+			So(existed, ShouldBeTrue)
+			So(runner.calls, ShouldResemble, []string{
+				"schtasks /Query /TN sctl", "schtasks /Run /TN sctl",
+				"schtasks /Query /TN sctl", "schtasks /End /TN sctl",
+				"schtasks /Query /TN sctl", "schtasks /Run /TN sctl",
+				"schtasks /Query /TN sctl", "schtasks /End /TN sctl", "schtasks /Delete /TN sctl /F",
+			})
+		})
+	})
+}
+
+func TestWindowsArgQuoting(t *testing.T) {
+	Convey("Windows 命令行参数按 CommandLineToArgvW 的规则加引号", t, func() {
+		cases := map[string]string{
+			"serve":        "serve",
+			"":             `""`,
+			`a b`:          `"a b"`,
+			`C:\a b\`:      `"C:\a b\\"`,
+			`say "hi"`:     `"say \"hi\""`,
+			`C:\no\space\`: `C:\no\space\`,
+			"tab\there":    "\"tab\there\"",
+			`back\\"quote`: `"back\\\\\"quote"`,
+		}
+		for in, want := range cases {
+			So(fmt.Sprintf("%s => %s", in, windowsQuoteArg(in)), ShouldEqual, fmt.Sprintf("%s => %s", in, want))
+		}
+	})
+}
+
+// decodeUTF16 解出带 BOM 的 UTF-16LE 文件内容。
+func decodeUTF16(b []byte) string {
+	So(b[:2], ShouldResemble, []byte{0xFF, 0xFE})
+	units := make([]uint16, 0, len(b)/2)
+	for i := 2; i+1 < len(b); i += 2 {
+		units = append(units, binary.LittleEndian.Uint16(b[i:]))
+	}
+	return string(utf16.Decode(units))
+}
+
+// exitErr 模拟外部命令以非零码退出(与 *exec.ExitError 一样带 ExitCode)。
+type exitErr struct{}
+
+func (exitErr) Error() string { return "exit status 1" }
+
+func (exitErr) ExitCode() int { return 1 }
+
+// runnerFunc 把一个函数当作 Runner,用于需要按调用次数改变结果的场景。
+type runnerFunc func(name string, args ...string) error
+
+func (f runnerFunc) Run(_ context.Context, name string, args ...string) ([]byte, error) {
+	return nil, f(name, args...)
+}
diff --git a/internal/client/service/systemd.go b/internal/client/service/systemd.go
new file mode 100644
index 0000000..aee2d81
--- /dev/null
+++ b/internal/client/service/systemd.go
@@ -0,0 +1,100 @@
+package service
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+const systemdUnitName = "sctl.service"
+
+type systemd struct {
+	runner Runner
+	dir    string // $XDG_CONFIG_HOME/systemd/user
+}
+
+func (s *systemd) Location() string { return filepath.Join(s.dir, systemdUnitName) }
+
+func (s *systemd) Installed(context.Context) (bool, error) { return fileExists(s.Location()) }
+
+func (s *systemd) systemctl(ctx context.Context, args ...string) error {
+	return run(ctx, s.runner, "systemctl", append([]string{"--user"}, args...)...)
+}
+
+func (s *systemd) Install(ctx context.Context, p Program) error {
+	if err := p.validate(); err != nil {
+		return err
+	}
+	if err := writeDefinition(s.Location(), systemdUnit(p)); err != nil {
+		return err
+	}
+	if err := s.systemctl(ctx, "daemon-reload"); err != nil {
+		return err
+	}
+	// 按绝对路径 enable:单元写在调用者 shell 的 XDG_CONFIG_HOME 下,systemd 用户实例的环境可能不同,
+	// 按名字会找不到它。
+	if err := s.systemctl(ctx, "enable", s.Location()); err != nil {
+		return err
+	}
+	// restart 在服务未运行时等同于 start,重复安装时让新定义生效。
+	return s.systemctl(ctx, "restart", systemdUnitName)
+}
+
+func (s *systemd) Uninstall(ctx context.Context) (bool, error) {
+	existed, err := s.Installed(ctx)
+	if err != nil || !existed {
+		return false, err
+	}
+	if err := s.systemctl(ctx, "disable", "--now", systemdUnitName); err != nil {
+		return true, err
+	}
+	if err := os.Remove(s.Location()); err != nil {
+		return true, err
+	}
+	return true, s.systemctl(ctx, "daemon-reload")
+}
+
+func (s *systemd) Start(ctx context.Context) error { return s.verb(ctx, "start") }
+
+func (s *systemd) Stop(ctx context.Context) error { return s.verb(ctx, "stop") }
+
+func (s *systemd) Restart(ctx context.Context) error { return s.verb(ctx, "restart") }
+
+func (s *systemd) verb(ctx context.Context, verb string) error {
+	ok, err := s.Installed(ctx)
+	if err != nil {
+		return err
+	}
+	if !ok {
+		return ErrNotInstalled
+	}
+	return s.systemctl(ctx, verb, systemdUnitName)
+}
+
+// systemdUnit 生成用户单元。stderr 由 journal 接收,daemon 在服务模式下只把 Go 运行时的崩溃信息写到那里。
+func systemdUnit(p Program) string {
+	args := make([]string, 0, len(p.Args)+1)
+	for _, a := range append([]string{p.Executable}, p.Args...) {
+		args = append(args, systemdQuote(a))
+	}
+	return `[Unit]
+Description=sctl bridge daemon
+
+[Service]
+Type=simple
+ExecStart=` + strings.Join(args, " ") + `
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+`
+}
+
+// systemdQuote 按 ExecStart 的规则给参数加双引号:反斜杠和引号用 C 风格转义,% 是单元说明符、$ 是环境变量
+// 替换,都要双写才能原样传给进程。
+func systemdQuote(s string) string {
+	r := strings.NewReplacer(`\`, `\\`, `"`, `\"`, `%`, `%%`, `$`, `$$`)
+	return `"` + r.Replace(s) + `"`
+}
diff --git a/internal/pkg/logging/logging.go b/internal/pkg/logging/logging.go
index ebc1660..98a9557 100644
--- a/internal/pkg/logging/logging.go
+++ b/internal/pkg/logging/logging.go
@@ -7,7 +7,8 @@
 //
 // 出口:持久文件日志(<dataDir>/logs/sctl.log 收 level+,sctl.err.log 只收 error+)
 // 外加 stderr console core —— sctl serve/connect 是前台命令,stderr 让用户实时看到日志,
-// 且 stderr 与 stdout 协议/JSON 输出互不干扰。
+// 且 stderr 与 stdout 协议/JSON 输出互不干扰。服务管理器托管的 serve 不要 stderr core:
+// launchd 把 stderr 写进一个不滚动的文件,再写一份会无限增长。
 package logging
 
 import (
@@ -21,13 +22,18 @@ import (
 	"github.com/scriptscat/sctl/internal/pkg/paths"
 )
 
-// Setup 构建并注入全局 logger。level 取 debug/info/warn/error。文件日志目录不可写时
-// 静默降级为仅 stderr(不因日志目录问题阻断命令)。返回构建出的 logger 供直接使用。
-func Setup(level string) *zap.Logger {
+// Setup 构建并注入全局 logger。level 取 debug/info/warn/error;toStderr 为 false 时只写文件。
+// 文件日志目录不可写时静默降级为仅 stderr(不因日志目录问题阻断命令,也不丢日志)。
+// 返回构建出的 logger 供直接使用。
+func Setup(level string, toStderr bool) *zap.Logger {
 	lvl := logger.ToLevel(level)
 
-	cores := []zapcore.Core{stderrCore(lvl)}
-	if fileCores, ok := fileCores(lvl); ok {
+	var cores []zapcore.Core
+	fileCores, ok := fileCores(lvl)
+	if toStderr || !ok {
+		cores = append(cores, stderrCore(lvl))
+	}
+	if ok {
 		cores = append(cores, fileCores...)
 	}
 
diff --git a/internal/pkg/logging/logging_test.go b/internal/pkg/logging/logging_test.go
new file mode 100644
index 0000000..e903dc3
--- /dev/null
+++ b/internal/pkg/logging/logging_test.go
@@ -0,0 +1,69 @@
+package logging
+
+import (
+	"io"
+	"os"
+	"path/filepath"
+	"testing"
+
+	. "github.com/smartystreets/goconvey/convey"
+
+	"github.com/scriptscat/sctl/internal/pkg/paths"
+)
+
+// captureStderr 在 fn 执行期间把 os.Stderr 换成管道,返回写进去的内容。stderr core 在 Setup 时绑定
+// os.Stderr,所以 Setup 必须在 fn 里调用。
+func captureStderr(fn func()) string {
+	old := os.Stderr
+	r, w, _ := os.Pipe()
+	os.Stderr = w
+	fn()
+	os.Stderr = old
+	_ = w.Close()
+	b, _ := io.ReadAll(r)
+	return string(b)
+}
+
+func TestSetupStderr(t *testing.T) {
+	Convey("日志出口", t, func() {
+		dir := t.TempDir()
+		paths.SetDataDir(dir)
+		Reset(func() { paths.SetDataDir("") })
+
+		Convey("前台运行时日志同时写 stderr 和文件", func() {
+			out := captureStderr(func() {
+				l := Setup("info", true)
+				l.Info("foreground-line")
+				_ = l.Sync()
+			})
+			So(out, ShouldContainSubstring, "foreground-line")
+			b, err := os.ReadFile(filepath.Join(dir, "logs", "sctl.log"))
+			So(err, ShouldBeNil)
+			So(string(b), ShouldContainSubstring, "foreground-line")
+		})
+
+		Convey("服务模式下日志只写文件,stderr 留给运行时崩溃信息", func() {
+			out := captureStderr(func() {
+				l := Setup("info", false)
+				l.Info("service-line")
+				_ = l.Sync()
+			})
+			So(out, ShouldBeEmpty)
+			b, err := os.ReadFile(filepath.Join(dir, "logs", "sctl.log"))
+			So(err, ShouldBeNil)
+			So(string(b), ShouldContainSubstring, "service-line")
+		})
+
+		Convey("服务模式下日志目录不可写时退回 stderr,不丢日志", func() {
+			blocker := filepath.Join(dir, "file")
+			So(os.WriteFile(blocker, nil, 0o600), ShouldBeNil)
+			paths.SetDataDir(blocker)
+			out := captureStderr(func() {
+				l := Setup("info", false)
+				l.Info("fallback-line")
+				_ = l.Sync()
+			})
+			So(out, ShouldContainSubstring, "fallback-line")
+		})
+	})
+}
diff --git a/skills/sctl/SKILL.md b/skills/sctl/SKILL.md
index 3505878..a38080c 100644
--- a/skills/sctl/SKILL.md
+++ b/skills/sctl/SKILL.md
@@ -48,8 +48,8 @@ sctl status            # daemon version, whether the extensions are connected
 sctl browsers -o json  # paired sctl Browser instances: name, online, product
 ```
 
-- **Cannot reach the daemon:** it is not running. Ask the user to start it (`sctl serve` in a terminal, or restart
-  the launchd/systemd service that runs it). Do not start one yourself in the background: it dies with your session
+- **Cannot reach the daemon:** it is not running. Ask the user to start it (`sctl serve` in a terminal,
+  `sctl service start` when they installed the background service, or `sctl service install` to set one up). Do not start one yourself in the background: it dies with your session
   and can fight the user's service for the port.
 - **`NO_BROWSER_CONNECTED`:** no browser is paired or it is closed. Pairing needs the user: they run `sctl connect`
   and type the one-time code into the sctl Browser popup.