lark-relay 0.6.3 → 0.6.5

package/README.md

@@ -34,13 +34,15 @@ user 未登录或授权过期不影响 bot 采集,bot 凭据和权限由 `lark-c
 - `--app` 是 lark-cli profile 名,`--chats` 是逗号分隔的 chat_id 或 `@文件`(首列)
 - 监听要求 bot 已在群内,查群与验成员的完整命令见 `take --help`
 - `--name` 标识消费断点,默认按 app+chats 派生,并行消费使用不同名字
+- app 和消费名称不能含路径分隔符、控制字符、首尾空白或以点开头
 - `--filter` 是唯一业务过滤入口,使用 jq 表达式;语法错误在启动前拒绝
-- 消息数据导致 jq 求值失败时,该次扫描到的消息告警并放行,避免阻塞断点
+- jq 求值失败或输出不完整时中止取批,不输出消息、不提交待交付批次的断点;修正后可重取
+- 损坏的事件文件跳过并告警,不中止取批 —— 硬失败会把断点永久停在它前面
 - 默认防抖 5 秒,从第一条消息起最多攒 25 秒,本次取用总超时 12 小时
 - `--render` 支持 `ndjson`(默认)和按群/话题分组的 `text`
 - 参数校验完成后 stderr 输出「监听中」;未知参数、位置参数、缺值和空值均报错
 
-退出码:0=有一批/帮助/信号退出,2=参数错,3=消费身份被占用,4=超时无消息
+退出码:0=有一批/帮助/信号退出,1=读取/过滤等运行错误,2=参数错,3=消费身份被占用,4=超时无消息
 `--timeout 0` 立即扫描一次并返回,有消息仍会输出
 
 ## 断点与保留期
@@ -55,8 +57,13 @@ user 未登录或授权过期不影响 bot 采集,bot 凭据和权限由 `lark-c
 多消费者共享事件存储,各持独立断点
 已有断点始终续接,不按空闲时长过期;首次取用由 `--since now|all` 决定起点,默认 `now`
 需要从新的起点消费时使用新的 `--name`
+两种首次起点都会创建断点,没有事件时也可通过 `status` 查看等待中的消费者
+断点和事件文件读取失败时明确报错,不会当成首次消费或空数据继续推进
+损坏的事件文件不中止 `take`、采集或 `status`:三者都跳过它并告警,断点越过它继续。
+那几条消息永久丢失 —— `status` 标记该 app 并返回非零,复核后删除坏文件
 
 采集端 `--retain` 指定事件保留天数(默认 3 个自然日,含今天),启动时及每小时回收超期目录
+回收失败写入采集日志,排除文件系统错误后在下一轮重试
 断点只定位仍在盘上的消息,无法恢复已被回收的事件
 
 取批使用 at-most-once 交付:攒批期间只推进内存游标,交付前才提交磁盘断点
@@ -66,8 +73,10 @@ user 未登录或授权过期不影响 bot 采集,bot 凭据和权限由 `lark-c
 ## 存储取舍
 
 - 一事件一文件,同目录写临时文件后 rename,消费者只扫描完整事件文件
+- 写入失败时清理本次临时文件,原断点保持不变
 - 按日期及数值文件名排序;stamp 在采集进程内严格递增
-- 按 message_id 去重,启动时从当天文件恢复集合,跨天重置
+- 按 message_id 去重,进程启动或跨天后的首条消息前从当天文件恢复集合
+- 损坏文件在恢复去重时跳过并告警,其 message_id 不在集合内,该条重投会重复落盘
 - 每 500ms 扫描保留的全部日期,不引入额外扫描窗口
 - 参数由 Node 内置解析器处理,不兼容已移除的命令或参数
 
@@ -82,6 +91,8 @@ user 未登录或授权过期不影响 bot 采集,bot 凭据和权限由 `lark-c
 需要缩减日志时截断文件,不要删除或替换 launchd 持有的文件
 `status` 中 collect running 只说明主进程在跑,各 app 是否连接成功需查看采集日志
 `collect.profiles` 列出已配置 profile,不表示正在采集,也不反映 collect 的 `--exclude`
+profile 查询失败时 `status` 保留本地状态并以 exit 1 返回,错误见 `collect.profileError` 或文本输出
+某个 app 有损坏事件时同样以 exit 1 返回,错误见该 app 的 `error` 字段或文本中的 ⚠ 标记
 
 ## 许可
 

package/bin/lark-relay.js

@@ -41,6 +41,7 @@ async function cmdTake(argv) {
   const { validateFilter } = require('../lib/filter')
   const { render } = require('../lib/render')
   const { acquireExclusive } = require('../lib/lock')
+  const { namePart } = require('../lib/paths')
 
   if (!a.app) {
     process.stderr.write('需要 --app <name>,跑 `lark-relay take --help` 看用法\n')
@@ -52,6 +53,8 @@ async function cmdTake(argv) {
     return 2
   }
   const name = a.name ?? deriveName(a.app, chats)
+  namePart(a.app, '--app')
+  namePart(name, '--name')
   const since = a.since ?? 'now'
   const mode = a.render ?? 'ndjson'
   if (!['now', 'all'].includes(since)) {
@@ -78,8 +81,8 @@ async function cmdTake(argv) {
     process.stderr.write(`游标身份 "${name}" 被占用(pid ${lock.holder}),并行消费请换 --name\n`)
     return 3
   }
-  if (since === 'now' && store.readCursor(name, a.app) === null) {
-    store.seedCursorNow(name, a.app)
+  if (store.readCursor(name, a.app) === null) {
+    store.seedCursor(name, a.app, since)
   }
 
   const fmtDur = (ms) => (ms >= 3600000 ? `${ms / 3600000}h` : `${ms / 1000}s`)
@@ -101,6 +104,14 @@ async function cmdTake(argv) {
     timeoutMs,
     signal: ac.signal,
   })
+  // 跳过的坏文件必须显式说出来:它们是永久丢掉的消息,不是延迟送达。
+  // 退出码保持批次语义,否则调用方会把已交付的一批当成失败丢弃
+  if (res.skipped.length) {
+    process.stderr.write(
+      `warn: 跳过 ${res.skipped.length} 个损坏的事件文件,这些消息永久丢失:` +
+        `${res.skipped.join(' ')}\n  用 lark-relay status 复核,确认后删除坏文件\n`,
+    )
+  }
   if (!res.events.length) {
     process.stderr.write(`没等到消息(${res.reason}),再起一个继续\n`)
     return res.reason === 'timeout' ? 4 : 0
@@ -119,7 +130,8 @@ async function cmdStatus(argv) {
   const { buildStatus, formatStatus } = require('../lib/status')
   const s = await buildStatus()
   process.stdout.write(`${a.json ? JSON.stringify(s, null, 2) : formatStatus(s)}\n`)
-  return 0
+  // 输出完整,但异常仍以退出码透出,便于脚本发现
+  return s.collect.profileError || s.apps.some((r) => r.error) ? 1 : 0
 }
 
 // 自然排空 stdout,避免大批次经管道输出时被截断

package/lib/collect.js

@@ -19,9 +19,9 @@ class AppCollector {
     this.stopped = false
     this.backoffMs = 1000
     this.healthyTimer = null
-    // 启动时从当天落盘事件恢复去重集合
+    this.restartTimer = null
     this.day = dayKey()
-    this.seen = store.seedIds(app, this.day)
+    this.seen = null
   }
 
   // 收下一条:重复的丢弃,新的落盘。跨天时重置去重集(与 store 按天分目录同构)
@@ -29,7 +29,20 @@ class AppCollector {
     const today = dayKey()
     if (today !== this.day) {
       this.day = today
-      this.seen = new Set()
+      this.seen = null
+    }
+    // 首条消息前恢复当天去重;读不出的文件跳过,不阻断落盘
+    if (this.seen === null) {
+      const { ids, skipped } = store.seedIds(this.app, this.day)
+      this.seen = ids
+      // 跳过的文件其 message_id 不在集合内,那几条重投会重复落盘;
+      // 换来的是这个 app 继续采集,而不是每条消息都在 seed 上再失败一次
+      if (skipped.length) {
+        logLine(
+          `[${this.app}] warn: 恢复去重不完整,跳过 ${skipped.join(' ')};` +
+            `这些消息的 message_id 不在去重集合内,重投会重复落盘`,
+        )
+      }
     }
     const id = obj?.message_id
     if (id && this.seen.has(id)) return false
@@ -40,6 +53,7 @@ class AppCollector {
 
   start() {
     if (this.stopped) return
+    this.restartTimer = null
     const child = larkcli.spawnConsume(this.app, EVENT_KEY, ['--as', 'bot', '--timeout', '0'])
     this.child = child
 
@@ -88,7 +102,7 @@ class AppCollector {
           `—— 这段时间该 app 的消息会永久丢失`,
       )
       // 每 app 一个子进程;某个挂了单独重启,不影响其他
-      setTimeout(() => this.start(), this.backoffMs)
+      this.restartTimer = setTimeout(() => this.start(), this.backoffMs)
       this.backoffMs = Math.min(this.backoffMs * 2, 60_000)
     }
 
@@ -105,6 +119,7 @@ class AppCollector {
   stop() {
     this.stopped = true
     clearTimeout(this.healthyTimer)
+    clearTimeout(this.restartTimer)
     // 优雅停止:SIGTERM。禁 SIGKILL —— 否则漏卸载服务端订阅
     if (this.child) this.child.kill('SIGTERM')
   }

package/lib/filter.js

@@ -35,22 +35,12 @@ function applyFilter(events, expr) {
       maxBuffer: 64 * 1024 * 1024,
     })
   } catch (err) {
-    // 数据导致的求值错误保守放行,避免同一条消息卡住消费
-    process.stderr.write(
-      `warn: --filter 求值失败,本批不过滤(${events.length} 条放行)。表达式:${expr}\n` +
-        `      ${(err.stderr || err.message || '').trim().split('\n')[0]}\n` +
-        `      提示:字段可能不存在,用 ? 和 // 兜底,如 '(.mentions // []) | any(.id == "ou_xxx")'\n`,
-    )
-    return events
+    const reason = (err.stderr || err.message).trim().split('\n')[0]
+    throw Object.assign(new Error(`--filter 求值失败:${reason}`), { userFacing: true })
   }
   const verdicts = out.split('\n').filter((l) => l.length > 0)
-  // 求值行数应与事件数一致;不一致说明表达式产出多值,保守放行全部并 warn
-  if (verdicts.length !== events.length) {
-    process.stderr.write(
-      `warn: --filter 产出 ${verdicts.length} 个结果但有 ${events.length} 条事件,` +
-        `本批不过滤。表达式应对每条事件求出单个布尔值\n`,
-    )
-    return events
+  if (verdicts.length !== events.length || verdicts.some((v) => v !== 'true' && v !== 'false')) {
+    throw Object.assign(new Error('--filter 必须为每条事件返回一个布尔结果'), { userFacing: true })
   }
   return events.filter((_, i) => verdicts[i] === 'true')
 }

package/lib/help.js

@@ -29,8 +29,11 @@ const TAKE_HELP = `需要 --app 和 --chats,监听要求 bot 已在群内
 
 断点持续保留,不随空闲时间过期;store 只保留采集端设定天数的消息
 使用新的 --name 可从新的起点消费
+app 和消费名称不能含路径分隔符、控制字符、首尾空白或以点开头
+过滤失败时中止取批并保留待交付批次的断点,修正后可重取
+损坏的事件文件跳过并在 stderr 告警,断点越过它继续 —— 那几条消息永久丢失
 
-退出码:0=有一批/帮助/信号退出,2=参数错,3=身份被占用,4=超时无消息`
+退出码:0=有一批/帮助/信号退出,1=运行错误,2=参数错,3=身份被占用,4=超时无消息`
 
 const COLLECT_HELP = `lark-relay-collect -- 常驻收集 im.message.receive_v1 消息并原子落盘
 
@@ -65,7 +68,10 @@ const STATUS_HELP = `lark-relay status -- 采集状态、事件数量和消费
   lark-relay status --json
 
 消费者以持锁进程是否存活区分在跑/未运行,未运行的断点仍保留
+首次 --since all 等待中也会保留起始断点
 profiles 列出已配置项,不表示正在采集,也不反映 collect 的 --exclude
+profile 查询失败时保留本地状态并以 exit 1 返回,错误见 collect.profileError
+扫描全部保留日期,任意位置的损坏事件都标记 ⚠ 并以 exit 1 返回,其余 app 照常显示
 collect running 只表示主进程在跑,各 app 的连接状态需查看采集日志`
 
 module.exports = { TAKE_HELP, COLLECT_HELP, STATUS_HELP }

package/lib/larkcli.js

@@ -2,6 +2,7 @@
 
 // 唯一外部依赖:spawn lark-cli,通过公开命令读取配置
 const { spawn, execFile } = require('child_process')
+const { namePart } = require('./paths')
 
 const CLI = process.env.LARK_CLI_BIN || 'lark-cli'
 
@@ -26,7 +27,7 @@ function run(args, opts = {}) {
 // 只枚举配置;bot 认证和权限由 event consume --as bot 检查
 async function listProfiles() {
   const { stdout } = await run(['profile', 'list'])
-  return JSON.parse(stdout).map((p) => p.name)
+  return JSON.parse(stdout).map((p) => namePart(p.name, 'profile name'))
 }
 
 // 保持 stdin 管道打开,stdout NDJSON 由 collect 原子写入

package/lib/lock.js

@@ -4,7 +4,7 @@
 // mkdir 与写 pid 之间的空目录保守拒绝,避免抢走正在初始化的锁
 const fs = require('fs')
 const path = require('path')
-const { paths, ensureDir } = require('./paths')
+const { paths, ensureDir, namePart } = require('./paths')
 
 function acquireExclusive(key) {
   const dir = lockPathFor(key)
@@ -15,23 +15,24 @@ function acquireExclusive(key) {
   for (let attempt = 0; attempt < 2; attempt++) {
     try {
       fs.mkdirSync(dir) // 非 recursive:已存在就抛 EEXIST
-      fs.writeFileSync(pidFile, me)
-      return mkHandle(dir, pidFile, me)
     } catch (err) {
       if (err.code !== 'EEXIST') throw err
+      const holder = readPid(pidFile)
+      if (holder === process.pid) return mkHandle(dir, pidFile, me)
+      // 空目录可能正处于写 PID 的窗口,只接管已知持有者死亡的锁
+      if (holder === null || alive(holder)) return { ok: false, file: dir, holder }
+      fs.rmSync(dir, { recursive: true, force: true })
+      continue
     }
-
-    const holder = readPid(pidFile)
-    if (holder === process.pid) return mkHandle(dir, pidFile, me) // 自己已持有,复用
-    if (holder === null) {
-      // 无法区分初始化中的锁与崩溃留下的空壳,需确认持有者后处理
-      return { ok: false, file: dir, holder: null }
-    }
-    if (holder && alive(holder)) return { ok: false, file: dir, holder }
-    // 持有者已死:清掉重试一次
     try {
-      fs.rmSync(dir, { recursive: true, force: true })
-    } catch {}
+      fs.writeFileSync(pidFile, me)
+    } catch (err) {
+      try { fs.rmSync(dir, { recursive: true, force: true }) } catch (cleanup) {
+        err.message += `; 清理未完成的锁失败:${cleanup.message}`
+      }
+      throw err
+    }
+    return mkHandle(dir, pidFile, me)
   }
   return { ok: false, file: dir, holder: readPid(pidFile) }
 }
@@ -46,7 +47,9 @@ function mkHandle(dir, pidFile, me) {
       if (fs.readFileSync(pidFile, 'utf8').trim() === me) {
         fs.rmSync(dir, { recursive: true, force: true })
       }
-    } catch {}
+    } catch (err) {
+      if (err.code !== 'ENOENT') process.stderr.write(`释放锁失败:${err.message}\n`)
+    }
   }
   // 注:SIGKILL 不跑 exit 钩子 -> 留下陈旧锁,靠上面的死进程检测清理
   process.once('exit', release)
@@ -57,8 +60,9 @@ function readPid(file) {
   try {
     const n = Number(fs.readFileSync(file, 'utf8').trim())
     return Number.isInteger(n) && n > 0 ? n : null
-  } catch {
-    return null
+  } catch (err) {
+    if (err.code === 'ENOENT') return null
+    throw err
   }
 }
 
@@ -71,10 +75,9 @@ function alive(pid) {
   }
 }
 
-// 锁目录位置。**外部判活必须走这个函数**:sanitize 会把非 [A-Za-z0-9._-] 换成 `_`,
-// 自己拼路径会让含特殊字符的 key 匹配不上
+// 与数据目录使用相同的名称,不重写字符造成身份碰撞
 function lockPathFor(key) {
-  return path.join(paths.run, `${String(key).replace(/[^A-Za-z0-9._-]/g, '_')}.lock`)
+  return path.join(paths.run, `${namePart(key, 'lock name')}.lock`)
 }
 
 // 谁持有这把锁(活着才算)。与抢锁时的判活口径完全一致
@@ -84,4 +87,4 @@ function holderPid(key) {
   return alive(pid) ? pid : null
 }
 
-module.exports = { acquireExclusive, lockPathFor, holderPid }
+module.exports = { acquireExclusive, holderPid }

package/lib/paths.js

@@ -1,6 +1,6 @@
 'use strict'
 
-// 运行态路径与目录布局。判据:能随时删掉重建的东西才放这里。
+// 本地事件与消费断点的路径,删除后无法恢复已回收或离线的消息
 const os = require('os')
 const path = require('path')
 const fs = require('fs')
@@ -14,26 +14,41 @@ const paths = {
   run: path.join(ROOT, 'run'),
 
   appDay(app, day) {
-    return path.join(ROOT, 'store', app, day)
+    return path.join(ROOT, 'store', namePart(app, 'app'), day)
   },
   appStore(app) {
-    return path.join(ROOT, 'store', app)
+    return path.join(ROOT, 'store', namePart(app, 'app'))
   },
   cursor(name, app) {
-    return path.join(ROOT, 'cursors', name, app)
+    return path.join(ROOT, 'cursors', namePart(name, 'name'), namePart(app, 'app'))
   },
 }
 
+function namePart(value, label) {
+  if (typeof value !== 'string' || !value || value !== value.trim() ||
+      value.startsWith('.') || /[\\/\x00-\x1f\x7f]/.test(value)) {
+    throw Object.assign(new Error(`${label} 需要普通名称,不能含路径分隔符、控制字符、首尾空白或以点开头`), {
+      userFacing: true, exitCode: 2,
+    })
+  }
+  return value
+}
+
 function ensureDir(dir) {
   fs.mkdirSync(dir, { recursive: true })
   return dir
 }
 
-// 事件文件名 <stamp>_<pid>_<seq>.json -- stamp 前缀让字典序 == 写入序,
-// pid+seq 保证同一 stamp 内多进程/多事件不撞名。
-//
-// ⚠️ stamp 必须**严格单调递增**,否则游标会跨过后写的事件 -> 永久丢消息。
-// 墙上时间只作下界,计数器保证单调。见 docs/lessons.md#单调-stamp
+function readDir(dir, options) {
+  try {
+    return fs.readdirSync(dir, options)
+  } catch (err) {
+    if (err.code === 'ENOENT') return []
+    throw err
+  }
+}
+
+// stamp 在进程内严格单调,文件名按 stamp/pid/seq 数值排序
 let lastStamp = 0n
 
 function eventFilename(seq) {
@@ -57,4 +72,4 @@ function dayKeyOffset(days) {
   return dayKey(t)
 }
 
-module.exports = { paths, ensureDir, eventFilename, dayKey, dayKeyOffset }
+module.exports = { paths, namePart, ensureDir, readDir, eventFilename, dayKey, dayKeyOffset }

package/lib/render.js

@@ -8,30 +8,12 @@ function fmtTime(ts) {
   return `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`
 }
 
+// 事件体里没有发送者姓名:mentions 只装被 @ 的人,实测 861 条真实事件
+// 无一条把 sender_id 收进 mentions。要姓名需另查通讯录,不在渲染层做
 function senderLabel(e) {
-  const mention = (e.mentions || []).find((m) => m && m.id === e.sender_id)
-  if (mention && mention.name) return mention.name
   return e.sender_id || 'unknown'
 }
 
-// 文本正文:content 可能是字符串,也可能是 lark 原始的 JSON 字符串
-function bodyOf(e) {
-  if (typeof e.content === 'string') {
-    const s = e.content.trim()
-    if (s.startsWith('{')) {
-      try {
-        const j = JSON.parse(s)
-        if (typeof j.text === 'string') return j.text
-      } catch {}
-    }
-    return e.content
-  }
-  if (e.content && typeof e.content === 'object' && typeof e.content.text === 'string') {
-    return e.content.text
-  }
-  return e.content == null ? '' : String(e.content)
-}
-
 function renderNdjson(events) {
   return events.map((e) => JSON.stringify(e)).join('\n')
 }
@@ -54,7 +36,7 @@ function renderText(events) {
     for (const e of list) {
       const line = [`[${fmtTime(e.create_time)}]`, senderLabel(e)]
       if (e.message_type && e.message_type !== 'text') line.push(`<${e.message_type}>`)
-      out.push(`${line.join(' ')}: ${bodyOf(e)}`)
+      out.push(`${line.join(' ')}: ${e.content ?? ''}`)
       const meta = []
       meta.push(`message_id=${e.message_id || '?'}`)
       meta.push(`sender_id=${e.sender_id || '?'}`)
@@ -79,4 +61,4 @@ function render(events, mode) {
   return renderNdjson(events)
 }
 
-module.exports = { render, renderText }
+module.exports = { render }

package/lib/status.js

@@ -2,11 +2,10 @@
 
 // status:一眼看清全局 —— 谁在跑、各 app 收了多少、游标在哪。
 const { execFileSync } = require('child_process')
-const fs = require('fs')
 const path = require('path')
 const store = require('./store')
 const larkcli = require('./larkcli')
-const { paths } = require('./paths')
+const { paths, readDir } = require('./paths')
 const { holderPid } = require('./lock')
 
 function ago(ms) {
@@ -32,32 +31,22 @@ function serviceState() {
     const pid = Number((out.match(/^\s*pid\s*=\s*(\d+)/m) || [])[1]) || null
     const s = (state || '').trim()
     return { state: s === 'running' ? 'active' : s || 'inactive', pid }
-  } catch {
-    return { state: 'inactive', pid: null }
+  } catch (err) {
+    if (err.status === 113) return { state: 'inactive', pid: null }
+    throw err
   }
 }
 
 // 枚举游标:cursors/<name>/<app>。活消费者判定复用 take 的锁,不另造注册表
 function listCursors() {
-  let names
-  try {
-    names = fs.readdirSync(paths.cursors).filter((n) => !n.startsWith('.'))
-  } catch {
-    return []
-  }
+  const names = readDir(paths.cursors, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && !e.name.startsWith('.')).map((e) => e.name)
   const out = []
   for (const name of names.sort()) {
     const dir = path.join(paths.cursors, name)
-    let files
-    try {
-      if (!fs.statSync(dir).isDirectory()) continue
-      files = fs.readdirSync(dir)
-    } catch {
-      continue
-    }
+    const files = readDir(dir).filter((app) => !app.startsWith('.'))
     const pid = holderPid(`take-${name}`)
     for (const app of files.sort()) {
-      if (app.startsWith('.') || app.endsWith('.tmp')) continue
       const cursor = store.readCursor(name, app)
       if (!cursor) continue
       out.push({ name, app, cursor, pid })
@@ -70,23 +59,41 @@ async function buildStatus() {
   const { state, pid } = serviceState()
 
   let profiles = []
+  let profileError = null
   try {
     profiles = await larkcli.listProfiles()
-  } catch {}
+  } catch (err) {
+    profileError = `读取 profile 失败:${err.message.split('\n')[0]}`
+  }
   const byApp = new Map()
   for (const c of listCursors()) {
     if (!byApp.has(c.app)) byApp.set(c.app, [])
     byApp.get(c.app).push(c)
   }
 
-  const apps = [...new Set([...store.listApps(), ...profiles])].sort()
+  const apps = [...new Set([...store.listApps(), ...profiles, ...byApp.keys()])].sort()
   const rows = apps.map((app) => {
-    const latest = store.latestEntry(app)
-    const ev = latest ? store.readEvent(latest) : null
+    // 扫全量:坏文件不在最新位置时同样要报出来 —— take 会跳过它,
+    // 而 status 是唯一的排障入口。实测本机 905 个事件全读约 23ms
+    const corrupt = []
+    let latestMs = null
+    for (const entry of store.scanAll(app)) {
+      let ev
+      try {
+        ev = store.readEvent(entry)
+      } catch (err) {
+        if (!err.corrupt) throw err
+        corrupt.push(`${entry.day}/${entry.name}`)
+        continue
+      }
+      // 最新时间取最后一条读得出的事件,坏文件不该让它变成「—」
+      if (ev) latestMs = Number(ev.timestamp) || latestMs
+    }
     return {
       app,
       today: store.countToday(app),
-      latestMs: Number(ev?.timestamp) || null,
+      latestMs,
+      error: corrupt.length ? `${corrupt.length} 个事件文件损坏:${corrupt.join(' ')}` : null,
       consumers: byApp.get(app) || [],
     }
   })
@@ -96,6 +103,7 @@ async function buildStatus() {
       state,
       pid,
       profiles,
+      profileError,
       hint: `sudo launchctl bootstrap system /Library/LaunchDaemons/${COLLECT_LABEL}.plist`,
     },
     apps: rows,
@@ -123,6 +131,7 @@ function formatStatus(s) {
   if (s.collect.profiles.length) bits.push(`${s.collect.profiles.length} configured profiles`)
   if (bits.length) head += ` (${bits.join(', ')})`
   out.push(head)
+  if (s.collect.profileError) out.push(`  error: ${s.collect.profileError}`)
   if (s.collect.state !== 'active') {
     out.push('  ⚠ collect 没在跑 —— 此刻的消息会永久丢失,不是延迟送达')
     out.push(`    ${s.collect.hint}`)
@@ -133,14 +142,16 @@ function formatStatus(s) {
   for (const r of s.apps) {
     if (!r.consumers.length) {
       out.push(`${w(r.app, 8)}${w(r.today, 10)}${w(ago(r.latestMs), 13)}—(无消费者)`)
-      continue
-    }
-    // 消费者各占一行:「谁在跑」是排障第一问,挤在一行里 ●/○ 会被淹掉
-    out.push(`${w(r.app, 8)}${w(r.today, 10)}${w(ago(r.latestMs), 13)}`.trimEnd())
-    for (const c of r.consumers) {
-      const note = c.pid ? `在跑 (pid ${c.pid})` : '未运行 (断点保留)'
-      out.push(`  ${w(c.name, 24)}${c.pid ? '●' : '○'} ${note}`)
+    } else {
+      // 消费者各占一行:「谁在跑」是排障第一问,挤在一行里 ●/○ 会被淹掉
+      out.push(`${w(r.app, 8)}${w(r.today, 10)}${w(ago(r.latestMs), 13)}`.trimEnd())
+      for (const c of r.consumers) {
+        const note = c.pid ? `在跑 (pid ${c.pid})` : '未运行 (断点保留)'
+        out.push(`  ${w(c.name, 24)}${c.pid ? '●' : '○'} ${note}`)
+      }
     }
+    // 坏文件会让该 app 的采集跳过去重、take 直接失败,必须显式暴露
+    if (r.error) out.push(`  ⚠ ${r.error}`)
   }
   out.push('')
   out.push(

package/lib/store.js

@@ -3,34 +3,44 @@
 // 多消费者共享按天存储的事件,各持消费断点;GC 只回收事件目录
 const fs = require('fs')
 const path = require('path')
-const { paths, ensureDir, eventFilename, dayKey, dayKeyOffset } = require('./paths')
+const { paths, ensureDir, readDir, eventFilename, dayKey, dayKeyOffset } = require('./paths')
 
 const DAY_RE = /^\d{4}-\d{2}-\d{2}$/
 
+function writeAtomic(file, text) {
+  ensureDir(path.dirname(file))
+  const tmp = path.join(path.dirname(file), `.${path.basename(file)}.tmp`)
+  try {
+    fs.writeFileSync(tmp, text)
+    fs.renameSync(tmp, file)
+  } catch (err) {
+    try { fs.unlinkSync(tmp) } catch (cleanup) {
+      if (cleanup.code !== 'ENOENT') err.message += `; 清理临时文件失败:${cleanup.message}`
+    }
+    throw err
+  }
+}
+
 // 原子落盘:同目录 写 .tmp -> rename。不用 lark-cli --output-dir(非原子)
 function writeEvent(app, obj, seq) {
   const day = dayKey()
-  const dir = ensureDir(paths.appDay(app, day))
   const name = eventFilename(seq)
-  const tmp = path.join(dir, `.${name}.tmp`)
-  const dest = path.join(dir, name)
-  fs.writeFileSync(tmp, JSON.stringify(obj))
-  fs.renameSync(tmp, dest)
+  const dest = path.join(paths.appDay(app, day), name)
+  writeAtomic(dest, JSON.stringify(obj))
   return { day, name, file: dest }
 }
 
 // 排序键:stamp -> pid -> seq,数值比较(字典序在位宽变化时会错序)。
-const NAME_RE = /^(\d+)_(\d+)_(\d+)$/
+const NAME_RE = /^(\d+)_(\d+)_(\d+)\.json$/
 
 function parseKey(name) {
-  const base = name.endsWith('.json') ? name.slice(0, -5) : name
-  const m = NAME_RE.exec(base)
-  if (!m) return { stamp: 0n, pid: 0, seq: 0, valid: false }
-  return { stamp: BigInt(m[1]), pid: Number(m[2]), seq: Number(m[3]), valid: true }
+  const m = NAME_RE.exec(name)
+  if (!m) throw new Error(`事件文件名无效:${name}`)
+  return { stamp: BigInt(m[1]), pid: Number(m[2]), seq: Number(m[3]) }
 }
 
 function isEventName(name) {
-  return name.endsWith('.json') && NAME_RE.test(name.slice(0, -5))
+  return NAME_RE.test(name)
 }
 
 function cmpName(a, b) {
@@ -61,21 +71,9 @@ function afterCursor(entry, cursor) {
 // 扫描盘上保留的全部日期
 function scanAll(app) {
   const out = []
-  let days
-  try {
-    days = fs.readdirSync(paths.appStore(app))
-  } catch {
-    return out
-  }
-  for (const day of days) {
+  for (const day of readDir(paths.appStore(app))) {
     if (!DAY_RE.test(day)) continue
-    let names
-    try {
-      names = fs.readdirSync(paths.appDay(app, day))
-    } catch {
-      continue
-    }
-    for (const name of names) {
+    for (const name of readDir(paths.appDay(app, day))) {
       if (!isEventName(name)) continue // 跳过 .tmp、隐藏文件、手工放进来的杂项
       out.push({ app, day, name, file: path.join(paths.appDay(app, day), name) })
     }
@@ -85,64 +83,88 @@ function scanAll(app) {
 }
 
 function readEvent(entry) {
+  let raw
   try {
-    const raw = fs.readFileSync(entry.file, 'utf8')
-    if (!raw) return null
-    return JSON.parse(raw)
-  } catch {
-    return null // 半成品或坏文件:跳过,不让一条坏数据卡死消费
+    raw = fs.readFileSync(entry.file, 'utf8')
+  } catch (err) {
+    if (err.code === 'ENOENT') return null // 扫描后可能被 GC 回收
+    throw err
+  }
+  try {
+    const event = JSON.parse(raw)
+    if (!event || typeof event !== 'object' || Array.isArray(event)) throw new Error('需要 JSON 对象')
+    return event
+  } catch (err) {
+    // corrupt:盘上数据坏了,重试不会好转。与 EACCES 等瞬时错误区分开,
+    // 让只读概览和采集能跳过单个坏文件继续跑;take 仍然硬失败
+    throw Object.assign(new Error(`事件文件损坏:${entry.file}: ${err.message}`), {
+      userFacing: true, corrupt: true,
+    })
   }
 }
 
-// 重启后从当天事件恢复 message_id 去重集合
+// 重启后从当天事件恢复 message_id 去重集合。
+// 去重是尽力而为的优化,不是落盘的前置条件:任何读不出的文件都跳过并回报,
+// 最坏结果是那几条重投时重复落盘,比为它们丢掉后续所有消息轻得多
 function seedIds(app, day = dayKey()) {
   const ids = new Set()
+  const skipped = []
+  const dir = paths.appDay(app, day)
   let names
   try {
-    names = fs.readdirSync(paths.appDay(app, day))
-  } catch {
-    return ids
+    names = readDir(dir) // ENOENT 已按空目录处理,这里兜的是 EACCES 等
+  } catch (err) {
+    return { ids, skipped: [`整个目录读不出(${err.code || err.message})`] }
   }
   for (const name of names) {
     if (!isEventName(name)) continue
-    const ev = readEvent({ file: path.join(paths.appDay(app, day), name) })
-    const id = ev?.message_id
-    if (id) ids.add(id)
+    try {
+      const ev = readEvent({ file: path.join(dir, name) })
+      if (ev?.message_id) ids.add(ev.message_id)
+    } catch {
+      skipped.push(name)
+    }
   }
-  return ids
+  return { ids, skipped }
 }
 
 function readCursor(name, app) {
+  const file = paths.cursor(name, app)
+  let raw
   try {
-    const raw = fs.readFileSync(paths.cursor(name, app), 'utf8').trim()
-    return raw || null
-  } catch {
-    return null
+    raw = fs.readFileSync(file, 'utf8').trim()
+  } catch (err) {
+    if (err.code === 'ENOENT') return null
+    throw err
+  }
+  checkCursor(raw, file)
+  return raw
+}
+
+function checkCursor(key, file) {
+  const [day, name, extra] = String(key).split('/')
+  const time = Date.parse(day)
+  if (!DAY_RE.test(day) || !Number.isFinite(time) || new Date(time).toISOString().slice(0, 10) !== day ||
+      !isEventName(name) || extra !== undefined) {
+    throw Object.assign(new Error(`断点格式无效:${file}`), { userFacing: true })
   }
 }
 
 function writeCursor(name, app, key) {
   const file = paths.cursor(name, app)
-  ensureDir(path.dirname(file))
-  const tmp = `${file}.tmp`
-  fs.writeFileSync(tmp, key)
-  fs.renameSync(tmp, file)
+  checkCursor(key, file)
+  writeAtomic(file, key)
 }
 
-// --since now:游标落到当前最新,不重放历史
-function seedCursorNow(name, app) {
-  const all = scanAll(app)
-  if (all.length) writeCursor(name, app, entryKey(all[all.length - 1]))
-  else writeCursor(name, app, `${dayKey()}/0_0_0.json`)
+// 两种起点都落盘,空闲消费者也能通过断点与锁显示在 status 中
+function seedCursor(name, app, since) {
+  const latest = since === 'now' ? latestEntry(app) : null
+  const startDay = since === 'now' ? dayKey() : '0000-01-01'
+  writeCursor(name, app, latest ? entryKey(latest) : `${startDay}/0_0_0.json`)
 }
 
 function countToday(app) {
-  const dir = paths.appDay(app, dayKey())
-  try {
-    return fs.readdirSync(dir).filter(isEventName).length
-  } catch {
-    return 0
-  }
+  return readDir(paths.appDay(app, dayKey())).filter(isEventName).length
 }
 
 function latestEntry(app) {
@@ -151,11 +173,8 @@ function latestEntry(app) {
 }
 
 function listApps() {
-  try {
-    return fs.readdirSync(paths.store).filter((n) => !n.startsWith('.')).sort()
-  } catch {
-    return []
-  }
+  return readDir(paths.store, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && !e.name.startsWith('.')).map((e) => e.name).sort()
 }
 
 // gc:删超期的整个日期目录
@@ -164,19 +183,11 @@ function gcStore(retainDays) {
   for (let i = 0; i < retainDays; i++) keep.add(dayKeyOffset(-i))
   const removed = []
   for (const app of listApps()) {
-    let days
-    try {
-      days = fs.readdirSync(paths.appStore(app))
-    } catch {
-      continue
-    }
-    for (const day of days) {
+    for (const day of readDir(paths.appStore(app))) {
       if (!DAY_RE.test(day)) continue
       if (keep.has(day)) continue
-      try {
-        fs.rmSync(path.join(paths.appStore(app), day), { recursive: true, force: true })
-        removed.push(`${app}/${day}`)
-      } catch {}
+      fs.rmSync(path.join(paths.appStore(app), day), { recursive: true, force: true })
+      removed.push(`${app}/${day}`)
     }
   }
   return removed
@@ -189,13 +200,11 @@ module.exports = {
   seedIds,
   readCursor,
   writeCursor,
-  seedCursorNow,
+  seedCursor,
   afterCursor,
   entryKey,
-  cmpEntry,
   cmpName,
   countToday,
-  latestEntry,
   listApps,
   gcStore,
 }

package/lib/take.js

@@ -46,8 +46,9 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
 
 /**
  * 阻塞等一批事件。
- * @returns {Promise<{events:array, reason:string, cursor:string|null}>}
+ * @returns {Promise<{events:array, reason:string, cursor:string|null, skipped:string[]}>}
  *   reason: batch | timeout | signal
+ *   skipped: 跳过的损坏事件文件名,调用方负责告警
  */
 async function takeBatch(opts) {
   const {
@@ -65,6 +66,7 @@ async function takeBatch(opts) {
   const chatSet = new Set(chats)
   const startedAt = Date.now()
   const batch = []
+  const skipped = []
   let firstAt = null
   let lastNewAt = null
   let cursor = store.readCursor(name, app)
@@ -73,15 +75,24 @@ async function takeBatch(opts) {
     // 信号退出也交付已攒的批次,提交时机与正常退出一致
     if (signal && signal.aborted) {
       if (batch.length && cursor) store.writeCursor(name, app, cursor)
-      return { events: batch, reason: batch.length ? 'batch' : 'signal', cursor }
+      return { events: batch, reason: batch.length ? 'batch' : 'signal', cursor, skipped }
     }
 
     const entries = store.scanAll(app).filter((e) => store.afterCursor(e, cursor))
     const fresh = []
     for (const entry of entries) {
       cursor = store.entryKey(entry)
-      const ev = store.readEvent(entry)
-      if (!ev) continue // 半成品/坏文件:跳过
+      let ev
+      try {
+        ev = store.readEvent(entry)
+      } catch (err) {
+        // 损坏是永久错误:硬失败会让断点停在它前面,把它之后的好消息也永久取不到。
+        // 跳过并推进,损失是这一条;由调用方告警,status 也会标记它
+        if (!err.corrupt) throw err
+        skipped.push(`${entry.day}/${entry.name}`)
+        continue
+      }
+      if (!ev) continue // 扫描后已被 GC 回收
       if (ev.type !== 'im.message.receive_v1') continue
       if (chatSet.size && !chatSet.has(ev.chat_id)) continue
       fresh.push(ev)
@@ -108,13 +119,13 @@ async function takeBatch(opts) {
       if (quiet || capped) {
         // at-most-once:交付前提交,不等待业务处理确认
         if (cursor) store.writeCursor(name, app, cursor)
-        return { events: batch, reason: 'batch', cursor }
+        return { events: batch, reason: 'batch', cursor, skipped }
       }
     }
 
     if (Date.now() - startedAt >= timeoutMs) {
       if (batch.length && cursor) store.writeCursor(name, app, cursor)
-      return { events: batch, reason: batch.length ? 'batch' : 'timeout', cursor }
+      return { events: batch, reason: batch.length ? 'batch' : 'timeout', cursor, skipped }
     }
 
     await sleep(pollMs)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lark-relay",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "Lark event relay: collect events to disk, take a batch when you need it.",
   "keywords": [
     "lark",