@modesto_ma/dsh-channels 0.0.0-stage → 0.1.0

package/src/feishu-channel.ts

@@ -0,0 +1,339 @@
+/**
+ * Thin wrapper over the official SDK's `createLarkChannel` high-level module.
+ *
+ * The wrapper exists to pin the exact surface the plugin uses behind one
+ * interface so the unit tests can stub the official SDK wholesale (no
+ * network, no creds).
+ *
+ * @module dsh-channels/feishu-channel
+ */
+
+import { createLarkChannel, LoggerLevel } from '@larksuiteoapi/node-sdk'
+import type {
+  BotAddedEvent,
+  ChatInfo,
+  LarkChannel,
+  NormalizedMessage,
+  SendResult,
+  WSConnectionStatus,
+} from '@larksuiteoapi/node-sdk'
+
+export type { BotAddedEvent, ChatInfo, NormalizedMessage, SendResult } from '@larksuiteoapi/node-sdk'
+export type FeishuConnectionStatus = WSConnectionStatus
+
+/** Outbound payloads used by this plugin, including Buffer-backed file upload. */
+export type FeishuSendInput =
+  | { card: object }
+  | { text: string }
+  | { file: { source: string | Buffer; fileName: string } }
+
+/**
+ * One normalized card action (button click) event, as delivered by the
+ * official SDK's `card.action.trigger` handler (card JSON 2.0 callback
+ * behaviors). `messageId` is the card's own message id; `action.value` is the
+ * callback value object the button carried (SDK contract: object values).
+ */
+export interface CardActionEvent {
+  /** Message id of the card the action belongs to. */
+  messageId: string
+  chatId: string
+  operator: { openId: string; userId?: string; name?: string }
+  action: { value: unknown; tag: string; name?: string; option?: string }
+  raw?: unknown
+}
+
+/** The minimal channel surface the plugin consumes. */
+export interface FeishuChannel {
+  /** Bound handler for normalized inbound messages. */
+  onMessage(handler: (message: NormalizedMessage) => void | Promise<void>): () => void
+  /** Bound handler for card button-callback events. */
+  onCardAction(handler: (event: CardActionEvent) => void | Promise<void>): () => void
+  /**
+   * Bound handler for bot-added-to-chat events (`im.chat.member.bot.added_v1`).
+   * Requires the app to subscribe that event; without it the plugin falls
+   * back to the first denied @-mention for group information cards.
+   */
+  onBotAdded(handler: (event: BotAddedEvent) => void | Promise<void>): () => void
+  /** Chat name/owner/member count (needs chat-info read permission). */
+  getChatInfo(chatId: string): Promise<ChatInfo>
+  /** Bot open_id, available after `connect()` resolves. */
+  botOpenId(): string | undefined
+  /** Current official-SDK WebSocket lifecycle snapshot, when initialized. */
+  getConnectionStatus(): FeishuConnectionStatus | undefined
+  /** Start the WebSocket long connection (resolves after the handshake). */
+  connect(): Promise<void>
+  /** Stop the connection. */
+  disconnect(): Promise<void>
+  /** Send one message (text or card) with optional reply targeting. */
+  send(
+    chatId: string,
+    input: FeishuSendInput,
+    options?: { replyTo?: string; replyInThread?: boolean },
+  ): Promise<SendResult>
+  /** Full-card replacement of a previously sent card message. */
+  updateCard(messageId: string, card: object): Promise<void>
+  /** Add an emoji reaction; resolves with the reaction id needed for removal. */
+  addReaction(messageId: string, emojiType: string): Promise<string>
+  /** Remove a reaction previously added by the bot. */
+  removeReaction(messageId: string, reactionId: string): Promise<void>
+  /** Fetch the thread id of a sent message (undefined when not a topic message). */
+  threadIdOfMessage(messageId: string): Promise<string | undefined>
+  /**
+   * Stream one inbound message resource. Files and images share the same
+   * download endpoint; only the `type` query differs. The stream is bounded
+   * chunk-by-chunk so arbitrarily large files never have to fit in memory.
+   */
+  downloadResource(
+    messageId: string,
+    fileKey: string,
+    type: 'image' | 'file',
+  ): Promise<ResourceChunkStream>
+}
+
+/** Ordered byte chunks of one inbound resource. */
+export type ResourceChunkStream = AsyncIterable<Uint8Array>
+
+/**
+ * Chunk size for ranged file downloads. Feishu's message-resource endpoint
+ * rejects a single response larger than 100 MB (error 234037), but honors
+ * bounded Range requests, so large files are fetched in independent chunks.
+ */
+export const RANGE_DOWNLOAD_CHUNK_BYTES = 32 * 1024 * 1024
+
+/** Total object size from a `Content-Range: bytes start-end/total` header. */
+export function contentRangeTotal(headers: unknown): number | undefined {
+  const value = headerValue(headers, 'content-range')
+  if (value === undefined) return undefined
+  const match = /\/(\d+)\s*$/u.exec(value)
+  if (match === null) return undefined
+  const total = Number(match[1])
+  return Number.isSafeInteger(total) && total >= 0 ? total : undefined
+}
+
+/** Case-insensitive header lookup over a plain object or an AxiosHeaders-like getter. */
+function headerValue(headers: unknown, name: string): string | undefined {
+  if (headers === null || typeof headers !== 'object') return undefined
+  const record = headers as Record<string, unknown>
+  const lower = name.toLowerCase()
+  for (const key of Object.keys(record)) {
+    if (key.toLowerCase() !== lower) continue
+    const value = record[key]
+    if (typeof value === 'string') return value
+  }
+  const get = (headers as { get?: (key: string) => unknown }).get
+  if (typeof get === 'function') {
+    const value = get.call(headers, name)
+    return typeof value === 'string' ? value : undefined
+  }
+  return undefined
+}
+
+/** One bounded range request returning the response headers and byte stream. */
+export type ResourceRangeFetcher = (range: string) => Promise<{
+  headers?: unknown
+  stream: AsyncIterable<Uint8Array>
+}>
+
+/**
+ * Download one object through sequential bounded Range requests. The caller
+ * supplies the first response's total size and a fetcher for the remaining
+ * ranges; bytes are yielded as they arrive so the archive writes them
+ * straight to disk.
+ */
+export async function* downloadResourceInRanges(
+  fetchRange: ResourceRangeFetcher,
+  totalBytes: number,
+  chunkBytes = RANGE_DOWNLOAD_CHUNK_BYTES,
+): AsyncGenerator<Uint8Array> {
+  let offset = 0
+  while (offset < totalBytes) {
+    const end = Math.min(offset + chunkBytes, totalBytes) - 1
+    const response = await fetchRange(`bytes=${offset}-${end}`)
+    let received = 0
+    for await (const chunk of response.stream) {
+      received += chunk.length
+      yield chunk
+    }
+    if (received === 0) {
+      throw new Error(`dsh-channels: ranged download stalled at byte ${offset}/${totalBytes}`)
+    }
+    offset += received
+  }
+}
+
+export interface ChannelConnectOptions {
+  appId: string
+  appSecret: string
+  loggerLevel: 'debug' | 'info' | 'warn' | 'error'
+  requireMention: boolean
+  dmMode: 'open' | 'disabled'
+}
+
+class LarkChannelAdapter implements FeishuChannel {
+  private readonly channel: LarkChannel
+  private readonly requireMention: boolean
+  private readonly dmMode: 'open' | 'disabled'
+
+  constructor(options: ChannelConnectOptions) {
+    this.channel = createLarkChannel({
+      appId: options.appId,
+      appSecret: options.appSecret,
+      loggerLevel: LOGGER_LEVELS[options.loggerLevel],
+      // Keep the raw event body: rich-text messages attach files in a
+      // top-level `files` array the SDK normalizer drops, so the attachment
+      // intake recovers them from `msg.raw` instead.
+      includeRawEvent: true,
+      policy: {
+        // The plugin routes mentions itself (thread routing must work without
+        // mention), so the SDK policy layer stays permissive.
+        requireMention: false,
+        dmMode: options.dmMode === 'open' ? 'open' : 'disabled',
+        respondToMentionAll: false,
+      },
+    })
+    this.requireMention = options.requireMention
+    this.dmMode = options.dmMode
+  }
+
+  onMessage(handler: (message: NormalizedMessage) => void | Promise<void>): () => void {
+    return this.channel.on('message', handler)
+  }
+
+  onCardAction(handler: (event: CardActionEvent) => void | Promise<void>): () => void {
+    return this.channel.on('cardAction', handler)
+  }
+
+  onBotAdded(handler: (event: BotAddedEvent) => void | Promise<void>): () => void {
+    // The SDK event handler is synchronous; the plugin's handler is
+    // fire-and-forget (the service wraps it with its own catch/log).
+    return this.channel.on('botAdded', event => {
+      void handler(event)
+    })
+  }
+
+  async getChatInfo(chatId: string): Promise<ChatInfo> {
+    return this.channel.getChatInfo(chatId)
+  }
+
+  botOpenId(): string | undefined {
+    return this.channel.botIdentity?.openId
+  }
+
+  getConnectionStatus(): FeishuConnectionStatus | undefined {
+    return this.channel.getConnectionStatus()
+  }
+
+  async connect(): Promise<void> {
+    await this.channel.connect()
+  }
+
+  async disconnect(): Promise<void> {
+    await this.channel.disconnect()
+  }
+
+  async send(
+    chatId: string,
+    input: FeishuSendInput,
+    options?: { replyTo?: string; replyInThread?: boolean },
+  ): Promise<SendResult> {
+    return this.channel.send(chatId, input, options)
+  }
+
+  async updateCard(messageId: string, card: object): Promise<void> {
+    await this.channel.updateCard(messageId, card)
+  }
+
+  async addReaction(messageId: string, emojiType: string): Promise<string> {
+    return this.channel.addReaction(messageId, emojiType)
+  }
+
+  async removeReaction(messageId: string, reactionId: string): Promise<void> {
+    await this.channel.removeReaction(messageId, reactionId)
+  }
+
+  async threadIdOfMessage(messageId: string): Promise<string | undefined> {
+    const res = await this.channel.rawClient.im.v1.message.get({ path: { message_id: messageId } })
+    return res?.data?.items?.[0]?.thread_id
+  }
+
+  async downloadResource(
+    messageId: string,
+    fileKey: string,
+    type: 'image' | 'file',
+  ): Promise<ResourceChunkStream> {
+    if (type === 'image') {
+      // Images are platform-capped far below the download limit; one request.
+      const response = await this.rawResource(messageId, fileKey, type)
+      return chunkStream(response.stream)
+    }
+    // Probe one byte to learn the total size without triggering the whole-file
+    // size check. Feishu honors a bounded Range request even when the object
+    // is larger than the API's single-response limit.
+    const probe = await this.rawResource(messageId, fileKey, type, 'bytes=0-0')
+    const total = contentRangeTotal(probe.headers)
+    if (total === undefined) {
+      // The server ignored Range and returned the whole object; use it as is.
+      return chunkStream(probe.stream)
+    }
+    ;(probe.stream as { destroy?: () => void }).destroy?.()
+    if (total === 0) {
+      return {
+        async *[Symbol.asyncIterator]() { /* empty resource */ },
+      }
+    }
+    return downloadResourceInRanges(async range => {
+      const response = await this.rawResource(messageId, fileKey, type, range)
+      return { headers: response.headers, stream: chunkStream(response.stream) }
+    }, total)
+  }
+
+  /** One message-resource GET, with an optional Range header. */
+  private async rawResource(
+    messageId: string,
+    fileKey: string,
+    type: 'image' | 'file',
+    range?: string,
+  ): Promise<{ headers: unknown; stream: AsyncIterable<Uint8Array | Buffer> }> {
+    const response = await this.channel.rawClient.im.v1.messageResource.get(
+      { params: { type }, path: { message_id: messageId, file_key: fileKey } },
+      range === undefined ? undefined : { headers: { Range: range } },
+    ) as unknown as { getReadableStream(): AsyncIterable<Uint8Array | Buffer>; headers?: unknown }
+    return { headers: response.headers, stream: response.getReadableStream() }
+  }
+}
+
+/** Wrap one Node stream as a plain byte-chunk iterable. */
+function chunkStream(source: AsyncIterable<Uint8Array | Buffer>): ResourceChunkStream {
+  return {
+    async *[Symbol.asyncIterator]() {
+      for await (const chunk of source) {
+        yield Buffer.isBuffer(chunk) ? new Uint8Array(chunk) : chunk
+      }
+    },
+  }
+}
+
+/**
+ * Detect the raster format from magic bytes. Feishu's resource download does
+ * not hand back a media type, and DSH validates the declared type against the
+ * decoded bytes, so the plugin sniffs instead of trusting the file name.
+ */
+export function sniffImageMediaType(data: Uint8Array): 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif' | undefined {
+  if (data.length >= 8 && data[0] === 0x89 && data[1] === 0x50 && data[2] === 0x4E && data[3] === 0x47) return 'image/png'
+  if (data.length >= 3 && data[0] === 0xFF && data[1] === 0xD8 && data[2] === 0xFF) return 'image/jpeg'
+  if (data.length >= 12 && data[8] === 0x57 && data[9] === 0x45 && data[10] === 0x42 && data[11] === 0x50) return 'image/webp'
+  if (data.length >= 6 && data[0] === 0x47 && data[1] === 0x49 && data[2] === 0x46) return 'image/gif'
+  return undefined
+}
+
+const LOGGER_LEVELS: Record<ChannelConnectOptions['loggerLevel'], LoggerLevel> = {
+  debug: LoggerLevel.debug,
+  info: LoggerLevel.info,
+  warn: LoggerLevel.warn,
+  error: LoggerLevel.error,
+}
+
+/** Factory seam: tests substitute a stub adapter. */
+export type ChannelFactory = (options: ChannelConnectOptions) => FeishuChannel
+
+export const defaultChannelFactory: ChannelFactory = options => new LarkChannelAdapter(options)

package/src/health.ts

@@ -0,0 +1,233 @@
+/**
+ * Privacy-preserving health snapshot and Feishu card rendering.
+ *
+ * The fold consumes only aggregate lifecycle and service-presence signals.
+ * It never accepts configuration values, credentials, fiber errors, or stack
+ * traces, which keeps accidental disclosure out of the rendering boundary.
+ *
+ * @module dsh-channels/health
+ */
+
+import { CordisFiberState } from './dsh-types.ts'
+import type { CordisFiber } from './dsh-types.ts'
+import type { FeishuConnectionStatus } from './feishu-channel.ts'
+import { standaloneCard } from './cards/primitives.ts'
+
+export const HEALTH_DEPENDENCY_NAMES = [
+  'agents',
+  'commands',
+  'workspace',
+  'storage',
+  'credentials',
+  'llm',
+  'token-meter',
+] as const
+
+export type HealthDependencyName = typeof HEALTH_DEPENDENCY_NAMES[number]
+export type HealthLevel = 'healthy' | 'degraded' | 'unhealthy'
+
+export interface FiberHealthCounts {
+  active: number
+  pending: number
+  loading: number
+  failed: number
+  unloading: number
+}
+
+/** States that make the Fold report something other than healthy. */
+export type FiberIssueState = 'pending' | 'loading' | 'unloading' | 'failed'
+
+/** One non-active fiber with a best-effort plugin name (no errors/stacks). */
+export interface FiberHealthIssue {
+  state: FiberIssueState
+  label: string
+}
+
+/** Upper bound on the diagnostic list; counts still include every fiber. */
+const MAX_INACTIVE_FIBERS = 12
+
+export interface HealthSnapshotInput {
+  fibers: Iterable<CordisFiber>
+  dependencies: Readonly<Record<HealthDependencyName, boolean>>
+  connection?: FeishuConnectionStatus
+  botOpenId?: string
+  started: boolean
+  routeCount: number
+  liveAgentCount: number
+  inflightTurnCount: number
+}
+
+export interface HealthSnapshot extends Omit<HealthSnapshotInput, 'fibers' | 'botOpenId'> {
+  level: HealthLevel
+  fibers: FiberHealthCounts
+  /** Masked display only; the complete open_id never crosses this boundary. */
+  botOpenIdTail?: string
+  /** Non-active plugin fibers (capped at MAX_INACTIVE_FIBERS), diagnostics only. */
+  inactiveFibers: FiberHealthIssue[]
+  /** Total non-active fibers, including those beyond the capped list. */
+  inactiveTotal: number
+  /** Human-readable explanation of `level`; empty when healthy. */
+  reasons: string[]
+}
+
+/** Best-effort label for a fiber: Cordis exposes the plugin display name on the fiber. */
+function fiberLabel(fiber: CordisFiber): string {
+  const name = fiber.name?.trim()
+  return name !== undefined && name !== '' ? name : '(未命名插件)'
+}
+
+/** One pass over the fiber table: state counts plus the non-active diagnostics. */
+function foldFiberStates(fibers: Iterable<CordisFiber>): {
+  counts: FiberHealthCounts
+  inactive: FiberHealthIssue[]
+  inactiveTotal: number
+} {
+  const counts: FiberHealthCounts = { active: 0, pending: 0, loading: 0, failed: 0, unloading: 0 }
+  const inactive: FiberHealthIssue[] = []
+  let inactiveTotal = 0
+  for (const fiber of fibers) {
+    const issueState: FiberIssueState | undefined =
+      fiber.state === CordisFiberState.PENDING ? 'pending'
+        : fiber.state === CordisFiberState.LOADING ? 'loading'
+          : fiber.state === CordisFiberState.UNLOADING ? 'unloading'
+            : fiber.state === CordisFiberState.FAILED ? 'failed'
+              : undefined
+    if (fiber.state === CordisFiberState.ACTIVE) {
+      counts.active++
+      continue
+    }
+    if (issueState === undefined) continue // disposed fibers are not health signals
+    counts[issueState === 'pending' ? 'pending' : issueState === 'loading' ? 'loading' : issueState === 'unloading' ? 'unloading' : 'failed']++
+    inactiveTotal++
+    if (inactive.length < MAX_INACTIVE_FIBERS) inactive.push({ state: issueState, label: fiberLabel(fiber) })
+  }
+  return { counts, inactive, inactiveTotal }
+}
+
+/** Fold every non-disposed Cordis fiber into the five product-facing states. */
+export function countFiberStates(fibers: Iterable<CordisFiber>): FiberHealthCounts {
+  return foldFiberStates(fibers).counts
+}
+
+/** Human-readable connection state for diagnostics (keeps raw states visible). */
+function connectionReason(state: string | undefined): string {
+  switch (state) {
+    case 'connected': return '已连接'
+    case 'connecting': return '连接中'
+    case 'reconnecting': return '重连中'
+    case 'failed': return '连接失败'
+    case 'idle': return '空闲（未连接）'
+    default: return state ?? '未知'
+  }
+}
+
+function labelList(labels: readonly string[], total: number, max = 6): string {
+  if (labels.length === 0) return ''
+  const shown = labels.slice(0, max).join('、')
+  return total > Math.min(labels.length, max) ? `${shown} 等 ${total} 个` : shown
+}
+
+/** Reveal only the final four characters, and nothing for unusually short ids. */
+export function maskOpenIdTail(openId?: string): string | undefined {
+  if (openId === undefined || openId.length <= 4) return undefined
+  return `…${openId.slice(-4)}`
+}
+
+/** One deterministic fold owns both the snapshot and its overall conclusion. */
+export function foldHealthSnapshot(input: HealthSnapshotInput): HealthSnapshot {
+  const { counts: fibers, inactive, inactiveTotal } = foldFiberStates(input.fibers)
+  const missingDependencies = HEALTH_DEPENDENCY_NAMES.filter(name => !input.dependencies[name])
+  const dependencyMissing = missingDependencies.length > 0
+  const connectionState = input.connection?.state
+
+  let level: HealthLevel
+  if (!input.started || dependencyMissing || connectionState === 'failed' || fibers.failed > 0) {
+    level = 'unhealthy'
+  } else if (
+    connectionState !== 'connected'
+    || fibers.pending > 0
+    || fibers.loading > 0
+    || fibers.unloading > 0
+  ) {
+    level = 'degraded'
+  } else {
+    level = 'healthy'
+  }
+
+  const reasons: string[] = []
+  if (!input.started) reasons.push('飞书通道尚未启动')
+  if (dependencyMissing) reasons.push(`主机服务未就绪：${missingDependencies.join('、')}`)
+  if (input.connection === undefined) reasons.push('飞书长连接尚未建立')
+  else if (connectionState === 'failed') reasons.push('飞书长连接失败')
+  else if (connectionState !== 'connected') reasons.push(`飞书长连接状态：${connectionReason(connectionState)}`)
+
+  const failedLabels = inactive.filter(issue => issue.state === 'failed').map(issue => issue.label)
+  if (fibers.failed > 0) {
+    reasons.push(`插件加载失败 ${fibers.failed} 个${failedLabels.length === 0 ? '' : `：${labelList(failedLabels, fibers.failed)}`}`)
+  }
+  const stalled = fibers.pending + fibers.loading + fibers.unloading
+  if (stalled > 0) {
+    const stalledLabels = inactive
+      .filter(issue => issue.state === 'pending' || issue.state === 'loading' || issue.state === 'unloading')
+      .map(issue => issue.label)
+    reasons.push(
+      `宿主其它插件仍有 ${stalled} 个入口在等待依赖或加载/卸载（与飞书通道无关）`
+      + (stalledLabels.length === 0 ? '' : `：${labelList(stalledLabels, stalled)}`),
+    )
+  }
+
+  return {
+    level,
+    fibers,
+    dependencies: input.dependencies,
+    connection: input.connection,
+    botOpenIdTail: maskOpenIdTail(input.botOpenId),
+    started: input.started,
+    routeCount: input.routeCount,
+    liveAgentCount: input.liveAgentCount,
+    inflightTurnCount: input.inflightTurnCount,
+    inactiveFibers: inactive,
+    inactiveTotal,
+    reasons,
+  }
+}
+
+const LEVEL_PRESENTATION: Record<HealthLevel, { icon: string; title: string }> = {
+  healthy: { icon: '✅', title: '运行健康' },
+  degraded: { icon: '⚠️', title: '运行降级' },
+  unhealthy: { icon: '❌', title: '运行异常' },
+}
+
+function formatTimestamp(timestamp?: number): string {
+  if (timestamp === undefined || !Number.isFinite(timestamp)) return '—'
+  const date = new Date(timestamp)
+  return Number.isNaN(date.getTime()) ? '—' : date.toISOString()
+}
+
+/** Render a standalone non-streaming health card from the sanitized snapshot. */
+export function buildHealthCard(snapshot: HealthSnapshot): object {
+  const presentation = LEVEL_PRESENTATION[snapshot.level]
+  const dependencyLine = HEALTH_DEPENDENCY_NAMES
+    .map(name => `${snapshot.dependencies[name] ? '✅' : '❌'} ${name}`)
+    .join(' · ')
+  const connection = snapshot.connection
+  const connectionState = connection?.state ?? 'unknown'
+
+  return standaloneCard(`**${presentation.icon} 健康检查 · ${presentation.title}**`, [
+    { tag: 'markdown', content: `整体结论：**${snapshot.level}**` },
+    { tag: 'hr' },
+    {
+      tag: 'markdown',
+      content: `**Harness fibers**\nactive ${snapshot.fibers.active} · pending ${snapshot.fibers.pending} · loading ${snapshot.fibers.loading} · failed ${snapshot.fibers.failed} · unloading ${snapshot.fibers.unloading}`,
+    },
+    { tag: 'markdown', content: `**关键依赖**\n${dependencyLine}` },
+    {
+      tag: 'markdown',
+      content: `**飞书 WebSocket**\n${connectionState} · 最近连接 ${formatTimestamp(connection?.lastConnectTime)} · 下次重连 ${formatTimestamp(connection?.nextConnectTime)} · 重连次数 ${connection?.reconnectAttempts ?? 0} · bot open_id ${snapshot.botOpenIdTail ?? '—'}`,
+    },
+    {
+      tag: 'markdown',
+      content: `**dsh-channels**\n${snapshot.started ? 'started' : 'stopped'} · 持久化路由 ${snapshot.routeCount} · live Agent ${snapshot.liveAgentCount} · in-flight turn ${snapshot.inflightTurnCount}`,
+    },
+  ])
+}