lark-relay 0.4.9 → 0.4.11

package/README.md

@@ -80,6 +80,12 @@ lark-relay take --app <app> --chats oc_xxx --render text
 多消费者**共享 store、各持游标**,不做「处理完即删」-- 谁都不能替别人删。
 盯同一 app 请用不同 `--name` 隔离游标。
 
+**游标要自己收尾**:它是「关了会话、过阵子接着盯」的续接凭据,所以引擎**不会**
+自动清理不活跃的游标 -- 自动清掉就等于下次重挂要么全量重放、要么跳过停机期的消息。
+代价是不再用的游标会一直留在 `status` 里显示「落后 N 条」,而 store 只保留几天,
+那个 N 会随过期删除而变小(**看着像追上了,其实是消息没了**)。
+一次性监听、验完的排查、不再值守的任务,收尾时 `rm -rf ~/.lark-relay/cursors/<name>`。
+
 ## 设计取舍
 
 - **原子落盘**:collect 读 stdout NDJSON 后自己 `写 .tmp -> rename`(同目录原子)。

package/bin/lark-relay.js

@@ -17,21 +17,21 @@ const COMMANDS = ['take', 'status', 'guide']
 
 // collect 搬家提示。能力是**搬走了不是删了**,所以不能只说「未知命令」
 const MOVED_HINT =
-  `collect 已拆成独立命令 —— 它是常驻服务,不该和在场取用挤在一个入口:\n` +
+  `collect 已拆成独立命令 -- 它是常驻服务,不该和在场取用挤在一个入口:\n` +
   `  lark-relay-collect            # 前台跑(调试)\n` +
   `  lark-relay-collect --help     # 参数与常驻部署\n` +
   `同一个包就带,不用另外装。\n`
 
-const USAGE = `lark-relay ${VERSION} —— Lark 事件中继站(在场取用)
+const USAGE = `lark-relay ${VERSION} -- Lark 事件中继站(在场取用)
 
-  lark-relay take …             在场取用:阻塞等一批 → 输出 → 退出
+  lark-relay take ...           在场取用:阻塞等一批 -> 输出 -> 退出
   lark-relay status             谁在跑 / 各 app 积压 / 各游标位置
-  lark-relay guide              一页用法（装完先读这个）
+  lark-relay guide              一页用法(装完先读这个)
 
 采集底座是独立命令(常驻服务):lark-relay-collect
 
-第一次用 → lark-relay guide
-各命令详情 → lark-relay <命令> --help`
+第一次用 -> lark-relay guide
+各命令详情 -> lark-relay <命令> --help`
 
 async function main() {
   const argv = process.argv.slice(2)

package/lib/help.js

@@ -34,6 +34,8 @@ function takeHelp(apps) {
   --name <n>        游标身份,省略时按 app+chats 自动派生
   --filter <jq>     业务过滤,如 '.sender_id != "ou_xxx"'
   --debounce N      防抖秒数(默认 5;聊天场景建议 15)
+  --max-wait N      从第一条起最多攒多久就吐(默认 25 秒)
+  --timeout N       没消息时最多阻塞多久,到点空手退出码 4(默认 12 小时)
   --render text     按群分组紧凑文本(默认 NDJSON)
   --since now|all   起始位置(默认 now,不重放历史)
 
@@ -44,10 +46,12 @@ function takeHelp(apps) {
   4  超时没消息 -- 正常,再起一个继续
 
 最佳实践
-  · 用 run_in_background 起,不要前台跑 -- 会阻塞会话最长 12h
-  · 一批处理完再起下一个;不需要自己写 while 循环
-  · 拿不到消息先查第二步:bot 不在群是最常见原因
-  · 多个消费者盯同一 app 用不同 --name,游标互不干扰`
+  · 一直等不到消息 -> 九成是 bot 不在群,回第二步验(最常见故障)
+  · 多个消费者盯同一 app 用不同 --name,游标互不干扰
+  · 不盯了就删游标:rm -rf ~/.lark-relay/cursors/<name>
+    引擎不会自动清(它是跨会话续接的凭据)。留着会在 status 里一直挂
+    「落后 N 条」,而 store 只保留几天 -- N 会随过期删除而变小,
+    看着像追上了,其实是消息没了`
 }
 
 const COLLECT_HELP = `把全部 lark-cli profile 的事件收下来,原子落盘。零参数、零配置。
@@ -55,7 +59,7 @@ const COLLECT_HELP = `把全部 lark-cli profile 的事件收下来,原子落盘
   lark-relay-collect                    # 前台跑(调试)
   常驻:macOS 用 launchd(plist 模板见仓库 launchd/ 目录)
 
-独立可执行文件而非 \`lark-relay\` 的子命令 —— 它是常驻服务,服务管理器展示的是
+独立可执行文件而非 \`lark-relay\` 的子命令 -- 它是常驻服务,服务管理器展示的是
 可执行文件名,与 launchd label(com.adaex.lark-relay-collect)同名才认得出。
 
 app 列表实时读 \`lark-cli profile list\`,新增 profile 自动纳入,无需改配置。
@@ -67,18 +71,18 @@ tokenStatus 为 expired 的 profile 自动跳过并 warn(永久失败,重试是
 8s 后才起 consumer,收到 0 条)。collect 独立常驻,才能让 take 侧
 崩了、AI 跑 30 分钟、会话关几小时,都不丢消息。
 
-装完先 \`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 status\` 确认 -- collect 行应为 running;不在跑看日志:
+  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)。
 
 参数
   --exclude <apps>  排除指定 profile(逗号分隔)
-  --retain N        store 保留天数(默认 3)
+  --retain N        store 保留天数(默认 3,上限 4 = 消费侧扫描窗口;
+                    再大就会「留着却扫不到」,故硬拒)
 
 环境变量
   LARK_RELAY_LOG_MAX_MB  单个日志文件上限(默认 16),超了轮转
@@ -91,9 +95,10 @@ const STATUS_HELP = `一眼看清全局:谁在跑、积压多少、游标在哪
 
 排障入口:某消费者「落后」很多 -> 它的 take 没在跑或卡住;
 「无消费者」= 白采,可考虑 --exclude。
-collect 行不是 running -> 看服务日志(Linux journalctl;
-macOS \`tail -f ~/.lark-relay/logs/collect.err.log\` -- 不进统一日志),
-collect 停摆的每一秒都在丢消息。`
+不打算再盯的消费者要删游标(引擎不会自动清,积压数还会随 store 过期而虚假变小):
+  rm -rf ~/.lark-relay/cursors/<name>
+collect 行不是 running -> tail -f ~/.lark-relay/logs/collect.err.log
+(launchd 不进统一日志),collect 停摆的每一秒都在丢消息。`
 
 const GUIDE = `lark-relay -- Lark 事件中继站。两件事:收下来 / 我来取。
 
@@ -107,15 +112,18 @@ const GUIDE = `lark-relay -- Lark 事件中继站。两件事:收下来 / 我来
   不在跑 -> 起常驻服务(macOS launchd,plist 模板见仓库;
            或 \`lark-relay-collect\` 前台调试)
 
-take 三步(照做)
+take 四步(照做)
   1. 查群 ID   lark-cli --profile <app> im +chat-search --as user --query "<群名>"
   2. 验 bot 在群  lark-cli --profile <app> im chat.members bots --as user \\
                     --params '{"chat_id":"oc_xxx"}'
   3. 监听(用 run_in_background 起,别前台)
      lark-relay take --app <app> --chats oc_xxx --render text
-  起来后 stderr 有一行「监听中」-- 没有就是没起来,看 stderr。
-  一批处理完再起一个。不要自己写 while 循环 -- 进程退出会通知你。
-  退出码:0=有一批,4=超时没消息(正常,再起一个),2=参数错,3=游标被占用。
+     起来后 stderr 有一行「监听中」-- 没有就是没起来,看 stderr。
+     一批处理完再起一个。不要自己写 while 循环 -- 进程退出会通知你。
+     退出码:0=有一批,4=超时没消息(正常,再起一个),2=参数错,3=游标被占用。
+  4. 不盯了收尾  rm -rf ~/.lark-relay/cursors/<name>
+     游标只为「关了会话、过阵子接着盯」而存在,引擎不会自动清。
+     临时监听、验完的排查、不再值守的任务,收尾时自己删掉
 
 常见错误
   · 拿不到消息 -> 九成是 bot 不在群。验 bot 必须 --as user,

package/package.json

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