@dcrays/dcgchat-test 0.6.1 → 0.6.2

package/src/utils/sessionTermination.ts

@@ -0,0 +1,228 @@
+/**
+ * 会话终止 / 抢占 / 网关 abort 的集中实现，便于单独调整策略与观测。
+ * 与 inboundTurnState（generation / streamChunkIdx）、入站业务上下文分离，仅负责：本地 AbortController、流抑制标记、
+ * 入站串行队尾、activeRunId、以及 /stop control barrier 时的 chat.abort（子会话→主会话）。
+ */
+import { sendGatewayRpc } from '../gateway/socket.js'
+import { dcgLogger } from './log.js'
+import { bumpInboundGeneration, bumpStopSeq, clearInboundGenerationForSession, getStopSeq } from './inboundTurnState.js'
+import { getDescendantSessionKeysForRequester, resetSubagentStateForRequesterSession, cleanupSubagentStateForSession } from '../tool.js'
+import { clearParamsMessage } from './params.js'
+import { setMsgStatus } from './global.js'
+import { clearOutboundTextState } from './outboundAssistantText.js'
+
+// 缩短超时时间，避免长时间阻塞
+const GATEWAY_ABORT_TIMEOUT_MS = 5_000
+
+// --- 状态（仅本模块内修改，供 bot 通过下方 API 使用）---
+
+/** 当前会话最近一次 agent run 的 runId（网关 chat.abort 主会话时携带） */
+const activeRunIdBySessionKey = new Map<string, string>()
+
+/** dispatchReplyFromConfig 使用的 AbortSignal，用于真正掐断工具与模型 */
+const dispatchAbortBySessionKey = new Map<string, AbortController>()
+
+/** 打断后抑制 deliver / onPartialReply 继续下发 */
+const sessionStreamSuppressed = new Set<string>()
+
+/**
+ * 同 sessionKey 入站串行队尾；与 Core session lane 对齐，避免并发 dispatch 过早返回。
+ */
+const inboundTurnTailBySessionKey = new Map<string, Promise<void>>()
+
+/** 当前 session 正在执行的 /stop 终止屏障；普通消息必须等它结束后再进入新 turn。 */
+const stopBarrierBySessionKey = new Map<string, Promise<void>>()
+
+// --- activeRunId（供 bot 在 onAgentRunStart / 错误收尾时同步）---
+
+export function setActiveRunIdForSession(sessionKey: string, runId: string): void {
+  activeRunIdBySessionKey.set(sessionKey, runId)
+}
+
+export function clearActiveRunIdForSession(sessionKey: string): void {
+  activeRunIdBySessionKey.delete(sessionKey)
+}
+
+// --- 流抑制 ---
+
+export function isSessionStreamSuppressed(sessionKey: string): boolean {
+  return sessionStreamSuppressed.has(sessionKey)
+}
+
+export function clearSessionStreamSuppression(sessionKey: string): void {
+  sessionStreamSuppressed.delete(sessionKey)
+}
+
+export function markSessionStreamSuppressed(sessionKey: string): void {
+  sessionStreamSuppressed.add(sessionKey)
+}
+
+// --- 入站串行队列 ---
+
+/**
+ * /stop control path：掐断当前 in-process，等待网关 chat.abort（子会话→主会话）完成后再释放普通消息。
+ *
+ * 返回 started=false 表示已有同 session 的 stop barrier 在跑；调用方仍应给当前 /stop 消息立即 ack。
+ */
+export function requestStopInterruption(sessionKey: string): { started: boolean; barrier: Promise<void> } {
+  const key = sessionKey.trim()
+  if (!key) return { started: false, barrier: Promise.resolve() }
+
+  const existing = stopBarrierBySessionKey.get(key)
+  if (existing) {
+    dcgLogger(`stop barrier already running sessionKey=${key}`)
+    return { started: false, barrier: existing }
+  }
+
+  let barrier!: Promise<void>
+  barrier = Promise.resolve().then(async () => {
+    try {
+      const c = dispatchAbortBySessionKey.get(key)
+      if (c) {
+        c.abort()
+        dispatchAbortBySessionKey.delete(key)
+        dcgLogger(`stop barrier: aborted local controller sessionKey=${key}`)
+      }
+
+      markSessionStreamSuppressed(key)
+      const inboundGenAfterBump = bumpInboundGeneration(key)
+      const stopSeqAfterBump = bumpStopSeq(key)
+      dcgLogger(`stop barrier: bump inboundGen=${inboundGenAfterBump}, stopSeq=${stopSeqAfterBump}, sessionKey=${key}`)
+
+      const oldTail = inboundTurnTailBySessionKey.get(key)
+      if (oldTail) {
+        await Promise.race([oldTail.catch(() => {}), new Promise<void>((r) => setTimeout(r, 100))])
+        dcgLogger(`stop barrier: old tail done/timeout sessionKey=${key}`)
+      }
+
+      try {
+        await abortGatewayRunsForSession(key)
+      } catch (e) {
+        dcgLogger(`stop barrier: gateway abort: ${String(e)}`, 'error')
+      }
+
+      inboundTurnTailBySessionKey.set(key, Promise.resolve())
+      dcgLogger(`stop barrier: released inbound queue sessionKey=${key}`)
+    } finally {
+      if (stopBarrierBySessionKey.get(key) === barrier) {
+        stopBarrierBySessionKey.delete(key)
+      }
+    }
+  })
+
+  stopBarrierBySessionKey.set(key, barrier)
+  return { started: true, barrier }
+}
+
+/** 普通入站消息进入队列前调用，保证 /stop 的 gateway abort 已完成或超时。 */
+export async function waitForStopInterruption(sessionKey: string): Promise<void> {
+  const key = sessionKey.trim()
+  if (!key) return
+  for (;;) {
+    const barrier = stopBarrierBySessionKey.get(key)
+    if (!barrier) return
+    dcgLogger(`waiting stop barrier before inbound turn sessionKey=${key}`)
+    await barrier.catch((e) => dcgLogger(`stop barrier wait failed: ${String(e)}`, 'error'))
+  }
+}
+
+/** 将本轮入站处理挂到 sessionKey 队尾，保证同会话顺序执行 */
+export async function runInboundTurnSequenced(sessionKey: string, run: () => Promise<void>): Promise<void> {
+  const prev = inboundTurnTailBySessionKey.get(sessionKey) ?? Promise.resolve()
+
+  const next = prev.catch(() => {}).then(() => run())
+
+  inboundTurnTailBySessionKey.set(
+    sessionKey,
+    next.catch((e) => dcgLogger(`session turn failed: ${String(e)}`, 'error'))
+  )
+  await next
+}
+
+// --- 网关 abort ---
+
+/**
+ * 终止网关上仍可能活跃的 run（子会话自深到浅，再主会话）。
+ * 主会话始终 chat.abort；有 mainRunId 则按 run 掐断，无则仅用 sessionKey 扫尾。
+ */
+export async function abortGatewayRunsForSession(sessionKey: string): Promise<void> {
+  const prefix = 'interrupt'
+  const descendantKeys = getDescendantSessionKeysForRequester(sessionKey)
+  const abortSubKeys = [...descendantKeys].reverse()
+  const mainRunId = activeRunIdBySessionKey.get(sessionKey)
+
+  if (abortSubKeys.length > 0) {
+    dcgLogger(`${prefix}: chat.abort ${abortSubKeys.length} subagent session(s) (nested incl.)`)
+  }
+
+  const abortAllSequentially = async () => {
+    // 按“先子后主”顺序终止，降低主会话先结束导致子会话残留事件的概率。
+    for (const subKey of abortSubKeys) {
+      try {
+        await sendGatewayRpc({ method: 'chat.abort', params: { sessionKey: subKey } })
+      } catch (e: unknown) {
+        dcgLogger(`${prefix}: chat.abort subagent ${subKey}: ${String(e)}`, 'error')
+      }
+    }
+    try {
+      await sendGatewayRpc({
+        method: 'chat.abort',
+        params: mainRunId ? { sessionKey, runId: mainRunId } : { sessionKey }
+      })
+    } catch (e: unknown) {
+      dcgLogger(`${prefix}: chat.abort main ${sessionKey}: ${String(e)}`, 'error')
+    }
+  }
+
+  try {
+    await Promise.race([
+      abortAllSequentially(),
+      new Promise<void>((_, reject) => setTimeout(() => reject(new Error('batch abort timeout')), GATEWAY_ABORT_TIMEOUT_MS))
+    ])
+  } catch (e) {
+    dcgLogger(`${prefix}: batch abort timeout: ${String(e)}`, 'error')
+  }
+
+  activeRunIdBySessionKey.delete(sessionKey)
+  resetSubagentStateForRequesterSession(sessionKey)
+}
+
+// --- 本地 dispatch AbortController ---
+
+/**
+ * 新一轮非 /stop 用户消息：本地中止上一轮 AbortController（若有）、清除流抑制，并安装本轮 AbortController。
+ * 不在此处发往网关 chat.abort；每轮流式由入站串行保证先后，网关 run 收尾由上一轮正常完结或用户 /stop 处理。
+ * 调用方须在之前或之后自行 `resetStreamChunkIdxForSession(sessionKey, 0)`（见 inboundTurnState）。
+ */
+export function beginDispatchAbortForInboundTurn(sessionKey: string): AbortController {
+  dispatchAbortBySessionKey.get(sessionKey)?.abort()
+  sessionStreamSuppressed.delete(sessionKey)
+  const ac = new AbortController()
+  dispatchAbortBySessionKey.set(sessionKey, ac)
+  return ac
+}
+
+/** try/finally 中：仅当仍是当前 controller 时从 map 移除 */
+export function releaseDispatchAbortIfCurrent(sessionKey: string, controller: AbortController | undefined): void {
+  if (controller && dispatchAbortBySessionKey.get(sessionKey) === controller) {
+    dispatchAbortBySessionKey.delete(sessionKey)
+  }
+}
+
+/**
+ * 会话完全终止时的资源清理：移除本模块及 tool 模块中与该会话相关的所有状态，
+ * 防止 Map/Set 内存泄漏。
+ */
+export function cleanupTerminatedSession(sessionKey: string): void {
+  if (!sessionKey) return
+  activeRunIdBySessionKey.delete(sessionKey)
+  dispatchAbortBySessionKey.delete(sessionKey)
+  sessionStreamSuppressed.delete(sessionKey)
+  inboundTurnTailBySessionKey.delete(sessionKey)
+  stopBarrierBySessionKey.delete(sessionKey)
+  clearInboundGenerationForSession(sessionKey)
+  clearParamsMessage(sessionKey)
+  setMsgStatus(sessionKey, '')
+  clearOutboundTextState(sessionKey)
+  cleanupSubagentStateForSession(sessionKey)
+}

package/src/utils/streamMerge.ts

@@ -0,0 +1,150 @@
+import type { IMsgParams } from '../types.js'
+import { sendChunk } from '../transport.js'
+import { getWsConnection } from './global.js'
+import { isSessionStreamSuppressed } from './sessionTermination.js'
+import { getInboundGeneration, takeStreamChunkIdxAndAdvance } from './inboundTurnState.js'
+
+export const STREAM_MERGE_PROFILES = [
+  { maxAvgDeltaGapMs: 20, flushIntervalMs: 50, deltaCount: 20, charCount: 100 },
+  { maxAvgDeltaGapMs: 60, flushIntervalMs: 30, deltaCount: 15, charCount: 60 },
+  { maxAvgDeltaGapMs: Number.POSITIVE_INFINITY, flushIntervalMs: 20, deltaCount: 6, charCount: 30 }
+] as const
+
+export const STREAM_MERGE_ENABLE_WINDOW_MS = 1000
+export const STREAM_MERGE_ENABLE_DELTA_COUNT = 50
+export const STREAM_MERGE_IDLE_RESET_MS = 300
+export const STREAM_BACKPRESSURE_HIGH_WATERMARK = 512 * 1024
+export const STREAM_BACKPRESSURE_RETRY_MS = 50
+
+export interface StreamMergeController {
+  queueDelta(delta: string): boolean
+  flush(force?: boolean): boolean
+  dispose(): void
+}
+
+export interface CreateStreamMergeControllerOptions {
+  sessionKey: string
+  inboundGenAtStart: number
+  outboundCtx: IMsgParams
+}
+
+export function createStreamMergeController(
+  options: CreateStreamMergeControllerOptions
+): StreamMergeController {
+  const { sessionKey, inboundGenAtStart, outboundCtx } = options
+
+  let pendingText = ''
+  let pendingDeltaCount = 0
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let mergeMode = false
+  let burstWindowStart = 0
+  let burstDeltaCount = 0
+  let lastDeltaAt = 0
+  let deltaGapAvgMs = 0
+
+  const clearTimer = () => {
+    if (timer) {
+      clearTimeout(timer)
+      timer = undefined
+    }
+  }
+
+  const isBackpressured = () => (getWsConnection()?.bufferedAmount ?? 0) > STREAM_BACKPRESSURE_HIGH_WATERMARK
+
+  const currentProfile = () =>
+    STREAM_MERGE_PROFILES.find((profile) => deltaGapAvgMs <= profile.maxAvgDeltaGapMs) ?? STREAM_MERGE_PROFILES[1]
+
+  const isStale = () =>
+    getInboundGeneration(sessionKey) !== inboundGenAtStart || isSessionStreamSuppressed(sessionKey)
+
+  const emit = (text: string) => sendChunk(text, outboundCtx, takeStreamChunkIdxAndAdvance(sessionKey))
+
+  const resetMerge = () => {
+    mergeMode = false
+    burstWindowStart = 0
+    burstDeltaCount = 0
+    deltaGapAvgMs = 0
+  }
+
+  const flush = (force = false): boolean => {
+    clearTimer()
+    if (!pendingText.trim()) {
+      pendingText = ''
+      pendingDeltaCount = 0
+      return false
+    }
+    if (isStale()) {
+      pendingText = ''
+      pendingDeltaCount = 0
+      return false
+    }
+    if (!force && isBackpressured()) {
+      scheduleFlush(STREAM_BACKPRESSURE_RETRY_MS)
+      return false
+    }
+    const textToSend = pendingText
+    pendingText = ''
+    pendingDeltaCount = 0
+    return emit(textToSend)
+  }
+
+  const scheduleFlush = (delayMs = currentProfile().flushIntervalMs) => {
+    if (timer) return
+    timer = setTimeout(() => flush(), delayMs)
+  }
+
+  const queueDelta = (delta: string): boolean => {
+    const now = Date.now()
+    const deltaGapMs = lastDeltaAt > 0 ? now - lastDeltaAt : 0
+
+    if (lastDeltaAt > 0 && deltaGapMs >= STREAM_MERGE_IDLE_RESET_MS) {
+      flush(true)
+      resetMerge()
+    }
+
+    if (deltaGapMs > 0) {
+      deltaGapAvgMs = deltaGapAvgMs === 0 ? deltaGapMs : deltaGapAvgMs * 0.7 + deltaGapMs * 0.3
+    }
+    lastDeltaAt = now
+
+    if (!mergeMode) {
+      if (burstWindowStart === 0 || now - burstWindowStart > STREAM_MERGE_ENABLE_WINDOW_MS) {
+        burstWindowStart = now
+        burstDeltaCount = 1
+      } else {
+        burstDeltaCount += 1
+      }
+
+      pendingText += delta
+      pendingDeltaCount += 1
+      flush()
+
+      if (burstDeltaCount >= STREAM_MERGE_ENABLE_DELTA_COUNT) {
+        mergeMode = true
+      }
+      return true
+    }
+
+    pendingText += delta
+    pendingDeltaCount += 1
+    const profile = currentProfile()
+    if (pendingText.length >= profile.charCount || pendingDeltaCount >= profile.deltaCount) {
+      flush()
+      return true
+    }
+    scheduleFlush()
+    return true
+  }
+
+  const dispose = () => {
+    clearTimer()
+    pendingText = ''
+    pendingDeltaCount = 0
+  }
+
+  return {
+    queueDelta,
+    flush,
+    dispose
+  }
+}

package/src/utils/subagentRunMap.ts

@@ -0,0 +1,71 @@
+const requesterSessionKeyByRunId = new Map<string, string>()
+const childSessionKeyByRunId = new Map<string, string>()
+
+export type SubagentRunMapSnapshot = {
+  requesterSessionKeyByRunId?: Array<[string, string]>
+  childSessionKeyByRunId?: Array<[string, string]>
+}
+
+export function setSubagentRunRequester(runId: string | undefined, requesterSessionKey: string | undefined): void {
+  const rid = runId?.trim()
+  const req = requesterSessionKey?.trim()
+  if (!rid || !req) return
+  requesterSessionKeyByRunId.set(rid, req)
+}
+
+export function setSubagentRunChild(runId: string | undefined, childSessionKey: string | undefined): void {
+  const rid = runId?.trim()
+  const child = childSessionKey?.trim()
+  if (!rid || !child) return
+  childSessionKeyByRunId.set(rid, child)
+}
+
+export function deleteSubagentRunMappings(runId: string | undefined): void {
+  const rid = runId?.trim()
+  if (!rid) return
+  requesterSessionKeyByRunId.delete(rid)
+  childSessionKeyByRunId.delete(rid)
+}
+
+export function clearSubagentRunMappings(): void {
+  requesterSessionKeyByRunId.clear()
+  childSessionKeyByRunId.clear()
+}
+
+export function resolveRequesterSessionKeyBySubagentRunId(runId: string | undefined): string | undefined {
+  const rid = runId?.trim()
+  if (!rid) return undefined
+  return requesterSessionKeyByRunId.get(rid)
+}
+
+export function resolveChildSessionKeyBySubagentRunId(runId: string | undefined): string | undefined {
+  const rid = runId?.trim()
+  if (!rid) return undefined
+  return childSessionKeyByRunId.get(rid)
+}
+
+export function cleanupSubagentRunMappingsForSessionKeys(sessionKeys: Set<string>): void {
+  for (const [rid, child] of childSessionKeyByRunId.entries()) {
+    if (sessionKeys.has(child)) deleteSubagentRunMappings(rid)
+  }
+  for (const [rid, requester] of requesterSessionKeyByRunId.entries()) {
+    if (sessionKeys.has(requester)) deleteSubagentRunMappings(rid)
+  }
+}
+
+export function snapshotSubagentRunMappings(): SubagentRunMapSnapshot {
+  return {
+    requesterSessionKeyByRunId: [...requesterSessionKeyByRunId.entries()],
+    childSessionKeyByRunId: [...childSessionKeyByRunId.entries()]
+  }
+}
+
+export function restoreSubagentRunMappings(snap: SubagentRunMapSnapshot | null | undefined): void {
+  clearSubagentRunMappings()
+  for (const [k, v] of snap?.requesterSessionKeyByRunId ?? []) {
+    if (typeof k === 'string' && typeof v === 'string' && k && v) requesterSessionKeyByRunId.set(k, v)
+  }
+  for (const [k, v] of snap?.childSessionKeyByRunId ?? []) {
+    if (typeof k === 'string' && typeof v === 'string' && k && v) childSessionKeyByRunId.set(k, v)
+  }
+}

package/src/utils/workspaceFilePaths.ts

@@ -0,0 +1,18 @@
+import os from 'node:os'
+import path from 'node:path'
+
+/**
+ * 将正文里的 `~/...` / `~\...` 展开为绝对路径（`path.resolve` 不会处理 `~`）。
+ */
+export function expandTildePath(input: string): string {
+  const s = input.trim()
+  if (!s) return s
+  if (s === '~') return os.homedir()
+  if (s.startsWith('~/')) {
+    return path.resolve(os.homedir(), s.slice(2))
+  }
+  if (s.startsWith('~\\')) {
+    return path.resolve(os.homedir(), s.slice(2))
+  }
+  return s
+}

package/src/utils/wsMessageHandler.ts

@@ -0,0 +1,124 @@
+import { handleDcgchatMessage } from '../bot.js'
+import { setMsgStatus, getSessionKey } from './global.js'
+import type { InboundMessage } from '../types.js'
+import { installSkill, uninstallSkill } from '../skill.js'
+import { dcgLogger } from './log.js'
+import { onDisabledCronJob, onEnabledCronJob, onRemoveCronJob, onRunCronJob } from '../cron/message.js'
+import { ignoreToolCommand } from './constant.js'
+import { createAgent, onRemoveAgent, onUpdateAgent } from '../agent.js'
+import { onRemoveSession } from '../session.js'
+
+interface WsEventContent {
+  event_type?: string
+  operation_type?: string
+  skill_url?: string
+  skill_code?: string
+  skill_id?: string
+  bot_token?: string
+  websocket_trace_id?: string
+  job_id?: string
+  message_id?: string
+  agent_id?: string
+  session_id?: string
+  agent_clone_code?: string
+  url?: string
+  clone_code?: string
+  name?: string
+  description?: string
+  [key: string]: unknown
+}
+
+export type ParsedWsPayload = {
+  messageType?: string
+  content: WsEventContent | null
+}
+
+function logUnsupportedOpenclawBotEvent(
+  branch: 'skill' | 'agent',
+  eventType: string,
+  operationType: unknown,
+  rawPayload: string
+): void {
+  dcgLogger(
+    `openclaw_bot_event ${branch}: unsupported operation_type=${String(operationType)} (event_type=${eventType}), ${rawPayload}`,
+    'error'
+  )
+}
+
+/**
+ * 处理 WebSocket 已解析 JSON 且 content 已二次 parse 后的业务消息（openclaw_bot_chat / openclaw_bot_event）。
+ */
+export async function handleParsedWsMessage(parsed: ParsedWsPayload, rawPayload: string, accountId: string): Promise<void> {
+  if (parsed.messageType === 'openclaw_bot_chat') {
+    const msg = parsed as unknown as InboundMessage
+    // 与 monitor 原逻辑一致：工具类指令不进入 running，避免误触工具链监控
+    const effectiveSessionKey = getSessionKey(msg.content, accountId)
+    const isToolOnly = ignoreToolCommand.includes(msg.content.text?.trim() ?? '')
+    if (!isToolOnly) {
+      setMsgStatus(effectiveSessionKey, 'running')
+    } else {
+      setMsgStatus(effectiveSessionKey, 'finished')
+    }
+    try {
+      await handleDcgchatMessage(msg, accountId)
+    } catch (err) {
+      dcgLogger(`handleDcgchatMessage failed: ${String(err)}`, 'error')
+      if (!isToolOnly) {
+        setMsgStatus(effectiveSessionKey, '')
+      }
+      // 不再向上 throw：否则 async onMessage 未接住的 rejection 会触发 Unhandled promise rejection
+    }
+  } else if (parsed.messageType === 'openclaw_bot_event') {
+    if (!parsed.content) {
+      dcgLogger(`openclaw_bot_event: content is null, ${rawPayload}`, 'error')
+      return
+    }
+    const { event_type, operation_type } = parsed.content
+    if (event_type === 'skill') {
+      const { skill_url = '', skill_code = '', skill_id, bot_token, websocket_trace_id } = parsed.content
+      const content = { event_type, operation_type, skill_url, skill_code, skill_id, bot_token, websocket_trace_id }
+      if (operation_type === 'install' || operation_type === 'enable' || operation_type === 'update') {
+        installSkill({ path: skill_url, code: skill_code }, content)
+      } else if (operation_type === 'remove' || operation_type === 'disable') {
+        uninstallSkill({ code: skill_code }, content)
+      } else {
+        logUnsupportedOpenclawBotEvent('skill', event_type, operation_type, rawPayload)
+      }
+    } else if (event_type === 'agent') {
+      if (operation_type === 'create') {
+        await createAgent(parsed.content)
+      } else if (operation_type === 'remove') {
+        await onRemoveAgent(parsed.content)
+      } else if (operation_type === 'update') {
+        await onUpdateAgent(parsed.content)
+      } else {
+        logUnsupportedOpenclawBotEvent('agent', event_type, operation_type, rawPayload)
+      }
+    } else if (event_type === 'cron') {
+      const { job_id = '', message_id = '' } = parsed.content
+      if (operation_type === 'remove') {
+        await onRemoveCronJob(job_id)
+      } else if (operation_type === 'enable') {
+        await onEnabledCronJob(job_id)
+      } else if (operation_type === 'disable') {
+        await onDisabledCronJob(job_id)
+      } else if (operation_type === 'run') {
+        await onRunCronJob(job_id, message_id)
+      } else {
+        dcgLogger(`openclaw_bot_event cron: unsupported operation_type=${String(operation_type)}, ${rawPayload}`, 'error')
+      }
+    } else if (event_type === 'session') {
+      const { agent_id = '', session_id = '', agent_clone_code } = parsed.content
+      if (operation_type === 'remove') {
+        await onRemoveSession({ agent_id, session_id, agent_clone_code, account_id: accountId })
+      }
+    } else {
+      dcgLogger(
+        `openclaw_bot_event: unknown event_type=${String(event_type)}, operation_type=${String(operation_type)}, ${rawPayload}`,
+        'error'
+      )
+    }
+  } else {
+    dcgLogger(`ignoring unknown messageType: ${parsed.messageType}`, 'error')
+  }
+}

package/src/utils/zipExtract.ts

@@ -0,0 +1,97 @@
+import path from 'path'
+import fs from 'fs'
+/** @ts-ignore */
+import unzipper from 'unzipper'
+import { pipeline } from 'stream/promises'
+import { decodeZipEntryPath } from './zipPath.js'
+
+/**
+ * 若且唯若所有条目都在同一顶层目录下（如 GitHub 下载的 repo-name/...），返回该目录名；否则返回 null。
+ * 不能再用「第一个多段路径的第一段」推断，否则 ZIP 条目顺序变化时会误判（例如先出现 .github/ 或 src/）。
+ */
+export function computeSharedZipRootPrefix(decodedPaths: string[]): string | null {
+  const normalized = decodedPaths
+    .map((p) => p.replace(/\\/g, '/').replace(/\/+$/, ''))
+    .filter((p) => p.length > 0)
+
+  if (normalized.length === 0) return null
+
+  const firstSegs = new Set<string>()
+  for (const p of normalized) {
+    const seg = p.split('/').filter(Boolean)[0]
+    if (seg) firstSegs.add(seg)
+  }
+  if (firstSegs.size !== 1) return null
+
+  const root = [...firstSegs][0]!
+  const prefix = `${root}/`
+  for (const p of normalized) {
+    if (p !== root && !p.startsWith(prefix)) return null
+  }
+  return root
+}
+
+function assertSafeZipTarget(destDir: string, relativePath: string): string {
+  const resolvedPath = path.resolve(destDir, relativePath)
+  const resolvedDest = path.resolve(destDir)
+  const rel = path.relative(resolvedDest, resolvedPath)
+  if (rel.startsWith('..') || path.isAbsolute(rel)) {
+    throw new Error(`zip 路径越界: ${relativePath}`)
+  }
+  return resolvedPath
+}
+
+type ZipEntry = {
+  path: string
+  pathBuffer: Buffer
+  flags: number
+  type: string
+  stream: (password?: string) => NodeJS.ReadableStream
+}
+
+/**
+ * 将已下载的 zip 解压到 destDir；顶层单根目录（若存在）会被剥掉，与原先流式 Parse 行为一致，但根目录由全量路径计算，与条目顺序无关。
+ */
+export async function extractZipBufferToDirectory(buf: Buffer, destDir: string): Promise<void> {
+  const directory = await unzipper.Open.buffer(buf)
+  const files = (await directory.files) as ZipEntry[]
+
+  const decodedPaths = files.map((entry) =>
+    decodeZipEntryPath(entry.pathBuffer, entry.flags ?? 0, entry.path)
+  )
+  const rootDir = computeSharedZipRootPrefix(decodedPaths)
+
+  // 与 unzipper 默认 extract 一致：串行读各 entry，避免同一 buffer 上多路解压竞争
+  for (let i = 0; i < files.length; i++) {
+    const entry = files[i]!
+    const entryPath = decodedPaths[i]!
+    let newPath = entryPath.replace(/\\/g, '/')
+    if (rootDir) {
+      if (newPath === rootDir || newPath === `${rootDir}/`) {
+        continue
+      }
+      if (newPath.startsWith(`${rootDir}/`)) {
+        newPath = newPath.slice(rootDir.length + 1)
+      }
+    }
+    newPath = newPath.replace(/\/+$/, '')
+    if (!newPath) continue
+
+    const targetPath = assertSafeZipTarget(destDir, newPath)
+
+    if (entry.type === 'Directory') {
+      fs.mkdirSync(targetPath, { recursive: true })
+      continue
+    }
+
+    const parentDir = path.dirname(targetPath)
+    fs.mkdirSync(parentDir, { recursive: true })
+    const writeStream = fs.createWriteStream(targetPath)
+    try {
+      await pipeline(entry.stream(), writeStream)
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      throw new Error(`解压文件失败 ${entryPath}: ${message}`)
+    }
+  }
+}