lark-relay 0.4.6 → 0.4.7

package/README.md

@@ -1,13 +1,13 @@
 # lark-relay
 
-Lark(飞书)事件中继站。三个命令:**收下来** / **我来取** / **派给别人**。
+Lark(飞书)事件中继站。两件事:**收下来** / **我来取**。
 
 依赖 [`lark-cli`](https://www.npmjs.com/package/@lark-base-open/lark-cli) 提供认证与
-事件总线;本包只负责缓冲、批次与派活,零 npm 依赖。
+事件总线;本包只负责缓冲与批次,零 npm 依赖。
 
 ```bash
-npm i -g lark-relay
-lark-relay guide          # 装完先读这个
+npm i -g lark-relay      # 装出两个命令:lark-relay-collect(常驻)/ lark-relay(在场)
+lark-relay guide         # 装完先读这个
 ```
 
 ## 为什么需要它
@@ -16,14 +16,17 @@ Lark 事件是**流式**的 -- 进程不在的时刻,消息**永久丢失**,不
 (实测:消息发出 8 秒后才起 consumer,收到 0 条)。
 
 所以要有一个常驻进程只管把事件收下来落盘,消费侧崩了、AI 跑了半小时、
-会话关了几小时,都不丢消息。这就是 `collect`。
+会话关了几小时,都不丢消息。这就是 `lark-relay-collect`。
 
 ## 两段分离
 
-采集与消费必须分离:`collect` 只管把事件收下来落盘,`take` 在你需要时取走一批。
-消费侧崩了、AI 跑了半小时、会话关了几小时,采集都不能停 --
+采集与消费必须分离:`lark-relay-collect` 只管把事件收下来落盘,`lark-relay take`
+在你需要时取走一批。消费侧崩了、AI 跑了半小时、会话关了几小时,采集都不能停 --
 停摆的每一秒都在丢消息。
 
+分离到**可执行文件**这一层,不是两个子命令:采集是常驻服务,服务管理器
+(systemd / launchd)展示的是可执行文件名,与单元名同名才认得出是谁。
+
 | | |
 | --- | --- |
 | 长命的 | AI 会话(人设、上下文连续) |
@@ -36,13 +39,14 @@ Lark 事件是**流式**的 -- 进程不在的时刻,消息**永久丢失**,不
 ## 命令
 
 ```bash
-lark-relay collect            # 底座:全部 profile 各起 consume -> 原子落盘(常驻服务)
+lark-relay-collect            # 底座:全部 profile 各起 consume -> 原子落盘(常驻服务)
+
 lark-relay take …             # 阻塞等一批 -> 输出 -> 退出
 lark-relay status             # 谁在跑 / 各 app 积压 / 各游标位置
 lark-relay guide              # 一页用法
 ```
 
-### collect
+### lark-relay-collect
 
 零参数、零配置。app 列表实时读 `lark-cli profile list`,新增 profile 自动纳入。
 未授权或授权过期的 profile 自动跳过并 warn(永久失败,重试是死循环)。
@@ -50,7 +54,7 @@ lark-relay guide              # 一页用法
 每 app 一个子进程,某个挂了单独重启不影响其他。回收在本进程内每小时自查,
 删超期的整个日期目录 -- 不另起 gc 单元/timer。
 
-### take
+### lark-relay take
 
 只有一种形态:**阻塞等 -> 有一批就输出 -> 退出**。循环交给 harness --
 Claude Code 用 `run_in_background` 起,进程退出会主动通知 AI,这才是事件驱动。

package/bin/lark-relay-collect.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+'use strict'
+
+// lark-relay-collect —— 事件采集底座,常驻服务专用入口。
+//
+// 为什么独立成一个可执行文件、不做 `lark-relay collect` 子命令:
+// 这是个 LaunchDaemon / systemd 单元,服务管理器展示的是 ProgramArguments[0]。
+// 挤在通用 CLI 里时 `launchctl print` 的 program 栏是 `lark-relay`、`ps` 的 COMM
+// 是裸 `node` —— 看不出这是常驻服务。独立后 bin 名与 launchd label
+// (com.adaex.lark-relay-collect)、systemd 单元名三处同名,好搜好认。
+//
+// 采集逻辑全在 lib/collect.js,本文件只做参数解析与进程身份。
+
+require('../lib/utf8').ensureUtf8()
+
+// ps/top 里显示成自己的名字,不再是裸 node(实测 macOS 与 Linux 都生效)。
+// 排障第一步常是 `ps | grep`,进程认不出来会先浪费一轮
+process.title = 'lark-relay-collect'
+
+const { parseArgs, num, list, rejectUnknown } = require('../lib/args')
+const help = require('../lib/help')
+
+const VERSION = require('../package.json').version
+const PROG = 'lark-relay-collect'
+const KEYS = ['exclude', 'retain']
+
+async function main() {
+  const argv = process.argv.slice(2)
+
+  // --version 要有:deploy-launchd.sh 用它打印「全局命令版本」作部署前后对照
+  if (argv[0] === '--version' || argv[0] === '-v' || argv[0] === 'version') {
+    process.stdout.write(`${VERSION}\n`)
+    return 0
+  }
+
+  const a = parseArgs(argv, { flags: ['help'], keys: KEYS })
+  if (a._unknown.length) return rejectUnknown(PROG, argv, a._unknown, KEYS)
+  if (a.help || argv[0] === 'help') {
+    process.stdout.write(`${help.COLLECT_HELP}\n`)
+    return 0
+  }
+
+  const { runCollect } = require('../lib/collect')
+  return await runCollect({
+    exclude: list(a.exclude),
+    retain: num(a.retain, 3),
+  })
+}
+
+main()
+  .then((code) => process.exit(code || 0))
+  .catch((err) => {
+    // 注:runCollect 内部的错误走 lib/log.js 的 logLine(带时间戳,常驻服务要的)。
+    // 这里只兜住它之前/之外的意外,故是裸 stderr
+    if (err && err.userFacing) process.stderr.write(`${err.message}\n`)
+    else process.stderr.write(`${PROG}: ${(err && err.stack) || err}\n`)
+    process.exit(1)
+  })

package/bin/lark-relay.js

@@ -1,88 +1,35 @@
 #!/usr/bin/env node
 'use strict'
 
-// UTF-8 兜底:systemd 默认 C locale。虽然 Node 的字符串处理不像 bash 那样
-// 按字节切片,但子进程(lark-cli / claude)会继承 locale,中文仍会被切坏。
-if (!/utf-?8/i.test(process.env.LC_ALL || process.env.LC_CTYPE || process.env.LANG || '')) {
-  process.env.LANG = 'C.UTF-8'
-  process.env.LC_ALL = 'C.UTF-8'
-}
+require('../lib/utf8').ensureUtf8()
 
-const { parseArgs, num, list, suggest } = require('../lib/args')
+const { parseArgs, num, suggest, rejectUnknown } = require('../lib/args')
 const help = require('../lib/help')
 
 const VERSION = require('../package.json').version
 
-// 各命令的带值参数白名单(布尔开关在 parseArgs 的 flags 里)。
+// 带值参数白名单(布尔开关在 parseArgs 的 flags 里)。
 // 不在白名单的 --xxx 一律硬报错 —— 拼错参数静默吞掉是实测事故:
 // --chat-id 拼错 -> 打印用法退出,看着像「正常退出但没消息」,漏看 bot 第一条 Working
 const TAKE_KEYS = ['app', 'chats', 'name', 'filter', 'debounce', 'max-wait', 'timeout', 'render', 'since']
-const COLLECT_KEYS = ['exclude', 'retain']
-
-// 未知参数 -> stderr 短错误 + 候选提示 + 改写后的命令,exit 2。
-// 不打印完整用法 -- 那看着像 --help 成功,会被当成「正常退出但没消息」
-function rejectUnknown(cmd, argv, unknown, allowed) {
-  const names = [...new Set(unknown)]
-  const shown = names.map((k) => `--${k}`).join(', ')
-  let hint = ''
-  for (const k of names) {
-    const s = suggest(k, allowed)
-    if (s) {
-      hint = `\n你是不是想写 --${s}?`
-      break
-    }
-  }
-  const rewrite = rewriteArgv(argv, names, allowed)
-  const tail = rewrite.length
-    ? `\n你是不是想跑这个?\n  lark-relay ${cmd} ${rewrite.join(' ')}`
-    : ''
-  process.stderr.write(`未知参数:${shown}${hint}${tail}\n跑 \`lark-relay ${cmd}\` 看完整用法\n`)
-  return 2
-}
 
-// 把未知参数替换成候选,拼出可照跑的命令行;无候选的未知参数(连同它的值)丢弃
-function rewriteArgv(argv, unknown, allowed) {
-  const map = new Map()
-  for (const k of unknown) {
-    const s = suggest(k, allowed)
-    if (s && !map.has(k)) map.set(k, s)
-  }
-  if (!map.size) return []
-  const out = []
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i]
-    if (a.startsWith('--') && a !== '--') {
-      const eq = a.indexOf('=')
-      const k = eq !== -1 ? a.slice(2, eq) : a.slice(2)
-      if (map.has(k)) {
-        out.push(eq !== -1 ? `--${map.get(k)}=${a.slice(eq + 1)}` : `--${map.get(k)}`)
-        if (eq === -1) {
-          const next = argv[i + 1]
-          if (next !== undefined && !next.startsWith('--')) {
-            out.push(next)
-            i++
-          }
-        }
-        continue
-      }
-      if (eq === -1) {
-        const next = argv[i + 1]
-        if (next !== undefined && !next.startsWith('--')) i++
-      }
-      continue
-    }
-    out.push(a)
-  }
-  return out
-}
+const COMMANDS = ['take', 'status', 'guide']
+
+// collect 搬家提示。能力是**搬走了不是删了**,所以不能只说「未知命令」
+const MOVED_HINT =
+  `collect 已拆成独立命令 —— 它是常驻服务,不该和在场取用挤在一个入口:\n` +
+  `  lark-relay-collect            # 前台跑(调试)\n` +
+  `  lark-relay-collect --help     # 参数与常驻部署\n` +
+  `同一个包就带,不用另外装。\n`
 
-const USAGE = `lark-relay ${VERSION} —— Lark 事件中继站
+const USAGE = `lark-relay ${VERSION} —— Lark 事件中继站(在场取用)
 
-  lark-relay collect            底座:全部 profile 各起 consume → 原子落盘（常驻服务）
   lark-relay take …             在场取用:阻塞等一批 → 输出 → 退出
   lark-relay status             谁在跑 / 各 app 积压 / 各游标位置
   lark-relay guide              一页用法（装完先读这个）
 
+采集底座是独立命令(常驻服务):lark-relay-collect
+
 第一次用 → lark-relay guide
 各命令详情 → lark-relay <命令> --help`
 
@@ -104,37 +51,34 @@ async function main() {
     case 'guide':
       process.stdout.write(`${help.GUIDE}\n`)
       return 0
-    case 'collect':
-      return await cmdCollect(rest)
     case 'take':
       return await cmdTake(rest)
     case 'status':
       return await cmdStatus(rest)
+    // collect 拆成了独立可执行文件,这里专门拦一下告诉人改敲什么。
+    // 不能落到 default 分支:suggest('collect', ['take','status','guide']) 必然返回
+    // null(编辑距离都 >2、前缀 coll 也不匹配),只会打出干巴巴的「未知命令:collect」--
+    // 那会让人以为采集功能被删了。**能力是搬家,不是消失,提示必须给出新名字**
+    case 'collect':
+      process.stderr.write(MOVED_HINT)
+      return 2
     default: {
-      const s = suggest(cmd, ['collect', 'take', 'status', 'guide'])
+      // 拼错 collect(collectt / colect)同样走搬家提示 —— 意图明显是采集,
+      // 给「未知命令」等于让人以为功能没了。判据:编辑距离 <=2 且不像任何现有命令
+      if (cmd !== 'collect' && suggest(cmd, ['collect']) === 'collect' && !suggest(cmd, COMMANDS)) {
+        process.stderr.write(`未知命令:${cmd}。${MOVED_HINT}`)
+        return 2
+      }
+      const s = suggest(cmd, COMMANDS)
       process.stderr.write(`未知命令:${cmd}${s ? `。你是不是想写 ${s}?` : ''}\n\n${USAGE}\n`)
       return 2
     }
   }
 }
 
-async function cmdCollect(argv) {
-  const a = parseArgs(argv, { flags: ['help'], keys: COLLECT_KEYS })
-  if (a._unknown.length) return rejectUnknown('collect', argv, a._unknown, COLLECT_KEYS)
-  if (a.help) {
-    process.stdout.write(`${help.COLLECT_HELP}\n`)
-    return 0
-  }
-  const { runCollect } = require('../lib/collect')
-  return await runCollect({
-    exclude: list(a.exclude),
-    retain: num(a.retain, 3),
-  })
-}
-
 async function cmdTake(argv) {
   const a = parseArgs(argv, { flags: ['help'], keys: TAKE_KEYS })
-  if (a._unknown.length) return rejectUnknown('take', argv, a._unknown, TAKE_KEYS)
+  if (a._unknown.length) return rejectUnknown('lark-relay take', argv, a._unknown, TAKE_KEYS)
   const larkcli = require('../lib/larkcli')
 
   // 空参数输出完整照做指导,而非报错 -- AI 的真实行为是「先空参数跑一下看看」。
@@ -231,7 +175,7 @@ async function cmdTake(argv) {
 
 async function cmdStatus(argv) {
   const a = parseArgs(argv, { flags: ['json', 'help'], keys: [] })
-  if (a._unknown.length) return rejectUnknown('status', argv, a._unknown, ['json'])
+  if (a._unknown.length) return rejectUnknown('lark-relay status', argv, a._unknown, ['json'])
   if (a.help) {
     process.stdout.write(`${help.STATUS_HELP}\n`)
     return 0

package/lib/args.js

@@ -100,4 +100,64 @@ function suggest(unknown, allowed) {
   return null
 }
 
-module.exports = { parseArgs, num, list, suggest }
+// 未知参数 -> stderr 短错误 + 候选提示 + 改写后的命令,exit 2。
+// 不打印完整用法 -- 那看着像 --help 成功,会被当成「正常退出但没消息」
+//
+// ⚠️ `prog` 必须由调用方传入,不能写死 'lark-relay':两个 bin 共用这段,
+// 而提示里那行「你是不是想跑这个」是要照抄执行的 —— 打出一个不存在的命令
+// (如已拆走的 `lark-relay collect`)会把人引向死路。
+// lark-relay 传 `lark-relay <子命令>`,lark-relay-collect 传自己的名字。
+function rejectUnknown(prog, argv, unknown, allowed, out = process.stderr) {
+  const names = [...new Set(unknown)]
+  const shown = names.map((k) => `--${k}`).join(', ')
+  let hint = ''
+  for (const k of names) {
+    const s = suggest(k, allowed)
+    if (s) {
+      hint = `\n你是不是想写 --${s}?`
+      break
+    }
+  }
+  const rewrite = rewriteArgv(argv, names, allowed)
+  const tail = rewrite.length ? `\n你是不是想跑这个?\n  ${prog} ${rewrite.join(' ')}` : ''
+  out.write(`未知参数:${shown}${hint}${tail}\n跑 \`${prog}\` 看完整用法\n`)
+  return 2
+}
+
+// 把未知参数替换成候选,拼出可照跑的命令行;无候选的未知参数(连同它的值)丢弃
+function rewriteArgv(argv, unknown, allowed) {
+  const map = new Map()
+  for (const k of unknown) {
+    const s = suggest(k, allowed)
+    if (s && !map.has(k)) map.set(k, s)
+  }
+  if (!map.size) return []
+  const out = []
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a.startsWith('--') && a !== '--') {
+      const eq = a.indexOf('=')
+      const k = eq !== -1 ? a.slice(2, eq) : a.slice(2)
+      if (map.has(k)) {
+        out.push(eq !== -1 ? `--${map.get(k)}=${a.slice(eq + 1)}` : `--${map.get(k)}`)
+        if (eq === -1) {
+          const next = argv[i + 1]
+          if (next !== undefined && !next.startsWith('--')) {
+            out.push(next)
+            i++
+          }
+        }
+        continue
+      }
+      if (eq === -1) {
+        const next = argv[i + 1]
+        if (next !== undefined && !next.startsWith('--')) i++
+      }
+      continue
+    }
+    out.push(a)
+  }
+  return out
+}
+
+module.exports = { parseArgs, num, list, suggest, rejectUnknown, rewriteArgv }

package/lib/collect.js

@@ -162,7 +162,7 @@ async function runCollect(opts) {
   }
 
   logLine(
-    `lark-relay collect: ${chosen.length}/${profiles.length} profiles → ${paths.store}\n` +
+    `lark-relay-collect: ${chosen.length}/${profiles.length} profiles → ${paths.store}\n` +
       `  ${chosen.map((p) => p.name).join(' ')}\n` +
       `  event_key=${EVENT_KEY} store 保留 ${opts.retain}天`,
   )

package/lib/help.js

@@ -52,9 +52,12 @@ function takeHelp(apps) {
 
 const COLLECT_HELP = `把全部 lark-cli profile 的事件收下来,原子落盘。零参数、零配置。
 
-  lark-relay collect                    # 前台跑(调试)
+  lark-relay-collect                    # 前台跑(调试)
   常驻:Linux 用 systemd,macOS 用 launchd(单元模板见仓库 systemd//launchd 目录)
 
+独立可执行文件而非 \`lark-relay\` 的子命令 —— 它是常驻服务,服务管理器展示的是
+可执行文件名,与 launchd label(com.adaex.lark-relay-collect)、systemd 单元名同名才认得出。
+
 app 列表实时读 \`lark-cli profile list\`,新增 profile 自动纳入,无需改配置。
 每 app 一个子进程;某个挂了单独重启,不影响其他。
 tokenStatus 为 expired 的 profile 自动跳过并 warn(永久失败,重试是死循环)。
@@ -92,15 +95,17 @@ collect 行不是 running -> 看服务日志(Linux journalctl;
 macOS \`tail -f ~/.lark-relay/logs/collect.err.log\` -- 不进统一日志),
 collect 停摆的每一秒都在丢消息。`
 
-const GUIDE = `lark-relay -- Lark 事件中继站。两个命令:收下来 / 我来取。
+const GUIDE = `lark-relay -- Lark 事件中继站。两件事:收下来 / 我来取。
 
-collect 把事件收下来落盘,take 在你需要时取走一批。两者分离是硬需求:
-消费侧崩了、AI 跑 30 分钟、会话关几小时,采集都不能停 -- 停摆的每一秒都在丢消息。
+\`lark-relay-collect\` 把事件收下来落盘(常驻服务),\`lark-relay take\` 在你需要时取走一批。
+两者分离是硬需求:消费侧崩了、AI 跑 30 分钟、会话关几小时,采集都不能停 --
+停摆的每一秒都在丢消息。所以采集是独立的可执行文件,不是本命令的子命令。
 
-前置:collect 必须在跑
+前置:采集必须在跑
   lark-relay status        # collect 行应为 running
   进程不在的时刻消息永久丢失,不是延迟送达。
-  不在跑 -> 起常驻服务(Linux systemd / macOS launchd,模板见仓库;或 \`lark-relay collect\` 前台调试)
+  不在跑 -> 起常驻服务(Linux systemd / macOS launchd,模板见仓库;
+           或 \`lark-relay-collect\` 前台调试)
 
 take 三步(照做)
   1. 查群 ID   lark-cli --profile <app> im +chat-search --as user --query "<群名>"

package/lib/utf8.js

@@ -0,0 +1,15 @@
+'use strict'
+
+// UTF-8 兜底:systemd / launchd 环境都无 LANG -> C locale。虽然 Node 的字符串处理
+// 不像 bash 那样按字节切片,但子进程(lark-cli)会继承 locale,中文仍会被切坏。
+//
+// 两个 bin(lark-relay / lark-relay-collect)都要,故抽成模块 —— 复制两份会漂移。
+// 必须在任何 spawn 之前执行,所以两个入口都在最顶上 require 它。
+function ensureUtf8(env = process.env) {
+  if (!/utf-?8/i.test(env.LC_ALL || env.LC_CTYPE || env.LANG || '')) {
+    env.LANG = 'C.UTF-8'
+    env.LC_ALL = 'C.UTF-8'
+  }
+}
+
+module.exports = { ensureUtf8 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lark-relay",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "Lark event relay: collect events to disk, take a batch when you need it.",
   "keywords": [
     "lark",
@@ -17,7 +17,8 @@
     "node": ">=18"
   },
   "bin": {
-    "lark-relay": "bin/lark-relay.js"
+    "lark-relay": "bin/lark-relay.js",
+    "lark-relay-collect": "bin/lark-relay-collect.js"
   },
   "files": [
     "bin",