lark-relay 0.6.6 → 0.6.7

package/bin/lark-relay.js

@@ -10,7 +10,12 @@ const USAGE = `lark-relay ${VERSION} -- Lark 事件中继站
 
   lark-relay take ...           阻塞等一批 -> 输出 -> 退出
   lark-relay status             采集状态 / 事件数量 / 消费断点
-  lark-relay-collect            常驻采集
+  lark-relay-collect            常驻采集(前台)
+
+常驻部署(macOS/launchd,需 sudo):
+  lark-relay install            装或重装常驻服务(plist 按当前环境生成)
+  lark-relay restart            只改了代码时重启到新版本
+  lark-relay uninstall          停服务并删 plist
 
 用法详情: lark-relay take --help`
 
@@ -18,6 +23,7 @@ async function main() {
   const [cmd, ...rest] = process.argv.slice(2)
   if (cmd === 'take') return cmdTake(rest)
   if (cmd === 'status') return cmdStatus(rest)
+  if (cmd === 'install' || cmd === 'uninstall' || cmd === 'restart') return cmdService(cmd, rest)
   if (cmd && !cmd.startsWith('-')) {
     process.stderr.write(`未知命令:${cmd}\n${USAGE}\n`)
     return 2
@@ -27,6 +33,16 @@ async function main() {
   return 0
 }
 
+async function cmdService(cmd, argv) {
+  const a = parseArgs(argv, {})
+  if (a.help) {
+    process.stdout.write(`${help.SERVICE_HELP}\n`)
+    return 0
+  }
+  const service = require('../lib/service')
+  return service[cmd]({ log: (line) => process.stdout.write(`${line}\n`) })
+}
+
 async function cmdTake(argv) {
   const a = parseArgs(argv, { keys: TAKE_KEYS })
   if (a.help || argv.length === 0) {

package/lib/help.js

@@ -68,9 +68,30 @@ const STATUS_HELP = `lark-relay status -- 采集状态、事件数量和消费
 
 消费者以持锁进程是否存活区分在跑/未运行,未运行的断点仍保留
 首次 --since all 等待中也会保留起始断点
-profiles 列出已配置项,不表示正在采集,也不反映 collect 的 --exclude
+profiles 列出已配置项,不表示正在采集
 profile 查询失败时保留本地状态并以 exit 1 返回,错误见 collect.profileError
 扫描全部保留日期,任意位置的损坏事件都标记 ⚠ 并以 exit 1 返回,其余 app 照常显示
 collect running 只表示主进程在跑,各 app 的连接状态需查看采集日志`
 
-module.exports = { TAKE_HELP, COLLECT_HELP, STATUS_HELP }
+const SERVICE_HELP = `常驻部署 -- 把采集装成 launchd 服务(仅 macOS,需 sudo)
+
+  sudo -v && lark-relay install      装或重装(幂等;已在跑则先停再起)
+  sudo -v && lark-relay restart      只改了代码时重启到新版本
+  sudo -v && lark-relay uninstall    停服务并删 plist
+
+plist **按当前机器生成**,不存仓内文件:可执行文件位置、HOME、PATH、日志路径
+都是本机事实,存成文件就得写死用户名,换机器即失效。改行为去改 lib/service.js
+
+install 会做:探 sudo 凭据(失败则不动服务) -> 定位 lark-relay-collect ->
+建日志目录 -> 生成并 plutil 校验 plist -> 卸旧实例并等 label 释放 ->
+装到 /Library/LaunchDaemons -> bootstrap(最多 3 次) -> 轮询等 state=running
+
+**install 与 uninstall 都有丢消息窗口**:事件 8 秒零回放,停摆期间的消息永久丢失,
+选空闲时段执行。发布流程里改了代码用 restart(不重写 plist)就够
+
+label 由 LR_COLLECT_LABEL 覆盖,默认 local.lark-relay-collect;
+status 与本组命令共用同一个定义,不会出现「服务正常却报没在跑」
+
+退出码:0=成功,1=运行错误(服务状态见输出),2=参数错/缺 sudo/非 macOS`
+
+module.exports = { TAKE_HELP, COLLECT_HELP, STATUS_HELP, SERVICE_HELP }

package/lib/service.js

@@ -0,0 +1,297 @@
+'use strict'
+
+// launchd 常驻部署:install / uninstall / restart。
+//
+// **plist 运行时生成，不存仓内文件**：它的每个值都是「当前机器的事实」——
+// 可执行文件位置(fnm 切版本就变)、HOME、PATH、日志路径。存成文件就得写死
+// /Users/<名>，换机器或换用户名即失效，还要靠安装脚本 sed 替换回来。
+// 生成则一律取自 process，零写死路径(2026-09-11 从 deploy-launchd.sh 收进 CLI)。
+//
+// 仅 macOS/launchd:Linux 侧不做常驻(CONVENTIONS.md 的引擎边界)。
+const { execFileSync, execSync } = require('child_process')
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+
+const LABEL = process.env.LR_COLLECT_LABEL || 'local.lark-relay-collect'
+const PLIST_PATH = `/Library/LaunchDaemons/${LABEL}.plist`
+
+function die(message, exitCode = 1) {
+  throw Object.assign(new Error(message), { userFacing: true, exitCode })
+}
+
+function requireDarwin() {
+  if (process.platform !== 'darwin') {
+    die(`常驻部署仅支持 macOS/launchd,当前 ${process.platform}`, 2)
+  }
+}
+
+// 采集入口的真实路径。**不能用 process.argv[1]**：那是 lark-relay 而非
+// lark-relay-collect;也不能拼 __dirname，全局安装下 bin 有 npm 生成的 shim。
+//
+// **which 的结果要归一到 fnm 的稳定别名目录**：终端里 PATH 首位是
+// fnm multishell 的临时目录(~/.local/state/fnm_multishells/<pid>_<ts>/bin)，
+// 那个目录随 shell 会话消失，写进 plist 则重启后 launchd 找不到程序。
+// $FNM_DIR/aliases/default 是符号链，跟随 fnm default 切换，长期有效。
+// 不用 fnm 时(brew/系统 node)which 的结果本身就稳定，原样返回
+function stableBin(bin) {
+  if (!bin.includes('fnm_multishells')) return bin
+  const fnmDir = process.env.FNM_DIR || path.join(os.homedir(), '.local/share/fnm')
+  const alias = path.join(fnmDir, 'aliases/default/bin', path.basename(bin))
+  if (fs.existsSync(alias)) return alias
+  die(
+    `which 只找到 fnm 临时路径 ${bin}，而 ${alias} 不存在。\n` +
+      '  该临时目录随 shell 退出即失效，写进 plist 会导致重启后服务起不来。\n' +
+      '  先 `fnm default <版本>` 并 `npm i -g lark-relay` 让稳定目录里有它。',
+  )
+}
+
+function resolveCollectBin() {
+  try {
+    return stableBin(execFileSync('which', ['lark-relay-collect'], { encoding: 'utf8' }).trim())
+  } catch (err) {
+    if (err.userFacing) throw err
+    die('PATH 里找不到 lark-relay-collect,先 npm i -g lark-relay', 2)
+  }
+}
+
+// launchd 给的默认 PATH 只有 /usr/bin:/bin:/usr/sbin:/sbin,
+// 子进程 lark-cli 与 jq 都找不到。
+//
+// **用固定白名单而非照搬 process.env.PATH**：后者混着 fnm multishell 临时目录、
+// VS Code server 会话目录、/var/run 下的 cryptex 路径这类进程级条目，
+// 写进 plist 就是定时炸弹；且顺序随人当时的 shell 变，两次 install 出不同结果。
+// 只留「采集入口所在目录 + 包管理器前缀 + 系统目录」，去重后拼。
+// home 由调用方传入而不在此处取,便于测试与「装给另一个用户」
+function buildPath(collectBin, home) {
+  const candidates = [
+    path.dirname(collectBin),
+    '/opt/homebrew/bin', '/usr/local/bin', '/usr/local/sbin',
+    path.join(home, '.local/bin'),
+    '/usr/bin', '/bin', '/usr/sbin', '/sbin',
+  ]
+  return [...new Set(candidates)].join(':')
+}
+
+function buildPlist({ collectBin, home, user, logDir }) {
+  const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!--
+  由 \`lark-relay install\` 生成,不要手改 —— 下次 install 会整体覆盖。
+  改行为去改 lib/service.js;形态取舍见 CONVENTIONS.md「launchd 部署」。
+-->
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${esc(LABEL)}</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>${esc(collectBin)}</string>
+    </array>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <!-- launchd 不展开 ~ 和 $VAR,全写字面值;这里是 HOME 的定义源头。
+             不设 LANG:子进程 lark-cli(Node)与 jq 均不依赖 locale 处理中文 -->
+        <key>HOME</key>
+        <string>${esc(home)}</string>
+        <key>PATH</key>
+        <string>${esc(buildPath(collectBin, home))}</string>
+    </dict>
+    <!-- 无头 Mac mini:root 加载、降权跑,开机即起无需登录。
+         LaunchAgent 登出即停,而事件 8 秒零回放,停摆=永久丢消息,故不用 Agent -->
+    <key>UserName</key>
+    <string>${esc(user)}</string>
+    <key>RunAtLoad</key>
+    <true/>
+    <!-- 非零退出时自动重启 -->
+    <key>KeepAlive</key>
+    <dict>
+        <key>SuccessfulExit</key>
+        <false/>
+    </dict>
+    <key>ThrottleInterval</key>
+    <integer>5</integer>
+    <!-- collect 收摊需 3s,保留 5s;event _bus 的退出由其自身管理 -->
+    <key>ExitTimeOut</key>
+    <integer>5</integer>
+    <!-- Standard 避免 Background 的 IO/CPU 节流 -->
+    <key>ProcessType</key>
+    <string>Standard</string>
+    <!-- 日志父目录须已存在,collect 逐行加时间戳;需要缩减时截断文件 -->
+    <key>StandardOutPath</key>
+    <string>${esc(path.join(logDir, 'collect.out.log'))}</string>
+    <key>StandardErrorPath</key>
+    <string>${esc(path.join(logDir, 'collect.err.log'))}</string>
+</dict>
+</plist>
+`
+}
+
+function isLoaded() {
+  try {
+    execFileSync('launchctl', ['print', `system/${LABEL}`], {
+      stdio: ['ignore', 'ignore', 'ignore'],
+    })
+    return true
+  } catch {
+    return false
+  }
+}
+
+function serviceState() {
+  try {
+    const out = execFileSync('launchctl', ['print', `system/${LABEL}`], {
+      encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    })
+    return {
+      state: ((out.match(/^\s*state\s*=\s*(.+)$/m) || [])[1] || '').trim(),
+      pid: Number((out.match(/^\s*pid\s*=\s*(\d+)/m) || [])[1]) || null,
+      program: ((out.match(/^\s*program\s*=\s*(.+)$/m) || [])[1] || '').trim(),
+    }
+  } catch {
+    return { state: '', pid: null, program: '' }
+  }
+}
+
+// sudo 凭据先探再改:失败时服务未被动过,采集照常在跑
+function requireSudo(action) {
+  try {
+    execFileSync('sudo', ['-n', 'true'], { stdio: 'ignore' })
+  } catch {
+    die(
+      `${action} 需要 sudo。请在终端(不是 AI 会话)先认证再跑,凭据会被复用:\n` +
+        `    sudo -v && lark-relay ${action}\n` +
+        '  当前服务未被改动。',
+      2,
+    )
+  }
+}
+
+const sudo = (args) => execFileSync('sudo', args, { stdio: ['ignore', 'ignore', 'pipe'] })
+
+// bootout 是异步的:label 不释放就 bootstrap 会失败。等它真消失
+function waitUnloaded(seconds = 30) {
+  for (let i = 0; i < seconds; i++) {
+    if (!isLoaded()) return true
+    execSync('sleep 1')
+  }
+  return false
+}
+
+// bootstrap 后 launchd 先给 spawn scheduled(已排程、进程未起),
+// 固定等待撞上它会把正常部署报成失败(2026-09-10 实测)。轮询等 state 收敛
+function waitRunning(seconds = 15) {
+  for (let i = 0; i < seconds; i++) {
+    const s = serviceState()
+    if (s.state === 'running') return s
+    execSync('sleep 1')
+  }
+  return serviceState()
+}
+
+function install({ log = () => {} } = {}) {
+  requireDarwin()
+  const collectBin = resolveCollectBin()
+  const home = os.homedir()
+  const user = os.userInfo().username
+  const logDir = path.join(process.env.LARK_RELAY_HOME || path.join(home, '.lark-relay'), 'logs')
+  const version = execFileSync(collectBin, ['--version'], { encoding: 'utf8' }).trim()
+  log(`采集入口:${collectBin}(${version})`)
+
+  requireSudo('install')
+  // launchd 不建目录,日志父目录必须先在
+  fs.mkdirSync(logDir, { recursive: true })
+
+  const body = buildPlist({ collectBin, home, user, logDir })
+  const tmp = path.join(os.tmpdir(), `${LABEL}.${process.pid}.plist`)
+  fs.writeFileSync(tmp, body, { mode: 0o644 })
+  // 装之前先验语法,避免把坏文件 bootstrap 进系统
+  try {
+    execFileSync('plutil', ['-lint', tmp], { stdio: 'ignore' })
+  } catch {
+    fs.unlinkSync(tmp)
+    die('生成的 plist 语法不合法(请报 bug)')
+  }
+
+  const wasLoaded = isLoaded()
+  if (wasLoaded) {
+    log('丢消息窗口从现在开始 --')
+    try { sudo(['launchctl', 'bootout', `system/${LABEL}`]) } catch {}
+    if (!waitUnloaded()) {
+      fs.unlinkSync(tmp)
+      die(`旧实例 30s 未卸载完,手动 sudo launchctl bootout system/${LABEL} 后重试`)
+    }
+  }
+
+  sudo(['install', '-o', 'root', '-g', 'wheel', '-m', '644', tmp, PLIST_PATH])
+  fs.unlinkSync(tmp)
+  log(`plist 已装:${PLIST_PATH}`)
+
+  let bootstrapped = false
+  for (let attempt = 1; attempt <= 3; attempt++) {
+    try {
+      sudo(['launchctl', 'bootstrap', 'system', PLIST_PATH])
+      bootstrapped = true
+      break
+    } catch (err) {
+      const msg = (err.stderr || '').toString().trim()
+      log(`第 ${attempt} 次 bootstrap 失败:${msg}`)
+      if (attempt < 3) execSync('sleep 5')
+    }
+  }
+  if (!bootstrapped) {
+    die(
+      'bootstrap 三次都失败。服务当前**未运行,正在丢消息**。\n' +
+        `  排查:launchctl print system/${LABEL}\n` +
+        '  应急顶住采集(前台跑,不经 launchd):lark-relay-collect',
+    )
+  }
+
+  const s = waitRunning()
+  if (s.state !== 'running' || s.program !== collectBin) {
+    let tail = ''
+    try {
+      tail = fs.readFileSync(path.join(logDir, 'collect.err.log'), 'utf8').split('\n').slice(-5).join('\n')
+    } catch {}
+    die(`部署验证失败:state=${s.state || '未加载'}, program=${s.program}\n${tail}`)
+  }
+  log(`✓ ${wasLoaded ? '已重装' : '已安装'}并运行中(pid ${s.pid})`)
+  log('重连可能持续数分钟(退避重试),期间 status 的 collect 已是 running 但各 app 未必都接上')
+  return 0
+}
+
+function uninstall({ log = () => {} } = {}) {
+  requireDarwin()
+  if (!isLoaded() && !fs.existsSync(PLIST_PATH)) {
+    log('未安装,无需卸载')
+    return 0
+  }
+  requireSudo('uninstall')
+  // 先 bootout 再删文件:只删文件的话跑着的服务会活到下次重启
+  if (isLoaded()) {
+    try { sudo(['launchctl', 'bootout', `system/${LABEL}`]) } catch {}
+    waitUnloaded()
+  }
+  if (fs.existsSync(PLIST_PATH)) {
+    sudo(['rm', '-f', PLIST_PATH])
+    log(`已删:${PLIST_PATH}`)
+  }
+  log('已卸载。采集已停,此刻起的消息永久丢失;重装:lark-relay install')
+  log('日志与事件仍在 ~/.lark-relay/,需要时自行清理')
+  return 0
+}
+
+// 只改了代码、plist 无需变时的快路径
+function restart({ log = () => {} } = {}) {
+  requireDarwin()
+  if (!isLoaded()) die('服务未加载,先 lark-relay install', 2)
+  requireSudo('restart')
+  sudo(['launchctl', 'kickstart', '-k', `system/${LABEL}`])
+  const s = waitRunning()
+  if (s.state !== 'running') die(`重启后未运行:state=${s.state || '未加载'}`)
+  log(`✓ 已重启(pid ${s.pid})`)
+  return 0
+}
+
+module.exports = { LABEL, PLIST_PATH, install, uninstall, restart, serviceState, isLoaded, buildPlist, buildPath }

package/lib/status.js

@@ -1,7 +1,6 @@
 'use strict'
 
 // status:一眼看清全局 —— 谁在跑、各 app 收了多少、游标在哪。
-const { execFileSync } = require('child_process')
 const path = require('path')
 const store = require('./store')
 const larkcli = require('./larkcli')
@@ -17,24 +16,13 @@ function ago(ms) {
   return `${Math.round(s / 86400)}d ago`
 }
 
-const COLLECT_LABEL = process.env.LR_COLLECT_LABEL || 'com.adaex.lark-relay-collect'
+// label 与 launchd 查询都归 service.js，不在两处各定义一份
+// （改名时漏掉一处就会「服务正常却报没在跑」）
+const { LABEL: COLLECT_LABEL, serviceState: rawServiceState } = require('./service')
 
 function serviceState() {
-  try {
-    // stderr 必须 ignore:launchctl 对不存在的服务把 "Bad request" 写到 stderr
-    const out = execFileSync('launchctl', ['print', `system/${COLLECT_LABEL}`], {
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'ignore'],
-    })
-    // state 可以是多词值,如 not running
-    const state = (out.match(/^\s*state\s*=\s*(.+)$/m) || [])[1]
-    const pid = Number((out.match(/^\s*pid\s*=\s*(\d+)/m) || [])[1]) || null
-    const s = (state || '').trim()
-    return { state: s === 'running' ? 'active' : s || 'inactive', pid }
-  } catch (err) {
-    if (err.status === 113) return { state: 'inactive', pid: null }
-    throw err
-  }
+  const s = rawServiceState()
+  return { state: s.state === 'running' ? 'active' : s.state || 'inactive', pid: s.pid }
 }
 
 // 枚举游标:cursors/<name>/<app>。活消费者判定复用 take 的锁,不另造注册表
@@ -104,7 +92,7 @@ async function buildStatus() {
       pid,
       profiles,
       profileError,
-      hint: `sudo launchctl bootstrap system /Library/LaunchDaemons/${COLLECT_LABEL}.plist`,
+      hint: 'sudo -v && lark-relay install',
     },
     apps: rows,
     cursorsDir: paths.cursors,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lark-relay",
-  "version": "0.6.6",
+  "version": "0.6.7",
   "description": "Lark event relay: collect events to disk, take a batch when you need it.",
   "keywords": [
     "lark",