@dcrays/dcgchat 0.3.33 → 0.4.4

package/src/tools/messageTool.ts

@@ -0,0 +1,215 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import type { AnyAgentTool } from 'openclaw/plugin-sdk'
+import { jsonResult } from 'openclaw/plugin-sdk'
+import { sendDcgchatMedia } from '../channel.js'
+import { getOutboundMsgParams } from '../utils/params.js'
+import { sendText } from '../transport.js'
+
+/** 与 `registerTool` 工厂入参一致（主包未导出 `OpenClawPluginToolContext` 时仅用所需字段）。 */
+export type DcgchatMessageToolContext = {
+  sessionKey?: string
+  workspaceDir?: string
+}
+
+/** 统一为 POSIX 风格斜杠，便于跨平台判断（不改变语义，仅用于匹配）。 */
+function toPosixPath(p: string): string {
+  return path.normalize(p.trim()).replace(/\\/g, '/')
+}
+
+/** `filepath` 解析后在 `rootDir` 内或等于 `rootDir`（防 `..` 逃逸）。 */
+function isPathInsideDir(filepath: string, rootDir: string): boolean {
+  const root = path.resolve(rootDir)
+  const resolved = path.resolve(filepath)
+  const rel = path.relative(root, resolved)
+  if (rel.startsWith('..') || path.isAbsolute(rel)) return false
+  return true
+}
+
+/**
+ * 允许发送的路径：
+ * - 当前 Agent 工作区根及其子路径（`workspaceDir`，如 ~/.openclaw/workspace-xxx/output/...）；
+ * - 兼容旧挂载：Unix `/workspace`、`/mobook`；Windows 盘符下 `workspace`、`mobook`。
+ */
+function isSafePath(filepath: string, workspaceDir?: string): boolean {
+  const ws = workspaceDir?.trim()
+  if (ws && isPathInsideDir(filepath, ws)) return true
+  const p = toPosixPath(filepath)
+  if (p.startsWith('/workspace/') || p === '/workspace') return true
+  if (p === '/mobook') return true
+  return /^[A-Za-z]:\/(workspace|mobook)(\/|$)/.test(p)
+}
+
+/** 同一路径在 Windows 上可能大小写不同，用于 Set 去重。 */
+function pathKey(filepath: string): string {
+  const n = path.normalize(filepath.trim())
+  return os.platform() === 'win32' ? n.toLowerCase() : n
+}
+
+const fileType1 = ['.webp', '.gif', '.bmp', '.doc', '.docx', '.xls', '.xlsx', '.ppt', '.pptx', '.pdf', '.txt', '.rtf', '.odt', '.json']
+const fileType2 = ['.xml', '.csv', '.yaml', '.yml', '.html', '.htm', '.md', '.markdown', '.css', '.js', '.ts', '.png', '.jpg', '.jpeg']
+const fileType3 = ['.zip', '.rar', '.7z', '.tar', '.gz', '.bz2', '.xz', '.exe', '.dmg', '.pkg', '.apk', '.ipa', '.log', '.dat', '.bin']
+const fileType4 = ['.svg', '.ico', '.mp3', '.wav', '.ogg', '.aac', '.m4a', '.mp4', '.avi', '.mov', '.wmv', '.flv', '.mkv', '.webm']
+const SAFE_EXTENSIONS = new Set([...fileType1, ...fileType2, ...fileType3, ...fileType4])
+
+const messageToolParameters = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    target: {
+      type: 'string',
+      description: '目标会话键（sessionKey），必须与当前会话 SessionKey 一致，禁止填写 userId。'
+    },
+    content: {
+      type: 'string',
+      description: '发送文本内容'
+    },
+    media: {
+      type: 'array',
+      description: '发送附件',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          file: {
+            type: 'string',
+            description:
+              '文件绝对路径：须在「当前 Agent 工作区」目录下（如 /root/.openclaw/workspace-xxx/output/28337/slices_result.json），或为兼容环境的 /workspace/、/mobook/（Windows 盘符下 workspace、mobook）'
+          }
+        },
+        required: ['file']
+      }
+    }
+  },
+  oneOf: [{ required: ['content'] }, { required: ['media'] }]
+}
+
+/** 从正文提取可发送的文件路径（固定挂载 + 当前工作区前缀）。 */
+function extractPaths(text: string | undefined, workspaceDir?: string): string[] {
+  if (!text) return []
+  const unix = text.match(/\/workspace\/[^\s]+|\/mobook\/[^\s]+/g) ?? []
+  const win = text.match(/[A-Za-z]:[/\\](?:workspace|mobook)[/\\][^\s]+/g) ?? []
+  const underWs: string[] = []
+  const ws = workspaceDir?.trim()
+  if (ws) {
+    const variants = new Set<string>()
+    variants.add(ws)
+    variants.add(toPosixPath(ws))
+    if (path.sep === '\\') variants.add(ws.replace(/\//g, '\\'))
+    for (const prefix of variants) {
+      if (!prefix) continue
+      let from = 0
+      while (from < text.length) {
+        const i = text.indexOf(prefix, from)
+        if (i === -1) break
+        let end = i + prefix.length
+        while (end < text.length && !/\s/.test(text[end])) end++
+        underWs.push(text.slice(i, end))
+        from = i + 1
+      }
+    }
+  }
+  return [...new Set([...unix, ...win, ...underWs])]
+}
+
+function isSafeFile(filepath: string) {
+  if (!fs.existsSync(filepath)) return false
+  const stat = fs.statSync(filepath)
+  if (!stat.isFile()) return false
+  if (stat.size === 0) return false
+  const ext = path.extname(filepath).toLowerCase()
+  return SAFE_EXTENSIONS.has(ext)
+}
+
+/**
+ * 书灵墨宝出站消息工具：须符合 OpenClaw `AgentTool`（execute 返回 `AgentToolResult`）。
+ * 工具名使用 `dcgchat_message`，避免与核心内置 `message` 冲突。
+ * 通过注册时的 `OpenClawPluginToolContext.sessionKey` 出站，不再使用非标准的 `execute(args, ctx)`。
+ */
+export function createDcgchatMessageTool(pluginCtx: DcgchatMessageToolContext): AnyAgentTool {
+  return {
+    name: 'dcgchat_message',
+    label: 'dcgchat_message',
+    description: `
+      向用户发送消息。
+      若传 target，target 必须是 sessionKey，不能是 userId。
+      如果发送附件：必须使用 media 字段
+      文件路径须在当前 Agent 工作区目录下（随部署变化，如 ~/.openclaw/workspace-xxx/...），或为兼容环境的 /workspace/、/mobook/（Windows 盘符下 workspace、mobook）。
+      禁止在正文中直接输出可访问路径（应通过 media 发送）
+    `,
+    parameters: messageToolParameters,
+    execute: async (_toolCallId, args, signal) => {
+      if (signal?.aborted) {
+        const err = new Error('Message send aborted')
+        err.name = 'AbortError'
+        throw err
+      }
+
+      const sessionKey = pluginCtx.sessionKey?.trim()
+      if (!sessionKey) {
+        return jsonResult({ error: '缺少 sessionKey，无法向当前会话发送消息' })
+      }
+
+      try {
+        const sentFiles = new Set<string>()
+        const sentKeys = new Set<string>()
+        const workspaceDir = pluginCtx.workspaceDir
+
+        if (args.media?.length) {
+          for (const media of args.media) {
+            const filepath = media.file
+            if (!filepath) continue
+            if (!isSafePath(filepath, workspaceDir)) continue
+            if (!isSafeFile(filepath)) continue
+            const key = pathKey(filepath)
+            if (sentKeys.has(key)) continue
+
+            await sendDcgchatMedia({ sessionKey, mediaUrl: filepath })
+            sentFiles.add(filepath)
+            sentKeys.add(key)
+          }
+        }
+
+        const fallbackPaths = extractPaths(args.content, workspaceDir)
+        for (const filepath of fallbackPaths) {
+          if (!isSafePath(filepath, workspaceDir)) continue
+          if (!isSafeFile(filepath)) continue
+          const key = pathKey(filepath)
+          if (sentKeys.has(key)) continue
+
+          await sendDcgchatMedia({ sessionKey, mediaUrl: filepath })
+          sentFiles.add(filepath)
+          sentKeys.add(key)
+        }
+
+        let content = args.content ?? ''
+        for (const filepath of sentFiles) {
+          const posix = toPosixPath(filepath)
+          const variants = posix === filepath ? [filepath] : [filepath, posix]
+          const seen = new Set<string>()
+          for (const v of variants) {
+            if (!v || seen.has(v)) continue
+            seen.add(v)
+            content = content.split(v).join('')
+          }
+        }
+        content = content.trim()
+
+        if (content.length > 0) {
+          const msgCtx = getOutboundMsgParams(sessionKey)
+          sendText(content, msgCtx)
+        }
+
+        return jsonResult({
+          success: true,
+          sentMediaCount: sentFiles.size
+        })
+      } catch (err) {
+        return jsonResult({
+          error: err instanceof Error ? err.message : String(err)
+        })
+      }
+    }
+  }
+}

package/src/transport.ts

@@ -152,11 +152,14 @@ export function wsSend(ctx: IMsgParams, content: Record<string, unknown>): boole
  */
 export function wsSendRaw(ctx: IMsgParams, content: Record<string, unknown>, isLog = true): boolean {
   const ws = getWsConnection()
-  if (isWsOpen()) {
-    ws?.send(JSON.stringify(buildOpenclawBotChat(ctx, content, { mergeChannelDefaults: true })))
-    if (isLog) {
-      dcgLogger('已发送：' + JSON.stringify(buildOpenclawBotChat(ctx, content, { mergeChannelDefaults: true })))
-    }
+  if (ws?.readyState !== WebSocket.OPEN) {
+    dcgLogger(`server socket not ready ${ws?.readyState}`, 'error')
+    return false
+  }
+  const envelope = buildOpenclawBotChat(ctx, content, { mergeChannelDefaults: true })
+  ws.send(JSON.stringify(envelope))
+  if (isLog) {
+    dcgLogger('已发送：' + JSON.stringify(envelope))
   }
   return true
 }
@@ -166,7 +169,7 @@ export function sendChunk(text: string, ctx: IMsgParams, chunkIdx: number): bool
 }
 
 export function sendFinal(ctx: IMsgParams, tag: string): boolean {
-  dcgLogger(` message handling complete state: final tag:${tag}`)
+  dcgLogger(` message handling complete state: to=${ctx.sessionId} final tag:${tag}`)
   return wsSend(ctx, { response: '', state: 'final' })
 }
 
@@ -178,7 +181,7 @@ export function sendError(errorMsg: string, ctx: IMsgParams): boolean {
   return wsSend(ctx, { response: `[错误] ${errorMsg}`, state: 'final' })
 }
 
-export function sendEventMessage(url: string, params: Record<string, string> = {}) {
+export function sendEventMessage(params: Record<string, string> = {}) {
   const ctx = getParamsDefaults()
   const ws = getWsConnection()
   if (isWsOpen()) {
@@ -190,7 +193,6 @@ export function sendEventMessage(url: string, params: Record<string, string> = {
           bot_token: ctx.botToken,
           domain_id: ctx.domainId,
           app_id: ctx.appId,
-          oss_url: url,
           bot_id: ctx.botId,
           ...params
         }

package/src/types.ts

@@ -11,6 +11,11 @@ export type DcgchatConfig = {
   userId?: string
   domainId?: string
   appId?: string
+  /**
+   * 内置 `message` 工具走 OpenClaw 目标解析：`true`（默认）时仅将符合 sessionKey 形态的字符串视为合法 target，
+   * 纯数字（WS userId 等）会解析失败；设为 `false` 恢复旧版宽松行为（不推荐）。
+   */
+  strictMessageToolTarget?: boolean
 }
 
 export type ResolvedDcgchatAccount = {
@@ -38,7 +43,9 @@ export type InboundMessage = {
   source: string // 'server',
   // content: string;
   content: {
+    skills_scope: Record<string, any>[]
     bot_token: string
+    agent_clone_code?: string
     domain_id?: string
     app_id?: string
     bot_id?: string

package/src/utils/constant.ts

@@ -2,6 +2,6 @@ export const ENV: 'production' | 'test' | 'develop' = 'production'
 
 
 export const systemCommand = ['/new', '/status']
-export const interruptCommand = ['chat.stop']
+export const interruptCommand = ['/stop']
 
-export const ignoreToolCommand = ['/search', '/abort', '/stop', '/queue interrupt', ...systemCommand, ...interruptCommand]
+export const ignoreToolCommand = ['/search', '/abort', '/queue interrupt', ...systemCommand, ...interruptCommand]

package/src/utils/gatewayMsgHanlder.ts

@@ -0,0 +1,47 @@
+import type { GatewayEvent } from '../gateway/index.js'
+import { finishedDcgchatCron, sendDcgchatCron } from '../cron.js'
+import { dcgLogger } from './log.js'
+import { getEffectiveMsgParams, getSessionKeyBySubAgentRunId } from './params.js'
+import { sendChunk } from '../transport.js'
+
+/**
+ * 处理网关 event 帧的副作用（agent 流式输出、cron 同步），并构造供上层分发的 GatewayEvent。
+ */
+export function handleGatewayEventMessage(msg: { event?: string; payload?: Record<string, unknown>; seq?: number }): GatewayEvent {
+  try {
+    if (msg.event === 'agent') {
+      const pl = msg.payload as { runId: string; data?: { delta?: unknown } }
+      const sessionKey = getSessionKeyBySubAgentRunId(pl.runId)
+      const outboundCtx = getEffectiveMsgParams(sessionKey)
+      if (pl.data?.delta) {
+        if (outboundCtx.sessionId) {
+          dcgLogger(`[Gateway] 收到agent事件: ${JSON.stringify(msg).slice(0, 100)}`)
+          sendChunk(pl.data.delta as string, outboundCtx, 0)
+        }
+      }
+    }
+    if (msg.event === 'cron') {
+      const p = msg.payload
+      dcgLogger(`[Gateway] 收到定时任务事件: ${JSON.stringify(p)}`)
+      if (p?.action === 'added') {
+        sendDcgchatCron(p?.jobId as string)
+      }
+      if (p?.action === 'updated') {
+        sendDcgchatCron(p?.jobId as string)
+      }
+      if (p?.action === 'removed') {
+        sendDcgchatCron(p?.jobId as string)
+      }
+      if (p?.action === 'finished') {
+        finishedDcgchatCron(p?.jobId as string)
+      }
+    }
+  } catch (error) {
+    dcgLogger(`[Gateway] 处理事件失败: ${error}`, 'error')
+  }
+  return {
+    type: msg.event as string,
+    payload: msg.payload,
+    seq: msg.seq as number | undefined
+  }
+}

package/src/utils/global.ts

@@ -1,6 +1,12 @@
-/** socket connection */
 import type WebSocket from 'ws'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { createPluginRuntimeStore, type OpenClawConfig, type PluginRuntime } from 'openclaw/plugin-sdk'
+import { channelInfo, ENV } from './constant.js'
+import { dcgLogger } from './log.js'
 
+/** socket connection */
 let ws: WebSocket | null = null
 
 export function setWsConnection(next: WebSocket | null) {
@@ -11,7 +17,6 @@ export function getWsConnection(): WebSocket | null {
   return ws
 }
 
-// OpenClawConfig
 let config: OpenClawConfig | null = null
 
 export function setOpenClawConfig(next: OpenClawConfig | null) {
@@ -22,15 +27,7 @@ export function getOpenClawConfig(): OpenClawConfig | null {
   return config
 }
 
-import type { OpenClawConfig, PluginRuntime } from 'openclaw/plugin-sdk'
-import { dcgLogger } from './log.js'
-import { channelInfo, ENV } from './constant.js'
-
-const path = require('path')
-const fs = require('fs')
-const os = require('os')
-
-function getWorkspacePath() {
+function getWorkspacePath(): string | null {
   const workspacePath = path.join(
     os.homedir(),
     config?.channels?.["dcgchat"]?.appId == 110 ? '.mobook' : '.openclaw',
@@ -42,14 +39,14 @@ function getWorkspacePath() {
   return null
 }
 
-let runtime: PluginRuntime | null = null
-let workspaceDir: string = getWorkspacePath()
+let workspaceDir: string = getWorkspacePath() ?? ''
 
 export function setWorkspaceDir(dir?: string) {
   if (dir) {
     workspaceDir = dir
   }
 }
+
 export function getWorkspaceDir(): string {
   if (!workspaceDir) {
     dcgLogger?.('Workspace directory not initialized', 'error')
@@ -57,16 +54,10 @@ export function getWorkspaceDir(): string {
   return workspaceDir
 }
 
-export function setDcgchatRuntime(next: PluginRuntime) {
-  runtime = next
-}
-
-export function getDcgchatRuntime(): PluginRuntime {
-  if (!runtime) {
-    dcgLogger?.('runtime not initialized', 'error')
-  }
-  return runtime as PluginRuntime
-}
+const { setRuntime: setDcgchatRuntime, getRuntime: getDcgchatRuntime } = createPluginRuntimeStore<PluginRuntime>(
+  `${"dcgchat"} runtime not initialized`
+)
+export { setDcgchatRuntime, getDcgchatRuntime }
 
 export type MsgSessionStatus = 'running' | 'finished' | ''
 
@@ -117,19 +108,6 @@ export function clearSentMediaKeys(messageId?: string) {
   }
 }
 
-export const getSessionKey = (content: any, accountId: string) => {
-  const { real_mobook, agent_id, conversation_id, session_id } = content
-  const core = getDcgchatRuntime()
-
-  const route = core.channel.routing.resolveAgentRoute({
-    cfg: getOpenClawConfig() as OpenClawConfig,
-    channel: "dcgchat",
-    accountId: accountId || 'default',
-    peer: { kind: 'direct', id: session_id }
-  })
-  return real_mobook == '1' ? route.sessionKey : `agent:main:mobook:direct:${agent_id}:${session_id}`.toLowerCase()
-}
-
 const cronMessageIdMap = new Map<string, string>()
 
 export function setCronMessageId(sk: string, messageId: string) {
@@ -144,6 +122,21 @@ export function removeCronMessageId(sk: string) {
   cronMessageIdMap.delete(sk)
 }
 
+export const getSessionKey = (content: any, accountId: string) => {
+  const { real_mobook, agent_id, agent_clone_code, session_id } = content
+  const core = getDcgchatRuntime()
+
+  const agentCode = agent_clone_code || 'main'
+
+  const route = core.channel.routing.resolveAgentRoute({
+    cfg: getOpenClawConfig() as OpenClawConfig,
+    channel: "dcgchat",
+    accountId: accountId || 'default',
+    peer: { kind: 'direct', id: session_id }
+  })
+  return real_mobook == '1' ? route.sessionKey : `agent:${agentCode}:mobook:direct:${agent_id}:${session_id}`.toLowerCase()
+}
+
 export function getInfoBySessionKey(sk: string): { sessionId: string; agentId: string } {
   const sessionInfo = sk.split(':')
   return { sessionId: sessionInfo.at(-1) ?? '', agentId: sessionInfo.at(-2) ?? '' }

package/src/utils/params.ts

@@ -47,9 +47,8 @@ export function getEffectiveMsgParams(sessionKey?: string): IMsgParams {
 }
 
 /**
- * Agent `message` 工具的 `target` 应为 `effectiveSessionKey`（如 `agent:main:mobook:direct:...`）。
- * `setParamsMessage` 使用的 key 与此一致。若按 preferredKey 查不到 map，
- * 则回落到当前会话 `currentSessionKey`，避免拿到空 `messageId` / `sessionId` 导致无文件卡片、WS 上下文错误。
+ * Agent `dcgchat_message` / 出站 `target` 应为 `dcgSessionKey`（如 `agent:main:mobook:direct:...`）。
+ * `setParamsMessage` 的 key 与此一致；查不到 map 时回落到配置缺省（无会话级 messageId/sessionId）。
  */
 export function getOutboundMsgParams(preferredKey: string): IMsgParams {
   const k = preferredKey?.trim()
@@ -69,3 +68,21 @@ export function setParamsMessage(sessionKey: string, params: Partial<IMsgParams>
 export function getParamsMessage(sessionKey: string): IMsgParams | undefined {
   return paramsMessageMap.get(sessionKey)
 }
+
+export function clearParamsMessage(sessionKey: string): void {
+  const k = sessionKey?.trim()
+  if (!k) return
+  paramsMessageMap.delete(k)
+}
+
+// sessionKey 对应的 子agent的runId
+const subagentRunIdMap = new Map<string, string>()
+export function getSessionKeyBySubAgentRunId(runId: string): string | undefined {
+  return subagentRunIdMap.get(runId)
+}
+export function setSessionKeyBySubAgentRunId(runId: string, sessionKey: string) {
+  subagentRunIdMap.set(runId, sessionKey)
+}
+export function deleteSessionKeyBySubAgentRunId(runId: string) {
+  subagentRunIdMap.delete(runId)
+}

package/src/utils/wsMessageHandler.ts

@@ -0,0 +1,64 @@
+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.js'
+import { ignoreToolCommand } from './constant.js'
+import { createAgent } from '../agent.js'
+
+export type ParsedWsPayload = {
+  messageType?: string
+  content: any
+}
+
+/**
+ * 处理 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)
+    if (!ignoreToolCommand.includes(msg.content.text?.trim() ?? '')) {
+      setMsgStatus(effectiveSessionKey, 'running')
+    } else {
+      setMsgStatus(effectiveSessionKey, 'finished')
+    }
+    await handleDcgchatMessage(msg, accountId)
+  } else if (parsed.messageType == 'openclaw_bot_event') {
+    const { event_type, operation_type } = parsed.content ? parsed.content : ({} as Record<string, any>)
+    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 {
+        dcgLogger(`openclaw_bot_event unknown event_type: ${event_type}, ${rawPayload}`)
+      }
+    } else if (event_type === 'agent') {
+      if (operation_type === 'create') {
+        await createAgent(parsed.content)
+      } else {
+        dcgLogger(`openclaw_bot_event unknown event_type: ${event_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 unknown operation_type: ${operation_type}, ${rawPayload}`)
+    }
+  } 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}`)
+    }
+  }
+}

package/src/utils/zipPath.ts

@@ -0,0 +1,24 @@
+/**
+ * ZIP 文件名编码：规范要求 UTF-8 时设置 0x800；很多工具未设标志但仍写 UTF-8 字节。
+ * 无标志时若一律按 GBK 解码，会得到「鍥句功…」类乱码。先严格 UTF-8，失败再 GBK（兼容 Windows 中文 ZIP）。
+ */
+export function decodeZipEntryPath(
+  pathBuffer: Buffer | Uint8Array | undefined,
+  flags: number,
+  fallbackPath: string
+): string {
+  if ((flags & 0x800) !== 0) {
+    if (pathBuffer) {
+      return new TextDecoder('utf-8').decode(pathBuffer)
+    }
+    return fallbackPath
+  }
+  if (pathBuffer && pathBuffer.length > 0) {
+    try {
+      return new TextDecoder('utf-8', { fatal: true }).decode(pathBuffer)
+    } catch {
+      return new TextDecoder('gbk').decode(pathBuffer)
+    }
+  }
+  return fallbackPath
+}