lark-relay 0.1.1 → 0.2.1

package/README.md

@@ -74,10 +74,30 @@ 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
+# display: card     默认;card | cot | final(见下)
 # model: <名称>      默认走终端同一套默认路由
 ```
 
+`display` 三档:
+
+| 档 | 过程展示 | 结论 | 备注 |
+| --- | --- | --- | --- |
+| `card` | CardKit 流式打字机,单卡原地更新 | 写进同一张卡片 | 收尾 PUT 失败自动回退纯文本 |
+| `cot` | 思考过程挂在 COT 消息上(AG-UI 事件流) | **总是单独发一条** | 客户端 PC ≥ 7.70 / 移动 ≥ 7.74 |
+| `final` | 无 | 单独发一条 | 最省事,不流式 |
+
+`cot` 档的「结论单独发」不是降级路径,而是 COT 接口的设计前提 —— COT 消息只承载
+过程。它也**不写工具结果**:工具输出动辄几千字符且可能含不宜进群的仓库内容,
+与 `card` 档只显示工具名+参数摘要一致。
+
+⚠️ **老客户端(< 7.70)看不到过程**:COT 消息底层是 `msg_type: post`,不支持的客户端
+只会看到一条内容为「Completed」的消息(实测,不会崩)。群里有老客户端用户时选 `card`。
+结论那条普通文本不受影响 —— 这也是「结论单独发」的价值。
+
+环境变量:`LR_COT_BATCH_MS`(攒批窗口,默认 1000)、
+`LR_COT_SAY_AS=text|reasoning`(中间文本走正式文本流还是思考流,默认 `text`)。
+实测两者渲染一致,`text` 每段少 2 个事件(reasoning 多一对 START/END 包裹)。
+
 ## 存储布局
 
 ```

package/lib/card.js

@@ -1,6 +1,6 @@
 'use strict'
 
-// card display:CardKit 流式打字机,单卡原地更新。ai-pmo 在用的模式。
+// card display:CardKit 流式打字机,单卡原地更新。
 // 五步流:建卡实体 → 发引用消息 → 流式 PUT body → 收尾全卡重构 → 关流式定格。
 //
 // ⚠️ 两处双层编码(踩过):
@@ -8,6 +8,7 @@
 // ⚠️ print_frequency_ms / print_step 必须是按端对象 {default,android,ios,pc},
 //   传标量会 10002 unmarshal 报错
 const larkcli = require('./larkcli')
+const { stripToJson, errText, tail } = 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)
@@ -64,17 +65,30 @@ class CardSession {
     this.replyInThread = replyInThread
     this.cardId = null
     this.messageId = null
-    this.seq = 0 // int32 从 1 起,卡片更新串行无并发
+    this.seq = 0 // int32 从 1 起
     this.lastPutAt = 0
     this.acc = ''
     this.proc = ''
     this.pendingSay = null
+    // 串行队列:所有卡片写操作排队执行。
+    // ⚠️ onEvent 里的 update() 是 fire-and-forget(不 await),若并发发出,
+    // 晚发的可能先到 → 服务端拒较小 sequence;更糟的是 in-flight 的 update
+    // (seq 小、body 大所以慢)在 finalize/stop 之后才到达 →
+    // **卡片从最终结论退回中间过程文本并定格在那里**(流式已关,不会再刷新)。
+    // 实测到达顺序曾是 finalize(2) → stop(3) → update(1)
+    this.q = Promise.resolve()
   }
 
   next() {
     return ++this.seq
   }
 
+  // 把卡片写操作排进串行队列。seq 在**真正执行时**才取,保证发出顺序 == seq 顺序
+  _enqueue(fn) {
+    this.q = this.q.then(fn, fn)
+    return this.q
+  }
+
   // 步骤 ①:建卡片实体 → card_id。data 是**字符串**(双层编码)
   async create() {
     const body = JSON.stringify({ type: 'card_json', data: JSON.stringify(initCard()) })
@@ -115,71 +129,78 @@ class CardSession {
 
   // 步骤 ③:流式期单 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 {}
+  // 走串行队列:调用方 fire-and-forget 也不会乱序
+  update(text) {
+    return this._enqueue(async () => {
+      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) }],
+  // 步骤 ④:收尾全卡重构。注意外层键是 card(内含 {type,data}),不是 ③ 的 content。
+  // 排在队尾执行 —— 必须等所有 in-flight update 落地,否则会被它们覆盖
+  finalize(result) {
+    return this._enqueue(async () => {
+      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(),
       })
-      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) {
+        process.stderr.write(`card: 收尾全卡更新失败 → ${tail(errText(err), 200)}\n`)
+        return false
+      }
     })
-    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 {}
+  stop() {
+    return this._enqueue(async () => {
+      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 就是最终结论
@@ -209,10 +230,4 @@ class CardSession {
   }
 }
 
-// lark-cli 可能有前置非 JSON 行,剥到第一个 { 起
-function stripToJson(s) {
-  const i = String(s).indexOf('{')
-  return i === -1 ? '{}' : String(s).slice(i)
-}
-
 module.exports = { CardSession, mdfix }

package/lib/claude.js

@@ -7,10 +7,12 @@ const os = require('os')
 const path = require('path')
 const { spawn } = require('child_process')
 
-// 模型分发交给 dotfiles 里的 claude() 函数 —— 它有白名单校验,是单一事实源。
-// 旧架构存的是内部函数名(route: cc-48,实测早已不存在),改存模型名后
-// 新增后端零改动,写错也会被分发器 exit 2 挡住。
-const CC_RC = process.env.LR_CC_RC || path.join(os.homedir(), 'space/dotfiles/rc.d/claude.sh')
+// 模型分发交给一个 shell 函数 `claude()` —— 由它做白名单校验与后端路由,
+// 是模型名的单一事实源。包不自己维护模型清单(那样新增后端要改两处)。
+//
+// LR_CC_RC 指向定义了 `claude()` 的 rc 文件。默认值只是个约定俗成的位置,
+// 部署时按实际环境设置:Environment=LR_CC_RC=%h/path/to/claude.sh
+const CC_RC = process.env.LR_CC_RC || path.join(os.homedir(), '.claude-route.sh')
 
 // sha1(task|scope) 前 32 位切成 8-4-4-4-12
 function deriveUuid(task, scope) {
@@ -86,15 +88,23 @@ function runClaude(opts) {
   args.push('--output-format', stream ? 'stream-json' : 'json')
   if (stream) args.push('--verbose')
 
-  // 经 bash -lc source claude.sh 后调 claude() —— 模型分发与白名单校验都在那里
+  // 经 bash -lc source <rc> 后调 claude() —— 模型分发与白名单校验都在那里。
+  // rc 不存在时**不当致命错误**:降级到 PATH 里的 claude,只在指定了 --model 时才必须有 rc
+  // (否则 --model 传给原生 claude 会是另一套语义)。
+  // ⚠️ CC_RC 必须 shellQuote:曾直接内插进双引号里的 echo,
+  // LR_CC_RC='/x$(命令)' 会被执行(实测)。所有插进 script 的值一律走 shellQuote
   const quoted = args.map(shellQuote).join(' ')
-  const modelArg = model ? `--model ${shellQuote(model)} ` : ''
-  const script =
-    `set -o pipefail\n` +
-    `if ! source ${shellQuote(CC_RC)} 2>/dev/null; then\n` +
-    `  echo "cc: 无法 source ${CC_RC}" >&2; exit 3\n` +
-    `fi\n` +
-    `claude ${modelArg}${quoted}\n`
+  const rcQ = shellQuote(CC_RC)
+  const script = model
+    ? `set -o pipefail\n` +
+      `if ! source ${rcQ} 2>/dev/null; then\n` +
+      `  printf '%s\\n' "cc: 指定了 --model 但 source 失败,设 LR_CC_RC 指向定义 claude() 的文件" >&2\n` +
+      `  exit 3\n` +
+      `fi\n` +
+      `claude --model ${shellQuote(model)} ${quoted}\n`
+    : `set -o pipefail\n` +
+      `source ${rcQ} 2>/dev/null || true\n` +
+      `claude ${quoted}\n`
 
   return new Promise((resolve) => {
     const child = spawn('bash', ['-lc', script], {
@@ -196,12 +206,4 @@ function shellQuote(s) {
   return `'${String(s).replace(/'/g, `'\\''`)}'`
 }
 
-module.exports = {
-  runClaude,
-  deriveUuid,
-  sessionEpoch,
-  sessionFile,
-  encCwd,
-  PROMPT_TEMPLATE,
-  CC_RC,
-}
+module.exports = { runClaude, deriveUuid, sessionEpoch, PROMPT_TEMPLATE }

package/lib/collect.js

@@ -24,6 +24,7 @@ class AppCollector {
     this.stopped = false
     this.backoffMs = 1000
     this.restarts = 0
+    this.healthyTimer = null
   }
 
   start() {
@@ -50,39 +51,55 @@ class AppCollector {
       try {
         store.writeEvent(this.app, obj, this.seq++)
         this.received++
-        // 收到第一条就说明这个 app 通了,重置退避
-        this.backoffMs = 1000
       } catch (err) {
         process.stderr.write(`[${this.app}] error: 落盘失败 ${err.message}\n`)
       }
     })
 
+    // 退避重置的判据是「子进程活够久」而非「收到消息」:
+    // 某 app 长期没消息但连接正常时,退避会一路顶到 60s 上限再也不降,
+    // 占空比掉到 50% 以下 —— 而那段时间的消息是永久丢的
+    this.healthyTimer = setTimeout(() => {
+      this.backoffMs = 1000
+    }, 30_000)
+
     // 不加 --quiet:它会隐藏事件丢失。stderr 的 ready/exit/drop 诊断进 journald
     child.stderr.on('data', (buf) => {
       const text = buf.toString().trimEnd()
       if (text) process.stderr.write(`[${this.app}] ${text}\n`)
     })
 
-    child.on('exit', (code, signal) => {
+    // spawn 失败(lark-cli 被卸载 / 升级中途 / PATH 变化)只发 error+close,**没有 exit**。
+    // 把重启逻辑挂在 close 上,否则该 app 会永久停摆而主进程看着还 active
+    let restarted = false
+    const scheduleRestart = (why) => {
+      if (restarted || this.stopped) return
+      restarted = true
+      clearTimeout(this.healthyTimer)
       this.child = null
-      if (this.stopped) return
       this.restarts++
-      const why = signal ? `signal ${signal}` : `code ${code}`
       process.stderr.write(
-        `[${this.app}] consume 退出(${why}),${Math.round(this.backoffMs / 1000)}s 后重启\n`,
+        `[${this.app}] consume 退出(${why}),${Math.round(this.backoffMs / 1000)}s 后重启 ` +
+          `—— 这段时间该 app 的消息会永久丢失\n`,
       )
       // 每 app 一个子进程;某个挂了单独重启,不影响其他
       setTimeout(() => this.start(), this.backoffMs)
       this.backoffMs = Math.min(this.backoffMs * 2, 60_000)
+    }
+
+    child.on('close', (code, signal) => {
+      scheduleRestart(signal ? `signal ${signal}` : `code ${code}`)
     })
 
     child.on('error', (err) => {
       process.stderr.write(`[${this.app}] spawn 失败:${err.message}\n`)
+      scheduleRestart(`spawn error ${err.code || err.message}`)
     })
   }
 
   stop() {
     this.stopped = true
+    clearTimeout(this.healthyTimer)
     // 优雅停止:SIGTERM。禁 SIGKILL —— 否则漏卸载服务端订阅
     if (this.child) this.child.kill('SIGTERM')
   }
@@ -94,7 +111,20 @@ async function runCollect(opts) {
   ensureDir(paths.ledger)
 
   const exclude = new Set(opts.exclude || [])
-  const profiles = await larkcli.listProfiles()
+  let profiles
+  try {
+    profiles = await larkcli.listProfiles()
+  } catch (err) {
+    const e = new Error(
+      `读不到 lark-cli profile 列表:${(err.message || '').split('\n')[0]}\n` +
+        `collect 依赖 lark-cli 提供认证与事件总线。检查:\n` +
+        `  which ${larkcli.CLI}          # 装了吗、在 PATH 里吗\n` +
+        `  ${larkcli.CLI} profile list   # 能跑吗\n` +
+        `systemd 单元里 PATH 要用 fnm default alias 的稳定路径,不能用会话级的 multishell 路径`,
+    )
+    e.userFacing = true
+    throw e
+  }
 
   const chosen = []
   const skipped = []
@@ -164,4 +194,4 @@ async function runCollect(opts) {
   })
 }
 
-module.exports = { runCollect, EVENT_KEY }
+module.exports = { runCollect }