lark-relay 0.5.1 → 0.6.1

package/README.md

@@ -7,7 +7,7 @@ Lark(飞书)事件中继站。两件事:**收下来** / **我来取**。
 
 ```bash
 npm i -g lark-relay      # 装出两个命令:lark-relay-collect(常驻)/ lark-relay(在场)
-lark-relay guide         # 装完先读这个
+lark-relay take          # 空参输出完整的照做指导
 ```
 
 ## 为什么需要它
@@ -39,17 +39,36 @@ Lark 事件是**流式**的 -- 进程不在的时刻,消息**永久丢失**,不
 lark-relay-collect            # 底座:全部 profile 各起 consume -> 原子落盘(常驻服务)
 
 lark-relay take …             # 阻塞等一批 -> 输出 -> 退出
-lark-relay status             # 谁在跑 / 各 app 积压 / 各游标位置
-lark-relay guide              # 一页用法
+lark-relay status             # 谁在跑 / 各 app 收了多少 / 游标在哪
 ```
 
+就这两件事。踩坑史见 `docs/lessons.md`,代码里只留指针。
+
 ### lark-relay-collect
 
 零参数、零配置。app 列表实时读 `lark-cli profile list`,新增 profile 自动纳入。
 未授权或授权过期的 profile 自动跳过并 warn(永久失败,重试是死循环)。
 
-每 app 一个子进程,某个挂了单独重启不影响其他。回收在本进程内每小时自查,
-删超期的整个日期目录 -- 不另起 gc 单元/timer。
+每 app 一个子进程,某个挂了单独重启不影响其他。同一 message_id 只落一次。
+回收在本进程内每小时自查(store 删超期日期目录、游标删空闲超期的)-- 不另起 gc 单元/timer。
+
+日志直写 stderr,每行带 ISO 时间戳(launchd 场景重定向到
+`~/.lark-relay/logs/collect.err.log`)。不做轮转 —— 实测约 10MB/年,
+嫌大就 `> ~/.lark-relay/logs/collect.err.log` 截断(launchd 持有 fd,别 rm)。
+### 常驻部署(macOS / launchd)
+
+要点三条,plist 自己写十来行就够:
+
+- 用 **LaunchDaemon**(装 `/Library/LaunchDaemons/`)+ `UserName` 降权到你自己。
+  不用 LaunchAgent —— 它要 GUI 登录才加载、登出即停,而事件零回放,停摆=丢消息
+- `ProgramArguments` 写绝对路径(`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。
 
 ### lark-relay take
 
@@ -64,6 +83,8 @@ lark-relay take --app <app> --chats oc_xxx --render text
 起来后 stderr 先打一行「监听中」-- 没这行就是没起来,看 stderr 报错。
 退出码:0=有一批,4=超时没消息(正常,再起一个),2=参数错,3=游标被占用。
 参数拼错(如 `--chat-id`)会硬失败并给出正确写法,不静默吞掉。
+枚举参数(`--render text|ndjson`、`--since now|all`)也走白名单,且在**阻塞之前**校验 --
+`--render` 只在吐批时生效,拼错若不当场拦下要等满一批才看得出格式不对。
 
 业务过滤只有 `--filter`(jq 表达式)一个口子,不为每个业务加参数。
 
@@ -80,24 +101,13 @@ lark-relay take --app <app> --chats oc_xxx --render text
 多消费者**共享 store、各持游标**,不做「处理完即删」-- 谁都不能替别人删。
 盯同一 app 请用不同 `--name` 隔离游标。
 
-**游标会自动回收**:空闲超过 2 天的游标由 collect 删掉(每小时自查一次,
-与 store 的日期目录回收同一个 gc)。判据是「多久没人用过它」——
-不需要你记得收尾,也不需要你判断该不该删。
-
-```bash
-lark-relay cursors                     # ● 在跑 / ○ 空闲 Nh / ⚠ 空闲超期待回收
-lark-relay cursors --forget <name>     # 不等超期,现在就清
-```
-
-为什么是空闲时长而不是「落后多少条」:落后量是**遗弃的症状,不是反面** ——
-被遗弃的游标落后会一路涨,拿它当判据会把该清的保护起来、该留的删掉
-(2026-09-06 实测)。空闲时长与遗弃程度同向单调。
-
-为什么 2 天够:take 是**实时场景**的取用口。空闲一两天以上再重挂,
-下一次消费一定从新的开始;要历史消息有专门的接口,不靠游标回放。
+**游标会自动回收**:空闲超过 2 天的由 collect 删掉(每小时自查,与 store 同一个 gc)。
+判据是「多久没人用过它」(mtime)—— 不需要你记得收尾,也不需要判断该不该删。
+看状态 `lark-relay status`;等不及就 `rm -rf ~/.lark-relay/cursors`。
 改期限:`LARK_RELAY_CURSOR_TTL_DAYS=<天>`。
 
-在跑的游标(有 take 持锁)一律不回收 —— take 会立刻把它写回来。
+为什么不是「落后多少条」:那个方向是反的,这条判据错过两次 --
+见 `docs/lessons.md#游标判据`。
 
 ## 设计取舍
 
@@ -106,11 +116,16 @@ lark-relay cursors --forget <name>     # 不等超期,现在就清
 - **一事件一文件 + 按天分目录**:不用追加式 NDJSON。因为多消费者共享 store 时
   两种方案都不能「处理完即删」,NDJSON 最大的优势(删除简单)失效,而它的 gc
   要按大小滚动 + 保留 N 个文件,反而比整目录删复杂
-- **两层去重**:cursor 管进度,`message_id` 管幂等(TTL 6h)。
-  collect 重启或 bus 重投时同一条消息会落成**新文件**,游标拦不住
+- **去重做在落盘侧**:collect 持 `Set<message_id>`,同一条消息在盘上只出现一次。
+  collect 重启或 bus 重投时它是**新文件**,游标拦不住 —— 所以不能只靠游标。
+  做在落盘侧而非每个消费者各存一份,游标目录才能只放游标
 - **`--chats` 只接 `oc_` 开头的 chat_id,不接群名**:群名可能匹配多个或匹配错群,
   而监听错群是**静默失败**(一直等一个永不来的消息)
 - **`--since` 默认 `now`**:不重放历史,消灭「预热游标」这一步
+- **不设扫描窗口**:消费侧扫盘上还在的全部日期。曾有个 3 天窗口,省 4ms,
+  换来「窗口必须正好等于 retain」的跨进程不变量
+- **体积预算**:`lib`+`bin` 超 1900 行 `npm test` 就红(`test/budget.test.js`)。
+  这个包只做两件事,防的是治理层长回来
 
 ## 许可
 

package/bin/lark-relay-collect.js

@@ -2,24 +2,17 @@
 'use strict'
 
 // lark-relay-collect —— 事件采集底座,常驻服务专用入口。
-//
-// 为什么独立成一个可执行文件、不做 `lark-relay collect` 子命令:
-// 这是个 LaunchDaemon,服务管理器展示的是 ProgramArguments[0]。
-// 挤在通用 CLI 里时 `launchctl print` 的 program 栏是 `lark-relay`、`ps` 的 COMM
-// 是裸 `node` —— 看不出这是常驻服务。独立后 bin 名与 launchd label
-// (com.adaex.lark-relay-collect)同名,好搜好认。
-//
+// 独立成可执行文件而非子命令:launchd 展示的是 ProgramArguments[0],
+// 与 label(com.adaex.lark-relay-collect)同名才认得出。
 // 采集逻辑全在 lib/collect.js,本文件只做参数解析与进程身份。
 
 require('../lib/utf8').ensureUtf8()
 
-// ps/top 里显示成自己的名字,不再是裸 node(实测 macOS 与 Linux 都生效)。
-// 排障第一步常是 `ps | grep`,进程认不出来会先浪费一轮
+// ps/top 里显示成自己的名字,不再是裸 node -- 排障第一步常是 `ps | grep`
 process.title = 'lark-relay-collect'
 
 const { parseArgs, numStrict, list, rejectUnknown } = require('../lib/args')
 const help = require('../lib/help')
-const store = require('../lib/store')
 
 const VERSION = require('../package.json').version
 const PROG = 'lark-relay-collect'
@@ -34,11 +27,9 @@ async function main() {
     return 0
   }
 
-  // ⚠️ 短横线别名与 help 必须在 parseArgs **之前**拦。
-  // parseArgs 只认 `--xxx`:`-h` 既不置 a.help、也不进 _unknown(不以 -- 开头),
-  // 会一路穿到 runCollect() —— 实测「敲 -h 求帮助,结果起了一个 daemon」。
-  // 那会抢线上 daemon 的 event bus(同一 app 服务端只放行一个),线上那个要
-  // 退避重连数分钟。**帮助命令导致丢消息**,反直觉到不会有人怀疑
+  // ⚠️ 短横线别名与 help 必须在 parseArgs **之前**拦:parseArgs 只认 `--xxx`,
+  // `-h` 会一路穿到 runCollect() 起一个 daemon 去抢线上的 bus。
+  // **帮助命令导致丢消息** -- 见 docs/lessons.md#静默失败
   if (argv[0] === '--help' || argv[0] === '-h' || argv[0] === 'help') {
     process.stdout.write(`${help.COLLECT_HELP}\n`)
     return 0
@@ -51,32 +42,22 @@ async function main() {
     return 0
   }
 
-  // 本命令没有子命令,位置参数一律是敲错了 —— 静默吞掉违反本仓铁律
-  // (见 lib/args.js:4-6:拼错参数必须当场失败)。
-  // 最可能被敲的正是 `lark-relay-collect collect`:人记得有个 collect,
-  // 而它若静默起 daemon,又是一次「求助反而丢消息」
+  // 本命令没有子命令,位置参数一律是敲错了。最可能被敲的正是
+  // `lark-relay-collect collect`,它若静默起 daemon 又是一次「求助反而丢消息」
   if (a._.length) {
     const extra = a._.join(' ')
-    const hint = /^(collect|take|status|guide)$/.test(a._[0])
-      ? `\n采集就是本命令自己,不带子命令;take/status/guide 在 \`lark-relay\` 那边\n`
+    const hint = /^(collect|take|status)$/.test(a._[0])
+      ? `\n采集就是本命令自己,不带子命令;take/status 在 \`lark-relay\` 那边\n`
       : '\n'
     process.stderr.write(`${PROG} 不接位置参数,多了:${extra}${hint}跑 \`${PROG} --help\` 看用法\n`)
     return 2
   }
 
-  // retain 必须**正好等于**消费侧的扫描窗口。两个方向都是事故:
-  //   retain > 窗口:事件留在盘上却永远扫不到(store.js 那条注释警告的)
-  //   retain < 窗口:窗口最老那几天已被 gc 删空,却仍被算作「窗口内」——
-  //                  停在那里的游标判成「可续接」,而数据一条都不在了
-  //                  (2026-09-06 实测 retain=3 / 窗口=4 的 D-3 就是这种空档)
-  // 两个值在两个进程里,只能在这里把不变量钉死:装完新版直接起不来,好过悄悄丢
-  const retain = numStrict(a.retain, store.SCAN_DAYS)
-  if (retain === null || retain !== store.SCAN_DAYS) {
-    process.stderr.write(
-      `--retain 必须等于消费侧扫描窗口 ${store.SCAN_DAYS} 天,当前:${a.retain}\n` +
-        `要改保留期就同时改两边:LARK_RELAY_SCAN_DAYS=<N> 且 --retain <N>。\n` +
-        `留得比窗口久 -> 事件在盘上却扫不到;短于窗口 -> 空目录被当成「还能续接」\n`,
-    )
+  // store 保留天数。消费侧扫盘上还在的全部日期,所以这里改多少都自洽,
+  // 不再有「窗口必须正好等于 retain」那条跨进程不变量(见 docs/lessons.md#扫描窗口)
+  const retain = numStrict(a.retain, 3)
+  if (retain === null || !(retain >= 1)) {
+    process.stderr.write(`--retain 需要 >= 1 的天数,当前:${a.retain === true ? '(没给值)' : a.retain}\n`)
     return 2
   }
 

package/bin/lark-relay.js

@@ -3,34 +3,23 @@
 
 require('../lib/utf8').ensureUtf8()
 
-const { parseArgs, numStrict, suggest, rejectUnknown } = require('../lib/args')
+const { parseArgs, numStrict, rejectUnknown } = require('../lib/args')
 const help = require('../lib/help')
 
 const VERSION = require('../package.json').version
 
 // 带值参数白名单(布尔开关在 parseArgs 的 flags 里)。
-// 不在白名单的 --xxx 一律硬报错 —— 拼错参数静默吞掉是实测事故:
-// --chat-id 拼错 -> 打印用法退出,看着像「正常退出但没消息」,漏看 bot 第一条 Working
+// 不在白名单的 --xxx 一律硬报错 —— 拼错参数静默吞掉是实测事故,见 docs/lessons.md#静默失败
 const TAKE_KEYS = ['app', 'chats', 'name', 'filter', 'debounce', 'max-wait', 'timeout', 'render', 'since']
 
-const COMMANDS = ['take', 'status', 'cursors', 'guide']
-
-// collect 搬家提示。能力是**搬走了不是删了**,所以不能只说「未知命令」
-const MOVED_HINT =
-  `collect 已拆成独立命令(同一个包就带,不用另外装):\n` +
-  `  lark-relay-collect --help     # 前台调试与常驻部署\n`
-
 const USAGE = `lark-relay ${VERSION} -- Lark 事件中继站(在场取用)
 
   lark-relay take ...           在场取用:阻塞等一批 -> 输出 -> 退出
-  lark-relay status             谁在跑 / 各 app 积压 / 各游标位置
-  lark-relay cursors            游标状态:谁在值守 / 空闲多久(超期自动回收)
-  lark-relay guide              一页用法(装完先读这个)
+  lark-relay status             谁在跑 / 各 app 收了多少 / 游标在哪
 
-采集底座是独立命令(常驻服务):lark-relay-collect
+采集底座是独立的常驻命令:lark-relay-collect
 
-第一次用 -> lark-relay guide
-各命令详情 -> lark-relay <命令> --help`
+用法详情 -> lark-relay take(空参就是完整指导)`
 
 async function main() {
   const argv = process.argv.slice(2)
@@ -47,33 +36,17 @@ async function main() {
   }
 
   switch (cmd) {
-    case 'guide':
-      process.stdout.write(`${help.GUIDE}\n`)
-      return 0
     case 'take':
       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」--
-    // 那会让人以为采集功能被删了。**能力是搬家,不是消失,提示必须给出新名字**
+    // 能力是**搬家不是删除**,提示必须给出新名字,否则会被当成功能没了
     case 'collect':
-      process.stderr.write(MOVED_HINT)
+      process.stderr.write('采集是独立命令(同一个包就带):lark-relay-collect --help\n')
       return 2
-    default: {
-      // 拼错 collect(collectt / colect)同样走搬家提示 —— 意图明显是采集,
-      // 给「未知命令」等于让人以为功能没了。判据:编辑距离 <=2 且不像任何现有命令
-      if (suggest(cmd, ['collect']) === 'collect' && !suggest(cmd, COMMANDS)) {
-        process.stderr.write(`未知命令:${cmd}。${MOVED_HINT}`)
-        return 2
-      }
-      const s = suggest(cmd, COMMANDS)
-      process.stderr.write(`未知命令:${cmd}${s ? `。你是不是想写 ${s}?` : ''}\n\n${USAGE}\n`)
+    default:
+      process.stderr.write(`未知命令:${cmd}\n\n${USAGE}\n`)
       return 2
-    }
   }
 }
 
@@ -84,7 +57,7 @@ async function cmdTake(argv) {
 
   // 空参数输出完整照做指导,而非报错 -- AI 的真实行为是「先空参数跑一下看看」。
   // 但带了参数又缺 app/chats 的走下面短错误 -- 打印完整用法和 --help 长得一样,
-  // 会被当成「正常退出但没消息」(实测漏看 bot 第一条 Working)。
+  // 会被当成「正常退出但没消息」
   if (a.help || argv.length === 0) {
     let apps = []
     try {
@@ -130,38 +103,31 @@ async function cmdTake(argv) {
     return 3
   }
 
-  // --since 只有 now|all 两个取值。必须白名单校验:曾经是「跟 'now' 比一次,
-  // 其余全当 all」,于是 `--since Now`(大写)、`--since 乱码` 都静默变成全量重放。
-  // 与本仓「拼错参数当场硬失败」的铁律一致(args.js 开头那条)
+  // --since 只有 now|all 两个取值,必须白名单校验:曾经是「跟 'now' 比一次,
+  // 其余全当 all」,于是 `--since Now` 静默变成全量重放
   const since = a.since === true ? 'now' : a.since || 'now'
   if (since !== 'now' && since !== 'all') {
     process.stderr.write(`--since 只能是 now 或 all,当前:${since}\n`)
     return 2
   }
-  // 游标初始化:没有游标就按 --since now 起头(消灭旧架构「预热游标」那一步)。
-  //
-  // ⚠️ 2026-09-06 删掉了这里的「stale 自愈」。它曾在游标位置超出扫描窗口时
-  // 把游标**重置到当前最新**,理由写的是「续接它和 seed now 行为完全一样」。
-  // 那个理由是错的,实测证伪:afterCursor 比的是「事件日期 > 游标日期」,
-  // 游标越老放行的事件越多。实测游标停在 D-5、窗口内有 3 条未消费时,
-  //   保留游标 -> 取到 3 条    重置到 now -> 取到 0 条
-  // 也就是说那个「自愈」每次都在**静默丢掉窗口内的全部积压**。
-  // 现在:游标一律原样保留,能取到的照常取。
-  //
-  // 不再需要「位置早于窗口」那条告知了 —— 遗弃的游标由 collect 按空闲时长自动回收
-  // (见 lib/cursors.js),不靠位置推断,也不靠人清。
+  // --render 同理,且必须在阻塞之前校验:`--render tex` 曾静默退回 NDJSON,
+  // 而那要等满一批(最长 12h)才看得出来 —— 到时候批次已经吐成了错的格式
+  const mode = a.render === true ? 'text' : a.render || 'ndjson'
+  if (mode !== 'text' && mode !== 'ndjson') {
+    process.stderr.write(`--render 只能是 text 或 ndjson,当前:${mode}\n`)
+    return 2
+  }
+  // 没有游标就按 --since now 起头。已有的一律原样保留 ——
+  // 别「自愈」到最新,那会静默丢掉全部积压(见 docs/lessons.md#游标判据)
   if (since === 'now') {
     if (store.readCursor(name, a.app) === null) store.seedCursorNow(name, a.app)
   }
 
-  // 标记「有人来取过」。回收判据是空闲时长,而它读 mtime --
-  // ⚠️ 必须在这里显式 touch:take 的正常路径只在**有批次**时写游标,
-  // 空手超时/被 SIGTERM 都不写(实测起一个 take 再 kill,mtime 一动不动)。
-  // 不 touch 就会把「安静的群盯了两天没消息」误判成遗弃并回收
+  // 标记「有人来取过」:gc 判据是 mtime,而 take 空手退出时不写游标。
+  // 不 touch 会把「盯着一个安静的群」误判成遗弃
   store.touchCursor(name, a.app)
 
   // 时长参数校验:负数/非数字过去会静默退回默认值或原样生效
-  // (实测 --debounce -5 被接受并打印「防抖=-5s」,--timeout abc 悄悄变成 12 小时)
   const dur = (val, def, label) => {
     const n = numStrict(val, def)
     if (n === null || !(n >= 0)) {
@@ -177,7 +143,7 @@ async function cmdTake(argv) {
   const timeoutMs = dur(a.timeout, 12 * 3600, 'timeout')
 
   // 起来先打一行「监听中」-- 没这行就是没起来。
-  // 反馈实测:进程静默退出(参数错)被当成「在监听」,漏看 bot 第一条 Working
+  // 实测:进程静默退出(参数错)被当成「在监听」,漏看 bot 第一条 Working
   const fmtDur = (ms) => (ms >= 3600000 ? `${ms / 3600000}h` : `${ms / 1000}s`)
   process.stderr.write(
     `监听中:app=${a.app} 群=${chats.length} 个(${chats.join(',')}) 游标=${name} ` +
@@ -205,96 +171,11 @@ async function cmdTake(argv) {
     return res.reason === 'timeout' ? 4 : 0
   }
 
-  const mode = a.render === true ? 'text' : a.render
   process.stdout.write(`${render(res.events, mode)}\n`)
   process.stderr.write(`${res.events.length} 条,游标身份 ${name}\n`)
   return 0
 }
 
-// cursors:**只读展示 + 一个提前忘掉的逃生舱**。
-//
-// ⚠️ 这里曾有 --prune / --force 与一套「该不该删」的判断(2026-09-06 删)。
-// 删的理由不是简化:那套东西要求人拿着一个数字做破坏性决定,而**判据错了两次**
-// (先按游标日期、后按待消费数,方向都是反的 —— 见 lib/cursors.js 文件头)。
-// 现在回收由 collect 按空闲时长自动做,人不必判断,所以那些档位和确认步骤
-// 一起失去了存在理由。留一个 --forget 给「现在就想清干净」。
-function cmdCursors(argv) {
-  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) {
-    process.stdout.write(`${help.CURSORS_HELP}\n`)
-    return 0
-  }
-  const cursors = require('../lib/cursors')
-  const ttlDays = cursors.IDLE_TTL_DAYS
-
-  // 人话的空闲时长。回收判据就是这个数,所以它必须是最显眼的一列
-  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`
-  }
-
-  // 只读模式:列清单。删数据必须显式 --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')
-      return 0
-    }
-    const mark = { live: '●', idle: '○', expiring: '⚠' }
-    const note = {
-      live: (r) => `在跑 (pid ${r.pid}, 待消费 ${r.pending})`,
-      idle: (r) => `空闲 ${idleTxt(r.idleMs)}(待消费 ${r.pending},重挂 take 接着盯)`,
-      expiring: (r) => `空闲 ${idleTxt(r.idleMs)} 超 ${ttlDays} 天 -> 下轮 gc 自动回收`,
-    }
-    for (const r of rows) {
-      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(
-        `\n${expiring} 个已超 ${ttlDays} 天空闲,collect 每小时自查时会回收 —— 不用手动清\n`,
-      )
-    }
-    return 0
-  }
-
-  // --forget <name>...:不等 TTL,现在就清
-  const names = a._
-  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.missing) process.stderr.write(`没有这个游标身份:${n}\n`)
-  for (const r of res.refused) {
-    process.stderr.write(
-      `跳过 ${r.name}:有 take 正在用它(pid ${r.pid})。\n` +
-        `  要清它先停掉那个 take(kill ${r.pid}),否则它会把游标立刻写回来。\n`,
-    )
-  }
-
-  if (res.missing.length) return 2
-  if (res.refused.length && !res.removed.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', a._unknown, ['json'])
@@ -311,10 +192,8 @@ async function cmdStatus(argv) {
 
 main()
   .then((code) => {
-    // ⚠️ 不能用 process.exit() —— stdout 是管道时它会丢掉未 flush 的缓冲。
-    // 实测:400 条 NDJSON 重定向到文件得 676070 字节,同样数据接管道只收到
-    // 65536(管道缓冲上限)且切在 JSON 中途,而 stderr 照报「400 条」。
-    // 设 exitCode 让事件循环自然排空,退出码语义不变
+    // ⚠️ 不能用 process.exit():stdout 是管道时它会丢掉未 flush 的缓冲
+    // (实测 676KB 只收到 65536 且切在 JSON 中途)。见 docs/lessons.md#管道截断
     process.exitCode = code || 0
   })
   .catch((err) => {

package/lib/args.js

@@ -67,67 +67,19 @@ function list(v) {
     .filter(Boolean)
 }
 
-function levenshtein(a, b) {
-  const m = a.length
-  const n = b.length
-  const dp = Array.from({ length: m + 1 }, (_, i) => [i, ...Array(n).fill(0)])
-  for (let j = 0; j <= n; j++) dp[0][j] = j
-  for (let i = 1; i <= m; i++) {
-    for (let j = 1; j <= n; j++) {
-      dp[i][j] = Math.min(
-        dp[i - 1][j] + 1,
-        dp[i][j - 1] + 1,
-        dp[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1),
-      )
-    }
-  }
-  return dp[m][n]
-}
-
-// 拼错参数时给个候选:编辑距离 <= 2,或前 4 字符前缀相同(--chat-id -> --chats)。
-// 都不沾边返回 null,不硬猜。
-function suggest(unknown, allowed) {
-  let best = null
-  let bestD = Infinity
-  for (const k of allowed) {
-    const d = levenshtein(unknown, k)
-    if (d < bestD) {
-      bestD = d
-      best = k
-    }
-  }
-  if (bestD <= 2) return best
-  if (unknown.length >= 4) {
-    const hit = allowed.find((k) => k.startsWith(unknown.slice(0, 4)))
-    if (hit) return hit
-  }
-  return null
-}
-
-// 未知参数 -> stderr 短错误 + 候选提示,exit 2。
-// 不打印完整用法 -- 那看着像 --help 成功,会被当成「正常退出但没消息」
+// 未知参数 -> stderr 短错误 + 合法参数清单,exit 2。
+// 不打印完整用法 -- 那看着像 --help 成功,会被当成「正常退出但没消息」。
 //
-// ⚠️ `prog` 必须由调用方传入,不能写死 'lark-relay':两个 bin 共用这段,
-// 而提示里那行是要照抄执行的 —— 打出一个不存在的命令
-// (如已拆走的 `lark-relay collect`)会把人引向死路。
-// lark-relay 传 `lark-relay <子命令>`,lark-relay-collect 传自己的名字。
+// 直接列出全部合法参数,不做编辑距离猜测:参数总共 9 个,列出来比猜一个更有用
+// (曾有 50 行 levenshtein + suggest 干这件事)。
 //
-// 注:2026-09-06 删掉了 rewriteArgv(把整条 argv 重写成可照跑的命令行,约 35 行)。
-// 它是纯投机 —— 参数总共 9 个,`suggest` 已经点名了该写哪个,
-// 再拼一条完整命令行属于替调用方猜意图,而那 35 行要长期跟着参数表走
+// ⚠️ `prog` 必须由调用方传入:两个 bin 共用这段,而提示里那行是要照抄执行的 --
+// 打出一个不存在的命令会把人引向死路
 function rejectUnknown(prog, unknown, allowed, out = process.stderr) {
-  const names = [...new Set(unknown)]
-  const shown = names.map((k) => `--${k}`).join(', ')
-  let hint = ''
-  for (const k of names) {
-    const s = suggest(k, allowed)
-    if (s) {
-      hint = `\n你是不是想写 --${s}?`
-      break
-    }
-  }
-  out.write(`未知参数:${shown}${hint}\n跑 \`${prog}\` 看完整用法\n`)
+  const shown = [...new Set(unknown)].map((k) => `--${k}`).join(', ')
+  const list = allowed.map((k) => `--${k}`).join(' ')
+  out.write(`未知参数:${shown}\n可用参数:${list}\n跑 \`${prog}\` 看完整用法\n`)
   return 2
 }
 
-module.exports = { parseArgs, numStrict, list, suggest, rejectUnknown }
+module.exports = { parseArgs, numStrict, list, rejectUnknown }