lark-relay 0.4.11 → 0.4.13

package/bin/lark-relay.js

@@ -13,7 +13,7 @@ const VERSION = require('../package.json').version
 // --chat-id 拼错 -> 打印用法退出,看着像「正常退出但没消息」,漏看 bot 第一条 Working
 const TAKE_KEYS = ['app', 'chats', 'name', 'filter', 'debounce', 'max-wait', 'timeout', 'render', 'since']
 
-const COMMANDS = ['take', 'status', 'guide']
+const COMMANDS = ['take', 'status', 'cursors', 'guide']
 
 // collect 搬家提示。能力是**搬走了不是删了**,所以不能只说「未知命令」
 const MOVED_HINT =
@@ -26,6 +26,7 @@ const USAGE = `lark-relay ${VERSION} -- Lark 事件中继站(在场取用)
 
   lark-relay take ...           在场取用:阻塞等一批 -> 输出 -> 退出
   lark-relay status             谁在跑 / 各 app 积压 / 各游标位置
+  lark-relay cursors            游标治理:看谁还在值守 / --prune 清失效的
   lark-relay guide              一页用法(装完先读这个)
 
 采集底座是独立命令(常驻服务):lark-relay-collect
@@ -55,6 +56,8 @@ async function main() {
       return await cmdTake(rest)
     case 'status':
       return await cmdStatus(rest)
+    case 'cursors':
+      return cmdCursors(rest)
     // collect 拆成了独立可执行文件,这里专门拦一下告诉人改敲什么。
     // 不能落到 default 分支:suggest('collect', ['take','status','guide']) 必然返回
     // null(编辑距离都 >2、前缀 coll 也不匹配),只会打出干巴巴的「未知命令:collect」--
@@ -137,8 +140,30 @@ async function cmdTake(argv) {
     process.stderr.write(`--since 只能是 now 或 all,当前:${since}\n`)
     return 2
   }
-  if (since === 'now' && store.readCursor(name, a.app) === null) {
-    store.seedCursorNow(name, a.app) // 默认不重放历史,消灭「预热游标」这一步
+  // 游标初始化 / 自愈。两种情况都落到「按 --since now 重新起头」:
+  //   ① 没有游标 —— 首次跑,消灭旧架构「预热游标」那一步
+  //   ② 游标已 stale —— 位置超出扫描窗口,那段消息 collect 的 gc 已经整目录删了。
+  //      续接它和 seed now **行为完全一样**(scanWindow 扫不到那些日期),
+  //      但留着会让 status 一直虚报积压。所以当场自愈,并说清楚发生了什么。
+  // ⚠️ 只动自己这一个游标,不碰别人的 —— 自愈的边界就在这里。
+  // ⚠️ --since all 时不自愈:用户显式要全量重放,尊重它
+  if (since === 'now') {
+    const existing = store.readCursor(name, a.app)
+    if (existing === null) {
+      store.seedCursorNow(name, a.app)
+    } else {
+      const { cursorDay, isStaleDay, oldestScannedDay } = require('../lib/cursors')
+      const day = cursorDay(existing)
+      if (isStaleDay(day)) {
+        // 说明行必须打在「监听中」**之前** —— 那一行是约定的启动信号
+        // (「没这行就是没起来」),不能被别的输出插到中间
+        process.stderr.write(
+          `游标 ${name} 停在 ${day},已超扫描窗口(最早 ${oldestScannedDay()})\n` +
+            `-> 那段消息已被 gc 回收,按 --since now 重新起头\n`,
+        )
+        store.seedCursorNow(name, a.app)
+      }
+    }
   }
 
   // 时长参数校验:负数/非数字过去会静默退回默认值或原样生效
@@ -192,6 +217,68 @@ async function cmdTake(argv) {
   return 0
 }
 
+function cmdCursors(argv) {
+  const CURSORS_FLAGS = ['prune', 'json', 'help']
+  const a = parseArgs(argv, { flags: CURSORS_FLAGS, keys: [] })
+  if (a._unknown.length) return rejectUnknown('lark-relay cursors', argv, a._unknown, CURSORS_FLAGS)
+  if (a.help) {
+    process.stdout.write(`${help.CURSORS_HELP}\n`)
+    return 0
+  }
+  const cursors = require('../lib/cursors')
+
+  // 只读模式:列清单。默认不删任何东西 —— 删数据必须显式 --prune
+  if (!a.prune) {
+    const rows = cursors.listCursors()
+    if (a.json) {
+      process.stdout.write(`${JSON.stringify(rows, null, 2)}\n`)
+      return 0
+    }
+    if (!rows.length) {
+      process.stdout.write('没有游标(还没跑过 take,或已全部清理)\n')
+      return 0
+    }
+    const mark = { live: '●', idle: '○', stale: '⚠' }
+    const note = {
+      live: (r) => `在跑 (pid ${r.pid})`,
+      idle: () => '暂停,可续接',
+      stale: () => '超扫描窗口,续接取不到东西 -> 可清理',
+    }
+    for (const r of rows) {
+      process.stdout.write(
+        `${mark[r.state]} ${r.name}  app=${r.app}  位置=${r.day}  ${note[r.state](r)}\n`,
+      )
+    }
+    const stale = rows.filter((r) => r.state === 'stale').length
+    if (stale) process.stdout.write(`\n${stale} 个 stale -> lark-relay cursors --prune\n`)
+    return 0
+  }
+
+  // --prune:位置参数是要删的身份;没给就只清 stale 的那些
+  const names = a._
+  const res = cursors.prune(names)
+
+  // removed 的元素是 `name/app` —— 删的单位是 app,一个身份可能盯多个
+  for (const n of res.removed) process.stdout.write(`已删 ${n}\n`)
+  for (const n of res.missing) process.stderr.write(`没有这个游标身份:${n}\n`)
+
+  // 在跑的一律不删 —— take 会立刻把游标写回来,删了是白删还让人以为清理生效了
+  for (const r of res.refused) {
+    process.stderr.write(
+      `跳过 ${r.name}:有 take 正在用它(pid ${r.pid})。\n` +
+        `  要清它先停掉那个 take(kill ${r.pid}),否则它会把游标立刻写回来。\n`,
+    )
+  }
+  if (!res.removed.length && !res.missing.length && !res.refused.length) {
+    process.stdout.write(names.length ? '没删任何东西\n' : '没有 stale 游标,无需清理\n')
+  }
+  // 退出码:点名的目标一个都没删成(全被拒/全不存在)才算失败 ——
+  // 裸 prune 顺带跳过一个在跑的游标不是错误,那次清理是成功的
+  if (res.missing.length) return 2
+  if (res.refused.length && !res.removed.length && names.length) return 3
+  return 0
+}
+
 async function cmdStatus(argv) {
   const a = parseArgs(argv, { flags: ['json', 'help'], keys: [] })
   if (a._unknown.length) return rejectUnknown('lark-relay status', argv, a._unknown, ['json'])

package/lib/cursors.js

@@ -0,0 +1,168 @@
+'use strict'
+
+// cursors:游标治理 -- 判定每个游标是「在跑 / 暂停可续接 / 已失效」,并支持清理。
+//
+// 为什么需要这个模块:纪律「不盯了就删游标」写在 AGENTS.md 和 help 三处,
+// 却从落地到 2026-09-06 一次都没被执行 -- 8 个游标全留着,0 个在值守。
+// 根因不是人不自觉,是**没有反馈回路**:
+//   ① status 把死游标和活消费者渲染成同一个样子,看不出谁有人在跑
+//   ② 唯一的信号「落后 N 条」**越久越小** -- store 只留几天,gc 删掉的部分不再计入 lag,
+//      于是越该清理的游标看起来越健康(实测 novel-watch-lianhua 从 373 条一路缩水)
+// 所以这里给出机械判据,让状态可见、清理一键化,而不是把纪律再写一遍。
+const fs = require('fs')
+const path = require('path')
+const store = require('./store')
+const { paths, dayKeyOffset } = require('./paths')
+const { lockPathFor, holderPid } = require('./lock')
+
+// stale 判据的地基(**整个方案的正确性都压在这一条上**):
+// 游标位置的日期早于扫描窗口最老的一天时,续接它和 --since now 行为**完全等价** --
+// scanWindow 只看最近 SCAN_DAYS 天的目录,更早的日期 collect 的 gc 已经整目录删了,
+// afterCursor 过滤后必然为空。也就是说**删掉这种游标是无损的**,不会丢任何还能取到的消息。
+//
+// ⚠️ 反过来说,窗口**内**的游标不能自动删 -- 那才是「关了会话、过阵子接着盯」的续接凭据,
+// 删了等于跳过停机期已落盘的消息。这是 idle 与 stale 必须分开的全部理由
+function oldestScannedDay() {
+  return dayKeyOffset(-(store.SCAN_DAYS - 1))
+}
+
+// 游标值形如 `2026-09-04/<stamp>_<pid>_<seq>.json`,取日期段。
+// YYYY-MM-DD 字典序 == 时间序,故可直接字符串比较(store.afterCursor 已在用这个性质)
+function cursorDay(key) {
+  return String(key || '').split('/')[0] || null
+}
+
+function isStaleDay(day) {
+  if (!day) return true // 读不出日期的游标续接不了,按失效处理
+  return day < oldestScannedDay()
+}
+
+// 活消费者判定:复用 take 已经在用的锁,不另造注册表。
+// take 用 `take-<name>` 作锁键(bin/lark-relay.js),锁目录里的 pid 文件就是持有者
+function livePidOf(name) {
+  return holderPid(`take-${name}`)
+}
+
+// 枚举 cursors/ 下的全部游标。
+// 一个 name 目录下可能有多个 app 文件,外加 dedup 的 <app>.seen.json 与落盘用的 .tmp --
+// 只有「没后缀的那些」才是游标本身,别把 dedup 文件当成一个 app
+function listCursors() {
+  let names
+  try {
+    names = fs.readdirSync(paths.cursors).filter((n) => !n.startsWith('.'))
+  } catch {
+    return [] // 还没跑过任何 take
+  }
+  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 pid = livePidOf(name)
+    for (const f of files.sort()) {
+      if (f.startsWith('.') || f.endsWith('.tmp') || f.endsWith('.seen.json')) continue
+      const key = store.readCursor(name, f)
+      if (!key) continue
+      const day = cursorDay(key)
+      // live 优先于 stale:take 正在跑就以它为准 -- 它马上会把游标推到当前位置,
+      // 此刻位置旧只说明它刚起来还没追上,不代表失效
+      const state = pid ? 'live' : isStaleDay(day) ? 'stale' : 'idle'
+      out.push({ name, app: f, cursor: key, day, state, pid })
+    }
+  }
+  return out
+}
+
+// 删一个身份下的**指定 app** 游标,连同它的 dedup 记录。
+// ⚠️ 必须连 <app>.seen.json 一起删 -- 留下 dedup 残留会让重挂后的头几条消息
+// 被误判成重复而静默丢掉(TTL 6 小时,见 dedup.js)。
+//
+// ⚠️ 粒度必须是 app 而不是整个身份目录:一个 --name 可以同时盯多个 app
+// (cursors/<name>/appA、<name>/appB),而 stale 是**逐 app 判定**的。
+// 早先这里 rm -rf 整个 name 目录,于是「appA 已过期、appB 还在窗口内」时
+// 清 appA 会把 appB 那个**还能续接**的游标一起删掉(实测复现)。
+function removeCursorApp(name, app) {
+  const dir = path.join(paths.cursors, name)
+  let ok = false
+  for (const f of [app, `${app}.seen.json`, `${app}.tmp`]) {
+    try {
+      fs.rmSync(path.join(dir, f), { force: true })
+      ok = true
+    } catch {}
+  }
+  // 目录空了才删目录 -- 还有别的 app 就留着
+  try {
+    if (!fs.readdirSync(dir).length) fs.rmdirSync(dir)
+  } catch {}
+  return ok
+}
+
+// 顺带清掉该身份的锁目录(若持有者已死)。
+// prune 删了游标却留着 take-<name>.lock,会在 run/ 里积累孤儿锁 --
+// 不致命(下次抢锁会夺走陈旧锁),但既然在清理就一并收干净
+function removeStaleLock(name) {
+  if (holderPid(`take-${name}`)) return // 还活着,不碰
+  try {
+    fs.rmSync(lockPathFor(`take-${name}`), { recursive: true, force: true })
+  } catch {}
+}
+
+/**
+ * 清理游标。
+ * @param {string[]} names 指定要删的身份(该身份下全部 app);空数组 = 只删 stale 的那些 app
+ * @returns {{removed:string[], refused:Array<{name:string,pid:number}>, missing:string[]}}
+ *   removed 的元素形如 `name/app` -- 删的单位是 app,不是整个身份
+ */
+function prune(names = []) {
+  const all = listCursors()
+  // 一个 name 可能有多个 app 行,按身份归并 -- live 判定是按身份的(锁以 name 为键)
+  const byName = new Map()
+  for (const c of all) {
+    if (!byName.has(c.name)) byName.set(c.name, [])
+    byName.get(c.name).push(c)
+  }
+
+  const removed = []
+  const refused = []
+  const missing = []
+
+  const targets = names.length ? names : [...byName.keys()]
+
+  for (const name of targets) {
+    const rows = byName.get(name)
+    if (!rows) {
+      missing.push(name)
+      continue
+    }
+    // live 一律不删,即使显式点名:take 还在跑,它会立刻把游标写回来 --
+    // 删了是白删,还会让人以为清理没生效
+    const live = rows.find((r) => r.state === 'live')
+    if (live) {
+      refused.push({ name, pid: live.pid })
+      continue
+    }
+    // 显式点名 = 清该身份的全部 app(用户明确不盯了);
+    // 裸 prune = 只清 stale 的那些 app,窗口内的留着续接
+    const victims = names.length ? rows : rows.filter((r) => r.state === 'stale')
+    for (const r of victims) {
+      if (removeCursorApp(name, r.app)) removed.push(`${name}/${r.app}`)
+    }
+    if (victims.length) removeStaleLock(name)
+  }
+
+  return { removed, refused, missing }
+}
+
+module.exports = {
+  listCursors,
+  prune,
+  removeCursorApp,
+  cursorDay,
+  isStaleDay,
+  oldestScannedDay,
+}

package/lib/help.js

@@ -48,16 +48,16 @@ function takeHelp(apps) {
 最佳实践
   · 一直等不到消息 -> 九成是 bot 不在群,回第二步验(最常见故障)
   · 多个消费者盯同一 app 用不同 --name,游标互不干扰
-  · 不盯了就删游标:rm -rf ~/.lark-relay/cursors/<name>
-    引擎不会自动清(它是跨会话续接的凭据)。留着会在 status 里一直挂
-    「落后 N 条」,而 store 只保留几天 -- N 会随过期删除而变小,
+  · 不盯了就清游标:lark-relay cursors --prune
+    引擎不主动删你的续接凭据(它是跨会话接着盯的凭据)。留着会在 status 里
+    一直挂「落后 N 条」,而 store 只保留几天 -- N 会随过期删除而变小,
     看着像追上了,其实是消息没了`
 }
 
 const COLLECT_HELP = `把全部 lark-cli profile 的事件收下来,原子落盘。零参数、零配置。
 
   lark-relay-collect                    # 前台跑(调试)
-  常驻:macOS 用 launchd(plist 模板见仓库 launchd/ 目录)
+  常驻:macOS 用 launchd(见下「常驻部署」)
 
 独立可执行文件而非 \`lark-relay\` 的子命令 -- 它是常驻服务,服务管理器展示的是
 可执行文件名,与 launchd label(com.adaex.lark-relay-collect)同名才认得出。
@@ -86,20 +86,56 @@ tokenStatus 为 expired 的 profile 自动跳过并 warn(永久失败,重试是
 
 环境变量
   LARK_RELAY_LOG_MAX_MB  单个日志文件上限(默认 16),超了轮转
-  LARK_RELAY_LOG_KEEP    保留几代旧日志(默认 3)`
+  LARK_RELAY_LOG_KEEP    保留几代旧日志(默认 3)
+
+常驻部署(macOS / launchd)
+  要点只有三条,plist 自己写十来行就够,不必找模板:
+  · 用 **LaunchDaemon**(装 /Library/LaunchDaemons/)+ \`UserName\` 降权到你自己,
+    不用 LaunchAgent -- Agent 要 GUI 登录才加载、登出即停,而事件零回放,停摆=丢消息
+  · \`ProgramArguments\` 写 \`lark-relay-collect\` 的**绝对路径**(\`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`
 
 const STATUS_HELP = `一眼看清全局:谁在跑、积压多少、游标在哪。
 
   lark-relay status              # 概览
   lark-relay status --json       # 机器可读
 
-排障入口:某消费者「落后」很多 -> 它的 take 没在跑或卡住;
+消费者三态:
+  ● 在跑    有 take 持锁,pid 是它
+  ○ 暂停    没人在跑,但位置还在扫描窗口内 -- 再起一个 take 能接着盯
+  ⚠ stale   位置已超扫描窗口,那段消息 gc 已回收,续接取不到东西 -> 该清理
+
+排障入口:「○ 暂停」而你以为它在盯 -> 它的 take 没起来或早退了;
 「无消费者」= 白采,可考虑 --exclude。
-不打算再盯的消费者要删游标(引擎不会自动清,积压数还会随 store 过期而虚假变小):
-  rm -rf ~/.lark-relay/cursors/<name>
+stale 游标清理:lark-relay cursors --prune
 collect 行不是 running -> tail -f ~/.lark-relay/logs/collect.err.log
 (launchd 不进统一日志),collect 停摆的每一秒都在丢消息。`
 
+const CURSORS_HELP = `游标治理:看清哪些还在值守,清掉已失效的。
+
+  lark-relay cursors                    # 列出全部游标及状态
+  lark-relay cursors --prune            # 清掉全部 stale 的
+  lark-relay cursors --prune <name>...  # 清指定身份的全部 app(在跑的会跳过)
+
+三态:● 在跑 / ○ 暂停(窗口内,可续接) / ⚠ stale(超窗口,续接无意义)
+
+删的单位是 **app**,不是身份:一个 --name 可以同时盯多个 app,
+裸 --prune 只清其中 stale 的那些,窗口内的留着续接(点名才整个身份清)。
+连带删该 app 的 dedup 记录(<app>.seen.json),不留会让重挂后头几条被误判重复。
+
+为什么 stale 能放心删:消费侧只扫最近几天的目录,更早的日期 collect 的 gc
+已整目录删掉。**续接一个超窗口的游标和 --since now 行为完全一样** --
+删它不会丢任何还取得到的消息,留着只会让 status 虚报积压。
+反过来,窗口内的「○ 暂停」不自动删 -- 那是「关了会话、过阵子接着盯」的续接凭据。
+
+退出码:0 正常(含「跳过了在跑的那个」),2 参数错或点名的身份不存在,
+3 点名的目标全在跑、一个都没清掉`
+
 const GUIDE = `lark-relay -- Lark 事件中继站。两件事:收下来 / 我来取。
 
 \`lark-relay-collect\` 把事件收下来落盘(常驻服务),\`lark-relay take\` 在你需要时取走一批。
@@ -109,7 +145,7 @@ const GUIDE = `lark-relay -- Lark 事件中继站。两件事:收下来 / 我来
 前置:采集必须在跑
   lark-relay status        # collect 行应为 running
   进程不在的时刻消息永久丢失,不是延迟送达。
-  不在跑 -> 起常驻服务(macOS launchd,plist 模板见仓库;
+  不在跑 -> 起常驻服务(macOS launchd,要点见 \`lark-relay-collect --help\`;
            或 \`lark-relay-collect\` 前台调试)
 
 take 四步(照做)
@@ -121,9 +157,12 @@ take 四步(照做)
      起来后 stderr 有一行「监听中」-- 没有就是没起来,看 stderr。
      一批处理完再起一个。不要自己写 while 循环 -- 进程退出会通知你。
      退出码:0=有一批,4=超时没消息(正常,再起一个),2=参数错,3=游标被占用。
-  4. 不盯了收尾  rm -rf ~/.lark-relay/cursors/<name>
-     游标只为「关了会话、过阵子接着盯」而存在,引擎不会自动清。
-     临时监听、验完的排查、不再值守的任务,收尾时自己删掉
+  4. 不盯了收尾  lark-relay cursors --prune
+     游标为「关了会话、过阵子接着盯」而存在,引擎不主动删你的续接凭据。
+     临时监听、验完的排查、不再值守的任务,收尾时自己清 --
+     不清的代价:status 里一直挂着假积压(数字会随 store 过期变小,
+     看着像追上了,其实是消息永久没了)。
+     显式清掉某个身份:lark-relay cursors --prune <name>
 
 常见错误
   · 拿不到消息 -> 九成是 bot 不在群。验 bot 必须 --as user,
@@ -137,4 +176,4 @@ take 四步(照做)
 
 各命令详情:lark-relay <命令> --help`
 
-module.exports = { takeHelp, COLLECT_HELP, STATUS_HELP, GUIDE }
+module.exports = { takeHelp, COLLECT_HELP, STATUS_HELP, CURSORS_HELP, GUIDE }

package/lib/lock.js

@@ -19,7 +19,7 @@ const { paths, ensureDir } = require('./paths')
 function acquireExclusive(key) {
   const safe = sanitize(key)
   const runDir = ensureDir(paths.run)
-  const dir = path.join(runDir, `${safe}.lock`)
+  const dir = lockPathFor(key)
   const pidFile = path.join(dir, 'pid')
   const me = String(process.pid)
 
@@ -114,4 +114,18 @@ function sanitize(s) {
   return String(s).replace(/[^A-Za-z0-9._-]/g, '_')
 }
 
-module.exports = { acquireExclusive }
+// 锁目录位置。**外部判活必须走这个函数**,不能自己拼路径 ——
+// sanitize() 会把非 [A-Za-z0-9._-] 换成 `_`,自己拼会让含特殊字符的 key 匹配不上
+function lockPathFor(key) {
+  return path.join(paths.run, `${sanitize(key)}.lock`)
+}
+
+// 谁持有这把锁(活着才算)。没锁、锁陈旧(持有者已死)都返回 null。
+// 复用上面的 readPid/alive —— 与抢锁时的判活口径完全一致
+function holderPid(key) {
+  const pid = readPid(path.join(lockPathFor(key), 'pid'))
+  if (!pid) return null
+  return alive(pid) ? pid : null
+}
+
+module.exports = { acquireExclusive, lockPathFor, holderPid }

package/lib/status.js

@@ -1,12 +1,10 @@
 'use strict'
 
 // status:一眼看清全局 —— 谁在跑、积压多少、游标在哪。
-const fs = require('fs')
-const path = require('path')
 const { execFileSync } = require('child_process')
 const store = require('./store')
-const { paths } = require('./paths')
 const larkcli = require('./larkcli')
+const cursors = require('./cursors')
 
 function ago(ms) {
   if (!ms) return '—'
@@ -52,32 +50,10 @@ function collectHint() {
   return `sudo launchctl bootstrap system /Library/LaunchDaemons/${COLLECT_LABEL}.plist`
 }
 
-// 消费者 = cursors/ 下的目录。每个记录它在各 app 上的游标位置。
+// 消费者 = cursors/ 下的目录。枚举与三态判定都在 lib/cursors.js,这里只做展示 ——
+// 「哪些游标存在、谁还活着」是治理逻辑,status 和 cursors 子命令必须用同一份口径
 function listConsumers() {
-  let names
-  try {
-    names = fs.readdirSync(paths.cursors).filter((n) => !n.startsWith('.'))
-  } catch {
-    return []
-  }
-  const out = []
-  for (const name of names) {
-    const dir = path.join(paths.cursors, name)
-    let files
-    try {
-      if (!fs.statSync(dir).isDirectory()) continue
-      files = fs.readdirSync(dir)
-    } catch {
-      continue
-    }
-    for (const f of files) {
-      if (f.endsWith('.tmp') || f.endsWith('.seen.json')) continue
-      const key = store.readCursor(name, f)
-      if (!key) continue
-      out.push({ name, app: f, cursor: key })
-    }
-  }
-  return out
+  return cursors.listCursors()
 }
 
 // 落后多少条:游标之后还剩几个事件没消费
@@ -114,8 +90,10 @@ async function buildStatus() {
       latestMs = Number(ev?.timestamp || ev?.create_time) || null
     }
     const cs = (byApp.get(app) || []).map((c) => {
-      const lag = lagOf(app, c.cursor)
-      return { name: c.name, lag }
+      // stale 的 lag 不算也不显示 —— 那个数字是误导的来源:gc 删掉的部分不再计入,
+      // 于是越久没消费看起来越「追上了」,而实际是消息永久没了
+      const lag = c.state === 'stale' ? null : lagOf(app, c.cursor)
+      return { name: c.name, lag, state: c.state, pid: c.pid, cursor: c.cursor, day: c.day }
     })
     rows.push({ app, today: store.countToday(app), latestMs, consumers: cs })
   }
@@ -149,13 +127,38 @@ function formatStatus(s) {
   }
   const w = (str, n) => String(str) + ' '.repeat(Math.max(1, n - dispWidth(str)))
   out.push(`${w('app', 8)}${w('今日事件', 10)}${w('最新事件', 13)}消费者`)
+  let staleCount = 0
   for (const r of s.apps) {
-    const cs = r.consumers.length
-      ? r.consumers
-          .map((c) => `${c.name}(${c.lag === 0 ? '游标追平' : `落后 ${c.lag} 条`})`)
-          .join(', ')
-      : '—（无消费者）'
-    out.push(`${w(r.app, 8)}${w(r.today, 10)}${w(ago(r.latestMs), 13)}${cs}`)
+    // 消费者各占一行:三态要一眼分得清,挤在一行里 ●/○/⚠ 会被淹掉。
+    // 「谁在跑」是排障第一问,以前得靠猜(全都长成 `name(落后 N 条)`)
+    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 lagTxt = c.lag === 0 ? '游标追平' : `落后 ${c.lag} 条`
+      let mark
+      let note
+      if (c.state === 'live') {
+        mark = '●'
+        note = `在跑 (pid ${c.pid}, ${lagTxt})`
+      } else if (c.state === 'stale') {
+        staleCount++
+        mark = '⚠'
+        // 不给 lag:它已经不代表「还能取到多少」。给位置和原因才可行动
+        note = `stale (游标停在 ${c.day || '?'},已超 ${cursors.oldestScannedDay()} 的扫描窗口,续接取不到东西)`
+      } else {
+        mark = '○'
+        note = `暂停 (${lagTxt},可续接)`
+      }
+      out.push(`  ${w(c.name, 24)}${mark} ${note}`)
+    }
+  }
+  if (staleCount) {
+    out.push('')
+    out.push(`⚠ ${staleCount} 个 stale 游标 —— 那段消息 gc 已回收,留着只会虚报积压`)
+    out.push('  清理:lark-relay cursors --prune')
   }
 
   return out.join('\n')

package/package.json

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