@cloudbase/manager-node 5.8.9-beta.0 → 5.9.0

package/lib/error-docs.js

@@ -0,0 +1,385 @@
+"use strict";
+/**
+ * 错误码 → 文档链接 映射
+ *
+ * 用途：报错时自动关联到对应的错误码指引文档，让用户能直接跳转查看。
+ * 在 CloudBaseError 构造与 errorHandler 汇聚处统一调用 resolveErrorDoc(code, source)，
+ * 避免在每个命令里散落手写 docs 链接（容易覆盖不全、口径不一致）。
+ *
+ * ## 来源分流（source）
+ *
+ * 消费方收到四类来源的 code，必须按来源选择不同的文档：
+ *
+ * | source | 含义 | 文档 |
+ * |---|---|---|
+ * | `cloud-api` | 控制面云 API 原始 code（876/34823） | 腾讯云《云开发 CloudBase 错误码》 |
+ * | `runtime` | 数据面错误码（`tcberror.go`，源自 `error-code/basic`） | 单码页 `error-code/{CODE}` |
+ * | `manager-node` | SDK 本地校验/构建自定义 code | 部署模块页（未登记时软降级） |
+ * | `cli` / `toolbox` | CLI / toolbox 本地语义码 | 待登记 |
+ *
+ * **为什么必须分流**：CLI 本地码与数据面码大量重名（`INVALID_PARAM` / `INVALID_OPERATION` /
+ * `RESOURCE_NOT_FOUND` / `CHECK_LOGIN_FAILED` / `FUNCTION_NOT_FOUND` 共 5 个），
+ * 单靠 code 无法判断该指向哪张文档。这是 AIP-193 `(reason, domain)` 二元组的落地
+ * （见《错误码治理方案》§4.3）。同时也解释了为何不能把 `INVALID_` / `AUTH_`
+ * 这类宽泛前缀加进「无 source」的宽松匹配路径。
+ *
+ * ## 数据面码表来源
+ *
+ * `RUNTIME_ERROR_CODES` 逐条摘录自 `cloudbase-docs/docs/error-code/basic.md`，
+ * 与服务端事实源 `tcblinker/internal/tcberror/tcberror.go` 对齐。
+ * 建议在 CI 中加入与 `basic.md` 的 diff 校验（见治理方案 §6.4），防止再次漂移。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RUNTIME_ERROR_CODES = exports.RUNTIME_ERROR_CODE_DOC_BASE = exports.RUNTIME_ERROR_DOC = exports.CONTROL_PLANE_ERROR_DOC = void 0;
+exports.resolveErrorDoc = resolveErrorDoc;
+/** 控制面云 API 错误码文档（腾讯云云开发 CloudBase 错误码） */
+exports.CONTROL_PLANE_ERROR_DOC = 'https://cloud.tencent.com/document/product/876/34823';
+/** 数据面错误码总览页（分类索引） */
+exports.RUNTIME_ERROR_DOC = 'https://docs.cloudbase.net/error-code/basic';
+/** 数据面单码页 URL 前缀：最终形如 `${BASE}/${CODE}` */
+exports.RUNTIME_ERROR_CODE_DOC_BASE = 'https://docs.cloudbase.net/error-code';
+/**
+ * 控制面云 API 公共错误码（来源：876/34823「公共错误码」章节）。
+ * 匹配策略：先精确匹配，再取 code 第一个 '.' 前的基段匹配，
+ * 从而覆盖 AuthFailure.SignatureFailure、FailedOperation.PGExecuteSqlError 等子错误码。
+ */
+const CONTROL_PLANE_CODES = new Set([
+    // 公共错误码
+    'ActionOffline',
+    'AuthFailure',
+    'AuthFailure.InvalidAuthorization',
+    'AuthFailure.InvalidSecretId',
+    'AuthFailure.MFAFailure',
+    'AuthFailure.SecretIdNotFound',
+    'AuthFailure.SignatureExpire',
+    'AuthFailure.SignatureFailure',
+    'AuthFailure.TokenFailure',
+    'AuthFailure.UnauthorizedOperation',
+    'DryRunOperation',
+    'FailedOperation',
+    'InternalError',
+    'InvalidAction',
+    'InvalidParameter',
+    'InvalidParameterValue',
+    'InvalidRequest',
+    'IpInBlacklist',
+    'IpNotInWhitelist',
+    'LimitExceeded',
+    'MissingParameter',
+    'NoSuchProduct',
+    'NoSuchVersion',
+    'RequestLimitExceeded',
+    'RequestSizeLimitExceeded',
+    'ResourceInUse',
+    'ResourceInsufficient',
+    'ResourceNotFound',
+    'ResourceUnavailable',
+    'ResponseSizeLimitExceeded',
+    'ServiceUnavailable',
+    'UnauthorizedOperation',
+    'UnknownParameter',
+    'UnsupportedOperation',
+    'UnsupportedProtocol',
+    'UnsupportedRegion',
+    // 业务错误码（顶层前缀，覆盖带 '.' 的子错误码）
+    'OperationDenied',
+    'ResourcesSoldOut'
+]);
+/**
+ * 数据面（运行时）错误码全量清单。
+ *
+ * 来源：`cloudbase-docs/docs/error-code/basic.md`（131 个），
+ * 与服务端事实源 `tcblinker/internal/tcberror/tcberror.go` 对齐。
+ * 每个码在文档站都有独立页面：`https://docs.cloudbase.net/error-code/{CODE}`。
+ *
+ * ⚠️ 仅在 `source === 'runtime'` 时使用本表。因为其中 `INVALID_*`（21 个）、
+ * `AUTH_*` 等与 CLI 本地语义码重名，无 source 时不可参与匹配。
+ */
+exports.RUNTIME_ERROR_CODES = new Set([
+    'ACCESS_DENIED',
+    'ACCESS_TOKEN_DISABLED',
+    'ACCESS_TOKEN_EXPIRED',
+    'ACCESS_TOKEN_INVALID',
+    'ACCESS_TOKEN_KID_INVALID',
+    'ACTION_FORBIDDEN',
+    'AI_MODEL_CONFIG_MISSING',
+    'AI_MODEL_DISABLED',
+    'AI_MODEL_NOT_FOUND',
+    'AI_MODEL_NOT_SUPPORTED',
+    'AI_MODEL_PARAM_REQUIRED',
+    'APIS_GET_OPENAPI_SCHEMA_ERROR',
+    'APIS_PARSE_OPENAPI_SCHEMA_ERROR',
+    'APIS_PROCESS_AUTH_ERROR',
+    'APIS_PROCESS_SELF_DEFINE_VARIABLE_ERROR',
+    'APP_SIGN_EXPIRED',
+    'AUTHENTICATION_FAILED',
+    'AUTH_CUSTOM_USER_ID_HAS_BEEN_BOUND',
+    'AUTH_EMAIL_HAS_BEEN_BOUND',
+    'AUTH_INVALID_CUSTOM_LOGIN_TICKET',
+    'AUTH_LOGIN_FAILED',
+    'AUTH_OPEN_ID_HAS_BEEN_BOUND',
+    'AUTH_UNION_ID_HAS_BEEN_BOUND',
+    'AUTH_WX_OAUTH_FAILED',
+    'BAD_GATEWAY',
+    'BAD_REQUEST',
+    'CDN_INVALID_SIGNATURE',
+    'CDN_SIGNATURE_EXPIRED',
+    'CDN_SIGNATURE_MISSING',
+    'CHECK_LOGIN_FAILED',
+    'COS_ACTION_FAILED',
+    'DATABASE_COLLECTION_ALREADY_EXIST',
+    'DATABASE_COLLECTION_EXCEED_LIMIT',
+    'DATABASE_COLLECTION_NOT_EXIST',
+    'DATABASE_DUPLICATE_WRITE',
+    'DATABASE_INVALID_OPERRATOR',
+    'DATABASE_PERMISSION_DENIED',
+    'DATABASE_REQUEST_FAILED',
+    'DATABASE_TIMEOUT',
+    'DATABASE_TRANSACTION_CONFLICT',
+    'DATABASE_TRANSACTION_FAIL',
+    'DEFAULT_DOMAIN_EXPIRED',
+    'ENV_ABNORMAL',
+    'ENV_FEATURE_NOT_CONFIGURED',
+    'ENV_NOT_READY',
+    'ERR_ABORT_HANDLER',
+    'EXCEED_AUTHORITY',
+    'EXCEED_CONCURRENT_REQUEST_LIMIT',
+    'EXCEED_MAX_PAYLOAD_SIZE',
+    'EXCEED_MAX_RESPONSE_SIZE',
+    'EXCEED_RATELIMIT',
+    'EXCEED_REQUEST_LIMIT',
+    'EXCEED_REQUEST_SIZE_LIMIT',
+    'EXCEED_TOKEN_QUOTA_LIMIT',
+    'EXCEED_UPLOAD_MAXFILESIZE',
+    'FUNCTIONS_EXECUTE_FAIL',
+    'FUNCTIONS_MEMORY_LIMIT_EXCEEDED',
+    'FUNCTIONS_STATUS_ABNORMITY',
+    'FUNCTIONS_TIME_LIMIT_EXCEEDED',
+    'FUNCTION_EXCEED_RESOURCE_LIMIT',
+    'FUNCTION_EXECUTE_FAIL',
+    'FUNCTION_INVOCATION_FAILED',
+    'FUNCTION_MEMORY_LIMIT_EXCEEDED',
+    'FUNCTION_NOT_FOUND',
+    'FUNCTION_PARAM_INVALID',
+    'FUNCTION_QUALIFIER_NOT_FOUND',
+    'FUNCTION_STATUS_ABNORMAL',
+    'FUNCTION_TIME_LIMIT_EXCEEDED',
+    // D21：平台已统一为复数形式（文档站共 13 个）—— 补齐此前遗漏的 9 个。
+    // 单数形式**不删**：微搭 qbase-service / wxapi 与 CLI 自身仍可能产出单数（见治理方案 §5.6）。
+    'FUNCTIONS_NOT_FOUND', // 云函数未找到
+    'FUNCTIONS_INVOCATION_FAILED', // 调用云函数超时或失败
+    'FUNCTIONS_QUALIFIER_NOT_FOUND', // 指定访问的函数版本不存在
+    'FUNCTIONS_STATUS_ABNORMAL', // 函数状态异常
+    'FUNCTIONS_PARAM_INVALID', // 调用函数的参数异常
+    'FUNCTIONS_EXCEED_RESOURCE_LIMIT', // 请求频率超过函数预置并发
+    'FUNCTIONS_NAME_MISSING', // 调用时未指定函数名
+    'FUNCTIONS_PERMISSION_DENIED', // 无权限调用该云函数
+    'FUNCTIONS_RESERVED_PATH', // 使用了云函数保留路径
+    'HTTPSERVICE_NONACTIVATED',
+    'INTERNAL_REQUEST_FAIL',
+    'INVALID_ACCESS_TOKEN',
+    'INVALID_ACTION',
+    'INVALID_APPID',
+    'INVALID_APP_ACCESS',
+    'INVALID_APP_SIGN',
+    'INVALID_COMMON_PARAM',
+    'INVALID_CREDENTIALS',
+    'INVALID_EMAIL_TOKEN',
+    'INVALID_ENV',
+    'INVALID_ENV_SOURCE',
+    'INVALID_ENV_STATUS',
+    'INVALID_HOST',
+    'INVALID_OPERATION',
+    'INVALID_PARAM',
+    'INVALID_PATH',
+    'INVALID_REFRESH_TOKEN',
+    'INVALID_REGION',
+    'INVALID_REQUEST',
+    'INVALID_REQUEST_SOURCE',
+    'INVALID_THIRDAPP_STATUS',
+    'INVALID_WX_ACCESS_TOKEN',
+    'LOGIN_MANNER_UNREGISTED',
+    'MISSING_CREDENTIALS',
+    'OBJECT_ALREADY_EXIST',
+    'OBJECT_BATCH_TOO_LARGE',
+    'OBJECT_NOT_EXIST',
+    'PERMISSION_DENIED',
+    'PHONE_CODE_NOTFOUND_OR_EXPIRED',
+    'PHONE_CODE_NOT_MATCHED',
+    'PHONE_CODE_SEND_LIMIT_EXCEED',
+    'REFRESH_TOKEN_DISABLED',
+    'REFRESH_TOKEN_EXHAUSTED',
+    'REFRESH_TOKEN_EXPIRED',
+    'REQUEST_CANCELED',
+    'REQUEST_FORBIDDEN',
+    'RESOURCE_NOT_FOUND',
+    'RESOURCE_NOT_INITIAL',
+    'RequestLimitExceeded',
+    'SERVER_TIMEOUT',
+    'SERVICE_CHARGE_OVERDUE',
+    'SERVICE_ENDPOINT_NOT_FOUND',
+    'SERVICE_FORBIDDEN',
+    'SERVICE_LB_STATUS_ABNORMAL',
+    'SERVICE_NOT_FOUND',
+    'SERVICE_NOT_READY',
+    'SERVICE_RESOURCE_NOT_FOUND',
+    'SERVICE_TIMEOUT',
+    'SERVICE_VERSION_NOT_FOUND',
+    'SIGN_PARAM_INVALID',
+    'STATIC_RESOURCE_NONACTIVATED',
+    'STATIC_RESOURCE_REQUESTS_FAILED',
+    'STATIC_RESOURCE_TOO_MANY_REDIRECTS',
+    'STORAGE_EXCEED_AUTHORITY',
+    'STORAGE_FILE_NONEXIST',
+    'STORAGE_FILE_PATH_CONFLICT',
+    'STORAGE_REQUEST_FAIL',
+    'STORAGE_SIGN_PARAM_INVALID',
+    'SYS_ERR',
+    'UNSUPPORTED_AUTH_TYPE',
+    'WX_HEADER_GET_FAILED',
+    'WX_WEBSOCKET_TOKEN_EXPIRED'
+]);
+/**
+ * 数据面模块前缀（仅 `source === 'runtime'` 时生效）。
+ *
+ * 作用：兜住 RUNTIME_ERROR_CODES 尚未收录的**新增**数据面码，
+ * 让它们至少能落到总览页，而不是哑火。已收录的码走单码页精确链接。
+ */
+const RUNTIME_ERROR_MODULE_PREFIXES = [
+    'SYS_',
+    'DATABASE_',
+    'STORAGE_',
+    'FUNCTIONS_',
+    'FUNCTION_',
+    'STATIC_',
+    'CLOUDRUN_',
+    'SERVICE_',
+    'AI_MODEL_',
+    'APIS_',
+    'AUTH_',
+    'ACCESS_TOKEN_',
+    'REFRESH_TOKEN_',
+    'PHONE_CODE_',
+    'WX_',
+    'OBJECT_',
+    'COS_',
+    'CDN_',
+    'ENV_'
+];
+/**
+ * 无 source 时的宽松匹配前缀（**历史行为，勿扩展**）。
+ *
+ * 仅保留「服务模块」级前缀，避免与 CLI 语义码（AUTH_FAILED / INVALID_PARAM /
+ * RESOURCE_NOT_FOUND 等，同样为下划线大写命名）冲突。
+ * 新增前缀请加到 RUNTIME_ERROR_MODULE_PREFIXES（受 source 保护）。
+ */
+const RUNTIME_ERROR_PREFIXES = [
+    'SYS_', // 系统内部异常
+    'DATABASE_', // 数据库
+    'STORAGE_', // 云存储
+    'FUNCTIONS_', // 云函数
+    'STATIC_', // 静态托管
+    'CLOUDRUN_' // 云托管
+];
+/**
+ * manager-node 部署自定义码 → 文档页（软降级白名单）。
+ *
+ * 文档站尚未登记这些码（治理方案 D5）。登记后把 `ready` 置 true 即可自动
+ * 切换为精确锚点，无需改动逻辑；未 ready 时不返回链接（`MANAGER_NODE_DOC_FALLBACK`），
+ * 避免指向不存在的页面产生 404。
+ */
+const MANAGER_NODE_DOC_BASE = 'https://docs.cloudbase.net/error-code';
+/** 未登记时的回落值：空串表示「没有可跳转的页面」，优于给出误导性链接 */
+const MANAGER_NODE_DOC_FALLBACK = '';
+const MANAGER_NODE_DOC_PAGES = [
+    { prefix: '', slug: 'manager-node', ready: true }
+];
+/** 控制面：精确匹配 + 基段匹配（取 '.' 前段） */
+function resolveControlPlaneDoc(codeStr) {
+    const baseCode = codeStr.split('.')[0];
+    if (CONTROL_PLANE_CODES.has(codeStr) || CONTROL_PLANE_CODES.has(baseCode)) {
+        return exports.CONTROL_PLANE_ERROR_DOC;
+    }
+    return '';
+}
+/** 数据面：精确码 → 单码页；未知码按模块前缀兜底到总览页 */
+function resolveRuntimeDoc(codeStr) {
+    if (exports.RUNTIME_ERROR_CODES.has(codeStr)) {
+        return `${exports.RUNTIME_ERROR_CODE_DOC_BASE}/${codeStr}`;
+    }
+    if (RUNTIME_ERROR_MODULE_PREFIXES.some((prefix) => codeStr.startsWith(prefix))) {
+        return exports.RUNTIME_ERROR_DOC;
+    }
+    return '';
+}
+/** manager-node 自定义码：按前缀族查模块页；未登记时软降级 */
+function resolveManagerNodeDoc(codeStr) {
+    // 仅对**自造码形态**给链接；平台码 / 带子码形态不产生无意义锚点
+    if (!SELF_CODE_PATTERN.test(codeStr) || codeStr.length > 63 || codeStr.endsWith('_')) {
+        return '';
+    }
+    const page = MANAGER_NODE_DOC_PAGES.find((item) => codeStr.startsWith(item.prefix));
+    if (!page) {
+        return MANAGER_NODE_DOC_FALLBACK;
+    }
+    // 未登记（ready=false）时不返回链接，避免 404
+    // 锚点用小写码名（登记页 heading ID 约定：`{#config_invalid}`）
+    return page.ready
+        ? `${MANAGER_NODE_DOC_BASE}/${page.slug}#${codeStr.toLowerCase()}`
+        : MANAGER_NODE_DOC_FALLBACK;
+}
+/** CLI / toolbox 本地语义码：文档站尚未登记对应页面（治理方案 D5） */
+/** 自造码形态：UPPER_SNAKE_CASE、≤63、不以 `_` 结尾（与 error.ts 的 isValidErrorCode 同口径） */
+const SELF_CODE_PATTERN = /^[A-Z][A-Z0-9_]*$/;
+/**
+ * CLI / toolbox 本地语义码 → **分层登记页**锚点（`/error-code/{cli,toolbox}#<小写码名>`）。
+ *
+ * 文档站已按层登记这些自造码；**非自造码形态**（如平台码被误标本层）不返回链接。
+ */
+function resolveLayerDoc(layer, codeStr) {
+    if (!SELF_CODE_PATTERN.test(codeStr) || codeStr.length > 63 || codeStr.endsWith('_')) {
+        return '';
+    }
+    return `${MANAGER_NODE_DOC_BASE}/${layer}#${codeStr.toLowerCase()}`;
+}
+/**
+ * 根据错误码解析对应的文档链接。
+ *
+ * @param code 错误码（可能是语义 code、云 API code，或带 '.' 的子错误码）
+ * @param source 错误来源层（见 ErrorSource）。传入时按来源精确分流；
+ *               不传时保持历史宽松匹配（控制面精确 + 6 个模块前缀），向后兼容。
+ * @returns 文档链接；无法归类时返回空串（由调用方决定是否兜底）
+ */
+function resolveErrorDoc(code, source) {
+    if (code === null || code === undefined) {
+        return '';
+    }
+    const codeStr = String(code);
+    if (!codeStr) {
+        return '';
+    }
+    // 已知来源：按来源分流，避免跨层重名码误判
+    switch (source) {
+        case 'runtime':
+            return resolveRuntimeDoc(codeStr);
+        case 'cloud-api':
+            return resolveControlPlaneDoc(codeStr);
+        case 'manager-node':
+            return resolveManagerNodeDoc(codeStr);
+        case 'cli':
+            return resolveLayerDoc('cli', codeStr);
+        case 'toolbox':
+            return resolveLayerDoc('toolbox', codeStr);
+        default:
+            break;
+    }
+    // 无来源（向后兼容）：维持历史行为 —— 先控制面，再 6 个运行时模块前缀
+    const controlPlane = resolveControlPlaneDoc(codeStr);
+    if (controlPlane) {
+        return controlPlane;
+    }
+    if (RUNTIME_ERROR_PREFIXES.some((prefix) => codeStr.startsWith(prefix))) {
+        return exports.RUNTIME_ERROR_DOC;
+    }
+    return '';
+}

package/lib/error-types.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERROR_TYPES = void 0;
+/**
+ * 抛错「标准错误类型」表（manager-node 层）
+ *
+ * ⚠️ **自有码的唯一来源**：code 字面量只允许出现在本文件（helper 与显式 throw 都引用这里）。
+ *    source **不在本表**：由各仓构造器按本层注入（避免跨仓复制时串层）。
+ *
+ * 用法（两种写法语义等价）：
+ *   throw new CloudBaseError(message, { type: ERROR_TYPES.invalidParam })   // 显式 throw ✓
+ *   throwInvalidParam(message)                                              // 短形态 ✓
+ */
+exports.ERROR_TYPES = {
+    invalidParam: { code: 'INVALID_PARAM' },
+    notFound: { code: 'NOT_FOUND' },
+    netError: { code: 'NETWORK_ERROR' },
+    apiError: { code: 'API_ERROR' },
+    credentialError: { code: 'MISSING_CREDENTIAL' },
+    fileError: { code: 'FILE_READ_ERROR' }
+};

package/lib/error.js

@@ -1,17 +1,254 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CloudBaseError = void 0;
+exports.isCloudBaseError = isCloudBaseError;
+exports.isValidErrorCode = isValidErrorCode;
+exports.isErrorSource = isErrorSource;
+exports.errorSourceOf = errorSourceOf;
+exports.throwInvalidParam = throwInvalidParam;
+exports.throwNotFound = throwNotFound;
+exports.throwNetError = throwNetError;
+exports.throwApiError = throwApiError;
+exports.throwCredentialError = throwCredentialError;
+exports.throwFileError = throwFileError;
+/**
+ * 错误来源层（五类 code 来源，与 CLI / toolbox ErrorSource 对齐）
+ * - cloud-api：控制面云 API 原始 code（876/34823）
+ * - runtime：运行时错误码（error-code/basic）
+ * - manager-node：SDK 本地校验/构建自定义 code
+ * - cli：CLI 本地语义 code
+ * - toolbox：底层 @cloudbase/toolbox 本地 code
+ */
+const error_docs_1 = require("./error-docs");
+const error_types_1 = require("./error-types");
+/**
+ * ## `code` 与 `source` 的两条硬规则（2026-09-20 确立）
+ *
+ * **规则 1：原本无 `code` → 必须补；已有 `code` → 一律不变。**
+ * `code` 是机器契约（驱动消费层 `exitCode`、在 `--json` 暴露、是埋点与文档锚点的键），
+ * 改它等于破坏下游判断。
+ *
+ * > **批量改 `code` 前必跑「已发布影响审计」**：被改动的**原始行**是否存在于**上一个发布 tag**
+ * > 的同名文件中 ⇒ 判断是否动了**已发布给用户**的行为。
+ *
+ * **规则 2：`source` 必须与 `code` 的`归属`配套。**
+ * - 包装点**自造** `code`（本层语义）→ `source: 'manager-node'`（本层即 domain）
+ * - 包装点**沿用上游** `code`（`e.code || '<FALLBACK>'`）→ `source` 继承上游来源层
+ *
+ * 反例（禁止）：自造的 `code` 配上**上游**的 `source` —— `(reason, domain)` 二元组失真（AIP-193）。
+ */
+/**
+ * CloudBase SDK（manager-node）标准化错误类。
+ *
+ * 对齐 CLI 的 CloudBaseError 对象模型：code（稳定语义码）+ message（调试信息）+
+ * source（来源层）+ original（cause 链）+ requestId/action（诊断信息）+
+ * meta（结构化载荷 —— 多项失败明细见 `meta.failures`）。
+ * 差异：SDK 层无 exitCode（进程退出码是 CLI 概念），message 自动加 [action] 前缀（CLI 依赖）。
+ */
 class CloudBaseError extends Error {
     constructor(message, options = {}) {
         super();
         this.name = 'CloudBaseError';
-        const { code = '', action = '', original = null, requestId = '', meta } = options;
+        // 防御：本仓是「被 CLI / MCP / **第三方**直接依赖的公共中间层」，第三方构建链不在我们控制内。
+        // 若被降级编译到 ES5，`extends Error` 会丢失原型链（`toJSON()` 等原型成员消失、`instanceof`
+        // 失效）⇒ 运行时把原型钉回本类。
+        // （我们自己的 cloudbase-cli / @cloudbase/cloudbase-mcp 均为 `target: node` + ts-loader，不降级，
+        //   故该调用在现代链上是 no-op；toolbox 因只支持 Node 已移除同款补丁。）
+        Object.setPrototypeOf(this, CloudBaseError.prototype);
+        const { type, code = '', action = '', original = null, requestId = '', meta, source = '', docs } = options;
         this.message = action ? `[${action}] ${message}` : message;
         this.original = original;
-        this.code = code;
+        // 标准类型优先：type 存在时 code / source 由它决定 ⇒ 与 helper 同一保证（调用方无法覆盖）
+        this.code = type ? type.code : code;
         this.requestId = requestId;
         this.action = action;
         this.meta = meta;
+        this.source = type ? 'manager-node' : source;
+        // §4.8：MN 是「被 CLI / MCP / 第三方直接依赖的公共中间层」——在这里挂上 docs，
+        // 所有消费方零成本获得；`opts.docs` 可覆盖
+        this.docs = docs !== null && docs !== void 0 ? docs : (0, error_docs_1.resolveErrorDoc)(this.code, this.source);
+    }
+    /**
+     * 标准 `Error.cause` 视图（ES2022）。
+     *
+     * 与 `original` **同源**（不重复存储，仅暴露标准视图）：
+     * - `original` **保留**，因为已有 8 处调用点依赖它访问上游 SDK 错误
+     *   （`.Code` / `.Message` / `.RequestId` / `.Response`）；
+     * - 额外提供 `cause` 是为了对齐标准 —— Node 等工具链会**自动打印 cause 链**，
+     *   且与 `AggregateError` 兼容。
+     */
+    get cause() {
+        var _a;
+        // `original` 缺省为 null（本仓与 toolbox），归一化为 undefined 以对齐 `Error.cause` 语义
+        return (_a = this.original) !== null && _a !== void 0 ? _a : undefined;
+    }
+    /**
+     * 转为 JSON 错误结构（对齐 CLI CloudBaseError.toJSON）
+     * 格式：{ error: { code, message, stack?, requestId?, action?, source?, docs?, meta? } }
+     */
+    toJSON() {
+        // ⚠️ 不能写 `this.code || 'ERROR'`：数值 0 会被 `||` 吞成 'ERROR'。
+        // 本仓 `code` 允许 `string | number`（控制面 / 数据面平台码由 `data.Response.Error.Code`
+        // 直通，形态不受我们控制）⇒ 数值码不能被当作假值丢弃。
+        // ⚠️ 这里**在输出层归一化为字符串**：与 CLI 的 toJSON 口径一致，消费方（--json / 埋点 / MCP）
+        // 按 code 聚合时，同一个码不会因类型不同裂成两个 key。**对象上的 `code` 仍保持保真**。
+        // ⚠️ NaN / Infinity 不是合法码：放行会让 `JSON.stringify` 输出 `null`
+        // （消费方看到「有 code 字段但值为空」），故先过 `Number.isFinite` 再决定。
+        let code = 'ERROR';
+        if (typeof this.code === 'number') {
+            code = Number.isFinite(this.code) ? String(this.code) : 'ERROR';
+        }
+        else if (this.code) {
+            code = this.code;
+        }
+        const err = {
+            code,
+            message: this.message
+        };
+        // 抛出点：不带 stack 时，错误经 SDK → CLI → 上报体跨层后无法定位原始抛出位置
+        if (this.stack)
+            err.stack = this.stack;
+        if (this.requestId)
+            err.requestId = this.requestId;
+        if (this.action)
+            err.action = this.action;
+        if (this.source)
+            err.source = this.source;
+        // 文档链接：消费方（CLI / MCP / 第三方）可直接读取，无需各自维护码表
+        if (this.docs)
+            err.docs = this.docs;
+        // 结构化载荷（含多项失败的 meta.failures）必须进上报体，否则埋点只能看到一个码；
+        // 但**绝不能让它把「构造上报体」这件事搞崩**：meta 里可能有循环引用 / BigInt，
+        // 直接 JSON.stringify(err) 会抛（Converting circular structure / Do not know how to serialize a BigInt）
+        if (this.meta && Object.keys(this.meta).length) {
+            try {
+                JSON.stringify(this.meta);
+                err.meta = this.meta;
+            }
+            catch (_a) {
+                // 降级：保留「有载荷但不可序列化」这一事实，而不是让上报失败
+                err.meta = { unserializable: true };
+            }
+        }
+        return { error: err };
     }
 }
 exports.CloudBaseError = CloudBaseError;
+/**
+ * 判断一个值是否为 CloudBaseError（**跨仓 / 跨进程安全**）。
+ *
+ * ⚠️ **不要用 `instanceof CloudBaseError` 做跨仓判断**：CLI / manager-node / toolbox
+ * 各有**独立的** CloudBaseError 类（三个不同的构造函数），跨仓时 `instanceof`
+ * 必然为 false；本仓为第三方消费方保留了 ES5 原型兜底（`Object.setPrototypeOf`，见构造函数），
+ * 降级编译下同仓内 `instanceof` 也可能失效。因此判断**只依赖结构特征**：
+ *
+ *   1. 是 Error 实例
+ *   2. `name === 'CloudBaseError'`
+ *   3. 有 `toJSON()` 方法
+ *
+ * ⚠️ **不要依赖其他字段**（`requestId` / `source` / `params` / `original` …）做判断 ——
+ * 它们都是**按需可选字段**，未来增删不应影响「是不是 CloudBaseError」。
+ *
+ * 三仓各持一份**同名同实现**的副本（约定相同，不共享包）。
+ */
+function isCloudBaseError(value) {
+    return (value instanceof Error &&
+        value.name === 'CloudBaseError' &&
+        typeof value.toJSON === 'function');
+}
+/** 错误码最大长度（对齐 AIP-193 `ErrorInfo.reason` 的 63 字符上限） */
+const ERROR_CODE_MAX_LENGTH = 63;
+/** 错误码格式：UPPER_SNAKE_CASE */
+const ERROR_CODE_PATTERN = /^[A-Z][A-Z0-9_]*$/;
+/**
+ * 判断错误码是否满足**正规化**规则（**我们自定义的码**适用）。
+ *
+ * 规则（对齐 AIP-193 `ErrorInfo.reason`）：
+ *   1. `UPPER_SNAKE_CASE` —— `^[A-Z][A-Z0-9_]*$`
+ *   2. 长度 ≤ **63** 字符
+ *   3. **不以 `_` 结尾**（`_` 结尾表示「前缀」，不是完整码）
+ *
+ * ⚠️ **仅适用于我们自定义的码**（`source` 为 `manager-node` / `cli` / `toolbox`）。
+ * **平台码不适用**：控制面是驼峰（如 `InvalidParameter`），数据面由平台规范约束。
+ *
+ * 用法：单测断言码表全员合规；新增码时先过这里，再落库。
+ */
+function isValidErrorCode(code) {
+    if (typeof code !== 'string')
+        return false;
+    if (code.length === 0 || code.length > ERROR_CODE_MAX_LENGTH)
+        return false;
+    if (code.endsWith('_'))
+        return false;
+    return ERROR_CODE_PATTERN.test(code);
+}
+/**
+ * 判断值是否属于 `ErrorSource` 闭集。
+ *
+ * 存在的理由：`source` 在**跨仓**传递时是普通字符串（另一仓的声明无法约束本仓类型），
+ * 直接 `return e.source` 会丢类型 ⇒ 用守卫**收窄**，而不是 `as` 强转。
+ */
+function isErrorSource(value) {
+    return (value === 'cloud-api' ||
+        value === 'runtime' ||
+        value === 'manager-node' ||
+        value === 'cli' ||
+        value === 'toolbox');
+}
+/**
+ * **重包装时继承上游错误的来源层**（R3：`source` 与 `code` 归属配套）。
+ *
+ * - 上游错误带**合法** `source` ⇒ 沿用（`code` 也应同时沿用它，不可自造）
+ * - 否则 ⇒ 落到**本层** `'manager-node'`
+ *
+ * ⚠️ 只在**沿用上游 `code`** 时使用；自造 `code` 时必须硬写本层 `source`。
+ */
+function errorSourceOf(e) {
+    const source = isCloudBaseError(e) ? e.source : '';
+    return isErrorSource(source) ? source : 'manager-node';
+}
+/**
+ * 参数校验错误：统一 code = INVALID_PARAM + source = manager-node。
+ *
+ * 用于替换散落的 `throw new Error('参数校验消息')`，让参数校验类错误
+ * 带上稳定 code（CLI 据此映射 exitCode=3）与来源标识，而非裸 Error 兜底。
+ */
+function throwInvalidParam(message) {
+    throw new CloudBaseError(message, { type: error_types_1.ERROR_TYPES.invalidParam });
+}
+/**
+ * 资源不存在错误：统一 code = NOT_FOUND + source = manager-node。
+ * 用于替换 `throw new Error('xxx 不存在')` 类错误。
+ */
+function throwNotFound(message) {
+    throw new CloudBaseError(message, { type: error_types_1.ERROR_TYPES.notFound });
+}
+/**
+ * 网络/请求错误：统一 code = NETWORK_ERROR + source = manager-node。
+ * 用于替换 `throw new Error('下载失败' / 'HTTP ERROR')` 类错误。
+ */
+function throwNetError(message) {
+    throw new CloudBaseError(message, { type: error_types_1.ERROR_TYPES.netError });
+}
+/**
+ * 服务端/业务操作错误：统一 code = API_ERROR + source = manager-node。
+ * 用于替换「服务端返回异常 / 业务状态不满足」类错误。
+ */
+function throwApiError(message) {
+    throw new CloudBaseError(message, { type: error_types_1.ERROR_TYPES.apiError });
+}
+/**
+ * 缺凭证错误：统一 code = MISSING_CREDENTIAL + source = manager-node。
+ * 用于替换 `throw new Error('missing secretId ...')` 类错误（SDK 初始化缺密钥）。
+ */
+function throwCredentialError(message) {
+    throw new CloudBaseError(message, { type: error_types_1.ERROR_TYPES.credentialError });
+}
+/**
+ * 本地文件读写错误：统一 code = FILE_READ_ERROR + source = manager-node。
+ * 用于替换本地文件系统操作（读取 / 写入 / 计算摘要 / 路径处理）失败类错误。
+ * 与 CLI / toolbox 的同名 helper 一致（三仓同名同语义）。
+ */
+function throwFileError(message) {
+    throw new CloudBaseError(message, { type: error_types_1.ERROR_TYPES.fileError });
+}