lark-relay 0.4.8 → 0.4.10

package/README.md

@@ -25,16 +25,13 @@ Lark 事件是**流式**的 -- 进程不在的时刻,消息**永久丢失**,不
 停摆的每一秒都在丢消息。
 
 分离到**可执行文件**这一层,不是两个子命令:采集是常驻服务,服务管理器
-(systemd / launchd)展示的是可执行文件名,与单元名同名才认得出是谁。
+(launchd)展示的是可执行文件名,与 label 同名才认得出是谁。
 
-| | |
-| --- | --- |
-| 长命的 | AI 会话(人设、上下文连续) |
-| 短命的 | 消息(来一批处理一批) |
-| 谁在等谁 | AI 等消息 |
-| 控制权 | AI 手里(自己决定何时再取) |
-| 谁能干 | 任何 agent(Claude Code / Codex / 手敲) |
-| 配置 | 纯参数,无文件 |
+`take` 的形态:
+
+- **长命的是 AI 会话**(人设、上下文连续),**短命的是消息**(来一批处理一批)
+- **AI 等消息**,不是消息推给 AI —— 控制权在 AI 手里,自己决定何时再取
+- 任何 agent 都能干(Claude Code / Codex / 手敲),纯参数、无配置文件
 
 ## 命令
 
@@ -83,6 +80,12 @@ lark-relay take --app <app> --chats oc_xxx --render text
 多消费者**共享 store、各持游标**,不做「处理完即删」-- 谁都不能替别人删。
 盯同一 app 请用不同 `--name` 隔离游标。
 
+**游标要自己收尾**:它是「关了会话、过阵子接着盯」的续接凭据,所以引擎**不会**
+自动清理不活跃的游标 -- 自动清掉就等于下次重挂要么全量重放、要么跳过停机期的消息。
+代价是不再用的游标会一直留在 `status` 里显示「落后 N 条」,而 store 只保留几天,
+那个 N 会随过期删除而变小(**看着像追上了,其实是消息没了**)。
+一次性监听、验完的排查、不再值守的任务,收尾时 `rm -rf ~/.lark-relay/cursors/<name>`。
+
 ## 设计取舍
 
 - **原子落盘**:collect 读 stdout NDJSON 后自己 `写 .tmp -> rename`(同目录原子)。

package/bin/lark-relay-collect.js

@@ -4,10 +4,10 @@
 // lark-relay-collect —— 事件采集底座,常驻服务专用入口。
 //
 // 为什么独立成一个可执行文件、不做 `lark-relay collect` 子命令:
-// 这是个 LaunchDaemon / systemd 单元,服务管理器展示的是 ProgramArguments[0]。
+// 这是个 LaunchDaemon,服务管理器展示的是 ProgramArguments[0]。
 // 挤在通用 CLI 里时 `launchctl print` 的 program 栏是 `lark-relay`、`ps` 的 COMM
 // 是裸 `node` —— 看不出这是常驻服务。独立后 bin 名与 launchd label
-// (com.adaex.lark-relay-collect)、systemd 单元名三处同名,好搜好认。
+// (com.adaex.lark-relay-collect)同名,好搜好认。
 //
 // 采集逻辑全在 lib/collect.js,本文件只做参数解析与进程身份。
 
@@ -17,8 +17,9 @@ require('../lib/utf8').ensureUtf8()
 // 排障第一步常是 `ps | grep`,进程认不出来会先浪费一轮
 process.title = 'lark-relay-collect'
 
-const { parseArgs, num, list, rejectUnknown } = require('../lib/args')
+const { parseArgs, numStrict, list, rejectUnknown } = require('../lib/args')
 const help = require('../lib/help')
+const store = require('../lib/store')
 
 const VERSION = require('../package.json').version
 const PROG = 'lark-relay-collect'
@@ -63,19 +64,33 @@ async function main() {
     return 2
   }
 
+  // retain 必须落在消费侧的扫描窗口内,否则事件留在盘上却永远扫不到 =
+  // 静默丢消息(正是 store.js 那条注释警告的)。两个值在两个进程里,
+  // 只能在这里把不变量钉死:装完新版直接起不来,好过悄悄丢
+  const retain = numStrict(a.retain, 3)
+  if (retain === null || !(retain >= 1) || retain > store.SCAN_DAYS) {
+    process.stderr.write(
+      `--retain 需要 1~${store.SCAN_DAYS} 之间(消费侧扫描窗口 ${store.SCAN_DAYS} 天),当前:${a.retain}\n` +
+        `要保留更久得同时调大 LARK_RELAY_SCAN_DAYS,否则超窗口的事件留着也扫不到\n`,
+    )
+    return 2
+  }
+
   const { runCollect } = require('../lib/collect')
   return await runCollect({
     exclude: list(a.exclude),
-    retain: num(a.retain, 3),
+    retain,
   })
 }
 
 main()
-  .then((code) => process.exit(code || 0))
+  .then((code) => {
+    process.exitCode = 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)
+    process.exitCode = 1
   })

package/bin/lark-relay.js

@@ -3,7 +3,7 @@
 
 require('../lib/utf8').ensureUtf8()
 
-const { parseArgs, num, suggest, rejectUnknown } = require('../lib/args')
+const { parseArgs, numStrict, suggest, rejectUnknown } = require('../lib/args')
 const help = require('../lib/help')
 
 const VERSION = require('../package.json').version
@@ -129,14 +129,33 @@ async function cmdTake(argv) {
     return 3
   }
 
+  // --since 只有 now|all 两个取值。必须白名单校验:曾经是「跟 'now' 比一次,
+  // 其余全当 all」,于是 `--since Now`(大写)、`--since 乱码` 都静默变成全量重放。
+  // 与本仓「拼错参数当场硬失败」的铁律一致(args.js 开头那条)
   const since = a.since === true ? 'now' : a.since || 'now'
+  if (since !== 'now' && since !== 'all') {
+    process.stderr.write(`--since 只能是 now 或 all,当前:${since}\n`)
+    return 2
+  }
   if (since === 'now' && store.readCursor(name, a.app) === null) {
     store.seedCursorNow(name, a.app) // 默认不重放历史,消灭「预热游标」这一步
   }
 
-  const debounceMs = num(a.debounce, 5) * 1000
-  const maxWaitMs = num(a['max-wait'], 25) * 1000
-  const timeoutMs = num(a.timeout, 12 * 3600) * 1000
+  // 时长参数校验:负数/非数字过去会静默退回默认值或原样生效
+  // (实测 --debounce -5 被接受并打印「防抖=-5s」,--timeout abc 悄悄变成 12 小时)
+  const dur = (val, def, label) => {
+    const n = numStrict(val, def)
+    if (n === null || !(n >= 0)) {
+      const e = new Error(`--${label} 需要 >= 0 的秒数,当前:${val === true ? '(没给值)' : val}`)
+      e.userFacing = true
+      e.exitCode = 2
+      throw e
+    }
+    return n * 1000
+  }
+  const debounceMs = dur(a.debounce, 5, 'debounce')
+  const maxWaitMs = dur(a['max-wait'], 25, 'max-wait')
+  const timeoutMs = dur(a.timeout, 12 * 3600, 'timeout')
 
   // 起来先打一行「监听中」-- 没这行就是没起来。
   // 反馈实测:进程静默退出(参数错)被当成「在监听」,漏看 bot 第一条 Working
@@ -188,9 +207,15 @@ async function cmdStatus(argv) {
 }
 
 main()
-  .then((code) => process.exit(code || 0))
+  .then((code) => {
+    // ⚠️ 不能用 process.exit() —— stdout 是管道时它会丢掉未 flush 的缓冲。
+    // 实测:400 条 NDJSON 重定向到文件得 676070 字节,同样数据接管道只收到
+    // 65536(管道缓冲上限)且切在 JSON 中途,而 stderr 照报「400 条」。
+    // 设 exitCode 让事件循环自然排空,退出码语义不变
+    process.exitCode = code || 0
+  })
   .catch((err) => {
     if (err && err.userFacing) process.stderr.write(`${err.message}\n`)
     else process.stderr.write(`lark-relay: ${(err && err.stack) || err}\n`)
-    process.exit(1)
+    process.exitCode = (err && err.exitCode) || 1
   })

package/lib/args.js

@@ -49,10 +49,14 @@ function parseArgs(argv, spec = {}) {
   return out
 }
 
-function num(v, dflt) {
-  if (v === undefined || v === true) return dflt
+// 数值参数:省略 -> 默认值;给了但不是有效数字 -> null,由调用方硬失败。
+// ⚠️ 不要退化成「非法值悄悄用默认值」—— 那样 `--timeout abc` 就成了
+// 「跑起来但行为不对」,与本仓「拼错当场失败」的铁律相悖(实测它会静默变成 12 小时)
+function numStrict(v, dflt) {
+  if (v === undefined) return dflt
+  if (v === true) return null // `--timeout` 后面没跟值
   const n = Number(v)
-  return Number.isFinite(n) ? n : dflt
+  return Number.isFinite(n) ? n : null
 }
 
 function list(v) {
@@ -160,4 +164,4 @@ function rewriteArgv(argv, unknown, allowed) {
   return out
 }
 
-module.exports = { parseArgs, num, list, suggest, rejectUnknown, rewriteArgv }
+module.exports = { parseArgs, numStrict, list, suggest, rejectUnknown, rewriteArgv }

package/lib/collect.js

@@ -117,7 +117,7 @@ async function runCollect(opts) {
   ensureDir(paths.store)
   ensureDir(paths.cursors)
   // 日志接管要最早做 —— 下面的启动横幅、profile 报错都该带上时间戳。
-  // 非 launchd 场景(journald / 前台)是 no-op,logLine 退化成裸 stderr 直写
+  // 非 launchd 场景(前台调试)是 no-op,logLine 退化成裸 stderr 直写
   logInit()
 
   const exclude = new Set(opts.exclude || [])
@@ -132,7 +132,7 @@ async function runCollect(opts) {
         `collect 依赖 lark-cli 提供认证与事件总线。检查:\n` +
         `  which ${larkcli.CLI}          # 装了吗、在 PATH 里吗\n` +
         `  ${larkcli.CLI} profile list   # 能跑吗\n` +
-        `常驻服务(systemd 单元/launchd plist)的 PATH 要用 fnm default alias 的稳定路径,不能用会话级的 multishell 路径`,
+        `常驻服务(launchd plist)的 PATH 要用 fnm default alias 的稳定路径,不能用会话级的 multishell 路径`,
     )
     return 1
   }

package/lib/filter.js

@@ -39,7 +39,7 @@ function applyFilter(events, expr) {
   } catch (err) {
     // 保守放行 + warn,不抛 —— 抛出去会让常驻消费者崩溃循环:
     // 表达式对某类事件报错(如 `.mentions[].id` 遇到没有 mentions 的消息)时,
-    // 那条消息永远卡在队首,游标推不动,systemd 每 5s 重启一次,该任务彻底停摆。
+    // 那条消息永远卡在队首,游标推不动,服务每 5s 重启一次,该任务彻底停摆。
     // 放行的代价是模型多看几条本该滤掉的消息,远小于停摆
     process.stderr.write(
       `warn: --filter 求值失败,本批不过滤(${events.length} 条放行)。表达式:${expr}\n` +

package/lib/help.js

@@ -47,16 +47,22 @@ function takeHelp(apps) {
   · 用 run_in_background 起,不要前台跑 -- 会阻塞会话最长 12h
   · 一批处理完再起下一个;不需要自己写 while 循环
   · 拿不到消息先查第二步:bot 不在群是最常见原因
-  · 多个消费者盯同一 app 用不同 --name,游标互不干扰`
+  · 多个消费者盯同一 app 用不同 --name,游标互不干扰
+  · 不盯了就删游标:rm -rf ~/.lark-relay/cursors/<name>
+    游标是给「关了会话、过阵子接着盯」用的续接凭据,不是运行态缓存,
+    引擎不会自动清 -- 一次性的临时监听、验证完的排查、不再值守的任务,
+    收尾时自己删掉。留着只会在 status 里挂一行越积越多的「落后 N 条」,
+    而 store 只保留几天,那个 N 迟早会因为过期删除而变小 --
+    看着像追上了,其实是消息没了`
 }
 
 const COLLECT_HELP = `把全部 lark-cli profile 的事件收下来,原子落盘。零参数、零配置。
 
   lark-relay-collect                    # 前台跑(调试)
-  常驻:Linux 用 systemd,macOS 用 launchd(单元模板见仓库 systemd//launchd 目录)
+  常驻:macOS 用 launchd(plist 模板见仓库 launchd/ 目录)
 
 独立可执行文件而非 \`lark-relay\` 的子命令 —— 它是常驻服务,服务管理器展示的是
-可执行文件名,与 launchd label(com.adaex.lark-relay-collect)、systemd 单元名同名才认得出。
+可执行文件名,与 launchd label(com.adaex.lark-relay-collect)同名才认得出。
 
 app 列表实时读 \`lark-cli profile list\`,新增 profile 自动纳入,无需改配置。
 每 app 一个子进程;某个挂了单独重启,不影响其他。
@@ -91,9 +97,11 @@ const STATUS_HELP = `一眼看清全局:谁在跑、积压多少、游标在哪
 
 排障入口:某消费者「落后」很多 -> 它的 take 没在跑或卡住;
 「无消费者」= 白采,可考虑 --exclude。
-collect 行不是 running -> 看服务日志(Linux journalctl;
-macOS \`tail -f ~/.lark-relay/logs/collect.err.log\` -- 不进统一日志),
-collect 停摆的每一秒都在丢消息。`
+⚠️ 「落后」的那个消费者如果已经不打算再盯了,删掉它的游标:
+\`rm -rf ~/.lark-relay/cursors/<name>\` -- 引擎不会自动清,
+留着只会让这张表越来越长,且积压数会随 store 过期删除而虚假变小。
+collect 行不是 running -> \`tail -f ~/.lark-relay/logs/collect.err.log\`
+(launchd 不进统一日志),collect 停摆的每一秒都在丢消息。`
 
 const GUIDE = `lark-relay -- Lark 事件中继站。两件事:收下来 / 我来取。
 
@@ -104,7 +112,7 @@ const GUIDE = `lark-relay -- Lark 事件中继站。两件事:收下来 / 我来
 前置:采集必须在跑
   lark-relay status        # collect 行应为 running
   进程不在的时刻消息永久丢失,不是延迟送达。
-  不在跑 -> 起常驻服务(Linux systemd / macOS launchd,模板见仓库;
+  不在跑 -> 起常驻服务(macOS launchd,plist 模板见仓库;
            或 \`lark-relay-collect\` 前台调试)
 
 take 三步(照做)
@@ -116,6 +124,9 @@ take 三步(照做)
   起来后 stderr 有一行「监听中」-- 没有就是没起来,看 stderr。
   一批处理完再起一个。不要自己写 while 循环 -- 进程退出会通知你。
   退出码:0=有一批,4=超时没消息(正常,再起一个),2=参数错,3=游标被占用。
+  4. 不盯了收尾  rm -rf ~/.lark-relay/cursors/<name>
+     游标只为「关了会话、过阵子接着盯」而存在,引擎不会自动清。
+     临时监听、验完的排查、不再值守的任务,收尾时自己删掉
 
 常见错误
   · 拿不到消息 -> 九成是 bot 不在群。验 bot 必须 --as user,

package/lib/log.js

@@ -4,8 +4,8 @@
 // CLI 的用户可见输出(take 的 NDJSON 载荷、status --json)绝不能过这里 --
 // 加前缀会破坏下游解析契约。
 //
-// 为什么需要:Linux 有 journald 免费给时间戳和轮转,macOS 的 launchd 只有
-// StandardErrorPath 直写文件 -- 无时间戳、无轮转、无分级。而本项目的核心排查
+// 为什么需要:launchd 只有 StandardErrorPath 直写文件 -- 无时间戳、无轮转、
+// 无分级(journald 那种免费给时间戳和轮转的东西这边没有)。而本项目的核心排查
 // 问题恰是「**什么时候**断线、断了多久、那个窗口丢了几条」,时间戳是唯一依据。
 const fs = require('fs')
 const path = require('path')
@@ -13,11 +13,10 @@ const { paths } = require('./paths')
 
 // 激活判据:stderr 是普通文件 = launchd 直写场景。
 // 实测 fs.fstatSync(2):pipe -> isFile=false/isFIFO=true;重定向到文件 -> isFile=true。
-// 这一个判据同时分开了三种场景:
+// 这一个判据同时分开了两种场景:
 //   launchd 直写文件  -> 要时间戳、要轮转(本模块接管)
-//   systemd journald  -> 不要(journald 自带时间戳,加了会重复;socket 不是 file)
 //   前台调试 tty/pipe -> 不要(人眼看,时间戳是噪音)
-// 所以不需要按平台分支,也不需要环境变量开关 -- 判据天然对齐。
+// 所以不需要环境变量开关 -- 判据天然对齐。
 function stderrIsFile() {
   try {
     return fs.fstatSync(2).isFile()

package/lib/status.js

@@ -17,29 +17,7 @@ function ago(ms) {
   return `${Math.round(s / 86400)}d ago`
 }
 
-function unitState(unit) {
-  try {
-    const out = execFileSync('systemctl', ['is-active', unit], { encoding: 'utf8' }).trim()
-    return out
-  } catch (err) {
-    return (err.stdout || '').trim() || 'inactive'
-  }
-}
-
-function unitMainPid(unit) {
-  try {
-    const out = execFileSync('systemctl', ['show', unit, '-p', 'MainPID', '--value'], {
-      encoding: 'utf8',
-    }).trim()
-    const n = Number(out)
-    return n > 0 ? n : null
-  } catch {
-    return null
-  }
-}
-
-// 服务管理器按平台分治:Linux systemd / macOS launchd。
-// 单元名/label 是部署约定,与 systemd 单元、launchd plist 同源;
+// 服务管理器:launchd。label 是部署约定,与 launchd plist 同源;
 // LR_COLLECT_LABEL 是改名部署的逃生舱。
 const COLLECT_LABEL = process.env.LR_COLLECT_LABEL || 'com.adaex.lark-relay-collect'
 
@@ -55,9 +33,8 @@ function launchctlState(label) {
     // 输出 `state = not running`,(\S+) 只吃到 "not",status 会显示成
     // 「collect ○ not」。而「collect 没在跑」正是最要命的状态,偏偏这时不可读
     //
-    // 只把 running 归一成 active(供上层判活),其余保留 launchd 原话不映射成
-    // systemd 的 inactive —— 用户接着要跑 `launchctl print`,看到的就是
-    // `not running`,术语一致比跨平台统一更有用
+    // 只把 running 归一成 active(供上层判活),其余保留 launchd 原话 ——
+    // 用户接着要跑 `launchctl print`,看到的就是 `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()
@@ -68,15 +45,11 @@ function launchctlState(label) {
 }
 
 function serviceState() {
-  if (process.platform === 'darwin') return launchctlState(COLLECT_LABEL)
-  const unit = 'lark-relay-collect.service'
-  return { state: unitState(unit), pid: unitMainPid(unit) }
+  return launchctlState(COLLECT_LABEL)
 }
 
 function collectHint() {
-  return process.platform === 'darwin'
-    ? `sudo launchctl bootstrap system /Library/LaunchDaemons/${COLLECT_LABEL}.plist`
-    : 'systemctl enable --now lark-relay-collect'
+  return `sudo launchctl bootstrap system /Library/LaunchDaemons/${COLLECT_LABEL}.plist`
 }
 
 // 消费者 = cursors/ 下的目录。每个记录它在各 app 上的游标位置。

package/lib/store.js

@@ -8,7 +8,9 @@ const path = require('path')
 const { paths, ensureDir, eventFilename, dayKey, dayKeyOffset } = require('./paths')
 
 // scan 窗口天数。必须 >= store 保留天数,否则「保留着却扫不到」= 静默丢消息。
-// 只扫窗口内是为了避免全目录排序(旧架构每轮全扫 4467 个文件)
+// 只扫窗口内是为了避免全目录排序(旧架构每轮全扫 4467 个文件)。
+// ⚠️ 与 collect 的 --retain 是两个进程里的两个值,没法在运行时互相读取,
+// 故由 collect 启动时校验(见 bin/lark-relay-collect.js),这里导出给它用
 const SCAN_DAYS = Number(process.env.LARK_RELAY_SCAN_DAYS || 4)
 
 // 原子落盘:同目录 写 .tmp → rename。
@@ -68,7 +70,7 @@ function afterCursor(entry, cursor) {
   return cmpName(entry.name, cName) > 0
 }
 
-// 只扫今天 + 昨天…… 的窗口跟随 retain,避免「保留 3 天却只扫 2 天」:
+// 只扫今天 + 昨天…… 的窗口必须覆盖 store 保留天数,避免「保留 3 天却只扫 2 天」:
 // 消费者停机超过 1 天后,盘上还在的事件会永久扫不到(游标停在更早的日期,
 // 而窗口已经不覆盖它 → 静默丢失)。实测:游标停在 D-2、第三天启动即复现
 function scanWindow(app, days = SCAN_DAYS) {
@@ -176,6 +178,7 @@ function gcStore(retainDays) {
 }
 
 module.exports = {
+  SCAN_DAYS,
   writeEvent,
   scanWindow,
   readEvent,

package/lib/utf8.js

@@ -1,6 +1,6 @@
 'use strict'
 
-// UTF-8 兜底:systemd / launchd 环境都无 LANG -> C locale。虽然 Node 的字符串处理
+// UTF-8 兜底:launchd 环境无 LANG -> C locale。虽然 Node 的字符串处理
 // 不像 bash 那样按字节切片,但子进程(lark-cli)会继承 locale,中文仍会被切坏。
 //
 // 两个 bin(lark-relay / lark-relay-collect)都要,故抽成模块 —— 复制两份会漂移。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lark-relay",
-  "version": "0.4.8",
+  "version": "0.4.10",
   "description": "Lark event relay: collect events to disk, take a batch when you need it.",
   "keywords": [
     "lark",
@@ -26,10 +26,8 @@
     "README.md"
   ],
   "scripts": {
-    "test": "node --test test/*.test.js"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/adaex/lark-relay.git"
+    "test": "node --test test/*.test.js",
+    "prepublishOnly": "node --test test/*.test.js && npm run check-pack",
+    "check-pack": "node scripts/check-pack.js"
   }
 }