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

package/.codebuddy/rules/error-code-contract.mdc

@@ -0,0 +1,13 @@
+# 错误码契约（manager-node · 本仓指引）
+
+**规则的唯一来源** → `cloudbase-cli/specs/error-rules.md`（**改规则只改那一处**；本文件只写**本仓差异**）。
+
+## 本仓差异
+
+- **字段**：三仓应有项全有（含 `docs`、`meta`）+ **本仓专属 `meta.failures`**（多项失败明细登记，见 rules §5）
+- **`docs`**：`this.docs = opts.docs ?? resolveErrorDoc(this.code, this.source)`（**类内派生**，依赖本仓 `src/error-docs.ts`）
+  > ⚠️ 映射表**只在本仓并不充分**：TB 侧错误拿不到 `docs` ⇒ 按判据 C 应走**单一来源**（文档站生成）或下沉共享基座；本仓不应成为映射表唯一归属点
+- **机制**：有 `isCloudBaseError` / `isValidErrorCode` / 8 个 helper（含 `throwCredentialError`）；**缺 `errorSourceOf`**（R3 前置，待对齐）
+- **守卫**：`test/error.test.ts`（burn-down 平衡括号 + 码表）、`test/error-no-code-baseline.json`（`{}`）
+- **本仓特殊约定**：错误对象是**对外 API**（CLI / MCP / 第三方 SDK 直接读 `.code` / `.docs` / `.meta`）⇒ 字段增删按 §3 冻结形状处理，不随基座版本漂移
+- **新增自造码 ⇒ 必须同步文档站**：到 `cloudbase-docs` 跑 `node scripts/generate-sdk-error-code-pages.mjs`（分层登记页由生成器产出，**勿手工建页**、**勿加进 `basic.md`**；详见该仓 `.codebuddy/skills/error-code-manager`）

package/CHANGELOG.md

@@ -1,3 +1,4 @@
+
 ## @cloudbase/manager-node v5.8.8 版本发布 🚀(2026-09-18)
 
 - 新增平台版套餐服务 PlatformService

package/lib/agent/index.js

@@ -13,6 +13,7 @@ exports.AgentService = void 0;
 const cloudrun_1 = require("../cloudrun");
 const type_1 = require("../cloudrun/type");
 const utils_1 = require("../utils");
+const error_1 = require("../error");
 const path_1 = __importDefault(require("path"));
 /**
  * Agent 管理类
@@ -254,7 +255,7 @@ class AgentService {
         // 1. 查询 Agent 获取类型
         const agentListRes = await this.describeAgentList({ AgentId });
         if (!agentListRes.AgentList || agentListRes.AgentList.length === 0) {
-            throw new Error(`Agent ${AgentId} 不存在`);
+            (0, error_1.throwNotFound)(`Agent ${AgentId} 不存在`);
         }
         const agentInfo = agentListRes.AgentList[0];
         const agentType = agentInfo.AgentType;
@@ -273,7 +274,7 @@ class AgentService {
             });
         }
         else {
-            throw new Error(`不支持的 Agent 类型: ${agentType}`);
+            (0, error_1.throwInvalidParam)(`不支持的 Agent 类型: ${agentType}`);
         }
     }
     /**
@@ -333,7 +334,7 @@ class AgentService {
         // 1. 查询 Agent 获取类型
         const agentListRes = await this.describeAgentList({ AgentId });
         if (!agentListRes.AgentList || agentListRes.AgentList.length === 0) {
-            throw new Error(`Agent ${AgentId} 不存在`);
+            (0, error_1.throwNotFound)(`Agent ${AgentId} 不存在`);
         }
         const agentInfo = agentListRes.AgentList[0];
         const agentType = agentInfo.AgentType;
@@ -368,7 +369,7 @@ class AgentService {
             });
         }
         else {
-            throw new Error(`不支持的 Agent 类型: ${agentType}`);
+            (0, error_1.throwInvalidParam)(`不支持的 Agent 类型: ${agentType}`);
         }
     }
     // ==================== TCBR 云托管（内部方法，暂不对外暴露） ====================
@@ -592,7 +593,7 @@ class AgentService {
         const envConfig = this.environment.lazyEnvironmentConfig;
         // 判断 params.BotId 的数据格式是否为 ibot-xxx-xxx 的格式
         if (!/^ibot-[a-z0-9_]+-[a-z0-9_]+$/.test(BotId)) {
-            throw new Error('BotId格式应为"ibot-xxx-xxx"，其中 xxx 仅支持小写字母、数字或下划线');
+            (0, error_1.throwInvalidParam)('BotId格式应为"ibot-xxx-xxx"，其中 xxx 仅支持小写字母、数字或下划线');
         }
         // 获取函数型云托管服务的名称：ibot-xxx-xxx 中的 ibot-xxx
         const serverName = BotId.split('-').slice(0, 2).join('-');

package/lib/aiModel/index.js

@@ -8,6 +8,14 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AiModelService = void 0;
 const utils_1 = require("../utils");
+const error_1 = require("../error");
+/** AI 模型分组状态（CreateAIModel / UpdateAIModel 协议值） */
+const MODEL_STATUS = {
+    /** 启用 */
+    enabled: 1,
+    /** 禁用 */
+    disabled: 2
+};
 class AiModelService {
     constructor(environment) {
         this.environment = environment;
@@ -20,13 +28,15 @@ class AiModelService {
         const { EnvId } = this.environment.lazyEnvironmentConfig;
         const { envId, groupName, baseUrl, models, remark, status, secret } = options;
         if (!groupName || groupName.trim().length === 0) {
-            throw new Error('groupName is required');
+            (0, error_1.throwInvalidParam)('groupName is required');
         }
         if (groupName.toLowerCase().startsWith('cloudbase')) {
-            throw new Error('groupName cannot start with cloudbase');
+            (0, error_1.throwInvalidParam)('groupName cannot start with cloudbase');
         }
-        if (status !== undefined && status !== 1 && status !== 2) {
-            throw new Error('status must be 1 or 2');
+        if (status !== undefined &&
+            status !== MODEL_STATUS.enabled &&
+            status !== MODEL_STATUS.disabled) {
+            (0, error_1.throwInvalidParam)(`status must be ${MODEL_STATUS.enabled} or ${MODEL_STATUS.disabled}`);
         }
         return this.tcbService.request('CreateAIModel', Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ EnvId: envId || EnvId, GroupName: groupName }, (baseUrl !== undefined ? { BaseUrl: baseUrl } : {})), (models !== undefined ? { Models: models } : {})), (remark !== undefined ? { Remark: remark } : {})), (status !== undefined ? { Status: status } : {})), (secret !== undefined ? { Secret: secret } : {})));
     }
@@ -37,10 +47,12 @@ class AiModelService {
         const { EnvId } = this.environment.lazyEnvironmentConfig;
         const { envId, groupName, baseUrl, models, remark, status, secret } = options;
         if (!groupName || groupName.trim().length === 0) {
-            throw new Error('groupName is required');
+            (0, error_1.throwInvalidParam)('groupName is required');
         }
-        if (status !== undefined && status !== 1 && status !== 2) {
-            throw new Error('status must be 1 or 2');
+        if (status !== undefined &&
+            status !== MODEL_STATUS.enabled &&
+            status !== MODEL_STATUS.disabled) {
+            (0, error_1.throwInvalidParam)(`status must be ${MODEL_STATUS.enabled} or ${MODEL_STATUS.disabled}`);
         }
         return this.tcbService.request('UpdateAIModel', Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ EnvId: envId || EnvId, GroupName: groupName }, (baseUrl !== undefined ? { BaseUrl: baseUrl } : {})), (models !== undefined ? { Models: models } : {})), (remark !== undefined ? { Remark: remark } : {})), (status !== undefined ? { Status: status } : {})), (secret !== undefined ? { Secret: secret } : {})));
     }
@@ -51,11 +63,11 @@ class AiModelService {
         const { EnvId } = this.environment.lazyEnvironmentConfig;
         const { envId, groupNames } = options;
         if (!Array.isArray(groupNames) || groupNames.length === 0) {
-            throw new Error('groupNames is required');
+            (0, error_1.throwInvalidParam)('groupNames is required');
         }
         const invalidGroupName = groupNames.find(item => typeof item !== 'string' || item.trim().length === 0);
         if (invalidGroupName !== undefined) {
-            throw new Error('groupNames contains invalid item');
+            (0, error_1.throwInvalidParam)('groupNames contains invalid item');
         }
         return this.tcbService.request('DeleteAIModel', {
             EnvId: envId || EnvId,

package/lib/cloudApp/index.js

@@ -133,11 +133,11 @@ class CloudAppService {
         const { serviceName, localPath, ignore = [], excludeNodeModules = true, onPhase } = params;
         // 1. 验证本地路径
         if (!fs_1.default.existsSync(localPath)) {
-            throw new error_1.CloudBaseError(`本地路径不存在: ${localPath}`);
+            (0, error_1.throwNotFound)(`本地路径不存在: ${localPath}`);
         }
         const stat = fs_1.default.statSync(localPath);
         if (!stat.isDirectory()) {
-            throw new error_1.CloudBaseError(`localPath 必须是目录: ${localPath}`);
+            (0, error_1.throwInvalidParam)(`localPath 必须是目录: ${localPath}`);
         }
         // 2. 打包本地文件为 ZIP（node_modules 按场景决定是否排除）
         const tmpZipPath = path_1.default.join(os_1.default.tmpdir(), `cloudapp-${Date.now()}-${Math.random().toString(36).slice(2)}.zip`);
@@ -193,7 +193,7 @@ class CloudAppService {
                 catch (_a) {
                     // 解析失败时 errorDetail 保持空串，不影响主错误抛出
                 }
-                throw new error_1.CloudBaseError(`上传失败: ${response.status} ${response.statusText}${errorDetail}`);
+                (0, error_1.throwApiError)(`上传失败: ${response.status} ${response.statusText}${errorDetail}`);
             }
             onPhase === null || onPhase === void 0 ? void 0 : onPhase({ phase: 'upload', durationMs: Date.now() - putStart, bytes: zipBuffer.length });
             // 7. 返回结果（返回 cosTimestamp，用于创建应用）
@@ -226,7 +226,7 @@ class CloudAppService {
     validateRequiredParams(params, fields) {
         for (const field of fields) {
             if (!params[field]) {
-                throw new error_1.CloudBaseError(`${field} 是必填参数`);
+                (0, error_1.throwInvalidParam)(`${field} 是必填参数`);
             }
         }
     }

package/lib/cloudrun/index.js

@@ -15,6 +15,7 @@ exports.parseObjectToDiffConfigItem = parseObjectToDiffConfigItem;
 const archiver_1 = __importDefault(require("archiver"));
 const fs_extra_1 = require("fs-extra");
 const path_1 = __importDefault(require("path"));
+const error_1 = require("../error");
 const utils_1 = require("../utils");
 const type_1 = require("./type");
 /**
@@ -46,7 +47,7 @@ class CloudRunService {
         const templates = await this.getTemplates();
         const templateData = templates.find(item => item.identifier === template);
         if (!templateData || !templateData.zipFileStore) {
-            throw new Error(`未找到匹配的模板: ${template}`);
+            (0, error_1.throwNotFound)(`未找到匹配的模板: ${template}`);
         }
         // 2. 下载并解压模板到目标目录
         const downloadUrl = templateData.zipFileStore;
@@ -75,7 +76,7 @@ class CloudRunService {
         const cloudRunServerDetailRes = await this.detail({ serverName });
         const version = (_b = (_a = cloudRunServerDetailRes.OnlineVersionInfos) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.VersionName;
         if (!version) {
-            throw new Error('未找到云托管服务版本');
+            (0, error_1.throwNotFound)('未找到云托管服务版本');
         }
         /**
          * 获取下载地址
@@ -89,7 +90,7 @@ class CloudRunService {
             await (0, utils_1.downloadAndExtractRemoteZip)(cloudBaseBuildServiceRes === null || cloudBaseBuildServiceRes === void 0 ? void 0 : cloudBaseBuildServiceRes.DownloadUrl, path_1.default.resolve(targetPath));
         }
         else {
-            throw new Error(`云托管代码下载地址为空（请求ID: ${cloudBaseBuildServiceRes.RequestId}）`);
+            (0, error_1.throwApiError)(`云托管代码下载地址为空（请求ID: ${cloudBaseBuildServiceRes.RequestId}）`);
         }
     }
     /**
@@ -116,7 +117,7 @@ class CloudRunService {
         const serverName = (_a = params === null || params === void 0 ? void 0 : params.ServerName) === null || _a === void 0 ? void 0 : _a.trim();
         const status = (_b = params === null || params === void 0 ? void 0 : params.Status) === null || _b === void 0 ? void 0 : _b.trim();
         if (!serverName) {
-            throw new Error('Missing required parameters: ServerName');
+            (0, error_1.throwInvalidParam)('Missing required parameters: ServerName');
         }
         return this.tcbrService.request('DescribeReleaseOrder', Object.assign({ EnvId: envConfig.EnvId, ServerName: serverName }, (status ? { Status: status } : {})));
     }
@@ -148,7 +149,7 @@ class CloudRunService {
     async setTraffic(serverName, stablePercent, canaryPercent) {
         // 校验比例之和是否为100%
         if (stablePercent + canaryPercent !== 100) {
-            throw new Error('稳定版本流量比例和灰度版本流量比例之和必须等于 100');
+            (0, error_1.throwInvalidParam)('稳定版本流量比例和灰度版本流量比例之和必须等于 100');
         }
         const envConfig = this.environment.lazyEnvironmentConfig;
         const { Task } = await this.tcbrService.request('DescribeServerManageTask', {
@@ -159,7 +160,7 @@ class CloudRunService {
         // 判断是否存在灰度版本
         const isGary = (Task === null || Task === void 0 ? void 0 : Task.ReleaseType) === type_1.ReleaseTypeEnum.GRAY && (Task === null || Task === void 0 ? void 0 : Task.Status) === 'running';
         if (!isGary) {
-            throw new Error('不存在灰度中的版本或灰度版本部署未完成');
+            (0, error_1.throwApiError)('不存在灰度中的版本或灰度版本部署未完成');
         }
         // 获取当前版本和灰度版本
         const { ReleaseOrderInfo } = await this.tcbrService.request('DescribeReleaseOrder', {
@@ -242,13 +243,13 @@ class CloudRunService {
         const rollbackVersionName = (_c = params === null || params === void 0 ? void 0 : params.RollbackVersionName) === null || _c === void 0 ? void 0 : _c.trim();
         const operatorRemark = (_d = params === null || params === void 0 ? void 0 : params.OperatorRemark) === null || _d === void 0 ? void 0 : _d.trim();
         if (!serverName) {
-            throw new Error('Missing required parameters: ServerName');
+            (0, error_1.throwInvalidParam)('Missing required parameters: ServerName');
         }
         if (!currentVersionName) {
-            throw new Error('Missing required parameters: CurrentVersionName');
+            (0, error_1.throwInvalidParam)('Missing required parameters: CurrentVersionName');
         }
         if (!rollbackVersionName) {
-            throw new Error('Missing required parameters: RollbackVersionName');
+            (0, error_1.throwInvalidParam)('Missing required parameters: RollbackVersionName');
         }
         return this.tcbrService.request('SubmitServerRollback', Object.assign({ EnvId: envConfig.EnvId, ServerName: serverName, CurrentVersionName: currentVersionName, RollbackVersionName: rollbackVersionName }, (operatorRemark ? { OperatorRemark: operatorRemark } : {})));
     }
@@ -262,17 +263,17 @@ class CloudRunService {
         const envConfig = this.environment.lazyEnvironmentConfig;
         const operatorRemark = (_a = params === null || params === void 0 ? void 0 : params.OperatorRemark) === null || _a === void 0 ? void 0 : _a.trim();
         if (!Array.isArray(params === null || params === void 0 ? void 0 : params.SimpleVersions) || params.SimpleVersions.length === 0) {
-            throw new Error('Missing required parameters: SimpleVersions');
+            (0, error_1.throwInvalidParam)('Missing required parameters: SimpleVersions');
         }
         const simpleVersions = params.SimpleVersions.map((item, index) => {
             var _a, _b, _c;
             const serverName = (_a = item === null || item === void 0 ? void 0 : item.ServerName) === null || _a === void 0 ? void 0 : _a.trim();
             const versionName = (_b = item === null || item === void 0 ? void 0 : item.VersionName) === null || _b === void 0 ? void 0 : _b.trim();
             if (!serverName) {
-                throw new Error(`Invalid SimpleVersions[${index}].ServerName`);
+                (0, error_1.throwInvalidParam)(`Invalid SimpleVersions[${index}].ServerName`);
             }
             if (!versionName) {
-                throw new Error(`Invalid SimpleVersions[${index}].VersionName`);
+                (0, error_1.throwInvalidParam)(`Invalid SimpleVersions[${index}].VersionName`);
             }
             return {
                 EnvId: ((_c = item === null || item === void 0 ? void 0 : item.EnvId) === null || _c === void 0 ? void 0 : _c.trim()) || envConfig.EnvId,
@@ -294,10 +295,10 @@ class CloudRunService {
         const versionName = (_b = params === null || params === void 0 ? void 0 : params.VersionName) === null || _b === void 0 ? void 0 : _b.trim();
         const channel = (_c = params === null || params === void 0 ? void 0 : params.Channel) === null || _c === void 0 ? void 0 : _c.trim();
         if (!serverName) {
-            throw new Error('Missing required parameters: ServerName');
+            (0, error_1.throwInvalidParam)('Missing required parameters: ServerName');
         }
         if (!versionName) {
-            throw new Error('Missing required parameters: VersionName');
+            (0, error_1.throwInvalidParam)('Missing required parameters: VersionName');
         }
         return this.tcbrService.request('DescribeVersionDetail', Object.assign({ EnvId: envConfig.EnvId, ServerName: serverName, VersionName: versionName }, (channel ? { Channel: channel } : {})));
     }
@@ -359,7 +360,7 @@ class CloudRunService {
          * 参数校验和默认值设置
          */
         if (!serverName) {
-            throw new Error('Missing required parameters: serviceName');
+            (0, error_1.throwInvalidParam)('Missing required parameters: serviceName');
         }
         // 获取当前环境配置(包含EnvId)
         const envConfig = this.environment.lazyEnvironmentConfig;

package/lib/common/index.js

@@ -30,7 +30,7 @@ class CommonService {
     async call(options) {
         const { Action, Param = {} } = options;
         if (!Action) {
-            throw new error_1.CloudBaseError('缺少必填参数 Action');
+            (0, error_1.throwInvalidParam)('缺少必填参数 Action');
         }
         const res = await this.commonService.request(Action, Object.assign({}, Param));
         return res;

package/lib/database/index.js

@@ -201,7 +201,7 @@ class DatabaseService {
             fileType = path_1.default.extname(filePath).substring(1);
         }
         else {
-            throw new error_1.CloudBaseError('Miss file.filePath or file.objectKey');
+            (0, error_1.throwInvalidParam)('Miss file.filePath or file.objectKey');
         }
         if (file['FileType']) {
             fileType = file['FileType'];
@@ -217,7 +217,7 @@ class DatabaseService {
             fileType = path_1.default.extname(filePath).substring(1);
         }
         else {
-            throw new error_1.CloudBaseError('Miss file.filePath or file.objectKey');
+            (0, error_1.throwInvalidParam)('Miss file.filePath or file.objectKey');
         }
         if (file['FileType']) {
             fileType = file['FileType'];
@@ -334,17 +334,17 @@ class DatabaseService {
         var _a;
         const { EnvId, Migrations, IncludeAll } = options;
         if (!Array.isArray(Migrations) || Migrations.length === 0) {
-            throw new error_1.CloudBaseError('Migrations 至少需要 1 条');
+            (0, error_1.throwInvalidParam)('Migrations 至少需要 1 条');
         }
         for (const migration of Migrations) {
             if (!/^\d{14}$/.test(migration.Version)) {
-                throw new error_1.CloudBaseError('Migration.Version 必须是 14 位数字');
+                (0, error_1.throwInvalidParam)('Migration.Version 必须是 14 位数字');
             }
             if (!/^[a-z_]+$/.test(migration.Name)) {
-                throw new error_1.CloudBaseError('Migration.Name 只允许小写字母和下划线');
+                (0, error_1.throwInvalidParam)('Migration.Name 只允许小写字母和下划线');
             }
             if (!((_a = migration.Query) === null || _a === void 0 ? void 0 : _a.trim())) {
-                throw new error_1.CloudBaseError('Migration.Query 不能为空');
+                (0, error_1.throwInvalidParam)('Migration.Query 不能为空');
             }
         }
         return this.dbOpService.request('PreviewPGUserMigrations', Object.assign({ EnvId: EnvId || this.envId, Migrations }, (IncludeAll !== undefined ? { IncludeAll } : {})));
@@ -358,24 +358,24 @@ class DatabaseService {
         var _a;
         const { EnvId, Migrations, LockTimeoutMs, StatementTimeoutMs, IncludeAll } = options;
         if (!Array.isArray(Migrations) || Migrations.length === 0) {
-            throw new error_1.CloudBaseError('Migrations 至少需要 1 条');
+            (0, error_1.throwInvalidParam)('Migrations 至少需要 1 条');
         }
         for (const migration of Migrations) {
             if (!/^\d{14}$/.test(migration.Version)) {
-                throw new error_1.CloudBaseError('Migration.Version 必须是 14 位数字');
+                (0, error_1.throwInvalidParam)('Migration.Version 必须是 14 位数字');
             }
             if (!/^[a-z_]+$/.test(migration.Name)) {
-                throw new error_1.CloudBaseError('Migration.Name 只允许小写字母和下划线');
+                (0, error_1.throwInvalidParam)('Migration.Name 只允许小写字母和下划线');
             }
             if (!((_a = migration.Query) === null || _a === void 0 ? void 0 : _a.trim())) {
-                throw new error_1.CloudBaseError('Migration.Query 不能为空');
+                (0, error_1.throwInvalidParam)('Migration.Query 不能为空');
             }
         }
         if (LockTimeoutMs !== undefined && LockTimeoutMs < 0) {
-            throw new error_1.CloudBaseError('LockTimeoutMs 不能小于 0');
+            (0, error_1.throwInvalidParam)('LockTimeoutMs 不能小于 0');
         }
         if (StatementTimeoutMs !== undefined && StatementTimeoutMs < 0) {
-            throw new error_1.CloudBaseError('StatementTimeoutMs 不能小于 0');
+            (0, error_1.throwInvalidParam)('StatementTimeoutMs 不能小于 0');
         }
         return this.dbOpService.request('PushPGUserMigrations', Object.assign(Object.assign(Object.assign({ EnvId: EnvId || this.envId, Migrations }, (LockTimeoutMs !== undefined ? { LockTimeoutMs } : {})), (StatementTimeoutMs !== undefined ? { StatementTimeoutMs } : {})), (IncludeAll !== undefined ? { IncludeAll } : {})));
     }
@@ -387,19 +387,19 @@ class DatabaseService {
     async repairPGUserMigrationHistory(options) {
         const { EnvId, MigrationVersion, Name, Status, Reason, Query } = options;
         if (!/^\d{14}$/.test(MigrationVersion)) {
-            throw new error_1.CloudBaseError('MigrationVersion 必须是 14 位数字');
+            (0, error_1.throwInvalidParam)('MigrationVersion 必须是 14 位数字');
         }
         if (!/^[a-z_]+$/.test(Name)) {
-            throw new error_1.CloudBaseError('Name 只允许小写字母和下划线');
+            (0, error_1.throwInvalidParam)('Name 只允许小写字母和下划线');
         }
         if (Status !== 'applied' && Status !== 'reverted') {
-            throw new error_1.CloudBaseError('Status 只允许 applied 或 reverted');
+            (0, error_1.throwInvalidParam)('Status 只允许 applied 或 reverted');
         }
         if (!(Reason === null || Reason === void 0 ? void 0 : Reason.trim())) {
-            throw new error_1.CloudBaseError('Reason 不能为空');
+            (0, error_1.throwInvalidParam)('Reason 不能为空');
         }
         if (Status === 'applied' && !(Query === null || Query === void 0 ? void 0 : Query.trim())) {
-            throw new error_1.CloudBaseError('Status=applied 时 Query 不能为空');
+            (0, error_1.throwInvalidParam)('Status=applied 时 Query 不能为空');
         }
         const params = {
             EnvId: EnvId || this.envId,
@@ -421,10 +421,10 @@ class DatabaseService {
     async listPGUserMigrations(options = {}) {
         const { EnvId, Limit, Offset } = options;
         if (Limit !== undefined && (Limit < 1 || Limit > 500)) {
-            throw new error_1.CloudBaseError('Limit 取值范围为 [1, 500]');
+            (0, error_1.throwInvalidParam)('Limit 取值范围为 [1, 500]');
         }
         if (Offset !== undefined && Offset < 0) {
-            throw new error_1.CloudBaseError('Offset 不能小于 0');
+            (0, error_1.throwInvalidParam)('Offset 不能小于 0');
         }
         return this.dbOpService.request('ListPGUserMigrations', Object.assign(Object.assign({ EnvId: EnvId || this.envId }, (Limit !== undefined ? { Limit } : {})), (Offset !== undefined ? { Offset } : {})));
     }
@@ -436,7 +436,7 @@ class DatabaseService {
     async listAllPGUserMigrations(options = {}) {
         const { EnvId, PageSize = 500 } = options;
         if (PageSize < 1 || PageSize > 500) {
-            throw new error_1.CloudBaseError('PageSize 取值范围为 [1, 500]');
+            (0, error_1.throwInvalidParam)('PageSize 取值范围为 [1, 500]');
         }
         const migrations = [];
         let offset = 0;
@@ -474,7 +474,7 @@ class DatabaseService {
     async describePGUserMigration(options) {
         const { EnvId, MigrationVersion } = options;
         if (!/^\d{14}$/.test(MigrationVersion)) {
-            throw new error_1.CloudBaseError('MigrationVersion 必须是 14 位数字');
+            (0, error_1.throwInvalidParam)('MigrationVersion 必须是 14 位数字');
         }
         return this.dbOpService.request('DescribePGUserMigration', {
             EnvId: EnvId || this.envId,
@@ -489,7 +489,7 @@ class DatabaseService {
     async describeTaskResult(options) {
         const { EnvId, TaskId } = options;
         if (!(TaskId === null || TaskId === void 0 ? void 0 : TaskId.trim())) {
-            throw new error_1.CloudBaseError('TaskId 不能为空');
+            (0, error_1.throwInvalidParam)('TaskId 不能为空');
         }
         return this.dbOpService.request('DescribeTaskResult', {
             EnvId: EnvId || this.envId,
@@ -501,7 +501,7 @@ class DatabaseService {
         const currEnv = this.environment;
         const instanceId = (_c = (_b = (_a = currEnv.lazyEnvironmentConfig) === null || _a === void 0 ? void 0 : _a.Databases) === null || _b === void 0 ? void 0 : _b[0]) === null || _c === void 0 ? void 0 : _c.InstanceId;
         if (!instanceId) {
-            throw new error_1.CloudBaseError('当前环境未开通文档型数据库');
+            (0, error_1.throwApiError)('当前环境未开通文档型数据库');
         }
         return instanceId;
     }

package/lib/deploy/DatabaseDeployer.js

@@ -27,7 +27,7 @@ class DatabaseDeployer {
      */
     parseMigrationFiles(migrationsDir) {
         if (!fs_1.default.existsSync(migrationsDir)) {
-            throw new error_1.CloudBaseError(`数据库迁移目录不存在: ${migrationsDir}`);
+            (0, error_1.throwNotFound)(`数据库迁移目录不存在: ${migrationsDir}`);
         }
         const files = fs_1.default.readdirSync(migrationsDir)
             .filter(f => f.endsWith('.sql'))
@@ -36,13 +36,13 @@ class DatabaseDeployer {
         for (const file of files) {
             const match = file.match(MIGRATION_FILE_PATTERN);
             if (!match) {
-                throw new error_1.CloudBaseError(`migration 文件名格式错误: ${file}，应为 {14位时间戳}_{小写下划线名称}.sql`);
+                (0, error_1.throwInvalidParam)(`migration 文件名格式错误: ${file}，应为 {14位时间戳}_{小写下划线名称}.sql`);
             }
             const [, version, name] = match;
             const filePath = path_1.default.join(migrationsDir, file);
             const query = fs_1.default.readFileSync(filePath, 'utf-8');
             if (!query.trim()) {
-                throw new error_1.CloudBaseError(`migration 文件内容为空: ${file}`);
+                (0, error_1.throwInvalidParam)(`migration 文件内容为空: ${file}`);
             }
             migrations.push({ Version: version, Name: name, Query: query });
         }
@@ -71,10 +71,9 @@ class DatabaseDeployer {
         }
         catch (error) {
             const err = error;
-            throw new error_1.CloudBaseError(`数据库迁移预览失败 [EnvId=${envId}]：${(err === null || err === void 0 ? void 0 : err.message) || String(error)}`, {
+            throw new error_1.CloudBaseError(`数据库迁移预览失败 [EnvId=${envId}]：${(err === null || err === void 0 ? void 0 : err.message) || String(error)}`, { code: 'API_ERROR', source: 'manager-node',
                 requestId: (err === null || err === void 0 ? void 0 : err.RequestId) || (err === null || err === void 0 ? void 0 : err.requestId),
-                original: err instanceof Error ? err : undefined
-            });
+                original: err instanceof Error ? err : undefined });
         }
         const items = [];
         // pending：将要执行的
@@ -124,16 +123,15 @@ class DatabaseDeployer {
         }
         catch (error) {
             const err = error;
-            throw new error_1.CloudBaseError(`数据库迁移预览失败 [EnvId=${envId}]：${(err === null || err === void 0 ? void 0 : err.message) || String(error)}`, {
+            throw new error_1.CloudBaseError(`数据库迁移预览失败 [EnvId=${envId}]：${(err === null || err === void 0 ? void 0 : err.message) || String(error)}`, { code: 'API_ERROR', source: 'manager-node',
                 requestId: (err === null || err === void 0 ? void 0 : err.RequestId) || (err === null || err === void 0 ? void 0 : err.requestId),
-                original: err instanceof Error ? err : undefined
-            });
+                original: err instanceof Error ? err : undefined });
         }
         if (!preview.Executable) {
             const conflictDetails = (preview.Conflicts || [])
                 .map((c) => `  - ${c.Version}_${c.Name || '?'}: ${c.Reason || c.Message || 'unknown'}`)
                 .join('\n');
-            throw new error_1.CloudBaseError(`数据库迁移存在冲突，中断部署。请先解决以下冲突：\n${conflictDetails}`, {
+            throw new error_1.CloudBaseError(`数据库迁移存在冲突，中断部署。请先解决以下冲突：\n${conflictDetails}`, { code: 'API_ERROR', source: 'manager-node',
                 requestId: preview.RequestId
             });
         }
@@ -151,24 +149,22 @@ class DatabaseDeployer {
         }
         catch (error) {
             const err = error;
-            throw new error_1.CloudBaseError(`数据库迁移提交失败 [EnvId=${envId}]：${(err === null || err === void 0 ? void 0 : err.message) || String(error)}`, {
+            throw new error_1.CloudBaseError(`数据库迁移提交失败 [EnvId=${envId}]：${(err === null || err === void 0 ? void 0 : err.message) || String(error)}`, { code: 'API_ERROR', source: 'manager-node',
                 requestId: (err === null || err === void 0 ? void 0 : err.RequestId) || (err === null || err === void 0 ? void 0 : err.requestId),
-                original: err instanceof Error ? err : undefined
-            });
+                original: err instanceof Error ? err : undefined });
         }
         // 4. 轮询等待完成
         try {
             await this.waitForTask(envId, result.TaskId, DEFAULT_TIMEOUT_MS);
         }
         catch (error) {
-            if (error instanceof error_1.CloudBaseError) {
+            if ((0, error_1.isCloudBaseError)(error)) {
                 throw error;
             }
             const err = error;
-            throw new error_1.CloudBaseError(`数据库迁移任务等待失败 [TaskId=${result.TaskId}]：${(err === null || err === void 0 ? void 0 : err.message) || String(error)}`, {
+            throw new error_1.CloudBaseError(`数据库迁移任务等待失败 [TaskId=${result.TaskId}]：${(err === null || err === void 0 ? void 0 : err.message) || String(error)}`, { code: 'API_ERROR', source: 'manager-node',
                 requestId: (err === null || err === void 0 ? void 0 : err.RequestId) || (err === null || err === void 0 ? void 0 : err.requestId),
-                original: err instanceof Error ? err : undefined
-            });
+                original: err instanceof Error ? err : undefined });
         }
         return { taskId: result.TaskId };
     }
@@ -180,7 +176,7 @@ class DatabaseDeployer {
     resolveMigrationsDir(cwd, migrations) {
         const raw = migrations || './cloudbase/migrations';
         if (path_1.default.isAbsolute(raw) || raw.startsWith('/')) {
-            throw new error_1.CloudBaseError('database.migrations 仅支持相对路径（例如 ./cloudbase/migrations）');
+            (0, error_1.throwInvalidParam)('database.migrations 仅支持相对路径（例如 ./cloudbase/migrations）');
         }
         return path_1.default.resolve(cwd, raw);
     }
@@ -189,7 +185,7 @@ class DatabaseDeployer {
      */
     assertDatabaseType(config) {
         if (config.type !== 'postgresql') {
-            throw new error_1.CloudBaseError(`database.type 仅支持 postgresql，当前为: ${String(config.type)}`);
+            (0, error_1.throwInvalidParam)(`database.type 仅支持 postgresql，当前为: ${String(config.type)}`);
         }
     }
     /**
@@ -206,10 +202,9 @@ class DatabaseDeployer {
             catch (error) {
                 if (Date.now() - startTime > timeoutMs) {
                     const err = error;
-                    throw new error_1.CloudBaseError(`数据库迁移任务状态查询超时（${timeoutMs / 1000}s），TaskId: ${taskId}，最后错误：${(err === null || err === void 0 ? void 0 : err.message) || String(error)}`, {
+                    throw new error_1.CloudBaseError(`数据库迁移任务状态查询超时（${timeoutMs / 1000}s），TaskId: ${taskId}，最后错误：${(err === null || err === void 0 ? void 0 : err.message) || String(error)}`, { code: 'NETWORK_ERROR', source: 'manager-node',
                         requestId: (err === null || err === void 0 ? void 0 : err.RequestId) || (err === null || err === void 0 ? void 0 : err.requestId),
-                        original: err instanceof Error ? err : undefined
-                    });
+                        original: err instanceof Error ? err : undefined });
                 }
                 await new Promise(resolve => {
                     setTimeout(resolve, POLL_INTERVAL_MS);
@@ -220,12 +215,12 @@ class DatabaseDeployer {
                 return;
             }
             if (task.Status === 'Failed') {
-                throw new error_1.CloudBaseError(`数据库迁移任务失败 [TaskId=${taskId}]: ${task.Reason || '未知原因'}`, {
+                throw new error_1.CloudBaseError(`数据库迁移任务失败 [TaskId=${taskId}]: ${task.Reason || '未知原因'}`, { code: 'API_ERROR', source: 'manager-node',
                     requestId: task.RequestId
                 });
             }
             if (Date.now() - startTime > timeoutMs) {
-                throw new error_1.CloudBaseError(`数据库迁移任务超时（${timeoutMs / 1000}s），TaskId: ${taskId}，当前状态: ${task.Status}/${task.Phase}`, {
+                throw new error_1.CloudBaseError(`数据库迁移任务超时（${timeoutMs / 1000}s），TaskId: ${taskId}，当前状态: ${task.Status}/${task.Phase}`, { code: 'NETWORK_ERROR', source: 'manager-node',
                     requestId: task.RequestId
                 });
             }

package/lib/deploy/DeployOrchestrator.js

@@ -531,10 +531,10 @@ class DeployOrchestrator {
      */
     guardConfig(config) {
         if (!config || typeof config !== 'object') {
-            throw new error_1.CloudBaseError('无效的配置：config 必须为对象');
+            (0, error_1.throwInvalidParam)('无效的配置：config 必须为对象');
         }
         if (!config.envId) {
-            throw new error_1.CloudBaseError('无效的配置：缺少 envId');
+            (0, error_1.throwInvalidParam)('无效的配置：缺少 envId');
         }
     }
 }

package/lib/deploy/FunctionDeployer.js

@@ -447,6 +447,16 @@ class FunctionDeployer {
             return;
         }
         const failures = report.checks.filter(item => item.status === 'fail');
+        // ⚠️ `report.ready === false` 但没有任何 `status === 'fail'` 的检查项（报告不自洽）时，
+        // `failures` 是空数组，直接取 `failures[0].id` 会先抛 TypeError、把真正的校验失败盖掉
+        // （代码评审：边界条件）。这里合成一条兜底失败项，保证 code / message / meta.failures 都有取值。
+        if (failures.length === 0) {
+            failures.push({
+                id: 'CHECK_REPORT_INCONSISTENT',
+                status: 'fail',
+                summary: '部署前检查未通过，但未给出具体失败项，请重试或用 --debug 查看完整报告'
+            });
+        }
         const message = failures
             .map(item => {
             const remediation = item.remediation ? `，${item.remediation}` : '';
@@ -454,7 +464,15 @@ class FunctionDeployer {
         })
             .join('\n');
         throw new error_1.CloudBaseError(`部署前检查未通过：\n${message}`, {
-            code: failures[0].id
+            code: failures[0].id,
+            // code 只能承载第一个失败项，meta.failures 保留全量（埋点才能统计真实分布）
+            meta: {
+                failures: failures.map(item => ({
+                    code: item.id,
+                    summary: item.summary,
+                    remediation: item.remediation
+                }))
+            }
         });
     }
     /**