@mhfire/dsh-im-bridge 0.2.0 → 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/tsconfig.json

@@ -10,5 +10,5 @@
     "verbatimModuleSyntax": true,
     "allowImportingTsExtensions": true
   },
-  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.d.ts"]
+  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.d.ts", "tests/**/*.ts"]
 }