lark-relay 0.1.1 → 0.2.1

package/lib/cot.js

@@ -0,0 +1,363 @@
+'use strict'
+
+// cot display:消息上挂载「思考过程」,事件流对齐 AG-UI 协议。
+// 三步流:POST 建 COT 消息 → PUT 攒批写事件(可反复)→ RUN_FINISHED 自动完结。
+// 接口与 CardSession 同构,让 dispatch 里两档只差一个 new。
+// 接口细节与实测边界见 docs/cot-message-api.md
+//
+// **COT 只承载过程,结论必须单独发一条普通消息** —— 接口的设计前提,不是我们的选择。
+// 故本类没有 card.finalize(result) 那种「把结论写进载体」的能力。
+//
+// ⚠️ content 是**字符串化的 JSON**(双层编码),_encode 统一处理
+// ⚠️ RUN_FINISHED / RUN_ERROR 后再写事件被硬拒("COT already in terminal state"),
+//   故 finalize 之后必须闭嘴 —— 用 this.done 守
+const larkcli = require('./larkcli')
+const { stripToJson, errText, tail } = larkcli
+
+const BATCH_MS = Number(process.env.LR_COT_BATCH_MS || 1000)
+const MAX_EVENTS = 50 // 接口硬上限:events[] 每次 1~50 条
+// 单条 content 上限是**序列化后 4096 字节**,不是字符(文档写「字符」)。
+// 中文每字 3 字节 → 按字符截会稳定超限,且一条超长会让同批全部事件被拒
+const MAX_CONTENT_BYTES = 4096
+
+// say 映射到哪类事件。**实测两者渲染完全一致**,故按事件量取舍:
+// text 每段 3 个事件,reasoning 每段 5 个(多一对外包裹)。
+// 留开关是因为渲染一致不保证永远一致
+const SAY_AS = process.env.LR_COT_SAY_AS === 'reasoning' ? 'reasoning' : 'text'
+
+// claude 工具名 → COT 内置 icon 枚举。
+// 枚举只有 search/bash/read/write/doc/calendar/task/meeting/default,
+// 不在表里的一律 default —— 传非枚举值的渲染行为未验证,不赌。
+const ICONS = {
+  Bash: 'bash',
+  BashOutput: 'bash',
+  Read: 'read',
+  NotebookRead: 'read',
+  Edit: 'write',
+  Write: 'write',
+  NotebookEdit: 'write',
+  Grep: 'search',
+  Glob: 'search',
+  WebSearch: 'search',
+  WebFetch: 'search',
+  Task: 'task',
+  TodoWrite: 'task',
+}
+
+function iconFor(tool) {
+  return ICONS[tool] || 'default'
+}
+
+// 按 UTF-8 字节截断,且不切坏字符(码点边界对齐)。
+// 不能按码点数截 —— 上限是字节,中文每字 3 字节(见 MAX_CONTENT_BYTES)
+function clipBytes(s, maxBytes) {
+  const str = String(s)
+  if (Buffer.byteLength(str, 'utf8') <= maxBytes) return str
+  const ell = '…'
+  const ellBytes = Buffer.byteLength(ell, 'utf8')
+  // 连省略号都装不下 → 返回空串。否则 '' + '…' 会**超过** maxBytes,
+  // 破坏「返回值 ≤ maxBytes」这个契约(本函数是导出的)
+  if (maxBytes < ellBytes) return ''
+  const budget = maxBytes - ellBytes
+  // Buffer 直切会把多字节字符切成半个 → 用码点逐个累加,天然对齐边界。
+  // 逐码点而非逐 UTF-16 单元:emoji 等代理对不能拆
+  let bytes = 0
+  let out = ''
+  for (const ch of str) {
+    const b = Buffer.byteLength(ch, 'utf8')
+    if (bytes + b > budget) break
+    out += ch
+    bytes += b
+  }
+  return out + ell
+}
+
+class CotSession {
+  constructor({ profile, chatId, lastMsg, replyInThread }) {
+    this.profile = profile
+    this.chatId = chatId
+    this.lastMsg = lastMsg
+    this.replyInThread = replyInThread
+    this.cotId = null
+    this.messageId = null
+    this.done = false // 已写 RUN_FINISHED/RUN_ERROR;之后写入必被拒
+    this.acc = '' // **只写不读**,纯为与 CardSession 接口同构;无消费者,别维护它的格式
+    // 只用来生成本地唯一 id,**从不发给服务端**。
+    // ⚠️ 与 CardSession.seq 同名但无关:那个是服务端排序号,小了会被拒
+    this.seq = 0
+    this.pending = [] // 待发事件队列
+    this.pendingSay = null // 延迟一段的 say(见 onSay);结论不能进过程区
+    this.timer = null
+    // 串行队列:PUT 必须按写入顺序到达,晚发先到会让 delta 乱序拼接。
+    // 与 CardSession 的 q 同一理由(那边是 sequence 被服务端拒,这边是文本错位)。
+    this.q = Promise.resolve()
+  }
+
+  _enqueue(fn) {
+    this.q = this.q.then(fn, fn)
+    return this.q
+  }
+
+  // 步骤 ①:建 COT 消息 → {cot_id, message_id}。两者后续都要带。
+  // origin_message_id 让 COT 挂在触发它的那条用户消息上。
+  async create() {
+    const data = { receive_id: this.chatId }
+    if (this.lastMsg && this.lastMsg !== '-') data.origin_message_id = this.lastMsg
+    if (this.replyInThread) data.reply_in_thread = true
+    const { stdout } = await larkcli.run([
+      '--profile', this.profile, 'api', 'POST', '/open-apis/im/v1/message_cot',
+      '--params', JSON.stringify({ receive_id_type: 'chat_id' }),
+      '--as', 'bot', '--data', JSON.stringify(data),
+    ])
+    const j = JSON.parse(stripToJson(stdout))
+    this.cotId = j?.data?.cot_id || null
+    this.messageId = j?.data?.message_id || null
+    if (!this.cotId || !this.messageId) return null
+    // RUN_STARTED 立刻发,让消息一出现就是「在跑」而不是空壳
+    this._push(['RUN_STARTED', { runId: this.cotId, threadId: this.cotId }])
+    await this.flush()
+    return this.cotId
+  }
+
+  // 与 CardSession 接口对齐:COT 一步建好,没有「另发一条消息引用它」的步骤
+  async post() {
+    return this.messageId
+  }
+
+  // 编码单条事件:content 序列化 + 超 4096 字节时截断自由文本字段。
+  // 返回事件对象,null = 截不下来只能丢弃(整批被服务端拒比丢一条更糟)
+  _encode(eventType, content) {
+    let s = JSON.stringify(content)
+    if (Buffer.byteLength(s, 'utf8') > MAX_CONTENT_BYTES) {
+      // 超长只可能来自 delta/title/message 这类自由文本
+      const key = ['delta', 'title', 'message'].find((k) => typeof content[k] === 'string')
+      if (!key) return null // 没有可截的字段 → 丢这条,过程事件不值得冒整批失败
+      // JSON 转义会膨胀(换行 2 字节、控制字符 6 字节),故截完再验、按实测比例收敛。
+      // 别用固定系数退让 —— 0.8 退 8 次才到 0.17,覆盖不了 6 倍膨胀(ANSI 日志会撞上)
+      const overhead = Buffer.byteLength(JSON.stringify({ ...content, [key]: '' }), 'utf8')
+      let budget = MAX_CONTENT_BYTES - overhead
+      for (let i = 0; i < 8 && budget > 0; i++) {
+        const clipped = { ...content, [key]: clipBytes(content[key], budget) }
+        s = JSON.stringify(clipped)
+        const actual = Buffer.byteLength(s, 'utf8')
+        if (actual <= MAX_CONTENT_BYTES) break
+        // 按本轮实测膨胀率反推能装多少,留 2% 余量
+        const ratio = (MAX_CONTENT_BYTES - overhead) / (actual - overhead)
+        const next = Math.floor(budget * ratio * 0.98)
+        budget = next < budget ? next : budget - 1 // 保证严格递减,不会死循环
+      }
+      // 截不下来就丢;配对的 START/END 由 _push 的成组语义一起丢,不留空气泡
+      if (Buffer.byteLength(s, 'utf8') > MAX_CONTENT_BYTES) return null
+    }
+    return { event_type: eventType, content: s, timestamp: String(Date.now()) }
+  }
+
+  // 成组入队:**同一组事件保证同批发出**。
+  // 一段 say 是 3 件套(reasoning 档 5 件)、一次工具调用是 2 件套 —— 若被切批拆散,
+  // 前半批失败就会让客户端收到没有 START 的孤立 CONTENT/END(渲染行为未验证)。
+  // 组内任一条因超长被丢 → 整组丢,不留「有气泡无内容」
+  _push(...events) {
+    if (this.done) return
+    const encoded = []
+    for (const [type, content] of events) {
+      const e = this._encode(type, content)
+      if (!e) return // 组内有一条编码不出来 → 整组不发
+      encoded.push(e)
+    }
+    // 装不下整组就先把已攒的发走,让这一组完整落进下一批 —— 这是「不跨批」的实现
+    if (this.pending.length && this.pending.length + encoded.length > MAX_EVENTS) this.flush()
+    this.pending.push(...encoded)
+    if (this.pending.length >= MAX_EVENTS) {
+      this.flush()
+    } else if (!this.timer) {
+      this.timer = setTimeout(() => this.flush(), BATCH_MS)
+      if (this.timer.unref) this.timer.unref() // 别让攒批定时器吊住进程退出
+    }
+  }
+
+  // 等队列排空后返回 v,且**吞掉 rejection** —— flush/update 返回的就是 this.q,
+  // 而它们被 fire-and-forget 调用,裸传 rejected 的 q 会终结常驻进程
+  _settled(v) {
+    return this.q.then(
+      () => v,
+      () => v,
+    )
+  }
+
+  // 步骤 ②:PUT 写事件。返回 bool —— **调用方靠它判断是否要兜底**
+  // (RUN_FINISHED 写失败则 COT 永久卡在「在跑」)。
+  // 整个 fn 体裹 try:flush() 绝不能抛(理由同 _settled);连日志的 EPIPE 也要吞
+  flush() {
+    if (this.timer) {
+      clearTimeout(this.timer)
+      this.timer = null
+    }
+    // 已封口:pending 里的事件注定被拒,清掉省下每批一次的失败请求 + 日志
+    if (this.done) {
+      this.pending = []
+      return this._settled(false)
+    }
+    // cotId 为 null 时**不清空 pending** —— create 还没成功,事件要活到它成功
+    if (!this.pending.length || !this.cotId) return this._settled(true)
+    const batch = this.pending
+    this.pending = []
+    return this._enqueue(async () => {
+      let ok = true
+      try {
+        // 切片非冗余:create 之前攒的事件可远超 50 条(那时 flush 提前返回且不清空)。
+        // 切点不会落在一段 say 中间 —— _push 的成组语义保证
+        for (let i = 0; i < batch.length; i += MAX_EVENTS) {
+          const events = batch.slice(i, i + MAX_EVENTS)
+          try {
+            await larkcli.run([
+              '--profile', this.profile, 'api', 'PUT', '/open-apis/im/v1/message_cot',
+              '--as', 'bot',
+              '--data', JSON.stringify({
+                events, message_id: this.messageId, cot_id: this.cotId,
+              }),
+            ])
+          } catch (err) {
+            ok = false
+            const t = tail(errText(err), 200)
+            process.stderr.write(`cot: 写事件失败(${events.length} 条)→ ${t}\n`)
+            // terminal state 之后的写入全是徒劳,直接封口
+            if (/terminal state/.test(t)) this.done = true
+            break // 一片失败,后续片多半同因,别刷屏
+          }
+        }
+      } catch {
+        ok = false // 含 stderr.write 抛 EPIPE 这类极端情况
+      }
+      return ok
+    })
+  }
+
+  // 中间文本。每段一个独立 messageId —— 同 id 的多条 CONTENT 会被客户端拼成一段,
+  // 而两次 say 之间通常隔着工具调用,拼起来读不通。
+  //
+  // **延迟一段**(与 CardSession 同机制):最后一段 say 就是结论,它会作为独立消息
+  // 再发一次 —— 也写进过程区群里就看到两遍。故压着最新一段,onFinal 时丢弃。
+  // 用「延迟一段」而非内容比较 —— 最稳(card.js 踩出来的)
+  onSay(text) {
+    this.acc += (this.acc ? '\n\n' : '') + text
+    this._flushPending()
+    this.pendingSay = text
+  }
+
+  _flushPending() {
+    if (this.pendingSay === null) return
+    const text = this.pendingSay
+    this.pendingSay = null
+    const id = `say-${++this.seq}`
+    if (SAY_AS === 'text') {
+      this._push(
+        ['TEXT_MESSAGE_START', { messageId: id, role: 'assistant' }],
+        ['TEXT_MESSAGE_CONTENT', { messageId: id, delta: String(text) }],
+        ['TEXT_MESSAGE_END', { messageId: id }],
+      )
+    } else {
+      this._push(
+        ['REASONING_START', { messageId: id }],
+        ['REASONING_MESSAGE_START', { messageId: id }],
+        ['REASONING_MESSAGE_CONTENT', { messageId: id, delta: String(text) }],
+        ['REASONING_MESSAGE_END', { messageId: id }],
+        ['REASONING_END', { messageId: id }],
+      )
+    }
+  }
+
+  // 工具调用。**不写 TOOL_CALL_RESULT**:输出动辄几千字符且可能含不宜进群的仓库内容,
+  // 与 card 档只显示工具名+参数摘要一致。text 形如 "Bash: ls -la"(claude.js 拼的)
+  onTool(text) {
+    this.acc += (this.acc ? '\n\n' : '') + `_🔧 ${text}_`
+    // 工具调用到来 = 前面那段 say 不是结论,可以放行了
+    this._flushPending()
+    const s = String(text)
+    const tool = s.split(':', 1)[0].trim()
+    const id = `tool-${++this.seq}`
+    this._push(
+      [
+        'TOOL_CALL_START',
+        {
+          toolCallId: id,
+          icon: iconFor(tool),
+          title: s,
+          toolCallName: tool || 'tool',
+        },
+      ],
+      ['TOOL_CALL_END', { toolCallId: id }],
+    )
+  }
+
+  // 与 CardSession 同签名同语义:手里那段 pending(= 结论)直接丢弃,不放行 ——
+  // 它会作为独立消息发出,写进过程区就成了群里的第二遍
+  onFinal() {
+    this.pendingSay = null
+  }
+
+  // 步骤 ③:RUN_FINISHED 自动完结 —— **但只在写入成功时**。写失败(500/频控/抖动)
+  // 那条终结事件就没到服务端,COT 永久卡在「在跑」→ 靠 complete 兜底(幂等,不守 done)。
+  // rc != 0 走 RUN_ERROR + 无条件 complete:RUN_ERROR 是否自动流转未验证,补一刀不亏
+  async finalize({ rc = 0, error = '' } = {}) {
+    if (!this.cotId || this.done) return false
+    if (rc === 0) {
+      this._push(['RUN_FINISHED', { runId: this.cotId, threadId: this.cotId }])
+      const ok = await this.flush()
+      this.done = true
+      if (!ok) await this.complete('done') // 它和最多 49 条事件同批,该批被拒就一起没了
+      return true
+    }
+    // rc != 0:没有「结论」这回事,压着的那段 say 是仅有的线索,放行
+    this._flushPending()
+    this._push([
+      'RUN_ERROR',
+      {
+        runId: this.cotId,
+        threadId: this.cotId,
+        message: clipBytes(error || `rc=${rc}`, 500),
+        code: String(rc),
+      },
+    ])
+    await this.flush()
+    this.done = true
+    await this.complete('error')
+    return true
+  }
+
+  // 手动关写入态。正常路径不需要(RUN_FINISHED 已流转),
+  // 留给异常中断 —— 不调的话 COT 会一直显示「在跑」
+  async complete(reason = 'done') {
+    if (!this.cotId) return false
+    return this._enqueue(async () => {
+      try {
+        await larkcli.run([
+          '--profile', this.profile, 'api', 'POST',
+          `/open-apis/im/v1/message_cot/complete/${this.cotId}`,
+          '--params', JSON.stringify({ message_id: this.messageId, reason }),
+          '--as', 'bot',
+        ])
+        return true
+      } catch {
+        return false
+      }
+    })
+  }
+
+  // 与 CardSession 接口对齐:onEvent 里 fire-and-forget 调,cot 侧攒批已自带节流
+  update() {
+    return this._settled()
+  }
+
+  // 与 CardSession 接口对齐。finalize 已完结,这里只兜「从没 finalize 成功」的情况:
+  // 超时被 SIGTERM、异常中断 —— 不调 complete 的话 COT 会一直显示「在跑」
+  async stop() {
+    if (this.done || !this.cotId) return
+    // 从没 finalize 就走到这里 = 异常中断,压着的那段不是结论 → 放行
+    this._flushPending()
+    await this.flush()
+    await this.complete('timeout')
+    this.done = true
+  }
+}
+
+module.exports = { CotSession, iconFor, clipBytes, SAY_AS, MAX_EVENTS, MAX_CONTENT_BYTES }

package/lib/dedup.js

@@ -66,4 +66,4 @@ class Dedup {
   }
 }
 
-module.exports = { Dedup, TTL_MS }
+module.exports = { Dedup }

package/lib/dispatch.js

@@ -14,8 +14,8 @@ const { paths, ensureDir } = require('./paths')
 const store = require('./store')
 const claude = require('./claude')
 const { CardSession } = require('./card')
+const { CotSession } = require('./cot')
 const { reply } = require('./reply')
-const larkcli = require('./larkcli')
 
 function cmdList() {
   const tasks = listTasks()
@@ -109,17 +109,19 @@ async function handleGroup(t, group, opts = {}) {
     }
 
     const replyInThread = session === 'thread'
-    const useCard = display === 'card'
-    let card = null
+    // card 与 cot 同构(create/post/onSay/onTool/onFinal/update),只差一个构造器。
+    // 差别只在收尾:card 把结论写进卡片,cot 的结论**必须**单独发(接口设计前提)
+    const Session = display === 'card' ? CardSession : display === 'cot' ? CotSession : null
+    let view = null
 
-    if (useCard) {
-      card = new CardSession({ profile, chatId, lastMsg, replyInThread })
+    if (Session) {
+      view = new Session({ profile, chatId, lastMsg, replyInThread })
       try {
-        if (!(await card.create())) throw new Error('建卡片实体失败')
-        if (!(await card.post())) throw new Error('发卡片消息失败')
+        if (!(await view.create())) throw new Error('建展示载体失败')
+        if (!(await view.post())) throw new Error('发展示消息失败')
       } catch (err) {
-        process.stderr.write(`card: ${err.message},回退 final\n`)
-        card = null
+        process.stderr.write(`${display}: ${err.message},回退 final\n`)
+        view = null
       }
     }
 
@@ -132,13 +134,13 @@ async function handleGroup(t, group, opts = {}) {
       allowedTools: cfg.allowed || 'Read Edit Write Bash',
       model: cfg.model,
       timeoutSec: Number(cfg.timeout) || 1800,
-      stream: !!card,
-      onEvent: card
+      stream: !!view,
+      onEvent: view
         ? (kind, text) => {
-            if (kind === 'say') card.onSay(text)
-            else if (kind === 'tool') card.onTool(text)
-            else if (kind === 'final') card.onFinal()
-            if (kind !== 'final') card.update(card.acc)
+            if (kind === 'say') view.onSay(text)
+            else if (kind === 'tool') view.onTool(text)
+            else if (kind === 'final') view.onFinal()
+            if (kind !== 'final') view.update(view.acc)
           }
         : null,
     })
@@ -153,12 +155,31 @@ async function handleGroup(t, group, opts = {}) {
               .slice(-300)}`
     }
 
-    if (card) {
-      // 全卡 PUT 失败必须降级发纯文本,保证结论必达
-      const ok = await card.finalize(final)
+    if (view && display === 'card') {
+      // 全卡 PUT 失败必须降级发纯文本,保证结论必达。
+      // 抛出时也当失败处理 —— 不依赖「CardSession 内部不抛」这个远处的性质
+      let ok = false
+      try {
+        ok = await view.finalize(final)
+        await view.stop()
+      } catch (err) {
+        process.stderr.write(`card: 收尾异常 → ${err.stack || err}\n`)
+      }
       if (!ok) await reply(profile, chatId, lastMsg, final, { inThread: replyInThread })
-      await card.stop()
     } else {
+      // cot 档:过程在 COT 消息里,结论**总是**单独发一条 —— 不是降级,是设计。
+      // ⚠️ 收尾必须包 try/catch 且排在 reply 之前不能挡住它:handleGroup 外层只有
+      //   try/finally(无 catch),收尾一抛就会跳过 reply + ledgerAppend,
+      //   而 take 游标已推 → 结论既不进群也不进台账,这批消息永不重来。
+      //   「过程展示是锦上添花,绝不能因它让整轮派活失败」—— 靠这里兜住
+      if (view) {
+        try {
+          await view.finalize({ rc: res.rc, error: res.err })
+          await view.stop()
+        } catch (err) {
+          process.stderr.write(`cot: 收尾异常(不影响结论)→ ${err.stack || err}\n`)
+        }
+      }
       await reply(profile, chatId, lastMsg, final, { inThread: replyInThread })
     }
 
@@ -210,32 +231,53 @@ async function run(task, opts = {}) {
   process.on('SIGINT', onSig)
 
   for (;;) {
-    const res = await takeBatch({
-      app: cfg.app,
-      chats,
-      name: consumer,
-      filter: cfg.filter,
-      debounceMs,
-      maxWaitMs: 75_000,
-      timeoutMs: opts.once ? 300_000 : 12 * 3600 * 1000,
-      signal: ac.signal,
-    })
+    let res
+    try {
+      res = await takeBatch({
+        app: cfg.app,
+        chats,
+        name: consumer,
+        filter: cfg.filter,
+        debounceMs,
+        maxWaitMs: 75_000,
+        timeoutMs: opts.once ? 300_000 : 12 * 3600 * 1000,
+        signal: ac.signal,
+      })
+    } catch (err) {
+      // 取批阶段的异常绝不能让进程退出:Restart=on-failure 会变成每 5s 崩一次,
+      // 而卡住的那条消息永远在队首 → 任务彻底停摆且看不出原因
+      process.stderr.write(`dispatch: ${task} 取批失败,15s 后重试 → ${err.stack || err}\n`)
+      if (opts.once) return 1
+      await new Promise((r) => setTimeout(r, 15_000))
+      continue
+    }
 
     if (res.events.length) {
       // 一个防抖窗口会吐同群多话题的消息,只按 chat_id 分组会**串话题**
-      for (const g of groupByChatThread(res.events)) {
+      const groups = groupByChatThread(res.events)
+      for (let i = 0; i < groups.length; i++) {
+        // 收到停止信号后不再开新一轮 claude:单元 TimeoutStopSec=30,
+        // 而一轮最长 1800s → 会被 SIGKILL,卡片停在占位符、结论不回群。
+        // 游标此时也没推(take 的 abort 分支只在有批次时推),故剩余组下次重新取到
+        if (stopping) {
+          process.stderr.write(
+            `dispatch: ${task} 正在停止,剩余 ${groups.length - i} 组留到下次\n`,
+          )
+          break
+        }
         try {
-          await handleGroup(t, g)
+          await handleGroup(t, groups[i])
         } catch (err) {
           process.stderr.write(`dispatch: ${task} 处理组失败 ${err.stack || err}\n`)
         }
       }
     } else if (opts.once) {
       process.stderr.write(`dispatch: 没等到消息(${res.reason})\n`)
+      return res.reason === 'timeout' ? 4 : 0 // 与 take 对齐:4 = 等超时,0 = 正常
     }
 
     if (opts.once || stopping) return 0
   }
 }
 
-module.exports = { run, cmdList, ledgerAppend, handleGroup }
+module.exports = { run, cmdList, handleGroup }

package/lib/filter.js

@@ -37,11 +37,16 @@ function applyFilter(events, expr) {
       maxBuffer: 64 * 1024 * 1024,
     })
   } catch (err) {
-    const e = new Error(
-      `--filter 表达式求值失败:${expr}\n${(err.stderr || err.message || '').trim()}`,
+    // 保守放行 + warn,不抛 —— 抛出去会让 dispatch 崩溃循环:
+    // 表达式对某类事件报错(如 `.mentions[].id` 遇到没有 mentions 的消息)时,
+    // 那条消息永远卡在队首,游标推不动,systemd 每 5s 重启一次,该任务彻底停摆。
+    // 放行的代价是模型多看几条本该滤掉的消息,远小于停摆
+    process.stderr.write(
+      `warn: --filter 求值失败,本批不过滤(${events.length} 条放行)。表达式:${expr}\n` +
+        `      ${(err.stderr || err.message || '').trim().split('\n')[0]}\n` +
+        `      提示:字段可能不存在,用 ? 和 // 兜底,如 '(.mentions // []) | any(.id == "ou_xxx")'\n`,
     )
-    e.userFacing = true
-    throw e
+    return events
   }
   const verdicts = out.split('\n').filter((l) => l.length > 0)
   // 求值行数应与事件数一致;不一致说明表达式产出多值,保守放行全部并 warn

package/lib/help.js

@@ -90,9 +90,16 @@ dispatch.yaml（5 必填 + 3 可选）
   instructions: ./instructions.md  # 职责/边界,--append-system-prompt-file 注入
   filter: '.mentions[]?.id == "ou_xxx"'   # 可选
   # session: thread   默认;thread=按 thread_id 隔离 | idle=一群一 session
-  # display: card     默认;card | final
+  # display: card     默认;card | cot | final
   # model: <名称>      默认走终端同一套默认路由
 
+display 三档
+  card   CardKit 流式打字机,单卡原地更新,结论写进卡片(收尾失败回退纯文本)
+  cot    思考过程挂在 COT 消息上,**结论总是单独发一条**(接口设计前提,非降级)
+         客户端门槛 PC ≥ 7.70 / 移动 ≥ 7.74;老客户端只看到一条「Completed」
+         (不崩,但过程不可见 → 群里有老客户端就选 card);不写工具结果
+  final  只发最终结论,不展示过程
+
 最佳实践
   · 边界写 instructions,别指望 --add-dir 目录的 CLAUDE.md（启动不加载）
   · 改完 yaml 先 --once 跑一轮验证,再 enable