lark-relay 0.4.0 → 0.4.2

package/README.md

@@ -12,7 +12,7 @@ lark-relay guide          # 装完先读这个
 
 ## 为什么需要它
 
-Lark 事件是**流式**的 —— 进程不在的时刻,消息**永久丢失**,不是延迟送达
+Lark 事件是**流式**的 -- 进程不在的时刻,消息**永久丢失**,不是延迟送达
 (实测:消息发出 8 秒后才起 consumer,收到 0 条)。
 
 所以要有一个常驻进程只管把事件收下来落盘,消费侧崩了、AI 跑了半小时、
@@ -29,13 +29,13 @@ Lark 事件是**流式**的 —— 进程不在的时刻,消息**永久丢失**,
 | 谁能干 | 任何 agent(Claude Code / Codex / 手敲) | 需内置唤起知识 |
 | 配置 | 纯参数,无文件 | `dispatch.yaml` |
 
-你(AI)在会话里盯群 → `take`。无人在场也要干活 → `dispatch`。
+你(AI)在会话里盯群 -> `take`。无人在场也要干活 -> `dispatch`。
 
 ## 命令
 
 ```bash
-lark-relay collect            # 底座:全部 profile 各起 consume → 原子落盘(systemd 常驻)
-lark-relay take …             # 场景1:阻塞等一批 → 输出 → 退出
+lark-relay collect            # 底座:全部 profile 各起 consume -> 原子落盘(systemd 常驻)
+lark-relay take …             # 场景1:阻塞等一批 -> 输出 -> 退出
 lark-relay dispatch <task>    # 场景2:常驻循环 = take + 唤起 claude
 lark-relay status             # 谁在跑 / 各 app 积压 / 各游标位置
 lark-relay guide              # 一页用法
@@ -47,24 +47,27 @@ lark-relay guide              # 一页用法
 未授权或授权过期的 profile 自动跳过并 warn(永久失败,重试是死循环)。
 
 每 app 一个子进程,某个挂了单独重启不影响其他。回收在本进程内每小时自查,
-删超期的整个日期目录 —— 不另起 gc 单元/timer。
+删超期的整个日期目录 -- 不另起 gc 单元/timer。
 
 ### take
 
-只有一种形态:**阻塞等 → 有一批就输出 → 退出**。循环交给 harness ——
+只有一种形态:**阻塞等 -> 有一批就输出 -> 退出**。循环交给 harness --
 Claude Code 用 `run_in_background` 起,进程退出会主动通知 AI,这才是事件驱动。
 
 ```bash
 lark-relay take --app <app> --chats oc_xxx --render text
 ```
 
-空参数跑一下会输出完整的照做指导(查群 ID → 验 bot 在群 → 监听三步)。
+空参数跑一下会输出完整的照做指导(查群 ID -> 验 bot 在群 -> 监听三步),exit 0。
+起来后 stderr 先打一行「监听中」-- 没这行就是没起来,看 stderr 报错。
+退出码:0=有一批,4=超时没消息(正常,再起一个),2=参数错,3=游标被占用。
+参数拼错(如 `--chat-id`)会硬失败并给出改写后的命令,不静默吞掉。
 
 业务过滤只有 `--filter`(jq 表达式)一个口子,不为每个业务加参数。
 
 ### dispatch
 
-任务发现:扫 `$LR_ROOT/*/dispatch.yaml` —— 有文件即是任务,无需注册表。
+任务发现:扫 `$LR_ROOT/*/dispatch.yaml` -- 有文件即是任务,无需注册表。
 `dispatch` 内部就是调 `take`,保证两场景不实现分叉。
 
 ```yaml
@@ -77,7 +80,7 @@ filter: '.mentions[]?.id == "ou_xxx"'   # 可选
 # model: <名称>      默认走终端同一套默认路由
 ```
 
-`mode` 三个场景 —— 一个键定死全部行为,不用拼组合:
+`mode` 三个场景 -- 一个键定死全部行为,不用拼组合:
 
 | | `work`(默认) | `chat` | `agent` |
 |---|---|---|---|
@@ -90,18 +93,18 @@ filter: '.mentions[]?.id == "ou_xxx"'   # 可选
 
 `agent` 是给「**多数轮该沉默**」的场景准备的:群运营里绝大多数消息不需要回应,
 而 `work`/`chat` 的提示词都承诺「你的最终回复会被发回群」,等于逼模型每轮说话。
-`agent` 模式下引擎只负责拉起模型、传消息批次、记台账 —— 发不发、回哪条、
+`agent` 模式下引擎只负责拉起模型、传消息批次、记台账 -- 发不发、回哪条、
 用哪个 bot 身份、发文字还是表情回应,全由模型按 `instructions` 决定(它有
 Bash + lark-cli)。沉默的轮也会进台账,便于事后看它到底判了多少次。
 
 这与「引擎不做权限管控」是同一条思路:**引擎不做回复决策,边界靠 instructions
 到达模型侧**。
 
-`work` 的过程与结论是**两条消息** —— COT 消息只承载过程(接口的设计前提),
+`work` 的过程与结论是**两条消息** -- COT 消息只承载过程(接口的设计前提),
 结论另发一条卡片。卡片发送失败会自动降级纯文本,保证结论必达。
 
 ⚠️ **COT 要求客户端 PC ≥ 7.70 / 移动 ≥ 7.74**:老客户端上那条过程消息显示为
-「Completed」(不会崩),结论卡片不受影响 —— 这也是「结论单独发」的价值。
+「Completed」(不会崩),结论卡片不受影响 -- 这也是「结论单独发」的价值。
 
 环境变量:`LR_COT_BATCH_MS`(COT 攒批窗口,默认 1000)、
 `LR_COT_SAY_AS=text|reasoning`(中间文本走正式文本流还是思考流,默认 `text`;
@@ -119,13 +122,13 @@ Bash + lark-cli)。沉默的轮也会进台账,便于事后看它到底判了多
 判据:能随时删掉重建的才放这里。`ledger` 是唯一不能重建的东西
 (session 会因空闲滚动/过期丢上下文,结论不能丢),走文件系统级备份。
 
-多消费者**共享 store、各持游标**,不做「处理完即删」—— 谁都不能替别人删。
+多消费者**共享 store、各持游标**,不做「处理完即删」-- 谁都不能替别人删。
 盯同一 app 请用不同 `--name` 隔离游标。
 
 ## 设计取舍
 
-- **原子落盘**:collect 读 stdout NDJSON 后自己 `写 .tmp → rename`(同目录原子)。
-  不用 `--output-dir` —— 它先建 0 字节再填充,消费侧游标可能跨过半成品导致事件永久丢失
+- **原子落盘**:collect 读 stdout NDJSON 后自己 `写 .tmp -> rename`(同目录原子)。
+  不用 `--output-dir` -- 它先建 0 字节再填充,消费侧游标可能跨过半成品导致事件永久丢失
 - **一事件一文件 + 按天分目录**:不用追加式 NDJSON。因为多消费者共享 store 时
   两种方案都不能「处理完即删」,NDJSON 最大的优势(删除简单)失效,而它的 gc
   要按大小滚动 + 保留 N 个文件,反而比整目录删复杂

package/bin/lark-relay.js

@@ -8,11 +8,74 @@ if (!/utf-?8/i.test(process.env.LC_ALL || process.env.LC_CTYPE || process.env.LA
   process.env.LC_ALL = 'C.UTF-8'
 }
 
-const { parseArgs, num, list } = require('../lib/args')
+const { parseArgs, num, list, suggest } = require('../lib/args')
 const help = require('../lib/help')
 
 const VERSION = require('../package.json').version
 
+// 各命令的带值参数白名单(布尔开关在 parseArgs 的 flags 里)。
+// 不在白名单的 --xxx 一律硬报错 —— 拼错参数静默吞掉是实测事故:
+// --chat-id 拼错 -> 打印用法退出,看着像「正常退出但没消息」,漏看 bot 第一条 Working
+const TAKE_KEYS = ['app', 'chats', 'name', 'filter', 'debounce', 'max-wait', 'timeout', 'render', 'since']
+const COLLECT_KEYS = ['exclude', 'retain', 'ledger-retain']
+
+// 未知参数 -> stderr 短错误 + 候选提示 + 改写后的命令,exit 2。
+// 不打印完整用法 -- 那看着像 --help 成功,会被当成「正常退出但没消息」
+function rejectUnknown(cmd, argv, unknown, allowed) {
+  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
+    }
+  }
+  const rewrite = rewriteArgv(argv, names, allowed)
+  const tail = rewrite.length
+    ? `\n你是不是想跑这个?\n  lark-relay ${cmd} ${rewrite.join(' ')}`
+    : ''
+  process.stderr.write(`未知参数:${shown}${hint}${tail}\n跑 \`lark-relay ${cmd}\` 看完整用法\n`)
+  return 2
+}
+
+// 把未知参数替换成候选,拼出可照跑的命令行;无候选的未知参数(连同它的值)丢弃
+function rewriteArgv(argv, unknown, allowed) {
+  const map = new Map()
+  for (const k of unknown) {
+    const s = suggest(k, allowed)
+    if (s && !map.has(k)) map.set(k, s)
+  }
+  if (!map.size) return []
+  const out = []
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a.startsWith('--') && a !== '--') {
+      const eq = a.indexOf('=')
+      const k = eq !== -1 ? a.slice(2, eq) : a.slice(2)
+      if (map.has(k)) {
+        out.push(eq !== -1 ? `--${map.get(k)}=${a.slice(eq + 1)}` : `--${map.get(k)}`)
+        if (eq === -1) {
+          const next = argv[i + 1]
+          if (next !== undefined && !next.startsWith('--')) {
+            out.push(next)
+            i++
+          }
+        }
+        continue
+      }
+      if (eq === -1) {
+        const next = argv[i + 1]
+        if (next !== undefined && !next.startsWith('--')) i++
+      }
+      continue
+    }
+    out.push(a)
+  }
+  return out
+}
+
 const USAGE = `lark-relay ${VERSION} —— Lark 事件中继站
 
   lark-relay collect            底座:全部 profile 各起 consume → 原子落盘（systemd 常驻）
@@ -50,14 +113,17 @@ async function main() {
       return await cmdStatus(rest)
     case 'dispatch':
       return await cmdDispatch(rest)
-    default:
-      process.stderr.write(`未知命令:${cmd}\n\n${USAGE}\n`)
+    default: {
+      const s = suggest(cmd, ['collect', 'take', 'dispatch', 'status', 'guide'])
+      process.stderr.write(`未知命令:${cmd}${s ? `。你是不是想写 ${s}?` : ''}\n\n${USAGE}\n`)
       return 2
+    }
   }
 }
 
 async function cmdCollect(argv) {
-  const a = parseArgs(argv, { flags: ['help'] })
+  const a = parseArgs(argv, { flags: ['help'], keys: COLLECT_KEYS })
+  if (a._unknown.length) return rejectUnknown('collect', argv, a._unknown, COLLECT_KEYS)
   if (a.help) {
     process.stdout.write(`${help.COLLECT_HELP}\n`)
     return 0
@@ -71,17 +137,20 @@ async function cmdCollect(argv) {
 }
 
 async function cmdTake(argv) {
-  const a = parseArgs(argv, { flags: ['help'] })
+  const a = parseArgs(argv, { flags: ['help'], keys: TAKE_KEYS })
+  if (a._unknown.length) return rejectUnknown('take', argv, a._unknown, TAKE_KEYS)
   const larkcli = require('../lib/larkcli')
 
-  // 空参数输出完整照做指导,而非报错 —— AI 的真实行为是「先空参数跑一下看看」
-  if (a.help || (!a.app && !a.chats)) {
+  // 空参数输出完整照做指导,而非报错 -- AI 的真实行为是「先空参数跑一下看看」。
+  // 但带了参数又缺 app/chats 的走下面短错误 -- 打印完整用法和 --help 长得一样,
+  // 会被当成「正常退出但没消息」(实测漏看 bot 第一条 Working)。
+  if (a.help || argv.length === 0) {
     let apps = []
     try {
       apps = (await larkcli.listProfiles()).filter((p) => p.usable).map((p) => p.name)
     } catch {}
     process.stdout.write(`${help.takeHelp(apps)}\n`)
-    return a.help ? 0 : 2
+    return 0 // 空参 = 求教,和 --help 一样是成功路径
   }
 
   const store = require('../lib/store')
@@ -90,7 +159,7 @@ async function cmdTake(argv) {
   const { acquireExclusive } = require('../lib/lock')
 
   if (!a.app || a.app === true) {
-    process.stderr.write('需要 --app <name>。跑 `lark-relay take` 看完整用法\n')
+    process.stderr.write('需要 --app <name>(= lark-cli profile 名)。完整步骤跑 `lark-relay take`\n')
     return 2
   }
   const chats = parseChats(a.chats === true ? '' : a.chats)
@@ -129,6 +198,14 @@ async function cmdTake(argv) {
   const maxWaitMs = num(a['max-wait'], 25) * 1000
   const timeoutMs = num(a.timeout, 12 * 3600) * 1000
 
+  // 起来先打一行「监听中」-- 没这行就是没起来。
+  // 反馈实测:进程静默退出(参数错)被当成「在监听」,漏看 bot 第一条 Working
+  const fmtDur = (ms) => (ms >= 3600000 ? `${ms / 3600000}h` : `${ms / 1000}s`)
+  process.stderr.write(
+    `监听中:app=${a.app} 群=${chats.length} 个(${chats.join(',')}) 游标=${name} ` +
+      `防抖=${debounceMs / 1000}s 最长等=${fmtDur(timeoutMs)}\n`,
+  )
+
   const ac = new AbortController()
   const onSig = () => ac.abort()
   process.on('SIGTERM', onSig)
@@ -146,7 +223,7 @@ async function cmdTake(argv) {
   })
 
   if (!res.events.length) {
-    process.stderr.write(`没等到消息(${res.reason})。游标身份 ${name}\n`)
+    process.stderr.write(`没等到消息(${res.reason})。游标身份 ${name},正常退出,再起一个继续\n`)
     return res.reason === 'timeout' ? 4 : 0
   }
 
@@ -157,7 +234,8 @@ async function cmdTake(argv) {
 }
 
 async function cmdStatus(argv) {
-  const a = parseArgs(argv, { flags: ['json', 'help'] })
+  const a = parseArgs(argv, { flags: ['json', 'help'], keys: [] })
+  if (a._unknown.length) return rejectUnknown('status', argv, a._unknown, ['json'])
   if (a.help) {
     process.stdout.write(`${help.STATUS_HELP}\n`)
     return 0
@@ -170,7 +248,8 @@ async function cmdStatus(argv) {
 }
 
 async function cmdDispatch(argv) {
-  const a = parseArgs(argv, { flags: ['list', 'once', 'help'] })
+  const a = parseArgs(argv, { flags: ['list', 'once', 'help'], keys: [] })
+  if (a._unknown.length) return rejectUnknown('dispatch', argv, a._unknown, ['list', 'once'])
   if (a.help) {
     process.stdout.write(`${help.DISPATCH_HELP}\n`)
     return 0

package/lib/args.js

@@ -1,9 +1,14 @@
 'use strict'
 
 // 零依赖 argv 解析。只支持 --key value / --key=value / --flag。
+// spec.flags:布尔开关;spec.keys:带值选项。不在两者里的 --xxx 进 out._unknown,
+// 由调用侧硬报错 —— 拼错参数必须当场失败,不能静默吞掉
+// (实测:--chat-id 拼错 -> 打印用法退出,看着像「正常退出但没消息」,漏看 bot 第一条 Working)
 function parseArgs(argv, spec = {}) {
   const flags = new Set(spec.flags || [])
-  const out = { _: [] }
+  const keys = new Set(spec.keys || [])
+  const known = (k) => flags.has(k) || keys.has(k)
+  const out = { _: [], _unknown: [] }
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]
     if (a === '--') {
@@ -16,17 +21,26 @@ function parseArgs(argv, spec = {}) {
     }
     const eq = a.indexOf('=')
     if (eq !== -1) {
-      out[a.slice(2, eq)] = a.slice(eq + 1)
+      const k = a.slice(2, eq)
+      if (known(k)) out[k] = a.slice(eq + 1)
+      else out._unknown.push(k)
       continue
     }
     const key = a.slice(2)
+    if (!known(key)) {
+      out._unknown.push(key)
+      // 吞掉它的值,避免下一个非 -- 参数错位成位置参数
+      const next = argv[i + 1]
+      if (next !== undefined && !next.startsWith('--')) i++
+      continue
+    }
     if (flags.has(key)) {
       out[key] = true
       continue
     }
     const next = argv[i + 1]
     if (next === undefined || next.startsWith('--')) {
-      out[key] = true // 当成 flag,由调用侧校验
+      out[key] = true // 缺值,由调用侧校验
     } else {
       out[key] = next
       i++
@@ -49,4 +63,41 @@ function list(v) {
     .filter(Boolean)
 }
 
-module.exports = { parseArgs, num, list }
+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
+}
+
+module.exports = { parseArgs, num, list, suggest }

package/lib/help.js

@@ -1,7 +1,8 @@
 'use strict'
 
-// 帮助文本是 AI 的主入口 —— 实际行为是「先空参数跑一下看看」,
+// 帮助文本是 AI 的主入口 -- 实际行为是「先空参数跑一下看看」,
 // 故 take 空参输出必须是完整的照做指导,而非报错。
+// 所有提示按「AI 读到后下一步该做什么」来写:给完整命令、给退出码语义、给判据。
 //
 // ⚠️ 公网包:示例只用占位符(oc_xxx/<app>/ou_xxx),绝不含真实 chat_id/open_id/profile 名。
 
@@ -9,34 +10,41 @@ function takeHelp(apps) {
   const appLine = apps && apps.length ? apps.join(' ') : '(跑 `lark-cli profile list` 看)'
   return `需要 --app 和 --chats。监听要求 bot 已在群内。
 
-一、查群 ID（用户身份;bot 搜不到自己没加入的群）
+一、查群 ID(用户身份;bot 搜不到自己没加入的群)
   lark-cli --profile <app> im +chat-search --as user --query "<群名>"
-  → 取 oc_ 开头的 chat_id;多个匹配时向用户确认是哪个
+  -> 取 oc_ 开头的 chat_id;多个匹配时向用户确认是哪个
 
-二、验 bot 在群（用户身份;bot 不在群时用 bot 身份查不到,无法作判据）
+二、验 bot 在群(用户身份;bot 不在群时用 bot 身份查不到,不能作判据)
   lark-cli --profile <app> im chat.members bots --as user --params '{"chat_id":"oc_xxx"}'
-  → bots[] 含本 app 才算在群
-  → 不在群:请用户拉 bot 进群（对群可见动作,先征得同意）
+  -> bots[] 含本 app 才算在群
+  -> 不在群:请用户拉 bot 进群(对群可见动作,先征得同意)
 
-三、监听（Claude Code 用 run_in_background 起,有消息会自动通知你）
+三、监听(Claude Code 用 run_in_background 起,有消息会自动通知你)
   lark-relay take --app <app> --chats oc_xxx --render text
 
-  阻塞等消息,有一批就输出并退出（默认防抖 5s、最长等 12h）。
+  起来后 stderr 先打一行「监听中 ...」-- 没这行就是没起来,看 stderr 报错。
+  阻塞等消息,有一批就吐到 stdout 并退出(默认防抖 5s、最长等 12h)。
   处理完再起一个,如此循环。
 
-可用 app：${appLine}
+可用 app:${appLine}
 
 参数
   --app <name>      必填,= lark-cli profile 名
-  --chats <ids>     必填,oc_ 开头;逗号分隔多个;或 @文件（首列 chat_id）
+  --chats <ids>     必填,oc_ 开头;逗号分隔多个;或 @文件(首列 chat_id)
   --name <n>        游标身份,省略时按 app+chats 自动派生
   --filter <jq>     业务过滤,如 '.sender_id != "ou_xxx"'
-  --debounce N      防抖秒数（默认 5;聊天场景建议 15）
-  --render text     按群分组紧凑文本（默认 NDJSON）
-  --since now|all   起始位置（默认 now,不重放历史）
+  --debounce N      防抖秒数(默认 5;聊天场景建议 15)
+  --render text     按群分组紧凑文本(默认 NDJSON)
+  --since now|all   起始位置(默认 now,不重放历史)
+
+退出码
+  0  吐了一批(stdout);空参求教也是 0
+  2  参数错 -- stderr 有短错误和正确写法,照着重跑
+  3  游标身份被另一个 take 占用 -- 换 --name
+  4  超时没消息 -- 正常,再起一个继续
 
 最佳实践
-  · 用 run_in_background 起,不要前台跑 —— 会阻塞会话最长 12h
+  · 用 run_in_background 起,不要前台跑 -- 会阻塞会话最长 12h
   · 一批处理完再起下一个;不需要自己写 while 循环
   · 拿不到消息先查第二步:bot 不在群是最常见原因
   · 多个消费者盯同一 app 用不同 --name,游标互不干扰`
@@ -44,109 +52,113 @@ function takeHelp(apps) {
 
 const COLLECT_HELP = `把全部 lark-cli profile 的事件收下来,原子落盘。零参数、零配置。
 
-  lark-relay collect                    # 前台跑（调试）
-  systemctl enable --now lark-relay-collect   # 常驻（推荐）
+  lark-relay collect                    # 前台跑(调试)
+  systemctl enable --now lark-relay-collect   # 常驻(推荐)
 
 app 列表实时读 \`lark-cli profile list\`,新增 profile 自动纳入,无需改配置。
 每 app 一个子进程;某个挂了单独重启,不影响其他。
-tokenStatus 为 expired 的 profile 自动跳过并 warn（永久失败,重试是死循环）。
+tokenStatus 为 expired 的 profile 自动跳过并 warn(永久失败,重试是死循环)。
 用户重新 login 后下次启动自动纳入。
 
-为什么必须常驻:lark 事件是流式的,进程不在的时刻消息永久丢失（实测:消息发出
-8s 后才起 consumer,收到 0 条）。collect 独立常驻,才能让 take/dispatch 侧
+为什么必须常驻:lark 事件是流式的,进程不在的时刻消息永久丢失(实测:消息发出
+8s 后才起 consumer,收到 0 条)。collect 独立常驻,才能让 take/dispatch 侧
 崩了、claude 跑 30 分钟、会话关几小时,都不丢消息。
 
 落盘:~/.lark-relay/store/<app>/<YYYY-MM-DD>/<纳秒>_<pid>_<seq>.json
-回收由 collect 进程内每小时自查一次,删超期的整个日期目录（不另起 gc 单元/timer）。
+回收由 collect 进程内每小时自查一次,删超期的整个日期目录(不另起 gc 单元/timer)。
 
 参数
-  --exclude <apps>  排除指定 profile（逗号分隔）
-  --retain N        store 保留天数（默认 3）
-  --ledger-retain N ledger 保留天数（默认 90）`
+  --exclude <apps>  排除指定 profile(逗号分隔)
+  --retain N        store 保留天数(默认 3)
+  --ledger-retain N ledger 保留天数(默认 90)`
 
 const STATUS_HELP = `一眼看清全局:谁在跑、积压多少、游标在哪。
 
   lark-relay status              # 概览
   lark-relay status --json       # 机器可读
 
-排障入口:某消费者「落后」很多 → 它的 take/dispatch 没在跑或卡住;
+排障入口:某消费者「落后」很多 -> 它的 take/dispatch 没在跑或卡住;
 「无消费者」= 白采,可考虑 --exclude。`
 
-const DISPATCH_HELP = `常驻:等消息 → 唤起 claude 干活 → 结果回群。无人在场也跑。
+const DISPATCH_HELP = `常驻:等消息 -> 唤起 claude 干活 -> 结果回群。无人在场也跑。
 
   lark-relay dispatch --list          # 列出所有 dispatch 任务及状态
-  lark-relay dispatch <task> --once   # 前台跑一轮（调试,不进 systemd）
+  lark-relay dispatch <task> --once   # 前台跑一轮(调试,不进 systemd)
   systemctl enable --now lark-relay-dispatch@<task>
 
 --list 输出:任务名 / app / 群数 / systemd 单元是否 active / 上次 ledger 时间
 
-任务发现:扫 $LR_ROOT/*/dispatch.yaml —— 有文件即是任务,无需注册表。
-LR_ROOT 在单元里指定（唯一的目录绑定,与代码无关）。
+任务发现:扫 $LR_ROOT/*/dispatch.yaml -- 有文件即是任务,无需注册表。
+LR_ROOT 在单元里指定(唯一的目录绑定,与代码无关)。
 
-dispatch.yaml（4 必填 + 3 可选）
+dispatch.yaml(4 必填 + 3 可选)
   app: <profile 名>
   chats: [oc_xxx]
   dirs: [/path/to/repo]            # 首个 = 主工作目录
   instructions: ./instructions.md  # 职责/边界,--append-system-prompt-file 注入
   filter: '.mentions[]?.id == "ou_xxx"'   # 可选
-  # mode: work        默认;work | chat | agent（见下）
+  # mode: work        默认;work | chat | agent(见下)
   # model: <名称>      默认走终端同一套默认路由
 
-mode 三个场景（一个键定死全部行为,不用拼组合）
+mode 三个场景(一个键定死全部行为,不用拼组合)
   work   处理工作:话题内回复 + 过程挂 COT 消息 + 结论发卡片
-         + 按 thread_id 隔离 session + 防抖 1s（一问一答要跟手）
-         COT 要求客户端 PC ≥ 7.70 / 移动 ≥ 7.74;老客户端那条过程消息显示为
-         「Completed」（不崩）,结论卡片不受影响
-  chat   简单问答:直发群里 + 纯文本 + 按（群, epoch）隔离 session
-         + 防抖 15s（等人打完多行）
+         + 按 thread_id 隔离 session + 防抖 1s(一问一答要跟手)
+         COT 要求客户端 PC >= 7.70 / 移动 >= 7.74;老客户端那条过程消息显示为
+         「Completed」(不崩),结论卡片不受影响
+  chat   简单问答:直发群里 + 纯文本 + 按(群, epoch)隔离 session
+         + 防抖 15s(等人打完多行)
   agent  模型自己当运营者:引擎只拉起它 + 传消息 + 记台账,**一条消息都不发**。
          发不发 / 回哪条 / 用哪个 bot 身份 / 文字还是表情,全由模型按
-         instructions 决定（它有 Bash + lark-cli）。适合「多数轮该沉默」的
-         群运营 —— work/chat 会逼模型每轮都产出一段发回群的话
+         instructions 决定(它有 Bash + lark-cli)。适合「多数轮该沉默」的
+         群运营 -- work/chat 会逼模型每轮都产出一段发回群的话
 
 最佳实践
-  · 边界写 instructions,别指望 --add-dir 目录的 CLAUDE.md（启动不加载）
+  · 边界写 instructions,别指望 --add-dir 目录的 CLAUDE.md(启动不加载)
   · 改完 yaml 先 --once 跑一轮验证,再 enable
   · 高风险发布仍建议人工执行`
 
-const GUIDE = `lark-relay —— Lark 事件中继站。三个命令:收下来 / 我来取 / 派给别人。
+const GUIDE = `lark-relay -- Lark 事件中继站。三个命令:收下来 / 我来取 / 派给别人。
 
-先判场景（两者不可混用）
+先判场景(两者不可混用)
 ┌──────────┬────────────────────────┬────────────────────────┐
 │          │ 在场取用 take          │ 托管派活 dispatch      │
 ├──────────┼────────────────────────┼────────────────────────┤
-│ 长命的   │ AI 会话（人设、上下文）│ 消息（等在队列里）     │
-│ 短命的   │ 消息（来一批处理一批） │ AI（每轮新起,跑完就没）│
+│ 长命的   │ AI 会话(人设、上下文) │ 消息(等在队列里)     │
+│ 短命的   │ 消息(来一批处理一批)  │ AI(每轮新起,跑完就没)│
 │ 谁等谁   │ AI 等消息              │ 消息等 AI              │
 │ 控制权   │ AI 手里                │ 服务手里               │
 │ 谁能干   │ 任何 agent             │ 需内置唤起知识         │
 │ 配置     │ 纯参数,无文件         │ dispatch.yaml          │
 └──────────┴────────────────────────┴────────────────────────┘
 
-你（AI）在会话里盯群 → take。无人在场也要干活 → dispatch。
+你(AI)在会话里盯群 -> take。无人在场也要干活 -> dispatch。
 
 前置:collect 必须在跑
   lark-relay status        # collect 行应为 running
   进程不在的时刻消息永久丢失,不是延迟送达。
 
-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 起,别前台）
+  3. 监听(用 run_in_background 起,别前台)
      lark-relay take --app <app> --chats oc_xxx --render text
-  一批处理完再起一个。不要自己写 while 循环 —— 进程退出会通知你。
+  起来后 stderr 有一行「监听中」-- 没有就是没起来,看 stderr。
+  一批处理完再起一个。不要自己写 while 循环 -- 进程退出会通知你。
+  退出码:0=有一批,4=超时没消息(正常,再起一个),2=参数错,3=游标被占用。
 
 建 dispatch 任务
-  1. 在任务目录写 dispatch.yaml（\`lark-relay dispatch --help\` 有模板）
+  1. 在任务目录写 dispatch.yaml(\`lark-relay dispatch --help\` 有模板)
   2. lark-relay dispatch <task> --once     # 前台验一轮
   3. systemctl enable --now lark-relay-dispatch@<task>
 
 常见错误
-  · 拿不到消息 → 九成是 bot 不在群。验 bot 必须 --as user,
+  · 拿不到消息 -> 九成是 bot 不在群。验 bot 必须 --as user,
     bot 不在群时用 bot 身份查不到,「查询失败」不能推断「不在群」
-  · --chats 只接受 oc_ 开头的 chat_id,不接群名 —— 群名会匹配错群,
-    而监听错群是静默失败（你会一直等一个永不来的消息）
+  · 起来后没有「监听中」那行 -> 没起来;参数拼错会直接报错并给正确写法,
+    不会静默
+  · --chats 只接受 oc_ 开头的 chat_id,不接群名 -- 群名会匹配错群,
+    而监听错群是静默失败(你会一直等一个永不来的消息)
   · 默认 --since now 不重放历史。要历史用 --since all
   · 多个消费者盯同一 app 必须用不同 --name,否则互相推游标撕批次
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lark-relay",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Lark event relay: collect events to disk, take a batch when you need it, or dispatch work to an AI agent.",
   "keywords": [
     "lark",