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

package/lib/user/index.js

@@ -8,6 +8,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UserService = void 0;
 const utils_1 = require("../utils");
+const error_1 = require("../error");
 class UserService {
     constructor(environment) {
         this.environment = environment;
@@ -119,25 +120,25 @@ class UserService {
         const { name, uid, type, password, userStatus, nickName, phone, email, avatarUrl, description } = options;
         // name 校验：1-64，字母/数字开头，仅字母数字._-
         if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(name)) {
-            throw new Error('Invalid name');
+            (0, error_1.throwInvalidParam)('Invalid name');
         }
         // uid 校验：<=64
         if (uid && uid.length > 64) {
-            throw new Error('Invalid uid');
+            (0, error_1.throwInvalidParam)('Invalid uid');
         }
         // type / status 白名单
         if (type && !['internalUser', 'externalUser'].includes(type)) {
-            throw new Error('Invalid type');
+            (0, error_1.throwInvalidParam)('Invalid type');
         }
         if (userStatus && !['ACTIVE', 'BLOCKED'].includes(userStatus)) {
-            throw new Error('Invalid userStatus');
+            (0, error_1.throwInvalidParam)('Invalid userStatus');
         }
         if (password) {
             if (password.length < 8 || password.length > 32) {
-                throw new Error('Invalid password length');
+                (0, error_1.throwInvalidParam)('Invalid password length');
             }
             if (!/^[A-Za-z0-9]/.test(password)) {
-                throw new Error('Password cannot start with special character');
+                (0, error_1.throwInvalidParam)('Password cannot start with special character');
             }
             const kinds = [
                 /[a-z]/.test(password),
@@ -146,21 +147,21 @@ class UserService {
                 /[()!@#$%^&*|?><_-]/.test(password)
             ].filter(Boolean).length;
             if (kinds < 3) {
-                throw new Error('Password must include at least 3 character categories');
+                (0, error_1.throwInvalidParam)('Password must include at least 3 character categories');
             }
         }
         // 其他字段校验
         if (nickName && (nickName.length < 2 || nickName.length > 64)) {
-            throw new Error('Invalid nickName');
+            (0, error_1.throwInvalidParam)('Invalid nickName');
         }
         if (description && description.length > 200) {
-            throw new Error('Invalid description');
+            (0, error_1.throwInvalidParam)('Invalid description');
         }
         if (phone && !/^1\d{10}$/.test(phone)) {
-            throw new Error('Invalid phone');
+            (0, error_1.throwInvalidParam)('Invalid phone');
         }
         if (email && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
-            throw new Error('Invalid email');
+            (0, error_1.throwInvalidParam)('Invalid email');
         }
         const reqData = {
             EnvId,
@@ -190,10 +191,10 @@ class UserService {
         const { EnvId } = this.environment.lazyEnvironmentConfig;
         const { pageNo = 1, pageSize = 20, name, nickName, phone, email, uidList } = options;
         if (!Number.isInteger(pageNo) || pageNo < 1) {
-            throw new Error('Invalid pageNo');
+            (0, error_1.throwInvalidParam)('Invalid pageNo');
         }
         if (!Number.isInteger(pageSize) || pageSize < 1 || pageSize > 100) {
-            throw new Error('Invalid pageSize');
+            (0, error_1.throwInvalidParam)('Invalid pageSize');
         }
         const reqData = {
             EnvId,
@@ -216,26 +217,26 @@ class UserService {
         const { EnvId } = this.environment.lazyEnvironmentConfig;
         const { uid, name, type, password, userStatus, nickName, phone, email, avatarUrl, description } = options;
         if (!this.isValidStr(uid) || uid.length > 64) {
-            throw new Error('Invalid uid');
+            (0, error_1.throwInvalidParam)('Invalid uid');
         }
         // Name: 不传或空字符串 => 不修改；传了非空则校验
         if (name !== undefined && name !== '' && !/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(name)) {
-            throw new Error('Invalid name');
+            (0, error_1.throwInvalidParam)('Invalid name');
         }
         // Type / UserStatus: 不传或空字符串 => 不修改；非空时白名单校验
-        if (type !== undefined && !['internalUser', 'externalUser'].includes(type)) {
-            throw new Error('Invalid type');
+        if (type && !['internalUser', 'externalUser'].includes(type)) {
+            (0, error_1.throwInvalidParam)('Invalid type');
         }
-        if (userStatus !== undefined && !['ACTIVE', 'BLOCKED'].includes(userStatus)) {
-            throw new Error('Invalid userStatus');
+        if (userStatus && !['ACTIVE', 'BLOCKED'].includes(userStatus)) {
+            (0, error_1.throwInvalidParam)('Invalid userStatus');
         }
         // Password: 不传或空字符串 => 不修改；非空时校验复杂度
         if (password !== undefined && password !== '') {
             if (password.length < 8 || password.length > 32) {
-                throw new Error('Invalid password length');
+                (0, error_1.throwInvalidParam)('Invalid password length');
             }
             if (!/^[A-Za-z0-9]/.test(password)) {
-                throw new Error('Password cannot start with special character');
+                (0, error_1.throwInvalidParam)('Password cannot start with special character');
             }
             const kinds = [
                 /[a-z]/.test(password),
@@ -244,21 +245,21 @@ class UserService {
                 /[()!@#$%^&*|?><_-]/.test(password)
             ].filter(Boolean).length;
             if (kinds < 3) {
-                throw new Error('Password must include at least 3 character categories');
+                (0, error_1.throwInvalidParam)('Password must include at least 3 character categories');
             }
         }
         // 这些字段：不传 => 不修改；传空字符串 => 清空（允许）
         if (nickName !== undefined && nickName !== '' && (nickName.length < 2 || nickName.length > 64)) {
-            throw new Error('Invalid nickName');
+            (0, error_1.throwInvalidParam)('Invalid nickName');
         }
         if (phone !== undefined && phone !== '' && !/^1\d{10}$/.test(phone)) {
-            throw new Error('Invalid phone');
+            (0, error_1.throwInvalidParam)('Invalid phone');
         }
         if (email !== undefined && email !== '' && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
-            throw new Error('Invalid email');
+            (0, error_1.throwInvalidParam)('Invalid email');
         }
         if (description !== undefined && description !== '' && description.length > 200) {
-            throw new Error('Invalid description');
+            (0, error_1.throwInvalidParam)('Invalid description');
         }
         const reqData = {
             EnvId,
@@ -267,11 +268,11 @@ class UserService {
         // Name/Type/Password/UserStatus：空字符串视为不修改
         if (name !== undefined && name !== '')
             reqData.Name = name;
-        if (type !== undefined)
+        if (type)
             reqData.Type = type;
         if (password !== undefined && password !== '')
             reqData.Password = password;
-        if (userStatus !== undefined)
+        if (userStatus)
             reqData.UserStatus = userStatus;
         // 这些字段支持传空字符串清空：只要“传了”就下发
         if (Object.prototype.hasOwnProperty.call(options, 'nickName'))
@@ -290,14 +291,14 @@ class UserService {
         const { EnvId } = this.environment.lazyEnvironmentConfig;
         const { uids } = options;
         if (!Array.isArray(uids) || uids.length === 0) {
-            throw new Error('uids is required');
+            (0, error_1.throwInvalidParam)('uids is required');
         }
         if (uids.length > 100) {
-            throw new Error('uids length must be <= 100');
+            (0, error_1.throwInvalidParam)('uids length must be <= 100');
         }
         const invalidUid = uids.find(uid => !this.isValidStr(uid));
         if (invalidUid) {
-            throw new Error('Invalid uid in uids');
+            (0, error_1.throwInvalidParam)('Invalid uid in uids');
         }
         return this.tcbService.request('DeleteUsers', {
             EnvId,

package/lib/utils/cloud-api-request.js

@@ -111,9 +111,12 @@ class CloudService {
                 if (e.name === 'CloudBaseError') {
                     throw e;
                 }
+                // requestFn 注入模式：错误来自外部请求实现，保留 cause 链
                 throw new error_1.CloudBaseError(e.message, {
                     action,
-                    code: e.code
+                    code: e.code,
+                    original: e,
+                    source: 'cloud-api'
                 });
             }
         }
@@ -128,10 +131,10 @@ class CloudService {
             const envToken = (0, utils_1.getEnvVar)(constant_1.ENV_NAME.ENV_SESSIONTOKEN);
             if (!envSecretId || !envSecretKey) {
                 if ((0, utils_1.getRuntime)() === constant_1.RUN_ENV.SCF) {
-                    throw new Error('missing authoration key, redeploy the function');
+                    (0, error_1.throwCredentialError)('missing authorization key, redeploy the function');
                 }
                 else {
-                    throw new Error('missing secretId or secretKey of tencent cloud');
+                    (0, error_1.throwCredentialError)('missing secretId or secretKey of tencent cloud');
                 }
             }
             else {
@@ -146,11 +149,13 @@ class CloudService {
         try {
             const data = await this.requestWithSign();
             if (data.Response.Error) {
+                // 云 API 返回的错误：code 来自控制面官方错误码（876/34823），标记 source 便于分层追溯
                 const tcError = new error_1.CloudBaseError(data.Response.Error.Message, {
                     action,
                     requestId: data.Response.RequestId,
                     code: data.Response.Error.Code,
-                    original: data.Response.Error
+                    original: data.Response.Error,
+                    source: 'cloud-api'
                 });
                 throw tcError;
             }
@@ -163,9 +168,12 @@ class CloudService {
                 throw e;
             }
             else {
+                // 请求过程异常（网络/签名等），非云 API 业务错误
                 throw new error_1.CloudBaseError(e.message, {
                     action,
-                    code: e.code
+                    code: e.code,
+                    original: e,
+                    source: 'manager-node'
                 });
             }
         }

package/lib/utils/cloudbase-request.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.cloudBaseRequest = cloudBaseRequest;
+exports.assertDataPlaneOk = assertDataPlaneOk;
+const error_1 = require("../error");
 const auth_1 = require("./auth");
 const http_request_1 = require("./http-request");
 const SUPPORT_REGIONS = ['ap-shanghai', 'ap-guangzhou', 'ap-singapore'];
@@ -66,3 +68,22 @@ async function cloudBaseRequest(options) {
     }, process.env.TCB_ADMIN_PROXY || proxy);
     return res;
 }
+/**
+ * 校验数据面（/admin）响应，命中错误时抛出带 code 的 CloudBaseError。
+ *
+ * 必须把 `res.code` 落到 `CloudBaseError.code` 并标记 `source: 'runtime'`：
+ * 否则 CLI 侧 `resolveErrorDoc` 拿不到 code → 文档链接哑火，
+ * `resolveExitCode` 也会兜底成 1，灯塔上报退化为 `ERROR`。
+ * 这是「错误码治理方案」D11 的修复点。
+ */
+function assertDataPlaneOk(res, action) {
+    if (!res || !res.code) {
+        return;
+    }
+    throw new error_1.CloudBaseError(`${res.code}: ${res.message || ''}`, {
+        code: res.code,
+        requestId: res.requestId,
+        source: 'runtime',
+        action
+    });
+}

package/lib/utils/fs.js

@@ -19,7 +19,7 @@ function checkFullAccess(dest, throwError = false) {
     }
     catch (e) {
         if (throwError) {
-            throw new error_1.CloudBaseError(`路径不存在：${dest}`);
+            (0, error_1.throwNotFound)(`路径不存在：${dest}`);
         }
         return false;
     }
@@ -29,7 +29,7 @@ function checkFullAccess(dest, throwError = false) {
     }
     catch (e) {
         if (throwError) {
-            throw new error_1.CloudBaseError(`路径无读写权限：${dest}`);
+            (0, error_1.throwFileError)(`路径无读写权限：${dest}`);
         }
         return false;
     }
@@ -46,7 +46,7 @@ function checkReadable(dest, throwError = false) {
     }
     catch (e) {
         if (throwError) {
-            throw new error_1.CloudBaseError(`路径不存在或无读权限：${dest}`);
+            (0, error_1.throwNotFound)(`路径不存在或无读权限：${dest}`);
         }
         else {
             return false;

package/lib/utils/http-request.js

@@ -31,9 +31,9 @@ async function fetch(url, config = {}, proxy = null) {
         // 某些情况下回返回 HTML 文本异常
         // JSON 解析错误，抛出原响应文本
         if (e.name === 'SyntaxError') {
-            throw new error_1.CloudBaseError(text);
+            (0, error_1.throwApiError)(text);
         }
-        throw new error_1.CloudBaseError(e);
+        (0, error_1.throwApiError)(e.message || String(e));
     }
     return json;
 }

package/lib/utils/index.js

@@ -39,6 +39,7 @@ const path_1 = __importDefault(require("path"));
 const unzipper_1 = __importDefault(require("unzipper"));
 const constant_1 = require("../constant");
 const http_request_1 = require("./http-request");
+const error_1 = require("../error");
 __exportStar(require("./auth"), exports);
 __exportStar(require("./cloud-api-request"), exports);
 __exportStar(require("./cloudbase-request"), exports);
@@ -172,10 +173,10 @@ function shouldSkipEntry(entryPath) {
 async function downloadAndExtractRemoteZip(downloadUrl, targetPath) {
     const downloadResponse = await (0, http_request_1.fetchStream)(downloadUrl);
     if (!downloadResponse.ok) {
-        throw new Error(`下载失败，状态码: ${downloadResponse.status}`);
+        (0, error_1.throwNetError)(`下载失败，状态码: ${downloadResponse.status}`);
     }
     if (!downloadResponse.body) {
-        throw new Error('下载响应中没有数据流');
+        (0, error_1.throwNetError)('下载响应中没有数据流');
     }
     // 创建目标目录
     const dirPath = path_1.default.resolve(targetPath);
@@ -264,7 +265,7 @@ function upload({ url, file, method = 'POST', headers = {}, withCredentials = fa
             // If parsing fails, keep data as null
         }
         if (!response.ok) {
-            throw new Error(`${response.status} ${response.statusText} HTTP ERROR`);
+            (0, error_1.throwNetError)(`${response.status} ${response.statusText} HTTP ERROR`);
         }
         return dataMeta;
     })

package/lib/utils/storage-config.js

@@ -39,11 +39,11 @@ function resolveStorageConfig(envConfig) {
     var _a;
     // 环境信息由带 @preLazy 的方法首次调用时加载，直接调用 getStorageConfig 可能早于加载
     if (!envConfig) {
-        throw new error_1.CloudBaseError('环境信息尚未加载，无法获取存储配置，请先调用任一存储方法（如 listDirectoryFiles）或 environment.lazyInit() 完成初始化');
+        (0, error_1.throwApiError)('环境信息尚未加载，无法获取存储配置，请先调用任一存储方法（如 listDirectoryFiles）或 environment.lazyInit() 完成初始化');
     }
     const storage = (_a = envConfig.Storages) === null || _a === void 0 ? void 0 : _a[0];
     if (!storage) {
-        throw new error_1.CloudBaseError(`环境 ${envConfig === null || envConfig === void 0 ? void 0 : envConfig.EnvId} 未查询到云存储资源（Storages 为空），请确认环境 ID 正确且环境已开通云存储`);
+        (0, error_1.throwNotFound)(`环境 ${envConfig === null || envConfig === void 0 ? void 0 : envConfig.EnvId} 未查询到云存储资源（Storages 为空），请确认环境 ID 正确且环境已开通云存储`);
     }
     return Object.assign({ env: envConfig.EnvId }, resolveBucketConfig({
         envId: envConfig.EnvId,
@@ -67,7 +67,7 @@ function resolveBucketConfig(options) {
         const effectiveBucket = bucket || externalStorage.BucketName;
         // 线上存在已启用外部存储但未返回桶名的环境，继续执行会在 COS 调用时报 missing param Bucket
         if (!effectiveBucket) {
-            throw new error_1.CloudBaseError(`环境 ${envId} 已启用外部存储（ExternalStorage），但未返回存储桶名称（BucketName），无法访问存储桶，请联系平台检查该环境的共享桶配置`);
+            (0, error_1.throwNotFound)(`环境 ${envId} 已启用外部存储（ExternalStorage），但未返回存储桶名称（BucketName），无法访问存储桶，请联系平台检查该环境的共享桶配置`);
         }
         return {
             bucket: effectiveBucket,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cloudbase/manager-node",
-    "version": "5.8.9-beta.1",
+    "version": "5.9.0",
     "description": "The node manage service api for cloudbase.",
     "main": "lib/index.js",
     "scripts": {
@@ -42,7 +42,7 @@
     },
     "dependencies": {
         "@cloudbase/signature-nodejs": "^1.0.0",
-        "@cloudbase/toolbox": "~0.8.4",
+        "@cloudbase/toolbox": "~0.9.0",
         "@cloudbase/database": "^0.6.2",
         "archiver": "^3.1.1",
         "cos-nodejs-sdk-v5": "^2.14.0",

package/types/error-docs.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 错误码 → 文档链接 映射
+ *
+ * 用途：报错时自动关联到对应的错误码指引文档，让用户能直接跳转查看。
+ * 在 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），防止再次漂移。
+ */
+import type { ErrorSource } from './error';
+/** 控制面云 API 错误码文档（腾讯云云开发 CloudBase 错误码） */
+export declare const CONTROL_PLANE_ERROR_DOC = "https://cloud.tencent.com/document/product/876/34823";
+/** 数据面错误码总览页（分类索引） */
+export declare const RUNTIME_ERROR_DOC = "https://docs.cloudbase.net/error-code/basic";
+/** 数据面单码页 URL 前缀：最终形如 `${BASE}/${CODE}` */
+export declare const RUNTIME_ERROR_CODE_DOC_BASE = "https://docs.cloudbase.net/error-code";
+/**
+ * 数据面（运行时）错误码全量清单。
+ *
+ * 来源：`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 时不可参与匹配。
+ */
+export declare const RUNTIME_ERROR_CODES: Set<string>;
+/**
+ * 根据错误码解析对应的文档链接。
+ *
+ * @param code 错误码（可能是语义 code、云 API code，或带 '.' 的子错误码）
+ * @param source 错误来源层（见 ErrorSource）。传入时按来源精确分流；
+ *               不传时保持历史宽松匹配（控制面精确 + 6 个模块前缀），向后兼容。
+ * @returns 文档链接；无法归类时返回空串（由调用方决定是否兜底）
+ */
+export declare function resolveErrorDoc(code?: string | number, source?: ErrorSource | ''): string;

package/types/error-types.d.ts

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

package/types/error.d.ts

@@ -1,13 +1,60 @@
+import { ErrorType } from './error-types';
+export type ErrorSource = 'cloud-api' | 'runtime' | 'manager-node' | 'cli' | 'toolbox';
+/**
+ * `error.meta.failures` 的单项（**多项失败的统一表达**）。
+ *
+ * 用于**多项失败**场景：`code` 只能承载**一个**码（兼容既有消费方），其余失败项
+ * 的码会在结构层面丢失 —— 埋点因此统计不到真实分布。`meta.failures` 承载**全量**失败项。
+ *
+ * ⚠️ 它不是「替代 code」：`code` 仍取第一项，`meta.failures` 是**附加**信息。
+ * ⚠️ 与 `meta` 的其他 key 一样，新增字段必须 ① 抽具名 interface ② 补文档登记表 ③ 补契约测试。
+ */
+export interface IMetaFailure {
+    /** 精确错误码 */
+    code: string;
+    /** 简述（同 ICheckResult.summary） */
+    summary?: string;
+    /** 可执行的修复建议（同 ICheckResult.remediation） */
+    remediation?: string;
+}
 interface Options {
-    exit?: number;
     original?: Error | undefined;
     code?: string | number;
+    /** 标准错误类型：自有码的唯一来源；传入后 code / source 由它决定，且**不可被调用方覆盖** */
+    type?: ErrorType;
     requestId?: string;
     action?: string;
     meta?: Record<string, any>;
+    /** 错误来源层（对齐 CLI CloudBaseError.source） */
+    source?: ErrorSource;
+    /** 文档链接覆盖（缺省按 `(code, source)` 派生） */
+    docs?: string;
 }
+/**
+ * ## `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 依赖）。
+ */
 export declare class CloudBaseError extends Error {
-    readonly exit: number;
     readonly message: string;
     readonly name = "CloudBaseError";
     readonly original: Error | undefined;
@@ -15,6 +62,105 @@ export declare class CloudBaseError extends Error {
     readonly requestId: string;
     readonly action: string;
     readonly meta: Record<string, any> | undefined;
+    readonly source: ErrorSource | '';
+    /** 错误码文档链接（按 `(code, source)` 派生；`opts.docs` 可覆盖） */
+    readonly docs: string;
     constructor(message: string, options?: Options);
+    /**
+     * 标准 `Error.cause` 视图（ES2022）。
+     *
+     * 与 `original` **同源**（不重复存储，仅暴露标准视图）：
+     * - `original` **保留**，因为已有 8 处调用点依赖它访问上游 SDK 错误
+     *   （`.Code` / `.Message` / `.RequestId` / `.Response`）；
+     * - 额外提供 `cause` 是为了对齐标准 —— Node 等工具链会**自动打印 cause 链**，
+     *   且与 `AggregateError` 兼容。
+     */
+    get cause(): Error | undefined;
+    /**
+     * 转为 JSON 错误结构（对齐 CLI CloudBaseError.toJSON）
+     * 格式：{ error: { code, message, stack?, requestId?, action?, source?, docs?, meta? } }
+     */
+    toJSON(): Record<string, unknown>;
 }
+/**
+ * 判断一个值是否为 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」。
+ *
+ * 三仓各持一份**同名同实现**的副本（约定相同，不共享包）。
+ */
+export declare function isCloudBaseError(value: unknown): value is CloudBaseError;
+/**
+ * 判断错误码是否满足**正规化**规则（**我们自定义的码**适用）。
+ *
+ * 规则（对齐 AIP-193 `ErrorInfo.reason`）：
+ *   1. `UPPER_SNAKE_CASE` —— `^[A-Z][A-Z0-9_]*$`
+ *   2. 长度 ≤ **63** 字符
+ *   3. **不以 `_` 结尾**（`_` 结尾表示「前缀」，不是完整码）
+ *
+ * ⚠️ **仅适用于我们自定义的码**（`source` 为 `manager-node` / `cli` / `toolbox`）。
+ * **平台码不适用**：控制面是驼峰（如 `InvalidParameter`），数据面由平台规范约束。
+ *
+ * 用法：单测断言码表全员合规；新增码时先过这里，再落库。
+ */
+export declare function isValidErrorCode(code: unknown): code is string;
+/**
+ * 判断值是否属于 `ErrorSource` 闭集。
+ *
+ * 存在的理由：`source` 在**跨仓**传递时是普通字符串（另一仓的声明无法约束本仓类型），
+ * 直接 `return e.source` 会丢类型 ⇒ 用守卫**收窄**，而不是 `as` 强转。
+ */
+export declare function isErrorSource(value: unknown): value is ErrorSource;
+/**
+ * **重包装时继承上游错误的来源层**（R3：`source` 与 `code` 归属配套）。
+ *
+ * - 上游错误带**合法** `source` ⇒ 沿用（`code` 也应同时沿用它，不可自造）
+ * - 否则 ⇒ 落到**本层** `'manager-node'`
+ *
+ * ⚠️ 只在**沿用上游 `code`** 时使用；自造 `code` 时必须硬写本层 `source`。
+ */
+export declare function errorSourceOf(e: unknown): ErrorSource;
+/**
+ * 参数校验错误：统一 code = INVALID_PARAM + source = manager-node。
+ *
+ * 用于替换散落的 `throw new Error('参数校验消息')`，让参数校验类错误
+ * 带上稳定 code（CLI 据此映射 exitCode=3）与来源标识，而非裸 Error 兜底。
+ */
+export declare function throwInvalidParam(message: string): never;
+/**
+ * 资源不存在错误：统一 code = NOT_FOUND + source = manager-node。
+ * 用于替换 `throw new Error('xxx 不存在')` 类错误。
+ */
+export declare function throwNotFound(message: string): never;
+/**
+ * 网络/请求错误：统一 code = NETWORK_ERROR + source = manager-node。
+ * 用于替换 `throw new Error('下载失败' / 'HTTP ERROR')` 类错误。
+ */
+export declare function throwNetError(message: string): never;
+/**
+ * 服务端/业务操作错误：统一 code = API_ERROR + source = manager-node。
+ * 用于替换「服务端返回异常 / 业务状态不满足」类错误。
+ */
+export declare function throwApiError(message: string): never;
+/**
+ * 缺凭证错误：统一 code = MISSING_CREDENTIAL + source = manager-node。
+ * 用于替换 `throw new Error('missing secretId ...')` 类错误（SDK 初始化缺密钥）。
+ */
+export declare function throwCredentialError(message: string): never;
+/**
+ * 本地文件读写错误：统一 code = FILE_READ_ERROR + source = manager-node。
+ * 用于替换本地文件系统操作（读取 / 写入 / 计算摘要 / 路径处理）失败类错误。
+ * 与 CLI / toolbox 的同名 helper 一致（三仓同名同语义）。
+ */
+export declare function throwFileError(message: string): never;
 export {};