lark-relay 0.4.0 → 0.4.1

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,24 @@ 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 在群 -> 监听三步)。
 
 业务过滤只有 `--filter`(jq 表达式)一个口子,不为每个业务加参数。
 
 ### dispatch
 
-任务发现:扫 `$LR_ROOT/*/dispatch.yaml` —— 有文件即是任务,无需注册表。
+任务发现:扫 `$LR_ROOT/*/dispatch.yaml` -- 有文件即是任务,无需注册表。
 `dispatch` 内部就是调 `take`,保证两场景不实现分叉。
 
 ```yaml
@@ -77,7 +77,7 @@ filter: '.mentions[]?.id == "ou_xxx"'   # 可选
 # model: <名称>      默认走终端同一套默认路由
 ```
 
-`mode` 三个场景 —— 一个键定死全部行为,不用拼组合:
+`mode` 三个场景 -- 一个键定死全部行为,不用拼组合:
 
 | | `work`(默认) | `chat` | `agent` |
 |---|---|---|---|
@@ -90,18 +90,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 +119,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,33 @@ 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, 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
+    }
+  }
+  process.stderr.write(`未知参数:${shown}${hint}\n跑 \`lark-relay ${cmd}\` 看完整用法\n`)
+  return 2
+}
+
 const USAGE = `lark-relay ${VERSION} —— Lark 事件中继站
 
   lark-relay collect            底座:全部 profile 各起 consume → 原子落盘（systemd 常驻）
@@ -57,7 +79,8 @@ async function main() {
 }
 
 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', a._unknown, COLLECT_KEYS)
   if (a.help) {
     process.stdout.write(`${help.COLLECT_HELP}\n`)
     return 0
@@ -71,11 +94,14 @@ 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', 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)
@@ -157,7 +183,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', a._unknown, ['json'])
   if (a.help) {
     process.stdout.write(`${help.STATUS_HELP}\n`)
     return 0
@@ -170,7 +197,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', 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/package.json

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