lark-relay 0.4.2 → 0.4.4

package/README.md

@@ -34,7 +34,7 @@ Lark 事件是**流式**的 -- 进程不在的时刻,消息**永久丢失**,不
 ## 命令
 
 ```bash
-lark-relay collect            # 底座:全部 profile 各起 consume -> 原子落盘(systemd 常驻)
+lark-relay collect            # 底座:全部 profile 各起 consume -> 原子落盘(常驻服务)
 lark-relay take …             # 场景1:阻塞等一批 -> 输出 -> 退出
 lark-relay dispatch <task>    # 场景2:常驻循环 = take + 唤起 claude
 lark-relay status             # 谁在跑 / 各 app 积压 / 各游标位置

package/bin/lark-relay.js

@@ -258,7 +258,12 @@ async function cmdDispatch(argv) {
   if (a.list) return dispatch.cmdList()
   const task = a._[0]
   if (!task) {
-    process.stdout.write(`${help.DISPATCH_HELP}\n`)
+    // 空参 = 求教,和 take 一致(exit 0);带了 flag 却没任务名是写错,短错误
+    if (argv.length === 0) {
+      process.stdout.write(`${help.DISPATCH_HELP}\n`)
+      return 0
+    }
+    process.stderr.write('需要任务名($LR_ROOT/<任务名>/dispatch.yaml)。看现有任务:`lark-relay dispatch --list`\n')
     return 2
   }
   return await dispatch.run(task, { once: !!a.once })

package/lib/collect.js

@@ -120,7 +120,7 @@ async function runCollect(opts) {
         `collect 依赖 lark-cli 提供认证与事件总线。检查:\n` +
         `  which ${larkcli.CLI}          # 装了吗、在 PATH 里吗\n` +
         `  ${larkcli.CLI} profile list   # 能跑吗\n` +
-        `systemd 单元里 PATH 要用 fnm default alias 的稳定路径,不能用会话级的 multishell 路径`,
+        `常驻服务(systemd 单元/launchd plist)的 PATH 要用 fnm default alias 的稳定路径,不能用会话级的 multishell 路径`,
     )
     e.userFacing = true
     throw e

package/lib/help.js

@@ -53,7 +53,7 @@ function takeHelp(apps) {
 const COLLECT_HELP = `把全部 lark-cli profile 的事件收下来,原子落盘。零参数、零配置。
 
   lark-relay collect                    # 前台跑(调试)
-  systemctl enable --now lark-relay-collect   # 常驻(推荐)
+  常驻:Linux 用 systemd,macOS 用 launchd(单元模板见仓库 systemd//launchd 目录)
 
 app 列表实时读 \`lark-cli profile list\`,新增 profile 自动纳入,无需改配置。
 每 app 一个子进程;某个挂了单独重启,不影响其他。
@@ -64,6 +64,9 @@ tokenStatus 为 expired 的 profile 自动跳过并 warn(永久失败,重试是
 8s 后才起 consumer,收到 0 条)。collect 独立常驻,才能让 take/dispatch 侧
 崩了、claude 跑 30 分钟、会话关几小时,都不丢消息。
 
+装完先 \`lark-relay status\` 确认 -- collect 行应为 running;不在跑看
+服务日志(Linux \`journalctl -u lark-relay-collect\`;macOS \`log show --predicate 'process == "lark-relay"'\`)。
+
 落盘:~/.lark-relay/store/<app>/<YYYY-MM-DD>/<纳秒>_<pid>_<seq>.json
 回收由 collect 进程内每小时自查一次,删超期的整个日期目录(不另起 gc 单元/timer)。
 
@@ -78,15 +81,17 @@ const STATUS_HELP = `一眼看清全局:谁在跑、积压多少、游标在哪
   lark-relay status --json       # 机器可读
 
 排障入口:某消费者「落后」很多 -> 它的 take/dispatch 没在跑或卡住;
-「无消费者」= 白采,可考虑 --exclude。`
+「无消费者」= 白采,可考虑 --exclude。
+collect 行不是 running -> 看服务日志(systemd journal 或 launchd 统一日志),
+collect 停摆的每一秒都在丢消息。`
 
 const DISPATCH_HELP = `常驻:等消息 -> 唤起 claude 干活 -> 结果回群。无人在场也跑。
 
   lark-relay dispatch --list          # 列出所有 dispatch 任务及状态
-  lark-relay dispatch <task> --once   # 前台跑一轮(调试,不进 systemd)
-  systemctl enable --now lark-relay-dispatch@<task>
+  lark-relay dispatch <task> --once   # 前台跑一轮(调试,不进常驻服务)
+  常驻:Linux 用 systemd,macOS 用 launchd(单元模板见仓库 systemd//launchd 目录)
 
---list 输出:任务名 / app / 群数 / systemd 单元是否 active / 上次 ledger 时间
+--list 输出:任务名 / app / 群数 / 常驻服务是否 active / 上次 ledger 时间
 
 任务发现:扫 $LR_ROOT/*/dispatch.yaml -- 有文件即是任务,无需注册表。
 LR_ROOT 在单元里指定(唯一的目录绑定,与代码无关)。
@@ -115,7 +120,13 @@ mode 三个场景(一个键定死全部行为,不用拼组合)
 最佳实践
   · 边界写 instructions,别指望 --add-dir 目录的 CLAUDE.md(启动不加载)
   · 改完 yaml 先 --once 跑一轮验证,再 enable
-  · 高风险发布仍建议人工执行`
+  · 高风险发布仍建议人工执行
+
+退出码(--once)
+  0  跑了一轮,或没等到消息但正常结束
+  1  取批异常(看 stderr)
+  2  任务不存在或配置错
+  4  等消息超时(5min 没消息)`
 
 const GUIDE = `lark-relay -- Lark 事件中继站。三个命令:收下来 / 我来取 / 派给别人。
 
@@ -136,6 +147,7 @@ const GUIDE = `lark-relay -- Lark 事件中继站。三个命令:收下来 / 我
 前置:collect 必须在跑
   lark-relay status        # collect 行应为 running
   进程不在的时刻消息永久丢失,不是延迟送达。
+  不在跑 -> 起常驻服务(Linux systemd / macOS launchd,模板见仓库;或 \`lark-relay collect\` 前台调试)
 
 take 三步(照做)
   1. 查群 ID   lark-cli --profile <app> im +chat-search --as user --query "<群名>"
@@ -150,7 +162,7 @@ take 三步(照做)
 建 dispatch 任务
   1. 在任务目录写 dispatch.yaml(\`lark-relay dispatch --help\` 有模板)
   2. lark-relay dispatch <task> --once     # 前台验一轮
-  3. systemctl enable --now lark-relay-dispatch@<task>
+  3. 起常驻服务(Linux systemd / macOS launchd,模板见仓库)
 
 常见错误
   · 拿不到消息 -> 九成是 bot 不在群。验 bot 必须 --as user,

package/lib/status.js

@@ -39,6 +39,39 @@ function unitMainPid(unit) {
   }
 }
 
+// 服务管理器按平台分治:Linux systemd / macOS launchd。
+// 单元名/label 是部署约定,与 systemd 单元、launchd plist 同源;
+// LR_COLLECT_LABEL / LR_DISPATCH_LABEL_PREFIX 是改名部署的逃生舱。
+const COLLECT_LABEL = process.env.LR_COLLECT_LABEL || 'com.adaex.lark-relay-collect'
+const DISPATCH_LABEL_PREFIX = process.env.LR_DISPATCH_LABEL_PREFIX || 'com.adaex.lark-relay-dispatch'
+
+function launchctlState(label) {
+  try {
+    const out = execFileSync('launchctl', ['print', `system/${label}`], { encoding: 'utf8' })
+    const state = (out.match(/^\s*state\s*=\s*(\S+)/m) || [])[1]
+    const pid = Number((out.match(/^\s*pid\s*=\s*(\d+)/m) || [])[1]) || null
+    return { state: state === 'running' ? 'active' : state || 'inactive', pid }
+  } catch {
+    return { state: 'inactive', pid: null }
+  }
+}
+
+// kind: 'collect' | 'dispatch';dispatch 带任务名。
+function serviceState(kind, name) {
+  if (process.platform === 'darwin') {
+    const label = kind === 'collect' ? COLLECT_LABEL : `${DISPATCH_LABEL_PREFIX}.${name}`
+    return launchctlState(label)
+  }
+  const unit = kind === 'collect' ? 'lark-relay-collect.service' : `lark-relay-dispatch@${name}.service`
+  return { state: unitState(unit), pid: unitMainPid(unit) }
+}
+
+function collectHint() {
+  return process.platform === 'darwin'
+    ? `sudo launchctl bootstrap system /Library/LaunchDaemons/${COLLECT_LABEL}.plist`
+    : 'systemctl enable --now lark-relay-collect'
+}
+
 // 消费者 = cursors/ 下的目录。每个记录它在各 app 上的游标位置。
 function listConsumers() {
   let names
@@ -75,9 +108,7 @@ function lagOf(app, cursor) {
 }
 
 async function buildStatus() {
-  const collectUnit = 'lark-relay-collect.service'
-  const state = unitState(collectUnit)
-  const pid = unitMainPid(collectUnit)
+  const { state, pid } = serviceState('collect')
 
   let profiles = []
   try {
@@ -111,7 +142,6 @@ async function buildStatus() {
 
   const tasks = []
   for (const t of listTasks()) {
-    const unit = `lark-relay-dispatch@${t.name}.service`
     let lastLedgerMs = null
     for (const chat of t.config.chats || []) {
       try {
@@ -123,12 +153,12 @@ async function buildStatus() {
       name: t.name,
       app: t.config.app,
       chats: (t.config.chats || []).length,
-      state: unitState(unit),
+      state: serviceState('dispatch', t.name).state,
       lastLedgerMs,
     })
   }
 
-  return { collect: { state, pid, usable, expired }, apps: rows, tasks }
+  return { collect: { state, pid, usable, expired, hint: collectHint() }, apps: rows, tasks }
 }
 
 function formatStatus(s) {
@@ -145,7 +175,7 @@ function formatStatus(s) {
   out.push(head)
   if (s.collect.state !== 'active') {
     out.push('  ⚠ collect 没在跑 —— 此刻的消息会永久丢失,不是延迟送达')
-    out.push('    systemctl enable --now lark-relay-collect')
+    out.push(`    ${s.collect.hint}`)
   }
   out.push('')
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lark-relay",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Lark event relay: collect events to disk, take a batch when you need it, or dispatch work to an AI agent.",
   "keywords": [
     "lark",