lark-relay 0.6.0 → 0.6.2

package/README.md

@@ -1,130 +1,84 @@
 # lark-relay
 
-Lark(飞书)事件中继站。两件事:**收下来** / **我来取**。
+Lark(飞书)消息中继:常驻采集落盘,按需取出一批
 
-依赖 [`lark-cli`](https://www.npmjs.com/package/@lark-base-open/lark-cli) 提供认证与
-事件总线;本包只负责缓冲与批次,零 npm 依赖。
+依赖 Node.js >=22 和 [lark-cli](https://www.npmjs.com/package/@lark-base-open/lark-cli)
+使用 `--filter` 时还需要 jq,无 npm 运行依赖
 
 ```bash
-npm i -g lark-relay      # 装出两个命令:lark-relay-collect(常驻)/ lark-relay(在场)
-lark-relay take          # 空参输出完整的照做指导
+npm i -g lark-relay
+lark-relay take --help
+lark-relay-collect --help
 ```
 
-## 为什么需要它
+## 采集与消费
 
-Lark 事件是**流式**的 -- 进程不在的时刻,消息**永久丢失**,不是延迟送达
-(实测:消息发出 8 秒后才起 consumer,收到 0 条)。
-
-所以要有一个常驻进程只管把事件收下来落盘,消费侧崩了、AI 跑了半小时、
-会话关了几小时,都不丢消息。这就是 `lark-relay-collect`。
-
-## 两段分离
-
-采集与消费必须分离:`lark-relay-collect` 只管把事件收下来落盘,`lark-relay take`
-在你需要时取走一批。消费侧崩了、AI 跑了半小时、会话关了几小时,采集都不能停 --
-停摆的每一秒都在丢消息。
-
-分离到**可执行文件**这一层,不是两个子命令:采集是常驻服务,服务管理器
-(launchd)展示的是可执行文件名,与 label 同名才认得出是谁。
-
-`take` 的形态:
-
-- **长命的是 AI 会话**(人设、上下文连续),**短命的是消息**(来一批处理一批)
-- **AI 等消息**,不是消息推给 AI —— 控制权在 AI 手里,自己决定何时再取
-- 任何 agent 都能干(Claude Code / Codex / 手敲),纯参数、无配置文件
-
-## 命令
+Lark 事件流不回放离线期间的消息,采集必须独立于消费会话持续运行
+`lark-relay-collect` 通过 lark-cli 订阅 `im.message.receive_v1`,将消息原子写入磁盘
+`lark-relay take` 从磁盘读取,攒出一批后输出并退出,调用方处理后再次取用
 
 ```bash
-lark-relay-collect            # 底座:全部 profile 各起 consume -> 原子落盘(常驻服务)
-
-lark-relay take …             # 阻塞等一批 -> 输出 -> 退出
-lark-relay status             # 谁在跑 / 各 app 收了多少 / 游标在哪
+lark-relay-collect
+lark-relay take --app <app> --chats oc_xxx --render text
+lark-relay status
 ```
 
-就这两件事。踩坑史见 `docs/lessons.md`,代码里只留指针。
-
-### lark-relay-collect
-
-零参数、零配置。app 列表实时读 `lark-cli profile list`,新增 profile 自动纳入。
-未授权或授权过期的 profile 自动跳过并 warn(永久失败,重试是死循环)。
+采集在启动时读取 `lark-cli profile list`,跳过排除项以及未授权/授权过期的 profile
+新增 profile 或重新授权后需重启采集,每个 app 的 consumer 独立退避重连
+同一 app 的事件总线只允许一个实例,本地互斥锁按 `LARK_RELAY_HOME` 隔离
 
-每 app 一个子进程,某个挂了单独重启不影响其他。同一 message_id 只落一次。
-回收在本进程内每小时自查(store 删超期日期目录、游标删空闲超期的)-- 不另起 gc 单元/timer。
+## 取批规则
 
-日志直写 stderr,每行带 ISO 时间戳(launchd 场景重定向到
-`~/.lark-relay/logs/collect.err.log`)。不做轮转 —— 实测约 10MB/年,
-嫌大就 `> ~/.lark-relay/logs/collect.err.log` 截断(launchd 持有 fd,别 rm)。
+- `--app` 是 lark-cli profile 名,`--chats` 是逗号分隔的 chat_id 或 `@文件`(首列)
+- 监听要求 bot 已在群内,查群与验成员的完整命令见 `take --help`
+- `--name` 标识消费断点,默认按 app+chats 派生,并行消费使用不同名字
+- `--filter` 是唯一业务过滤入口,使用 jq 表达式;语法错误在启动前拒绝
+- 消息数据导致 jq 求值失败时,该次扫描到的消息告警并放行,避免阻塞断点
+- 默认防抖 5 秒,从第一条消息起最多攒 25 秒,本次取用总超时 12 小时
+- `--render` 支持 `ndjson`(默认)和按群/话题分组的 `text`
+- 参数校验完成后 stderr 输出「监听中」;未知参数、位置参数、缺值和空值均报错
 
-### 常驻部署(macOS / launchd)
+退出码:0=有一批/帮助/信号退出,2=参数错,3=消费身份被占用,4=超时无消息
+`--timeout 0` 立即扫描一次并返回,有消息仍会输出
 
-要点三条,plist 自己写十来行就够:
+## 断点与保留期
 
-- 用 **LaunchDaemon**(装 `/Library/LaunchDaemons/`)+ `UserName` 降权到你自己。
-  不用 LaunchAgent —— 它要 GUI 登录才加载、登出即停,而事件零回放,停摆=丢消息
-- `ProgramArguments` 写绝对路径(`which lark-relay-collect`),并显式设
-  `EnvironmentVariables` 里的 `HOME` 与 `PATH` —— launchd 不展开 `~`/`$VAR`,
-  也不继承 shell 环境
-- `KeepAlive` 用 `SuccessfulExit=false`;`StandardErrorPath` 指到一个**父目录已存在**
-  的路径,launchd 不建目录
-
-装:`sudo launchctl bootstrap system /Library/LaunchDaemons/<label>.plist`。
-改了 plist 必须 bootout + bootstrap —— `kickstart -k` 只重启进程、不重读 plist。
+```
+~/.lark-relay/
+  store/<app>/<YYYY-MM-DD>/<stamp>_<pid>_<seq>.json
+  cursors/<name>/<app>
+  run/<key>.lock/
+```
 
-### lark-relay take
+多消费者共享事件存储,各持独立断点
+已有断点始终续接,不按空闲时长过期;首次取用由 `--since now|all` 决定起点,默认 `now`
+需要从新的起点消费时使用新的 `--name`
 
-只有一种形态:**阻塞等 -> 有一批就输出 -> 退出**。循环交给 harness --
-Claude Code 用 `run_in_background` 起,进程退出会主动通知 AI,这才是事件驱动。
+采集端 `--retain` 指定事件保留天数(默认 3 个自然日,含今天),启动时及每小时回收超期目录
+断点只定位仍在盘上的消息,无法恢复已被回收的事件
 
-```bash
-lark-relay take --app <app> --chats oc_xxx --render text
-```
+取批使用 at-most-once 交付:攒批期间只推进内存游标,交付前才提交磁盘断点
+被过滤掉的消息在没有待交付批次时直接推进断点
+消费者崩溃发生在提交之后时,业务可能漏处理;不提供处理确认或重试队列
 
-空参数跑一下会输出完整的照做指导(查群 ID -> 验 bot 在群 -> 监听三步),exit 0。
-起来后 stderr 先打一行「监听中」-- 没这行就是没起来,看 stderr 报错。
-退出码:0=有一批,4=超时没消息(正常,再起一个),2=参数错,3=游标被占用。
-参数拼错(如 `--chat-id`)会硬失败并给出正确写法,不静默吞掉。
+## 存储取舍
 
-业务过滤只有 `--filter`(jq 表达式)一个口子,不为每个业务加参数。
+- 一事件一文件,同目录写临时文件后 rename,消费者只扫描完整事件文件
+- 按日期及数值文件名排序;stamp 在采集进程内严格递增
+- 按 message_id 去重,启动时从当天文件恢复集合,跨天重置
+- 每 500ms 扫描保留的全部日期,不引入额外扫描窗口
+- 参数由 Node 内置解析器处理,不兼容已移除的命令或参数
 
-## 存储布局
+## macOS 常驻部署
 
-```
-~/.lark-relay/
-  store/<app>/<YYYY-MM-DD>/<纳秒>_<pid>_<seq>.json   原始事件(可随时删,丢了自愈)
-  cursors/<name>/<app>                               各消费者游标
-```
+- 使用 LaunchDaemon + UserName,开机即起,不依赖 GUI 登录
+- ProgramArguments 写可执行文件的绝对路径,显式设置 HOME/PATH/UTF-8 locale
+- KeepAlive 使用 SuccessfulExit=false;日志路径父目录须预先创建
+- 代码升级后用 `kickstart -k`,修改 plist 后用 `bootout`、等 label 释放、再 `bootstrap`
 
-判据:能随时删掉重建的才放这里 -- 上面两样都能。
-
-多消费者**共享 store、各持游标**,不做「处理完即删」-- 谁都不能替别人删。
-盯同一 app 请用不同 `--name` 隔离游标。
-
-**游标会自动回收**:空闲超过 2 天的由 collect 删掉(每小时自查,与 store 同一个 gc)。
-判据是「多久没人用过它」(mtime)—— 不需要你记得收尾,也不需要判断该不该删。
-看状态 `lark-relay status`;等不及就 `rm -rf ~/.lark-relay/cursors`。
-改期限:`LARK_RELAY_CURSOR_TTL_DAYS=<天>`。
-
-为什么不是「落后多少条」:那个方向是反的,这条判据错过两次 --
-见 `docs/lessons.md#游标判据`。
-
-## 设计取舍
-
-- **原子落盘**:collect 读 stdout NDJSON 后自己 `写 .tmp -> rename`(同目录原子)。
-  不用 `--output-dir` -- 它先建 0 字节再填充,消费侧游标可能跨过半成品导致事件永久丢失
-- **一事件一文件 + 按天分目录**:不用追加式 NDJSON。因为多消费者共享 store 时
-  两种方案都不能「处理完即删」,NDJSON 最大的优势(删除简单)失效,而它的 gc
-  要按大小滚动 + 保留 N 个文件,反而比整目录删复杂
-- **去重做在落盘侧**:collect 持 `Set<message_id>`,同一条消息在盘上只出现一次。
-  collect 重启或 bus 重投时它是**新文件**,游标拦不住 —— 所以不能只靠游标。
-  做在落盘侧而非每个消费者各存一份,游标目录才能只放游标
-- **`--chats` 只接 `oc_` 开头的 chat_id,不接群名**:群名可能匹配多个或匹配错群,
-  而监听错群是**静默失败**(一直等一个永不来的消息)
-- **`--since` 默认 `now`**:不重放历史,消灭「预热游标」这一步
-- **不设扫描窗口**:消费侧扫盘上还在的全部日期。曾有个 3 天窗口,省 4ms,
-  换来「窗口必须正好等于 retain」的跨进程不变量
-- **体积预算**:`lib`+`bin` 超 1900 行 `npm test` 就红(`test/budget.test.js`)。
-  这个包只做两件事,防的是治理层长回来
+日志直写 stderr,每行带 ISO 时间戳,不做轮转
+需要缩减日志时截断文件,不要删除或替换 launchd 持有的文件
+`status` 中 collect running 只说明主进程在跑,各 app 是否连接成功需查看采集日志
 
 ## 许可
 

package/bin/lark-relay-collect.js

@@ -1,81 +1,34 @@
 #!/usr/bin/env node
 'use strict'
 
-// lark-relay-collect —— 事件采集底座,常驻服务专用入口。
-// 独立成可执行文件而非子命令:launchd 展示的是 ProgramArguments[0],
-// 与 label(com.adaex.lark-relay-collect)同名才认得出。
-// 采集逻辑全在 lib/collect.js,本文件只做参数解析与进程身份。
-
 require('../lib/utf8').ensureUtf8()
-
-// ps/top 里显示成自己的名字,不再是裸 node -- 排障第一步常是 `ps | grep`
 process.title = 'lark-relay-collect'
 
-const { parseArgs, numStrict, list, rejectUnknown } = require('../lib/args')
-const help = require('../lib/help')
-
+const { parseArgs, numberArg } = require('../lib/args')
+const { COLLECT_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
-  }
-
-  // ⚠️ 短横线别名与 help 必须在 parseArgs **之前**拦:parseArgs 只认 `--xxx`,
-  // `-h` 会一路穿到 runCollect() 起一个 daemon 去抢线上的 bus。
-  // **帮助命令导致丢消息** -- 见 docs/lessons.md#静默失败
-  if (argv[0] === '--help' || argv[0] === '-h' || argv[0] === 'help') {
-    process.stdout.write(`${help.COLLECT_HELP}\n`)
-    return 0
-  }
-
-  const a = parseArgs(argv, { flags: ['help'], keys: KEYS })
-  if (a._unknown.length) return rejectUnknown(PROG, a._unknown, KEYS)
-  if (a.help) {
-    process.stdout.write(`${help.COLLECT_HELP}\n`)
+  const a = parseArgs(process.argv.slice(2), { keys: ['exclude', 'retain'], flags: ['version'] })
+  if (a.help || a.version) {
+    process.stdout.write(`${a.version ? VERSION : COLLECT_HELP}\n`)
     return 0
   }
-
-  // 本命令没有子命令,位置参数一律是敲错了。最可能被敲的正是
-  // `lark-relay-collect collect`,它若静默起 daemon 又是一次「求助反而丢消息」
-  if (a._.length) {
-    const extra = a._.join(' ')
-    const hint = /^(collect|take|status)$/.test(a._[0])
-      ? `\n采集就是本命令自己,不带子命令;take/status 在 \`lark-relay\` 那边\n`
-      : '\n'
-    process.stderr.write(`${PROG} 不接位置参数,多了:${extra}${hint}跑 \`${PROG} --help\` 看用法\n`)
-    return 2
-  }
-
-  // store 保留天数。消费侧扫盘上还在的全部日期,所以这里改多少都自洽,
-  // 不再有「窗口必须正好等于 retain」那条跨进程不变量(见 docs/lessons.md#扫描窗口)
-  const retain = numStrict(a.retain, 3)
-  if (retain === null || !(retain >= 1)) {
-    process.stderr.write(`--retain 需要 >= 1 的天数,当前:${a.retain === true ? '(没给值)' : a.retain}\n`)
+  const retain = numberArg(a.retain, 3, 'retain')
+  if (!Number.isSafeInteger(retain) || retain < 1) {
+    process.stderr.write('--retain 需要 >= 1 的整数天数\n')
     return 2
   }
-
   const { runCollect } = require('../lib/collect')
-  return await runCollect({
-    exclude: list(a.exclude),
+  return runCollect({
+    exclude: a.exclude ? a.exclude.split(',').map((s) => s.trim()).filter(Boolean) : [],
     retain,
   })
 }
 
 main()
-  .then((code) => {
-    process.exitCode = code || 0
-  })
+  .then((code) => { process.exitCode = code })
   .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.exitCode = 1
+    process.stderr.write(`${err.userFacing ? err.message : err.stack}\n`)
+    process.exitCode = err.exitCode || 1
   })

package/bin/lark-relay.js

@@ -3,195 +3,129 @@
 
 require('../lib/utf8').ensureUtf8()
 
-const { parseArgs, numStrict, rejectUnknown } = require('../lib/args')
+const { parseArgs, numberArg } = require('../lib/args')
 const help = require('../lib/help')
-
 const VERSION = require('../package.json').version
-
-// 带值参数白名单(布尔开关在 parseArgs 的 flags 里)。
-// 不在白名单的 --xxx 一律硬报错 —— 拼错参数静默吞掉是实测事故,见 docs/lessons.md#静默失败
 const TAKE_KEYS = ['app', 'chats', 'name', 'filter', 'debounce', 'max-wait', 'timeout', 'render', 'since']
 
-const USAGE = `lark-relay ${VERSION} -- Lark 事件中继站(在场取用)
+const USAGE = `lark-relay ${VERSION} -- Lark 事件中继站
 
-  lark-relay take ...           在场取用:阻塞等一批 -> 输出 -> 退出
-  lark-relay status             谁在跑 / 各 app 收了多少 / 游标在哪
+  lark-relay take ...           阻塞等一批 -> 输出 -> 退出
+  lark-relay status             采集状态 / 事件数量 / 消费断点
+  lark-relay-collect            常驻采集
 
-采集底座是独立的常驻命令:lark-relay-collect
-
-用法详情 -> lark-relay take(空参就是完整指导)`
+用法详情: lark-relay take --help`
 
 async function main() {
-  const argv = process.argv.slice(2)
-  const cmd = argv[0]
-  const rest = argv.slice(1)
-
-  if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') {
-    process.stdout.write(`${USAGE}\n`)
-    return 0
-  }
-  if (cmd === '--version' || cmd === '-v' || cmd === 'version') {
-    process.stdout.write(`${VERSION}\n`)
-    return 0
-  }
-
-  switch (cmd) {
-    case 'take':
-      return await cmdTake(rest)
-    case 'status':
-      return await cmdStatus(rest)
-    // 能力是**搬家不是删除**,提示必须给出新名字,否则会被当成功能没了
-    case 'collect':
-      process.stderr.write('采集是独立命令(同一个包就带):lark-relay-collect --help\n')
-      return 2
-    default:
-      process.stderr.write(`未知命令:${cmd}\n\n${USAGE}\n`)
-      return 2
+  const [cmd, ...rest] = process.argv.slice(2)
+  if (cmd === 'take') return cmdTake(rest)
+  if (cmd === 'status') return cmdStatus(rest)
+  if (cmd && !cmd.startsWith('-')) {
+    process.stderr.write(`未知命令:${cmd}\n${USAGE}\n`)
+    return 2
   }
+  const a = parseArgs(process.argv.slice(2), { flags: ['version'] })
+  process.stdout.write(`${a.version ? VERSION : USAGE}\n`)
+  return 0
 }
 
 async function cmdTake(argv) {
-  const a = parseArgs(argv, { flags: ['help'], keys: TAKE_KEYS })
-  if (a._unknown.length) return rejectUnknown('lark-relay take', a._unknown, TAKE_KEYS)
-  const larkcli = require('../lib/larkcli')
-
-  // 空参数输出完整照做指导,而非报错 -- AI 的真实行为是「先空参数跑一下看看」。
-  // 但带了参数又缺 app/chats 的走下面短错误 -- 打印完整用法和 --help 长得一样,
-  // 会被当成「正常退出但没消息」
+  const a = parseArgs(argv, { keys: TAKE_KEYS })
   if (a.help || argv.length === 0) {
-    let apps = []
-    try {
-      apps = (await larkcli.listProfiles()).filter((p) => p.usable).map((p) => p.name)
-    } catch {}
-    process.stdout.write(`${help.takeHelp(apps)}\n`)
-    return 0 // 空参 = 求教,和 --help 一样是成功路径
+    process.stdout.write(`${help.TAKE_HELP}\n`)
+    return 0
   }
 
   const store = require('../lib/store')
   const { takeBatch, deriveName, parseChats } = require('../lib/take')
+  const { validateFilter } = require('../lib/filter')
   const { render } = require('../lib/render')
   const { acquireExclusive } = require('../lib/lock')
 
-  if (!a.app || a.app === true) {
-    process.stderr.write('需要 --app <name>(= lark-cli profile 名)。完整步骤跑 `lark-relay take`\n')
+  if (!a.app) {
+    process.stderr.write('需要 --app <name>,跑 `lark-relay take --help` 看用法\n')
     return 2
   }
-  const chats = parseChats(a.chats === true ? '' : a.chats)
-  if (!chats.length) {
-    process.stderr.write('需要 --chats oc_xxx。跑 `lark-relay take` 看完整用法\n')
+  const chats = parseChats(a.chats)
+  if (!chats.length || chats.some((c) => !c.startsWith('oc_'))) {
+    process.stderr.write('需要 --chats oc_xxx,多个 chat_id 用逗号分隔\n')
     return 2
   }
-  const bad = chats.filter((c) => !c.startsWith('oc_'))
-  if (bad.length) {
-    process.stderr.write(
-      `--chats 只接受 oc_ 开头的 chat_id,这些不是:${bad.join(' ')}\n` +
-        `群名会匹配错群,而监听错群是静默失败(你会一直等一个永不来的消息)。\n` +
-        `查 ID:lark-cli --profile ${a.app} im +chat-search --as user --query "<群名>"\n`,
-    )
+  const name = a.name ?? deriveName(a.app, chats)
+  const since = a.since ?? 'now'
+  const mode = a.render ?? 'ndjson'
+  if (!['now', 'all'].includes(since)) {
+    process.stderr.write(`--since 只能是 now 或 all,当前:${since}\n`)
     return 2
   }
+  if (!['text', 'ndjson'].includes(mode)) {
+    process.stderr.write(`--render 只能是 text 或 ndjson,当前:${mode}\n`)
+    return 2
+  }
+  const duration = (key, fallback) => numberArg(a[key], fallback, key) * 1000
+  const debounceMs = duration('debounce', 5)
+  const maxWaitMs = duration('max-wait', 25)
+  const timeoutMs = duration('timeout', 12 * 3600)
+  if (![debounceMs, maxWaitMs, timeoutMs].every(Number.isFinite)) {
+    process.stderr.write('时长超出可用范围\n')
+    return 2
+  }
+  validateFilter(a.filter)
 
-  const name = a.name && a.name !== true ? a.name : deriveName(a.app, chats)
-
-  // 同一 --name 不该有两个 take 在跑:两个进程互相推游标会撕批次
+  // 参数全部有效后才持锁或创建断点
   const lock = acquireExclusive(`take-${name}`)
   if (!lock.ok) {
-    process.stderr.write(
-      `已有一个 take 在用游标身份 "${name}"(pid ${lock.holder})。\n` +
-        `要并行盯同一 app 请用不同 --name,否则两个进程会互相推游标撕批次。\n`,
-    )
+    process.stderr.write(`游标身份 "${name}" 被占用(pid ${lock.holder}),并行消费请换 --name\n`)
     return 3
   }
-
-  // --since 只有 now|all 两个取值,必须白名单校验:曾经是「跟 'now' 比一次,
-  // 其余全当 all」,于是 `--since Now` 静默变成全量重放
-  const since = a.since === true ? 'now' : a.since || 'now'
-  if (since !== 'now' && since !== 'all') {
-    process.stderr.write(`--since 只能是 now 或 all,当前:${since}\n`)
-    return 2
-  }
-  // 没有游标就按 --since now 起头。已有的一律原样保留 ——
-  // 别「自愈」到最新,那会静默丢掉全部积压(见 docs/lessons.md#游标判据)
-  if (since === 'now') {
-    if (store.readCursor(name, a.app) === null) store.seedCursorNow(name, a.app)
+  if (since === 'now' && store.readCursor(name, a.app) === null) {
+    store.seedCursorNow(name, a.app)
   }
 
-  // 标记「有人来取过」:gc 判据是 mtime,而 take 空手退出时不写游标。
-  // 不 touch 会把「盯着一个安静的群」误判成遗弃
-  store.touchCursor(name, a.app)
-
-  // 时长参数校验:负数/非数字过去会静默退回默认值或原样生效
-  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
   const fmtDur = (ms) => (ms >= 3600000 ? `${ms / 3600000}h` : `${ms / 1000}s`)
   process.stderr.write(
     `监听中:app=${a.app} 群=${chats.length} 个(${chats.join(',')}) 游标=${name} ` +
       `防抖=${debounceMs / 1000}s 最长等=${fmtDur(timeoutMs)}\n`,
   )
-
   const ac = new AbortController()
   const onSig = () => ac.abort()
   process.on('SIGTERM', onSig)
   process.on('SIGINT', onSig)
-
   const res = await takeBatch({
     app: a.app,
     chats,
     name,
-    filter: a.filter === true ? null : a.filter,
+    filter: a.filter,
     debounceMs,
     maxWaitMs,
     timeoutMs,
     signal: ac.signal,
   })
-
   if (!res.events.length) {
-    process.stderr.write(`没等到消息(${res.reason})。游标身份 ${name},正常退出,再起一个继续\n`)
+    process.stderr.write(`没等到消息(${res.reason}),再起一个继续\n`)
     return res.reason === 'timeout' ? 4 : 0
   }
-
-  const mode = a.render === true ? 'text' : a.render
   process.stdout.write(`${render(res.events, mode)}\n`)
   process.stderr.write(`${res.events.length} 条,游标身份 ${name}\n`)
   return 0
 }
 
 async function cmdStatus(argv) {
-  const a = parseArgs(argv, { flags: ['json', 'help'], keys: [] })
-  if (a._unknown.length) return rejectUnknown('lark-relay status', a._unknown, ['json'])
+  const a = parseArgs(argv, { flags: ['json'] })
   if (a.help) {
     process.stdout.write(`${help.STATUS_HELP}\n`)
     return 0
   }
   const { buildStatus, formatStatus } = require('../lib/status')
   const s = await buildStatus()
-  if (a.json) process.stdout.write(`${JSON.stringify(s, null, 2)}\n`)
-  else process.stdout.write(`${formatStatus(s)}\n`)
+  process.stdout.write(`${a.json ? JSON.stringify(s, null, 2) : formatStatus(s)}\n`)
   return 0
 }
 
+// 自然排空 stdout,避免大批次经管道输出时被截断
 main()
-  .then((code) => {
-    // ⚠️ 不能用 process.exit():stdout 是管道时它会丢掉未 flush 的缓冲
-    // (实测 676KB 只收到 65536 且切在 JSON 中途)。见 docs/lessons.md#管道截断
-    process.exitCode = code || 0
-  })
+  .then((code) => { process.exitCode = code })
   .catch((err) => {
-    if (err && err.userFacing) process.stderr.write(`${err.message}\n`)
-    else process.stderr.write(`lark-relay: ${(err && err.stack) || err}\n`)
-    process.exitCode = (err && err.exitCode) || 1
+    process.stderr.write(`${err.userFacing ? err.message : err.stack}\n`)
+    process.exitCode = err.exitCode || 1
   })

package/lib/args.js

@@ -1,85 +1,37 @@
 'use strict'
 
-// 零依赖 argv 解析。只支持 --key value / --key=value / --flag。
-// spec.flags:布尔开关;spec.keys:带值选项。不在两者里的 --xxx 进 out._unknown,
-// 由调用侧硬报错 —— 拼错参数必须当场失败,不能静默吞掉
-// (实测:--chat-id 拼错 -> 打印用法退出,看着像「正常退出但没消息」,漏看 bot 第一条 Working)
-function parseArgs(argv, spec = {}) {
-  const flags = new Set(spec.flags || [])
-  const keys = new Set(spec.keys || [])
-  const known = (k) => flags.has(k) || keys.has(k)
-  const out = { _: [], _unknown: [] }
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i]
-    if (a === '--') {
-      out._.push(...argv.slice(i + 1))
-      break
-    }
-    if (!a.startsWith('--')) {
-      out._.push(a)
-      continue
-    }
-    const eq = a.indexOf('=')
-    if (eq !== -1) {
-      const k = a.slice(2, eq)
-      if (known(k)) out[k] = a.slice(eq + 1)
-      else out._unknown.push(k)
-      continue
-    }
-    const key = a.slice(2)
-    if (!known(key)) {
-      out._unknown.push(key)
-      // 吞掉它的值,避免下一个非 -- 参数错位成位置参数
-      const next = argv[i + 1]
-      if (next !== undefined && !next.startsWith('--')) i++
-      continue
-    }
-    if (flags.has(key)) {
-      out[key] = true
-      continue
-    }
-    const next = argv[i + 1]
-    if (next === undefined || next.startsWith('--')) {
-      out[key] = true // 缺值,由调用侧校验
-    } else {
-      out[key] = next
-      i++
+const { parseArgs: parse } = require('node:util')
+
+function parseArgs(args, { keys = [], flags = [] } = {}) {
+  const options = { help: { type: 'boolean', short: 'h' } }
+  for (const key of keys) options[key] = { type: 'string' }
+  for (const flag of flags) options[flag] = { type: 'boolean' }
+  if (options.version) options.version.short = 'v'
+  try {
+    const { values } = parse({ args, options, strict: true, allowPositionals: false })
+    for (const key of keys) {
+      if (values[key] !== undefined && !values[key].trim()) {
+        throw new Error(`--${key} 不能为空`)
+      }
     }
+    return values
+  } catch (err) {
+    err.message += `\n可用参数:${Object.keys(options).map((k) => `--${k}`).join(' ')}`
+    err.userFacing = true
+    err.exitCode = 2
+    throw err
   }
-  return out
 }
 
-// 数值参数:省略 -> 默认值;给了但不是有效数字 -> 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 : null
-}
-
-function list(v) {
-  if (!v || v === true) return []
-  return String(v)
-    .split(',')
-    .map((s) => s.trim())
-    .filter(Boolean)
-}
-
-// 未知参数 -> stderr 短错误 + 合法参数清单,exit 2。
-// 不打印完整用法 -- 那看着像 --help 成功,会被当成「正常退出但没消息」。
-//
-// 直接列出全部合法参数,不做编辑距离猜测:参数总共 9 个,列出来比猜一个更有用
-// (曾有 50 行 levenshtein + suggest 干这件事)。
-//
-// ⚠️ `prog` 必须由调用方传入:两个 bin 共用这段,而提示里那行是要照抄执行的 --
-// 打出一个不存在的命令会把人引向死路
-function rejectUnknown(prog, unknown, allowed, out = process.stderr) {
-  const shown = [...new Set(unknown)].map((k) => `--${k}`).join(', ')
-  const list = allowed.map((k) => `--${k}`).join(' ')
-  out.write(`未知参数:${shown}\n可用参数:${list}\n跑 \`${prog}\` 看完整用法\n`)
-  return 2
+function numberArg(value, fallback, label) {
+  const n = value === undefined ? fallback : Number(value)
+  if (!Number.isFinite(n) || n < 0) {
+    throw Object.assign(new Error(`--${label} 需要有限的非负数,当前:${value}`), {
+      userFacing: true,
+      exitCode: 2,
+    })
+  }
+  return n
 }
 
-module.exports = { parseArgs, numStrict, list, rejectUnknown }
+module.exports = { parseArgs, numberArg }