@modesto_ma/dsh-channels 0.0.0-stage → 0.1.0

package/src/feishu/agent-context.ts

@@ -0,0 +1,62 @@
+/**
+ * Agent-scoped system-prompt guidance for Feishu attachments.
+ *
+ * The channel archives inbound images/files/forwarded records below
+ * `<workspace>/attachments/` without any model turn. This section is what
+ * makes that convention discoverable: it tells the Agent where attachments
+ * live, how to read them, and that reading is opt-in per user request.
+ *
+ * Registered inside the Agent scope (through `inject(['systemPrompt'])`), so
+ * it is disposed with the Agent and does not leak into other compositions.
+ *
+ * @module dsh-channels/feishu/agent-context
+ */
+
+import type { AgentContext } from '../host/agent.ts'
+
+/** Stable prompt-section name; one registration per Agent scope. */
+export const FEISHU_ATTACHMENTS_SECTION = 'dsh-channels:feishu-attachments'
+
+/**
+ * Placement between the harness file-reference section (900) and the
+ * filesystem tool descriptions (1000): the convention is read before the
+ * tool that implements it.
+ */
+const FEISHU_ATTACHMENTS_ORDER = 950
+
+/** Model-facing text. Kept stable so unchanged sessions keep their KV cache. */
+export const FEISHU_ATTACHMENTS_GUIDANCE = `## Feishu attachments
+Every Feishu conversation (topic) has its own workspace and its own attachments directory. Images, files, and forwarded chat records sent through Feishu are archived verbatim in this conversation's \`attachments/\` directory. Each file name starts with its receipt time (\`YYYYMMDD-HHmmss-\`), so newer attachments sort later and \`ls -lt <dir>\` lists the newest first.
+
+Attachments are never inserted into the conversation automatically. Read them only when the user's request needs them, and do not read attachments the user did not mention:
+- images: use \`read_image\` with the file path;
+- text and code: use \`read\` when the session mounts that tool, otherwise \`bash\` (for example \`sed -n '1,200p' <file>\`);
+- other formats (PDF, Office, archives, ...): inspect or convert them with \`bash\`.
+If the user refers to "the file/image I just sent" without a name, list this conversation's attachments directory and pick the most recent matching attachment. Other Feishu conversations have separate workspaces: never read outside this workspace, and never mention files from another conversation.`
+
+/**
+ * Full guidance for one Session. The absolute per-session directory is
+ * appended when known so the convention still resolves after the Agent changes
+ * its working directory with the `working_directory` tool.
+ */
+export function attachmentsGuidance(attachmentsDir?: string): string {
+  if (attachmentsDir === undefined || attachmentsDir === '') return FEISHU_ATTACHMENTS_GUIDANCE
+  return `${FEISHU_ATTACHMENTS_GUIDANCE}\n\nThis conversation's attachment directory is \`${attachmentsDir.replace(/`/gu, "'")}\` (absolute).`
+}
+
+/**
+ * Mount the attachment guidance into one Agent scope. Call from agent setup;
+ * a missing `systemPrompt` service degrades to a no-op (headless hosts).
+ */
+export async function mountChannelGuidance(
+  agentCtx: AgentContext,
+  attachmentsDir?: string,
+): Promise<void> {
+  await agentCtx.inject(['systemPrompt'], (ctx) => {
+    ctx.systemPrompt?.section({
+      name: FEISHU_ATTACHMENTS_SECTION,
+      order: FEISHU_ATTACHMENTS_ORDER,
+      text: attachmentsGuidance(attachmentsDir),
+    })
+  })
+}

package/src/feishu/delivery.ts

@@ -0,0 +1,188 @@
+/**
+ * Outbound Feishu delivery: card sends, the topic-creating first reply, body
+ * segment fallbacks, and the command reaction lifecycle.
+ *
+ * Every send is gated on the service being started, and commands are the only
+ * plane that adds/deletes reactions (`Typing` → `DONE`); ordinary turns get
+ * their reaction lifecycle from the streamer's finalize path.
+ *
+ * @module dsh-channels/feishu/delivery
+ */
+
+import { buildCommandResultCard } from '../commands.ts'
+import type { CommandCardState } from '../commands.ts'
+import type { RouteRecord } from '../domain.ts'
+import type { FeishuChannel, NormalizedMessage, SendResult } from '../feishu-channel.ts'
+
+/** Rejection text for a message in a topic retired by route TTL. */
+export const EXPIRED_ROUTE_TEXT = '该话题已超过路由保留时间，并已与原 Session 解绑。为避免误接续上下文，插件不会在此话题创建新 Session；请从私聊或群聊主会话发起新消息（群聊请 @ 机器人）创建新话题。'
+
+export interface CardDeliveryDeps {
+  /** The live channel, or undefined before `start()` / after shutdown. */
+  channel(): FeishuChannel | undefined
+  /** Whether the service is accepting sends. */
+  started(): boolean
+  /** Route owning a session (segment-card anchoring). */
+  routeForSession(sessionId: string): RouteRecord | undefined
+  warn(message: string, ...args: unknown[]): void
+}
+
+export class CardDelivery {
+  constructor(private readonly deps: CardDeliveryDeps) {}
+
+  /** The live channel; throws instead of silently dropping a delivery. */
+  requireChannel(): FeishuChannel {
+    const channel = this.deps.channel()
+    if (channel === undefined) throw new Error('dsh-channels: channel not started')
+    return channel
+  }
+
+  /** Apply the command-only Typing → DONE reaction lifecycle. */
+  async withCommandReaction(msg: NormalizedMessage, operation: () => Promise<void>): Promise<void> {
+    if (!this.deps.started()) return
+    const channel = this.requireChannel()
+    const reactionId = await channel.addReaction(msg.messageId, 'Typing').catch(() => undefined)
+    try {
+      await operation()
+    } finally {
+      if (reactionId !== undefined) {
+        await channel.removeReaction(msg.messageId, reactionId).catch(() => {})
+      }
+      await channel.addReaction(msg.messageId, 'DONE').catch(() => {})
+    }
+  }
+
+  /** Standalone, non-streaming command result card with a non-threaded fallback. */
+  async commandCard(
+    msg: NormalizedMessage,
+    state: CommandCardState,
+    options: { createThread?: boolean } = {},
+  ): Promise<void> {
+    await this.standaloneReply(msg, buildCommandResultCard(state), options)
+  }
+
+  /** Reject a post-TTL topic message without creating or resuming an Agent. */
+  async expiredRouteCard(msg: NormalizedMessage, command?: string): Promise<void> {
+    await this.commandCard(msg, {
+      kind: 'expired',
+      ...(command === undefined ? {} : { command }),
+      text: EXPIRED_ROUTE_TEXT,
+    })
+  }
+
+  /**
+   * Shared delivery policy for command-plane cards: reply in a new topic by
+   * default, then degrade to a plain reply when Feishu refuses the topic.
+   */
+  async standaloneReply(
+    msg: NormalizedMessage,
+    card: object,
+    options: { createThread?: boolean } = {},
+  ): Promise<void> {
+    const channel = this.deps.channel()
+    if (!this.deps.started() || channel === undefined) return
+    const createThread = options.createThread ?? true
+    try {
+      await channel.send(msg.chatId, { card }, createThread
+        ? { replyTo: msg.messageId, replyInThread: true }
+        : { replyTo: msg.messageId })
+    } catch (error) {
+      if (!createThread) {
+        this.deps.warn(
+          'dsh-channels: direct command result delivery failed for message %s: %s',
+          msg.messageId, String(error),
+        )
+        return
+      }
+      try {
+        await channel.send(msg.chatId, { card }, { replyTo: msg.messageId })
+      } catch (fallbackError) {
+        this.deps.warn(
+          'dsh-channels: command result delivery failed for message %s: %s / %s',
+          msg.messageId, String(error), String(fallbackError),
+        )
+      }
+    }
+  }
+
+  /**
+   * Send one short plain-text notice anchored to an inbound message. Replies
+   * inside an existing topic when the message belongs to one, and never
+   * creates a topic: an attachment-only message must stay a notice, not a new
+   * conversation. Best-effort — a failed notice only warns.
+   */
+  async noticeText(msg: NormalizedMessage, text: string): Promise<void> {
+    const channel = this.deps.channel()
+    if (!this.deps.started() || channel === undefined) return
+    try {
+      await channel.send(msg.chatId, { text }, {
+        replyTo: msg.messageId,
+        ...(msg.threadId === undefined ? {} : { replyInThread: true }),
+      })
+    } catch (error) {
+      this.deps.warn(
+        'dsh-channels: attachment notice delivery failed for message %s: %s',
+        msg.messageId, String(error),
+      )
+    }
+  }
+
+  /**
+   * Reply with the first card frame. Prefers topic replies (`reply_in_thread`)
+   * — the documented way a bot creates a topic — and falls back to a plain
+   * reply when Feishu refuses (degraded chat-scoped routing).
+   */
+  async replyFirstCard(
+    msg: NormalizedMessage,
+    card: object,
+  ): Promise<{ messageId: string; threadId?: string; degraded: boolean }> {
+    const channel = this.requireChannel()
+    try {
+      const res = await channel.send(
+        msg.chatId,
+        { card },
+        { replyTo: msg.messageId, replyInThread: true },
+      )
+      const threadId = await channel.threadIdOfMessage(res.messageId).catch(() => undefined)
+      return { messageId: res.messageId, threadId, degraded: false }
+    } catch (error) {
+      if (!this.deps.started()) throw error
+      const res = await channel.send(msg.chatId, { card }, { replyTo: msg.messageId })
+      return { messageId: res.messageId, degraded: true }
+    }
+  }
+
+  /**
+   * Send one body-segment continuation card into the session's topic (or, for
+   * degraded chat-scoped routes, as a plain reply anchored to the main card).
+   * When Feishu rejects the card (e.g. per-card table limit, error 11310) the
+   * segment is re-delivered as a plain-text message so the content is never
+   * lost — text messages carry no card constraints.
+   */
+  async segmentCard(
+    sessionId: string,
+    segment: number,
+    card: object,
+    fallbackText: string,
+  ): Promise<{ messageId: string; mode: 'card' | 'text' }> {
+    const record = this.deps.routeForSession(sessionId)
+    if (record === undefined) {
+      throw new Error(`dsh-channels: no route record for session ${sessionId}; segment card not sent`)
+    }
+    const channel = this.requireChannel()
+    const options = { replyTo: record.cardMessageId, replyInThread: record.kind === 'thread' }
+    try {
+      const res: SendResult = await channel.send(record.chatId, { card }, options)
+      return { messageId: res.messageId, mode: 'card' }
+    } catch (error) {
+      this.deps.warn(
+        'dsh-channels: segment %d card for session %s rejected, falling back to plain text: %s',
+        segment, sessionId, String(error),
+      )
+      const res = await channel.send(record.chatId, {
+        text: `📄 回复分段 ${segment}（卡片发送失败，已降级为纯文本）\n\n${fallbackText}`,
+      }, options)
+      return { messageId: res.messageId, mode: 'text' }
+    }
+  }
+}

package/src/feishu/inbound-attachments.ts

@@ -0,0 +1,436 @@
+/**
+ * Inbound attachment archival: Feishu image/file resources and merged-forward
+ * chat records are written verbatim below `<workspace>/attachments/`.
+ *
+ * Nothing is forwarded to the model. The Agent's own filesystem tools read
+ * whichever attachment the conversation needs, so an attachment message costs
+ * no model request at all and unreferenced files never enter the context.
+ * Files are streamed straight to disk: there is no plugin-side size cap, so a
+ * large upload must not be collected in memory.
+ *
+ * Two payload shapes need care because the SDK normalizer drops them:
+ * rich-text (`post`) messages keep their attached files in a top-level
+ * `files` array that `convertPost` ignores, and merged-forward records are
+ * plain text rather than resources. Both are recovered here; the post files
+ * come from the raw event, which the channel adapter asks the SDK to attach.
+ *
+ * @module dsh-channels/feishu/inbound-attachments
+ */
+
+import { randomUUID } from 'node:crypto'
+import { createWriteStream } from 'node:fs'
+import { mkdir, open, readdir, rename, rm, stat, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { Readable } from 'node:stream'
+import { pipeline } from 'node:stream/promises'
+import type { FeishuChannel, NormalizedMessage } from '../feishu-channel.ts'
+import { sniffImageMediaType } from '../feishu-channel.ts'
+
+/** Workspace subdirectory that holds every archived attachment. */
+export const ATTACHMENTS_DIR = 'attachments'
+
+/** `<workspace>/attachments` directory of one topic workspace. */
+export function attachmentsDir(workspacePath: string): string {
+  return path.join(workspacePath, ATTACHMENTS_DIR)
+}
+
+/**
+ * Move every staged attachment into one topic workspace. Staging holds files
+ * received before their topic (and therefore its workspace) existed; they
+ * belong to the first Session created for that topic. Best-effort per file.
+ *
+ * @returns how many files were adopted.
+ */
+export async function adoptStagedAttachments(stagingDir: string, workspacePath: string): Promise<number> {
+  let entries: Array<{ name: string; isFile(): boolean }>
+  try {
+    entries = await readdir(stagingDir, { withFileTypes: true })
+  } catch {
+    return 0
+  }
+  const files = entries.filter(entry => entry.isFile() && !entry.name.startsWith('.'))
+  if (files.length === 0) return 0
+  const target = attachmentsDir(workspacePath)
+  try {
+    await mkdir(target, { recursive: true })
+  } catch {
+    return 0
+  }
+  let adopted = 0
+  for (const entry of files) {
+    const destination = await uniqueName(target, entry.name)
+    try {
+      await rename(path.join(stagingDir, entry.name), path.join(target, destination))
+      adopted += 1
+    } catch {
+      // Leave the staged file for the next attempt; never block the turn.
+    }
+  }
+  return adopted
+}
+
+/** The SDK placeholder for a rich-text message that carried no visible text. */
+const EMPTY_POST_PLACEHOLDER = '[rich text message]'
+
+/** Placeholders the SDK leaves in normalized content for attachment payloads. */
+const IMAGE_PLACEHOLDER = /!\[image\]\([^)]*\)/gu
+const FILE_PLACEHOLDER = /<file[^>]*\/>/gu
+const FORWARDED_PLACEHOLDER = /<forwarded_messages(?:\/>|>[\s\S]*?<\/forwarded_messages>)/gu
+/** An expanded record always starts with this wrapper; a bare empty one means the fetch failed. */
+const EMPTY_FORWARDED = '<forwarded_messages/>'
+
+export interface AttachmentIntakeDeps {
+  /** Whether this deployment archives inbound attachments at all. */
+  enabled(): boolean
+  /** Live channel; undefined after shutdown. */
+  channel(): FeishuChannel | undefined
+  /** Structured warning sink (never throws). */
+  warn(message: string, ...args: unknown[]): void
+  /** Deterministic clock seam for file-name prefixes. */
+  now?(): number
+}
+
+/** One decoded attachment recovered from the normalized message or its raw post payload. */
+export interface AttachmentResource {
+  readonly type: 'image' | 'file'
+  readonly fileKey: string
+  readonly fileName?: string
+  /** Feishu folder messages cannot be downloaded through the resource API. */
+  readonly folder?: boolean
+}
+
+/** One attachment that could not be archived, with a user-facing reason. */
+export interface AttachmentFailure {
+  readonly name: string
+  readonly reason: string
+}
+
+export interface AttachmentArchiveResult {
+  /** Resources durably written to the workspace. */
+  saved: number
+  /** Resources that failed to download, write, or are unsupported. */
+  failed: number
+  /** User-facing per-attachment failure notes (only when `failed > 0`). */
+  failures: readonly AttachmentFailure[]
+  /** True when the message carried no prompt text after removing placeholders. */
+  attachmentOnly: boolean
+  /** Remaining text after attachment placeholders are removed. */
+  text: string
+}
+
+/** One file attached to a rich-text (`post`) message. */
+export interface PostAttachedFile {
+  readonly fileKey: string
+  readonly fileName?: string
+  readonly folder?: boolean
+}
+
+/**
+ * Every attachment payload of one message, merging SDK-normalized resources
+ * with files the `post` converter dropped.
+ */
+export function attachmentResources(msg: NormalizedMessage): AttachmentResource[] {
+  const resources: AttachmentResource[] = (msg.resources ?? [])
+    .filter(resource => resource.type === 'image' || resource.type === 'file')
+    .map(resource => ({
+      type: resource.type === 'file' ? 'file' : 'image',
+      fileKey: resource.fileKey,
+      ...(resource.fileName === undefined ? {} : { fileName: resource.fileName }),
+    }))
+  const seen = new Set(resources.map(resource => resource.fileKey))
+  for (const file of postAttachedFiles(msg.rawContentType, msg.raw)) {
+    if (seen.has(file.fileKey)) continue
+    seen.add(file.fileKey)
+    resources.push({ type: 'file', ...file })
+  }
+  return resources
+}
+
+/** Whether one message may carry an attachment payload worth archiving. */
+export function hasAttachmentPayload(msg: NormalizedMessage): boolean {
+  if (msg.rawContentType === 'merge_forward') return true
+  if (msg.rawContentType === 'post') return true
+  return attachmentResources(msg).length > 0
+}
+
+/**
+ * Recover the files a rich-text message attached.
+ *
+ * Feishu serializes a post with text and files as `{ title, content, files }`.
+ * The SDK's `convertPost` walks `content` elements only, so every entry of
+ * `files` is lost from `NormalizedMessage.resources`; the raw event (enabled by
+ * `includeRawEvent`) still carries it. Locale-wrapped bodies are searched one
+ * level deep for the same shape.
+ */
+export function postAttachedFiles(rawContentType: string, raw: unknown): PostAttachedFile[] {
+  if (rawContentType !== 'post' || raw === null || raw === undefined) return []
+  const message = (raw as { message?: { content?: unknown } }).message
+  if (message === undefined) return []
+  const content = typeof message.content === 'string' ? safeJson(message.content) : message.content
+  if (content === undefined) return []
+  const entries = collectFileEntries(content, 0)
+  const files: PostAttachedFile[] = []
+  for (const entry of entries) {
+    const fileKey = typeof entry.file_key === 'string' && entry.file_key !== '' ? entry.file_key : undefined
+    if (fileKey === undefined) continue
+    files.push({
+      fileKey,
+      ...(typeof entry.file_name === 'string' && entry.file_name !== '' ? { fileName: entry.file_name } : {}),
+      ...(entry.is_folder === true ? { folder: true } : {}),
+    })
+  }
+  return files
+}
+
+function safeJson(value: string): unknown {
+  try {
+    return JSON.parse(value)
+  } catch {
+    return undefined
+  }
+}
+
+/** Find every `files` array in a post body (flat or locale-wrapped), depth-bounded. */
+function collectFileEntries(node: unknown, depth: number): Array<Record<string, unknown>> {
+  if (depth > 3 || node === null || typeof node !== 'object' || Array.isArray(node)) return []
+  const record = node as Record<string, unknown>
+  const files = record.files
+  if (Array.isArray(files)) {
+    return files.filter(
+      (entry): entry is Record<string, unknown> => entry !== null && typeof entry === 'object' && !Array.isArray(entry),
+    )
+  }
+  const out: Array<Record<string, unknown>> = []
+  for (const value of Object.values(record)) out.push(...collectFileEntries(value, depth + 1))
+  return out
+}
+
+export class AttachmentIntake {
+  constructor(private readonly deps: AttachmentIntakeDeps) {}
+
+  /**
+   * Archive every image/file resource and merged-forward record of one
+   * inbound message. Failures are contained per attachment; the method never
+   * throws and always reports the remaining prompt text.
+   */
+  async archive(msg: NormalizedMessage, directory: string): Promise<AttachmentArchiveResult> {
+    const resources = attachmentResources(msg)
+    const forwarded = msg.rawContentType === 'merge_forward'
+    if (resources.length === 0 && !forwarded) {
+      return { saved: 0, failed: 0, failures: [], attachmentOnly: false, text: msg.content ?? '' }
+    }
+
+    const stripped = stripAttachmentPlaceholders(msg.content ?? '', forwarded)
+    const remainingText = stripped === EMPTY_POST_PLACEHOLDER ? '' : stripped
+    const result = (
+      saved: number,
+      failures: readonly AttachmentFailure[],
+    ): AttachmentArchiveResult => ({
+      saved,
+      failed: failures.length,
+      failures,
+      attachmentOnly: remainingText === '',
+      text: remainingText,
+    })
+
+    if (!this.deps.enabled()) return result(0, [])
+
+    const channel = this.deps.channel()
+    if (channel === undefined) {
+      return result(0, resources.map(resource => ({
+        name: resourceName(resource),
+        reason: '飞书连接未运行，附件未保存',
+      })))
+    }
+
+    const dir = directory
+    let saved = 0
+    const failures: AttachmentFailure[] = []
+    try {
+      await mkdir(dir, { recursive: true })
+    } catch (error) {
+      this.deps.warn('dsh-channels: creating attachments directory %s failed: %s', dir, String(error))
+      return result(0, resources.map(resource => ({
+        name: resourceName(resource),
+        reason: `无法创建工作区附件目录：${describeFailure(error)}`,
+      })))
+    }
+
+    for (const resource of resources) {
+      const name = resourceName(resource)
+      if (resource.folder === true) {
+        failures.push({ name, reason: '飞书文件夹消息暂不支持下载' })
+        continue
+      }
+      try {
+        await this.saveResource(msg, resource, dir)
+        saved += 1
+      } catch (error) {
+        failures.push({ name, reason: describeFailure(error) })
+        this.deps.warn(
+          'dsh-channels: archiving resource %s of message %s failed: %s',
+          resource.fileKey, msg.messageId, String(error),
+        )
+      }
+    }
+
+    if (forwarded) {
+      try {
+        await this.saveForwardedRecord(msg, dir)
+        saved += 1
+      } catch (error) {
+        failures.push({ name: '会话记录', reason: describeFailure(error) })
+        this.deps.warn(
+          'dsh-channels: archiving forwarded record of message %s failed: %s',
+          msg.messageId, String(error),
+        )
+      }
+    }
+
+    if (saved > 0) {
+      await channel.addReaction(msg.messageId, 'DONE').catch(() => undefined)
+    } else if (failures.length > 0) {
+      await channel.addReaction(msg.messageId, 'No').catch(() => undefined)
+    }
+
+    return result(saved, failures)
+  }
+
+  /** Stream one image/file resource to disk, then publish it under a stable name. */
+  private async saveResource(
+    msg: NormalizedMessage,
+    resource: AttachmentResource,
+    dir: string,
+  ): Promise<void> {
+    const channel = this.deps.channel()
+    if (channel === undefined) throw new Error('channel is not running')
+    const stream = await channel.downloadResource(
+      msg.messageId,
+      resource.fileKey,
+      resource.type === 'file' ? 'file' : 'image',
+    )
+    const temporary = path.join(dir, `.tmp-${randomUUID()}`)
+    try {
+      await pipeline(Readable.from(stream), createWriteStream(temporary, { mode: 0o600 }))
+      const original = sanitizeFileName(resource.fileName)
+      const base = original ?? (resource.type === 'image'
+        ? `image${await sniffExtension(temporary)}`
+        : 'file.bin')
+      const finalName = await uniqueName(dir, `${this.stamp()}-${base}`)
+      await rename(temporary, path.join(dir, finalName))
+    } catch (error) {
+      await rm(temporary, { force: true }).catch(() => undefined)
+      throw error
+    }
+  }
+
+  /**
+   * Persist one expanded merged-forward record as UTF-8 text. The content is
+   * already plain text (`<forwarded_messages>…`), so no parsing or conversion
+   * happens here — the Agent reads the file when the conversation needs it.
+   */
+  private async saveForwardedRecord(msg: NormalizedMessage, dir: string): Promise<void> {
+    const content = msg.content ?? ''
+    if (content.trim() === '' || content.trim() === EMPTY_FORWARDED) {
+      throw new Error('会话记录为空（机器人可能缺少源消息的读取权限）')
+    }
+    const name = await uniqueName(dir, `${this.stamp()}-forwarded-record.txt`)
+    await writeFile(path.join(dir, name), `${content}\n`, { encoding: 'utf8', mode: 0o600 })
+  }
+
+  private stamp(): string {
+    return compactTimestamp(this.deps.now?.() ?? Date.now())
+  }
+}
+
+/** Remove attachment placeholders while keeping ordinary prompt text. */
+export function stripAttachmentPlaceholders(content: string, forwarded: boolean): string {
+  let text = content.replace(IMAGE_PLACEHOLDER, ' ').replace(FILE_PLACEHOLDER, ' ')
+  if (forwarded) text = text.replace(FORWARDED_PLACEHOLDER, ' ')
+  return text.replace(/[ \t]+/gu, ' ').replace(/\s*\n\s*/gu, '\n').trim()
+}
+
+/** `YYYYMMDD-HHmmss`, UTC, filesystem- and sort-friendly. */
+export function compactTimestamp(epochMs: number): string {
+  return new Date(epochMs).toISOString().replace(/[-:]/gu, '').replace(/\..+$/u, '').replace('T', '-')
+}
+
+/** Strip directories, control characters, and reserved path characters from a display name. */
+export function sanitizeFileName(raw: string | undefined): string | undefined {
+  if (raw === undefined) return undefined
+  const base = raw.split(/[\\/]/u).pop() ?? raw
+  const cleaned = base
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\u0000-\u001f\u007f<>:"\\|?*]/gu, '_')
+    .replace(/^[.\s]+/u, '')
+    .replace(/[.\s]+$/u, '')
+  if (cleaned === '') return undefined
+  return truncateUtf8(cleaned, 120)
+}
+
+/** User-facing name for one attachment. */
+function resourceName(resource: AttachmentResource): string {
+  if (resource.fileName !== undefined && resource.fileName !== '') return resource.fileName
+  return resource.type === 'image' ? '图片' : '文件'
+}
+
+/**
+ * Turn a download/write failure into a short user-facing reason. Feishu's
+ * message-resource API refuses files above 100 MB, which is the common case
+ * for a 400 on an otherwise valid file.
+ */
+export function describeFailure(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error)
+  if (/status code 400|bad request/iu.test(message)) {
+    return '飞书下载接口拒绝请求（文件可能已过期、已被删除或暂不可下载）'
+  }
+  if (/status code 403|forbidden/iu.test(message)) return '飞书下载接口无权限'
+  return message
+}
+
+/** Truncate a UTF-8 string on a character boundary. */
+function truncateUtf8(value: string, maxBytes: number): string {
+  if (Buffer.byteLength(value) <= maxBytes) return value
+  let out = ''
+  for (const char of value) {
+    if (Buffer.byteLength(out + char) > maxBytes) break
+    out += char
+  }
+  return out
+}
+
+/** Pick a non-colliding destination name inside one directory. */
+async function uniqueName(dir: string, candidate: string): Promise<string> {
+  const parsed = path.parse(candidate)
+  for (let attempt = 1; attempt <= 100; attempt += 1) {
+    const name = attempt === 1 ? candidate : `${parsed.name}-${attempt}${parsed.ext}`
+    try {
+      await stat(path.join(dir, name))
+    } catch {
+      return name
+    }
+  }
+  throw new Error('no free attachment file name after 100 attempts')
+}
+
+/** Detect an image extension from the first bytes of a staged file. */
+async function sniffExtension(file: string): Promise<string> {
+  let handle: Awaited<ReturnType<typeof open>> | undefined
+  try {
+    handle = await open(file, 'r')
+    const buffer = Buffer.alloc(16)
+    const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0)
+    const type = sniffImageMediaType(new Uint8Array(buffer.subarray(0, bytesRead)))
+    switch (type) {
+      case 'image/png': return '.png'
+      case 'image/jpeg': return '.jpg'
+      case 'image/webp': return '.webp'
+      case 'image/gif': return '.gif'
+      default: return '.bin'
+    }
+  } catch {
+    return '.bin'
+  } finally {
+    await handle?.close().catch(() => undefined)
+  }
+}