lark-relay 0.2.2 → 0.3.0

package/README.md

@@ -73,30 +73,30 @@ 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 | cot | final(见下)
+# mode: work        默认;work | chat(见下)
 # model: <名称>      默认走终端同一套默认路由
 ```
 
-`display` 三档:
+`mode` 就两个场景 —— 一个键定死全部行为,不用拼组合:
 
-| 档 | 过程展示 | 结论 | 备注 |
-| --- | --- | --- | --- |
-| `card` | CardKit 流式打字机,单卡原地更新 | 写进同一张卡片 | 收尾 PUT 失败自动回退纯文本 |
-| `cot` | 思考过程挂在 COT 消息上(AG-UI 事件流) | **总是单独发一条** | 客户端 PC ≥ 7.70 / 移动 ≥ 7.74 |
-| `final` | 无 | 单独发一条 | 最省事,不流式 |
+| | `work`(默认) | `chat` |
+|---|---|---|
+| 用途 | 处理工作 | 日常闲聊 |
+| 回复位置 | 话题内(首问开话题) | 直接发群里 |
+| 过程展示 | COT 消息(实时流式) | 无 |
+| 结论 | 卡片(markdown 渲染) | 纯文本 |
+| session 隔离 | 按 `thread_id`(话题即边界,不滚动) | 按 (群, epoch),空闲超 `idle_gap` 开新世代 |
+| 防抖 | 1s(一问一答要跟手) | 15s(等人打完多行) |
 
-`cot` 档的「结论单独发」不是降级路径,而是 COT 接口的设计前提 —— COT 消息只承载
-过程。它也**不写工具结果**:工具输出动辄几千字符且可能含不宜进群的仓库内容,
-与 `card` 档只显示工具名+参数摘要一致。
+`work` 的过程与结论是**两条消息** —— COT 消息只承载过程(接口的设计前提),
+结论另发一条卡片。卡片发送失败会自动降级纯文本,保证结论必达。
 
-⚠️ **老客户端(< 7.70)看不到过程**:COT 消息底层是 `msg_type: post`,不支持的客户端
-只会看到一条内容为「Completed」的消息(实测,不会崩)。群里有老客户端用户时选 `card`。
-结论那条普通文本不受影响 —— 这也是「结论单独发」的价值。
+⚠️ **COT 要求客户端 PC ≥ 7.70 / 移动 ≥ 7.74**:老客户端上那条过程消息显示为
+「Completed」(不会崩),结论卡片不受影响 —— 这也是「结论单独发」的价值。
 
-环境变量:`LR_COT_BATCH_MS`(攒批窗口,默认 1000)、
-`LR_COT_SAY_AS=text|reasoning`(中间文本走正式文本流还是思考流,默认 `text`)。
-实测两者渲染一致,`text` 每段少 2 个事件(reasoning 多一对 START/END 包裹)。
+环境变量:`LR_COT_BATCH_MS`(COT 攒批窗口,默认 1000)、
+`LR_COT_SAY_AS=text|reasoning`(中间文本走正式文本流还是思考流,默认 `text`;
+实测两者渲染一致,`text` 每段少 2 个事件)。
 
 ## 存储布局
 

package/lib/card.js

@@ -1,22 +1,16 @@
 'use strict'
 
-// card display:CardKit 流式打字机,单卡原地更新。
-// 五步流:建卡实体 → 发引用消息 → 流式 PUT body → 收尾全卡重构 → 关流式定格。
+// 结论卡片:一条非流式 interactive 消息。
+// work 模式用它发最终结论 —— 过程由 COT 消息承担(lib/cot.js),这里只放结论。
 //
-// ⚠️ 两处双层编码(踩过):
-//   建卡的 data 与关流式的 settings 都是**字符串化的 JSON**,不是对象
-// ⚠️ print_frequency_ms / print_step 必须是按端对象 {default,android,ios,pc},
-//   传标量会 10002 unmarshal 报错
+// 比纯文本好在:markdown 正常渲染、不受 reply 的 3500 字符分片限制。
+// **不需要 card 实体**:直接 msg_type=interactive 一步发出(实测),
+// cardkit 那套「建实体 → 拿 card_id → 流式 PUT → 关流式」只有流式打字机才需要
 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)
-const PRINT_STEP = Number(process.env.LR_CARD_PRINT_STEP || 20)
-const PLACEHOLDER = process.env.LR_CARD_PLACEHOLDER || '🤔 正在思考…'
+const { errText, tail } = larkcli
 
 // 飞书卡片按标题字号渲染 #,窄卡片里过大突兀 → ATX 标题降级为加粗。
-// 必须状态机跳过 ``` 代码块:块内的 `# 注释`(shell/python)绝不能被误降级。
+// 必须状态机跳过 ``` 代码块:块内的 `# 注释`(shell/python)绝不能被误降级
 function mdfix(text) {
   const out = []
   let inCode = false
@@ -38,196 +32,45 @@ function mdfix(text) {
   return out.join('\n')
 }
 
-function initCard() {
-  const perDevice = (v) => ({ default: v, android: v, ios: v, pc: v })
+function buildCard(text) {
   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 }],
-    },
+    config: {},
+    body: { elements: [{ tag: 'markdown', content: mdfix(text) }] },
   }
 }
 
-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
-    // 串行队列:所有卡片写操作排队执行。
-    // ⚠️ 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()) })
-    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' }),
+/**
+ * 发一张结论卡片。失败返回 false —— 调用方必须降级发纯文本,保证结论必达。
+ * @param {object} opts {profile, chatId, replyTo, inThread}
+ */
+async function sendCard(text, { profile, chatId, replyTo, inThread } = {}) {
+  const content = JSON.stringify(buildCard(text))
+  const args = replyTo && replyTo !== '-'
+    ? [
+        '--profile', profile, 'api', 'POST',
+        `/open-apis/im/v1/messages/${replyTo}/reply`,
+        '--as', 'bot',
         '--data', JSON.stringify({
-          receive_id: this.chatId, msg_type: 'interactive', content,
+          msg_type: 'interactive',
+          content,
+          ...(inThread ? { reply_in_thread: true } : {}),
         }),
+      ]
+    : [
+        '--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',
-      ])
-    }
-    const j = JSON.parse(stripToJson(out.stdout))
-    this.messageId = j?.data?.message_id || null
-    return this.messageId
-  }
-
-  // 步骤 ③:流式期单 body 元素全量替换(打字机)。
-  // 全量替换故本地要维护累积串;单次失败可容忍(下次 PUT 是全量,自愈)。
-  // 走串行队列:调用方 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。
-  // 排在队尾执行 —— 必须等所有 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(),
-      })
-      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
-      }
-    })
-  }
-
-  // 步骤 ⑤:关流式定格。settings 的值是**字符串化的 JSON**(双层转义)
-  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 就是最终结论
-  // (会作为 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
-    }
+      ]
+  try {
+    const { stdout } = await larkcli.run(args)
+    if (/"ok":\s*true/.test(stdout)) return true
+    process.stderr.write(`card: 未 ok chat=${chatId} → ${tail(stdout)}\n`)
+  } catch (err) {
+    process.stderr.write(`card: 发送失败 chat=${chatId} → ${tail(errText(err))}\n`)
   }
+  return false
 }
 
-module.exports = { CardSession, mdfix }
+module.exports = { sendCard, mdfix, buildCard }

package/lib/cot.js

@@ -2,7 +2,6 @@
 
 // cot display:消息上挂载「思考过程」,事件流对齐 AG-UI 协议。
 // 三步流:POST 建 COT 消息 → PUT 攒批写事件(可反复)→ RUN_FINISHED 自动完结。
-// 接口与 CardSession 同构,让 dispatch 里两档只差一个 new。
 // 接口细节与实测边界见 docs/cot-message-api.md
 //
 // **COT 只承载过程,结论必须单独发一条普通消息** —— 接口的设计前提,不是我们的选择。
@@ -100,16 +99,12 @@ class CotSession {
     this.cotId = null
     this.messageId = null
     this.done = false // 已写 RUN_FINISHED/RUN_ERROR;之后写入必被拒
-    this.acc = '' // **只写不读**,纯为与 CardSession 接口同构;无消费者,别维护它的格式
-    // 只用来生成本地唯一 id,**从不发给服务端**。
-    // ⚠️ 与 CardSession.seq 同名但无关:那个是服务端排序号,小了会被拒
-    this.seq = 0
+    this.seq = 0 // 只用来生成本地唯一的 messageId/toolCallId,**从不发给服务端**
     this.pending = [] // 待发事件队列
     this.lastStamp = 0 // 事件 timestamp 的单调下界(见 _stamp)
     this.pendingSay = null // 延迟一段的 say(见 onSay);结论不能进过程区
     this.timer = null
-    // 串行队列:PUT 必须按写入顺序到达,晚发先到会让 delta 乱序拼接。
-    // 与 CardSession 的 q 同一理由(那边是 sequence 被服务端拒,这边是文本错位)。
+    // 串行队列:PUT 必须按写入顺序到达,晚发先到会让 delta 乱序拼接成错乱文本
     this.q = Promise.resolve()
   }
 
@@ -139,11 +134,6 @@ class CotSession {
     return this.cotId
   }
 
-  // 与 CardSession 接口对齐:COT 一步建好,没有「另发一条消息引用它」的步骤
-  async post() {
-    return this.messageId
-  }
-
   // 编码单条事件:content 序列化 + 超 4096 字节时截断自由文本字段。
   // 返回事件对象,null = 截不下来只能丢弃(整批被服务端拒比丢一条更糟)
   _encode(eventType, content) {
@@ -266,11 +256,10 @@ class CotSession {
   // 中间文本。每段一个独立 messageId —— 同 id 的多条 CONTENT 会被客户端拼成一段,
   // 而两次 say 之间通常隔着工具调用,拼起来读不通。
   //
-  // **延迟一段**(与 CardSession 同机制):最后一段 say 就是结论,它会作为独立消息
-  // 再发一次 —— 也写进过程区群里就看到两遍。故压着最新一段,onFinal 时丢弃。
-  // 用「延迟一段」而非内容比较 —— 最稳(card.js 踩出来的)
+  // **延迟一段**:最后一段 say 就是结论,它会作为独立消息再发一次 ——
+  // 也写进过程区群里就看到两遍。故压着最新一段,onFinal 时丢弃。
+  // 用「延迟一段」而非内容比较 —— 最稳
   onSay(text) {
-    this.acc += (this.acc ? '\n\n' : '') + text
     this._flushPending()
     this.pendingSay = text
   }
@@ -300,7 +289,6 @@ class CotSession {
   // 工具调用。**不写 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)
@@ -320,8 +308,8 @@ class CotSession {
     )
   }
 
-  // 与 CardSession 同签名同语义:手里那段 pending(= 结论)直接丢弃,不放行 ——
-  // 它会作为独立消息发出,写进过程区就成了群里的第二遍
+  // 手里那段 pending(= 结论)直接丢弃,不放行 —— 它会作为独立消息发出,
+  // 写进过程区就成了群里的第二遍
   onFinal() {
     this.pendingSay = null
   }
@@ -374,13 +362,8 @@ class CotSession {
     })
   }
 
-  // 与 CardSession 接口对齐:onEvent 里 fire-and-forget 调,cot 侧攒批已自带节流
-  update() {
-    return this._settled()
-  }
-
-  // 与 CardSession 接口对齐。finalize 已完结,这里只兜「从没 finalize 成功」的情况:
-  // 超时被 SIGTERM、异常中断 —— 不调 complete 的话 COT 会一直显示「在跑」
+  // 兜「从没 finalize 成功」的情况:超时被 SIGTERM、异常中断 ——
+  // 不调 complete 的话 COT 会一直显示「在跑」
   async stop() {
     if (this.done || !this.cotId) return
     // 从没 finalize 就走到这里 = 异常中断,压着的那段不是结论 → 放行

package/lib/dispatch.js

@@ -13,7 +13,7 @@ const { acquireBlocking } = require('./lock')
 const { paths, ensureDir } = require('./paths')
 const store = require('./store')
 const claude = require('./claude')
-const { CardSession } = require('./card')
+const { sendCard } = require('./card')
 const { CotSession } = require('./cot')
 const { reply } = require('./reply')
 
@@ -76,7 +76,7 @@ function ledgerAppend(task, chatId, epoch, trigger, result) {
 
 // 处理一个 (chat_id, thread_id) 组:派一轮活
 async function handleGroup(t, group, opts = {}) {
-  const { name: task, taskDir, insPath, dirs, session, display } = t
+  const { name: task, taskDir, insPath, dirs, mode } = t
   const cfg = t.config
   const profile = cfg.app
   const chatId = group.chatId
@@ -97,31 +97,26 @@ async function handleGroup(t, group, opts = {}) {
   }
 
   try {
-    // session 派生:thread 模式按 thread_id 隔离(话题即边界,不滚动,epoch 恒 0);
-    // 否则按 (群, epoch),空闲超 idle_gap 就开新世代
+    // session 派生:work 模式按 thread_id 隔离(话题即边界,不滚动,epoch 恒 0);
+    // chat 模式按 (群, epoch),空闲超 idle_gap 就开新世代
     let uuid
     let epoch = 0
-    if (session === 'thread' && threadId) {
+    if (mode.thread && threadId) {
       uuid = claude.deriveUuid(task, `${chatId}|thread:${threadId}`)
     } else {
       epoch = claude.sessionEpoch(paths.root, task, chatId, Number(cfg.idle_gap) || 86400)
       uuid = claude.deriveUuid(task, `${chatId}|${epoch}`)
     }
 
-    const replyInThread = session === 'thread'
-    // card 与 cot 同构(create/post/onSay/onTool/onFinal/update),只差一个构造器。
-    // 差别只在收尾:card 把结论写进卡片,cot 的结论**必须**单独发(接口设计前提)
-    const Session = display === 'card' ? CardSession : display === 'cot' ? CotSession : null
-    let view = null
-
-    if (Session) {
-      view = new Session({ profile, chatId, lastMsg, replyInThread })
+    // 过程展示:work 模式挂 COT 消息。建不起来就静默降级(结论照发)
+    let cot = null
+    if (mode.cot) {
+      cot = new CotSession({ profile, chatId, lastMsg, replyInThread: mode.thread })
       try {
-        if (!(await view.create())) throw new Error('建展示载体失败')
-        if (!(await view.post())) throw new Error('发展示消息失败')
+        if (!(await cot.create())) throw new Error('建 COT 消息失败')
       } catch (err) {
-        process.stderr.write(`${display}: ${err.message},回退 final\n`)
-        view = null
+        process.stderr.write(`cot: ${err.message},本轮无过程展示\n`)
+        cot = null
       }
     }
 
@@ -134,13 +129,12 @@ async function handleGroup(t, group, opts = {}) {
       allowedTools: cfg.allowed || 'Read Edit Write Bash',
       model: cfg.model,
       timeoutSec: Number(cfg.timeout) || 1800,
-      stream: !!view,
-      onEvent: view
+      stream: !!cot,
+      onEvent: cot
         ? (kind, text) => {
-            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)
+            if (kind === 'say') cot.onSay(text)
+            else if (kind === 'tool') cot.onTool(text)
+            else if (kind === 'final') cot.onFinal()
           }
         : null,
     })
@@ -155,34 +149,25 @@ async function handleGroup(t, group, opts = {}) {
               .slice(-300)}`
     }
 
-    if (view && display === 'card') {
-      // 全卡 PUT 失败必须降级发纯文本,保证结论必达。
-      // 抛出时也当失败处理 —— 不依赖「CardSession 内部不抛」这个远处的性质
-      let ok = false
+    // 收尾必须包 try/catch:handleGroup 外层只有 try/finally(无 catch),
+    // 收尾一抛就会跳过下面的结论投递 + ledgerAppend,而 take 游标已推
+    // → 结论既不进群也不进台账,这批消息永不重来
+    if (cot) {
       try {
-        ok = await view.finalize(final)
-        await view.stop()
+        await cot.finalize({ rc: res.rc, error: res.err })
+        await cot.stop()
       } catch (err) {
-        process.stderr.write(`card: 收尾异常 → ${err.stack || err}\n`)
+        process.stderr.write(`cot: 收尾异常(不影响结论)→ ${err.stack || err}\n`)
       }
-      if (!ok) await reply(profile, chatId, lastMsg, final, { inThread: replyInThread })
-    } 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 })
     }
 
+    // 结论**总是单独一条**:work 发卡片(markdown 渲染、不受 3500 字符分片限制),
+    // chat 发纯文本。卡片失败降级纯文本 —— 保证结论必达
+    const sent = mode.card
+      ? await sendCard(final, { profile, chatId, replyTo: lastMsg, inThread: mode.thread })
+      : false
+    if (!sent) await reply(profile, chatId, lastMsg, final, { inThread: mode.thread })
+
     ledgerAppend(task, chatId, epoch, batch, final)
     process.stderr.write(
       `dispatch: ${task}/${chatId}${threadId ? `/${threadId}` : ''} 完成 rc=${res.rc} ` +
@@ -210,12 +195,12 @@ async function run(task, opts = {}) {
 
   const cfg = t.config
   const chats = cfg.chats || []
-  // thread=话题回复,交互式一问一答要跟手 → 1s;否则群任务多行需求 → 15s 让人打完
-  const debounceMs = (Number(cfg.debounce) || (t.session === 'thread' ? 1 : 15)) * 1000
+  // work=话题内一问一答要跟手 → 1s;chat=群里多行需求 → 15s 让人打完
+  const debounceMs = (Number(cfg.debounce) || t.mode.debounce) * 1000
 
   process.stderr.write(
-    `dispatch ${task}: app=${cfg.app} ${chats.length} 群 session=${t.session} ` +
-      `display=${t.display} model=${cfg.model || '(默认路由)'} 防抖 ${debounceMs / 1000}s\n`,
+    `dispatch ${task}: app=${cfg.app} ${chats.length} 群 mode=${t.modeName} ` +
+      `model=${cfg.model || '(默认路由)'} 防抖 ${debounceMs / 1000}s\n`,
   )
 
   const consumer = `dispatch-${task}`

package/lib/help.js

@@ -83,22 +83,22 @@ const DISPATCH_HELP = `常驻:等消息 → 唤起 claude 干活 → 结果回
 任务发现:扫 $LR_ROOT/*/dispatch.yaml —— 有文件即是任务,无需注册表。
 LR_ROOT 在单元里指定（唯一的目录绑定,与代码无关）。
 
-dispatch.yaml（5 必填 + 3 可选）
+dispatch.yaml（4 必填 + 3 可选）
   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 | cot | final
+  # mode: work        默认;work | chat（见下）
   # model: <名称>      默认走终端同一套默认路由
 
-display 三档
-  card   CardKit 流式打字机,单卡原地更新,结论写进卡片(收尾失败回退纯文本)
-  cot    思考过程挂在 COT 消息上,**结论总是单独发一条**(接口设计前提,非降级)
-         客户端门槛 PC ≥ 7.70 / 移动 ≥ 7.74;老客户端只看到一条「Completed」
-         (不崩,但过程不可见 → 群里有老客户端就选 card);不写工具结果
-  final  只发最终结论,不展示过程
+mode 两个场景（一个键定死全部行为,不用拼组合）
+  work   处理工作:话题内回复 + 过程挂 COT 消息 + 结论发卡片
+         + 按 thread_id 隔离 session + 防抖 1s（一问一答要跟手）
+         COT 要求客户端 PC ≥ 7.70 / 移动 ≥ 7.74;老客户端那条过程消息显示为
+         「Completed」（不崩）,结论卡片不受影响
+  chat   日常闲聊:直发群里 + 纯文本 + 按（群, epoch）隔离 session
+         + 防抖 15s（等人打完多行）
 
 最佳实践
   · 边界写 instructions,别指望 --add-dir 目录的 CLAUDE.md（启动不加载）

package/lib/tasks.js

@@ -106,6 +106,16 @@ function scalar(s) {
 
 const REQUIRED = ['app', 'chats', 'dirs', 'instructions']
 
+// 两个场景,不是几个正交开关的组合 —— 一个 mode 键定死全部行为。
+// 此前是 session(thread|idle) × display(card|cot|final) 交叉出 6 种组合,
+// 而 session 一个键实际控制三件事(隔离方式、是否开话题、防抖默认值)。
+const MODES = {
+  // 日常闲聊:群里直接对话,不开话题
+  chat: { thread: false, cot: false, card: false, debounce: 15 },
+  // 处理工作:话题内一问一答,过程挂 COT,结论发卡片
+  work: { thread: true, cot: true, card: true, debounce: 1 },
+}
+
 function validate(name, cfg, taskDir) {
   const errs = []
   for (const k of REQUIRED) {
@@ -116,12 +126,9 @@ function validate(name, cfg, taskDir) {
   for (const c of cfg.chats || []) {
     if (typeof c !== 'string' || !c.startsWith('oc_')) errs.push(`chats 项不是 oc_ 开头:${c}`)
   }
-  const session = cfg.session || 'thread'
-  if (!['thread', 'idle'].includes(session)) errs.push(`session 只能 thread|idle,给的是 ${session}`)
-  const display = cfg.display || 'card'
-  if (!['card', 'cot', 'final'].includes(display)) {
-    errs.push(`display 只能 card|cot|final,给的是 ${display}`)
-  }
+  const modeName = cfg.mode || 'work'
+  if (!MODES[modeName]) errs.push(`mode 只能 ${Object.keys(MODES).join('|')},给的是 ${modeName}`)
+  const mode = MODES[modeName] || MODES.work
 
   // instructions 相对任务目录解析 —— 执行偏好是资产,必须留仓库
   let insPath = null
@@ -133,7 +140,7 @@ function validate(name, cfg, taskDir) {
   for (const d of dirs) {
     if (!fs.existsSync(d)) errs.push(`dirs 目录不存在:${d}`)
   }
-  return { errs, insPath, dirs, session, display }
+  return { errs, insPath, dirs, modeName, mode }
 }
 
 function loadTask(name, root = lrRoot()) {

package/package.json

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