lark-relay 0.4.15 → 0.5.0

package/README.md

@@ -80,22 +80,24 @@ lark-relay take --app <app> --chats oc_xxx --render text
 多消费者**共享 store、各持游标**,不做「处理完即删」-- 谁都不能替别人删。
 盯同一 app 请用不同 `--name` 隔离游标。
 
-**游标要自己收尾**:它是「关了会话、过阵子接着盯」的续接凭据,所以引擎**不会**
-自动清理还有积压的游标 -- 自动清掉就等于下次重挂跳过这段已落盘的消息。
-代价是不再用的游标会一直留在 `status` 里显示「有 N 条待消费」,而 store 只保留几天,
-那个 N 会随过期删除而变小(**看着像追上了,其实是消息没了**)。
-
-一次性监听、验完的排查、不再值守的任务,收尾时:
+**游标会自动回收**:空闲超过 2 天的游标由 collect 删掉(每小时自查一次,
+与 store 的日期目录回收同一个 gc)。判据是「多久没人用过它」——
+不需要你记得收尾,也不需要你判断该不该删。
 
 ```bash
-lark-relay cursors           # ● 在跑 / ○ 已消费完 / ⚠ 有积压没人跑
-lark-relay cursors --prune   # 清「已消费完」的(删掉无损)
+lark-relay cursors                     # ● 在跑 / ○ 空闲 Nh / ⚠ 空闲超期待回收
+lark-relay cursors --forget <name>     # 不等超期,现在就清
 ```
 
-判据只有一条:按这个游标续接还剩几条没消费。剩 0 条才无条件可清;
-还有积压的要 `--prune <name> --force` 明确确认(删了就跳过那些消息)。
-别手工 `rm -rf` 游标目录 -- 那会漏掉同名的 `<app>.seen.json`(去重记录),
-残留会让重挂后头几条消息被误判成重复而静默丢掉。
+为什么是空闲时长而不是「落后多少条」:落后量是**遗弃的症状,不是反面** ——
+被遗弃的游标落后会一路涨,拿它当判据会把该清的保护起来、该留的删掉
+(2026-09-06 实测)。空闲时长与遗弃程度同向单调。
+
+为什么 2 天够:take 是**实时场景**的取用口。空闲一两天以上再重挂,
+下一次消费一定从新的开始;要历史消息有专门的接口,不靠游标回放。
+改期限:`LARK_RELAY_CURSOR_TTL_DAYS=<天>`。
+
+在跑的游标(有 take 持锁)一律不回收 —— take 会立刻把它写回来。
 
 ## 设计取舍
 

package/bin/lark-relay.js

@@ -24,7 +24,7 @@ const USAGE = `lark-relay ${VERSION} -- Lark 事件中继站(在场取用)
 
   lark-relay take ...           在场取用:阻塞等一批 -> 输出 -> 退出
   lark-relay status             谁在跑 / 各 app 积压 / 各游标位置
-  lark-relay cursors            游标治理:看谁还在值守 / --prune 清失效的
+  lark-relay cursors            游标状态:谁在值守 / 空闲多久(超期自动回收)
   lark-relay guide              一页用法(装完先读这个)
 
 采集底座是独立命令(常驻服务):lark-relay-collect
@@ -145,29 +145,21 @@ async function cmdTake(argv) {
   // 那个理由是错的,实测证伪:afterCursor 比的是「事件日期 > 游标日期」,
   // 游标越老放行的事件越多。实测游标停在 D-5、窗口内有 3 条未消费时,
   //   保留游标 -> 取到 3 条    重置到 now -> 取到 0 条
-  // 也就是说那个「自愈」每次都在**静默丢掉窗口内的全部积压**,
-  // 还打一行「那段消息已被 gc 回收」宽慰你。老游标本身工作得很好,不需要治。
+  // 也就是说那个「自愈」每次都在**静默丢掉窗口内的全部积压**。
+  // 现在:游标一律原样保留,能取到的照常取。
   //
-  // 位置早于窗口确实要说一句,但说的是「D-x 到 D-y 那段已被 gc 回收、找不回」
-  // (告知既成事实),而不是动用户的游标 —— 剩下能取到的照常取。
+  // 不再需要「位置早于窗口」那条告知了 —— 遗弃的游标由 collect 按空闲时长自动回收
+  // (见 lib/cursors.js),不靠位置推断,也不靠人清。
   if (since === 'now') {
-    const existing = store.readCursor(name, a.app)
-    if (existing === null) {
-      store.seedCursorNow(name, a.app)
-    } else {
-      const { cursorDay, isPreWindowDay, oldestScannedDay } = require('../lib/cursors')
-      const day = cursorDay(existing)
-      if (isPreWindowDay(day)) {
-        // 说明行必须打在「监听中」**之前** —— 那一行是约定的启动信号
-        // (「没这行就是没起来」),不能被别的输出插到中间
-        process.stderr.write(
-          `游标 ${name} 停在 ${day},早于扫描窗口(最早 ${oldestScannedDay()})\n` +
-            `-> 那之前的消息已被 gc 回收、找不回;窗口内还在的会照常取\n`,
-        )
-      }
-    }
+    if (store.readCursor(name, a.app) === null) store.seedCursorNow(name, a.app)
   }
 
+  // 标记「有人来取过」。回收判据是空闲时长,而它读 mtime --
+  // ⚠️ 必须在这里显式 touch:take 的正常路径只在**有批次**时写游标,
+  // 空手超时/被 SIGTERM 都不写(实测起一个 take 再 kill,mtime 一动不动)。
+  // 不 touch 就会把「安静的群盯了两天没消息」误判成遗弃并回收
+  store.touchCursor(name, a.app)
+
   // 时长参数校验:负数/非数字过去会静默退回默认值或原样生效
   // (实测 --debounce -5 被接受并打印「防抖=-5s」,--timeout abc 悄悄变成 12 小时)
   const dur = (val, def, label) => {
@@ -219,8 +211,15 @@ async function cmdTake(argv) {
   return 0
 }
 
+// cursors:**只读展示 + 一个提前忘掉的逃生舱**。
+//
+// ⚠️ 这里曾有 --prune / --force 与一套「该不该删」的判断(2026-09-06 删)。
+// 删的理由不是简化:那套东西要求人拿着一个数字做破坏性决定,而**判据错了两次**
+// (先按游标日期、后按待消费数,方向都是反的 —— 见 lib/cursors.js 文件头)。
+// 现在回收由 collect 按空闲时长自动做,人不必判断,所以那些档位和确认步骤
+// 一起失去了存在理由。留一个 --forget 给「现在就想清干净」。
 function cmdCursors(argv) {
-  const CURSORS_FLAGS = ['prune', 'force', 'json', 'help']
+  const CURSORS_FLAGS = ['forget', 'json', 'help']
   const a = parseArgs(argv, { flags: CURSORS_FLAGS, keys: [] })
   if (a._unknown.length) return rejectUnknown('lark-relay cursors', a._unknown, CURSORS_FLAGS)
   if (a.help) {
@@ -228,47 +227,62 @@ function cmdCursors(argv) {
     return 0
   }
   const cursors = require('../lib/cursors')
+  const ttlDays = Math.round(cursors.IDLE_TTL_MS / 86400000)
+
+  // 人话的空闲时长。回收判据就是这个数,所以它必须是最显眼的一列
+  const idleTxt = (ms) => {
+    if (!Number.isFinite(ms)) return '未知'
+    // 向下取整:这个数是回收判据,宁可少报不可多报 --
+    // Math.round 会把 2.5 天显示成「3d」,看着像已经超了 2 天的 TTL 更多
+    const m = Math.floor(ms / 60000)
+    if (m < 60) return `${m}m`
+    const h = Math.floor(m / 60)
+    return h < 48 ? `${h}h` : `${Math.floor(h / 24)}d`
+  }
 
-  // 只读模式:列清单。默认不删任何东西 —— 删数据必须显式 --prune
-  if (!a.prune) {
+  // 只读模式:列清单。删数据必须显式 --forget
+  if (!a.forget) {
     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')
+      process.stdout.write('没有游标(还没跑过 take,或已全部回收)\n')
       return 0
     }
-    const mark = { live: '●', drained: '○', backlog: '⚠' }
+    const mark = { live: '●', idle: '○', expiring: '⚠' }
     const note = {
       live: (r) => `在跑 (pid ${r.pid}, 待消费 ${r.pending})`,
-      drained: () => '已消费完 -> 删掉无损',
-      backlog: (r) => `有 ${r.pending} 条待消费但没人在跑 -> 重挂 take 能接着取`,
+      idle: (r) => `空闲 ${idleTxt(r.idleMs)}(待消费 ${r.pending},重挂 take 接着盯)`,
+      expiring: (r) => `空闲 ${idleTxt(r.idleMs)} 超 ${ttlDays} 天 -> 下轮 gc 自动回收`,
     }
     for (const r of rows) {
-      // 位置早于扫描窗口 = 那之前的一段已被 gc 回收、找不回。
-      // ⚠️ 这**不是**可删许可(早先的 stale 判据就错在这一步):
-      // 窗口内还在的事件,老游标照样全部放行。能否删只看待消费数
-      const lost = r.lostSpan ? `,${r.day} 之前的已被 gc 回收` : ''
+      process.stdout.write(`${mark[r.state]} ${r.name}  app=${r.app}  ${note[r.state](r)}\n`)
+    }
+    const expiring = rows.filter((r) => r.state === 'expiring').length
+    if (expiring) {
       process.stdout.write(
-        `${mark[r.state]} ${r.name}  app=${r.app}  位置=${r.day}  ${note[r.state](r)}${lost}\n`,
+        `\n${expiring} 个已超 ${ttlDays} 天空闲,collect 每小时自查时会回收 —— 不用手动清\n`,
       )
     }
-    const drained = rows.filter((r) => r.state === 'drained').length
-    if (drained) process.stdout.write(`\n${drained} 个已消费完 -> lark-relay cursors --prune\n`)
     return 0
   }
 
-  // --prune:位置参数是要删的身份;没给就只清 stale 的那些
+  // --forget <name>...:不等 TTL,现在就清
   const names = a._
-  const res = cursors.prune(names, { force: !!a.force })
+  if (!names.length) {
+    process.stderr.write(
+      `--forget 需要点名要忘掉哪个身份:lark-relay cursors --forget <name>...\n` +
+        `(不点名的批量清理已经不需要了 —— 空闲超 ${ttlDays} 天的由 collect 自动回收)\n`,
+    )
+    return 2
+  }
+  const res = cursors.forget(names)
 
   // removed 的元素是 `name/app` —— 删的单位是 app,一个身份可能盯多个
-  for (const n of res.removed) process.stdout.write(`已删 ${n}\n`)
+  for (const n of res.removed) process.stdout.write(`已忘掉 ${n}\n`)
   for (const n of res.missing) process.stderr.write(`没有这个游标身份:${n}\n`)
-
-  // 在跑的不删 -- take 会立刻把游标写回来。只有显式点名时才报告(见 cursors.prune)
   for (const r of res.refused) {
     process.stderr.write(
       `跳过 ${r.name}:有 take 正在用它(pid ${r.pid})。\n` +
@@ -276,23 +290,8 @@ function cmdCursors(argv) {
     )
   }
 
-  // 还有待消费的游标,删了就丢掉那些消息 -- 要 --force 再确认一次。
-  // 2026-09-06 真实踩到:点名删一个刚退出 take 的游标,那段消息的消费位置没了
-  for (const f of res.needForce) {
-    process.stderr.write(
-      `⚠ ${f.name}/${f.app} 还有 ${f.pending} 条待消费(位置 ${f.day})\n` +
-        `  删了就丢:重挂时会按 --since now 跳过这 ${f.pending} 条已落盘的消息\n` +
-        `  想取走 -> lark-relay take --app ${f.app} --name ${f.name} --chats oc_xxx\n` +
-        `  确认不要 -> lark-relay cursors --prune ${f.name} --force\n`,
-    )
-  }
-
-  if (!res.removed.length && !res.missing.length && !res.refused.length && !res.needForce.length) {
-    process.stdout.write(names.length ? '没删任何东西\n' : '没有已消费完的游标,无需清理\n')
-  }
-  // 点名的目标一个都没删成才算失败
   if (res.missing.length) return 2
-  if ((res.refused.length || res.needForce.length) && !res.removed.length) return 3
+  if (res.refused.length && !res.removed.length) return 3
   return 0
 }
 

package/lib/collect.js

@@ -9,6 +9,7 @@
 const readline = require('readline')
 const larkcli = require('./larkcli')
 const store = require('./store')
+const cursors = require('./cursors')
 const { paths, ensureDir } = require('./paths')
 const { acquireExclusive } = require('./lock')
 const { init: logInit, logLine } = require('./log')
@@ -191,22 +192,34 @@ async function runCollect(opts) {
   const collectors = chosen.map((p) => new AppCollector(p.name, opts))
   for (const c of collectors) c.start()
 
-  // gc 在本进程内每小时自查:回收逻辑就是「删超期日期目录」一句话,
-  // 另起 gc 命令 + systemd timer 是为一行逻辑加两个部署件。
-  const gcTimer = setInterval(() => {
+  // gc 在本进程内每小时自查:回收逻辑就是「删超期的东西」,
+  // 另起 gc 命令 + timer 是为几行逻辑加两个部署件。
+  // store 按天删目录,cursors 按空闲时长删 —— 同构,故同处一地
+  const runGc = () => {
     try {
       const s = store.gcStore(opts.retain)
-      if (s.length) {
-        logLine(`gc: 删 store ${s.length} 个日期目录`)
+      if (s.length) logLine(`gc: 删 store ${s.length} 个日期目录`)
+    } catch (err) {
+      logLine(`gc: store 回收失败 ${err.message}`)
+    }
+    try {
+      // 游标回收:空闲超 TTL 的自动删。**这是纪律「不盯了就清游标」的落地方式** --
+      // 那条纪律三处成文却零执行,靠人记不住;而判据本身还错过两次
+      // (见 lib/cursors.js 文件头)。引擎自己过期,不需要人判断
+      const c = cursors.gcCursors()
+      if (c.length) {
+        logLine(
+          `gc: 回收 ${c.length} 个空闲超 ${Math.round(cursors.IDLE_TTL_MS / 86400000)} 天的游标:` +
+            `${c.join(' ')}`,
+        )
       }
     } catch (err) {
-      logLine(`gc: 失败 ${err.message}`)
+      logLine(`gc: 游标回收失败 ${err.message}`)
     }
-  }, GC_INTERVAL_MS)
+  }
+  const gcTimer = setInterval(runGc, GC_INTERVAL_MS)
   // 启动时先跑一次,别等一小时
-  try {
-    store.gcStore(opts.retain)
-  } catch {}
+  runGc()
 
   return await new Promise((resolve) => {
     let shuttingDown = false

package/lib/cursors.js

@@ -1,50 +1,47 @@
 'use strict'
 
-// cursors:游标治理 -- 判定每个游标能不能删,并支持清理。
+// cursors:游标治理 -- 只做两件事:**如实展示**每个游标的状态,
+// 以及**按空闲时长自动回收**(由 collect 的 gc 每小时调一次)。
 //
-// 为什么需要这个模块:纪律「不盯了就删游标」写在 AGENTS.md 和 help 三处,
-// 却从落地到 2026-09-06 一次都没被执行 -- 8 个游标全留着,0 个在值守。
-// 根因不是人不自觉,是**没有反馈回路**:status 把死游标和活消费者渲染成同一个样子,
-// 看不出谁有人在跑。所以这里给出机械判据,让状态可见、清理一键化。
+// ⚠️ 这个模块 2026-09-06 一天内改了三版。前两版都错在同一个地方:
+// **让人拿着一个推断量去做破坏性决定**。记下来免得再走一遍:
 //
-// ⚠️ 2026-09-06 重写:上一版判据是**错的**,推理反了,实测证伪。
-// 原文写「游标日期早于扫描窗口 -> 续接它和 --since now 完全等价 -> 删掉无损」。
-// 但 afterCursor 比的是「事件日期 > 游标日期」-- **游标越老,通过过滤的事件越多**。
-// 实测:游标停在 D-5、窗口内 D-2/D-1/D-0 各有 1 条未消费,
-//   按该游标续接 -> 扫到 3 条(全是能取到的)
-//   --since now  -> 扫到 0 条
-// gc 删掉的只是游标所在那几天,窗口内的事件一条没删,而老游标恰好全部放行。
-// 「续接取不到东西」正好说反了,照它删就是丢掉窗口内的全部积压。
+// ① 第一版判据「游标日期超出扫描窗口 -> 删掉无损」。
+//    实测证伪:afterCursor 比的是「事件日期 > 游标日期」,游标越老放行的事件**越多**。
+//    停在 D-5 的游标能取到窗口内 3 条,而 --since now 取到 0 条。
+//    照它删/重置就是丢掉全部积压。
+// ② 第二版改成实测量「pending = 按这个游标续接还剩几条」,以为方向对了。
+//    **仍然是反的** —— 实测两种剧本:
+//      被遗弃两天的游标(app 还在收消息) -> pending 50 -> 判 backlog -> 保护它
+//      活跃任务刚处理完一批、take 暂退   -> pending 0  -> 判 drained -> 删掉它
+//    该清的被保护,该留的被删。因为**落后量是遗弃的症状,不是遗弃的反面**。
+//    更糟:只要 app 还在收消息,被遗弃游标的 pending 单调增长,永不归零 --
+//    裸 prune 对真正该清的东西**永久无效**(实测 gc 删掉游标所在那天后 pending 仍不变)。
 //
-// **正解:别再从游标日期推断,直接量。** 能不能无损删除只取决于一件事 --
-// 按这个游标续接还能扫到几条(pending)。pending==0 才是真的删掉无损。
-// 游标日期早于窗口是另一回事:它说明**那段已被 gc 回收、永久找不回**,
-// 这是要告知的事实,不是可以删除的许可。两件事必须分开,混在一起就是上一版的错。
+// **正解:判据是「多久没人用过它」,不是「它落后多少」。**
+// mtime 一直都在,从来没被读过。这个方向与遗弃程度同向单调:越久没碰越该清。
+// 而且它让清理**不再需要人做判断** -- 前两次犯错都发生在
+// 「人拿着一个数字决定删不删」这一步,这一版把那一步整个删掉:引擎自己过期。
 const fs = require('fs')
 const path = require('path')
 const store = require('./store')
-const { paths, dayKeyOffset } = require('./paths')
+const { paths } = require('./paths')
 const { lockPathFor, holderPid } = require('./lock')
 
-// 扫描窗口最老的一天。比它更早的日期,collect 的 gc 已经整目录删了。
-// ⚠️ 这个值只用来**告知「那段找不回了」**,不参与「能否删除」的判定 --
-// 那正是上一版把两件事混在一起犯的错
-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
-}
-
-// 游标位置是否早于扫描窗口 = 它与当前位置之间有一段已被 gc 回收、永久找不回。
-// 注意这**不**代表游标没用了:窗口内的事件它照样全部放行(见文件头实测)
-function isPreWindowDay(day) {
-  if (!day) return true // 读不出日期的游标,当作位置不明
-  return day < oldestScannedDay()
-}
+// 空闲多久算遗弃。默认 2 天。
+//
+// 为什么是 2 天而不是更长(2026-09-06 用户定):take 是**实时场景**的取用口 --
+// 「关了会话过阵子接着盯」的窗口本来就短。空闲一两天以上再重挂,
+// 下一次消费一定是从新的开始;真要历史消息有专门的接口,不靠游标回放。
+//
+// 代价说清楚:超过 TTL 的游标被回收后,重挂按 --since now 起头,
+// 跳过这段已落盘的消息。但 store 只保留 SCAN_DAYS(默认 3)天 --
+// TTL 2 天时,被回收的游标最多也就跳过盘上还剩的那一天多,
+// 而那种情况本身就是「两天没人管」。这个代价是可接受的,且是**显式**的
+const IDLE_TTL_MS = (() => {
+  const d = Number(process.env.LARK_RELAY_CURSOR_TTL_DAYS)
+  return (Number.isFinite(d) && d > 0 ? d : 2) * 86400_000
+})()
 
 // 活消费者判定:复用 take 已经在用的锁,不另造注册表。
 // take 用 `take-<name>` 作锁键(bin/lark-relay.js),锁目录里的 pid 文件就是持有者
@@ -53,15 +50,15 @@ function livePidOf(name) {
 }
 
 /**
- * 枚举 cursors/ 下的全部游标,并实测每个的待消费条数。
+ * 枚举 cursors/ 下的全部游标。
  *
  * 一个 name 目录下可能有多个 app 文件,外加 dedup 的 <app>.seen.json 与落盘用的 .tmp --
  * 只有「没后缀的那些」才是游标本身,别把 dedup 文件当成一个 app。
  *
- * @returns {Array<{name,app,cursor,day,state,pid,pending,lostSpan}>}
- *   state: live(有 take 在跑) | backlog(有待消费,删了就丢) | drained(消费完了,删掉无损)
- *   pending: 按此游标续接还能扫到几条 —— **能否删除的唯一判据**
- *   lostSpan: 位置早于扫描窗口,中间那段已被 gc 回收、找不回(与能否删除无关,仅告知)
+ * @returns {Array<{name,app,cursor,day,state,pid,idleMs,pending}>}
+ *   state: live(有 take 持锁) | idle(空闲但在 TTL 内) | expiring(超 TTL,下轮 gc 回收)
+ *   idleMs: 距最后一次被使用多久 —— **回收判据**
+ *   pending: 按此游标续接还剩几条 —— 仅作展示(它不是回收判据,见文件头 ②)
  */
 function listCursors() {
   let names
@@ -77,6 +74,7 @@ function listCursors() {
     return scanCache.get(app)
   }
 
+  const now = Date.now()
   const out = []
   for (const name of names.sort()) {
     const dir = path.join(paths.cursors, name)
@@ -92,12 +90,20 @@ function listCursors() {
       if (f.startsWith('.') || f.endsWith('.tmp') || f.endsWith('.seen.json')) continue
       const key = store.readCursor(name, f)
       if (!key) continue
-      const day = cursorDay(key)
-      // 实测待消费数 —— 判据在这里,不在日期上
-      const pending = scanOf(f).filter((e) => store.afterCursor(e, key)).length
-      // live 优先:take 正在跑就以它为准,它自己会把游标推进
-      const state = pid ? 'live' : pending > 0 ? 'backlog' : 'drained'
-      out.push({ name, app: f, cursor: key, day, state, pid, pending, lostSpan: isPreWindowDay(day) })
+      const mtime = store.cursorMtime(name, f)
+      const idleMs = mtime === null ? Infinity : Math.max(0, now - mtime)
+      // live 优先:take 正在跑就是在用,不看空闲时长
+      const state = pid ? 'live' : idleMs >= IDLE_TTL_MS ? 'expiring' : 'idle'
+      out.push({
+        name,
+        app: f,
+        cursor: key,
+        day: String(key).split('/')[0] || null,
+        state,
+        pid,
+        idleMs,
+        pending: scanOf(f).filter((e) => store.afterCursor(e, key)).length,
+      })
     }
   }
   return out
@@ -108,9 +114,9 @@ function listCursors() {
 // 被误判成重复而静默丢掉(TTL 6 小时,见 dedup.js)。
 //
 // ⚠️ 粒度必须是 app 而不是整个身份目录:一个 --name 可以同时盯多个 app
-// (cursors/<name>/appA、<name>/appB),而状态是**逐 app 判定**的。
-// 早先这里 rm -rf 整个 name 目录,于是「appA 已消费完、appB 还有积压」时
-// 清 appA 会把 appB 那个**还有积压**的游标一起删掉(实测复现)。
+// (cursors/<name>/appA、<name>/appB),而空闲时长是**逐 app 判定**的。
+// 早先这里 rm -rf 整个 name 目录,于是「appA 空闲很久、appB 昨天还在用」时
+// 清 appA 会把 appB 一起删掉(实测复现)。
 function removeCursorApp(name, app) {
   const dir = path.join(paths.cursors, name)
   let ok = false
@@ -128,7 +134,7 @@ function removeCursorApp(name, app) {
 }
 
 // 顺带清掉该身份的锁目录(若持有者已死)。
-// prune 删了游标却留着 take-<name>.lock,会在 run/ 里积累孤儿锁 --
+// 删了游标却留着 take-<name>.lock 会在 run/ 里积累孤儿锁 --
 // 不致命(下次抢锁会夺走陈旧锁),但既然在清理就一并收干净
 function removeStaleLock(name) {
   if (holderPid(`take-${name}`)) return // 还活着,不碰
@@ -138,17 +144,42 @@ function removeStaleLock(name) {
 }
 
 /**
- * 清理游标。
- * @param {string[]} names 指定要删的身份(该身份下全部 app);空数组 = 只删已消费完的
- * @param {{force?:boolean}} opts force 才允许删还有积压(backlog)的游标
- * @returns {{removed:string[], refused:Array<{name,pid}>, missing:string[],
- *            needForce:Array<{name,app,day,pending}>}}
- *   removed 的元素形如 `name/app` -- 删的单位是 app,不是整个身份。
- *   refused 只在**显式点名**时填充:裸 prune 遇到在跑的游标是静默跳过,不算例外
+ * 自动回收:删掉空闲超过 TTL 的游标。**由 collect 的 gc 每小时调一次**,
+ * 与 store.gcStore 完全同构 —— 都是「删超期的东西」,不需要人参与。
+ *
+ * 这是本模块存在的理由。前两版把回收做成「人拿着一个数字敲 --prune」,
+ * 结果纪律三处成文、零执行,而判据本身还错了两次。
+ * 引擎自己过期不需要人记得,也不需要人判断。
+ *
+ * ⚠️ 有 take 持锁的一律不动 —— 它正在用,而且它会立刻把游标写回来。
+ *
+ * @returns {string[]} 被回收的 `name/app`
  */
-function prune(names = [], opts = {}) {
+function gcCursors() {
+  const removed = []
+  const touchedNames = new Set()
+  for (const c of listCursors()) {
+    if (c.state !== 'expiring') continue
+    if (removeCursorApp(c.name, c.app)) {
+      removed.push(`${c.name}/${c.app}`)
+      touchedNames.add(c.name)
+    }
+  }
+  for (const n of touchedNames) removeStaleLock(n)
+  return removed
+}
+
+/**
+ * 逃生舱:立刻忘掉指定身份(该身份下全部 app),不等 TTL。
+ * 用于「刚验完、现在就想清干净」。
+ *
+ * 不设 --force 二次确认:回收本来就会自动发生,人只是提前几天,
+ * 没有「删了会丢消息」的额外判断负担 —— 那正是前两版的坑。
+ *
+ * @returns {{removed:string[], refused:Array<{name,pid}>, missing:string[]}}
+ */
+function forget(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, [])
@@ -158,11 +189,8 @@ function prune(names = [], opts = {}) {
   const removed = []
   const refused = []
   const missing = []
-  const needForce = []
 
-  const targets = names.length ? names : [...byName.keys()]
-
-  for (const name of targets) {
+  for (const name of names) {
     const rows = byName.get(name)
     if (!rows) {
       missing.push(name)
@@ -170,24 +198,12 @@ function prune(names = [], opts = {}) {
     }
     const live = rows.find((r) => r.state === 'live')
     if (live) {
-      // 显式点名时必须解释为什么没删(用户明确要求了);
-      // 而裸 prune 的意图是「清掉已经没用的」-- 在跑的游标本就不在这个视野里,
-      // 报告它是噪音(实测:3 个 take 在跑时,一次日常清理吐 3 段无关提示)
-      if (names.length) refused.push({ name, pid: live.pid })
+      // 在跑的不删:take 会立刻把游标写回来,删了只是骗自己
+      refused.push({ name, pid: live.pid })
       continue
     }
-    // 显式点名 = 清该身份的全部 app(用户明确不盯了);
-    // 裸 prune = 只清已消费完的,有积压的留着
-    const victims = names.length ? rows : rows.filter((r) => r.state === 'drained')
     let deletedAny = false
-    for (const r of victims) {
-      // ⚠️ 还有积压 = **删了就丢掉这 pending 条**(重挂时会按 --since now 跳过它们)。
-      // drained 删掉无损,backlog 不是 -- 故 backlog 要 --force 兜一道。
-      // 2026-09-06 真实踩到:点名删一个刚退出 take 的游标,消费位置就此丢失
-      if (r.state === 'backlog' && !opts.force) {
-        needForce.push({ name, app: r.app, day: r.day, pending: r.pending })
-        continue
-      }
+    for (const r of rows) {
       if (removeCursorApp(name, r.app)) {
         removed.push(`${name}/${r.app}`)
         deletedAny = true
@@ -196,14 +212,13 @@ function prune(names = [], opts = {}) {
     if (deletedAny) removeStaleLock(name)
   }
 
-  return { removed, refused, missing, needForce }
+  return { removed, refused, missing }
 }
 
 module.exports = {
+  IDLE_TTL_MS,
   listCursors,
-  prune,
+  gcCursors,
+  forget,
   removeCursorApp,
-  cursorDay,
-  isPreWindowDay,
-  oldestScannedDay,
 }

package/lib/help.js

@@ -48,10 +48,8 @@ function takeHelp(apps) {
 最佳实践
   · 一直等不到消息 -> 九成是 bot 不在群,回第二步验(最常见故障)
   · 多个消费者盯同一 app 用不同 --name,游标互不干扰
-  · 不盯了就清游标:lark-relay cursors --prune
-    引擎不主动删还有积压的游标(它是跨会话接着盯的凭据)。留着会在 status 里
-    一直挂「有 N 条待消费」,而 store 只保留几天 -- N 会随过期删除而变小,
-    看着像追上了,其实是消息没了`
+  · **不用手动清游标**:空闲超 2 天的由 collect 自动回收。
+    想立刻清干净:lark-relay cursors --forget <name>`
 }
 
 const COLLECT_HELP = `把全部 lark-cli profile 的事件收下来,原子落盘。零参数、零配置。
@@ -112,44 +110,46 @@ const STATUS_HELP = `一眼看清全局:谁在跑、积压多少、游标在哪
   lark-relay status --json       # 机器可读
 
 消费者状态:
-  ● 在跑           有 take 持锁,pid 是它
-  ○ 已消费完       没人在跑且没有待消费 -- 不盯了就清掉
-  ⚠ 有 N 条待消费  没人在跑但还有积压 -- 重挂一个 take 就能取走
+  ● 在跑      有 take 持锁,pid 是它
+  ○ 空闲 Nh   没人在跑,但最近用过 —— 重挂 take 接着盯
+  ⚠ 空闲 Nd   超过空闲期,下轮 gc 自动回收(不用手动清)
 
-游标位置早于扫描窗口时会附一句「<日期> 之前的已被 gc 回收」:
-那是既成损失(store 只保留几天),但**不影响窗口内还能取到的部分**。
+判据是**空闲多久**,不是落后多少条。落后量只作展示:
+它是遗弃的症状而不是反面 —— 被遗弃的游标落后会一路涨,
+拿它当清理判据会把该清的保护起来、该留的删掉(2026-09-06 实测)。
 
-排障入口:「○ 已消费完」而你以为它在盯 -> 它的 take 没起来或早退了;
+排障入口:「○ 空闲」而你以为它在盯 -> 它的 take 没起来或早退了;
 「无消费者」= 白采,可考虑 --exclude。
-清理已消费完的游标:lark-relay cursors --prune
 collect 行不是 running -> tail -f ~/.lark-relay/logs/collect.err.log
 (launchd 不进统一日志),collect 停摆的每一秒都在丢消息。`
 
-const CURSORS_HELP = `游标治理:看清哪些还在值守,清掉已经没用的。
+const CURSORS_HELP = `游标状态:谁在值守、空闲多久。**清理是自动的,不用你记。**
 
   lark-relay cursors                    # 列出全部游标及状态
-  lark-relay cursors --prune            # 清掉全部「已消费完」的
-  lark-relay cursors --prune <name>...  # 清指定身份的全部 app
-  lark-relay cursors --prune <name> --force   # 连「有积压」的一起清
+  lark-relay cursors --json             # 机器可读
+  lark-relay cursors --forget <name>... # 不等超期,现在就清掉
 
-状态:● 在跑 / ○ 已消费完 / ⚠ 有 N 条待消费但没人在跑
+状态:● 在跑 / ○ 空闲(最近用过)/ ⚠ 空闲超期(下轮 gc 回收)
 
-**判据只有一条:按这个游标续接还剩几条没消费。**
-  ● 在跑           不删。take 会立刻把游标写回来
-  ○ 已消费完       直接清。剩 0 条,删掉无损
-  ⚠ 有 N 条待消费  要 --force。删了那 N 条就跳过了;想要就重挂 take 取走
+**空闲超过 2 天的游标由 collect 自动回收**(每小时自查一次,与 store 的
+日期目录回收同一个 gc)。判据是「多久没人用过它」-- 与遗弃程度同向单调,
+且不需要人做判断。默认 2 天:take 是实时场景的取用口,
+空闲一两天以上再重挂,下一次消费一定从新的开始;要历史消息有专门的接口。
+改期限:LARK_RELAY_CURSOR_TTL_DAYS=<天>
 
-⚠️ 游标位置早于扫描窗口**不是**可删的理由(2026-09-06 实测纠正):
-那只说明「更早的一段已被 gc 回收」,而窗口内还在的事件老游标照样全部放行 --
-实测停在 D-5 的游标能取到窗口内 3 条,而 --since now 取到 0 条。
-按日期删游标或重置它,会静默丢掉这些消息。
+⚠️ 判据**不是**「落后多少条」,也不是「游标停在哪天」 -- 这两个都试过、都错了
+(方向反的,见下)。落后量只作展示。
 
-删的单位是 **app**,不是身份:一个 --name 可以同时盯多个 app,
-裸 --prune 只清其中已消费完的那些(在跑的静默跳过)。
-连带删该 app 的 dedup 记录(<app>.seen.json),不留会让重挂后头几条被误判重复。
+  ● 在跑的一律不回收 —— take 会立刻把游标写回来
+  被回收后重挂 = 按 --since now 起头,跳过那段已落盘的消息。
+  这正是「两天没人管」该有的行为;真要接着取,在超期前重挂就行
 
-退出码:0 正常,2 参数错或点名的身份不存在,
-3 点名的目标一个都没清掉(在跑,或需要 --force)`
+--forget 是逃生舱(验完了、现在就想清干净)。它不需要二次确认 --
+回收本来会自动发生,人只是提前几天。
+删的单位是 app 目录下的每个 app,连带删该 app 的 dedup 记录
+(<app>.seen.json),不留会让重挂后头几条被误判重复。
+
+退出码:0 正常,2 参数错或点名的身份不存在,3 点名的在跑(没清掉)`
 
 const GUIDE = `lark-relay -- Lark 事件中继站。两件事:收下来 / 我来取。
 
@@ -172,12 +172,10 @@ take 四步(照做)
      起来后 stderr 有一行「监听中」-- 没有就是没起来,看 stderr。
      一批处理完再起一个。不要自己写 while 循环 -- 进程退出会通知你。
      退出码:0=有一批,4=超时没消息(正常,再起一个),2=参数错,3=游标被占用。
-  4. 不盯了收尾  lark-relay cursors --prune
-     游标为「关了会话、过阵子接着盯」而存在,引擎不主动删还有积压的游标。
-     裸 --prune 只清「已消费完」的(删掉无损);还有待消费的会拦下来告诉你
-     会丢几条,确认不要才 --prune <name> --force。
-     不清的代价:status 里一直挂着积压数(它会随 store 过期变小,
-     看着像追上了,其实是消息永久没了)。
+  4. 不盯了就走开  什么都不用做
+     空闲超 2 天的游标由 collect 自动回收(每小时自查),不用你记得清理。
+     想立刻清干净:lark-relay cursors --forget <name>
+     看状态:lark-relay cursors(○ 空闲 / ⚠ 超期待回收 / ● 在跑)
 
 常见错误
   · 拿不到消息 -> 九成是 bot 不在群。验 bot 必须 --as user,

package/lib/status.js

@@ -84,10 +84,9 @@ async function buildStatus() {
       latestMs = Number(ev?.timestamp || ev?.create_time) || null
     }
     const cs = (byApp.get(app) || []).map((c) => {
-      // lag 直接用 listCursors 实测出来的 pending —— 它就是「按这个游标续接还剩几条」。
-      // ⚠️ 早先这里对 stale 游标刻意不算 lag,理由是「那个数字误导」。
-      // 实际反了:pending 一直是真实可取条数,误导的是当时那个 stale 判据本身
-      // (它以为老游标取不到东西,而老游标恰好全部放行)。现在只有一个口径
+      // lag = 实测待消费条数。它是**展示量,不是治理判据** ——
+      // 判据是空闲时长(见 lib/cursors.js):落后量是遗弃的症状,不是遗弃的反面,
+      // 拿它决定删不删会把「该清的保护起来、该留的删掉」(2026-09-06 实测)
       return {
         name: c.name,
         lag: c.pending,
@@ -95,7 +94,7 @@ async function buildStatus() {
         pid: c.pid,
         cursor: c.cursor,
         day: c.day,
-        lostSpan: c.lostSpan,
+        idleMs: c.idleMs,
       }
     })
     rows.push({ app, today: store.countToday(app), latestMs, consumers: cs })
@@ -130,7 +129,16 @@ 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 drainedCount = 0
+  let expiringCount = 0
+  const idleTxt = (ms) => {
+    if (!Number.isFinite(ms)) return '未知'
+    // 向下取整:这个数是回收判据,宁可少报不可多报 --
+    // Math.round 会把 2.5 天显示成「3d」,看着像已经超了 2 天的 TTL 更多
+    const m = Math.floor(ms / 60000)
+    if (m < 60) return `${m}m`
+    const h = Math.floor(m / 60)
+    return h < 48 ? `${h}h` : `${Math.floor(h / 24)}d`
+  }
   for (const r of s.apps) {
     // 消费者各占一行:状态要一眼分得清,挤在一行里 ●/○/⚠ 会被淹掉。
     // 「谁在跑」是排障第一问,以前得靠猜(全都长成 `name(落后 N 条)`)
@@ -145,24 +153,20 @@ function formatStatus(s) {
       if (c.state === 'live') {
         mark = '●'
         note = `在跑 (pid ${c.pid}, ${c.lag === 0 ? '游标追平' : `落后 ${c.lag} 条`})`
-      } else if (c.state === 'drained') {
-        drainedCount++
-        mark = '○'
-        note = '已消费完 (没人在跑,删掉无损)'
-      } else {
+      } else if (c.state === 'expiring') {
+        expiringCount++
         mark = '⚠'
-        note = `有 ${c.lag} 条待消费但没人在跑 —— 重挂 take 能接着取`
+        note = `空闲 ${idleTxt(c.idleMs)} —— 已超期,下轮 gc 自动回收`
+      } else {
+        mark = '○'
+        note = `空闲 ${idleTxt(c.idleMs)} (待消费 ${c.lag},重挂 take 接着盯)`
       }
-      // 位置早于扫描窗口:那之前的一段已被 gc 回收、找不回。
-      // 与「能不能删」无关(判据是上面的待消费数),但它是真实损失,必须说
-      if (c.lostSpan) note += `;${c.day} 之前的已被 gc 回收`
       out.push(`  ${w(c.name, 24)}${mark} ${note}`)
     }
   }
-  if (drainedCount) {
+  if (expiringCount) {
     out.push('')
-    out.push(`○ ${drainedCount} 个游标已消费完且没人在跑 —— 不盯了就清掉,留着只是噪音`)
-    out.push('  清理:lark-relay cursors --prune')
+    out.push(`⚠ ${expiringCount} 个游标已超空闲期 —— collect 每小时自查时回收,不用手动清`)
   }
 
   return out.join('\n')

package/lib/store.js

@@ -11,8 +11,8 @@ const { paths, ensureDir, eventFilename, dayKey, dayKeyOffset } = require('./pat
 //
 // ⚠️ 必须**等于** store 保留天数,不是「>= 就行」。两边差 1 会造出一个三不管的日子:
 // 2026-09-06 实测 SCAN_DAYS=4 / retain=3 时,D-3 被 gcStore 整目录删掉了,
-// 却仍被算作「窗口内」-> 停在那天的游标判成「可续接」、prune 还要 --force 才肯删,
-// 而那天的数据其实一条都不在了。方向反过来(窗口 < 保留)则是「留着却扫不到」。
+// 却仍被算作「窗口内」-> 停在那天的游标被当成「还能续接」,而那天的数据一条都不在了。
+// 方向反过来(窗口 < 保留)则是「留着却扫不到」。
 // 两个方向都错,所以判据不是不等式而是等号 —— 默认值就按等号配。
 //
 // 与 collect 的 --retain 是两个进程里的两个值,没法在运行时互相读取,
@@ -128,6 +128,35 @@ function writeCursor(name, app, key) {
   fs.renameSync(tmp, file)
 }
 
+// 把游标标记成「刚被用过」。回收判据是空闲时长(见 lib/cursors.js),
+// 而它读的是 mtime —— 所以「有人在用」必须能刷新 mtime。
+//
+// ⚠️ 为什么不能只靠 writeCursor 顺带刷新:take 的 abort 路径是
+// `if (batch.length && commit) writeCursor` —— **空手被 SIGTERM 时不写**。
+// 实测:游标写入后起一个 take、3 秒后 kill,mtime 一动不动。
+// 于是「一个安静的群盯了两天没消息」会被误判成遗弃并回收。
+// 故 take 启动时显式 touch 一次,让「有人来取过」这件事本身就算活动
+function touchCursor(name, app) {
+  const file = paths.cursor(name, app)
+  try {
+    const now = new Date()
+    fs.utimesSync(file, now, now)
+    return true
+  } catch {
+    return false // 还没有游标文件(首次跑),seedCursorNow 会建
+  }
+}
+
+// 游标最后一次被使用的时间(ms)。读不到返回 null。
+// mtime 而非 atime:atime 会被 status/cursors 的只读扫描刷新,那不算「在用」
+function cursorMtime(name, app) {
+  try {
+    return fs.statSync(paths.cursor(name, app)).mtimeMs
+  } catch {
+    return null
+  }
+}
+
 // --since now:游标落到当前最新,不重放历史。
 // 默认值反过来就消灭了旧架构 adhoc SOP 的「预热游标」那一步。
 function seedCursorNow(name, app) {
@@ -190,6 +219,8 @@ module.exports = {
   readEvent,
   readCursor,
   writeCursor,
+  touchCursor,
+  cursorMtime,
   seedCursorNow,
   afterCursor,
   entryKey,

package/package.json

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