dsh-plugin-weapp-gateway 0.8.13 → 0.8.23

package/lib/dsh-host-adapter.mjs

@@ -136,7 +136,7 @@ export function createDshHostAdapter(typertGateway) {
     if (payload.beforeSeq !== undefined) {
       const page = requireRecord(await invoke('session', 'page', requestArgs({
         address: request.address,
-        throughSeq: snapshot.cursor,
+        throughSeq: Number.isSafeInteger(payload.throughSeq) ? payload.throughSeq : snapshot.cursor,
         beforeSeq: payload.beforeSeq,
         ...(payload.maxMessages === undefined ? {} : { maxMessages: payload.maxMessages }),
       }), signal), 'session/page')

package/lib/index.mjs

@@ -135,6 +135,10 @@ import { createDshHostAdapter, DSH_VERSION, SESSION_FORMAT_VERSION } from './dsh
 import { createSpeechInputManager, SPEECH_REQUEST_TYPES } from './speech-input.mjs'
 import { handlePluginQuery, PLUGIN_REQUEST_TYPES } from './plugin-management.mjs'
 import { handleWorkspaceChanges, WORKSPACE_CHANGES_TYPES } from './workspace-changes-bridge.mjs'
+import { handleCostMeter, COST_METER_REQUEST_TYPES, registerCostMeterProjection, registerCostMeterServices } from './cost-meter-bridge.mjs'
+import { handleCostMeterWithDashboard } from './cost-meter-dashboard-bridge.mjs'
+import { handleContextQuery, handleContextFleet, handleContextContent, registerContextProjection, registerContextServices, CONTEXT_REQUEST_TYPES } from './context-bridge.mjs'
+import { handleAccount, ACCOUNT_REQUEST_TYPES } from './account-bridge.mjs'
 import { createSessionFollower } from './session-follower.mjs'
 import { createGatewayState, GATEWAY_MODES } from './gateway-state.mjs'
 import { createRelayState, PAIRING_MODES } from './relay-state.mjs'
@@ -289,6 +293,44 @@ function imagesOf(blocks) {
   return images
 }
 
+function attachmentsOf(blocks) {
+  const attachments = []
+  for (const block of blocks || []) {
+    if (!block || typeof block !== 'object') continue
+    if (block.type === 'image' && block.attachment) {
+      attachments.push({ kind: 'image', ...imagesOf([block])[0] })
+    } else if (block.type === 'file') {
+      const ref = block.attachment || block.file || block
+      const item = {
+        kind: 'file',
+        ...(typeof block.receiptId === 'string' ? { receiptId: block.receiptId } : {}),
+        ...(typeof ref?.attachmentId === 'string' ? { attachmentId: ref.attachmentId } : {}),
+        ...(typeof ref?.name === 'string' ? { name: ref.name } : {}),
+        ...(Number.isSafeInteger(ref?.bytes) ? { bytes: ref.bytes } : {}),
+        ...(typeof ref?.mediaType === 'string' ? { mediaType: ref.mediaType } : {}),
+      }
+      if (item.receiptId || item.attachmentId || item.name) attachments.push(item)
+    } else if (block.type === 'directory' || block.type === 'folder') {
+      const path = block.path || block.name
+      if (typeof path === 'string' && path) attachments.push({ kind: 'directory', path, name: block.name || path })
+    }
+  }
+  return attachments
+}
+
+function workspaceAttachmentsOfText(text) {
+  if (typeof text !== 'string') return []
+  const attachments = []
+  const pattern = /^\[工作区(文件|目录):\s*([^\]\n]+)\]$/gm
+  let match
+  while ((match = pattern.exec(text))) {
+    const pathValue = match[2].trim()
+    if (!pathValue) continue
+    attachments.push({ kind: match[1] === '目录' ? 'directory' : 'file', path: pathValue, name: pathValue.split('/').pop() || pathValue })
+  }
+  return attachments
+}
+
 // Build the small, owned JSON wire record for one session event. Reads only
 // leaf fields of the live SessionEvent — never serializes live objects.
 function buildWireEvent(session, event) {
@@ -300,13 +342,16 @@ function buildWireEvent(session, event) {
   switch (event.type) {
     case 'user/message': {
       const images = imagesOf(d.content || [])
+      const text = textOf(d.content || [])
+      const attachments = [...attachmentsOf(d.content || []), ...workspaceAttachmentsOfText(text)]
       return Object.assign(base, {
         event: {
           type: 'user/message',
-          text: textOf(d.content || []),
+          text,
           source: d.source && d.source.kind,
           ...(typeof d.id === 'string' && d.id ? { raw: { id: d.id } } : {}),
           ...(images.length ? { images } : {}),
+          ...(attachments.length ? { attachments } : {}),
         },
       })
     }
@@ -316,6 +361,7 @@ function buildWireEvent(session, event) {
       let reasoning = ''
       const toolCalls = []
       const images = imagesOf(blocks)
+      const attachments = attachmentsOf(blocks)
       for (const block of blocks) {
         if (!block) continue
         if (block.type === 'text' && typeof block.text === 'string') text += block.text
@@ -327,6 +373,7 @@ function buildWireEvent(session, event) {
           ...(d.interrupted === true ? { interrupted: true } : {}),
           ...(d.usage === undefined ? {} : { usage: d.usage }),
           ...(images.length ? { images } : {}),
+          ...(attachments.length ? { attachments } : {}),
         },
       })
     }
@@ -416,15 +463,15 @@ function buildWireEvent(session, event) {
           ...(typeof d.error === 'string' ? { error: d.error } : {}),
         },
       })
-    // Keep live file declarations equivalent to durable history.
-    case 'workspace/changes':
-      return Object.assign(base, { event: { type: event.type, turn: d.turn } })
-    case 'deliverables/presented':
-      return Object.assign(base, { event: { type: event.type, turn: d.turn, callId: d.callId,
-        files: (Array.isArray(d.files) ? d.files : []).filter(file => file && typeof file.path === 'string').map(file => ({
-          path: file.path, ...(typeof file.description === 'string' ? { description: file.description } : {}),
-        })),
-      } })
+    // Keep live file declarations equivalent to durable history.
+    case 'workspace/changes':
+      return Object.assign(base, { event: { type: event.type, turn: d.turn } })
+    case 'deliverables/presented':
+      return Object.assign(base, { event: { type: event.type, turn: d.turn, callId: d.callId,
+        files: (Array.isArray(d.files) ? d.files : []).filter(file => file && typeof file.path === 'string').map(file => ({
+          path: file.path, ...(typeof file.description === 'string' ? { description: file.description } : {}),
+        })),
+      } })
     case 'turn/start':
     case 'turn/end':
     case 'step/start':
@@ -470,6 +517,25 @@ function parseWireImages(rawImages, requestType) {
   return { value: imageParts }
 }
 
+function parseWireAttachments(rawAttachments, requestType) {
+  if (rawAttachments === undefined) return { value: [] }
+  if (!Array.isArray(rawAttachments) || rawAttachments.length > 6) {
+    return { error: { kind: 'error', code: 'bad-request', message: 'attachments must be an array with at most 6 items', requestType } }
+  }
+  const value = []
+  for (let index = 0; index < rawAttachments.length; index++) {
+    const item = rawAttachments[index]
+    if (!item || typeof item !== 'object' || !['file', 'directory'].includes(item.kind)
+      || typeof item.path !== 'string' || !item.path.trim() || item.path.includes('\0')
+      || path.isAbsolute(item.path) || item.path.split(/[\\/]+/).includes('..')) {
+      return { error: { kind: 'error', code: 'bad-request', message: `attachments[${index}] must be a workspace-relative file or directory path`, requestType } }
+    }
+    const cleanPath = item.path.trim().replace(/[\\]+/g, '/')
+    value.push({ kind: item.kind, path: cleanPath, ...(typeof item.name === 'string' && item.name ? { name: item.name.slice(0, 255) } : {}) })
+  }
+  return { value }
+}
+
 function commandNameOf(line) {
   const trimmed = line.trim()
   if (!trimmed.startsWith('/')) return null
@@ -545,7 +611,12 @@ async function admitMessage(api, msg, notificationTracker) {
   const parsedImages = parseWireImages(msg.images, 'message')
   if (parsedImages.error) return parsedImages.error
   const imageParts = parsedImages.value
-  if (!text && imageParts.length === 0) {
+  const parsedAttachments = parseWireAttachments(msg.attachments, 'message')
+  if (parsedAttachments.error) return parsedAttachments.error
+  const attachmentRefs = parsedAttachments.value
+  const attachmentText = attachmentRefs.map((item) => `[${item.kind === 'directory' ? '工作区目录' : '工作区文件'}: ${item.path}]`).join('\n')
+  const promptText = [text, attachmentText].filter(Boolean).join('\n')
+  if (!promptText && imageParts.length === 0) {
     return { kind: 'error', code: 'bad-request', message: 'message requires non-empty text or at least one image' }
   }
   const mode = msg.mode === 'steer' ? 'steer' : 'queue'
@@ -578,10 +649,10 @@ async function admitMessage(api, msg, notificationTracker) {
       sessionId,
       mode,
       // Match the official WebUI ordering: images first, optional text last.
-      content: [...imageParts, ...(text ? [{ type: 'text', text }] : [])],
+      content: [...imageParts, ...(promptText ? [{ type: 'text', text: promptText }] : [])],
       ...(typeof msg.clientTimeZone === 'string' && msg.clientTimeZone.trim() ? { clientTimeZone: msg.clientTimeZone.trim() } : {}),
     })
-    log(`mobile message accepted: session=${sessionId} mode=${mode} images=${imageParts.length} text="${text.slice(0, 60)}"`)
+    log(`mobile message accepted: session=${sessionId} mode=${mode} images=${imageParts.length} attachments=${attachmentRefs.length} text="${promptText.slice(0, 60)}"`)
     return {
       kind: 'sent',
       sessionId,
@@ -1457,7 +1528,12 @@ async function handleClawbotControl(clawbotService, msg) {
 // Dispatch one mobile query frame; returns the wire frame to send back.
 async function handleQuery(api, host, agentDefaultModel, msg, pluginContext) {
   if (msg.type === 'clawbot-control') return handleClawbotControl(pluginContext?.clawbotService, msg)
+  if (COST_METER_REQUEST_TYPES.has(msg.type)) return handleCostMeterWithDashboard(api, msg, { hostContext: pluginContext?.hostContext })
   if (WORKSPACE_CHANGES_TYPES.has(msg.type)) return handleWorkspaceChanges(api, msg)
+  if (msg.type === 'context-fleet') return handleContextFleet(msg)
+  if (msg.type === 'context-content') return handleContextContent(api, msg)
+  if (CONTEXT_REQUEST_TYPES.has(msg.type)) return handleContextQuery(api, msg)
+  if (ACCOUNT_REQUEST_TYPES.has(msg.type)) return handleAccount(api, msg)
   if (PLUGIN_REQUEST_TYPES.has(msg.type)) return handlePluginQuery(api, msg, pluginContext)
   if (msg.type === 'session-agent-preset' || msg.type === 'select-agent-preset') {
     const session = requireSessionId(msg)
@@ -2257,6 +2333,19 @@ const plugin = {
   apply(ctx, config) {
     const webServer = ctx.webServer
     const api = createDshHostAdapter(ctx.typertGateway)
+    // Optional lifecycle-bound services: hosts without session projections keep working.
+    registerContextProjection(ctx)
+    registerContextServices(ctx)
+    // Cost meter is standalone: it registers its own `costMeter` session
+    // projection (so the host folds usage into the projection cache) and reads
+    // that back in-process — no `dsh-cost-meter` plugin required.
+    registerCostMeterProjection(ctx)
+    registerCostMeterServices(ctx)
+    // Optional lifecycle-bound service: hosts without the DeepSeek account bundle keep working.
+    ctx.inject(['accountController'], accountCtx => {
+      api.account = accountCtx.accountController
+      accountCtx.effect(() => () => { api.account = undefined })
+    })
     const clawbotService = createClawbotService(ctx)
     ctx.effect(() => () => clawbotService.dispose())
     // Optional lifecycle-bound service: old hosts retain all existing gateway features.
@@ -2821,6 +2910,7 @@ const plugin = {
                 api,
                 currentVersion: PLUGIN_VERSION,
                 requestId: crypto.randomUUID(),
+                profileName: ctx.get?.('profileContext')?.name,
               })
               sendJson(res, 200, result)
             } finally {
@@ -3224,8 +3314,8 @@ const plugin = {
                        msg.type === 'goal-pause' || msg.type === 'goal-resume' || msg.type === 'goal-clear' ||
                        msg.type === 'schedule-catalog' || msg.type === 'schedule-list' || msg.type === 'schedule-history' ||
                        msg.type === 'schedule-update' || msg.type === 'schedule-delete' ||
-                       WORKSPACE_CHANGES_TYPES.has(msg.type) || PLUGIN_REQUEST_TYPES.has(msg.type)) {
-              if ((WORKSPACE_CHANGES_TYPES.has(msg.type) || PLUGIN_REQUEST_TYPES.has(msg.type) || msg.type === 'clawbot-control') && !ws.deviceId) {
+                       ACCOUNT_REQUEST_TYPES.has(msg.type) || COST_METER_REQUEST_TYPES.has(msg.type) || WORKSPACE_CHANGES_TYPES.has(msg.type) || CONTEXT_REQUEST_TYPES.has(msg.type) || PLUGIN_REQUEST_TYPES.has(msg.type)) {
+              if ((ACCOUNT_REQUEST_TYPES.has(msg.type) || COST_METER_REQUEST_TYPES.has(msg.type) || WORKSPACE_CHANGES_TYPES.has(msg.type) || CONTEXT_REQUEST_TYPES.has(msg.type) || PLUGIN_REQUEST_TYPES.has(msg.type) || msg.type === 'clawbot-control') && !ws.deviceId) {
                 sendFrame({ kind: 'error', code: 'authentication-required', requestType: msg.type,
                   ...(typeof msg.requestId === 'string' ? { requestId: msg.requestId } : {}),
                   message: msg.type === 'clawbot-control'
@@ -3242,6 +3332,7 @@ const plugin = {
                 onInstallStart: (requestId) => pluginInstallOwners.set(requestId, ws),
                 onInstallEnd: (requestId) => pluginInstallOwners.delete(requestId),
                 clawbotService,
+                hostContext: ctx,
               }).then((frame) => {
                 if (frame && ws.readyState === 1) ws.send(stringifyWireFrame(frame))
               })
@@ -3298,6 +3389,11 @@ const plugin = {
               'session-rename',
               ...(options.fileDownloadsEnabled ? ['file-downloads'] : []),
               ...(api.workspaceChanges ? ['workspace-changes-v1'] : []),
+              ...(api.account ? ['account-v1'] : []),
+              'cost-meter-v1',
+              'context-dashboard-v1',
+              'context-fleet-v1',
+              'context-content-v1',
             ],
             port: transport.port || webServer.port,
             clients: clients.size,

package/lib/plugin-updates.mjs

@@ -1,5 +1,6 @@
 export const PLUGIN_PACKAGE_NAME = 'dsh-plugin-weapp-gateway'
 const REGISTRY_LATEST_URL = `https://registry.npmjs.org/${PLUGIN_PACKAGE_NAME}/latest`
+const FAILED_INSTALL_STATES = new Set(['failed', 'cancelled', 'refused'])
 
 function errorField(value) {
   return typeof value === 'string' && value.trim() ? value.trim() : ''
@@ -22,6 +23,7 @@ export function formatPluginInstallError(error, depth = 0) {
     if (detail) return `${code && code !== detail ? `${code}: ` : ''}${detail}`.slice(0, 1000)
   }
 
+  if (code) return code
   try {
     const serialized = JSON.stringify(error, (key, value) => {
       if (/stack|authorization|cookie|password|secret|token|credential|api.?key/i.test(key)) return undefined
@@ -29,7 +31,28 @@ export function formatPluginInstallError(error, depth = 0) {
     })
     if (serialized && serialized !== '{}') return serialized.slice(0, 1000)
   } catch { /* use a generic message for cyclic or non-serializable errors */ }
-  return code || 'The plugin manager did not provide an error message'
+  return 'The plugin manager did not provide an error message'
+}
+
+function operationErrorCode(error, depth = 0) {
+  if (!error || typeof error !== 'object' || depth > 4) return ''
+  if (typeof error.code === 'string') return error.code
+  for (const nested of [error.error, error.cause, error.details]) {
+    const code = operationErrorCode(nested, depth + 1)
+    if (code) return code
+  }
+  return ''
+}
+
+function failedOperation(operation) {
+  return FAILED_INSTALL_STATES.has(operation?.application) || Boolean(operation?.error)
+}
+
+function operationMessage(operation) {
+  if (operation?.error) return formatPluginInstallError(operation.error)
+  return typeof operation?.message === 'string' && operation.message.trim()
+    ? operation.message.trim()
+    : `Plugin manager reported ${operation?.application || 'an unknown failure'}`
 }
 
 function parseVersion(value) {
@@ -97,11 +120,14 @@ export async function checkPluginUpdate({ currentVersion, fetchImpl = globalThis
   }
 }
 
-export async function installLatestPlugin({ api, currentVersion, fetchImpl = globalThis.fetch, requestId }) {
+export async function installLatestPlugin({ api, currentVersion, fetchImpl = globalThis.fetch, requestId, profileName }) {
   const update = await checkPluginUpdate({ currentVersion, fetchImpl })
   if (!update.updateAvailable) return { ...update, installed: false, reason: 'already-current' }
 
-  const command = `dsh plugin --profile web add ${PLUGIN_PACKAGE_NAME}@${update.latestVersion}`
+  const profile = typeof profileName === 'string' && /^[A-Za-z0-9._-]{1,80}$/.test(profileName)
+    ? profileName
+    : 'web'
+  const command = `dsh plugin --profile ${profile} add ${PLUGIN_PACKAGE_NAME}@${update.latestVersion}`
   let inventory
   try {
     inventory = await api.plugins.inventory()
@@ -112,16 +138,83 @@ export async function installLatestPlugin({ api, currentVersion, fetchImpl = glo
     return { ...update, installed: false, reason: 'plugin-manager-unavailable', command }
   }
 
-  const installation = await api.plugins.installBundle(
-    `${PLUGIN_PACKAGE_NAME}@${update.latestVersion}`,
-    { requestId },
-  )
-  const errorMessage = formatPluginInstallError(installation?.error)
+  let bundles
+  try {
+    bundles = await api.plugins.listBundles()
+  } catch (error) {
+    return { ...update, installed: false, reason: 'plugin-manager-unavailable', command, detail: error?.message }
+  }
+  if (!Array.isArray(bundles)) {
+    return { ...update, installed: false, reason: 'plugin-manager-unavailable', command }
+  }
+
+  const existing = bundles.find(bundle => bundle?.name === PLUGIN_PACKAGE_NAME && bundle.installed === true)
+  const installSpec = `${PLUGIN_PACKAGE_NAME}@${update.latestVersion}`
+  const installOptions = {
+    requestId,
+    saveExact: true,
+    ...(typeof existing?.enabled === 'boolean' ? { enabled: existing.enabled } : {}),
+  }
+
+  let removed = false
+  if (existing) {
+    if (typeof api.plugins.removeBundle !== 'function') {
+      return { ...update, installed: false, reason: 'plugin-manager-unavailable', command }
+    }
+
+    let removal
+    try {
+      removal = await api.plugins.removeBundle(PLUGIN_PACKAGE_NAME)
+    } catch (error) {
+      removal = { application: 'failed', error }
+    }
+
+    // Older hosts cannot hot-remove a running bundle; their package manager can still replace it for restart.
+    if (failedOperation(removal) && operationErrorCode(removal) !== 'stop-profile') {
+      return {
+        ...update,
+        installed: true,
+        installation: {
+          ...removal,
+          application: FAILED_INSTALL_STATES.has(removal?.application) ? removal.application : 'failed',
+          errorMessage: operationMessage(removal),
+        },
+      }
+    }
+    removed = !failedOperation(removal)
+  }
+
+  let installation
+  try {
+    installation = await api.plugins.installBundle(installSpec, installOptions)
+  } catch (error) {
+    installation = { application: 'failed', error }
+  }
+
+  let errorMessage = ''
+  if (failedOperation(installation) && removed) {
+    const previousSpec = typeof existing.source === 'string' && existing.source
+      ? existing.source
+      : `${PLUGIN_PACKAGE_NAME}@${currentVersion}`
+    try {
+      const recovery = await api.plugins.installBundle(previousSpec, {
+        ...(typeof existing.enabled === 'boolean' ? { enabled: existing.enabled } : {}),
+      })
+      errorMessage = failedOperation(recovery)
+        ? `Update failed: ${operationMessage(installation)}. Restoring the previous version also failed: ${operationMessage(recovery)}`
+        : `Update failed: ${operationMessage(installation)}. The previous version was restored.`
+      installation = { ...installation, recovery }
+    } catch (error) {
+      errorMessage = `Update failed: ${operationMessage(installation)}. Restoring the previous version also failed: ${formatPluginInstallError(error)}`
+    }
+  }
+
+  const detail = errorMessage || (installation?.error ? formatPluginInstallError(installation.error) : '')
   return {
     ...update,
     installed: true,
-    installation: errorMessage && installation && typeof installation === 'object'
-      ? { ...installation, errorMessage }
+    installation: detail && installation && typeof installation === 'object'
+      ? { ...installation, errorMessage: detail }
       : installation,
   }
 }

package/lib/vendor/cost-meter/aliyun-balance.mjs

@@ -0,0 +1,123 @@
+/** 千问 / 阿里云资金账户可用金（issue #98）。凭据仅用于服务端 ACS3 签名。 */
+import { createHash, createHmac, randomUUID } from 'node:crypto'
+import { credentialRef } from './credentials-shim.mjs'
+import { fetchWithRetry } from './net.mjs'
+
+// API shape/endpoint: aliyun/alibabacloud-typescript-sdk, bssopenapi-20230930.
+// Signature: https://help.aliyun.com/zh/sdk/product-overview/v3-request-structure-and-signature
+export const ALIYUN_BALANCE_URL = 'https://business.aliyuncs.com/'
+export const ALIYUN_BALANCE_CREDENTIAL_VARS = [
+  'ALIBABA_CLOUD_ACCESS_KEY_ID',
+  'ALIBABA_CLOUD_ACCESS_KEY_SECRET',
+  'ALIBABA_CLOUD_SECURITY_TOKEN',
+]
+const MAX_BYTES = 262144
+const hash = value => createHash('sha256').update(value).digest('hex')
+
+export function signAliyunBalanceRequest(accessKeyId, accessKeySecret, securityToken = '', { now = new Date(), nonce = randomUUID() } = {}) {
+  const headers = {
+    'content-type': 'application/x-www-form-urlencoded',
+    host: 'business.aliyuncs.com',
+    'x-acs-action': 'GetFundAccountAvailableAmount',
+    'x-acs-content-sha256': hash(''),
+    'x-acs-date': now.toISOString().replace(/\.\d{3}Z$/, 'Z'),
+    'x-acs-signature-nonce': nonce,
+    'x-acs-version': '2023-09-30',
+  }
+  if (securityToken) headers['x-acs-security-token'] = securityToken
+  const keys = Object.keys(headers).sort()
+  const signedHeaders = keys.join(';')
+  const canonicalHeaders = keys.map(key => `${key}:${headers[key].trim()}\n`).join('')
+  const canonical = ['POST', '/', '', canonicalHeaders, signedHeaders, hash('')].join('\n')
+  const signature = createHmac('sha256', accessKeySecret).update(`ACS3-HMAC-SHA256\n${hash(canonical)}`).digest('hex')
+  headers.Authorization = `ACS3-HMAC-SHA256 Credential=${accessKeyId},SignedHeaders=${signedHeaders},Signature=${signature}`
+  headers.Accept = 'application/json'
+  return { method: 'POST', headers, body: '', redirect: 'manual' }
+}
+
+const messages = {
+  zh: {
+    missing: '请配置阿里云 RAM AccessKey ID 和 AccessKey Secret（不是千问模型 API Key）',
+    network: '阿里云余额网络请求失败，请稍后重试',
+    redirect: '阿里云余额接口发生重定向，已拒绝转发凭据',
+    permission: '阿里云余额鉴权失败，请检查 AccessKey、STS 有效期及 RAM 权限 bss:DescribeBillingAccount',
+    http: '阿里云余额接口返回 HTTP {status}',
+    payload: '阿里云余额响应无效或过大，请稍后重试',
+    amount: '阿里云余额响应缺少有效的 AvailableAmount，未将其视为零余额',
+    currency: '阿里云余额响应缺少受支持的币种（CNY / USD / EUR）',
+  },
+  en: {
+    missing: 'Configure Alibaba Cloud RAM AccessKey ID and AccessKey Secret (not a Qianwen model API key)',
+    network: 'Alibaba Cloud balance network request failed; please retry later',
+    redirect: 'Alibaba Cloud balance redirect refused to protect credentials',
+    permission: 'Alibaba Cloud balance authentication failed; check AccessKey, STS expiry and RAM permission bss:DescribeBillingAccount',
+    http: 'Alibaba Cloud balance returned HTTP {status}',
+    payload: 'Alibaba Cloud balance response is invalid or too large; please retry later',
+    amount: 'Alibaba Cloud balance response has no valid AvailableAmount; it was not treated as zero',
+    currency: 'Alibaba Cloud balance response has no supported currency (CNY / USD / EUR)',
+  },
+}
+const failure = (locale, key, status = '') => new Error(messages[locale === 'en' ? 'en' : 'zh'][key].replace('{status}', String(status)))
+
+export function parseAliyunBalance(data, locale = 'zh') {
+  const raw = data?.AvailableAmount
+  const text = typeof raw === 'string' ? raw.trim() : ''
+  const amount = typeof raw === 'number' ? raw : /^[+-]?\d+(\.\d+)?$/.test(text) ? Number(text) : NaN
+  if (!Number.isFinite(amount)) throw failure(locale, 'amount')
+  if (!['CNY', 'USD', 'EUR'].includes(data?.Currency)) throw failure(locale, 'currency')
+  // AvailableAmount 是可用金，包含信控/未结清款等因素；不能把它当成现金余额或消费额。
+  return { remaining: amount, unit: data.Currency, maxBudget: null, spend: null }
+}
+
+async function resolveCredential(ctx, name) {
+  try {
+    const hit = await ctx?.get?.('credentials')?.resolve(credentialRef(name))
+    if (typeof hit?.value === 'string' && hit.value.trim()) return hit.value.trim()
+  } catch { /* 与现有余额 adapter 一致，回落环境变量。 */ }
+  return String(process.env[name] ?? '').trim()
+}
+
+async function readPayload(response, locale) {
+  if (Number(response.headers.get('content-length')) > MAX_BYTES) {
+    await response.body?.cancel().catch(() => {})
+    throw failure(locale, 'payload')
+  }
+  try {
+    const parts = []
+    let bytes = 0
+    for await (const part of response.body) {
+      bytes += part.length
+      if (bytes > MAX_BYTES) throw failure(locale, 'payload')
+      parts.push(part)
+    }
+    return JSON.parse(Buffer.concat(parts).toString('utf8'))
+  } catch { throw failure(locale, 'payload') }
+}
+
+export async function queryAliyunBalance(ctx, config, { fetchImpl = fetch, signal } = {}) {
+  signal?.throwIfAborted()
+  const locale = config?.locale
+  const [ak, sk, token] = await Promise.all(ALIYUN_BALANCE_CREDENTIAL_VARS.map(name => resolveCredential(ctx, name)))
+  if (!ak || !sk) throw Object.assign(failure(locale, 'missing'), { soft: true })
+  let response
+  try {
+    // 每次网络重试重新生成时间戳与 nonce；URL、Action、body 均固定为只读账户查询。
+    response = await fetchWithRetry(ALIYUN_BALANCE_URL, { signal }, {
+      attempts: 2, timeoutMs: 15000,
+      fetchImpl: (url, init) => fetchImpl(url, { ...signAliyunBalanceRequest(ak, sk, token), signal: init.signal }),
+    })
+  } catch {
+    signal?.throwIfAborted()
+    throw failure(locale, 'network')
+  }
+  if (!response.ok) {
+    await response.body?.cancel().catch(() => {})
+    if (response.status >= 300 && response.status < 400) throw failure(locale, 'redirect')
+    if (response.status === 401 || response.status === 403) throw failure(locale, 'permission')
+    throw failure(locale, 'http', response.status)
+  }
+  const data = await readPayload(response, locale)
+  // 不把上游 Message/RequestId/账户身份下发浏览器；即使错误响应夹带余额也不能记作成功。
+  if ((data?.Code && data.Code !== 'Success') || data?.Success === false) throw failure(locale, 'permission')
+  return { label: config?.customBalance?.label || '千问 / 阿里云', ...parseAliyunBalance(data, locale) }
+}