lark-relay 0.4.5 → 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,32 +16,37 @@ Lark 事件是**流式**的 -- 进程不在的时刻,消息**永久丢失**,不
 (实测:消息发出 8 秒后才起 consumer,收到 0 条)。
 
 所以要有一个常驻进程只管把事件收下来落盘,消费侧崩了、AI 跑了半小时、
-会话关了几小时,都不丢消息。这就是 `collect`。
+会话关了几小时,都不丢消息。这就是 `lark-relay-collect`。
 
-## 两个场景(不可混用)
+## 两段分离
 
-|  | 在场取用 `take` | 托管派活 `dispatch` |
-| --- | --- | --- |
-| 长命的 | AI 会话(人设、上下文连续) | 消息(等在队列里) |
-| 短命的 | 消息(来一批处理一批) | AI(每轮新起,跑完就没) |
-| 谁在等谁 | AI 等消息 | 消息等 AI |
-| 控制权 | AI 手里(自己决定何时再取) | 服务手里(决定何时拉起 AI) |
-| 谁能干 | 任何 agent(Claude Code / Codex / 手敲) | 需内置唤起知识 |
-| 配置 | 纯参数,无文件 | `dispatch.yaml` |
+采集与消费必须分离:`lark-relay-collect` 只管把事件收下来落盘,`lark-relay take`
+在你需要时取走一批。消费侧崩了、AI 跑了半小时、会话关了几小时,采集都不能停 --
+停摆的每一秒都在丢消息。
 
-你(AI)在会话里盯群 -> `take`。无人在场也要干活 -> `dispatch`。
+分离到**可执行文件**这一层,不是两个子命令:采集是常驻服务,服务管理器
+(systemd / launchd)展示的是可执行文件名,与单元名同名才认得出是谁。
+
+| | |
+| --- | --- |
+| 长命的 | AI 会话(人设、上下文连续) |
+| 短命的 | 消息(来一批处理一批) |
+| 谁在等谁 | AI 等消息 |
+| 控制权 | AI 手里(自己决定何时再取) |
+| 谁能干 | 任何 agent(Claude Code / Codex / 手敲) |
+| 配置 | 纯参数,无文件 |
 
 ## 命令
 
 ```bash
-lark-relay collect            # 底座:全部 profile 各起 consume -> 原子落盘(常驻服务)
-lark-relay take …             # 场景1:阻塞等一批 -> 输出 -> 退出
-lark-relay dispatch <task>    # 场景2:常驻循环 = take + 唤起 claude
+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(永久失败,重试是死循环)。
@@ -49,7 +54,7 @@ lark-relay guide              # 一页用法
 每 app 一个子进程,某个挂了单独重启不影响其他。回收在本进程内每小时自查,
 删超期的整个日期目录 -- 不另起 gc 单元/timer。
 
-### take
+### lark-relay take
 
 只有一种形态:**阻塞等 -> 有一批就输出 -> 退出**。循环交给 harness --
 Claude Code 用 `run_in_background` 起,进程退出会主动通知 AI,这才是事件驱动。
@@ -65,62 +70,15 @@ lark-relay take --app <app> --chats oc_xxx --render text
 
 业务过滤只有 `--filter`(jq 表达式)一个口子,不为每个业务加参数。
 
-### dispatch
-
-任务发现:扫 `$LR_ROOT/*/dispatch.yaml` -- 有文件即是任务,无需注册表。
-`dispatch` 内部就是调 `take`,保证两场景不实现分叉。
-
-```yaml
-app: <profile 名>
-chats: [oc_xxx]
-dirs: [/path/to/repo]            # 首个 = 主工作目录
-instructions: ./instructions.md  # 职责/边界,--append-system-prompt-file 注入
-filter: '.mentions[]?.id == "ou_xxx"'   # 可选
-# mode: work        默认;work | chat | agent(见下)
-# model: <名称>      默认走终端同一套默认路由
-```
-
-`mode` 三个场景 -- 一个键定死全部行为,不用拼组合:
-
-| | `work`(默认) | `chat` | `agent` |
-|---|---|---|---|
-| 用途 | 处理工作 | 简单问答 | 群运营 |
-| 回复位置 | 话题内(首问开话题) | 直接发群里 | **模型自己决定** |
-| 过程展示 | COT 消息(实时流式) | 无 | 无 |
-| 结论投递 | 引擎发卡片 | 引擎发纯文本 | **引擎不发** |
-| session 隔离 | 按 `thread_id` | 按 (群, epoch) | 按 (群, epoch) |
-| 防抖 | 1s | 15s | 15s |
-
-`agent` 是给「**多数轮该沉默**」的场景准备的:群运营里绝大多数消息不需要回应,
-而 `work`/`chat` 的提示词都承诺「你的最终回复会被发回群」,等于逼模型每轮说话。
-`agent` 模式下引擎只负责拉起模型、传消息批次、记台账 -- 发不发、回哪条、
-用哪个 bot 身份、发文字还是表情回应,全由模型按 `instructions` 决定(它有
-Bash + lark-cli)。沉默的轮也会进台账,便于事后看它到底判了多少次。
-
-这与「引擎不做权限管控」是同一条思路:**引擎不做回复决策,边界靠 instructions
-到达模型侧**。
-
-`work` 的过程与结论是**两条消息** -- COT 消息只承载过程(接口的设计前提),
-结论另发一条卡片。卡片发送失败会自动降级纯文本,保证结论必达。
-
-⚠️ **COT 要求客户端 PC ≥ 7.70 / 移动 ≥ 7.74**:老客户端上那条过程消息显示为
-「Completed」(不会崩),结论卡片不受影响 -- 这也是「结论单独发」的价值。
-
-环境变量:`LR_COT_BATCH_MS`(COT 攒批窗口,默认 1000)、
-`LR_COT_SAY_AS=text|reasoning`(中间文本走正式文本流还是思考流,默认 `text`;
-实测两者渲染一致,`text` 每段少 2 个事件)。
-
 ## 存储布局
 
 ```
 ~/.lark-relay/
   store/<app>/<YYYY-MM-DD>/<纳秒>_<pid>_<seq>.json   原始事件(可随时删,丢了自愈)
   cursors/<name>/<app>                               各消费者游标
-  ledger/<task>__<chat>.ndjson                       dispatch 结论台账
 ```
 
-判据:能随时删掉重建的才放这里。`ledger` 是唯一不能重建的东西
-(session 会因空闲滚动/过期丢上下文,结论不能丢),走文件系统级备份。
+判据:能随时删掉重建的才放这里 -- 上面两样都能。
 
 多消费者**共享 store、各持游标**,不做「处理完即删」-- 谁都不能替别人删。
 盯同一 app 请用不同 `--name` 隔离游标。

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,89 +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', 'ledger-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
-}
+const COMMANDS = ['take', 'status', 'guide']
 
-// 把未知参数替换成候选,拼出可照跑的命令行;无候选的未知参数(连同它的值)丢弃
-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
-}
+// 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 → 原子落盘（systemd 常驻）
-  lark-relay take …             场景1 在场取用:阻塞等一批 → 输出 → 退出
-  lark-relay dispatch <task>    场景2 托管派活:常驻循环 = take + 唤起 claude
+  lark-relay take …             在场取用:阻塞等一批 → 输出 → 退出
   lark-relay status             谁在跑 / 各 app 积压 / 各游标位置
   lark-relay guide              一页用法（装完先读这个）
 
+采集底座是独立命令(常驻服务):lark-relay-collect
+
 第一次用 → lark-relay guide
 各命令详情 → lark-relay <命令> --help`
 
@@ -105,40 +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)
-    case 'dispatch':
-      return await cmdDispatch(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', 'dispatch', '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),
-    ledgerRetain: num(a['ledger-retain'], 90),
-  })
-}
-
 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 的真实行为是「先空参数跑一下看看」。
@@ -235,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
@@ -247,28 +187,6 @@ async function cmdStatus(argv) {
   return 0
 }
 
-async function cmdDispatch(argv) {
-  const a = parseArgs(argv, { flags: ['list', 'once', 'help'], keys: [] })
-  if (a._unknown.length) return rejectUnknown('dispatch', argv, a._unknown, ['list', 'once'])
-  if (a.help) {
-    process.stdout.write(`${help.DISPATCH_HELP}\n`)
-    return 0
-  }
-  const dispatch = require('../lib/dispatch')
-  if (a.list) return dispatch.cmdList()
-  const task = a._[0]
-  if (!task) {
-    // 空参 = 求教,和 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 })
-}
-
 main()
   .then((code) => process.exit(code || 0))
   .catch((err) => {

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

@@ -5,11 +5,12 @@
 //
 // 为什么必须独立常驻:lark 事件是流式的,进程不在的时刻消息永久丢失
 // (实测:消息发出 8s 后才起 consumer,收到 0 条)。collect 独立常驻,
-// 才能让 take/dispatch 侧崩了、claude 跑 30 分钟、会话关几小时,都不丢消息。
+// 才能让 take 侧崩了、AI 跑 30 分钟、会话关几小时,都不丢消息。
 const readline = require('readline')
 const larkcli = require('./larkcli')
 const store = require('./store')
 const { paths, ensureDir } = require('./paths')
+const { init: logInit, logLine } = require('./log')
 
 const EVENT_KEY = process.env.LARK_RELAY_EVENT_KEY || 'im.message.receive_v1'
 const GC_INTERVAL_MS = 3600_000
@@ -45,14 +46,14 @@ class AppCollector {
       try {
         obj = JSON.parse(s)
       } catch {
-        process.stderr.write(`[${this.app}] warn: 非 JSON 行,已跳过\n`)
+        logLine(`[${this.app}] warn: 非 JSON 行,已跳过`)
         return
       }
       try {
         store.writeEvent(this.app, obj, this.seq++)
         this.received++
       } catch (err) {
-        process.stderr.write(`[${this.app}] error: 落盘失败 ${err.message}\n`)
+        logLine(`[${this.app}] error: 落盘失败 ${err.message}`)
       }
     })
 
@@ -63,10 +64,17 @@ class AppCollector {
       this.backoffMs = 1000
     }, 30_000)
 
-    // 不加 --quiet:它会隐藏事件丢失。stderr 的 ready/exit/drop 诊断进 journald
-    child.stderr.on('data', (buf) => {
-      const text = buf.toString().trimEnd()
-      if (text) process.stderr.write(`[${this.app}] ${text}\n`)
+    // 不加 --quiet:它会隐藏事件丢失。stderr 的 ready/exit/drop 诊断要留下。
+    //
+    // ⚠️ 必须走 readline 按行读,不能裸接 'data' 事件(改回去会同时带回三个 bug):
+    //   ① 一个 chunk 常含多行 -> 只有块首能拿到 [app] 前缀与时间戳,其余行无法归属
+    //   ② chunk 边界任意切,一条诊断可能被拆成两次 write -> 变成两条独立记录
+    //   ③ UTF-8 多字节被 chunk 边界切断 -> 中文诊断出现替换字符
+    // readline 内部用 StringDecoder 处理跨块残字节,故 stdout 路径从来没这些问题。
+    const erl = readline.createInterface({ input: child.stderr, crlfDelay: Infinity })
+    erl.on('line', (line) => {
+      const text = line.trimEnd()
+      if (text) logLine(`[${this.app}] ${text}`)
     })
 
     // spawn 失败(lark-cli 被卸载 / 升级中途 / PATH 变化)只发 error+close,**没有 exit**。
@@ -78,9 +86,9 @@ class AppCollector {
       clearTimeout(this.healthyTimer)
       this.child = null
       this.restarts++
-      process.stderr.write(
+      logLine(
         `[${this.app}] consume 退出(${why}),${Math.round(this.backoffMs / 1000)}s 后重启 ` +
-          `—— 这段时间该 app 的消息会永久丢失\n`,
+          `—— 这段时间该 app 的消息会永久丢失`,
       )
       // 每 app 一个子进程;某个挂了单独重启,不影响其他
       setTimeout(() => this.start(), this.backoffMs)
@@ -92,7 +100,7 @@ class AppCollector {
     })
 
     child.on('error', (err) => {
-      process.stderr.write(`[${this.app}] spawn 失败:${err.message}\n`)
+      logLine(`[${this.app}] spawn 失败:${err.message}`)
       scheduleRestart(`spawn error ${err.code || err.message}`)
     })
   }
@@ -108,22 +116,25 @@ class AppCollector {
 async function runCollect(opts) {
   ensureDir(paths.store)
   ensureDir(paths.cursors)
-  ensureDir(paths.ledger)
+  // 日志接管要最早做 —— 下面的启动横幅、profile 报错都该带上时间戳。
+  // 非 launchd 场景(journald / 前台)是 no-op,logLine 退化成裸 stderr 直写
+  logInit()
 
   const exclude = new Set(opts.exclude || [])
   let profiles
   try {
     profiles = await larkcli.listProfiles()
   } catch (err) {
-    const e = new Error(
-      `读不到 lark-cli profile 列表:${(err.message || '').split('\n')[0]}\n` +
+    // 不抛给 bin 的顶层 catch —— 那行是所有命令共用的裸 stderr,
+    // 会让「collect 崩了」这条最关键的记录反而没有时间戳
+    logLine(
+      `error: 读不到 lark-cli profile 列表:${(err.message || '').split('\n')[0]}\n` +
         `collect 依赖 lark-cli 提供认证与事件总线。检查:\n` +
         `  which ${larkcli.CLI}          # 装了吗、在 PATH 里吗\n` +
         `  ${larkcli.CLI} profile list   # 能跑吗\n` +
         `常驻服务(systemd 单元/launchd plist)的 PATH 要用 fnm default alias 的稳定路径,不能用会话级的 multishell 路径`,
     )
-    e.userFacing = true
-    throw e
+    return 1
   }
 
   const chosen = []
@@ -143,17 +154,17 @@ async function runCollect(opts) {
   }
 
   if (skipped.length) {
-    process.stderr.write(`warn: 跳过 ${skipped.join(' ')}\n`)
+    logLine(`warn: 跳过 ${skipped.join(' ')}`)
   }
   if (!chosen.length) {
-    process.stderr.write('error: 没有可用 profile。先 `lark-cli auth login`\n')
+    logLine('error: 没有可用 profile。先 `lark-cli auth login`')
     return 1
   }
 
-  process.stderr.write(
-    `lark-relay collect: ${chosen.length}/${profiles.length} profiles → ${paths.store}\n` +
+  logLine(
+    `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}天 ledger 保留 ${opts.ledgerRetain}天\n`,
+      `  event_key=${EVENT_KEY} store 保留 ${opts.retain}天`,
   )
 
   const collectors = chosen.map((p) => new AppCollector(p.name, opts))
@@ -164,18 +175,16 @@ async function runCollect(opts) {
   const gcTimer = setInterval(() => {
     try {
       const s = store.gcStore(opts.retain)
-      const l = store.gcLedger(opts.ledgerRetain)
-      if (s.length || l.length) {
-        process.stderr.write(`gc: 删 store ${s.length} 个日期目录, ledger ${l.length} 个文件\n`)
+      if (s.length) {
+        logLine(`gc: 删 store ${s.length} 个日期目录`)
       }
     } catch (err) {
-      process.stderr.write(`gc: 失败 ${err.message}\n`)
+      logLine(`gc: 失败 ${err.message}`)
     }
   }, GC_INTERVAL_MS)
   // 启动时先跑一次,别等一小时
   try {
     store.gcStore(opts.retain)
-    store.gcLedger(opts.ledgerRetain)
   } catch {}
 
   return await new Promise((resolve) => {
@@ -183,7 +192,7 @@ async function runCollect(opts) {
     const shutdown = (sig) => {
       if (shuttingDown) return
       shuttingDown = true
-      process.stderr.write(`收到 ${sig},停止 ${collectors.length} 个 consumer\n`)
+      logLine(`收到 ${sig},停止 ${collectors.length} 个 consumer`)
       clearInterval(gcTimer)
       for (const c of collectors) c.stop()
       // 给子进程时间卸载服务端订阅

package/lib/filter.js

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