lark-watch 0.0.0 → 1.0.0

package/README.md

@@ -1,3 +1,61 @@
 # lark-watch
 
-Placeholder — name reserved for future development. Not functional yet.
+Lark(飞书)消息浅封装:直接消费 `lark-cli event consume`,按防抖窗口攒一批消息输出后退出
+
+依赖 Node.js >=22 和 [@larksuite/cli](https://www.npmjs.com/package/@larksuite/cli)（命令名 `lark-cli`,
+需支持 `event consume` 的 `--jq`/`--timeout` bounded 模式,本机实测基准 1.0.96),零 npm 运行依赖
+
+```bash
+npm i -g lark-watch
+lark-watch --help
+```
+
+## 模型
+
+```
+lark-watch  ->  lark-cli event consume(bounded)  ->  lark-cli event bus daemon  ->  Lark
+```
+
+事件连接、认证、重连由 lark-cli 的 per-app event bus daemon 维护;`lark-watch` 只做三件事:
+
+1. 按参数起一个一次性 consumer
+2. 群白名单 + jq 过滤交给 CLI 的 `--jq`,按防抖窗口把 NDJSON 攒成一批
+3. 输出到 stdout 后退出,由调用方处理完再启动下一次
+
+```bash
+lark-watch --app <profile> --chats oc_xxx --render text
+lark-watch --app <profile> --chats @chats.txt --filter '.sender_id != "ou_xxx"'
+```
+
+## 语义
+
+- **无状态**:不存消息、不记进度。退出即结束,再启动只收到启动之后的新消息
+- Lark 事件不回放离线消息(发出约 8 秒后再挂的 consumer 收不到),需要补漏就回读群历史
+- 就绪以 stderr 的「监听中」为准;CLI 的连接日志与 drop 诊断原样透传,不做静默
+- 默认防抖 5 秒(最后一条消息后的静默窗口),从第一条起最多攒 25 秒,单次最长等 12 小时
+- 停止用 SIGTERM:CLI 会优雅卸载服务端订阅,不要 SIGKILL
+
+## 参数
+
+| 参数 | 说明 |
+| --- | --- |
+| `--app <name>` | 必填,lark-cli profile 名 |
+| `--chats <ids>` | 必填,逗号分隔 chat_id,或 `@文件`(取首列,忽略空行与 `#` 注释) |
+| `--filter <jq>` | 业务过滤表达式,与群白名单取交集 |
+| `--debounce N` | 最后一条消息后静默 N 秒吐批,默认 5 |
+| `--max-wait N` | 从第一条起最多攒 N 秒,默认 25 |
+| `--timeout N` | 单次最长阻塞 N 秒,默认 43200;`0` 为不限时 |
+| `--render text\|ndjson` | 默认 ndjson;text 按群/话题分组,带发送者与消息元数据 |
+
+退出码:0=有一批/帮助/信号退出,1=运行错误,2=参数错或过滤表达式无效,4=超时无消息
+
+监听要求 bot 已在群内。查群与验成员:
+
+```bash
+lark-cli --profile <profile> im +chat-search --as user --query "<群名>"
+lark-cli --profile <profile> im chat.members bots --as user --params '{"chat_id":"oc_xxx"}'
+```
+
+## 许可
+
+MIT

package/bin/lark-watch.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+'use strict'
+
+const { parseCliArgs, numberArg } = require('../lib/args')
+const { parseChats, checkChats, buildJq } = require('../lib/chats')
+const { render } = require('../lib/render')
+const { watch } = require('../lib/watch')
+const pkg = require('../package.json')
+const { HELP } = require('../lib/help')
+
+async function main() {
+  const argv = process.argv.slice(2)
+  if (argv.length === 0 || argv.includes('-h') || argv.includes('--help')) {
+    process.stdout.write(`${HELP}\n`)
+    return 0
+  }
+  if (argv.includes('-v') || argv.includes('--version')) {
+    process.stdout.write(`${pkg.version}\n`)
+    return 0
+  }
+
+  const a = parseCliArgs(argv)
+
+  if (!a.app) {
+    process.stderr.write('需要 --app <name>,跑 `lark-watch --help` 看用法\n')
+    return 2
+  }
+  let chats
+  try {
+    chats = parseChats(a.chats)
+    checkChats(chats)
+  } catch (err) {
+    process.stderr.write(`${err.message}\n`)
+    return err.exitCode || 2
+  }
+  if (!chats.length) {
+    process.stderr.write('需要 --chats oc_xxx,多个 chat_id 用逗号分隔\n')
+    return 2
+  }
+  const mode = a.render ?? 'ndjson'
+  if (!['text', 'ndjson'].includes(mode)) {
+    process.stderr.write(`--render 只能是 text 或 ndjson,当前:${mode}\n`)
+    return 2
+  }
+
+  let debounceSec, maxWaitSec, timeoutSec
+  try {
+    debounceSec = numberArg(a['debounce'], 5, 'debounce')
+    maxWaitSec = numberArg(a['max-wait'], 25, 'max-wait')
+    timeoutSec = numberArg(a['timeout'], 43200, 'timeout')
+  } catch (err) {
+    process.stderr.write(`${err.message}\n`)
+    return 2
+  }
+  if (timeoutSec !== 0 && timeoutSec < maxWaitSec) {
+    process.stderr.write('--timeout 不能小于 --max-wait,否则首批可能被整体超时截断\n')
+    return 2
+  }
+  const jq = buildJq(chats, a.filter)
+
+  // 参数全部有效后再 spawn
+  const ac = new AbortController()
+  process.on('SIGTERM', () => ac.abort())
+  process.on('SIGINT', () => ac.abort())
+
+  const res = await watch({
+    app: a.app,
+    jq,
+    debounceMs: debounceSec * 1000,
+    maxWaitMs: maxWaitSec * 1000,
+    timeoutSec,
+    externalSignal: ac.signal,
+    onReady: () => {
+      const total = timeoutSec === 0 ? '不限时' : `${timeoutSec}s`
+      process.stderr.write(
+        `监听中:app=${a.app} 群=${chats.length} 个(${chats.join(',')}) ` +
+          `防抖=${debounceSec}s 首批封顶=${maxWaitSec}s 总超时=${total}\n`,
+      )
+    },
+    onWarn: (msg) => process.stderr.write(`warn: ${msg}\n`),
+    // CLI 例行行(consuming/listening/exited)与 drop 诊断原样保留:
+    // 不用 --quiet,它会连丢消息提示一起吞掉
+    onCliStderr: (line) => process.stderr.write(`${line}\n`),
+  })
+
+  if (!res.events.length) {
+    if (res.reason === 'error') {
+      process.stderr.write('监听失败,见上方 lark-cli 输出\n')
+      return res.exitCode || 1
+    }
+    process.stderr.write(`没等到消息(${res.reason}),再起一个继续\n`)
+    return res.reason === 'timeout' ? 4 : 0
+  }
+  process.stdout.write(`${render(res.events, mode)}\n`)
+  process.stderr.write(`${res.events.length} 条\n`)
+  return 0
+}
+
+// 自然排空 stdout,避免大批次经管道输出时被截断
+main()
+  .then((code) => { process.exitCode = code })
+  .catch((err) => {
+    process.stderr.write(`${err.userFacing ? err.message : err.stack}\n`)
+    process.exitCode = err.exitCode || 1
+  })

package/lib/args.js

@@ -0,0 +1,37 @@
+'use strict'
+
+const { parseArgs: parse } = require('node:util')
+
+const KEYS = ['app', 'chats', 'filter', 'debounce', 'max-wait', 'timeout', 'render']
+
+function parseCliArgs(args) {
+  const options = { help: { type: 'boolean', short: 'h' } }
+  for (const key of KEYS) options[key] = { type: 'string' }
+  try {
+    const { values } = parse({ args, options, strict: true, allowPositionals: false })
+    for (const key of KEYS) {
+      if (values[key] !== undefined && !values[key].trim()) {
+        throw new Error(`--${key} 不能为空`)
+      }
+    }
+    return values
+  } catch (err) {
+    err.message += `\n可用参数:${['help', ...KEYS].map((k) => `--${k}`).join(' ')}`
+    err.userFacing = true
+    err.exitCode = 2
+    throw err
+  }
+}
+
+function numberArg(value, fallback, label) {
+  const n = value === undefined ? fallback : Number(value)
+  if (!Number.isFinite(n) || n < 0) {
+    throw Object.assign(new Error(`--${label} 需要有限的非负数,当前:${value}`), {
+      userFacing: true,
+      exitCode: 2,
+    })
+  }
+  return n
+}
+
+module.exports = { parseCliArgs, numberArg, KEYS }

package/lib/chats.js

@@ -0,0 +1,53 @@
+'use strict'
+
+// 只放行形如 oc_xxx 的普通 id:白名单同时是 jq 字符串注入的防线,
+// 合成 --jq 时 id 会被包进双引号字面量
+const CHAT_ID = /^oc_[A-Za-z0-9_-]+$/
+
+// --chats 支持 @文件(取首列,忽略空行与 # 注释)
+function parseChats(spec) {
+  if (!spec) return []
+  let raw = spec
+  if (spec.startsWith('@')) {
+    const fs = require('fs')
+    const file = spec.slice(1)
+    let text
+    try {
+      text = fs.readFileSync(file, 'utf8')
+    } catch {
+      const e = new Error(`--chats 指向的文件读不到:${file}`)
+      e.userFacing = true
+      e.exitCode = 2
+      throw e
+    }
+    raw = text
+      .split('\n')
+      .map((l) => l.trim())
+      .filter((l) => l && !l.startsWith('#'))
+      .map((l) => l.split(/[\s,\t]+/)[0])
+      .join(',')
+  }
+  return [...new Set(raw.split(',').map((s) => s.trim()).filter(Boolean))]
+}
+
+function checkChats(chats) {
+  const bad = chats.find((c) => !CHAT_ID.test(c))
+  if (bad) {
+    const e = new Error(`非法 chat_id:${bad}(需要 oc_ 前缀的字母数字串)`)
+    e.userFacing = true
+    e.exitCode = 2
+    throw e
+  }
+}
+
+// 群白名单与业务过滤合成一个 select,全部交给 CLI 的 --jq,本地不 spawn jq。
+// chats 已过白名单,可安全拼进字符串字面量;filter 是用户自己的表达式,原样包裹
+function buildJq(chats, filter) {
+  const chatExpr = chats.map((c) => `.chat_id==${JSON.stringify(c)}`).join(' or ')
+  if (chats.length && filter) return `select((${chatExpr}) and (${filter}))`
+  if (chats.length) return `select(${chatExpr})`
+  if (filter) return `select(${filter})`
+  return null
+}
+
+module.exports = { parseChats, checkChats, buildJq, CHAT_ID }

package/lib/help.js

@@ -0,0 +1,37 @@
+'use strict'
+
+const HELP = `lark-watch -- 直接消费 lark-cli 事件流,攒一批消息输出后退出
+
+需要 --app 和 --chats,监听要求 bot 已在群内
+
+1. 查群 ID(用户身份)
+  lark-cli --profile <app> im +chat-search --as user --query "<群名>"
+  -> 取 oc_ 开头的 chat_id,多个匹配时确认目标群
+
+2. 验 bot 在群(用户身份)
+  lark-cli --profile <app> im chat.members bots --as user --params '{"chat_id":"oc_xxx"}'
+  -> bots[] 应含本 app,不在群则先安排入群
+
+3. 监听一批
+  lark-watch --app <app> --chats oc_xxx --render text
+  -> stderr 先出现 lark-cli 的连接日志,「监听中」表示已就绪进入等待
+  -> 攒出一批输出到 stdout 后退出,处理完再次运行
+
+参数
+  --app <name>      必填,lark-cli profile 名(用 lark-cli profile list 查询)
+  --chats <ids>     必填,逗号分隔的 chat_id,或 @文件(首列 chat_id)
+  --filter <jq>     业务过滤,与群白名单取交集,如 '.sender_id != "ou_xxx"'
+  --debounce N      最后一条消息后静默多久吐批,默认 5 秒
+  --max-wait N      从第一条起最多攒多久,默认 25 秒
+  --timeout N       本次最多阻塞多少秒,默认 43200(12 小时);0 = 不限时
+  --render <mode>   text 或 ndjson,默认 ndjson
+  -h, --help       用法
+
+语义
+  无状态:不存消息、不记进度,退出即结束;重跑只收到启动之后的新消息
+  Lark 事件不回放离线消息(发出约 8 秒后再挂就收不到),需要补漏就回读群历史
+  事件连接由 lark-cli 的 event bus daemon 维护,不要用 lark-cli event stop 拆共享总线
+
+退出码:0=有一批/帮助/信号退出,1=运行错误,2=参数错或过滤表达式无效,4=超时无消息`
+
+module.exports = { HELP }

package/lib/render.js

@@ -0,0 +1,64 @@
+'use strict'
+
+function fmtTime(ts) {
+  const ms = Number(ts)
+  if (!Number.isFinite(ms) || ms <= 0) return '?'
+  const d = new Date(ms)
+  const p = (n) => String(n).padStart(2, '0')
+  return `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`
+}
+
+// 事件体里没有发送者姓名:mentions 只装被 @ 的人,实测 861 条真实事件
+// 无一条把 sender_id 收进 mentions。要姓名需另查通讯录,不在渲染层做
+function senderLabel(e) {
+  return e.sender_id || 'unknown'
+}
+
+function renderNdjson(events) {
+  return events.map((e) => JSON.stringify(e)).join('\n')
+}
+
+// 群与话题共同确定分组,使用转义 NUL 分隔
+function renderText(events) {
+  const groups = new Map()
+  for (const e of events) {
+    const key = `${e.chat_id || '?'}\x00${e.thread_id || ''}`
+    if (!groups.has(key)) groups.set(key, [])
+    groups.get(key).push(e)
+  }
+  const out = []
+  for (const [key, list] of groups) {
+    const [chatId, threadId] = key.split('\x00')
+    let head = `## chat ${chatId}`
+    if (threadId) head += `  thread ${threadId}`
+    head += `  (${list.length} 条)`
+    out.push(head)
+    for (const e of list) {
+      const line = [`[${fmtTime(e.create_time)}]`, senderLabel(e)]
+      if (e.message_type && e.message_type !== 'text') line.push(`<${e.message_type}>`)
+      out.push(`${line.join(' ')}: ${e.content ?? ''}`)
+      const meta = []
+      meta.push(`message_id=${e.message_id || '?'}`)
+      meta.push(`sender_id=${e.sender_id || '?'}`)
+      // sender_type 是业务判据(如「自家 bot 的消息跳过」),必须渲染出来
+      meta.push(`sender_type=${e.sender_type || '?'}`)
+      const mentions = (e.mentions || []).filter(Boolean)
+      if (mentions.length) {
+        meta.push(`mentions=${mentions.map((m) => `${m.name || '?'}(${m.id || '?'})`).join(',')}`)
+      }
+      if (e.reply_to) meta.push(`reply_to=${e.reply_to}`)
+      if (e.root_id) meta.push(`root_id=${e.root_id}`)
+      if (e.thread_id) meta.push(`thread_id=${e.thread_id}`)
+      out.push(`    ${meta.join(' ')}`)
+    }
+    out.push('')
+  }
+  return out.join('\n').trimEnd()
+}
+
+function render(events, mode) {
+  if (mode === 'text') return renderText(events)
+  return renderNdjson(events)
+}
+
+module.exports = { render }

package/lib/watch.js

@@ -0,0 +1,193 @@
+'use strict'
+
+// 浅封装核心:spawn 一个 bounded `lark-cli event consume`,逐行收 NDJSON,
+// 按防抖窗口攒成一批;CLI 退出、超时或收到信号时交付并结束。
+// 不做落盘、断点、重连 -- 连接与保活是 lark-cli event bus daemon 的职责。
+const { spawn } = require('child_process')
+const readline = require('readline')
+
+const EVENT_KEY = 'im.message.receive_v1'
+
+// LARK_WATCH_CLI 测试接缝:字符串 = 可执行路径(生产用 lark-cli);
+// JSON 数组 = [可执行, ...前置参数],测试借此用真 node 直接跑假 CLI 脚本,
+// 绕开 macOS 对新建 shebang 文件首次 execve 的策略评估延迟(实测可达数百毫秒)
+function cliCommand() {
+  const raw = process.env.LARK_WATCH_CLI
+  if (!raw) return { file: 'lark-cli', preArgs: [] }
+  if (raw.trimStart().startsWith('[')) {
+    const arr = JSON.parse(raw)
+    return { file: arr[0], preArgs: arr.slice(1) }
+  }
+  return { file: raw, preArgs: [] }
+}
+// CLI 自己打的就绪行;bus daemon 首次建连的 connected 行复用时不会再打,不能拿它判就绪
+const READY_RE = /\[event\] ready event_key=/
+
+/**
+ * @param {object} opts
+ *   app: lark-cli profile 名
+ *   jq: 合成好的 select 表达式,null 表示不过滤
+ *   debounceMs / maxWaitMs: 攒批窗口
+ *   timeoutSec: 透传给 CLI 的 bounded 超时;0 = unbounded
+ *   externalSignal: { aborted } -- 外部(SIGTERM/SIGINT)要求收尾
+ *   onReady(line) / onWarn(msg) / onCliStderr(line)
+ * @returns {Promise<{events:array, reason:string, exitCode?:number}>}
+ *   reason: batch | timeout | signal | error
+ */
+function watch(opts) {
+  const {
+    app,
+    jq,
+    debounceMs,
+    maxWaitMs,
+    timeoutSec,
+    externalSignal,
+    onReady = () => {},
+    onWarn = () => {},
+    onCliStderr = () => {},
+  } = opts
+
+  const args = [
+    '--profile', app,
+    'event', 'consume', EVENT_KEY,
+    '--as', 'bot',
+    '--timeout', `${timeoutSec}s`,
+  ]
+  if (jq) args.push('--jq', jq)
+
+  // bounded 运行忽略 stdin EOF;只有 --timeout 0 的 unbounded 模式把 EOF 当退出信号,
+  // 那时必须给一根保持打开的管道(给 /dev/null 或 ignore 会立刻 EOF)
+  const stdio = timeoutSec === 0 ? ['pipe', 'pipe', 'pipe'] : ['ignore', 'pipe', 'pipe']
+  const { file, preArgs } = cliCommand()
+  // detached:子进程自建进程组。PATH 上的 lark-cli 在 fnm 等版本管理器下是个
+  // 包装脚本,真二进制是它派生的孙子;child.kill() 只杀包装层,孙子会带着
+  // stdout 管道成孤儿,close 永不触发。结束必须按进程组(负 pid)杀整棵树
+  const child = spawn(file, [...preArgs, ...args], { stdio, detached: true })
+  if (timeoutSec === 0 && child.stdin) child.stdin.on('error', () => {})
+
+  const stopChild = () => {
+    try {
+      process.kill(-child.pid, "SIGTERM")
+    } catch (err) {
+      if (err.code !== 'ESRCH') child.kill('SIGTERM')
+    }
+  }
+
+  const batch = []
+  let ready = false
+  let shuttingDown = false
+  let startupExit = null // ready 前的致命错误用退出码 2(参数/过滤表达式问题)
+  let runtimeError = null
+  let debounceTimer = null
+  let maxWaitTimer = null
+  let firstAt = 0
+
+  return new Promise((resolve) => {
+    let settled = false
+    const settle = (reason) => {
+      if (settled) return
+      settled = true
+      clearTimeout(debounceTimer)
+      clearTimeout(maxWaitTimer)
+      if (reason === 'error') {
+        resolve({ events: batch, reason, exitCode: startupExit || 1 })
+      } else if (batch.length) {
+        resolve({ events: batch, reason: 'batch' })
+      } else {
+        resolve({ events: batch, reason })
+      }
+    }
+
+    const armDebounce = () => {
+      clearTimeout(debounceTimer)
+      debounceTimer = setTimeout(() => finish('batch'), debounceMs)
+    }
+
+    const accept = (obj) => {
+      batch.push(obj)
+      if (!firstAt) {
+        firstAt = Date.now()
+        // 绝对封顶:热闹群也不能无限攒下去
+        maxWaitTimer = setTimeout(() => finish('batch'), maxWaitMs)
+      }
+      armDebounce()
+    }
+
+    // 防抖到点或封顶:请 CLI 进程组优雅退出(禁 SIGKILL -- 会漏卸载服务端订阅),
+    // close 后统一交付;退出前在途到达的行照收进本批
+    const finish = () => {
+      if (shuttingDown) return
+      shuttingDown = true
+      clearTimeout(debounceTimer)
+      stopChild()
+    }
+
+    if (externalSignal) {
+      externalSignal.addEventListener('abort', () => {
+        shuttingDown = true
+        stopChild()
+      }, { once: true })
+    }
+
+    child.on('error', (err) => {
+      const hint = err.code === 'ENOENT'
+        ? `找不到 ${file},检查它已安装且在 PATH 中`
+        : `spawn ${file} 失败:${err.message}`
+      onWarn(hint)
+      runtimeError = err
+      settle('error')
+    })
+
+    const rl = readline.createInterface({ input: child.stdout, crlfDelay: Infinity })
+    rl.on('line', (line) => {
+      const s = line.trim()
+      if (!s || s[0] !== '{') {
+        if (s) onWarn(`非 JSON 行,已跳过:${s.slice(0, 200)}`)
+        return
+      }
+      let obj
+      try {
+        obj = JSON.parse(s)
+      } catch {
+        onWarn(`非 JSON 行,已跳过:${s.slice(0, 200)}`)
+        return
+      }
+      // CLI 的错误信封(如 --jq 编译失败)从 stdout 出来,不是事件
+      if (obj.ok === false) {
+        const detail = obj.error?.message || s.slice(0, 500)
+        onWarn(`lark-cli 报错:${detail}`)
+        if (!ready) startupExit = 2
+        else runtimeError = new Error(detail)
+        return
+      }
+      accept(obj)
+    })
+
+    const erl = readline.createInterface({ input: child.stderr, crlfDelay: Infinity })
+    erl.on('line', (line) => {
+      const text = line.trimEnd()
+      if (!text) return
+      onCliStderr(text)
+      if (!ready && READY_RE.test(text)) {
+        ready = true
+        onReady(text)
+      }
+    })
+
+    child.on('close', (code, signal) => {
+      if (externalSignal?.aborted) return settle('signal')
+      if (shuttingDown) return settle('batch')
+      if (!ready) {
+        // ready 前退出:没连上就什么都没收到,原因 CLI 已打到 stderr。
+        // 错误信封已置过 startupExit=2(过滤表达式/参数问题),其余按运行错 1
+        if (startupExit === null) startupExit = 1
+        return settle('error')
+      }
+      if (code === 0 || signal === 'SIGTERM') return settle(batch.length ? 'batch' : 'timeout')
+      runtimeError = runtimeError || new Error(`lark-cli 异常退出(code ${code},signal ${signal})`)
+      settle('error')
+    })
+  })
+}
+
+module.exports = { watch, cliCommand, EVENT_KEY }

package/package.json

@@ -1,9 +1,32 @@
 {
   "name": "lark-watch",
-  "version": "0.0.0",
-  "description": "Placeholder. Reserved for future development.",
+  "version": "1.0.0",
+  "description": "Watch Lark messages: spawn lark-cli event consume, debounce a batch, print and exit.",
+  "keywords": [
+    "lark",
+    "feishu",
+    "events",
+    "watch",
+    "bot",
+    "agent"
+  ],
   "license": "MIT",
   "author": "adaex",
-  "files": ["README.md"],
-  "keywords": ["lark", "feishu"]
+  "type": "commonjs",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "lark-watch": "bin/lark-watch.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "prepublishOnly": "node --test test/*.test.js && npm run check-pack",
+    "check-pack": "node scripts/check-pack.js"
+  }
 }