lark-relay 0.4.13 → 0.4.14

package/bin/lark-relay.js

@@ -218,7 +218,7 @@ async function cmdTake(argv) {
 }
 
 function cmdCursors(argv) {
-  const CURSORS_FLAGS = ['prune', 'json', 'help']
+  const CURSORS_FLAGS = ['prune', 'force', '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) {
@@ -256,26 +256,36 @@ function cmdCursors(argv) {
 
   // --prune:位置参数是要删的身份;没给就只清 stale 的那些
   const names = a._
-  const res = cursors.prune(names)
+  const res = cursors.prune(names, { force: !!a.force })
 
   // 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 会立刻把游标写回来,删了是白删还让人以为清理生效了
+  // 在跑的不删 -- take 会立刻把游标写回来。只有显式点名时才报告(见 cursors.prune)
   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) {
+
+  // 「○ 暂停」的游标还能续接,删了就丢消费位置 -- 要 --force 再确认一次。
+  // 2026-09-06 真实踩到:点名删一个刚退出 take 的 idle 游标,那段消息的消费位置没了
+  for (const f of res.needForce) {
+    process.stderr.write(
+      `⚠ ${f.name}/${f.app} 是「○ 暂停」,位置 ${f.day} 仍在扫描窗口内\n` +
+        `  删了就丢续接凭据:重挂时会按 --since now 跳过这段已落盘的消息\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' : '没有 stale 游标,无需清理\n')
   }
-  // 退出码:点名的目标一个都没删成(全被拒/全不存在)才算失败 ——
-  // 裸 prune 顺带跳过一个在跑的游标不是错误,那次清理是成功的
+  // 点名的目标一个都没删成才算失败
   if (res.missing.length) return 2
-  if (res.refused.length && !res.removed.length && names.length) return 3
+  if ((res.refused.length || res.needForce.length) && !res.removed.length) return 3
   return 0
 }
 

package/lib/cursors.js

@@ -115,10 +115,13 @@ function removeStaleLock(name) {
 /**
  * 清理游标。
  * @param {string[]} names 指定要删的身份(该身份下全部 app);空数组 = 只删 stale 的那些 app
- * @returns {{removed:string[], refused:Array<{name:string,pid:number}>, missing:string[]}}
- *   removed 的元素形如 `name/app` -- 删的单位是 app,不是整个身份
+ * @param {{force?:boolean}} opts force 才允许删「○ 暂停」(窗口内)的游标
+ * @returns {{removed:string[], refused:Array<{name:string,pid:number}>, missing:string[],
+ *            needForce:Array<{name:string,app:string,day:string}>}}
+ *   removed 的元素形如 `name/app` -- 删的单位是 app,不是整个身份。
+ *   refused 只在**显式点名**时填充:裸 prune 遇到在跑的游标是静默跳过,不算例外
  */
-function prune(names = []) {
+function prune(names = [], opts = {}) {
   const all = listCursors()
   // 一个 name 可能有多个 app 行,按身份归并 -- live 判定是按身份的(锁以 name 为键)
   const byName = new Map()
@@ -130,6 +133,7 @@ function prune(names = []) {
   const removed = []
   const refused = []
   const missing = []
+  const needForce = []
 
   const targets = names.length ? names : [...byName.keys()]
 
@@ -139,23 +143,35 @@ function prune(names = []) {
       missing.push(name)
       continue
     }
-    // live 一律不删,即使显式点名:take 还在跑,它会立刻把游标写回来 --
-    // 删了是白删,还会让人以为清理没生效
     const live = rows.find((r) => r.state === 'live')
     if (live) {
-      refused.push({ name, pid: live.pid })
+      // 显式点名时必须解释为什么没删(用户明确要求了);
+      // 而裸 prune 的意图是「清掉失效的」-- 在跑的游标本就不在这个视野里,
+      // 报告它是噪音(实测:3 个 take 在跑时,一次日常清理吐 3 段无关提示)
+      if (names.length) refused.push({ name, pid: live.pid })
       continue
     }
     // 显式点名 = 清该身份的全部 app(用户明确不盯了);
     // 裸 prune = 只清 stale 的那些 app,窗口内的留着续接
     const victims = names.length ? rows : rows.filter((r) => r.state === 'stale')
+    let deletedAny = false
     for (const r of victims) {
-      if (removeCursorApp(name, r.app)) removed.push(`${name}/${r.app}`)
+      // ⚠️ 「○ 暂停」= 位置还在扫描窗口内,**删了就丢续接凭据**(重挂会按 --since now
+      // 跳过这段已落盘的消息)。stale 删掉无损,idle 不是 -- 故 idle 要 --force 兜一道。
+      // 2026-09-06 真实踩到:点名删一个刚退出 take 的 idle 游标,消费位置就此丢失
+      if (r.state === 'idle' && !opts.force) {
+        needForce.push({ name, app: r.app, day: r.day })
+        continue
+      }
+      if (removeCursorApp(name, r.app)) {
+        removed.push(`${name}/${r.app}`)
+        deletedAny = true
+      }
     }
-    if (victims.length) removeStaleLock(name)
+    if (deletedAny) removeStaleLock(name)
   }
 
-  return { removed, refused, missing }
+  return { removed, refused, missing, needForce }
 }
 
 module.exports = {

package/lib/help.js

@@ -120,21 +120,22 @@ const CURSORS_HELP = `游标治理:看清哪些还在值守,清掉已失效的
 
   lark-relay cursors                    # 列出全部游标及状态
   lark-relay cursors --prune            # 清掉全部 stale 的
-  lark-relay cursors --prune <name>...  # 清指定身份的全部 app(在跑的会跳过)
+  lark-relay cursors --prune <name>...  # 清指定身份的全部 app
+  lark-relay cursors --prune <name> --force   # 连「○ 暂停」的一起清
 
 三态:● 在跑 / ○ 暂停(窗口内,可续接) / ⚠ stale(超窗口,续接无意义)
 
+**只有 stale 是无条件可清的**:
+  ● 在跑    不删。take 会立刻把游标写回来
+  ○ 暂停    要 --force。它还能续接,删了重挂就按 --since now 跳过这段消息
+  ⚠ stale   直接清。那段消息 gc 已回收,续接和 --since now 等价 -> 删它无损
+
 删的单位是 **app**,不是身份:一个 --name 可以同时盯多个 app,
-裸 --prune 只清其中 stale 的那些,窗口内的留着续接(点名才整个身份清)。
+裸 --prune 只清其中 stale 的那些(在跑的静默跳过)。
 连带删该 app 的 dedup 记录(<app>.seen.json),不留会让重挂后头几条被误判重复。
 
-为什么 stale 能放心删:消费侧只扫最近几天的目录,更早的日期 collect 的 gc
-已整目录删掉。**续接一个超窗口的游标和 --since now 行为完全一样** --
-删它不会丢任何还取得到的消息,留着只会让 status 虚报积压。
-反过来,窗口内的「○ 暂停」不自动删 -- 那是「关了会话、过阵子接着盯」的续接凭据。
-
-退出码:0 正常(含「跳过了在跑的那个」),2 参数错或点名的身份不存在,
-3 点名的目标全在跑、一个都没清掉`
+退出码:0 正常,2 参数错或点名的身份不存在,
+3 点名的目标一个都没清掉(在跑,或需要 --force)`
 
 const GUIDE = `lark-relay -- Lark 事件中继站。两件事:收下来 / 我来取。
 

package/package.json

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