@cloudbase/cloudbase-mcp 2.34.1 → 2.34.3

package/dist/index.js

@@ -2400,6 +2400,7 @@ exports.apps = (0, types_js_1.defineModule)({
     getSuccess: "CloudBase 应用详情查询成功",
     listVersionsSuccess: "CloudBase 应用版本列表查询成功",
     buildIdRequired: "action=getBuildLog 时必须提供 buildId",
+    buildIdMustBeNumeric: "buildId 必须是数字（云 API DescribeCloudBaseRunBuildLog 的 BuildId 为整数）。收到的值：{buildId}。请使用部署回执或 getAppVersion 返回的 BuildId。",
     buildLogFound: "查询到 {count} 条构建日志",
     buildLogEmpty: "暂无构建日志",
     nextStepQueryBuildLog: "查询构建日志",
@@ -2471,6 +2472,7 @@ exports.apps = (0, types_js_1.defineModule)({
     getSuccess: "CloudBase app details retrieved successfully",
     listVersionsSuccess: "CloudBase app version list retrieved successfully",
     buildIdRequired: "buildId is required when action=getBuildLog",
+    buildIdMustBeNumeric: "buildId must be numeric (the BuildId of the cloud API DescribeCloudBaseRunBuildLog is an integer). Received: {buildId}. Use the BuildId returned by the deploy response or getAppVersion.",
     buildLogFound: "Retrieved {count} build log entries",
     buildLogEmpty: "No build logs yet",
     nextStepQueryBuildLog: "Query build logs",
@@ -3730,7 +3732,7 @@ exports.env = (0, types_js_1.defineModule)({
     "auth.deviceCodeMissing": "未获取到设备码信息，请重试设备码登录",
     "auth.deviceStarted": "已发起设备码登录，请在浏览器中打开 verification_uri 并输入 user_code 完成授权。授权完成后请再次调用 auth(action=\"status\")。",
     "auth.loginStateMissing": "未获取到登录态，请先完成认证",
-    "auth.apiKeyArgsRequired": "action=login_by_api_key 时必须同时提供 apiKey 和 envId。",
+    "auth.apiKeyArgsRequired": "action=login_by_api_key 时必须同时提供 apiKey 和 apiKeyEnvId。",
     "auth.apiKeySuccess": "API Key 认证成功，已获取临时密钥。",
     "auth.apiKeyExchangeFailed": "API Key 换取临时密钥失败。",
     "auth.apiKeyDiagLogin": "\n\n诊断信息：\n- CLOUDBASE_ENV_ID: {envId}\n- CLOUDBASE_API_KEY: {apiKeyPrefix}...（已截断）\n- TCB_SITE: {site}\n\n可能原因：\n1. API Key 已过期或被删除\n2. CLOUDBASE_ENV_ID 与 API Key 所属环境不匹配\n3. API Key 与站点不匹配：国际站环境的 Key 需配置 TCB_SITE=intl（走 ap-singapore 网关）；国内站环境（含 ap-guangzhou/ap-singapore 地域）不要配置 intl\n4. 网络连接问题\n\n建议：请检查 API Key 和环境 ID 是否正确。",
@@ -3943,7 +3945,7 @@ exports.env = (0, types_js_1.defineModule)({
     "auth.deviceCodeMissing": "No device code info was returned; please retry device-code login",
     "auth.deviceStarted": "Device-code login started. Open verification_uri in the browser and enter user_code to complete the authorization. Once authorized, call auth(action=\"status\") again.",
     "auth.loginStateMissing": "No login state was obtained; please complete authentication first",
-    "auth.apiKeyArgsRequired": "Both apiKey and envId must be provided when action=login_by_api_key.",
+    "auth.apiKeyArgsRequired": "Both apiKey and apiKeyEnvId must be provided when action=login_by_api_key.",
     "auth.apiKeySuccess": "API Key authentication succeeded; temporary credentials obtained.",
     "auth.apiKeyExchangeFailed": "Failed to exchange the API Key for temporary credentials.",
     "auth.apiKeyDiagLogin": "\n\nDiagnostics:\n- CLOUDBASE_ENV_ID: {envId}\n- CLOUDBASE_API_KEY: {apiKeyPrefix}... (truncated)\n- TCB_SITE: {site}\n\nPossible causes:\n1. The API Key has expired or was deleted\n2. CLOUDBASE_ENV_ID does not match the environment the API Key belongs to\n3. The API Key does not match the site: keys for international-site environments need TCB_SITE=intl (routed via the ap-singapore gateway); do not set intl for domestic-site environments (including the ap-guangzhou/ap-singapore regions)\n4. Network connectivity issue\n\nSuggestion: check that the API Key and environment ID are correct.",
@@ -4605,6 +4607,9 @@ exports.gateway = (0, types_js_1.defineModule)({
     "create.backendError": "为目标资源配置访问路由失败（后端内部错误）。请确保：1) 目标云函数已成功创建并处于 Active 状态；2) 环境默认 HTTP 域名已完成初始化（IsDefault）；3) 该访问路径未被占用。",
     "create.backendErrorScfHint": "此外注意：HTTP 云函数必须用 upstreamResourceType=WEB_SCF，Event 云函数必须用 SCF；互标会导致此错误。",
     "create.backendErrorSuffix": " 原始错误：{message}",
+    "create.upstreamNotFound": "createRoute 未执行：上游目标不存在。upstreamResourceType={type}、targetName={name} 在环境中未找到，未创建任何路由。请先创建该资源（或核对名称/类型），再重新调用 createRoute。",
+    "create.upstreamCandidates": "当前环境已有的 {type} 目标（最多 10 个，供核对名称）：{candidates}",
+    "create.upstreamNotFoundReason": "核对上游资源名称与 upstreamResourceType 后重试 createRoute",
     "create.privilegeOffHint": "⚠️ HTTP 网关总开关未开启，路由创建成功后访问仍将返回 HTTPSERVICE_NONACTIVATED（403）；请先调用 manageGateway(action=\"enableService\", enable=true) 开启，再立刻探测 accessUrl（通常数秒到约 30 秒内生效，勿盲等 60 秒以上）。",
     "create.privilegeOffReason": "开启 HTTP 网关总开关（EnableService），否则访问路由会报 HTTPSERVICE_NONACTIVATED（403）",
     "create.privilegeUnknownHint": "（无法确认 HTTP 网关开关状态；若访问报 HTTPSERVICE_NONACTIVATED，请用 queryGateway(action=\"getPrivilege\") 查询后用 manageGateway(action=\"enableService\") 开启）",
@@ -4690,6 +4695,9 @@ exports.gateway = (0, types_js_1.defineModule)({
     "create.backendError": "Failed to configure the access route for the target resource (backend internal error). Ensure: 1) the target cloud function is created and Active; 2) the env default HTTP domain is initialized (IsDefault); 3) the access path is not taken.",
     "create.backendErrorScfHint": "Also note: HTTP cloud functions must use upstreamResourceType=WEB_SCF, Event cloud functions must use SCF; swapping them causes this error.",
     "create.backendErrorSuffix": " Original error: {message}",
+    "create.upstreamNotFound": "createRoute skipped: the upstream target does not exist. upstreamResourceType={type}, targetName={name} was not found in this environment; no route was created. Create the resource (or fix the name/type), then call createRoute again.",
+    "create.upstreamCandidates": "Existing {type} targets in this environment (up to 10, for name verification): {candidates}",
+    "create.upstreamNotFoundReason": "Verify the upstream resource name and upstreamResourceType, then retry createRoute",
     "create.privilegeOffHint": "⚠️ The HTTP gateway master switch is off; after the route is created, access will still return HTTPSERVICE_NONACTIVATED (403). Call manageGateway(action=\"enableService\", enable=true) first, then probe accessUrl immediately (usually takes effect within a few seconds to ~30 seconds; do not wait 60+ seconds).",
     "create.privilegeOffReason": "Turn on the HTTP gateway master switch (EnableService), otherwise accessing the route returns HTTPSERVICE_NONACTIVATED (403)",
     "create.privilegeUnknownHint": " (Could not confirm the HTTP gateway switch status; if access returns HTTPSERVICE_NONACTIVATED, query via queryGateway(action=\"getPrivilege\") and enable via manageGateway(action=\"enableService\"))",
@@ -5177,9 +5185,9 @@ exports.permissions = void 0;
 const types_js_1 = __webpack_require__(9921);
 exports.permissions = (0, types_js_1.defineModule)({
     queryTitle: "查询 CloudBase 权限与用户配置",
-    queryDescription: "查询 CloudBase 权限与用户配置，支持查询资源权限（数据库/云函数/存储桶等）、角色列表/详情、应用用户列表/详情，以及网关 OPA 授权策略（对齐 CLI `tcb policy list/get`）。\n\n示例：\n- 查询存储桶权限：`action=\"getResourcePermission\", resourceType=\"storage\", resourceId=\"bucket-name\"`\n- 列出旧网关策略：`action=\"listPolicy\"`（PG / OPA 引擎环境返回空列表，与 CLI 一致）\n- 读取用户 Rego：`action=\"getPolicy\"`；平台扩展策略：`action=\"getPolicy\", extension=true`\n\n📌 跨后端边界提示：调用前先用 `envQuery(action=\"info\", envId=...)` 看 `EnvInfo.RuntimeBackends`。`resourceType=\"noSqlDatabase\"` 查询的是 CloudBase NoSQL 集合规则，与 CloudBase PostgreSQL（PG）表的行级安全（RLS）是两套独立机制——同一个 PG 环境里 NoSQL 集合若仍在使用，对那些集合查询本工具结果**仍然有效**。要查 PG 表 RLS，请改用 `queryPgDatabase(action=\"sql\", sql=\"SELECT * FROM pg_policies WHERE tablename=...\")`。本工具不涉及 MySQL 权限。\n\n⚠️ PostgreSQL 环境：平台 `DescribeResourcePermission` 对 PG 环境会直接拒绝。当 `resourceType=\"function\"` 时，本工具会自动回退到 Manager SDK `describeEnvAuthzConfig`（与 CLI `tcb policy get` 一致，读取 `authz.user.rego`）。显式 OPA 策略请用 `listPolicy` / `getPolicy`。",
+    queryDescription: "查询 CloudBase 权限与用户配置，支持查询资源权限（数据库/云函数/存储桶等）、角色列表/详情、应用用户列表/详情，以及网关 OPA 授权策略（对齐 CLI `tcb policy list/get`）。\n\n示例：\n- 查询存储桶权限：`action=\"getResourcePermission\", resourceType=\"storage\", resourceId=\"bucket-name\"`\n- 列出旧网关策略：`action=\"listPolicy\"`（PG / OPA 引擎环境返回空列表，与 CLI 一致）\n- 读取用户 Rego：`action=\"getPolicy\"`；平台扩展策略：`action=\"getPolicy\", extension=true`\n\n📌 跨后端边界提示：调用前先用 `envQuery(action=\"info\", envId=...)` 看 `EnvInfo.RuntimeBackends`。`resourceType=\"noSqlDatabase\"` 查询的是 CloudBase NoSQL 集合规则，与 CloudBase PostgreSQL（PG）表的行级安全（RLS）是两套独立机制——同一个 PG 环境里 NoSQL 集合若仍在使用，对那些集合查询本工具结果**仍然有效**。要查 PG 表 RLS，请改用 `queryPgDatabase(action=\"sql\", sql=\"SELECT * FROM pg_policies WHERE tablename=...\")`。本工具不涉及 MySQL 权限。\n\n⚠️ PostgreSQL 环境：平台 `DescribeResourcePermission` 对 PG 环境会直接拒绝。当 `resourceType=\"function\"` 时，本工具会自动回退到 Manager SDK `describeEnvAuthzConfig`（与 CLI `tcb policy get` 一致，读取 `authz.user.rego`）。显式 OPA 策略请用 `listPolicy` / `getPolicy`。\n\n⚠️ 角色类 action（`listRoles` / `getRole`）在 **PostgreSQL 类型环境**下平台侧一律拒绝（`The current API does not support PostgreSQL type environments.`）——这是平台能力边界，不是配置问题，**不要在 PG 环境反复重试**；PG 环境请改用 RLS（`managePgDatabase(action=\"execute\")` 跑 `CREATE POLICY`）或控制台管理权限。",
     manageTitle: "管理 CloudBase 权限与用户配置",
-    manageDescription: "管理 CloudBase 权限与用户配置，支持修改资源权限（数据库/云函数/存储桶等）、角色管理、成员与策略增删、应用用户 CRUD，以及设置网关 OPA Rego 策略（对齐 CLI `tcb policy set`）。\n\n示例：\n- 设置存储桶为私有：`action=\"updateResourcePermission\", resourceType=\"storage\", resourceId=\"bucket-name\", permission=\"PRIVATE\"`\n- 创建角色：`action=\"createRole\", roleName=\"admin\", roleIdentity=\"admin\"`\n- 放开云函数匿名/未登录访问（PG 会走 OPA，对齐 CLI `tcb policy set`）：`action=\"updateResourcePermission\", resourceType=\"function\", resourceId=\"myFn\", permission=\"CUSTOM\", securityRule='{\"invoke\":true}'`\n- 直接设置用户 Rego：`action=\"setPolicy\", regoContent=\"package authz.user\\n\\ndefault allow := false\\n\", confirm=true`（⚠️ 立即禁用旧网关鉴权）\n\n注意：`createUser` / `updateUser` 是环境侧应用用户管理能力，适合测试账号、管理员或预置用户，不应替代浏览器里的 Web SDK 注册表单；前端用户名密码注册应使用 `auth.signUp({ username, password })`，登录应使用 `auth.signInWithPassword({ username, password })`。直接在浏览器里用 `auth.signUp` 创建用户名密码用户取决于 SDK/provider 支持，使用前必须验证；不支持时应走后端或管理端边界，不能在浏览器暴露密钥。`securityRule` 的详细语义取决于 `resourceType`：`doc._openid`、`auth.openid`、查询条件子集校验，以及 `create` / `update` / `delete` JSON 模板仅适用于 `resourceType=\"noSqlDatabase\"` 的文档数据库安全规则；配置 `function` 或 `storage` 时，请参考各自官方安全规则文档，而不是复用 NoSQL 模板。\n\n📌 跨后端边界提示：调用前先用 `envQuery(action=\"info\", envId=...)` 看 `EnvInfo.RuntimeBackends`：\n- `resourceType=\"noSqlDatabase\"` 仅作用于 CloudBase NoSQL 文档数据库的集合；CloudBase PostgreSQL（PG）表的行级权限**不**受它控制——PG 表请改用 RLS：`managePgDatabase(action=\"execute\", confirm=true)` 跑 `ALTER TABLE ... ENABLE ROW LEVEL SECURITY` 与 `CREATE POLICY ...`。同一个 PG 环境里如果还有 NoSQL 集合在用，对那些**集合**继续使用 `noSqlDatabase` 规则是正确的——不是\"PG 环境就禁用本工具\"。\n- `resourceType=\"storage\"` 控制的是 NoSQL/COS 存储桶 ACL；PG 的 `pgstore` bucket 不在此 `resourceType` 覆盖范围内。\n- 本工具不涉及 MySQL；MySQL 数据库权限请走 MySQL 自身的 GRANT/REVOKE 语句（通过 `manageMysqlDatabase`）。\n\n⚠️ PostgreSQL 环境：平台 `ModifyResourcePermission` 对 PG 环境会直接拒绝。当 `resourceType=\"function\"` 时，本工具会自动回退到 Manager SDK `modifyEnvAuthzConfig`（与 CLI `tcb policy set` 一致，写入 `authz.user.rego`）。`securityRule` 可传完整 Rego（`package authz.user`）或 `'{\"invoke\":true}'`（自动生成放通 anonymous/unauthenticated 调 functions 的策略）。设置 Rego 后旧网关鉴权会失效，行为与 CLI 相同。显式 OPA 策略请优先用 `action=\"setPolicy\"`。",
+    manageDescription: "管理 CloudBase 权限与用户配置，支持修改资源权限（数据库/云函数/存储桶等）、角色管理、成员与策略增删、应用用户 CRUD，以及设置网关 OPA Rego 策略（对齐 CLI `tcb policy set`）。\n\n示例：\n- 设置存储桶为私有：`action=\"updateResourcePermission\", resourceType=\"storage\", resourceId=\"bucket-name\", permission=\"PRIVATE\"`\n- 创建角色：`action=\"createRole\", roleName=\"admin\", roleIdentity=\"admin\"`\n- 放开云函数匿名/未登录访问（PG 会走 OPA，对齐 CLI `tcb policy set`）：`action=\"updateResourcePermission\", resourceType=\"function\", resourceId=\"myFn\", permission=\"CUSTOM\", securityRule='{\"invoke\":true}'`\n- 直接设置用户 Rego：`action=\"setPolicy\", regoContent=\"package authz.user\\n\\ndefault allow := false\\n\", confirm=true`（⚠️ 立即禁用旧网关鉴权）\n\n注意：`createUser` / `updateUser` 是环境侧应用用户管理能力，适合测试账号、管理员或预置用户，不应替代浏览器里的 Web SDK 注册表单；前端用户名密码注册应使用 `auth.signUp({ username, password })`，登录应使用 `auth.signInWithPassword({ username, password })`。直接在浏览器里用 `auth.signUp` 创建用户名密码用户取决于 SDK/provider 支持，使用前必须验证；不支持时应走后端或管理端边界，不能在浏览器暴露密钥。`securityRule` 的详细语义取决于 `resourceType`：`doc._openid`、`auth.openid`、查询条件子集校验，以及 `create` / `update` / `delete` JSON 模板仅适用于 `resourceType=\"noSqlDatabase\"` 的文档数据库安全规则；配置 `function` 或 `storage` 时，请参考各自官方安全规则文档，而不是复用 NoSQL 模板。\n\n📌 跨后端边界提示：调用前先用 `envQuery(action=\"info\", envId=...)` 看 `EnvInfo.RuntimeBackends`：\n- `resourceType=\"noSqlDatabase\"` 仅作用于 CloudBase NoSQL 文档数据库的集合；CloudBase PostgreSQL（PG）表的行级权限**不**受它控制——PG 表请改用 RLS：`managePgDatabase(action=\"execute\", confirm=true)` 跑 `ALTER TABLE ... ENABLE ROW LEVEL SECURITY` 与 `CREATE POLICY ...`。同一个 PG 环境里如果还有 NoSQL 集合在用，对那些**集合**继续使用 `noSqlDatabase` 规则是正确的——不是\"PG 环境就禁用本工具\"。\n- `resourceType=\"storage\"` 控制的是 NoSQL/COS 存储桶 ACL；PG 的 `pgstore` bucket 不在此 `resourceType` 覆盖范围内。\n- 本工具不涉及 MySQL；MySQL 数据库权限请走 MySQL 自身的 GRANT/REVOKE 语句（通过 `manageMysqlDatabase`）。\n\n⚠️ PostgreSQL 环境：平台 `ModifyResourcePermission` 对 PG 环境会直接拒绝。当 `resourceType=\"function\"` 时，本工具会自动回退到 Manager SDK `modifyEnvAuthzConfig`（与 CLI `tcb policy set` 一致，写入 `authz.user.rego`）。`securityRule` 可传完整 Rego（`package authz.user`）或 `'{\"invoke\":true}'`（自动生成放通 anonymous/unauthenticated 调 functions 的策略）。设置 Rego 后旧网关鉴权会失效，行为与 CLI 相同。显式 OPA 策略请优先用 `action=\"setPolicy\"`。\n\n⚠️ 角色类 action（`createRole` / `deleteRoles` / `updateRole`）在 **PostgreSQL 类型环境**下平台侧一律拒绝（`The current API does not support PostgreSQL type environments.`）——平台能力边界，不是配置问题，**不要在 PG 环境反复重试**；PG 环境请改用 RLS（`managePgDatabase(action=\"execute\")` 跑 `CREATE POLICY`）或控制台管理权限。",
     writeVerificationHint: "对于 {resourceId} 这类有后端权限控制的集合，前端调用 .doc(id).update() / .doc(id).remove() 后，不能只看是否没有抛异常。请显式检查返回结果中的 updated / deleted 是否大于 0；如果 result.code、result.message 存在，或 updated / deleted 为 0，要把它当作真实失败并向上抛错。",
     permissionPropagationHint: "刚更新完 {resourceId} 的安全规则时，后端权限通常在数秒到约 30 秒内生效。若紧接着的真实写操作仍返回 DATABASE_PERMISSION_DENIED，请先间隔数秒用同一登录态重试同一条 .doc(id).update() / .doc(id).remove()；不要盲等数分钟，也不要立刻连续重写规则，更不要在短暂传播窗口里把旧拒绝直接当成规则表达式仍然错误。",
     validateRegoEmpty: "action=setPolicy 需要非空 regoContent（对齐 CLI `tcb policy set <regoContent>`）。",
@@ -5246,9 +5254,9 @@ exports.permissions = (0, types_js_1.defineModule)({
     setPolicySuccess: "用户 OPA Rego 策略设置成功（旧网关鉴权已失效）",
 }, {
     queryTitle: "Query CloudBase permissions and user config",
-    queryDescription: "Query CloudBase permissions and user config: resource permissions (database/functions/buckets etc.), role list/detail, app user list/detail, and gateway OPA authorization policies (aligned with CLI `tcb policy list/get`).\n\nExamples:\n- Query bucket permission: `action=\"getResourcePermission\", resourceType=\"storage\", resourceId=\"bucket-name\"`\n- List legacy gateway policies: `action=\"listPolicy\"` (returns an empty list on PG / OPA engine environments, consistent with the CLI)\n- Read user Rego: `action=\"getPolicy\"`; platform extension policy: `action=\"getPolicy\", extension=true`\n\n📌 Cross-backend boundary note: before calling, check `EnvInfo.RuntimeBackends` via `envQuery(action=\"info\", envId=...)`. `resourceType=\"noSqlDatabase\"` queries CloudBase NoSQL collection rules, which are a separate mechanism from row-level security (RLS) on CloudBase PostgreSQL (PG) tables — in the same PG environment, if NoSQL collections are still in use, querying them with this tool **remains valid**. To query PG table RLS, use `queryPgDatabase(action=\"sql\", sql=\"SELECT * FROM pg_policies WHERE tablename=...\")` instead. This tool does not cover MySQL permissions.\n\n⚠️ PostgreSQL environments: the platform `DescribeResourcePermission` API rejects PG environments outright. When `resourceType=\"function\"`, this tool automatically falls back to the Manager SDK `describeEnvAuthzConfig` (aligned with CLI `tcb policy get`, reading `authz.user.rego`). For explicit OPA policies use `listPolicy` / `getPolicy`.",
+    queryDescription: "Query CloudBase permissions and user config: resource permissions (database/functions/buckets etc.), role list/detail, app user list/detail, and gateway OPA authorization policies (aligned with CLI `tcb policy list/get`).\n\nExamples:\n- Query bucket permission: `action=\"getResourcePermission\", resourceType=\"storage\", resourceId=\"bucket-name\"`\n- List legacy gateway policies: `action=\"listPolicy\"` (returns an empty list on PG / OPA engine environments, consistent with the CLI)\n- Read user Rego: `action=\"getPolicy\"`; platform extension policy: `action=\"getPolicy\", extension=true`\n\n📌 Cross-backend boundary note: before calling, check `EnvInfo.RuntimeBackends` via `envQuery(action=\"info\", envId=...)`. `resourceType=\"noSqlDatabase\"` queries CloudBase NoSQL collection rules, which are a separate mechanism from row-level security (RLS) on CloudBase PostgreSQL (PG) tables — in the same PG environment, if NoSQL collections are still in use, querying them with this tool **remains valid**. To query PG table RLS, use `queryPgDatabase(action=\"sql\", sql=\"SELECT * FROM pg_policies WHERE tablename=...\")` instead. This tool does not cover MySQL permissions.\n\n⚠️ PostgreSQL environments: the platform `DescribeResourcePermission` API rejects PG environments outright. When `resourceType=\"function\"`, this tool automatically falls back to the Manager SDK `describeEnvAuthzConfig` (aligned with CLI `tcb policy get`, reading `authz.user.rego`). For explicit OPA policies use `listPolicy` / `getPolicy`.\n\n⚠️ Role actions (`listRoles` / `getRole`) are rejected outright by the platform on **PostgreSQL environments** (`The current API does not support PostgreSQL type environments.`). This is a platform capability boundary, not a configuration problem — **do not keep retrying on PG**; use RLS (`managePgDatabase(action=\"execute\")` with `CREATE POLICY`) or the console to manage permissions instead.",
     manageTitle: "Manage CloudBase permissions and user config",
-    manageDescription: "Manage CloudBase permissions and user config: modify resource permissions (database/functions/buckets etc.), role management, member/policy add & remove, app user CRUD, and setting gateway OPA Rego policies (aligned with CLI `tcb policy set`).\n\nExamples:\n- Set a bucket to private: `action=\"updateResourcePermission\", resourceType=\"storage\", resourceId=\"bucket-name\", permission=\"PRIVATE\"`\n- Create a role: `action=\"createRole\", roleName=\"admin\", roleIdentity=\"admin\"`\n- Open a cloud function to anonymous/unauthenticated access (PG goes through OPA, aligned with CLI `tcb policy set`): `action=\"updateResourcePermission\", resourceType=\"function\", resourceId=\"myFn\", permission=\"CUSTOM\", securityRule='{\"invoke\":true}'`\n- Set user Rego directly: `action=\"setPolicy\", regoContent=\"package authz.user\\n\\ndefault allow := false\\n\", confirm=true` (⚠️ immediately disables legacy gateway authorization)\n\nNote: `createUser` / `updateUser` are environment-side app user management capabilities, suitable for test accounts, administrators, or pre-provisioned users; they should not replace the Web SDK signup form in the browser. For frontend username/password signup use `auth.signUp({ username, password })` and for login `auth.signInWithPassword({ username, password })`. Creating username/password users directly in the browser with `auth.signUp` depends on SDK/provider support and must be verified before use; if unsupported, go through a backend or management API boundary and never expose keys in the browser. The detailed semantics of `securityRule` depend on `resourceType`: `doc._openid`, `auth.openid`, query-condition subset validation, and the `create` / `update` / `delete` JSON templates only apply to document database security rules with `resourceType=\"noSqlDatabase\"`; when configuring `function` or `storage`, refer to their official security rule docs instead of reusing NoSQL templates.\n\n📌 Cross-backend boundary note: before calling, check `EnvInfo.RuntimeBackends` via `envQuery(action=\"info\", envId=...)`:\n- `resourceType=\"noSqlDatabase\"` only affects CloudBase NoSQL document database collections; row-level permissions of CloudBase PostgreSQL (PG) tables are **not** controlled by it — for PG tables use RLS instead: run `ALTER TABLE ... ENABLE ROW LEVEL SECURITY` and `CREATE POLICY ...` via `managePgDatabase(action=\"execute\", confirm=true)`. In the same PG environment, if NoSQL collections are still in use, continuing to use `noSqlDatabase` rules for those **collections** is correct — it does not mean \"this tool is disabled on PG environments\".\n- `resourceType=\"storage\"` controls NoSQL/COS bucket ACLs; PG `pgstore` buckets are not covered by this `resourceType`.\n- This tool does not cover MySQL; for MySQL database permissions use MySQL's own GRANT/REVOKE statements (via `manageMysqlDatabase`).\n\n⚠️ PostgreSQL environments: the platform `ModifyResourcePermission` API rejects PG environments outright. When `resourceType=\"function\"`, this tool automatically falls back to the Manager SDK `modifyEnvAuthzConfig` (aligned with CLI `tcb policy set`, writing `authz.user.rego`). `securityRule` accepts a full Rego document (`package authz.user`) or `'{\"invoke\":true}'` (auto-generates a policy allowing anonymous/unauthenticated calls to functions). Setting Rego disables legacy gateway authorization, same as the CLI. Prefer `action=\"setPolicy\"` for explicit OPA policies.",
+    manageDescription: "Manage CloudBase permissions and user config: modify resource permissions (database/functions/buckets etc.), role management, member/policy add & remove, app user CRUD, and setting gateway OPA Rego policies (aligned with CLI `tcb policy set`).\n\nExamples:\n- Set a bucket to private: `action=\"updateResourcePermission\", resourceType=\"storage\", resourceId=\"bucket-name\", permission=\"PRIVATE\"`\n- Create a role: `action=\"createRole\", roleName=\"admin\", roleIdentity=\"admin\"`\n- Open a cloud function to anonymous/unauthenticated access (PG goes through OPA, aligned with CLI `tcb policy set`): `action=\"updateResourcePermission\", resourceType=\"function\", resourceId=\"myFn\", permission=\"CUSTOM\", securityRule='{\"invoke\":true}'`\n- Set user Rego directly: `action=\"setPolicy\", regoContent=\"package authz.user\\n\\ndefault allow := false\\n\", confirm=true` (⚠️ immediately disables legacy gateway authorization)\n\nNote: `createUser` / `updateUser` are environment-side app user management capabilities, suitable for test accounts, administrators, or pre-provisioned users; they should not replace the Web SDK signup form in the browser. For frontend username/password signup use `auth.signUp({ username, password })` and for login `auth.signInWithPassword({ username, password })`. Creating username/password users directly in the browser with `auth.signUp` depends on SDK/provider support and must be verified before use; if unsupported, go through a backend or management API boundary and never expose keys in the browser. The detailed semantics of `securityRule` depend on `resourceType`: `doc._openid`, `auth.openid`, query-condition subset validation, and the `create` / `update` / `delete` JSON templates only apply to document database security rules with `resourceType=\"noSqlDatabase\"`; when configuring `function` or `storage`, refer to their official security rule docs instead of reusing NoSQL templates.\n\n📌 Cross-backend boundary note: before calling, check `EnvInfo.RuntimeBackends` via `envQuery(action=\"info\", envId=...)`:\n- `resourceType=\"noSqlDatabase\"` only affects CloudBase NoSQL document database collections; row-level permissions of CloudBase PostgreSQL (PG) tables are **not** controlled by it — for PG tables use RLS instead: run `ALTER TABLE ... ENABLE ROW LEVEL SECURITY` and `CREATE POLICY ...` via `managePgDatabase(action=\"execute\", confirm=true)`. In the same PG environment, if NoSQL collections are still in use, continuing to use `noSqlDatabase` rules for those **collections** is correct — it does not mean \"this tool is disabled on PG environments\".\n- `resourceType=\"storage\"` controls NoSQL/COS bucket ACLs; PG `pgstore` buckets are not covered by this `resourceType`.\n- This tool does not cover MySQL; for MySQL database permissions use MySQL's own GRANT/REVOKE statements (via `manageMysqlDatabase`).\n\n⚠️ PostgreSQL environments: the platform `ModifyResourcePermission` API rejects PG environments outright. When `resourceType=\"function\"`, this tool automatically falls back to the Manager SDK `modifyEnvAuthzConfig` (aligned with CLI `tcb policy set`, writing `authz.user.rego`). `securityRule` accepts a full Rego document (`package authz.user`) or `'{\"invoke\":true}'` (auto-generates a policy allowing anonymous/unauthenticated calls to functions). Setting Rego disables legacy gateway authorization, same as the CLI. Prefer `action=\"setPolicy\"` for explicit OPA policies.\n\n⚠️ Role actions (`createRole` / `deleteRoles` / `updateRole`) are rejected outright by the platform on **PostgreSQL environments** (`The current API does not support PostgreSQL type environments.`). This is a platform capability boundary, not a configuration problem — **do not keep retrying on PG**; use RLS (`managePgDatabase(action=\"execute\")` with `CREATE POLICY`) or the console to manage permissions instead.",
     writeVerificationHint: "For collections with backend permission control like {resourceId}, after the frontend calls .doc(id).update() / .doc(id).remove(), do not just check that no exception was thrown. Explicitly verify that updated / deleted in the result is greater than 0; if result.code or result.message exists, or updated / deleted is 0, treat it as a real failure and propagate the error.",
     permissionPropagationHint: "Right after updating security rules for {resourceId}, backend permissions usually take effect within a few seconds to about 30 seconds. If an immediate real write still returns DATABASE_PERMISSION_DENIED, wait a few seconds and retry the same .doc(id).update() / .doc(id).remove() with the same login state; do not wait blindly for minutes, do not immediately rewrite the rules repeatedly, and do not treat an old rejection during the short propagation window as evidence that the rule expression is still wrong.",
     validateRegoEmpty: "action=setPolicy requires non-empty regoContent (aligned with CLI `tcb policy set <regoContent>`).",
@@ -7139,9 +7147,15 @@ function registerAppTools(server) {
                 .optional()
                 .describe("版本名称。getAppVersion 时可与 buildId 二选一；已知版本号时优先传该值。"),
             buildId: zod_1.z
-                .string()
+                // ⚠️ 同一字段驱动两条链路、类型要求不同（F13）：
+                //   getAppVersion → SDK describeAppVersion，收 **string**
+                //   getBuildLog   → 云 API DescribeCloudBaseRunBuildLog，BuildId 是 **Integer(int64)**
+                // 收 string | number 并统一归一成 string（保证 getAppVersion 链路不回退），
+                // getBuildLog 分支再转 number 传给云 API。
+                .union([zod_1.z.string(), zod_1.z.number()])
+                .transform((value) => String(value).trim())
                 .optional()
-                .describe("构建 ID。getAppVersion 时可与 versionName 二选一；部署返回 BuildId 后可直接用它轮询状态。getBuildLog 时必填。"),
+                .describe("构建 ID（数字或数字字符串均可）。getAppVersion 时可与 versionName 二选一；部署返回 BuildId 后可直接用它轮询状态。getBuildLog 时必填。"),
             start: zod_1.z
                 .number()
                 .optional()
@@ -7243,15 +7257,22 @@ function registerAppTools(server) {
                 }, (0, index_js_1.t)("apps.listVersionsSuccess")));
             }
             if (action === "getBuildLog") {
-                if (!buildId) {
+                if (buildId === undefined || buildId === null || String(buildId).trim() === "") {
                     throw new Error((0, index_js_1.t)("apps.buildIdRequired"));
                 }
+                // DescribeCloudBaseRunBuildLog 的 BuildId 是 Integer(int64)（官方文档 876/135707），
+                // 传 string 会被后端拒：The value type of parameter BuildId is not valid, input type
+                // should be int64。schema 侧已归一成 string（getAppVersion 需要 string），此处转 number。
+                const numericBuildId = Number(String(buildId).trim());
+                if (!Number.isInteger(numericBuildId) || numericBuildId <= 0) {
+                    throw new Error((0, index_js_1.t)("apps.buildIdMustBeNumeric", { buildId: String(buildId) }));
+                }
                 const result = await cloudbase.commonService("tcb", "2018-06-08").call({
                     Action: "DescribeCloudBaseRunBuildLog",
                     Param: {
                         EnvId: cloudBaseOptions?.envId || process.env.CLOUDBASE_ENV_ID,
                         ServiceName: serviceName,
-                        BuildId: buildId,
+                        BuildId: numericBuildId,
                         Start: start ?? 0,
                     },
                 });
@@ -7260,7 +7281,7 @@ function registerAppTools(server) {
                 return (0, json_content_js_1.jsonContent)(buildEnvelope({
                     action,
                     serviceName,
-                    buildId,
+                    buildId: String(numericBuildId),
                     logs,
                     total: result.Response?.Total || logs.length,
                     nextStart: result.Response?.NextStart,
@@ -7273,7 +7294,8 @@ function registerAppTools(server) {
                 deployType: "static-hosting",
                 serviceName,
                 versionName,
-                buildId,
+                // 该链路要 string（SDK 类型 IDescribeCloudAppVersionParams.BuildId: string）
+                buildId: buildId === undefined ? undefined : String(buildId),
             });
             (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
             // Platform may return Failed/failed; normalize before matching.
@@ -7325,12 +7347,21 @@ function registerAppTools(server) {
                 .optional()
                 .describe("要上传并部署的本地项目根目录绝对路径。本地模式下 deployApp 时必填；通常传源码所在目录（含 package.json 和源码），不是 dist 目录。构建产物目录请用 buildPath 指定。cloud mode 下无需传此参数，改用 cosTimestamp。"),
             cosTimestamp: zod_1.z
-                .coerce
-                .number()
-                .int()
-                .positive()
+                // ⚠️ 不能用 z.coerce.number()：SDK 的 StaticConfig.CosTimestamp（manager-node
+                // types/cloudApp/types.d.ts `CosTimestamp?: string | null`）与后端 CreateCloudApp
+                // 都要求 **string**。coerce 会把外部传入的值（含 getUploadUrl 返回的 unixTimestamp）
+                // 强制转成 number，后端直接拒绝：
+                //   The value type of parameter `StaticConfig.CosTimestamp` is not valid,
+                //   input type should be `string`
+                // 本地路径不受影响，是因为 cosTs 来自 SDK uploadCode() 的 string 返回值、不经 zod。
+                // 因此这里收 string | number，统一归一成 string 后再透传。
+                .union([zod_1.z.string(), zod_1.z.number()])
+                .transform((value) => String(value).trim())
+                .refine((value) => /^[1-9]\d*$/.test(value), {
+                message: "cosTimestamp 必须是由数字组成的正整数时间戳，字符串或数字均可；直接使用 getUploadUrl 返回的 unixTimestamp 即可。",
+            })
                 .optional()
-                .describe("COS 时间戳（正整数 number，来自 getUploadUrl 返回的 unixTimestamp）。传入此值则直接使用已上传的代码创建应用，跳过本地文件上传。需先调用 getUploadUrl 获取预签名 URL，上传 ZIP 包后再传此时间戳。cloud mode 下为必填；本地模式也可传此值代替 filePath。两个路径严格二选一：filePath（本地打包上传）或 cosTimestamp（预签名 URL 上传），同时提供或都不提供都会报错。"),
+                .describe("COS 时间戳（getUploadUrl 返回的 unixTimestamp，字符串或数字均可）。传入则直接用已上传的代码创建应用，跳过本地打包上传；需先 getUploadUrl 拿预签名 URL 并 PUT ZIP。cloud mode 必填。与 filePath 严格二选一，同时提供或都不提供都会报错。"),
             appPath: zod_1.z
                 .string()
                 .optional()
@@ -7464,7 +7495,10 @@ function registerAppTools(server) {
                     }
                 }
                 // Local stdio only: pack directory and upload. Cloud mode must never reach uploadCode.
-                let cosTs = cosTimestamp;
+                // ⚠️ 类型契约（F12）：SDK `StaticConfig.CosTimestamp` 与后端 CreateCloudApp 都要求
+                // **string**。本地路径拿到的 `uploadResult.cosTimestamp` 本就是 SDK 给的 string；
+                // 外部传入的可能是 number（MCP 客户端按 JSON Schema 传数字），这里统一归一。
+                let cosTs = cosTimestamp === undefined ? undefined : String(cosTimestamp);
                 if (!(0, cloud_mode_js_1.isCloudMode)() && filePath) {
                     // Default excludes large build dirs (empirically target/ can be tens of GB).
                     // Merge caller ignore with defaults so explicit ignore does not drop safety excludes.
@@ -7479,7 +7513,9 @@ function registerAppTools(server) {
                         ignore: mergedIgnore,
                     });
                     (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, uploadResult);
-                    cosTs = uploadResult.cosTimestamp;
+                    cosTs = uploadResult.cosTimestamp === undefined
+                        ? undefined
+                        : String(uploadResult.cosTimestamp);
                 }
                 // 构建命令智能默认值
                 const resolvedInstallCmd = installCmd ?? "npm install";
@@ -8008,7 +8044,15 @@ function registerCapiTools(server) {
     const getManager = () => (0, cloudbase_manager_js_1.getCloudBaseManager)({ cloudBaseOptions, requireEnvId: false });
     server.registerTool?.("callCloudApi", {
         title: "capi.title",
-        description: "capi.description",
+        // ⚠️ 不能写成 `description: "capi.description"`（纯词典 key）：注册包装层解析
+        // key 时**不带插值参数**，而 {controlPlaneUrl}/{dependencyUrl} 只在错误路径
+        // （下方 t("capi.errorBuild", …)）传入 → 描述里的占位符永远替换不了，
+        // tools/list 在 zh 与 en 下都会吐字面 `{controlPlaneUrl}`。
+        // 因此这里按实例语言先解析成最终文案（与 env.ts 的 envQuery 别名同款处理）。
+        description: (0, index_js_1.t)("capi.description", {
+            controlPlaneUrl: CLOUDBASE_CONTROL_PLANE_DOC_URL,
+            dependencyUrl: CLOUDBASE_DEPENDENCY_API_DOC_URL,
+        }, server.lang),
         inputSchema: {
             service: zod_1.z
                 .enum(exports.AV)
@@ -8335,6 +8379,7 @@ exports.buildCloudRunDeployNextStep = buildCloudRunDeployNextStep;
 exports.buildCloudRunDeployProgressHint = buildCloudRunDeployProgressHint;
 exports.queryCloudRunEnvStatus = queryCloudRunEnvStatus;
 exports.describeCloudRunEnvStatus = describeCloudRunEnvStatus;
+exports.isCloudRunEnvNotOpenedError = isCloudRunEnvNotOpenedError;
 exports.extractEnvBaseInfoVpc = extractEnvBaseInfoVpc;
 exports.resolveCloudRunDeployVpcInfo = resolveCloudRunDeployVpcInfo;
 exports.buildCreateCloudRunEnvParam = buildCreateCloudRunEnvParam;
@@ -8915,6 +8960,36 @@ async function describeCloudRunEnvStatus(manager, envId) {
         : "unknown";
     return { isExist: true, status, baseInfo };
 }
+/**
+ * 判断「云托管环境未开通 / 不存在」类错误，用于 `describeCloudRunEnvStatus` 失败的归一化分支。
+ *
+ * ⚠️ 必须**同时**看 `error.code` 与 `error.message`：
+ * 报错文案有三套来源且会不一致 —— 英文错误码（`ResourceNotFound.CloudRunEnv`）、
+ * 中文兜底（`[DescribeEnvBaseInfo] 资源不存在`）、旧式 `InvalidParameter.*Env`。
+ * 只匹配 message 时，中文「资源不存在」不含 `ResourceNotFound`/`未开通`/`未初始化`，
+ * 守卫会失效并把裸错误抛给模型（国际站未开通云托管的环境实测命中，见 F2）。
+ *
+ * 调用方只有 `DescribeEnvBaseInfo`（唯一资源就是环境），因此把「资源不存在」纳入
+ * 未开通判定不会误伤其他语义。
+ */
+function isCloudRunEnvNotOpenedError(error) {
+    if (!error) {
+        return false;
+    }
+    const codeCandidates = [
+        error.code,
+        error.Code,
+        error.original?.code,
+        error.original?.Code,
+    ];
+    const codes = codeCandidates
+        .filter((value) => typeof value === "string")
+        .join(" ");
+    const message = error instanceof Error ? error.message : String(error);
+    const haystack = `${codes} ${message}`;
+    return (/ResourceNotFound|not.?initialized|未开通|未初始化|资源不存在|环境不存在/i.test(haystack) ||
+        /InvalidParameter.*(?:Env|CloudRun)/i.test(haystack));
+}
 /** CloudRun EnvType for CreateCloudRunEnv (baas DescribeEnvBaseInfo enum). */
 exports.CLOUDRUN_ENV_TYPE = "baas";
 /**
@@ -9015,12 +9090,11 @@ async function ensureCloudRunEnvInitialized(options) {
         return true;
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        // 错误兜底：未初始化/未开通类错误码。
+        // 错误兜底：未初始化/未开通类错误码。判据统一收敛到 isCloudRunEnvNotOpenedError，
+        // 避免「只匹配 message」被本地化文案（中文「资源不存在」）绕过。
         // 注意：裸 InvalidParameter 可能是普通参数错误，不拦截；仅当其带 Env/CloudRun
         // 上下文（疑似 "EnvironmentId not found / CloudRun Env 未开通"）时才按未初始化处理。
-        if (/ResourceNotFound|not.?initialized|未开通|未初始化/i.test(msg) ||
-            /InvalidParameter.*(?:Env|CloudRun)/i.test(msg)) {
+        if (isCloudRunEnvNotOpenedError(error)) {
             throwCloudRunEnvNotInitialized(options.envId);
         }
         // 其他错误（网络/权限等）不拦截，让上层按原逻辑处理。
@@ -9584,8 +9658,7 @@ function registerCloudRunTools(server) {
                 }
                 catch (error) {
                     const baseMessage = error instanceof Error ? error.message : String(error);
-                    if (/ResourceNotFound|not.?initialized|未开通|未初始化/i.test(baseMessage) ||
-                        /InvalidParameter.*(?:Env|CloudRun)/i.test(baseMessage)) {
+                    if (isCloudRunEnvNotOpenedError(error)) {
                         status = { isExist: false, status: "unopened", baseInfo: {} };
                     }
                     else {
@@ -9678,8 +9751,7 @@ function registerCloudRunTools(server) {
                 }
                 catch (error) {
                     const baseMessage = error instanceof Error ? error.message : String(error);
-                    if (/ResourceNotFound|not.?initialized|未开通|未初始化/i.test(baseMessage) ||
-                        /InvalidParameter.*(?:Env|CloudRun)/i.test(baseMessage)) {
+                    if (isCloudRunEnvNotOpenedError(error)) {
                         current = { isExist: false, status: "unopened", baseInfo: {} };
                     }
                     else {
@@ -19613,7 +19685,7 @@ function registerEnvTools(server) {
                             code: "INVALID_ARGS",
                             message: (0, index_js_1.t)("env.auth.apiKeyArgsRequired", undefined, outLang),
                             next_step: (0, tool_result_js_1.buildAuthNextStep)("login_by_api_key", {
-                                suggestedArgs: { action: "login_by_api_key", apiKey: "<your-api-key>", envId: "<your-env-id>" },
+                                suggestedArgs: { action: "login_by_api_key", apiKey: "<your-api-key>", apiKeyEnvId: "<your-env-id>" },
                             }),
                         });
                     }
@@ -19658,7 +19730,7 @@ function registerEnvTools(server) {
                             auth_mode: "api_key",
                             envId: toolApiKeyEnvId,
                             next_step: (0, tool_result_js_1.buildAuthNextStep)("login_by_api_key", {
-                                suggestedArgs: { action: "login_by_api_key", apiKey: "<your-api-key>", envId: "<your-env-id>" },
+                                suggestedArgs: { action: "login_by_api_key", apiKey: "<your-api-key>", apiKeyEnvId: "<your-env-id>" },
                             }),
                         });
                     }
@@ -19673,7 +19745,7 @@ function registerEnvTools(server) {
                             message: (0, index_js_1.t)("env.auth.apiKeyException", { message }, outLang),
                             auth_mode: "api_key",
                             next_step: (0, tool_result_js_1.buildAuthNextStep)("login_by_api_key", {
-                                suggestedArgs: { action: "login_by_api_key", apiKey: "<your-api-key>", envId: "<your-env-id>" },
+                                suggestedArgs: { action: "login_by_api_key", apiKey: "<your-api-key>", apiKeyEnvId: "<your-env-id>" },
                             }),
                         });
                     }
@@ -19982,14 +20054,7 @@ function registerEnvTools(server) {
                             }
                             (0, logger_js_1.debug)("降级到 listEnvs() 也失败:", fallbackError instanceof Error ? fallbackError : new Error(String(fallbackError)));
                             const enhancedMessage = buildEnvQueryErrorMessage(fallbackError, "list");
-                            return {
-                                content: [
-                                    {
-                                        type: "text",
-                                        text: enhancedMessage,
-                                    },
-                                ],
-                            };
+                            return (0, tool_result_js_1.buildTextErrorResult)(enhancedMessage);
                         }
                     }
                     result = buildEnvQueryListResult({
@@ -20172,14 +20237,7 @@ function registerEnvTools(server) {
                 return toolPayloadResult;
             }
             const enhancedMessage = buildEnvQueryErrorMessage(error, action);
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: enhancedMessage,
-                    },
-                ],
-            };
+            return (0, tool_result_js_1.buildTextErrorResult)(enhancedMessage);
         }
     };
     // Register primary tool name (queryEnv)
@@ -20313,16 +20371,9 @@ function registerEnvTools(server) {
                 if (toolPayloadResult) {
                     return toolPayloadResult;
                 }
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: (0, index_js_1.t)("env.domain.operationFailed", {
-                                message: error instanceof Error ? error.message : String(error),
-                            }),
-                        },
-                    ],
-                };
+                return (0, tool_result_js_1.buildTextErrorResult)((0, index_js_1.t)("env.domain.operationFailed", {
+                    message: error instanceof Error ? error.message : String(error),
+                }));
             }
         });
     } // end: wxide guard for envDomainManagement
@@ -20848,14 +20899,7 @@ function registerEnvTools(server) {
                     message: (0, index_js_1.t)("env.manage.listPackagesFailed", { message: errorMessage }),
                 });
             }
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: (0, index_js_1.t)("env.manage.operationFailed", { message: errorMessage }),
-                    },
-                ],
-            };
+            return (0, tool_result_js_1.buildTextErrorResult)((0, index_js_1.t)("env.manage.operationFailed", { message: errorMessage }));
         }
     });
 }
@@ -24202,6 +24246,123 @@ function registerGatewayTools(server) {
         data: {},
         message: error instanceof Error ? error.message : String(error),
     });
+    /**
+     * 上游目标存在性校验（F1）。
+     *
+     * 背景：`createHttpServiceRoute` 不校验 `UpstreamResourceName` 是否存在，预检
+     * （VerifyHTTPServiceRoute）也只查域名归属/证书/配额，因此**不存在的上游也能真实落库并
+     * 返回 success**，形成悬空路由（path 被占用、指向不存在的目标）。实测两站复现。
+     *
+     * 设计原则：**只在能证明「不存在」时拒绝**。
+     * - 列表接口报错、分页未扫全、类型不支持 → `unknown`，放行并记日志（fail-open）。
+     *   校验失败绝不该阻塞用户创建合法路由。
+     * - 只有扫完全量且确实没有该名称时，才返回 `missing`。
+     *
+     * 覆盖范围：SCF / WEB_SCF（函数列表）、CBR（云托管服务列表）。
+     * NOT covered：STATIC_STORE 的 UpstreamResourceName 是静态托管**实例名/固定别名
+     * staticstore**（不是 CloudApp 应用名），可靠列举要额外走 DescribeStaticStore，且该资源
+     * 随托管启用必然存在、悬空风险低；LH（轻量应用服务器）无列举接口。两者一律 fail-open。
+     */
+    const UPSTREAM_PROBE_PAGE_SIZE = 100;
+    const UPSTREAM_PROBE_MAX_PAGES = 5;
+    const UPSTREAM_PROBE_CANDIDATE_LIMIT = 10;
+    const probeUpstreamResource = async (cloudbase, params) => {
+        const wanted = params.upstreamResourceName.trim();
+        const upstreamResourceType = params.upstreamResourceType;
+        try {
+            if (upstreamResourceType === "SCF" || upstreamResourceType === "WEB_SCF") {
+                // fail-open：老 SDK / mock 没有该 API 时不校验，绝不让「拿不到列表」变成「判定不存在」。
+                if (typeof cloudbase.functions?.getFunctionList !== "function") {
+                    return { status: "unknown", reason: "function-list-api-unavailable" };
+                }
+                const names = new Set();
+                let scanned = 0;
+                let total = Number.POSITIVE_INFINITY;
+                for (let page = 0; page < UPSTREAM_PROBE_MAX_PAGES; page += 1) {
+                    const res = await cloudbase.functions.getFunctionList(UPSTREAM_PROBE_PAGE_SIZE, scanned);
+                    const list = Array.isArray(res?.Functions) ? res.Functions : [];
+                    for (const item of list) {
+                        const name = item?.FunctionName;
+                        if (typeof name === "string" && name) {
+                            names.add(name);
+                        }
+                    }
+                    scanned += list.length;
+                    total = typeof res?.TotalCount === "number" ? res.TotalCount : scanned;
+                    if (names.has(wanted) || list.length === 0 || scanned >= total) {
+                        break;
+                    }
+                }
+                if (names.has(wanted)) {
+                    return { status: "exists" };
+                }
+                if (scanned >= total) {
+                    return {
+                        status: "missing",
+                        candidates: [...names].slice(0, UPSTREAM_PROBE_CANDIDATE_LIMIT),
+                    };
+                }
+                return { status: "unknown", reason: "function-list-partially-scanned" };
+            }
+            if (upstreamResourceType === "CBR") {
+                // fail-open：同上，`cloudrun?.list` 缺失时会短路成 undefined，若不显式拦截会被
+                // 误判成「列表为空 = 目标不存在」，从而错误拒绝合法路由。
+                if (typeof cloudbase.cloudrun?.list !== "function") {
+                    return { status: "unknown", reason: "cloudrun-list-api-unavailable" };
+                }
+                const names = new Set();
+                for (let page = 1; page <= UPSTREAM_PROBE_MAX_PAGES; page += 1) {
+                    const res = await cloudbase.cloudrun.list({
+                        pageSize: UPSTREAM_PROBE_PAGE_SIZE,
+                        pageNum: page,
+                    });
+                    const list = Array.isArray(res?.ServerList) ? res.ServerList : [];
+                    for (const item of list) {
+                        const record = item;
+                        const name = record?.ServerName ?? record?.Name;
+                        if (typeof name === "string" && name) {
+                            names.add(name);
+                        }
+                    }
+                    const total = typeof res?.Total === "number" ? res.Total : names.size;
+                    if (names.has(wanted) || list.length === 0 || names.size >= total) {
+                        break;
+                    }
+                }
+                if (names.has(wanted)) {
+                    return { status: "exists" };
+                }
+                return {
+                    status: "missing",
+                    candidates: [...names].slice(0, UPSTREAM_PROBE_CANDIDATE_LIMIT),
+                };
+            }
+            // STATIC_STORE / LH：无可靠的实例列举通路，不校验（见上方说明）。
+            return { status: "unknown", reason: `unsupported-upstream-type:${upstreamResourceType}` };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { status: "unknown", reason: message };
+        }
+    };
+    /** 上游缺失时的候选列举工具，按类型给出下一步可用的只读入口。 */
+    const upstreamProbeNextAction = (upstreamResourceType) => {
+        if (upstreamResourceType === "SCF" || upstreamResourceType === "WEB_SCF") {
+            return {
+                tool: "queryFunctions",
+                action: "listFunctions",
+                reason: (0, index_js_1.t)("gateway.create.upstreamNotFoundReason"),
+            };
+        }
+        if (upstreamResourceType === "CBR") {
+            return {
+                tool: "queryCloudRun",
+                action: "list",
+                reason: (0, index_js_1.t)("gateway.create.upstreamNotFoundReason"),
+            };
+        }
+        return null;
+    };
     const verifyHttpServiceRouteOrFail = async (params) => {
         const cloudbase = await getManager();
         let result;
@@ -24688,6 +24849,46 @@ function registerGatewayTools(server) {
             case "createRoute": {
                 const cloudbase = await getManager();
                 const payload = await normalizeRoutePayload(input);
+                // 上游目标存在性校验（F1）：平台侧不校验 UpstreamResourceName，不存在的目标也会
+                // 真实落库形成悬空路由并返回 success。能证明不存在就拒绝，校验不了就放行（fail-open）。
+                const upstreamProbe = await probeUpstreamResource(cloudbase, {
+                    upstreamResourceType: payload.resolved.upstreamResourceType,
+                    upstreamResourceName: payload.resolved.upstreamResourceName,
+                });
+                if (upstreamProbe.status === "missing") {
+                    const nextAction = upstreamProbeNextAction(payload.resolved.upstreamResourceType);
+                    return {
+                        success: false,
+                        data: {
+                            action: "createRoute",
+                            upstreamResourceType: payload.resolved.upstreamResourceType,
+                            targetName: payload.resolved.upstreamResourceName,
+                            path: payload.resolved.path,
+                            candidates: upstreamProbe.candidates,
+                            ...(upstreamProbe.candidates.length
+                                ? {
+                                    candidateHint: (0, index_js_1.t)("gateway.create.upstreamCandidates", {
+                                        type: payload.resolved.upstreamResourceType,
+                                        candidates: upstreamProbe.candidates.join("、"),
+                                    }),
+                                }
+                                : {}),
+                        },
+                        message: (0, index_js_1.t)("gateway.create.upstreamNotFound", {
+                            type: payload.resolved.upstreamResourceType,
+                            name: payload.resolved.upstreamResourceName,
+                        }),
+                        ...(nextAction ? { nextActions: [nextAction] } : {}),
+                    };
+                }
+                if (upstreamProbe.status === "unknown") {
+                    // 校验不了不阻塞创建，但要留痕，便于排查「为什么这次没拦住」。
+                    server.logger?.({
+                        type: "errorToolCall",
+                        toolName: "manageGateway",
+                        message: `createRoute upstream probe skipped (${payload.resolved.upstreamResourceType}/${payload.resolved.upstreamResourceName}): ${upstreamProbe.reason}`,
+                    });
+                }
                 // Probe → create: ownership / cert / quota / conflict checks before create.
                 const verifyFailure = await verifyHttpServiceRouteOrFail({
                     envId: payload.EnvId,
@@ -26277,9 +26478,28 @@ function registerHostingTools(server) {
                     try {
                         const checkResult = await cloudbase.hosting.findFiles({
                             prefix: input.cloudPath,
-                            maxKeys: 1,
+                            maxKeys: 100,
                         });
-                        if (Array.isArray(checkResult) && checkResult.length > 0) {
+                        // ⚠️ 回查有两个坑，都会让 verified 失真：
+                        // 1) findFiles 返回 **COS 风格对象**（列表在 Contents 内），直接用
+                        //    `Array.isArray(checkResult)` 判断会静默失效、恒判 verified=true。
+                        //    统一走 extractFileList 归一化。
+                        // 2) findFiles 是 **prefix** 语义：删单文件 /a/b.txt 时，若同前缀的
+                        //    /a/b.txt.bak 还在也会命中 → 把「已删成功」误判成未验证。
+                        //    单文件场景必须精确比对 Key（前缀场景见 normalizeFileFields 的 key 字段）。
+                        const remaining = normalizeFileFields(checkResult);
+                        const stripLeadingSlash = (value) => value.replace(/^\/+/, '');
+                        const targetPath = stripLeadingSlash(input.cloudPath ?? '');
+                        const stillExists = input.isDir
+                            ? remaining.length > 0
+                            : remaining.some((file) => {
+                                const key = typeof file.key === 'string' ? file.key : '';
+                                // 拿不到 Key 时保守按「仍存在」处理，避免误报已验证
+                                if (!key)
+                                    return true;
+                                return stripLeadingSlash(key) === targetPath;
+                            });
+                        if (stillExists) {
                             deleteVerified = false;
                             verificationError = verificationError ?? (0, index_js_1.t)('hosting.deleteVerifyFailed');
                         }
@@ -32504,7 +32724,7 @@ class TelemetryReporter {
         const arch = os_1.default.arch(); // 系统架构
         // Build-time injected version; guard for vitest / non-webpack runtimes.
         const mcpVersion = process.env.npm_package_version ||
-            ( true ? "2.34.1" : 0);
+            ( true ? "2.34.3" : 0);
         return {
             userAgent: `${osType} ${osRelease} ${arch} ${nodeVersion} CloudBase-MCP/${mcpVersion}`,
             deviceId: this.deviceId,
@@ -32908,6 +33128,7 @@ exports.ToolPayloadError = void 0;
 exports.buildJsonToolResult = buildJsonToolResult;
 __webpack_unused_export__ = isBusinessFailureToolResult;
 exports.withBusinessFailureIsError = withBusinessFailureIsError;
+exports.buildTextErrorResult = buildTextErrorResult;
 exports.isToolPayloadError = isToolPayloadError;
 exports.toolPayloadErrorToResult = toolPayloadErrorToResult;
 exports.buildAuthNextStep = buildAuthNextStep;
@@ -32974,6 +33195,28 @@ function withBusinessFailureIsError(result) {
     }
     return { ...record, isError: true };
 }
+/**
+ * 纯文本失败回执：**必须显式带 `isError: true`**。
+ *
+ * 为什么需要它：`withBusinessFailureIsError` 只能识别结构化的 `{ success: false }`
+ * 载荷（`isBusinessFailureToolResult` 会 JSON.parse 文本内容再嗅 `success`）。工具在自己
+ * 的 catch 里返回 `{ content: [{ type: "text", text }] }` 这种**纯文本**回执时，文本不是
+ * JSON，嗅探不到任何失败标记 → 客户端只看到 `isError: false`，把失败当成功处理。
+ *
+ * 实测（F7）：`queryEnv(action="usage")` 不带 envId 时抛出的引导文案就是这样返回的，
+ * 只看 `isError` 的客户端会漏判。MCP 协议里 `isError` 是唯一可靠的失败标记，别省。
+ */
+function buildTextErrorResult(text) {
+    return {
+        content: [
+            {
+                type: "text",
+                text,
+            },
+        ],
+        isError: true,
+    };
+}
 class ToolPayloadError extends Error {
     payload;
     constructor(payload) {
@@ -33085,6 +33328,9 @@ ${envId}
     // 构建标题
     const title = `MCP工具错误: ${toolName}`;
     // 构建问题描述
+    // ⚠️ MCP 版本必须优先取构建期注入的 __MCP_VERSION__：hosted 场景下进程是 BFF 的进程，
+    // process.env.npm_package_version 是**宿主应用**的版本（实测报出 0.0.1，与 MCP 自身
+    // 版本 2.34.2 自相矛盾）；仅在未注入（源码直跑）时才回退到它。
     const body = `## 错误描述
 工具 \`${toolName}\` 执行时发生错误
 
@@ -33096,7 +33342,7 @@ ${envIdSection}
 ## 环境信息
 - 操作系统: ${os_1.default.type()} ${os_1.default.release()}
 - Node.js版本: ${process.version}
-- MCP 版本：${process.env.npm_package_version || ( true ? "2.34.1" : 0)}
+- MCP 版本：${( true ? "2.34.3" : 0) || 0 || 0}
 - 系统架构: ${os_1.default.arch()}
 - 时间: ${new Date().toISOString()}
 - 请求ID: ${requestId}
@@ -33185,7 +33431,7 @@ function createWrappedHandler(name, handler, server) {
                 requestId,
                 ide: server.ide || process.env.INTEGRATION_IDE || ''
             });
-            const mcpVersion =  true ? "2.34.1" : 0;
+            const mcpVersion =  true ? "2.34.3" : 0;
             const requestIdSuffix = requestId ? `\n🆔 RequestId: ${requestId}` : '';
             const enhancedErrorMessage = `${errorMessage}${requestIdSuffix}\n\n📦 CloudBase MCP v${mcpVersion}\n🔗 遇到问题？请复制以下链接到浏览器打开\n即可自动携带错误详情快速创建 GitHub Issue：\n${issueLink}`;
             // 创建新的错误对象，保持原有的错误类型但更新消息