lark-relay 0.4.4 → 0.4.6

package/README.md

@@ -18,25 +18,26 @@ Lark 事件是**流式**的 -- 进程不在的时刻,消息**永久丢失**,不
 所以要有一个常驻进程只管把事件收下来落盘,消费侧崩了、AI 跑了半小时、
 会话关了几小时,都不丢消息。这就是 `collect`。
 
-## 两个场景(不可混用)
+## 两段分离
 
-|  | 在场取用 `take` | 托管派活 `dispatch` |
-| --- | --- | --- |
-| 长命的 | AI 会话(人设、上下文连续) | 消息(等在队列里) |
-| 短命的 | 消息(来一批处理一批) | AI(每轮新起,跑完就没) |
-| 谁在等谁 | AI 等消息 | 消息等 AI |
-| 控制权 | AI 手里(自己决定何时再取) | 服务手里(决定何时拉起 AI) |
-| 谁能干 | 任何 agent(Claude Code / Codex / 手敲) | 需内置唤起知识 |
-| 配置 | 纯参数,无文件 | `dispatch.yaml` |
+采集与消费必须分离:`collect` 只管把事件收下来落盘,`take` 在你需要时取走一批。
+消费侧崩了、AI 跑了半小时、会话关了几小时,采集都不能停 --
+停摆的每一秒都在丢消息。
 
-你(AI)在会话里盯群 -> `take`。无人在场也要干活 -> `dispatch`。
+| | |
+| --- | --- |
+| 长命的 | 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 take …             # 阻塞等一批 -> 输出 -> 退出
 lark-relay status             # 谁在跑 / 各 app 积压 / 各游标位置
 lark-relay guide              # 一页用法
 ```
@@ -65,62 +66,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.js

@@ -17,7 +17,7 @@ const VERSION = require('../package.json').version
 // 不在白名单的 --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']
+const COLLECT_KEYS = ['exclude', 'retain']
 
 // 未知参数 -> stderr 短错误 + 候选提示 + 改写后的命令,exit 2。
 // 不打印完整用法 -- 那看着像 --help 成功,会被当成「正常退出但没消息」
@@ -78,9 +78,8 @@ function rewriteArgv(argv, unknown, allowed) {
 
 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 collect            底座:全部 profile 各起 consume → 原子落盘（常驻服务）
+  lark-relay take …             在场取用:阻塞等一批 → 输出 → 退出
   lark-relay status             谁在跑 / 各 app 积压 / 各游标位置
   lark-relay guide              一页用法（装完先读这个）
 
@@ -111,10 +110,8 @@ async function main() {
       return await cmdTake(rest)
     case 'status':
       return await cmdStatus(rest)
-    case 'dispatch':
-      return await cmdDispatch(rest)
     default: {
-      const s = suggest(cmd, ['collect', 'take', 'dispatch', 'status', 'guide'])
+      const s = suggest(cmd, ['collect', 'take', 'status', 'guide'])
       process.stderr.write(`未知命令:${cmd}${s ? `。你是不是想写 ${s}?` : ''}\n\n${USAGE}\n`)
       return 2
     }
@@ -132,7 +129,6 @@ async function cmdCollect(argv) {
   return await runCollect({
     exclude: list(a.exclude),
     retain: num(a.retain, 3),
-    ledgerRetain: num(a['ledger-retain'], 90),
   })
 }
 
@@ -247,28 +243,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/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(
+  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 重启一次,该任务彻底停摆。
     // 放行的代价是模型多看几条本该滤掉的消息,远小于停摆

package/lib/help.js

@@ -61,11 +61,14 @@ tokenStatus 为 expired 的 profile 自动跳过并 warn(永久失败,重试是
 用户重新 login 后下次启动自动纳入。
 
 为什么必须常驻:lark 事件是流式的,进程不在的时刻消息永久丢失(实测:消息发出
-8s 后才起 consumer,收到 0 条)。collect 独立常驻,才能让 take/dispatch 侧
-崩了、claude 跑 30 分钟、会话关几小时,都不丢消息。
+8s 后才起 consumer,收到 0 条)。collect 独立常驻,才能让 take 侧
+崩了、AI 跑 30 分钟、会话关几小时,都不丢消息。
 
-装完先 \`lark-relay status\` 确认 -- collect 行应为 running;不在跑看
-服务日志(Linux \`journalctl -u lark-relay-collect\`;macOS \`log show --predicate 'process == "lark-relay"'\`)。
+装完先 \`lark-relay status\` 确认 -- collect 行应为 running;不在跑看服务日志:
+  Linux   journalctl -u lark-relay-collect
+  macOS   tail -f ~/.lark-relay/logs/collect.err.log
+          (launchd 把 stderr 直写该文件,**不进统一日志**,log show 查不到)
+          日志行带 ISO 时间戳;超 16MB 自动轮转,旧的在 .1/.2/.3
 
 落盘:~/.lark-relay/store/<app>/<YYYY-MM-DD>/<纳秒>_<pid>_<seq>.json
 回收由 collect 进程内每小时自查一次,删超期的整个日期目录(不另起 gc 单元/timer)。
@@ -73,76 +76,26 @@ tokenStatus 为 expired 的 profile 自动跳过并 warn(永久失败,重试是
 参数
   --exclude <apps>  排除指定 profile(逗号分隔)
   --retain N        store 保留天数(默认 3)
-  --ledger-retain N ledger 保留天数(默认 90)`
+
+环境变量
+  LARK_RELAY_LOG_MAX_MB  单个日志文件上限(默认 16),超了轮转
+  LARK_RELAY_LOG_KEEP    保留几代旧日志(默认 3)`
 
 const STATUS_HELP = `一眼看清全局:谁在跑、积压多少、游标在哪。
 
   lark-relay status              # 概览
   lark-relay status --json       # 机器可读
 
-排障入口:某消费者「落后」很多 -> 它的 take/dispatch 没在跑或卡住;
+排障入口:某消费者「落后」很多 -> 它的 take 没在跑或卡住;
 「无消费者」= 白采,可考虑 --exclude。
-collect 行不是 running -> 看服务日志(systemd journal 或 launchd 统一日志),
+collect 行不是 running -> 看服务日志(Linux journalctl;
+macOS \`tail -f ~/.lark-relay/logs/collect.err.log\` -- 不进统一日志),
 collect 停摆的每一秒都在丢消息。`
 
-const DISPATCH_HELP = `常驻:等消息 -> 唤起 claude 干活 -> 结果回群。无人在场也跑。
-
-  lark-relay dispatch --list          # 列出所有 dispatch 任务及状态
-  lark-relay dispatch <task> --once   # 前台跑一轮(调试,不进常驻服务)
-  常驻:Linux 用 systemd,macOS 用 launchd(单元模板见仓库 systemd//launchd 目录)
-
---list 输出:任务名 / app / 群数 / 常驻服务是否 active / 上次 ledger 时间
-
-任务发现:扫 $LR_ROOT/*/dispatch.yaml -- 有文件即是任务,无需注册表。
-LR_ROOT 在单元里指定(唯一的目录绑定,与代码无关)。
-
-dispatch.yaml(4 必填 + 3 可选)
-  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   处理工作:话题内回复 + 过程挂 COT 消息 + 结论发卡片
-         + 按 thread_id 隔离 session + 防抖 1s(一问一答要跟手)
-         COT 要求客户端 PC >= 7.70 / 移动 >= 7.74;老客户端那条过程消息显示为
-         「Completed」(不崩),结论卡片不受影响
-  chat   简单问答:直发群里 + 纯文本 + 按(群, epoch)隔离 session
-         + 防抖 15s(等人打完多行)
-  agent  模型自己当运营者:引擎只拉起它 + 传消息 + 记台账,**一条消息都不发**。
-         发不发 / 回哪条 / 用哪个 bot 身份 / 文字还是表情,全由模型按
-         instructions 决定(它有 Bash + lark-cli)。适合「多数轮该沉默」的
-         群运营 -- work/chat 会逼模型每轮都产出一段发回群的话
+const GUIDE = `lark-relay -- Lark 事件中继站。两个命令:收下来 / 我来取。
 
-最佳实践
-  · 边界写 instructions,别指望 --add-dir 目录的 CLAUDE.md(启动不加载)
-  · 改完 yaml 先 --once 跑一轮验证,再 enable
-  · 高风险发布仍建议人工执行
-
-退出码(--once)
-  0  跑了一轮,或没等到消息但正常结束
-  1  取批异常(看 stderr)
-  2  任务不存在或配置错
-  4  等消息超时(5min 没消息)`
-
-const GUIDE = `lark-relay -- Lark 事件中继站。三个命令:收下来 / 我来取 / 派给别人。
-
-先判场景(两者不可混用)
-┌──────────┬────────────────────────┬────────────────────────┐
-│          │ 在场取用 take          │ 托管派活 dispatch      │
-├──────────┼────────────────────────┼────────────────────────┤
-│ 长命的   │ AI 会话(人设、上下文) │ 消息(等在队列里)     │
-│ 短命的   │ 消息(来一批处理一批)  │ AI(每轮新起,跑完就没)│
-│ 谁等谁   │ AI 等消息              │ 消息等 AI              │
-│ 控制权   │ AI 手里                │ 服务手里               │
-│ 谁能干   │ 任何 agent             │ 需内置唤起知识         │
-│ 配置     │ 纯参数,无文件         │ dispatch.yaml          │
-└──────────┴────────────────────────┴────────────────────────┘
-
-你(AI)在会话里盯群 -> take。无人在场也要干活 -> dispatch。
+collect 把事件收下来落盘,take 在你需要时取走一批。两者分离是硬需求:
+消费侧崩了、AI 跑 30 分钟、会话关几小时,采集都不能停 -- 停摆的每一秒都在丢消息。
 
 前置:collect 必须在跑
   lark-relay status        # collect 行应为 running
@@ -159,11 +112,6 @@ take 三步(照做)
   一批处理完再起一个。不要自己写 while 循环 -- 进程退出会通知你。
   退出码:0=有一批,4=超时没消息(正常,再起一个),2=参数错,3=游标被占用。
 
-建 dispatch 任务
-  1. 在任务目录写 dispatch.yaml(\`lark-relay dispatch --help\` 有模板)
-  2. lark-relay dispatch <task> --once     # 前台验一轮
-  3. 起常驻服务(Linux systemd / macOS launchd,模板见仓库)
-
 常见错误
   · 拿不到消息 -> 九成是 bot 不在群。验 bot 必须 --as user,
     bot 不在群时用 bot 身份查不到,「查询失败」不能推断「不在群」
@@ -176,4 +124,4 @@ take 三步(照做)
 
 各命令详情:lark-relay <命令> --help`
 
-module.exports = { takeHelp, COLLECT_HELP, STATUS_HELP, DISPATCH_HELP, GUIDE }
+module.exports = { takeHelp, COLLECT_HELP, STATUS_HELP, GUIDE }

package/lib/lock.js

@@ -1,10 +1,7 @@
 'use strict'
 
-// 两种锁,语义不同,别混:
-// - 消费者锁(非阻塞):同一 --name 不该有两个 take/dispatch 在跑,抢不到直接退出并说清楚。
-//   否则两个进程互相推游标,批次会被撕成两半。
-// - (任务,群)锁(阻塞 -w 1800):dispatch 每群串行。并发会写坏 append-only ledger,
-//   且同群两轮 claude 会互相打断。超时视为「别人正在干」,静默跳过。
+// 消费者锁(非阻塞):同一 --name 不该有两个 take 在跑,抢不到直接退出并说清楚。
+// 否则两个进程互相推游标,批次会被撕成两半。
 const fs = require('fs')
 const path = require('path')
 const { paths, ensureDir } = require('./paths')
@@ -72,19 +69,6 @@ function acquireExclusive(key) {
   return { ok: false, file: dir, holder: readPid(pidFile) }
 }
 
-// 阻塞版:等到拿到锁或超时。dispatch 每(任务,群)一把。
-async function acquireBlocking(key, timeoutMs = 1800_000, pollMs = 500) {
-  const deadline = Date.now() + timeoutMs
-  for (;;) {
-    const lock = acquireExclusive(key)
-    if (lock.ok) return lock
-    if (Date.now() >= deadline) {
-      return { ok: false, file: lock.file, holder: lock.holder, timedOut: true }
-    }
-    await new Promise((r) => setTimeout(r, pollMs))
-  }
-}
-
 function mkHandle(dir, pidFile, me) {
   let released = false
   const release = () => {
@@ -130,4 +114,4 @@ function sanitize(s) {
   return String(s).replace(/[^A-Za-z0-9._-]/g, '_')
 }
 
-module.exports = { acquireExclusive, acquireBlocking }
+module.exports = { acquireExclusive }

package/lib/log.js

@@ -0,0 +1,164 @@
+'use strict'
+
+// 常驻日志:时间戳前缀 + 按大小轮转。**只给 collect 这类常驻服务用**,
+// CLI 的用户可见输出(take 的 NDJSON 载荷、status --json)绝不能过这里 --
+// 加前缀会破坏下游解析契约。
+//
+// 为什么需要:Linux 有 journald 免费给时间戳和轮转,macOS 的 launchd 只有
+// StandardErrorPath 直写文件 -- 无时间戳、无轮转、无分级。而本项目的核心排查
+// 问题恰是「**什么时候**断线、断了多久、那个窗口丢了几条」,时间戳是唯一依据。
+const fs = require('fs')
+const path = require('path')
+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()
+  } catch {
+    return false
+  }
+}
+
+// 轮转阈值。默认 16MB。
+// ⚠️ 下界只防 0/负数/NaN,不能写 Math.max(1, MB) —— 那会把 0.001 这种
+// 小阈值抬成 1MB,测试就没法用小文件验轮转(踩过:930 字节都没触发)
+function envBytes() {
+  const mb = Number(process.env.LARK_RELAY_LOG_MAX_MB)
+  const v = Number.isFinite(mb) && mb > 0 ? mb : 16
+  return Math.max(1024, Math.round(v * 1024 * 1024))
+}
+const MAX_BYTES = envBytes()
+// 保留代数。⚠️ 必须 >1:实测只留 1 代时,高频写入会让第二次轮转覆盖第一次的 .1,
+// 中间整段永久丢失 -- 那正是加时间戳要回溯的东西,不能自拆台脚。
+const KEEP = (() => {
+  const n = Number(process.env.LARK_RELAY_LOG_KEEP)
+  return Number.isInteger(n) && n >= 1 ? n : 3
+})()
+
+let fd = null
+let target = null
+let size = 0
+let active = false
+
+// 拿 stderr 指向的真实路径。
+// ⚠️ 不能用 realpathSync('/dev/fd/2') —— macOS 实测**不解引用**,原样返回
+// '/dev/fd/2'(Linux 才解得开)。lsof 能拿到,但为写日志 spawn 外部进程太重。
+//
+// 正解:日志路径是我们自己在 plist 里定的约定路径,直接用它,再用 dev/ino
+// 核对「它确实就是 fd 2 指向的那个文件」-- 校验通过才接管,不匹配就退回直写。
+// 这样既不 spawn,也不会在别人自定义了 StandardErrorPath 时写错对象。
+//
+// LARK_RELAY_LOG_FILE 是显式指定的逃生舱(也是测试入口):给了就直接用,
+// 跳过 dev/ino 校验 -- 调用方明确知道自己要写哪儿。
+function resolveTarget() {
+  if (process.env.LARK_RELAY_LOG_FILE) return process.env.LARK_RELAY_LOG_FILE
+  const guess = path.join(paths.root, 'logs', 'collect.err.log')
+  try {
+    const a = fs.fstatSync(2)
+    const b = fs.statSync(guess)
+    if (a.dev === b.dev && a.ino === b.ino) return guess
+  } catch {}
+  return null
+}
+
+function open() {
+  fd = fs.openSync(target, 'a')
+  try {
+    size = fs.fstatSync(fd).size
+  } catch {
+    size = 0
+  }
+}
+
+// 轮转:KEEP=3 时 .2 -> .3、.1 -> .2、当前 -> .1,然后重开。
+// 必须由本进程 reopen -- launchd 持有 fd 2,外部 rename(newsyslog)后
+// 进程仍写旧 inode,日志看着「停了」。newsyslog 要配 SIGHUP 且是系统级配置,
+// 与「服务不绑代码目录」不自洽,故不用。
+function rotate() {
+  try {
+    if (fd !== null) fs.closeSync(fd)
+  } catch {}
+  // 先把带编号的整体后移(从大到小,避免覆盖),最旧的一代自然被 rename 挤掉。
+  // ⚠️ 编号档位是 .1 ~ .KEEP,循环必须到 1 为止(曾写成把当前文件直接
+  // rename 成 .2,导致 .1 永不存在 —— 实测文件跳号)
+  for (let i = KEEP - 1; i >= 1; i--) {
+    try {
+      if (fs.existsSync(`${target}.${i}`)) fs.renameSync(`${target}.${i}`, `${target}.${i + 1}`)
+    } catch {}
+  }
+  // 当前文件永远进 .1
+  try {
+    if (fs.existsSync(target)) fs.renameSync(target, `${target}.1`)
+  } catch {}
+  open()
+}
+
+function stamp() {
+  return new Date().toISOString()
+}
+
+function writeRaw(s) {
+  if (fd === null) return process.stderr.write(s)
+  const buf = Buffer.from(s)
+  if (size + buf.length > MAX_BYTES) rotate()
+  try {
+    fs.writeSync(fd, buf)
+    size += buf.length
+  } catch {
+    // 写失败不能让常驻进程崩 -- 日志是辅助,采集是本职
+    try {
+      process.stderr.write(s)
+    } catch {}
+  }
+}
+
+// 逐行加前缀。⚠️ 必须按 \n 拆分,不能只在整块前面拼一个时间戳:
+// 调用方存在单次 write 输出多行的情况(启动横幅 3 行、子进程转发的多行诊断),
+// 只给首行加前缀会让后续行无法归属到时间点,轮转/grep 时尤其致命。
+function logLine(text) {
+  const s = String(text)
+  if (!active) return void process.stderr.write(s.endsWith('\n') ? s : `${s}\n`)
+  const body = s.endsWith('\n') ? s.slice(0, -1) : s
+  const ts = stamp()
+  let out = ''
+  for (const line of body.split('\n')) out += `${ts} ${line}\n`
+  writeRaw(out)
+}
+
+// 常驻入口调一次。非 launchd 场景是 no-op,logLine 退化成裸 stderr 直写。
+function init() {
+  if (active) return active
+  // 显式指定优先于场景探测 -- 调用方明确要写文件时不该被 isFile 判据挡住
+  if (!process.env.LARK_RELAY_LOG_FILE && !stderrIsFile()) return false
+  target = resolveTarget()
+  if (!target) return false
+  try {
+    fs.mkdirSync(path.dirname(target), { recursive: true })
+    open()
+    active = true
+  } catch {
+    fd = null
+    active = false
+  }
+  return active
+}
+
+// 测试用:重置模块态。生产代码不该调
+function _reset() {
+  try {
+    if (fd !== null) fs.closeSync(fd)
+  } catch {}
+  fd = null
+  target = null
+  size = 0
+  active = false
+}
+
+module.exports = { init, logLine, stderrIsFile, _reset }