lark-relay 0.0.0 → 0.1.1

package/README.md

@@ -1,3 +1,111 @@
 # lark-relay
 
-Placeholder — name reserved for future development. Not functional yet.
+Lark(飞书)事件中继站。三个命令:**收下来** / **我来取** / **派给别人**。
+
+依赖 [`lark-cli`](https://www.npmjs.com/package/@lark-base-open/lark-cli) 提供认证与
+事件总线;本包只负责缓冲、批次与派活,零 npm 依赖。
+
+```bash
+npm i -g lark-relay
+lark-relay guide          # 装完先读这个
+```
+
+## 为什么需要它
+
+Lark 事件是**流式**的 —— 进程不在的时刻,消息**永久丢失**,不是延迟送达
+(实测:消息发出 8 秒后才起 consumer,收到 0 条)。
+
+所以要有一个常驻进程只管把事件收下来落盘,消费侧崩了、AI 跑了半小时、
+会话关了几小时,都不丢消息。这就是 `collect`。
+
+## 两个场景(不可混用)
+
+|  | 在场取用 `take` | 托管派活 `dispatch` |
+| --- | --- | --- |
+| 长命的 | AI 会话(人设、上下文连续) | 消息(等在队列里) |
+| 短命的 | 消息(来一批处理一批) | AI(每轮新起,跑完就没) |
+| 谁在等谁 | AI 等消息 | 消息等 AI |
+| 控制权 | AI 手里(自己决定何时再取) | 服务手里(决定何时拉起 AI) |
+| 谁能干 | 任何 agent(Claude Code / Codex / 手敲) | 需内置唤起知识 |
+| 配置 | 纯参数,无文件 | `dispatch.yaml` |
+
+你(AI)在会话里盯群 → `take`。无人在场也要干活 → `dispatch`。
+
+## 命令
+
+```bash
+lark-relay collect            # 底座:全部 profile 各起 consume → 原子落盘(systemd 常驻)
+lark-relay take …             # 场景1:阻塞等一批 → 输出 → 退出
+lark-relay dispatch <task>    # 场景2:常驻循环 = take + 唤起 claude
+lark-relay status             # 谁在跑 / 各 app 积压 / 各游标位置
+lark-relay guide              # 一页用法
+```
+
+### collect
+
+零参数、零配置。app 列表实时读 `lark-cli profile list`,新增 profile 自动纳入。
+未授权或授权过期的 profile 自动跳过并 warn(永久失败,重试是死循环)。
+
+每 app 一个子进程,某个挂了单独重启不影响其他。回收在本进程内每小时自查,
+删超期的整个日期目录 —— 不另起 gc 单元/timer。
+
+### take
+
+只有一种形态:**阻塞等 → 有一批就输出 → 退出**。循环交给 harness ——
+Claude Code 用 `run_in_background` 起,进程退出会主动通知 AI,这才是事件驱动。
+
+```bash
+lark-relay take --app <app> --chats oc_xxx --render text
+```
+
+空参数跑一下会输出完整的照做指导(查群 ID → 验 bot 在群 → 监听三步)。
+
+业务过滤只有 `--filter`(jq 表达式)一个口子,不为每个业务加参数。
+
+### dispatch
+
+任务发现:扫 `$LR_ROOT/*/dispatch.yaml` —— 有文件即是任务,无需注册表。
+`dispatch` 内部就是调 `take`,保证两场景不实现分叉。
+
+```yaml
+app: <profile 名>
+chats: [oc_xxx]
+dirs: [/path/to/repo]            # 首个 = 主工作目录
+instructions: ./instructions.md  # 职责/边界,--append-system-prompt-file 注入
+filter: '.mentions[]?.id == "ou_xxx"'   # 可选
+# session: thread   默认;thread=按 thread_id 隔离 | idle=一群一 session
+# display: card     默认;card=CardKit 流式打字机 | final
+# model: <名称>      默认走终端同一套默认路由
+```
+
+## 存储布局
+
+```
+~/.lark-relay/
+  store/<app>/<YYYY-MM-DD>/<纳秒>_<pid>_<seq>.json   原始事件(可随时删,丢了自愈)
+  cursors/<name>/<app>                               各消费者游标
+  ledger/<task>__<chat>.ndjson                       dispatch 结论台账
+```
+
+判据:能随时删掉重建的才放这里。`ledger` 是唯一不能重建的东西
+(session 会因空闲滚动/过期丢上下文,结论不能丢),走文件系统级备份。
+
+多消费者**共享 store、各持游标**,不做「处理完即删」—— 谁都不能替别人删。
+盯同一 app 请用不同 `--name` 隔离游标。
+
+## 设计取舍
+
+- **原子落盘**:collect 读 stdout NDJSON 后自己 `写 .tmp → rename`(同目录原子)。
+  不用 `--output-dir` —— 它先建 0 字节再填充,消费侧游标可能跨过半成品导致事件永久丢失
+- **一事件一文件 + 按天分目录**:不用追加式 NDJSON。因为多消费者共享 store 时
+  两种方案都不能「处理完即删」,NDJSON 最大的优势(删除简单)失效,而它的 gc
+  要按大小滚动 + 保留 N 个文件,反而比整目录删复杂
+- **两层去重**:cursor 管进度,`message_id` 管幂等(TTL 6h)。
+  collect 重启或 bus 重投时同一条消息会落成**新文件**,游标拦不住
+- **`--chats` 只接 `oc_` 开头的 chat_id,不接群名**:群名可能匹配多个或匹配错群,
+  而监听错群是**静默失败**(一直等一个永不来的消息)
+- **`--since` 默认 `now`**:不重放历史,消灭「预热游标」这一步
+
+## 许可
+
+MIT

package/bin/lark-relay.js

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+'use strict'
+
+// UTF-8 兜底:systemd 默认 C locale。虽然 Node 的字符串处理不像 bash 那样
+// 按字节切片,但子进程(lark-cli / claude)会继承 locale,中文仍会被切坏。
+if (!/utf-?8/i.test(process.env.LC_ALL || process.env.LC_CTYPE || process.env.LANG || '')) {
+  process.env.LANG = 'C.UTF-8'
+  process.env.LC_ALL = 'C.UTF-8'
+}
+
+const { parseArgs, num, list } = require('../lib/args')
+const help = require('../lib/help')
+
+const VERSION = require('../package.json').version
+
+const USAGE = `lark-relay ${VERSION} —— Lark 事件中继站
+
+  lark-relay collect            底座:全部 profile 各起 consume → 原子落盘（systemd 常驻）
+  lark-relay take …             场景1 在场取用:阻塞等一批 → 输出 → 退出
+  lark-relay dispatch <task>    场景2 托管派活:常驻循环 = take + 唤起 claude
+  lark-relay status             谁在跑 / 各 app 积压 / 各游标位置
+  lark-relay guide              一页用法（装完先读这个）
+
+第一次用 → lark-relay guide
+各命令详情 → lark-relay <命令> --help`
+
+async function main() {
+  const argv = process.argv.slice(2)
+  const cmd = argv[0]
+  const rest = argv.slice(1)
+
+  if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') {
+    process.stdout.write(`${USAGE}\n`)
+    return 0
+  }
+  if (cmd === '--version' || cmd === '-v' || cmd === 'version') {
+    process.stdout.write(`${VERSION}\n`)
+    return 0
+  }
+
+  switch (cmd) {
+    case 'guide':
+      process.stdout.write(`${help.GUIDE}\n`)
+      return 0
+    case 'collect':
+      return await cmdCollect(rest)
+    case 'take':
+      return await cmdTake(rest)
+    case 'status':
+      return await cmdStatus(rest)
+    case 'dispatch':
+      return await cmdDispatch(rest)
+    default:
+      process.stderr.write(`未知命令:${cmd}\n\n${USAGE}\n`)
+      return 2
+  }
+}
+
+async function cmdCollect(argv) {
+  const a = parseArgs(argv, { flags: ['help'] })
+  if (a.help) {
+    process.stdout.write(`${help.COLLECT_HELP}\n`)
+    return 0
+  }
+  const { runCollect } = require('../lib/collect')
+  return await runCollect({
+    exclude: list(a.exclude),
+    retain: num(a.retain, 3),
+    ledgerRetain: num(a['ledger-retain'], 90),
+  })
+}
+
+async function cmdTake(argv) {
+  const a = parseArgs(argv, { flags: ['help'] })
+  const larkcli = require('../lib/larkcli')
+
+  // 空参数输出完整照做指导,而非报错 —— AI 的真实行为是「先空参数跑一下看看」
+  if (a.help || (!a.app && !a.chats)) {
+    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
+  }
+
+  const store = require('../lib/store')
+  const { takeBatch, deriveName, parseChats } = require('../lib/take')
+  const { render } = require('../lib/render')
+  const { acquireExclusive } = require('../lib/lock')
+
+  if (!a.app || a.app === true) {
+    process.stderr.write('需要 --app <name>。跑 `lark-relay take` 看完整用法\n')
+    return 2
+  }
+  const chats = parseChats(a.chats === true ? '' : a.chats)
+  if (!chats.length) {
+    process.stderr.write('需要 --chats oc_xxx。跑 `lark-relay take` 看完整用法\n')
+    return 2
+  }
+  const bad = chats.filter((c) => !c.startsWith('oc_'))
+  if (bad.length) {
+    process.stderr.write(
+      `--chats 只接受 oc_ 开头的 chat_id,这些不是:${bad.join(' ')}\n` +
+        `群名会匹配错群,而监听错群是静默失败(你会一直等一个永不来的消息)。\n` +
+        `查 ID:lark-cli --profile ${a.app} im +chat-search --as user --query "<群名>"\n`,
+    )
+    return 2
+  }
+
+  const name = a.name && a.name !== true ? a.name : deriveName(a.app, chats)
+
+  // 同一 --name 不该有两个 take 在跑:两个进程互相推游标会撕批次
+  const lock = acquireExclusive(`take-${name}`)
+  if (!lock.ok) {
+    process.stderr.write(
+      `已有一个 take 在用游标身份 "${name}"(pid ${lock.holder})。\n` +
+        `要并行盯同一 app 请用不同 --name,否则两个进程会互相推游标撕批次。\n`,
+    )
+    return 3
+  }
+
+  const since = a.since === true ? 'now' : a.since || 'now'
+  if (since === 'now' && store.readCursor(name, a.app) === null) {
+    store.seedCursorNow(name, a.app) // 默认不重放历史,消灭「预热游标」这一步
+  }
+
+  const debounceMs = num(a.debounce, 5) * 1000
+  const maxWaitMs = num(a['max-wait'], 25) * 1000
+  const timeoutMs = num(a.timeout, 12 * 3600) * 1000
+
+  const ac = new AbortController()
+  const onSig = () => ac.abort()
+  process.on('SIGTERM', onSig)
+  process.on('SIGINT', onSig)
+
+  const res = await takeBatch({
+    app: a.app,
+    chats,
+    name,
+    filter: a.filter === true ? null : a.filter,
+    debounceMs,
+    maxWaitMs,
+    timeoutMs,
+    signal: ac.signal,
+  })
+
+  if (!res.events.length) {
+    process.stderr.write(`没等到消息(${res.reason})。游标身份 ${name}\n`)
+    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
+}
+
+async function cmdStatus(argv) {
+  const a = parseArgs(argv, { flags: ['json', 'help'] })
+  if (a.help) {
+    process.stdout.write(`${help.STATUS_HELP}\n`)
+    return 0
+  }
+  const { buildStatus, formatStatus } = require('../lib/status')
+  const s = await buildStatus()
+  if (a.json) process.stdout.write(`${JSON.stringify(s, null, 2)}\n`)
+  else process.stdout.write(`${formatStatus(s)}\n`)
+  return 0
+}
+
+async function cmdDispatch(argv) {
+  const a = parseArgs(argv, { flags: ['list', 'once', 'help'] })
+  if (a.help) {
+    process.stdout.write(`${help.DISPATCH_HELP}\n`)
+    return 0
+  }
+  const dispatch = require('../lib/dispatch')
+  if (a.list) return dispatch.cmdList()
+  const task = a._[0]
+  if (!task) {
+    process.stdout.write(`${help.DISPATCH_HELP}\n`)
+    return 2
+  }
+  return await dispatch.run(task, { once: !!a.once })
+}
+
+main()
+  .then((code) => process.exit(code || 0))
+  .catch((err) => {
+    if (err && err.userFacing) process.stderr.write(`${err.message}\n`)
+    else process.stderr.write(`lark-relay: ${(err && err.stack) || err}\n`)
+    process.exit(1)
+  })

package/lib/args.js

@@ -0,0 +1,52 @@
+'use strict'
+
+// 零依赖 argv 解析。只支持 --key value / --key=value / --flag。
+function parseArgs(argv, spec = {}) {
+  const flags = new Set(spec.flags || [])
+  const out = { _: [] }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--') {
+      out._.push(...argv.slice(i + 1))
+      break
+    }
+    if (!a.startsWith('--')) {
+      out._.push(a)
+      continue
+    }
+    const eq = a.indexOf('=')
+    if (eq !== -1) {
+      out[a.slice(2, eq)] = a.slice(eq + 1)
+      continue
+    }
+    const key = a.slice(2)
+    if (flags.has(key)) {
+      out[key] = true
+      continue
+    }
+    const next = argv[i + 1]
+    if (next === undefined || next.startsWith('--')) {
+      out[key] = true // 当成 flag,由调用侧校验
+    } else {
+      out[key] = next
+      i++
+    }
+  }
+  return out
+}
+
+function num(v, dflt) {
+  if (v === undefined || v === true) return dflt
+  const n = Number(v)
+  return Number.isFinite(n) ? n : dflt
+}
+
+function list(v) {
+  if (!v || v === true) return []
+  return String(v)
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean)
+}
+
+module.exports = { parseArgs, num, list }

package/lib/card.js

@@ -0,0 +1,218 @@
+'use strict'
+
+// card display:CardKit 流式打字机,单卡原地更新。ai-pmo 在用的模式。
+// 五步流:建卡实体 → 发引用消息 → 流式 PUT body → 收尾全卡重构 → 关流式定格。
+//
+// ⚠️ 两处双层编码(踩过):
+//   建卡的 data 与关流式的 settings 都是**字符串化的 JSON**,不是对象
+// ⚠️ print_frequency_ms / print_step 必须是按端对象 {default,android,ios,pc},
+//   传标量会 10002 unmarshal 报错
+const larkcli = require('./larkcli')
+
+const THROTTLE_MS = Number(process.env.LR_CARD_THROTTLE_MS || 300)
+const PRINT_FREQ_MS = Number(process.env.LR_CARD_PRINT_FREQ_MS || 10)
+const PRINT_STEP = Number(process.env.LR_CARD_PRINT_STEP || 20)
+const PLACEHOLDER = process.env.LR_CARD_PLACEHOLDER || '🤔 正在思考…'
+
+// 飞书卡片按标题字号渲染 #,窄卡片里过大突兀 → ATX 标题降级为加粗。
+// 必须状态机跳过 ``` 代码块:块内的 `# 注释`(shell/python)绝不能被误降级。
+function mdfix(text) {
+  const out = []
+  let inCode = false
+  for (const line of String(text).split('\n')) {
+    if (/^[ \t]*```/.test(line)) {
+      inCode = !inCode
+      out.push(line)
+      continue
+    }
+    if (!inCode) {
+      const m = line.match(/^#+[ \t]+(.*)$/)
+      if (m) {
+        out.push(m[1] === '' ? line : `**${m[1]}**`)
+        continue
+      }
+    }
+    out.push(line)
+  }
+  return out.join('\n')
+}
+
+function initCard() {
+  const perDevice = (v) => ({ default: v, android: v, ios: v, pc: v })
+  return {
+    schema: '2.0',
+    config: {
+      streaming_mode: true,
+      update_multi: true,
+      streaming_config: {
+        print_frequency_ms: perDevice(PRINT_FREQ_MS),
+        print_step: perDevice(PRINT_STEP),
+      },
+    },
+    // 不设 header:固定「🤖 Claude」标题头太突兀,去掉后卡片只剩正文更自然
+    body: {
+      elements: [{ tag: 'markdown', element_id: 'body', content: PLACEHOLDER }],
+    },
+  }
+}
+
+class CardSession {
+  constructor({ profile, chatId, lastMsg, replyInThread }) {
+    this.profile = profile
+    this.chatId = chatId
+    this.lastMsg = lastMsg
+    this.replyInThread = replyInThread
+    this.cardId = null
+    this.messageId = null
+    this.seq = 0 // int32 从 1 起,卡片更新串行无并发
+    this.lastPutAt = 0
+    this.acc = ''
+    this.proc = ''
+    this.pendingSay = null
+  }
+
+  next() {
+    return ++this.seq
+  }
+
+  // 步骤 ①:建卡片实体 → card_id。data 是**字符串**(双层编码)
+  async create() {
+    const body = JSON.stringify({ type: 'card_json', data: JSON.stringify(initCard()) })
+    const { stdout } = await larkcli.run([
+      '--profile', this.profile, 'api', 'POST', '/open-apis/cardkit/v1/cards',
+      '--as', 'bot', '--data', body,
+    ])
+    const j = JSON.parse(stripToJson(stdout))
+    this.cardId = j?.data?.card_id || null
+    return this.cardId
+  }
+
+  // 步骤 ②:发一条引用该 card_id 的消息
+  async post() {
+    const content = JSON.stringify({ type: 'card', data: { card_id: this.cardId } })
+    let out
+    if (this.replyInThread && this.lastMsg && this.lastMsg !== '-') {
+      const data = { msg_type: 'interactive', content, reply_in_thread: true }
+      out = await larkcli.run([
+        '--profile', this.profile, 'api', 'POST',
+        `/open-apis/im/v1/messages/${this.lastMsg}/reply`,
+        '--as', 'bot', '--data', JSON.stringify(data),
+      ])
+    } else {
+      out = await larkcli.run([
+        '--profile', this.profile, 'im', '+messages-send',
+        '--params', JSON.stringify({ receive_id_type: 'chat_id' }),
+        '--data', JSON.stringify({
+          receive_id: this.chatId, msg_type: 'interactive', content,
+        }),
+        '--as', 'bot',
+      ])
+    }
+    const j = JSON.parse(stripToJson(out.stdout))
+    this.messageId = j?.data?.message_id || null
+    return this.messageId
+  }
+
+  // 步骤 ③:流式期单 body 元素全量替换(打字机)。
+  // 全量替换故本地要维护累积串;单次失败可容忍(下次 PUT 是全量,自愈)。
+  async update(text) {
+    const now = Date.now()
+    if (now - this.lastPutAt < THROTTLE_MS) return // 仅防频控,不为攒批
+    this.lastPutAt = now
+    const content = mdfix(text || '🔧 正在查阅…')
+    try {
+      await larkcli.run([
+        '--profile', this.profile, 'api', 'PUT',
+        `/open-apis/cardkit/v1/cards/${this.cardId}/elements/body/content`,
+        '--as', 'bot',
+        '--data', JSON.stringify({ content, sequence: this.next() }),
+      ])
+    } catch {}
+  }
+
+  // 步骤 ④:收尾全卡重构。注意外层键是 card(内含 {type,data}),不是 ③ 的 content
+  async finalize(result) {
+    const elements = []
+    if (this.proc.trim()) {
+      elements.push({
+        tag: 'collapsible_panel',
+        expanded: false,
+        header: { title: { tag: 'markdown', content: '💭 思考与执行过程(点击展开)' } },
+        elements: [{ tag: 'markdown', content: mdfix(this.proc) }],
+      })
+      elements.push({ tag: 'hr' })
+    }
+    // 无过程内容时只放结论,不放空面板
+    elements.push({ tag: 'markdown', content: mdfix(result) })
+    const card = {
+      schema: '2.0',
+      config: { streaming_mode: false },
+      body: { elements },
+    }
+    const body = JSON.stringify({
+      card: { type: 'card_json', data: JSON.stringify(card) },
+      sequence: this.next(),
+    })
+    try {
+      const { stdout } = await larkcli.run([
+        '--profile', this.profile, 'api', 'PUT',
+        `/open-apis/cardkit/v1/cards/${this.cardId}`,
+        '--as', 'bot', '--data', body,
+      ])
+      return /"ok":\s*true/.test(stdout)
+    } catch (err) {
+      const tail = String(err.stdout || err.stderr || err.message).replace(/\n/g, ' ').slice(0, 200)
+      process.stderr.write(`card: 收尾全卡更新失败 → ${tail}\n`)
+      return false
+    }
+  }
+
+  // 步骤 ⑤:关流式定格。settings 的值是**字符串化的 JSON**(双层转义)
+  async stop() {
+    try {
+      await larkcli.run([
+        '--profile', this.profile, 'api', 'PATCH',
+        `/open-apis/cardkit/v1/cards/${this.cardId}/settings`,
+        '--as', 'bot',
+        '--data', JSON.stringify({
+          settings: JSON.stringify({ config: { streaming_mode: false } }),
+          sequence: this.next(),
+        }),
+      ])
+    } catch {}
+  }
+
+  // 流式事件三种 kind。pendingSay 延迟一段:每轮最后一段 say 就是最终结论
+  // (会作为 result 再来一次),不能进过程区否则结论重复。
+  // 用「延迟一段」而非内容比较 —— 最稳。
+  onSay(text) {
+    this.acc += (this.acc ? '\n\n' : '') + text
+    this._flushPending()
+    this.pendingSay = text
+  }
+
+  onTool(text) {
+    this.acc += (this.acc ? '\n\n' : '') + `_🔧 ${text}_`
+    this._flushPending()
+    this.proc += `🔧 ${text}\n`
+  }
+
+  onFinal() {
+    this.pendingSay = null // 手里那段 pending(=结论)直接丢弃,不 flush
+  }
+
+  _flushPending() {
+    if (this.pendingSay) {
+      this.proc += `💬 ${this.pendingSay}\n\n`
+      this.pendingSay = null
+    }
+  }
+}
+
+// lark-cli 可能有前置非 JSON 行,剥到第一个 { 起
+function stripToJson(s) {
+  const i = String(s).indexOf('{')
+  return i === -1 ? '{}' : String(s).slice(i)
+}
+
+module.exports = { CardSession, mdfix }