lark-relay 0.4.1 → 0.4.3

package/README.md

@@ -58,7 +58,10 @@ Claude Code 用 `run_in_background` 起,进程退出会主动通知 AI,这才是
 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 表达式)一个口子,不为每个业务加参数。
 

package/bin/lark-relay.js

@@ -19,8 +19,9 @@ const VERSION = require('../package.json').version
 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) {
+// 未知参数 -> stderr 短错误 + 候选提示 + 改写后的命令,exit 2。
+// 不打印完整用法 -- 那看着像 --help 成功,会被当成「正常退出但没消息」
+function rejectUnknown(cmd, argv, unknown, allowed) {
   const names = [...new Set(unknown)]
   const shown = names.map((k) => `--${k}`).join(', ')
   let hint = ''
@@ -31,10 +32,50 @@ function rejectUnknown(cmd, unknown, allowed) {
       break
     }
   }
-  process.stderr.write(`未知参数:${shown}${hint}\n跑 \`lark-relay ${cmd}\` 看完整用法\n`)
+  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 常驻）
@@ -72,15 +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'], keys: COLLECT_KEYS })
-  if (a._unknown.length) return rejectUnknown('collect', a._unknown, 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
@@ -95,11 +138,11 @@ async function cmdCollect(argv) {
 
 async function cmdTake(argv) {
   const a = parseArgs(argv, { flags: ['help'], keys: TAKE_KEYS })
-  if (a._unknown.length) return rejectUnknown('take', a._unknown, TAKE_KEYS)
+  if (a._unknown.length) return rejectUnknown('take', argv, a._unknown, TAKE_KEYS)
   const larkcli = require('../lib/larkcli')
 
-  // 空参数输出完整照做指导,而非报错 —— AI 的真实行为是「先空参数跑一下看看」。
-  // 但带了参数又缺 app/chats 的走下面短错误 —— 打印完整用法和 --help 长得一样,
+  // 空参数输出完整照做指导,而非报错 -- AI 的真实行为是「先空参数跑一下看看」。
+  // 但带了参数又缺 app/chats 的走下面短错误 -- 打印完整用法和 --help 长得一样,
   // 会被当成「正常退出但没消息」(实测漏看 bot 第一条 Working)。
   if (a.help || argv.length === 0) {
     let apps = []
@@ -107,7 +150,7 @@ async function cmdTake(argv) {
       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')
@@ -116,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)
@@ -155,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)
@@ -172,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
   }
 
@@ -184,7 +235,7 @@ async function cmdTake(argv) {
 
 async function cmdStatus(argv) {
   const a = parseArgs(argv, { flags: ['json', 'help'], keys: [] })
-  if (a._unknown.length) return rejectUnknown('status', a._unknown, ['json'])
+  if (a._unknown.length) return rejectUnknown('status', argv, a._unknown, ['json'])
   if (a.help) {
     process.stdout.write(`${help.STATUS_HELP}\n`)
     return 0
@@ -198,7 +249,7 @@ async function cmdStatus(argv) {
 
 async function cmdDispatch(argv) {
   const a = parseArgs(argv, { flags: ['list', 'once', 'help'], keys: [] })
-  if (a._unknown.length) return rejectUnknown('dispatch', a._unknown, ['list', 'once'])
+  if (a._unknown.length) return rejectUnknown('dispatch', argv, a._unknown, ['list', 'once'])
   if (a.help) {
     process.stdout.write(`${help.DISPATCH_HELP}\n`)
     return 0
@@ -207,7 +258,12 @@ async function cmdDispatch(argv) {
   if (a.list) return dispatch.cmdList()
   const task = a._[0]
   if (!task) {
-    process.stdout.write(`${help.DISPATCH_HELP}\n`)
+    // 空参 = 求教,和 take 一致(exit 0);带了 flag 却没任务名是写错,短错误
+    if (argv.length === 0) {
+      process.stdout.write(`${help.DISPATCH_HELP}\n`)
+      return 0
+    }
+    process.stderr.write('需要任务名($LR_ROOT/<任务名>/dispatch.yaml)。看现有任务:`lark-relay dispatch --list`\n')
     return 2
   }
   return await dispatch.run(task, { once: !!a.once })

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,125 @@ 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 status\` 确认 -- collect 行应为 running;不在跑看
+\`systemctl status lark-relay-collect\` 的日志。
+
 落盘:~/.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 没在跑或卡住;
-「无消费者」= 白采,可考虑 --exclude。`
+排障入口:某消费者「落后」很多 -> 它的 take/dispatch 没在跑或卡住;
+「无消费者」= 白采,可考虑 --exclude。
+collect 行不是 running -> \`systemctl status lark-relay-collect\` 看日志,
+collect 停摆的每一秒都在丢消息。`
 
-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
-  · 高风险发布仍建议人工执行`
+  · 高风险发布仍建议人工执行
+
+退出码(--once)
+  0  跑了一轮,或没等到消息但正常结束
+  1  取批异常(看 stderr)
+  2  任务不存在或配置错
+  4  等消息超时(5min 没消息)`
 
-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
   进程不在的时刻消息永久丢失,不是延迟送达。
+  不在跑 -> systemctl enable --now lark-relay-collect(或 \`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 起,别前台）
+  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.1",
+  "version": "0.4.3",
   "description": "Lark event relay: collect events to disk, take a batch when you need it, or dispatch work to an AI agent.",
   "keywords": [
     "lark",