feat: 添加追踪 ID 支持，增强错误处理和调试功能

Author: mfzzf

.gitignore

@@ -42,4 +42,5 @@ build/Release
 /test.md
 logs.txt
 /dist
-/files
+/files
+.ace-tool/

packages/js-sdk/src/api/index.ts

@@ -5,6 +5,11 @@ import { defaultHeaders } from './metadata'
 import { ConnectionConfig } from '../connectionConfig'
 import { AuthenticationError, RateLimitError, SandboxError } from '../errors'
 import { createApiLogger } from '../logs'
+import {
+  appendTraceIdToMessage,
+  createTraceIdMiddleware,
+  getTraceIdFromResponse,
+} from '../trace'
 
 export function handleApiError(
   response: FetchResponse<any, any, any>,
@@ -18,28 +23,47 @@ export function handleApiError(
     return
   }
 
+  const traceId = getTraceIdFromResponse(response.response)
+
   if (response.response.status === 401) {
     const message = 'Unauthorized, please check your credentials.'
     const content = response.error?.message ?? response.error
 
     if (content) {
-      return new AuthenticationError(`${message} - ${content}`)
+      const err = new AuthenticationError(
+        appendTraceIdToMessage(`${message} - ${content}`, traceId)
+      )
+      ;(err as any).traceId = traceId
+      return err
     }
-    return new AuthenticationError(message)
+    const err = new AuthenticationError(appendTraceIdToMessage(message, traceId))
+    ;(err as any).traceId = traceId
+    return err
   }
 
   if (response.response.status === 429) {
     const message = 'Rate limit exceeded, please try again later'
     const content = response.error?.message ?? response.error
 
     if (content) {
-      return new RateLimitError(`${message} - ${content}`)
+      const err = new RateLimitError(
+        appendTraceIdToMessage(`${message} - ${content}`, traceId)
+      )
+      ;(err as any).traceId = traceId
+      return err
     }
-    return new RateLimitError(message)
+    const err = new RateLimitError(appendTraceIdToMessage(message, traceId))
+    ;(err as any).traceId = traceId
+    return err
   }
 
   const message = response.error?.message ?? response.error
-  return new errorClass(`${response.response.status}: ${message}`, stackTrace)
+  const err = new errorClass(
+    appendTraceIdToMessage(`${response.response.status}: ${message}`, traceId),
+    stackTrace
+  )
+  ;(err as any).traceId = traceId
+  return err
 }
 
 /**
@@ -86,6 +110,8 @@ class ApiClient {
       },
     })
 
+    this.api.use(createTraceIdMiddleware())
+
     if (config.logger) {
       this.api.use(createApiLogger(config.logger))
     }

packages/js-sdk/src/envd/api.ts

@@ -11,6 +11,11 @@ import {
   formatSandboxTimeoutError,
   AuthenticationError,
 } from '../errors'
+import {
+  appendTraceIdToMessage,
+  createTraceIdMiddleware,
+  getTraceIdFromResponse,
+} from '../trace'
 import { StartResponse, ConnectResponse } from './process/process_pb'
 import { Code, ConnectError } from '@connectrpc/connect'
 import { WatchDirResponse } from './filesystem/filesystem_pb'
@@ -25,29 +30,46 @@ export async function handleEnvdApiError(res: {
     return
   }
 
+  const traceId = getTraceIdFromResponse(res.response)
+
   const message: string =
     typeof res.error == 'string'
       ? res.error
       : res.error?.message || (await res.response.text())
 
+  let err: Error
   switch (res.response.status) {
     case 400:
-      return new InvalidArgumentError(message)
+      err = new InvalidArgumentError(message)
+      break
     case 401:
-      return new AuthenticationError(message)
+      err = new AuthenticationError(message)
+      break
     case 404:
-      return new NotFoundError(message)
+      err = new NotFoundError(message)
+      break
     case 429:
-      return new SandboxError(
-        `${res.response.status}: ${message}: The requests are being rate limited.`
+      err = new SandboxError(
+        appendTraceIdToMessage(
+          `${res.response.status}: ${message}: The requests are being rate limited.`,
+          traceId
+        )
       )
+      break
     case 502:
-      return formatSandboxTimeoutError(message)
+      err = formatSandboxTimeoutError(message)
+      break
     case 507:
-      return new NotEnoughSpaceError(message)
+      err = new NotEnoughSpaceError(message)
+      break
     default:
-      return new SandboxError(`${res.response.status}: ${message}`)
+      err = new SandboxError(`${res.response.status}: ${message}`)
+      break
   }
+
+  err.message = appendTraceIdToMessage(err.message, traceId)
+  ;(err as any).traceId = traceId
+  return err
 }
 
 export async function handleProcessStartEvent(
@@ -117,6 +139,8 @@ class EnvdApiClient {
     })
     this.version = metadata.version
 
+    this.api.use(createTraceIdMiddleware())
+
     if (config.logger) {
       this.api.use(createApiLogger(config.logger))
     }

packages/js-sdk/src/index.ts

@@ -16,6 +16,7 @@ export {
   FileUploadError,
 } from './errors'
 export type { Logger } from './logs'
+export { getLastTraceId } from './trace'
 
 export { getSignature } from './sandbox/signature'
 

packages/js-sdk/src/sandbox/sandboxApi.ts

@@ -6,6 +6,7 @@ import {
 } from '../connectionConfig'
 import { compareVersions } from 'compare-versions'
 import { NotFoundError, TemplateError } from '../errors'
+import { appendTraceIdToMessage, getTraceIdFromResponse } from '../trace'
 import { timeoutToSeconds } from '../utils'
 import type { McpServer as BaseMcpServer } from './mcp'
 
@@ -432,7 +433,10 @@ export class SandboxApi {
     })
 
     if (res.error?.code === 404) {
-      throw new NotFoundError(`Sandbox ${sandboxId} not found`)
+      const traceId = getTraceIdFromResponse(res.response)
+      throw new NotFoundError(
+        appendTraceIdToMessage(`Sandbox ${sandboxId} not found`, traceId)
+      )
     }
 
     const err = handleApiError(res)
@@ -455,7 +459,10 @@ export class SandboxApi {
     })
 
     if (res.error?.code === 404) {
-      throw new NotFoundError(`Sandbox ${sandboxId} not found`)
+      const traceId = getTraceIdFromResponse(res.response)
+      throw new NotFoundError(
+        appendTraceIdToMessage(`Sandbox ${sandboxId} not found`, traceId)
+      )
     }
 
     const err = handleApiError(res)
@@ -508,7 +515,10 @@ export class SandboxApi {
     })
 
     if (res.error?.code === 404) {
-      throw new NotFoundError(`Sandbox ${sandboxId} not found`)
+      const traceId = getTraceIdFromResponse(res.response)
+      throw new NotFoundError(
+        appendTraceIdToMessage(`Sandbox ${sandboxId} not found`, traceId)
+      )
     }
 
     if (res.error?.code === 409) {
@@ -591,7 +601,13 @@ export class SandboxApi {
     })
 
     if (res.error?.code === 404) {
-      throw new NotFoundError(`Paused sandbox ${sandboxId} not found`)
+      const traceId = getTraceIdFromResponse(res.response)
+      throw new NotFoundError(
+        appendTraceIdToMessage(
+          `Paused sandbox ${sandboxId} not found`,
+          traceId
+        )
+      )
     }
 
     const err = handleApiError(res)

packages/js-sdk/src/trace.ts

@@ -0,0 +1,52 @@
+import type { Middleware } from 'openapi-fetch'
+
+export const TRACE_ID_HEADER = 'x-trace-id'
+
+let lastTraceId: string | undefined
+
+export function getLastTraceId(): string | undefined {
+  return lastTraceId
+}
+
+export function setLastTraceId(traceId: string | null | undefined) {
+  if (typeof traceId !== 'string') {
+    return
+  }
+
+  const trimmed = traceId.trim()
+  if (!trimmed) {
+    return
+  }
+
+  lastTraceId = trimmed
+}
+
+export function getTraceIdFromResponse(
+  response: Response | undefined | null
+): string | undefined {
+  return response?.headers?.get(TRACE_ID_HEADER) ?? undefined
+}
+
+export function appendTraceIdToMessage(
+  message: string,
+  traceId: string | undefined
+): string {
+  if (!traceId) {
+    return message
+  }
+
+  if (message.toLowerCase().includes('x-trace-id:')) {
+    return message
+  }
+
+  return `${message}\nX-Trace-ID: ${traceId}`
+}
+
+export function createTraceIdMiddleware(): Middleware {
+  return {
+    async onResponse({ response }) {
+      setLastTraceId(getTraceIdFromResponse(response))
+      return response
+    },
+  }
+}

packages/js-sdk/tests/traceId.test.ts

@@ -0,0 +1,78 @@
+import { afterAll, afterEach, beforeAll, describe, expect, it } from 'vitest'
+import { http, HttpResponse } from 'msw'
+import { setupServer } from 'msw/node'
+
+import { handleApiError } from '../src/api'
+import { handleEnvdApiError } from '../src/envd/api'
+import { Sandbox, getLastTraceId } from '../src'
+import { SandboxError } from '../src/errors'
+
+const server = setupServer(
+  http.get(
+    'https://api.sandbox.ucloudai.com/sandboxes/:sandboxID',
+    async () => {
+      return HttpResponse.json(
+        { code: 404, message: 'not found' },
+        {
+          status: 404,
+          headers: {
+            'X-Trace-ID': 'trace-404',
+          },
+        }
+      )
+    }
+  )
+)
+
+beforeAll(() => server.listen({ onUnhandledRequest: 'error' }))
+afterEach(() => server.resetHandlers())
+afterAll(() => server.close())
+
+describe('X-Trace-ID propagation', () => {
+  it('appends X-Trace-ID to handleApiError messages', () => {
+    const response = new Response(
+      JSON.stringify({ code: 500, message: 'internal error' }),
+      {
+        status: 500,
+        headers: {
+          'X-Trace-ID': 'trace-500',
+        },
+      }
+    )
+
+    const err = handleApiError({
+      error: { message: 'internal error' },
+      response,
+    } as any)
+
+    expect(err).toBeInstanceOf(SandboxError)
+    expect(err?.message).toContain('X-Trace-ID: trace-500')
+    expect((err as any)?.traceId).toBe('trace-500')
+  })
+
+  it('appends X-Trace-ID to handleEnvdApiError messages', async () => {
+    const response = new Response('unauthorized', {
+      status: 401,
+      headers: {
+        'X-Trace-ID': 'trace-envd-401',
+      },
+    })
+
+    const err = await handleEnvdApiError({
+      error: 'unauthorized',
+      response,
+    })
+
+    expect(err?.message).toContain('X-Trace-ID: trace-envd-401')
+    expect((err as any)?.traceId).toBe('trace-envd-401')
+  })
+
+  it('includes X-Trace-ID in NotFoundError messages and updates last trace id', async () => {
+    await expect(Sandbox.getInfo('missing-sandbox')).rejects.toMatchObject({
+      message: expect.stringContaining('X-Trace-ID: trace-404'),
+    })
+
+    expect(getLastTraceId()).toBe('trace-404')
+  })
+})
+

packages/js-sdk/vitest.config.ts

@@ -0,0 +1,29 @@
+import { defineConfig } from 'vitest/config'
+import { config as loadDotenv } from 'dotenv'
+
+const env = loadDotenv()
+
+export default defineConfig({
+  test: {
+    include: ['tests/**/*.test.ts'],
+    exclude: [
+      'tests/runtimes/**',
+      'tests/integration/**',
+      'tests/template/**',
+      'tests/connectionConfig.test.ts',
+    ],
+    isolate: false,
+    globals: false,
+    testTimeout: 30_000,
+    environment: 'node',
+    bail: 0,
+    deps: {
+      interopDefault: true,
+    },
+    env: {
+      ...(process.env as Record<string, string>),
+      ...env.parsed,
+    },
+  },
+})
+

src/commands/index.ts

@@ -19,3 +19,12 @@ Visit ${asPrimary(
   .addCommand(authCommand)
   .addCommand(templateCommand)
   .addCommand(sandboxCommand)
+
+function addDebugOption(cmd: commander.Command) {
+  cmd.option('--debug', 'print Trace ID for debugging')
+  for (const subcommand of cmd.commands) {
+    addDebugOption(subcommand)
+  }
+}
+
+addDebugOption(program)