@mhfire/dsh-im-bridge 0.1.7 → 0.3.0

package/src/reply-images.ts

@@ -0,0 +1,228 @@
+/**
+ * Collect workspace PNG paths from assistant Markdown and send them as
+ * WeCom image messages after the text stream finishes.
+ */
+
+import { readFileSync, realpathSync, statSync } from 'node:fs'
+import { basename, isAbsolute, relative, resolve, sep } from 'node:path'
+
+/** WeCom image-type upload cap (bytes before encoding). */
+export const MAX_PNG_BYTES = 10 * 1024 * 1024
+/** WeCom mixed-image list cap; also keeps send-rate headroom after stream ticks. */
+export const MAX_PNG_COUNT = 10
+/** PNG signature (first 8 bytes). */
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+
+/** One local PNG ready to upload. */
+export interface CollectedPng {
+  /** Realpath inside the workspace. */
+  absPath: string
+  /** Basename passed to `uploadMedia` (`*.png`). */
+  filename: string
+  /** File bytes. */
+  buffer: Buffer
+}
+
+/** Result of scanning a reply for sendable PNGs. */
+export interface CollectPngResult {
+  /** Deduped PNGs in first-seen order, capped at {@link MAX_PNG_COUNT}. */
+  images: CollectedPng[]
+  /** Human-readable skip reasons (path + why). */
+  skipped: string[]
+}
+
+/** Optional caps for tests; production uses the WeCom defaults. */
+export interface CollectPngOptions {
+  /** Override {@link MAX_PNG_BYTES}. */
+  maxBytes?: number
+  /** Override {@link MAX_PNG_COUNT}. */
+  maxCount?: number
+}
+
+/** WeCom client methods used after `sendFinal`. */
+export interface MediaSender {
+  uploadMedia(
+    fileBuffer: Buffer,
+    options: { type: string; filename: string },
+  ): Promise<{ media_id?: string; mediaId?: string }>
+  sendMediaMessage(chatid: string, mediaType: string, mediaId: string): Promise<unknown>
+}
+
+/** `![alt](url)` or `[text](url)`, capturing the destination. */
+const MARKDOWN_LINK = /!?\[(?:[^\]]*?)\]\(\s*(<[^>]+>|[^\s)]+)(?:\s+(?:"[^"]*"|'[^']*'))?\s*\)/g
+
+/**
+ * Pull destination URLs from Markdown images and links, in order.
+ * @param text - assistant reply body.
+ * @returns raw destinations (angle brackets already stripped).
+ */
+export function extractMarkdownUrls(text: string): string[] {
+  const urls: string[] = []
+  for (const match of text.matchAll(MARKDOWN_LINK)) {
+    const raw = match[1]
+    if (raw === undefined) continue
+    const dest = raw.startsWith('<') && raw.endsWith('>') ? raw.slice(1, -1) : raw
+    if (dest !== '') urls.push(dest)
+  }
+  return urls
+}
+
+/**
+ * Chat id for `sendMediaMessage`: group `chatid`, otherwise the sender userid.
+ * @param frame - inbound WeCom frame.
+ * @param sender - userid used for 1:1 chats.
+ */
+export function resolveChatId(
+  frame: { body?: { chatid?: string; chattype?: string | number } },
+  sender: string,
+): string {
+  const chattype = frame.body?.chattype
+  const chatid = frame.body?.chatid
+  const grouped = chattype === 'group' || chattype === 2 || chattype === '2'
+  if (grouped && chatid) return chatid
+  const single = chattype === 'single' || chattype === 1 || chattype === '1'
+  if (!single && chatid) return chatid
+  return sender
+}
+
+function stripQueryHash(url: string): string {
+  const noHash = url.split('#')[0] ?? url
+  return noHash.split('?')[0] ?? noHash
+}
+
+function isRemote(url: string): boolean {
+  return /^(?:https?:|data:|mailto:|file:)/i.test(url)
+}
+
+function isPngPath(url: string): boolean {
+  return /\.png$/i.test(url)
+}
+
+function containedIn(root: string, target: string): boolean {
+  const rel = relative(root, target)
+  if (rel === '') return false
+  if (isAbsolute(rel)) return false
+  if (rel === '..' || rel.startsWith(`..${sep}`)) return false
+  return true
+}
+
+function tryRealpath(path: string): string | undefined {
+  try {
+    return realpathSync(path)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Resolve Markdown destinations to workspace PNG files.
+ * @param text - untruncated assistant reply.
+ * @param workspace - Agent cwd / plugin `workspace`.
+ * @param options - optional size/count caps.
+ */
+export function collectReplyPngs(
+  text: string,
+  workspace: string,
+  options?: CollectPngOptions,
+): CollectPngResult {
+  const maxBytes = options?.maxBytes ?? MAX_PNG_BYTES
+  const maxCount = options?.maxCount ?? MAX_PNG_COUNT
+  const images: CollectedPng[] = []
+  const skipped: string[] = []
+  const seen = new Set<string>()
+  const root = tryRealpath(workspace)
+  if (root === undefined) {
+    skipped.push(`工作区不可读: ${workspace}`)
+    return { images, skipped }
+  }
+
+  for (const raw of extractMarkdownUrls(text)) {
+    const url = stripQueryHash(raw.trim())
+    if (url === '' || isRemote(url)) continue
+    if (!isPngPath(url)) continue
+    if (images.length >= maxCount) {
+      skipped.push(`超过 ${maxCount} 张上限，忽略后续图片`)
+      break
+    }
+    const abs = resolve(root, url)
+    const real = tryRealpath(abs)
+    if (real === undefined) {
+      skipped.push(`文件不存在: ${url}`)
+      continue
+    }
+    if (!containedIn(root, real)) {
+      skipped.push(`越出工作区: ${url}`)
+      continue
+    }
+    if (seen.has(real)) continue
+    let size: number
+    try {
+      size = statSync(real).size
+    } catch {
+      skipped.push(`无法读取: ${url}`)
+      continue
+    }
+    if (size > maxBytes) {
+      skipped.push(`超过 ${maxBytes} 字节: ${url}`)
+      continue
+    }
+    let buffer: Buffer
+    try {
+      buffer = readFileSync(real)
+    } catch {
+      skipped.push(`无法读取: ${url}`)
+      continue
+    }
+    if (buffer.subarray(0, PNG_MAGIC.length).compare(PNG_MAGIC) !== 0) {
+      skipped.push(`不是 PNG: ${url}`)
+      continue
+    }
+    seen.add(real)
+    images.push({ absPath: real, filename: basename(real), buffer })
+  }
+  return { images, skipped }
+}
+
+function mediaIdOf(result: { media_id?: string; mediaId?: string }): string | undefined {
+  const id = result.media_id ?? result.mediaId
+  return id !== undefined && id !== '' ? id : undefined
+}
+
+/**
+ * Upload each PNG then push it as a WeCom image message.
+ * Failures are logged and do not abort the remaining files.
+ * @param ws - WeCom client.
+ * @param chatid - 1:1 userid or group chatid.
+ * @param images - files from {@link collectReplyPngs}.
+ * @returns counts of sent vs failed filenames.
+ */
+export async function sendCollectedPngs(
+  ws: MediaSender,
+  chatid: string,
+  images: CollectedPng[],
+): Promise<{ sent: number; failed: string[] }> {
+  const failed: string[] = []
+  let sent = 0
+  for (const image of images) {
+    try {
+      const uploaded = await ws.uploadMedia(image.buffer, {
+        type: 'image',
+        filename: image.filename,
+      })
+      const mediaId = mediaIdOf(uploaded)
+      if (mediaId === undefined) {
+        failed.push(image.filename)
+        console.error(`[im-bridge] 上传成功但无 media_id: ${image.filename}`)
+        continue
+      }
+      await ws.sendMediaMessage(chatid, 'image', mediaId)
+      sent++
+      console.log(`[im-bridge] 已发送图片 ${image.filename} (${image.buffer.length}B)`)
+    } catch (error) {
+      failed.push(image.filename)
+      const message = error instanceof Error ? error.message : String(error)
+      console.error(`[im-bridge] 发送图片失败 ${image.filename}: ${message}`)
+    }
+  }
+  return { sent, failed }
+}

package/src/session-key.ts

@@ -0,0 +1,197 @@
+/**
+ * Route WeCom inbound frames onto one DSH session per chat window:
+ * 1:1 by userid, groups by chatid.
+ */
+
+import { createHash } from 'node:crypto'
+
+/** Inbound fields used to pick a session (official `from` / `chattype` / `chatid`). */
+export interface WecomSessionFrame {
+  body?: {
+    from?: { userid?: string }
+    userid?: string
+    chatid?: string
+    chattype?: string | number
+  }
+}
+
+/** One WeCom chat window mapped onto a DSH session. */
+export interface WecomSessionRef {
+  /** Map key: `single:<userid>` or `group:<chatid>`. */
+  key: string
+  /** Window kind. */
+  kind: 'single' | 'group'
+  /** Sender userid for allow-lists; empty when the group frame omitted `from`. */
+  sender: string
+  /** Group chatid when {@link WecomSessionRef.kind} is `group`. */
+  chatid?: string
+}
+
+/** Single-chat frame with no userid — caller must refuse, not merge. */
+export class WecomSessionReject extends Error {
+  /** Short WeCom reply when the frame cannot be routed. */
+  readonly reply: string
+
+  /**
+   * @param reply - text sent back on the inbound frame.
+   */
+  constructor(reply: string) {
+    super(reply)
+    this.name = 'WecomSessionReject'
+    this.reply = reply
+  }
+}
+
+/**
+ * Sender userid from official `from.userid`, then `body.userid`.
+ * Does not read `sender` (not on the SDK message type).
+ */
+export function senderUserid(frame: WecomSessionFrame): string {
+  const from = frame.body?.from?.userid?.trim()
+  if (from) return from
+  const body = frame.body?.userid?.trim()
+  if (body) return body
+  return ''
+}
+
+function isGroupChat(chattype: string | number | undefined, chatid: string): boolean {
+  if (chattype === 'group' || chattype === 2 || chattype === '2') return true
+  if (chatid !== '' && chattype !== 'single' && chattype !== 1 && chattype !== '1') return true
+  return false
+}
+
+/** GUI channel prefix by window kind (no userid / chatid). */
+export const WECOM_TITLE_PREFIX = {
+  single: '企微·私聊',
+  group: '企微·群',
+} as const
+
+/** Leading `企微·` / previously used `企业微信·` channel labels. */
+const CHANNEL_PREFIX = /^(?:企业微信|企微)·(?:私聊|群)\s*/u
+
+/**
+ * Sidebar title: channel kind plus first-prompt text, never an id.
+ * @param kind - {@link WecomSessionRef.kind}.
+ * @param raw - automatic or previously prefixed title.
+ */
+export function wecomDisplayTitle(kind: 'single' | 'group', raw: string): string {
+  const prefix = WECOM_TITLE_PREFIX[kind]
+  const stripped = raw.replace(CHANNEL_PREFIX, '').trim()
+  return stripped === '' ? prefix : `${prefix} ${stripped}`
+}
+
+/** One leading `@nickname` and its separator; JS `\s` covers WeCom's U+00A0 and U+2005. */
+const LEADING_MENTION = /^@[^\s@]+(?:\s+|$)/u
+
+/**
+ * Drop the `@bot` mentions WeCom prepends to a group message, so the model
+ * input and the generated title both start at the actual request. Mentions
+ * later in the text stay; a message that is nothing but mentions is returned
+ * unchanged rather than emptied.
+ * @param text - trimmed inbound message text.
+ */
+export function stripBotMention(text: string): string {
+  let rest = text
+  for (let match = LEADING_MENTION.exec(rest); match !== null; match = LEADING_MENTION.exec(rest)) {
+    rest = rest.slice(match[0].length)
+  }
+  const stripped = rest.trim()
+  return stripped === '' ? text : stripped
+}
+
+/** Previously pinned `企微·私聊/群 <id>` titles from the id-based rename. */
+export function isLegacyPinnedWecomTitle(title: string): boolean {
+  return /^(?:企微·(?:私聊|群))\s+[A-Za-z0-9][A-Za-z0-9_-]*$/.test(title.trim())
+}
+
+function singleRef(sender: string): WecomSessionRef {
+  return {
+    key: `single:${sender}`,
+    kind: 'single',
+    sender,
+  }
+}
+
+/**
+ * Stable DSH session id for one epoch of a WeCom window (survives process
+ * restart). Epoch 1 carries no suffix, so ids minted before archiving support
+ * keep resolving to the same session.
+ * @param key - {@link WecomSessionRef.key}.
+ * @param epoch - 1-based session generation for this window.
+ */
+export function wecomSessionId(key: string, epoch = 1): string {
+  const hex = createHash('sha256').update(key).digest('hex').slice(0, 16)
+  return epoch <= 1 ? `wecom-${hex}` : `wecom-${hex}-${epoch}`
+}
+
+/** Session a WeCom window binds to, and how {@link planWecomBind} reaches it. */
+export interface WecomBindPlan {
+  /** DSH session id from {@link wecomSessionId}. */
+  readonly sessionId: string
+  /** Adopt a live Agent, resume a persisted session, or create a new one. */
+  readonly bind: 'adopt' | 'resume' | 'create'
+  /** Which epoch {@link WecomBindPlan.sessionId} belongs to. */
+  readonly epoch: number
+}
+
+/** What the Host currently knows about candidate session ids. */
+export interface WecomBindState {
+  /** Whether the Agent registry holds a live Agent for this id. */
+  live: (sessionId: string) => boolean
+  /** Session ids present in session persistence. */
+  stored: ReadonlySet<string>
+  /** Session ids in the workspace registry's archive set. */
+  archived: ReadonlySet<string>
+}
+
+/**
+ * Bind a WeCom window to its first non-archived epoch. Archiving a session in
+ * the GUI hides it everywhere with no way back, so its epoch is skipped and
+ * the window continues in the next one; the chosen id adopts a live Agent,
+ * resumes a persisted session, or starts a new one.
+ * @param key - {@link WecomSessionRef.key}.
+ * @param state - live / persisted / archived knowledge per candidate id.
+ */
+export function planWecomBind(key: string, state: WecomBindState): WecomBindPlan {
+  // An archived id is necessarily a known session, so the archive set bounds
+  // how many epochs can be skipped.
+  const limit = state.archived.size + 1
+  for (let epoch = 1; epoch <= limit; epoch += 1) {
+    const sessionId = wecomSessionId(key, epoch)
+    if (state.archived.has(sessionId)) continue
+    if (state.live(sessionId)) return { sessionId, bind: 'adopt', epoch }
+    if (state.stored.has(sessionId)) return { sessionId, bind: 'resume', epoch }
+    return { sessionId, bind: 'create', epoch }
+  }
+  throw new Error(`im-bridge: no free session epoch for ${key} within ${String(limit)} candidates`)
+}
+
+/**
+ * Map one inbound frame to a chat-window session.
+ * Group without `chatid` falls back to 1:1 when userid is present.
+ * 1:1 without userid throws {@link WecomSessionReject}.
+ */
+export function resolveWecomSession(frame: WecomSessionFrame): WecomSessionRef {
+  const sender = senderUserid(frame)
+  const chattype = frame.body?.chattype
+  const chatid = frame.body?.chatid?.trim() ?? ''
+  if (isGroupChat(chattype, chatid)) {
+    if (chatid === '') {
+      if (sender === '') {
+        throw new WecomSessionReject('无法识别会话，已忽略')
+      }
+      console.error(`[im-bridge] 群消息缺少 chatid, 退回单聊 key from=${sender}`)
+      return singleRef(sender)
+    }
+    return {
+      key: `group:${chatid}`,
+      kind: 'group',
+      sender,
+      chatid,
+    }
+  }
+  if (sender === '') {
+    throw new WecomSessionReject('无法识别发送者，已忽略')
+  }
+  return singleRef(sender)
+}

package/src/{wecom.js → wecom.ts}

@@ -1,12 +1,45 @@
 /**
- * wecom.js — 企业微信交互封装: 流式动画(v3) + 最终简报 + 发送助手。
- * 逻辑移植自旧版 im-bridge/bridge.js, 改为纯 ESM 供插件使用。
+ * WeCom stream helpers: thinking animation, final brief, and send retries.
+ * The WeCom SDK is imported only on the final-send retry path so plugin load
+ * does not pull it in before Loader settle.
  */
-import { generateReqId } from '@wecom/aibot-node-sdk'
 
-/** 流式思考动画的默认素材(可被 Config.thinking / cordis patch 覆盖) */
-export const DEFAULT_THINKING = {
-  /** 尚无 assistant/chunk 时的时间轴兜底文案(与模型是否在推理无关) */
+/** One timed fallback line while no model chunk has arrived. */
+export interface ThinkingPhase {
+  /** Elapsed seconds at which this line becomes current. */
+  atSec: number
+  /** Status text shown in the stream. */
+  text: string
+}
+
+/** Stream-animation copy and timing. */
+export interface ThinkingConfig {
+  /** Timed fallback lines while no `assistant/chunk` has arrived. */
+  phases: ThinkingPhase[]
+  /** Idle-phase spinner glyphs. */
+  spin: string[]
+  /** Extra lines after {@link ThinkingConfig.eggAfterSec}. */
+  eggs: string[]
+  /** Seconds after which eggs start rotating. */
+  eggAfterSec: number
+  /** Stream refresh interval. */
+  intervalMs: number
+  /** Prefix before a friendly tool name. */
+  activityPrefix: string
+  /** Lines rotated during `reasoning-delta`. */
+  reasoningStatus: string[]
+  /** Lines rotated during `text-delta`. */
+  outputStatus: string[]
+  /** Spinner glyphs during reasoning. */
+  reasoningSpin: string[]
+  /** Spinner glyphs during output. */
+  outputSpin: string[]
+  /** Tool registration name → WeCom-visible label. */
+  toolLabels: Record<string, string>
+}
+
+/** Default stream-animation copy; Config / cordis patch may override. */
+export const DEFAULT_THINKING: ThinkingConfig = {
   phases: [
     { atSec: 0, text: '🤔 正在理解你的需求…' },
     { atSec: 8, text: '📋 正在整理任务清单' },
@@ -27,15 +60,10 @@ export const DEFAULT_THINKING = {
   eggAfterSec: 240,
   intervalMs: 1500,
   activityPrefix: '🛠️ 正在执行 ',
-  /** 收到 reasoning-delta 时的状态行文案(按刷新轮换) */
   reasoningStatus: ['💭 模型思考中…', '🧠 深入分析中…', '✨ 梳理思路中…'],
-  /** 收到 text-delta 时的状态行文案(按刷新轮换) */
   outputStatus: ['✍️ 正在输出回复…', '📝 组织文字中…', '💬 生成回答中…'],
-  /** 思考阶段专用旋转表情 */
   reasoningSpin: ['💭', '🧠', '🌀', '✨'],
-  /** 输出阶段专用旋转表情 */
   outputSpin: ['✍️', '📝', '💬', '⚡'],
-  /** 工具名 → 企微活动文案友好名(可被 thinking.toolLabels 覆盖) */
   toolLabels: {
     pwsh: 'PowerShell',
     bash: 'Shell',
@@ -53,13 +81,13 @@ export const DEFAULT_THINKING = {
   },
 }
 
-/**
- * 将工具注册名映射为企微可见友好名。
- * @param {string} name - 工具名(如 pwsh)
- * @param {typeof DEFAULT_THINKING | undefined} thinking - 含可选 toolLabels 覆盖
- * @returns {string}
- */
-export function labelTool(name, thinking) {
+/** WeCom client methods used by the animation and final send. */
+export interface WecomStreamClient {
+  replyStream(frame: unknown, streamId: string, content: string, finish: boolean): Promise<unknown>
+}
+
+/** Map a tool registration name to the WeCom-visible label. */
+export function labelTool(name: string, thinking?: Partial<ThinkingConfig>): string {
   const labels = {
     ...DEFAULT_THINKING.toolLabels,
     ...(thinking?.toolLabels && typeof thinking.toolLabels === 'object' ? thinking.toolLabels : {}),
@@ -67,25 +95,22 @@ export function labelTool(name, thinking) {
   return labels[name] || name
 }
 
-/**
- * 从 string | string[] 配置中按 tick 取一条状态文案。
- * @param {string | string[] | undefined} value
- * @param {string[]} fallback
- * @param {number} tick
- */
-export function pickStatusLine(value, fallback, tick) {
+/** Pick one status line from a configured list, rotating by tick. */
+export function pickStatusLine(
+  value: string | string[] | undefined,
+  fallback: string[],
+  tick: number,
+): string {
   const list = Array.isArray(value) && value.length > 0
     ? value
     : (typeof value === 'string' && value !== '' ? [value] : fallback)
-  return list[Math.abs(tick) % list.length]
+  return list[Math.abs(tick) % list.length] ?? fallback[0] ?? ''
 }
 
-/**
- * 根据 assistant/chunk 判别模型流式阶段。
- * @param {{ type?: string, blockType?: string } | undefined} chunk
- * @returns {'reasoning' | 'outputting' | null}
- */
-export function streamPhaseFromChunk(chunk) {
+/** Infer the model stream phase from one `assistant/chunk` payload. */
+export function streamPhaseFromChunk(
+  chunk: { type?: string; blockType?: string } | undefined,
+): 'reasoning' | 'outputting' | null {
   if (!chunk || typeof chunk !== 'object') return null
   if (chunk.type === 'reasoning-delta') return 'reasoning'
   if (chunk.type === 'text-delta') return 'outputting'
@@ -96,8 +121,8 @@ export function streamPhaseFromChunk(chunk) {
   return null
 }
 
-/** 毫秒 → 人类可读时长(如 "9 分 47 秒") */
-export function fmtDuration(ms) {
+/** Format milliseconds as a short Chinese duration. */
+export function fmtDuration(ms: number): string {
   const s = Math.floor(ms / 1000)
   if (s < 60) return `${s} 秒`
   const m = Math.floor(s / 60)
@@ -105,38 +130,47 @@ export function fmtDuration(ms) {
   return r > 0 ? `${m} 分 ${r} 秒` : `${m} 分钟`
 }
 
-/** 按耗时给个速度评价 */
-export function speedOf(ms) {
+/** Speed label from elapsed milliseconds. */
+export function speedOf(ms: number): string {
   if (ms < 60000) return '⚡ 神速'
   if (ms < 180000) return '🚀 正常速度'
   return '🐢 耗时较长'
 }
 
-/** 执行完成的尾部简报 */
-export function footerOf(ms) {
+/** Footer appended to a completed WeCom reply. */
+export function footerOf(ms: number): string {
   if (ms >= 180000) {
     return `\n\n---\n✅ 执行完成 · 🐢 耗时较长（${fmtDuration(ms)}）\n💡 如需提速，可让我把诊断步骤合并成更少的 SSH 批次`
   }
   return `\n\n---\n✅ 执行完成 · ${speedOf(ms)}（${fmtDuration(ms)}）`
 }
 
-/** 截断(按字节) */
-export function truncate(text, max) {
+/** Truncate a string to at most `max` UTF-8 bytes. */
+export function truncate(text: string, max: number): string {
   if (Buffer.byteLength(text, 'utf8') <= max) return text
   let t = text
   while (Buffer.byteLength(t, 'utf8') > max) t = t.slice(0, -100)
-  return t + '\n\n...(内容过长已截断)'
+  return `${t}\n\n...(内容过长已截断)`
 }
 
 /**
- * 流式动画 v3: 阶段化台词 + 旋转表情 + 进度条 + 已用时/剩余估算 + 长任务彩蛋。
- * 每 intervalMs 更新一次同一条流式消息(共用 streamId), 直到 agent 完成。返回停止函数。
- * @param {() => string} [activity] - 可选: 返回当前真实活动描述, 覆盖阶段台词。
- * @param {typeof DEFAULT_THINKING} [thinking] - 动画素材; 缺省用 {@link DEFAULT_THINKING}。
- * @param {() => 'idle' | 'reasoning' | 'outputting' | string} [getStreamPhase] - 模型流式阶段, 影响旋转表情池。
+ * Refresh one stream message until the caller stops it.
+ * @param activity - live tool/status text; empty falls back to timed phases.
+ * @param thinking - animation copy; defaults to {@link DEFAULT_THINKING}.
+ * @param getStreamPhase - model stream phase; selects the spinner pool.
+ * @returns disposer that cancels the interval.
  */
-export function startThinking(ws, frame, streamId, startedAt, timeoutSec, activity, thinking, getStreamPhase) {
-  const t = { ...DEFAULT_THINKING, ...(thinking || {}) }
+export function startThinking(
+  ws: WecomStreamClient,
+  frame: unknown,
+  streamId: string,
+  startedAt: number,
+  timeoutSec: number,
+  activity?: () => string,
+  thinking?: Partial<ThinkingConfig>,
+  getStreamPhase?: () => 'idle' | 'reasoning' | 'outputting' | string,
+): () => void {
+  const t = { ...DEFAULT_THINKING, ...thinking }
   const phases = Array.isArray(t.phases) && t.phases.length > 0 ? t.phases : DEFAULT_THINKING.phases
   const spin = Array.isArray(t.spin) && t.spin.length > 0 ? t.spin : DEFAULT_THINKING.spin
   const reasoningSpin = Array.isArray(t.reasoningSpin) && t.reasoningSpin.length > 0
@@ -153,10 +187,10 @@ export function startThinking(ws, frame, streamId, startedAt, timeoutSec, activi
   const timer = setInterval(() => {
     const secs = Math.floor((Date.now() - startedAt) / 1000)
     const live = activity ? activity() : ''
-    let stage = phases[0].text
+    let stage = phases[0]?.text ?? ''
     if (!live) {
-      for (const p of phases) {
-        if (secs >= p.atSec) stage = p.text
+      for (const phase of phases) {
+        if (secs >= phase.atSec) stage = phase.text
       }
     }
     const pct = Math.min(Math.floor((secs / total) * 100), 99)
@@ -176,17 +210,25 @@ export function startThinking(ws, frame, streamId, startedAt, timeoutSec, activi
     const emoji = emojiPool[i % emojiPool.length]
     i++
     const status = live || stage
-    ws.replyStream(frame, streamId, `${emoji} ${status}   ⏱ ${secs} 秒${remainTxt}${bar}${egg}`, false).catch(() => {})
+    void ws.replyStream(frame, streamId, `${emoji} ${status}   ⏱ ${secs} 秒${remainTxt}${bar}${egg}`, false)
+      .catch(() => {})
   }, intervalMs)
   return () => clearInterval(timer)
 }
 
-/** 最终回复: 原流失败(如 WeCom 10 分钟过期)时用新流重试一次 */
-export async function sendFinal(ws, frame, streamId, content) {
+/** Finish the current stream; open a new stream if WeCom expired the first. */
+export async function sendFinal(
+  ws: WecomStreamClient,
+  frame: unknown,
+  streamId: string,
+  content: string,
+): Promise<void> {
   try {
     await ws.replyStream(frame, streamId, content, true)
-  } catch (e) {
-    console.error(`[im-bridge] 原流最终回复失败(${e.message}), 尝试新流...`)
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    console.error(`[im-bridge] 原流最终回复失败(${message}), 尝试新流...`)
+    const { generateReqId } = await import('@wecom/aibot-node-sdk')
     await ws.replyStream(frame, generateReqId('stream'), content, true)
   }
 }

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "verbatimModuleSyntax": true,
+    "allowImportingTsExtensions": true
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.d.ts", "tests/**/*.ts"]
+}