bingocode 1.0.40 → 1.1.42

package/adapters/feishu/card-errors.ts

@@ -1,151 +0,0 @@
-/**
- * Feishu CardKit API 错误码解析与谓词
- *
- * 参考实现: openclaw-lark/src/card/card-error.ts + src/core/api-error.ts
- *
- * Lark SDK 抛出的错误对象结构有多种：
- *   - SDK 把 Feishu 的 {code, msg} 直接挂在 error 对象上
- *   - Axios 风格: error.response.data.{code, msg}
- *   - data.code 嵌套（某些包装层）
- *
- * 此模块把这些统一成 { code, subCode, errMsg } 结构，
- * 供 streaming-card-controller 判断是否跳帧重试、或降级到 Patch 路径。
- */
-
-// ---------------------------------------------------------------------------
-// Error code constants
-// ---------------------------------------------------------------------------
-
-/** 卡片 API 级别错误码。 */
-export const CARD_ERROR = {
-  /** 发送频率限制。需跳过当前帧，下次 flush 继续。 */
-  RATE_LIMITED: 230020,
-  /** 卡片内容创建失败（通用码，需看子错误确认具体原因）。 */
-  CARD_CONTENT_FAILED: 230099,
-} as const
-
-/**
- * 230099 的子错误码，嵌套在 msg 的 `ErrCode: xxx` 字段中。
- * 11310 是通用的"元素超限"码，需配合 errMsg 匹配具体原因。
- */
-export const CARD_CONTENT_SUB_ERROR = {
-  /** 卡片元素（表格等）数量超限 */
-  ELEMENT_LIMIT: 11310,
-} as const
-
-// ---------------------------------------------------------------------------
-// Code extraction
-// ---------------------------------------------------------------------------
-
-function coerceCode(value: unknown): number | undefined {
-  if (typeof value === 'number' && Number.isFinite(value)) return value
-  if (typeof value === 'string') {
-    const parsed = Number(value)
-    if (Number.isFinite(parsed)) return parsed
-  }
-  return undefined
-}
-
-/**
- * 从 Lark SDK 抛错对象中提取飞书 API code。支持三种结构：
- *   - `{ code }`                    (SDK 直接挂载)
- *   - `{ data: { code } }`          (响应体嵌套)
- *   - `{ response: { data: { code } } }` (Axios 风格)
- */
-export function extractLarkApiCode(err: unknown): number | undefined {
-  if (!err || typeof err !== 'object') return undefined
-  const e = err as {
-    code?: unknown
-    data?: { code?: unknown }
-    response?: { data?: { code?: unknown } }
-  }
-  return coerceCode(e.code) ?? coerceCode(e.data?.code) ?? coerceCode(e.response?.data?.code)
-}
-
-// ---------------------------------------------------------------------------
-// Sub-error extraction
-// ---------------------------------------------------------------------------
-
-/**
- * 从 msg 字符串里提取子错误码（`ErrCode: xxx`）。
- *
- * 示例输入:
- *   "Failed to create card content, ext=ErrCode: 11310; ErrMsg: card table number over limit; ..."
- * 返回: 11310
- */
-export function extractSubCode(msg: string): number | null {
-  const match = /ErrCode:\s*(\d+)/.exec(msg)
-  if (!match) return null
-  const code = Number(match[1])
-  return Number.isFinite(code) ? code : null
-}
-
-// ---------------------------------------------------------------------------
-// Structured error parsing
-// ---------------------------------------------------------------------------
-
-export type CardApiErrorInfo = {
-  code: number
-  subCode: number | null
-  errMsg: string
-}
-
-/**
- * 从任意抛错对象中解析卡片 API 错误结构。
- *
- * 返回 { code, subCode, errMsg }。无法提取 code 时返回 null。
- */
-export function parseCardApiError(err: unknown): CardApiErrorInfo | null {
-  const code = extractLarkApiCode(err)
-  if (code === undefined) return null
-
-  // 按优先级提取 msg 文本
-  let errMsg = ''
-  if (err && typeof err === 'object') {
-    const e = err as {
-      msg?: unknown
-      message?: unknown
-      response?: { data?: { msg?: unknown } }
-    }
-    if (typeof e.msg === 'string') {
-      errMsg = e.msg
-    } else if (typeof e.response?.data?.msg === 'string') {
-      errMsg = e.response.data.msg
-    } else if (typeof e.message === 'string') {
-      errMsg = e.message
-    }
-  }
-
-  const subCode = extractSubCode(errMsg)
-  return { code, subCode, errMsg }
-}
-
-// ---------------------------------------------------------------------------
-// Helper predicates
-// ---------------------------------------------------------------------------
-
-/** 判断错误是否为卡片发送频率限制（230020）。 */
-export function isCardRateLimitError(err: unknown): boolean {
-  const parsed = parseCardApiError(err)
-  if (!parsed) return false
-  return parsed.code === CARD_ERROR.RATE_LIMITED
-}
-
-/**
- * 判断错误是否为卡片表格数超限。
- *
- * 匹配条件: code 230099 + subCode 11310 + errMsg 含 "table number over limit"
- * （11310 是通用元素超限码，光靠它不够；必须同时检查 errMsg 锁定是表格数量问题）。
- *
- * 实际生产错误格式（openclaw-lark 2026-03 实测）:
- *   "Failed to create card content, ext=ErrCode: 11310; ErrMsg: card table number over limit; ErrorValue: table; "
- */
-export function isCardTableLimitError(err: unknown): boolean {
-  const parsed = parseCardApiError(err)
-  if (!parsed) return false
-  return (
-    parsed.code === CARD_ERROR.CARD_CONTENT_FAILED &&
-    parsed.subCode === CARD_CONTENT_SUB_ERROR.ELEMENT_LIMIT &&
-    /table number over limit/i.test(parsed.errMsg)
-  )
-}

package/adapters/feishu/cardkit.ts

@@ -1,294 +0,0 @@
-/**
- * 飞书 CardKit API 薄封装
- *
- * 这是生产路径的核心：openclaw-lark 的 CardKit 主路径等价实现。
- *
- * 五步流程：
- *   1. createCardEntity()    —— 创建卡片实体，返回 card_id
- *   2. sendCardAsMessage()   —— 通过 IM 消息把卡片挂到聊天窗，返回 message_id
- *   3. streamCardContent()   —— 循环调用，按 element_id 增量追加文本
- *   4. setCardStreamingMode() —— 关闭流式模式（收尾前必须做）
- *   5. updateCardKitCard()   —— 全量替换卡片为最终态
- *
- * 关键约束：
- * - 每次 3/4/5 类调用必须携带**单调递增**的 sequence，否则飞书拒绝
- * - streamCardContent 传的是**完整累计文本**，不是 delta
- * - 必须关闭 streaming_mode 后卡片才能被用户交互
- *
- * 参考实现: openclaw-lark/src/card/cardkit.ts
- */
-
-import type * as Lark from '@larksuiteoapi/node-sdk'
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-/** 流式 markdown 元素的固定 element_id。卡片 JSON 里用这个 id 标记要被
- *  `cardElement.content()` 更新的那一个 markdown 元素。 */
-export const STREAMING_ELEMENT_ID = 'streaming_content'
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-/**
- * SDK 返回的通用响应结构。
- * SDK 的 TypeScript 类型不完整，运行时实际返回 { code, msg, data }。
- * 我们统一当成 CardKitResponse 处理以免到处 `as any`。
- */
-type CardKitResponse = {
-  code?: number
-  msg?: string
-  data?: Record<string, unknown>
-  [key: string]: unknown
-}
-
-/** 非零 code 时抛出的结构化错误。字段与 Lark SDK 的标准错误对齐，
- *  可被 card-errors.ts 的 parseCardApiError 识别。 */
-export class CardKitApiError extends Error {
-  readonly code: number
-  readonly msg: string
-
-  constructor(params: { api: string; code: number; msg: string; context: string }) {
-    const { api, code, msg, context } = params
-    super(`cardkit ${api} FAILED: code=${code}, msg=${msg}, ${context}`)
-    this.name = 'CardKitApiError'
-    this.code = code
-    this.msg = msg
-  }
-}
-
-type LarkClient = Lark.Client
-
-// ---------------------------------------------------------------------------
-// Response check
-// ---------------------------------------------------------------------------
-
-/**
- * 检查 CardKit 响应的 body-level code。非 0 → 抛 CardKitApiError。
- *
- * Fail-fast 策略: 让 streaming-card 用 try/catch 配合 card-errors 统一
- * 判断是速率限制还是真错误。
- */
-function assertCardKitOk(params: {
-  resp: CardKitResponse
-  api: string
-  context: string
-}): void {
-  const { resp, api, context } = params
-  const code = resp.code
-  if (code !== undefined && code !== 0) {
-    throw new CardKitApiError({
-      api,
-      code,
-      msg: typeof resp.msg === 'string' ? resp.msg : '',
-      context,
-    })
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Step 1 — createCardEntity
-// ---------------------------------------------------------------------------
-
-/**
- * 创建一张 CardKit 卡片实体，返回 card_id。
- *
- * 此时卡片还没挂到任何聊天窗。需要再调 sendCardAsMessage 才能显示。
- *
- * @param client  Lark SDK client
- * @param card    Schema 2.0 格式的卡片 JSON
- * @returns       飞书分配的 card_id（失败时抛错）
- */
-export async function createCardEntity(
-  client: LarkClient,
-  card: Record<string, unknown>,
-): Promise<string> {
-  // SDK 返回类型不完整，cast 到运行时实际结构
-  const resp = (await client.cardkit.v1.card.create({
-    data: {
-      type: 'card_json',
-      data: JSON.stringify(card),
-    },
-  })) as unknown as CardKitResponse
-
-  assertCardKitOk({
-    resp,
-    api: 'card.create',
-    context: `cardLen=${JSON.stringify(card).length}`,
-  })
-
-  // 兼容不同 SDK 包装层：data.card_id 优先，回退顶层 card_id
-  const cardId =
-    (resp.data?.card_id as string | undefined) ??
-    (resp.card_id as string | undefined)
-
-  if (!cardId) {
-    throw new CardKitApiError({
-      api: 'card.create',
-      code: resp.code ?? -1,
-      msg: 'response missing card_id',
-      context: `resp=${JSON.stringify(resp).slice(0, 200)}`,
-    })
-  }
-  return cardId
-}
-
-// ---------------------------------------------------------------------------
-// Step 2 — sendCardAsMessage
-// ---------------------------------------------------------------------------
-
-/**
- * 把 CardKit 卡片通过 IM 消息挂到聊天窗。
- *
- * content 格式: `{"type":"card","data":{"card_id":"xxx"}}`
- * msg_type 固定为 `interactive`。
- *
- * @param client            Lark SDK client
- * @param chatId            目标 chat_id
- * @param cardId            CardKit card_id（由 createCardEntity 产生）
- * @param replyToMessageId  可选。如果提供，走 im.message.reply；否则 im.message.create
- * @returns                 飞书分配的 message_id
- */
-export async function sendCardAsMessage(
-  client: LarkClient,
-  chatId: string,
-  cardId: string,
-  replyToMessageId?: string,
-): Promise<string> {
-  const content = JSON.stringify({
-    type: 'card',
-    data: { card_id: cardId },
-  })
-
-  if (replyToMessageId) {
-    const resp = await client.im.message.reply({
-      path: { message_id: replyToMessageId },
-      data: { content, msg_type: 'interactive' },
-    })
-    const messageId = resp.data?.message_id
-    if (!messageId) {
-      throw new CardKitApiError({
-        api: 'im.message.reply',
-        code: -1,
-        msg: 'response missing message_id',
-        context: `cardId=${cardId}`,
-      })
-    }
-    return messageId
-  }
-
-  const resp = await client.im.message.create({
-    params: { receive_id_type: 'chat_id' },
-    data: {
-      receive_id: chatId,
-      msg_type: 'interactive',
-      content,
-    },
-  })
-  const messageId = resp.data?.message_id
-  if (!messageId) {
-    throw new CardKitApiError({
-      api: 'im.message.create',
-      code: -1,
-      msg: 'response missing message_id',
-      context: `chatId=${chatId} cardId=${cardId}`,
-    })
-  }
-  return messageId
-}
-
-// ---------------------------------------------------------------------------
-// Step 3 — streamCardContent
-// ---------------------------------------------------------------------------
-
-/**
- * 流式更新指定 element 的内容。飞书自动对比旧内容做 diff，在客户端
- * 渲染打字机效果。
- *
- * **重要**: `content` 必须传**完整累计文本**，不是 delta。
- * sequence 必须**单调递增**，否则飞书拒绝。
- *
- * @param client     Lark SDK client
- * @param cardId     CardKit card_id
- * @param elementId  要更新的元素 id（通常是 STREAMING_ELEMENT_ID）
- * @param content    完整累计文本
- * @param sequence   单调递增序列号
- */
-export async function streamCardContent(
-  client: LarkClient,
-  cardId: string,
-  elementId: string,
-  content: string,
-  sequence: number,
-): Promise<void> {
-  const resp = (await client.cardkit.v1.cardElement.content({
-    data: { content, sequence },
-    path: { card_id: cardId, element_id: elementId },
-  })) as unknown as CardKitResponse
-
-  assertCardKitOk({
-    resp,
-    api: 'cardElement.content',
-    context: `seq=${sequence} len=${content.length}`,
-  })
-}
-
-// ---------------------------------------------------------------------------
-// Step 4 — setCardStreamingMode
-// ---------------------------------------------------------------------------
-
-/**
- * 开/关卡片的流式模式。收尾前必须调用 `streamingMode: false`，
- * 否则卡片会保持"只读"状态，用户点按钮没反应。
- */
-export async function setCardStreamingMode(
-  client: LarkClient,
-  cardId: string,
-  streamingMode: boolean,
-  sequence: number,
-): Promise<void> {
-  const resp = (await client.cardkit.v1.card.settings({
-    data: {
-      settings: JSON.stringify({ streaming_mode: streamingMode }),
-      sequence,
-    },
-    path: { card_id: cardId },
-  })) as unknown as CardKitResponse
-
-  assertCardKitOk({
-    resp,
-    api: 'card.settings',
-    context: `seq=${sequence} streaming_mode=${streamingMode}`,
-  })
-}
-
-// ---------------------------------------------------------------------------
-// Step 5 — updateCardKitCard
-// ---------------------------------------------------------------------------
-
-/**
- * 全量替换卡片为新的 JSON。用于流式结束后把卡片切换成最终态
- * （加 header template、footer、完成样式等）。
- */
-export async function updateCardKitCard(
-  client: LarkClient,
-  cardId: string,
-  card: Record<string, unknown>,
-  sequence: number,
-): Promise<void> {
-  const resp = (await client.cardkit.v1.card.update({
-    data: {
-      card: { type: 'card_json', data: JSON.stringify(card) },
-      sequence,
-    },
-    path: { card_id: cardId },
-  })) as unknown as CardKitResponse
-
-  assertCardKitOk({
-    resp,
-    api: 'card.update',
-    context: `seq=${sequence} cardId=${cardId}`,
-  })
-}

package/adapters/feishu/extract-payload.ts

@@ -1,95 +0,0 @@
-/**
- * Feishu inbound message parser.
- *
- * Converts a raw Feishu `im.message.receive_v1` event payload (the JSON
- * string inside `message.content` plus its `message_type`) into a
- * structured `InboundPayload` containing:
- *   - plain text (for direct forwarding to Claude)
- *   - a list of `PendingDownload` refs describing any attachments we
- *     need to fetch via FeishuMediaService.downloadResource()
- *
- * Supports the five message_type values we care about:
- *   - text         → text only
- *   - post         → rich text (text nodes + img + file elements)
- *   - image        → single image_key
- *   - file         → single file_key
- *   - file_archive → single file_key (same shape as file)
- *
- * Any other shape returns an empty payload (text: '', downloads: []).
- */
-
-export type PendingDownload =
-  | { kind: 'image'; fileKey: string; fileName?: string }
-  | { kind: 'file'; fileKey: string; fileName?: string }
-
-export interface InboundPayload {
-  text: string
-  pendingDownloads: PendingDownload[]
-}
-
-export function extractInboundPayload(content: string, msgType: string): InboundPayload {
-  let parsed: any
-  try {
-    parsed = JSON.parse(content)
-  } catch {
-    return { text: '', pendingDownloads: [] }
-  }
-
-  if (msgType === 'text') {
-    return {
-      text: typeof parsed.text === 'string' ? parsed.text : '',
-      pendingDownloads: [],
-    }
-  }
-
-  if (msgType === 'image') {
-    if (typeof parsed.image_key === 'string' && parsed.image_key) {
-      return {
-        text: '',
-        pendingDownloads: [{ kind: 'image', fileKey: parsed.image_key }],
-      }
-    }
-    return { text: '', pendingDownloads: [] }
-  }
-
-  if (msgType === 'file' || msgType === 'file_archive') {
-    if (typeof parsed.file_key === 'string' && parsed.file_key) {
-      return {
-        text: '',
-        pendingDownloads: [
-          {
-            kind: 'file',
-            fileKey: parsed.file_key,
-            fileName: typeof parsed.file_name === 'string' ? parsed.file_name : undefined,
-          },
-        ],
-      }
-    }
-    return { text: '', pendingDownloads: [] }
-  }
-
-  if (msgType === 'post') {
-    const nodes = (parsed.zh_cn?.content ?? parsed.en_us?.content ?? []) as any[]
-    const flat = nodes.flat()
-    const textParts: string[] = []
-    const downloads: PendingDownload[] = []
-    for (const node of flat) {
-      if (!node || typeof node !== 'object') continue
-      if (node.tag === 'text' || node.tag === 'md') {
-        const t = node.text ?? node.content ?? ''
-        if (typeof t === 'string') textParts.push(t)
-      } else if (node.tag === 'img' && typeof node.image_key === 'string') {
-        downloads.push({ kind: 'image', fileKey: node.image_key })
-      } else if (node.tag === 'file' && typeof node.file_key === 'string') {
-        downloads.push({
-          kind: 'file',
-          fileKey: node.file_key,
-          fileName: typeof node.file_name === 'string' ? node.file_name : undefined,
-        })
-      }
-    }
-    return { text: textParts.join(''), pendingDownloads: downloads }
-  }
-
-  return { text: '', pendingDownloads: [] }
-}

package/adapters/feishu/flush-controller.ts

@@ -1,149 +0,0 @@
-/**
- * 节流 + mutex + 冲突重刷的通用 flush 调度器
- *
- * 这是个纯调度原语 —— 不含任何业务逻辑（发送卡片、构造 markdown 等）。
- * 实际 flush 工作由构造函数注入的 doFlush 回调负责。
- *
- * 语义:
- *   - throttledUpdate(throttleMs) 被流式数据触发，按窗口节流
- *   - flush() 被 mutex 保护，相同时刻只有一个在跑
- *   - flush 进行中的新数据标记 needsReflush，API 结束后立即补刷
- *   - 长间隔（> 2000ms）后的第一次 flush 延迟 300ms 批量，避免抖动
- *   - complete() 后拒绝所有新 flush
- *
- * 参考实现: openclaw-lark/src/card/flush-controller.ts
- */
-
-// ---------------------------------------------------------------------------
-// Throttle constants
-// ---------------------------------------------------------------------------
-
-export const THROTTLE = {
-  /** CardKit cardElement.content() 最小间隔 —— 官方为流式设计，可高频 */
-  CARDKIT_MS: 100,
-  /** im.message.patch 最小间隔 —— 严格速率限制（230020） */
-  PATCH_MS: 1500,
-  /** 长间隔判定阈值。elapsed > 2000ms 触发批量模式 */
-  LONG_GAP_THRESHOLD_MS: 2000,
-  /** 长间隔后第一帧的额外延迟，让文本积累更完整 */
-  BATCH_AFTER_GAP_MS: 300,
-} as const
-
-// ---------------------------------------------------------------------------
-// FlushController
-// ---------------------------------------------------------------------------
-
-export class FlushController {
-  private flushInProgress = false
-  private flushResolvers: Array<() => void> = []
-  private needsReflush = false
-  private pendingFlushTimer: ReturnType<typeof setTimeout> | null = null
-  private lastUpdateTime = 0
-  private isCompleted = false
-  private _cardMessageReady = false
-
-  constructor(private readonly doFlush: () => Promise<void>) {}
-
-  /** 标记完成 —— 当前 flush 跑完后不再接受新的。 */
-  complete(): void {
-    this.isCompleted = true
-  }
-
-  /** 取消任何挂起的延迟 flush 计时器。 */
-  cancelPendingFlush(): void {
-    if (this.pendingFlushTimer) {
-      clearTimeout(this.pendingFlushTimer)
-      this.pendingFlushTimer = null
-    }
-  }
-
-  /** 等待当前正在跑的 flush 结束。没在跑则立即返回。 */
-  waitForFlush(): Promise<void> {
-    if (!this.flushInProgress) return Promise.resolve()
-    return new Promise<void>((resolve) => this.flushResolvers.push(resolve))
-  }
-
-  /**
-   * 标记卡片消息是否已发送成功，决定 flush 是否被放行。
-   *
-   * 首次变 true 时同步更新 lastUpdateTime，让第一次 throttledUpdate
-   * 看到一个小的 elapsed，匹配 openclaw 的 "card 创建完立即可刷" 行为。
-   */
-  setCardMessageReady(ready: boolean): void {
-    this._cardMessageReady = ready
-    if (ready) this.lastUpdateTime = Date.now()
-  }
-
-  cardMessageReady(): boolean {
-    return this._cardMessageReady
-  }
-
-  /**
-   * 执行一次 flush（mutex 保护 + 冲突重刷）。
-   *
-   * 如果已有 flush 在跑，设置 needsReflush，当前 flush 结束后自动补一次。
-   */
-  async flush(): Promise<void> {
-    if (!this.cardMessageReady() || this.flushInProgress || this.isCompleted) {
-      if (this.flushInProgress && !this.isCompleted) this.needsReflush = true
-      return
-    }
-    this.flushInProgress = true
-    this.needsReflush = false
-    // 在 API 调用 **之前** 更新时间戳，防止并发调用者也进入 flush
-    this.lastUpdateTime = Date.now()
-    try {
-      await this.doFlush()
-      this.lastUpdateTime = Date.now()
-    } finally {
-      this.flushInProgress = false
-      const resolvers = this.flushResolvers
-      this.flushResolvers = []
-      for (const resolve of resolvers) resolve()
-
-      // 如果 API 调用期间有新事件进来，立即补一次 flush
-      if (this.needsReflush && !this.isCompleted && !this.pendingFlushTimer) {
-        this.needsReflush = false
-        this.pendingFlushTimer = setTimeout(() => {
-          this.pendingFlushTimer = null
-          void this.flush()
-        }, 0)
-      }
-    }
-  }
-
-  /**
-   * 节流更新入口。
-   *
-   * @param throttleMs - 最小 flush 间隔。CardKit 传 THROTTLE.CARDKIT_MS，
-   *   Patch 降级路径传 THROTTLE.PATCH_MS。
-   */
-  async throttledUpdate(throttleMs: number): Promise<void> {
-    if (!this.cardMessageReady()) return
-
-    const now = Date.now()
-    const elapsed = now - this.lastUpdateTime
-
-    if (elapsed >= throttleMs) {
-      this.cancelPendingFlush()
-      if (elapsed > THROTTLE.LONG_GAP_THRESHOLD_MS) {
-        // 长间隔批量模式：工具调用 / 推理回来后的第一帧延迟 300ms
-        // 让文本积累更完整，避免只显示一两个字
-        this.lastUpdateTime = now
-        this.pendingFlushTimer = setTimeout(() => {
-          this.pendingFlushTimer = null
-          void this.flush()
-        }, THROTTLE.BATCH_AFTER_GAP_MS)
-      } else {
-        await this.flush()
-      }
-    } else if (!this.pendingFlushTimer) {
-      // 在节流窗口内 —— 延迟到窗口结束再刷
-      const delay = throttleMs - elapsed
-      this.pendingFlushTimer = setTimeout(() => {
-        this.pendingFlushTimer = null
-        void this.flush()
-      }, delay)
-    }
-  }
-}