@xyagent/cli 0.0.1

package/src-ext/runtime/picoclaw/wsClient.mjs

@@ -0,0 +1,129 @@
+// PicoClaw daemon WebSocket 客户端。
+//
+// PicoClaw daemon 默认监听 127.0.0.1:18790,WS 路径 /pico/ws。
+// 鉴权 3 种方式(picoclaw 自身支持):
+//   1. Authorization: Bearer <token>     (服务端 / Node `ws` 包可用)
+//   2. Sec-WebSocket-Protocol "token.<value>"  (浏览器 / Node 22 内置 WebSocket 用这条)
+//   3. query 参数 ?token=<value>(picoclaw 必须开启 AllowTokenQuery)
+//
+// 这里走 #2 子协议 — Node 22 内置 WebSocket 不支持自定义 header,但支持
+// 第二参数 protocols。`@xyagent/cli` 之前没有任何 npm 依赖,我们保持零依赖,
+// 直接用 globalThis.WebSocket(Node ≥21 内置)。
+//
+// 通讯使用 PicoMessage:
+//   { type, id, session_id, timestamp, payload }
+//
+// CLI 端只需:
+//   send(msg)      —— 发消息(JSON 序列化)
+//   onMessage(fn)  —— 收消息回调
+//   onClose(fn)    —— 断开回调(自动重连由调用方决定)
+//   close()        —— 主动关闭
+
+import {
+  PICOCLAW_TOKEN,
+  PICOCLAW_WS_URL,
+} from "./constants.mjs";
+
+/**
+ * 建一个 PicoClaw 连接。
+ * @returns {Promise<PicoclawConn>}
+ */
+export function connect({ url, token, log }) {
+  const target = url || PICOCLAW_WS_URL;
+  const bearer = token || PICOCLAW_TOKEN;
+  return new Promise((resolve, reject) => {
+    const subprotocol = `token.${bearer}`;
+    const WS = globalThis.WebSocket;
+    if (!WS) {
+      reject(new Error("global WebSocket not available; require Node >= 21"));
+      return;
+    }
+    const ws = new WS(target, [subprotocol]);
+    let settled = false;
+    ws.addEventListener("open", () => {
+      if (settled) return;
+      settled = true;
+      resolve(makeConn(ws, log, target));
+    });
+    ws.addEventListener("error", (ev) => {
+      if (settled) return;
+      settled = true;
+      const msg = (ev && ev.message) || "ws error";
+      reject(new Error(String(msg)));
+    });
+    ws.addEventListener("close", (ev) => {
+      if (settled) return;
+      settled = true;
+      reject(new Error(`picoclaw ws closed before open: code=${ev?.code}`));
+    });
+  });
+}
+
+function makeConn(ws, log, target) {
+  /** @type {Set<(msg:any)=>void>} */
+  const messageHandlers = new Set();
+  /** @type {Set<(reason:string)=>void>} */
+  const closeHandlers = new Set();
+
+  ws.addEventListener("message", (ev) => {
+    let parsed;
+    try {
+      const data = typeof ev.data === "string" ? ev.data : Buffer.from(ev.data).toString("utf8");
+      parsed = JSON.parse(data);
+    } catch (err) {
+      if (log) log.warn("picoclaw.ws.parse.err", "bad pico message", { err: String(err?.message || err) });
+      return;
+    }
+    for (const h of messageHandlers) {
+      try { h(parsed); } catch (err) {
+        if (log) log.warn("picoclaw.ws.handler.err", "handler threw", { err: String(err?.message || err) });
+      }
+    }
+  });
+  ws.addEventListener("close", (ev) => {
+    if (log) log.info("picoclaw.ws.closed", "ws closed", { code: ev?.code, reason: String(ev?.reason || "") });
+    for (const h of closeHandlers) {
+      try { h(`code=${ev?.code}`); } catch {}
+    }
+  });
+  ws.addEventListener("error", (ev) => {
+    if (log) log.warn("picoclaw.ws.err", "ws error", { err: String(ev?.message || "ws error") });
+  });
+
+  if (log) log.info("picoclaw.ws.open", "connected", { url: target });
+
+  return {
+    send(picoMessage) {
+      if (ws.readyState !== 1 /* OPEN */) {
+        throw new Error(`picoclaw ws not open: state=${ws.readyState}`);
+      }
+      ws.send(JSON.stringify(picoMessage));
+    },
+    onMessage(fn) { messageHandlers.add(fn); return () => messageHandlers.delete(fn); },
+    onClose(fn) { closeHandlers.add(fn); return () => closeHandlers.delete(fn); },
+    close(reason) {
+      try { ws.close(1000, reason || "client close"); } catch {}
+    },
+    get readyState() { return ws.readyState; },
+    get url() { return target; },
+  };
+}
+
+/**
+ * 构造 message.send 帧(用户消息进入 PicoClaw)。
+ *
+ * @param {{sessionId:string, content:string, requestId?:string}} arg
+ */
+export function buildMessageSend({ sessionId, content, requestId }) {
+  return {
+    type: "message.send",
+    id: requestId || randomID(),
+    session_id: sessionId,
+    timestamp: Date.now(),
+    payload: { content: String(content || "") },
+  };
+}
+
+function randomID() {
+  return Math.random().toString(36).slice(2, 10) + Date.now().toString(36);
+}

package/src-ext/service/serviceManager.mjs

@@ -0,0 +1,521 @@
+// 跨平台 service 管理骨架。
+//
+// 目标：用户关终端 / 机器休眠后 bridge 仍自动拉起并保持和 relay 连接。
+//
+// 平台映射（详见 docs/PLATFORM.md）：
+//   - macOS       → launchd `~/Library/LaunchAgents/com.agentlink.agent.<runtime>.plist`
+//   - Linux       → systemd user unit `~/.config/systemd/user/agentlink-agent-<runtime>.service`
+//   - Linux (no systemd) → 打印提示，建议 tmux/nohup
+//   - Windows     → schtasks `Agentlink\Agent-<runtime>`（ONLOGON + 10s 重启延迟）
+//
+// service 里实际执行：`agentlink-agent <runtime>`（零参数，读本地持久化状态）。
+// 所以调用前必须先跑过 `agentlink pair <code> -r <runtime>` —— ensureState 会校验。
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+import { readPairState } from "../core/pairCodeClient.mjs";
+import { ensureDefaultWorkspace, defaultWorkspacePath } from "../core/defaultWorkspace.mjs";
+
+const SERVICE_RUNTIMES = new Set(["claude", "codex"]);
+
+/**
+ * reload 用的 runtime 清单 —— 比 install 集合更广：也覆盖 openclaw/hermes
+ * 的后台 bridge service（这两者的 install 在 bin/agentlink 里维护，label 固定）。
+ * reload 只做"重启已存在"的动作，不创建/不删除，所以即使 openclaw/hermes 未装也
+ * 只是 skip。
+ *
+ * 三端标签必须和各 runtime 实际 install 时写入的一致：
+ *   - claude/codex  : 见下方 macInstall / sdInstall / winInstall
+ *   - openclaw/hermes: 见 bin/agentlink 的 serviceNames() —— label/unit/task 规则
+ */
+const ALL_RELOAD_TARGETS = {
+  claude: {
+    mac:   "com.agentlink.agent.claude",
+    linux: "agentlink-agent-claude.service",
+    win:   "Agentlink\\Agent-claude",
+  },
+  codex: {
+    mac:   "com.agentlink.agent.codex",
+    linux: "agentlink-agent-codex.service",
+    win:   "Agentlink\\Agent-codex",
+  },
+  openclaw: {
+    mac:   "com.agentlink.bridge",
+    linux: "agentlink-bridge.service",
+    win:   "Agentlink Bridge",
+  },
+  hermes: {
+    mac:   "com.agentlink.bridge-hermes",
+    linux: "agentlink-bridge-hermes.service",
+    win:   "Agentlink Bridge Hermes",
+  },
+};
+
+function ensureRuntime(runtime) {
+  if (!SERVICE_RUNTIMES.has(runtime)) {
+    throw new Error(`service runtime must be one of: ${[...SERVICE_RUNTIMES].join(", ")}`);
+  }
+}
+
+function ensureReloadRuntime(runtime) {
+  if (!ALL_RELOAD_TARGETS[runtime]) {
+    throw new Error(`reload runtime must be one of: ${Object.keys(ALL_RELOAD_TARGETS).join(", ")}`);
+  }
+}
+
+function ensureStateOrFail(runtime) {
+  const s = readPairState(runtime);
+  if (!s) {
+    throw new Error(
+      `尚未配对 —— 请先在 App 上创建会话，然后运行：\n` +
+      `  agentlink pair <code> -r ${runtime} --relay <url>\n` +
+      `配对成功后再 service install。`,
+    );
+  }
+  return s;
+}
+
+function agentBinPath() {
+  // 取和当前 agentlink 可执行同目录的 agentlink-agent
+  const here = path.dirname(new URL(import.meta.url).pathname);
+  const guess = path.resolve(here, "../../bin/agentlink-agent");
+  if (fs.existsSync(guess)) return guess;
+  // 尝试 PATH
+  const which = spawnSync(process.platform === "win32" ? "where" : "which", ["agentlink-agent"], {
+    encoding: "utf8",
+  });
+  if (which.status === 0) {
+    const first = which.stdout.trim().split(/\r?\n/)[0];
+    if (first) return first;
+  }
+  throw new Error("could not locate agentlink-agent binary");
+}
+
+// ===== macOS launchd =====
+function macLabel(runtime) { return `com.agentlink.agent.${runtime}`; }
+function macPlistPath(runtime) {
+  return path.join(os.homedir(), "Library", "LaunchAgents", `${macLabel(runtime)}.plist`);
+}
+
+function macUid() {
+  return typeof process.getuid === "function" ? process.getuid() : 0;
+}
+
+/**
+ * 现代 launchd 注册序列（Big Sur+ 可靠）。
+ *
+ * 老路径用 `launchctl load -w` 依赖 plist 的 `RunAtLoad` 拉起进程。在 Big Sur+
+ * 上 legacy `load`/`unload` 已废弃，且 `load -w` 对**已加载**的 job 是 no-op——
+ * 不会重新触发 `RunAtLoad`，job 停在 "loaded but runs=0" 永远不真正执行。
+ * `agentlink pair <code> -r claude/codex` 装完 sleep 3s 查状态因此偶发报
+ * "进程未运行起来"，反复 pair / 残留旧 plist 更易触发。
+ *
+ * 健壮序列（与 bin/agentlink 的 installBridgeServiceMac 对齐）：
+ *   bootout    —— 现代 unload，先拆掉任何同 label 的旧实例（幂等，未加载也无妨）
+ *   bootstrap  —— 把 job 加载进 GUI domain
+ *   enable     —— 清掉上一次 unload -w / disable 留下的 stale "disabled" override
+ *   kickstart -k —— 强制真正运行（已在跑则重启），不再靠 RunAtLoad 的运气
+ *
+ * 纯函数：返回有序的 { cmd, args } 列表，便于单测；实际执行在 macInstall。
+ */
+export function buildMacInstallSteps({ uid, label, plistPath }) {
+  const domain = `gui/${uid}`;
+  const service = `gui/${uid}/${label}`;
+  return [
+    { cmd: "launchctl", args: ["bootout", domain, plistPath] },
+    { cmd: "launchctl", args: ["bootstrap", domain, plistPath] },
+    { cmd: "launchctl", args: ["enable", service] },
+    { cmd: "launchctl", args: ["kickstart", "-k", service] },
+  ];
+}
+
+/**
+ * 解析 `launchctl print gui/<uid>/<label>` 的关键字段。纯函数，便于单测。
+ * 只有 print 能暴露 `runs`，识破 pid 文件看不出的 "loaded but runs=0" 陷阱。
+ */
+export function parseLaunchctlPrint(out) {
+  const h = { state: null, pid: null, runs: null, lastExitCode: null };
+  for (const line of String(out || "").split(/\r?\n/)) {
+    const t = line.trim();
+    let m;
+    if ((m = t.match(/^state\s*=\s*(.+)$/))) h.state = m[1].trim();
+    else if ((m = t.match(/^pid\s*=\s*(\d+)$/))) h.pid = Number(m[1]);
+    else if ((m = t.match(/^runs\s*=\s*(\d+)$/))) h.runs = Number(m[1]);
+    else if ((m = t.match(/^last exit code\s*=\s*(\d+)$/))) h.lastExitCode = Number(m[1]);
+  }
+  h.running = (h.state || "").toLowerCase() === "running" || (h.pid != null && h.pid > 0);
+  return h;
+}
+
+async function macInstall(runtime, log) {
+  const bin = agentBinPath();
+  const node = process.execPath;
+  const state = ensureStateOrFail(runtime);
+  const label = macLabel(runtime);
+  const plistPath = macPlistPath(runtime);
+  const logDir = path.join(os.homedir(), ".agentlink", "logs");
+  fs.mkdirSync(logDir, { recursive: true });
+
+  // align-runtime-default-workspace: 仅 claude/codex 注入 WorkingDirectory
+  // install 前确保目录存在（否则 launchd 因 WorkingDirectory 不存在拒绝启动）
+  let workingDirectory = null;
+  if (runtime === "claude" || runtime === "codex") {
+    workingDirectory = await ensureDefaultWorkspace(runtime);
+  }
+  const stdoutLog = path.join(logDir, `service-${runtime}.out.log`);
+  const stderrLog = path.join(logDir, `service-${runtime}.err.log`);
+
+  // 关键：launchd 启动的进程默认 PATH 很短，收不到终端 rc 里的 PATH。
+  // agentlink-agent 之后要 spawn `claude` / `codex`，若 PATH 没它们所在目录 → ENOENT → 崩溃。
+  // 策略：取用户当前 shell 里的 PATH（安装命令执行时的环境），再并入常见 brew/npm 路径。
+  const pathParts = new Set();
+  for (const p of (process.env.PATH || "").split(":")) {
+    if (p) pathParts.add(p);
+  }
+  for (const p of [
+    "/opt/homebrew/bin", "/opt/homebrew/sbin",
+    "/usr/local/bin", "/usr/local/sbin",
+    path.join(os.homedir(), ".npm-global/bin"),
+    path.join(os.homedir(), ".nvm/versions/node"),
+    "/usr/bin", "/bin", "/usr/sbin", "/sbin",
+  ]) {
+    pathParts.add(p);
+  }
+  const mergedPath = [...pathParts].filter(Boolean).join(":");
+
+  const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTD/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${label}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${node}</string>
+    <string>${bin}</string>
+    <string>${runtime}</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>ThrottleInterval</key><integer>10</integer>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>AGENTLINK_RELAY_URL</key><string>${escapeXml(state.relay_url)}</string>
+    <key>AGENTLINK_AGENT_LOG_LEVEL</key><string>info</string>
+    <key>PATH</key><string>${escapeXml(mergedPath)}</string>
+    <key>HOME</key><string>${escapeXml(os.homedir())}</string>
+  </dict>${workingDirectory ? `
+  <key>WorkingDirectory</key><string>${escapeXml(workingDirectory)}</string>` : ""}
+  <key>StandardOutPath</key><string>${stdoutLog}</string>
+  <key>StandardErrorPath</key><string>${stderrLog}</string>
+</dict>
+</plist>
+`;
+  fs.mkdirSync(path.dirname(plistPath), { recursive: true });
+  fs.writeFileSync(plistPath, plist, "utf8");
+  log?.info("service.install", "plist written", { path: plistPath, label });
+
+  // 现代序列 bootout→bootstrap→enable→kickstart（见 buildMacInstallSteps 注释）。
+  const uid = macUid();
+  const steps = buildMacInstallSteps({ uid, label, plistPath });
+  let bootstrapOk = false;
+  let kickstart = null;
+  for (const step of steps) {
+    const verb = step.args[0];
+    const r = spawnSync(step.cmd, step.args, { encoding: "utf8" });
+    // bootout 对未加载的 job 必然失败——幂等忽略。
+    if (verb === "bootout") continue;
+    if (verb === "bootstrap") {
+      bootstrapOk = r.status === 0;
+      // bootstrap 失败常见于 job 已加载（EALREADY/5）；enable+kickstart 仍可救回，
+      // 故不在此抛错，留到最后看 kickstart 结果。
+      continue;
+    }
+    if (verb === "enable") continue; // 清 disabled override，失败无妨
+    if (verb === "kickstart") kickstart = r;
+  }
+
+  if (!kickstart || kickstart.status !== 0) {
+    // 现代序列没能拉起——回退 legacy load -w 兜底（与 bin/agentlink 一致）。
+    log?.warn("service.install", "modern launchctl sequence failed, falling back to load -w", {
+      bootstrap_ok: bootstrapOk,
+      kickstart_err: (kickstart?.stderr || kickstart?.stdout || "").trim(),
+    });
+    const fallback = spawnSync("launchctl", ["load", "-w", plistPath], { encoding: "utf8" });
+    if (fallback.status !== 0) {
+      const msg = (kickstart?.stderr || kickstart?.stdout || fallback.stderr || fallback.stdout || "").trim();
+      throw new Error(`launchctl bootstrap/kickstart failed: ${msg || "unknown"}`);
+    }
+  }
+  return { backend: "launchd", path: plistPath, label, logs: { out: stdoutLog, err: stderrLog } };
+}
+
+function macUninstall(runtime) {
+  const plistPath = macPlistPath(runtime);
+  const uid = macUid();
+  // bootout 是现代 unload；gui 与 user domain 都试一遍兜旧装法。
+  spawnSync("launchctl", ["bootout", `gui/${uid}`, plistPath], { encoding: "utf8" });
+  spawnSync("launchctl", ["bootout", `user/${uid}`, plistPath], { encoding: "utf8" });
+  // 兼容历史用 load -w 装的实例。
+  spawnSync("launchctl", ["unload", plistPath], { encoding: "utf8" });
+  try { fs.unlinkSync(plistPath); } catch {}
+  return { backend: "launchd", path: plistPath };
+}
+
+function macStatus(runtime) {
+  const label = macLabel(runtime);
+  const uid = macUid();
+  // launchctl print 能暴露 runs/state，识破 "loaded but runs=0" 陷阱。
+  const out = spawnSync("launchctl", ["print", `gui/${uid}/${label}`], { encoding: "utf8" });
+  if (out.status !== 0) {
+    // 未加载（job 不存在）→ print 返回非 0。
+    return { backend: "launchd", running: false };
+  }
+  const h = parseLaunchctlPrint(out.stdout);
+  return {
+    backend: "launchd",
+    running: h.running,
+    pid: h.pid,
+    runs: h.runs,
+    state: h.state,
+    last_exit: h.lastExitCode,
+  };
+}
+
+// ===== Linux systemd (user) =====
+function sdUnitName(runtime) { return `agentlink-agent-${runtime}.service`; }
+function sdUnitPath(runtime) {
+  return path.join(os.homedir(), ".config", "systemd", "user", sdUnitName(runtime));
+}
+
+function systemdAvailable() {
+  return spawnSync("systemctl", ["--user", "status"], { encoding: "utf8" }).status !== 127;
+}
+
+async function sdInstall(runtime, log) {
+  if (!systemdAvailable()) {
+    throw new Error(
+      "systemd user unit 不可用（systemctl 未安装）。" +
+      "请用 tmux/nohup 保活，或等未来支持 cron/init.d。",
+    );
+  }
+  const bin = agentBinPath();
+  const node = process.execPath;
+  const state = ensureStateOrFail(runtime);
+  const unitPath = sdUnitPath(runtime);
+  const logDir = path.join(os.homedir(), ".agentlink", "logs");
+  fs.mkdirSync(logDir, { recursive: true });
+
+  // align-runtime-default-workspace: 仅 claude/codex 注入 WorkingDirectory
+  // install 前确保目录存在（否则 systemd 因 WorkingDirectory 不存在拒绝启动）
+  let workingDirectoryLine = "";
+  if (runtime === "claude" || runtime === "codex") {
+    const wsPath = await ensureDefaultWorkspace(runtime);
+    workingDirectoryLine = `WorkingDirectory=${wsPath}`;
+  }
+
+  // 同 macOS：systemd user unit 也要扩 PATH，确保能找到 claude / codex
+  const pathEnv = (process.env.PATH || "/usr/local/bin:/usr/bin:/bin") +
+      ":/usr/local/bin:/opt/homebrew/bin:" +
+      path.join(os.homedir(), ".npm-global/bin");
+  const unit = `[Unit]
+Description=Agentlink Agent (${runtime})
+After=network-online.target
+
+[Service]
+Type=simple
+Environment=AGENTLINK_RELAY_URL=${state.relay_url}
+Environment=AGENTLINK_AGENT_LOG_LEVEL=info
+Environment=PATH=${pathEnv}
+Environment=HOME=${os.homedir()}${workingDirectoryLine ? `\n${workingDirectoryLine}` : ""}
+ExecStart=${node} ${bin} ${runtime}
+Restart=on-failure
+RestartSec=10s
+StandardOutput=append:${logDir}/service-${runtime}.out.log
+StandardError=append:${logDir}/service-${runtime}.err.log
+
+[Install]
+WantedBy=default.target
+`;
+  fs.mkdirSync(path.dirname(unitPath), { recursive: true });
+  fs.writeFileSync(unitPath, unit, "utf8");
+  log?.info("service.install", "unit written", { path: unitPath });
+
+  const daemon = spawnSync("systemctl", ["--user", "daemon-reload"], { encoding: "utf8" });
+  if (daemon.status !== 0) throw new Error(`daemon-reload failed: ${daemon.stderr}`);
+  const enable = spawnSync("systemctl", ["--user", "enable", "--now", sdUnitName(runtime)], { encoding: "utf8" });
+  if (enable.status !== 0) throw new Error(`enable --now failed: ${enable.stderr}`);
+
+  return { backend: "systemd-user", path: unitPath, logs: { dir: logDir } };
+}
+
+function sdUninstall(runtime) {
+  spawnSync("systemctl", ["--user", "disable", "--now", sdUnitName(runtime)], { encoding: "utf8" });
+  try { fs.unlinkSync(sdUnitPath(runtime)); } catch {}
+  spawnSync("systemctl", ["--user", "daemon-reload"], { encoding: "utf8" });
+  return { backend: "systemd-user", path: sdUnitPath(runtime) };
+}
+
+function sdStatus(runtime) {
+  const r = spawnSync("systemctl", ["--user", "is-active", sdUnitName(runtime)], { encoding: "utf8" });
+  const running = (r.stdout || "").trim() === "active";
+  return { backend: "systemd-user", running };
+}
+
+// ===== Windows schtasks =====
+function winTaskName(runtime) { return `Agentlink\\Agent-${runtime}`; }
+
+function winInstall(runtime, log) {
+  const bin = agentBinPath();
+  const node = process.execPath;
+  const state = ensureStateOrFail(runtime);
+  // ONLOGON + failure restart. 简化起见不加 env —— Windows schtasks 设置 env 要走注册表，麻烦。
+  // 把 relay url 作为 CLI 参数传入：
+  const args = `"${bin}" ${runtime} --relay ${state.relay_url}`;
+  const tr = `"${node}" ${args}`;
+  const create = spawnSync("schtasks", [
+    "/Create", "/F",
+    "/TN", winTaskName(runtime),
+    "/TR", tr,
+    "/SC", "ONLOGON",
+    "/RL", "LIMITED",
+  ], { encoding: "utf8" });
+  if (create.status !== 0) {
+    throw new Error(`schtasks /Create failed: ${create.stderr || create.stdout}`);
+  }
+  log?.info("service.install", "scheduled task created", { task: winTaskName(runtime) });
+  return { backend: "schtasks", task: winTaskName(runtime) };
+}
+
+function winUninstall(runtime) {
+  const r = spawnSync("schtasks", ["/Delete", "/F", "/TN", winTaskName(runtime)], { encoding: "utf8" });
+  return { backend: "schtasks", task: winTaskName(runtime), deleted: r.status === 0 };
+}
+
+function winStatus(runtime) {
+  const r = spawnSync("schtasks", ["/Query", "/TN", winTaskName(runtime), "/FO", "LIST"], { encoding: "utf8" });
+  if (r.status !== 0) return { backend: "schtasks", running: false };
+  const m = (r.stdout || "").match(/Status:\s*(\w+)/i);
+  return { backend: "schtasks", running: m ? m[1].toLowerCase() === "running" : false, raw: r.stdout.trim() };
+}
+
+// ===== 分发 =====
+export async function serviceInstall(runtime, log) {
+  ensureRuntime(runtime);
+  if (process.platform === "darwin") return macInstall(runtime, log);
+  if (process.platform === "linux") return sdInstall(runtime, log);
+  if (process.platform === "win32") return winInstall(runtime, log);
+  throw new Error(`unsupported platform: ${process.platform}`);
+}
+
+export function serviceUninstall(runtime, log) {
+  ensureRuntime(runtime);
+  if (process.platform === "darwin") return macUninstall(runtime);
+  if (process.platform === "linux") return sdUninstall(runtime);
+  if (process.platform === "win32") return winUninstall(runtime);
+  throw new Error(`unsupported platform: ${process.platform}`);
+}
+
+export function serviceStatus(runtime) {
+  ensureRuntime(runtime);
+  if (process.platform === "darwin") return macStatus(runtime);
+  if (process.platform === "linux") return sdStatus(runtime);
+  if (process.platform === "win32") return winStatus(runtime);
+  throw new Error(`unsupported platform: ${process.platform}`);
+}
+
+// ── Reload (restart existing service without re-installing) ─────────────────
+//
+// 语义：只针对"已安装的" service 做进程重启。用于开发者更新代码后希望让
+// 长寿 agent 进程重新加载模块。找不到已安装 service 的返回 "not-installed"，
+// 不视为错误。
+//
+// 三端实现：
+//   - macOS:   launchctl kickstart -k gui/$UID/<label>         （先探测 `launchctl print`）
+//   - Linux:   systemctl --user restart <unit>                 （先探测 `list-unit-files`）
+//   - Windows: schtasks /End + /Run <task>                     （先探测 `schtasks /Query`）
+
+export function serviceReload(runtime) {
+  ensureReloadRuntime(runtime);
+  if (process.platform === "darwin") return macReload(runtime);
+  if (process.platform === "linux") return sdReload(runtime);
+  if (process.platform === "win32") return winReload(runtime);
+  throw new Error(`unsupported platform: ${process.platform}`);
+}
+
+/**
+ * 重启所有已知 runtime。返回 { [runtime]: result }，每项有 status 字段
+ * （"restarted" / "not-installed" / "error"）。
+ */
+export function serviceReloadAll() {
+  const out = {};
+  for (const rt of Object.keys(ALL_RELOAD_TARGETS)) {
+    try {
+      out[rt] = serviceReload(rt);
+    } catch (err) {
+      out[rt] = { status: "error", error: err?.message || String(err) };
+    }
+  }
+  return out;
+}
+
+// macOS reload
+function macReload(runtime) {
+  const label = ALL_RELOAD_TARGETS[runtime].mac;
+  const uid = typeof process.getuid === "function" ? process.getuid() : 0;
+  const ref = `gui/${uid}/${label}`;
+  const present = spawnSync("launchctl", ["print", ref], { encoding: "utf8" });
+  if (present.status !== 0) {
+    return { status: "not-installed", backend: "launchd", label };
+  }
+  const r = spawnSync("launchctl", ["kickstart", "-k", ref], { encoding: "utf8" });
+  if (r.status !== 0) {
+    const msg = (r.stderr || r.stdout || "").trim();
+    throw new Error(`launchctl kickstart failed: ${msg || "exit " + r.status}`);
+  }
+  return { status: "restarted", backend: "launchd", label, ref };
+}
+
+// Linux systemd user reload
+function sdReload(runtime) {
+  const unit = ALL_RELOAD_TARGETS[runtime].linux;
+  // list-unit-files 可同时检测 masked/enabled/disabled；exit 0 表示 unit 存在。
+  // 另一种探测：`systemctl --user cat <unit>` —— 不存在会返回非 0。
+  const probe = spawnSync("systemctl", ["--user", "cat", unit], { encoding: "utf8" });
+  if (probe.status !== 0) {
+    return { status: "not-installed", backend: "systemd-user", unit };
+  }
+  const r = spawnSync("systemctl", ["--user", "restart", unit], { encoding: "utf8" });
+  if (r.status !== 0) {
+    const msg = (r.stderr || r.stdout || "").trim();
+    throw new Error(`systemctl --user restart failed: ${msg || "exit " + r.status}`);
+  }
+  return { status: "restarted", backend: "systemd-user", unit };
+}
+
+// Windows schtasks reload
+function winReload(runtime) {
+  const task = ALL_RELOAD_TARGETS[runtime].win;
+  const probe = spawnSync("schtasks", ["/Query", "/TN", task, "/FO", "LIST"], { encoding: "utf8" });
+  if (probe.status !== 0) {
+    return { status: "not-installed", backend: "schtasks", task };
+  }
+  // /End 若任务没在跑会返回非 0，忽略；/Run 真正触发启动
+  spawnSync("schtasks", ["/End", "/TN", task], { encoding: "utf8" });
+  const r = spawnSync("schtasks", ["/Run", "/TN", task], { encoding: "utf8" });
+  if (r.status !== 0) {
+    const msg = (r.stderr || r.stdout || "").trim();
+    throw new Error(`schtasks /Run failed: ${msg || "exit " + r.status}`);
+  }
+  return { status: "restarted", backend: "schtasks", task };
+}
+
+function escapeXml(s) {
+  return String(s)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}