lark-relay 0.2.0 → 0.2.2

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

@@ -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)
@@ -179,10 +180,7 @@ class CardSession {
         ])
         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`)
+        process.stderr.write(`card: 收尾全卡更新失败 → ${tail(errText(err), 200)}\n`)
         return false
       }
     })
@@ -232,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

@@ -206,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

@@ -194,4 +194,4 @@ async function runCollect(opts) {
   })
 }
 
-module.exports = { runCollect, EVENT_KEY }
+module.exports = { runCollect }

package/lib/cot.js

@@ -0,0 +1,394 @@
+'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 枚举。
+// 实测 9 个枚举全部有专属图标(search 🔍 / bash </> / read 📖 / write ✏️ / doc 📄 /
+// calendar 📅 / task ☑️ / meeting 📹 / default ●)。文档外的值多数回落成 default 的圆点,
+// 少数(shell/edit/web)生效但只是已有图标的别名 —— 没有新增表达力且无兼容承诺,不用
+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',
+}
+
+// MCP 工具名(mcp__<server>__<action>)按名字猜 —— 它们在 dispatch 场景很常见,
+// 一律给 default 的圆点等于没信息。命名约定不保证,故只在猜中时用。
+// **顺序即优先级**:域名词(doc/task/calendar)比动词更能说明工具属于哪个域,故排在前
+const MCP_HINTS = [
+  [/meeting|minutes|\bvc\b/, 'meeting'],
+  [/calendar|schedule/, 'calendar'],
+  [/task|todo/, 'task'],
+  [/doc|sheet|base|wiki|file/, 'doc'],
+  [/write|create|update|edit|send|post|delete/, 'write'],
+  [/read|get|fetch|view/, 'read'],
+  [/search|find|query|list/, 'search'],
+]
+
+function iconFor(tool) {
+  if (ICONS[tool]) return ICONS[tool]
+  const s = String(tool).toLowerCase()
+  if (s.startsWith('mcp__')) {
+    for (const [re, icon] of MCP_HINTS) if (re.test(s)) return icon
+  }
+  return '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.lastStamp = 0 // 事件 timestamp 的单调下界(见 _stamp)
+    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(this._stamp()) }
+  }
+
+  // 事件 timestamp 必须**严格单调递增**。
+  // 实测(2026-08-20):同一批 8 个 delta 用相同 timestamp 时,客户端渲染成
+  // 「3 2 6 8 7 5 4 1」—— 不是反转而是完全打乱,说明它按 timestamp 排序且排序不稳定。
+  // 而一段 say 的 START/CONTENT/END 是同步生成的,Date.now() 必然相同 → 文字错乱。
+  // 墙上时间只作下界,计数器保证单调(同 paths.js 的 stamp,时钟回拨也不倒退)
+  _stamp() {
+    const now = Date.now()
+    this.lastStamp = now > this.lastStamp ? now : this.lastStamp + 1
+    return this.lastStamp
+  }
+
+  // 成组入队:**同一组事件保证同批发出**。
+  // 一段 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 })
     }
 
@@ -259,4 +280,4 @@ async function run(task, opts = {}) {
   }
 }
 
-module.exports = { run, cmdList, ledgerAppend, handleGroup }
+module.exports = { run, cmdList, handleGroup }

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

package/lib/larkcli.js

@@ -23,6 +23,27 @@ function run(args, opts = {}) {
   })
 }
 
+// lark-cli 的 stdout 可能有前置非 JSON 行(如「installed successfully」自更新提示),
+// 剥到第一个 { 起。这是 lark-cli 的输出契约,故与 run 同处一地。
+//
+// ⚠️ **只适用于对象响应**:数组响应会被切坏 ——
+//    stripToJson('[{"a":1}]') → '{"a":1}]' → JSON.parse 抛错。
+//    listProfiles 解析的正是数组,所以它不能用这个(它直接 JSON.parse)
+function stripToJson(s) {
+  const i = String(s).indexOf('{')
+  return i === -1 ? '{}' : String(s).slice(i)
+}
+
+// execFile 失败时错误信息散在三个字段里,取第一个有内容的
+function errText(err) {
+  return String(err.stdout || err.stderr || err.message || err)
+}
+
+// 压成单行并截断,给 stderr 日志用。行首那段才是错误码/原因所在
+function tail(s, n = 300) {
+  return String(s).replace(/\n/g, ' ').slice(0, n)
+}
+
 // profile list 默认输出 JSON,无需 --json。
 // 两类不可用,都要跳过,否则 consume 一直失败重试(死循环):
 // - tokenStatus 为 expired:授权过期,永久失败直到用户重新 login
@@ -57,111 +78,4 @@ function spawnConsume(profile, eventKey, extraArgs = []) {
   return spawn(CLI, args, { stdio: ['pipe', 'pipe', 'pipe'] })
 }
 
-async function sendText(profile, chatId, text, opts = {}) {
-  const params = { receive_id_type: 'chat_id' }
-  const data = {
-    receive_id: chatId,
-    msg_type: 'text',
-    content: JSON.stringify({ text }),
-  }
-  const args = [
-    '--profile',
-    profile,
-    'im',
-    '+messages-send',
-    '--params',
-    JSON.stringify(params),
-    '--data',
-    JSON.stringify(data),
-    '--as',
-    'bot',
-  ]
-  if (opts.replyTo) return replyText(profile, opts.replyTo, text, opts)
-  const { stdout } = await run(args)
-  return JSON.parse(stdout)
-}
-
-async function replyText(profile, messageId, text, opts = {}) {
-  const data = {
-    msg_type: 'text',
-    content: JSON.stringify({ text }),
-  }
-  if (opts.inThread) data.reply_in_thread = true
-  const args = [
-    '--profile',
-    profile,
-    'api',
-    'POST',
-    `/open-apis/im/v1/messages/${messageId}/reply`,
-    '--data',
-    JSON.stringify(data),
-    '--as',
-    'bot',
-  ]
-  const { stdout } = await run(args)
-  return JSON.parse(stdout)
-}
-
-async function sendCard(profile, chatId, card, opts = {}) {
-  const content = JSON.stringify(card)
-  if (opts.replyTo) {
-    const data = { msg_type: 'interactive', content }
-    if (opts.inThread) data.reply_in_thread = true
-    const { stdout } = await run([
-      '--profile',
-      profile,
-      'api',
-      'POST',
-      `/open-apis/im/v1/messages/${opts.replyTo}/reply`,
-      '--data',
-      JSON.stringify(data),
-      '--as',
-      'bot',
-    ])
-    return JSON.parse(stdout)
-  }
-  const { stdout } = await run([
-    '--profile',
-    profile,
-    'im',
-    '+messages-send',
-    '--params',
-    JSON.stringify({ receive_id_type: 'chat_id' }),
-    '--data',
-    JSON.stringify({ receive_id: chatId, msg_type: 'interactive', content }),
-    '--as',
-    'bot',
-  ])
-  return JSON.parse(stdout)
-}
-
-// reply 返回体的 thread_id 是 null,要单独查消息详情才拿得到(实测)。
-async function getMessageThreadId(profile, messageId) {
-  try {
-    const { stdout } = await run([
-      '--profile',
-      profile,
-      'api',
-      'GET',
-      `/open-apis/im/v1/messages/${messageId}`,
-      '--as',
-      'bot',
-    ])
-    const j = JSON.parse(stdout)
-    const items = j?.data?.items || j?.items || []
-    return items[0]?.thread_id || null
-  } catch {
-    return null
-  }
-}
-
-module.exports = {
-  CLI,
-  run,
-  listProfiles,
-  spawnConsume,
-  sendText,
-  replyText,
-  sendCard,
-  getMessageThreadId,
-}
+module.exports = { CLI, run, stripToJson, errText, tail, listProfiles, spawnConsume }

package/lib/reply.js

@@ -3,6 +3,7 @@
 // 回群:超长按**字符**分片。飞书单条 text 有长度上限,超长会整条发送失败
 // (用户收不到任何东西),故必须分片而非截断。
 const larkcli = require('./larkcli')
+const { errText, tail } = larkcli
 
 const CHUNK = Number(process.env.LR_REPLY_CHUNK || 3500)
 
@@ -65,12 +66,4 @@ async function replyOne(profile, chatId, msgId, text, inThread) {
   }
 }
 
-function errText(err) {
-  return String(err.stdout || err.stderr || err.message || err)
-}
-
-function tail(s) {
-  return String(s).replace(/\n/g, ' ').slice(0, 300)
-}
-
 module.exports = { reply, CHUNK }

package/lib/tasks.js

@@ -119,7 +119,9 @@ function validate(name, cfg, taskDir) {
   const session = cfg.session || 'thread'
   if (!['thread', 'idle'].includes(session)) errs.push(`session 只能 thread|idle,给的是 ${session}`)
   const display = cfg.display || 'card'
-  if (!['card', 'final'].includes(display)) errs.push(`display 只能 card|final,给的是 ${display}`)
+  if (!['card', 'cot', 'final'].includes(display)) {
+    errs.push(`display 只能 card|cot|final,给的是 ${display}`)
+  }
 
   // instructions 相对任务目录解析 —— 执行偏好是资产,必须留仓库
   let insPath = null

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lark-relay",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Lark event relay: collect events to disk, take a batch when you need it, or dispatch work to an AI agent.",
   "keywords": [
     "lark",