fix: callCloudApi MCP 工具的 schema/prompt 未清晰标注 CreateUser 必填参数（EnvId），且参数命名约定不明确导致模型首次调用失败

doc/mcp-tools.md

@@ -2292,6 +2292,8 @@ Agent 域统一写入口。支持创建、更新和删除远端 Agent。
 **云函数**: `DescribeFunctions`、`CreateFunction`、`UpdateFunctionCode`、`DeleteFunction`
 **数据库**: `CreateMySQLInstance`、`DescribeMySQLInstances`、`DestroyMySQLInstance`
 
+**CreateUser 快速提醒**：首次调用 `tcb/CreateUser` 时，`params` 至少带上 `EnvId` 与 `Name`；参数键名使用官方 PascalCase：`Name` / `Type` / `UserStatus`，不要写成 `UserName` / `UserType` / `Status`。如果手头只有环境别名或当前会话环境，请先解析出真实 `EnvId` 再调用。
+
 销毁环境时，常见做法是至少带上 `EnvId` 和 `BypassCheck: true`，如果环境已经处于隔离期再按文档补 `IsForce: true`。
 
 #### 参数
@@ -2308,12 +2310,12 @@ Agent 域统一写入口。支持创建、更新和删除远端 Agent。
       name: "action",
       type: "string",
       required: true,
-      description: `具体 Action 名称，需符合对应服务的官方 API 定义。若不确定正确 Action，请先查官方文档；不要用近义词或历史命名进行猜测。tcb 常用 Action：环境管理 CreateEnv/ModifyEnv/DescribeEnvs/DestroyEnv、用户管理 CreateUser/ModifyUser/DescribeUserList/DeleteUsers、认证配置 EditAuthConfig、云函数 DescribeFunctions/CreateFunction、数据库 CreateMySQLInstance 等。`,
+      description: `具体 Action 名称，需符合对应服务的官方 API 定义。若不确定正确 Action，请先查官方文档；不要用近义词或历史命名进行猜测。tcb 常用 Action：环境管理 CreateEnv/ModifyEnv/DescribeEnvs/DestroyEnv、用户管理 CreateUser/ModifyUser/DescribeUserList/DeleteUsers、认证配置 EditAuthConfig、云函数 DescribeFunctions/CreateFunction、数据库 CreateMySQLInstance 等。特别是创建用户时，Action 固定为 \`CreateUser\`，不要自行改写名称。`,
     },
     {
       name: "params",
       type: "object",
-      description: `Action 对应的参数对象，键名需与官方 API 定义一致。某些 Action 需要携带 EnvId 等信息；如不确定参数结构，请先查官方文档。tcb 示例：\`{ "service": "tcb", "action": "DestroyEnv", "params": { "EnvId": "env-xxx", "BypassCheck": true } }\`，如果环境已经处于隔离期，可再补 \`IsForce: true\`；更新环境别名则可用 \`{ "service": "tcb", "action": "ModifyEnv", "params": { "EnvId": "env-xxx", "Alias": "demo" } }\`。若你的场景是通过 HTTP 协议直接集成 auth/functions/cloudrun/storage/mysqldb 等 CloudBase 业务 API，请优先使用 OpenAPI / Swagger 或 searchKnowledgeBase(mode="openapi")，而不是优先使用 callCloudApi。`,
+      description: `Action 对应的参数对象，键名需与官方 API 定义完全一致（区分大小写）。如果是 \`tcb/CreateUser\`，请先记住两个高频约束：\`params\` 必填 \`EnvId\` 与 \`Name\`，并且参数键名必须使用官方 PascalCase（\`Name\` / \`Type\` / \`UserStatus\`），不要写成 \`UserName\` / \`UserType\` / \`Status\`。某些 Action 需要携带 EnvId 等信息；如不确定参数结构，请先查官方文档。tcb 示例：销毁环境 \`{ "service": "tcb", "action": "DestroyEnv", "params": { "EnvId": "env-xxx", "BypassCheck": true } }\`，如果环境已经处于隔离期，可再补 \`IsForce: true\`；更新环境别名 \`{ "service": "tcb", "action": "ModifyEnv", "params": { "EnvId": "env-xxx", "Alias": "demo" } }\`；创建用户 \`{ "service": "tcb", "action": "CreateUser", "params": { "EnvId": "env-xxx", "Name": "username", "NickName": "昵称", "Phone": "13800138000", "Email": "user@example.com", "Type": "internalUser", "UserStatus": "ACTIVE" } }\`（注意：使用 \`Name\` 而不是 \`UserName\`，\`Type\` 而不是 \`UserType\`，\`UserStatus\` 而不是 \`Status\`）。若你的场景是通过 HTTP 协议直接集成 auth/functions/cloudrun/storage/mysqldb 等 CloudBase 业务 API，请优先使用 OpenAPI / Swagger 或 searchKnowledgeBase(mode="openapi")，而不是优先使用 callCloudApi。`,
     }
   ]}
 />

mcp/src/tools/capi.test.ts

@@ -1,5 +1,22 @@
-import { describe, expect, it } from "vitest";
-import { buildCapiErrorMessage } from "./capi.js";
+import { describe, expect, it, vi } from "vitest";
+import { buildCapiErrorMessage, registerCapiTools } from "./capi.js";
+import type { ExtendedMcpServer } from "../server.js";
+
+function createMockServer() {
+  const tools: Record<string, { meta: any; handler: (args: any) => Promise<any> }> = {};
+
+  const server: ExtendedMcpServer = {
+    cloudBaseOptions: { envId: "env-test", region: "ap-guangzhou" },
+    logger: vi.fn(),
+    registerTool: vi.fn((name: string, meta: any, handler: (args: any) => Promise<any>) => {
+      tools[name] = { meta, handler };
+    }),
+  } as unknown as ExtendedMcpServer;
+
+  registerCapiTools(server);
+
+  return { tools };
+}
 
 describe("buildCapiErrorMessage", () => {
   it("suggests likely tcb actions for invalid action names", () => {
@@ -27,6 +44,20 @@ describe("buildCapiErrorMessage", () => {
     expect(message).toContain("/**");
   });
 
+  it("adds CreateUser-specific required-key and field-name guidance", () => {
+    const message = buildCapiErrorMessage(
+      "tcb",
+      "CreateUser",
+      new Error("The request is missing the required parameter `EnvId`."),
+    );
+
+    expect(message).toContain("必填参数");
+    expect(message).toContain("`EnvId`");
+    expect(message).toContain("`Name`");
+    expect(message).toContain("`Name`（而非 `UserName`）");
+    expect(message).toContain("`UserStatus`（而非 `Status`）");
+  });
+
   it("does not inject tcb action suggestions for non-tcb services", () => {
     const message = buildCapiErrorMessage(
       "scf",
@@ -37,3 +68,15 @@ describe("buildCapiErrorMessage", () => {
     expect(message).not.toContain("可能的 tcb Action");
   });
 });
+
+describe("registerCapiTools", () => {
+  it("front-loads CreateUser guidance in the tool description", () => {
+    const { tools } = createMockServer();
+    const description = tools.callCloudApi.meta.description as string;
+
+    expect(description).toContain("CreateUser 快速提醒");
+    expect(description).toContain("`EnvId` 与 `Name`");
+    expect(description).toContain("`Name` / `Type` / `UserStatus`");
+    expect(description).toContain("`UserName` / `UserType` / `Status`");
+  });
+});

mcp/src/tools/capi.ts

@@ -112,7 +112,7 @@ export function buildCapiErrorMessage(service: AllowedService, action: string, e
     const suggestions: string[] = [];
     const tcbEntry = service === "tcb" ? findTcbActionEntry(action) : undefined;
     const hasInvalidActionError = /invalid or not found|does not exist|not recognized/i.test(baseMessage);
-    const hasParameterError = /parameter\s+`?.+?`?\s+is not recognized|MissingParameter|missing parameter|missing required/i.test(baseMessage);
+    const hasParameterError = /parameter\s+`?.+?`?\s+is not recognized|MissingParameter|missing parameter|missing the required parameter|missing required/i.test(baseMessage);
     const hasInvalidParameterValueError = /invalid parameter value/i.test(baseMessage);
 
     if (hasInvalidActionError) {
@@ -146,6 +146,10 @@ export function buildCapiErrorMessage(service: AllowedService, action: string, e
             if (paramsTypeHint) {
                 suggestions.push(paramsTypeHint);
             }
+            // Add specific guidance for CreateUser to avoid common parameter naming mistakes
+            if (tcbEntry.action === "CreateUser") {
+                suggestions.push("特别注意：创建用户时请使用 `Name`（而非 `UserName`）、`Type`（而非 `UserType`）、`UserStatus`（而非 `Status`）作为参数键名。");
+            }
         }
     }
 
@@ -205,6 +209,8 @@ export function registerCapiTools(server: ExtendedMcpServer) {
 **云函数**: \`DescribeFunctions\`、\`CreateFunction\`、\`UpdateFunctionCode\`、\`DeleteFunction\`
 **数据库**: \`CreateMySQLInstance\`、\`DescribeMySQLInstances\`、\`DestroyMySQLInstance\`
 
+**CreateUser 快速提醒**：首次调用 \`tcb/CreateUser\` 时，\`params\` 至少带上 \`EnvId\` 与 \`Name\`；参数键名使用官方 PascalCase：\`Name\` / \`Type\` / \`UserStatus\`，不要写成 \`UserName\` / \`UserType\` / \`Status\`。如果手头只有环境别名或当前会话环境，请先解析出真实 \`EnvId\` 再调用。
+
 销毁环境时，常见做法是至少带上 \`EnvId\` 和 \`BypassCheck: true\`，如果环境已经处于隔离期再按文档补 \`IsForce: true\`。`,
             inputSchema: {
                 service: z
@@ -215,12 +221,12 @@ export function registerCapiTools(server: ExtendedMcpServer) {
                 action: z
                     .string()
                     .min(1)
-                    .describe("具体 Action 名称，需符合对应服务的官方 API 定义。若不确定正确 Action，请先查官方文档；不要用近义词或历史命名进行猜测。tcb 常用 Action：环境管理 CreateEnv/ModifyEnv/DescribeEnvs/DestroyEnv、用户管理 CreateUser/ModifyUser/DescribeUserList/DeleteUsers、认证配置 EditAuthConfig、云函数 DescribeFunctions/CreateFunction、数据库 CreateMySQLInstance 等。"),
+                    .describe("具体 Action 名称，需符合对应服务的官方 API 定义。若不确定正确 Action，请先查官方文档；不要用近义词或历史命名进行猜测。tcb 常用 Action：环境管理 CreateEnv/ModifyEnv/DescribeEnvs/DestroyEnv、用户管理 CreateUser/ModifyUser/DescribeUserList/DeleteUsers、认证配置 EditAuthConfig、云函数 DescribeFunctions/CreateFunction、数据库 CreateMySQLInstance 等。特别是创建用户时，Action 固定为 `CreateUser`，不要自行改写名称。"),
                 params: z
                     .record(z.any())
                     .optional()
                     .describe(
-                        "Action 对应的参数对象，键名需与官方 API 定义一致。某些 Action 需要携带 EnvId 等信息；如不确定参数结构，请先查官方文档。tcb 示例：`{ \"service\": \"tcb\", \"action\": \"DestroyEnv\", \"params\": { \"EnvId\": \"env-xxx\", \"BypassCheck\": true } }`，如果环境已经处于隔离期，可再补 `IsForce: true`；更新环境别名则可用 `{ \"service\": \"tcb\", \"action\": \"ModifyEnv\", \"params\": { \"EnvId\": \"env-xxx\", \"Alias\": \"demo\" } }`。若你的场景是通过 HTTP 协议直接集成 auth/functions/cloudrun/storage/mysqldb 等 CloudBase 业务 API，请优先使用 OpenAPI / Swagger 或 searchKnowledgeBase(mode=\"openapi\")，而不是优先使用 callCloudApi。",
+                        "Action 对应的参数对象，键名需与官方 API 定义完全一致（区分大小写）。如果是 `tcb/CreateUser`，请先记住两个高频约束：`params` 必填 `EnvId` 与 `Name`，并且参数键名必须使用官方 PascalCase（`Name` / `Type` / `UserStatus`），不要写成 `UserName` / `UserType` / `Status`。某些 Action 需要携带 EnvId 等信息；如不确定参数结构，请先查官方文档。tcb 示例：销毁环境 `{ \"service\": \"tcb\", \"action\": \"DestroyEnv\", \"params\": { \"EnvId\": \"env-xxx\", \"BypassCheck\": true } }`，如果环境已经处于隔离期，可再补 `IsForce: true`；更新环境别名 `{ \"service\": \"tcb\", \"action\": \"ModifyEnv\", \"params\": { \"EnvId\": \"env-xxx\", \"Alias\": \"demo\" } }`；创建用户 `{ \"service\": \"tcb\", \"action\": \"CreateUser\", \"params\": { \"EnvId\": \"env-xxx\", \"Name\": \"username\", \"NickName\": \"昵称\", \"Phone\": \"13800138000\", \"Email\": \"user@example.com\", \"Type\": \"internalUser\", \"UserStatus\": \"ACTIVE\" } }`（注意：使用 `Name` 而不是 `UserName`，`Type` 而不是 `UserType`，`UserStatus` 而不是 `Status`）。若你的场景是通过 HTTP 协议直接集成 auth/functions/cloudrun/storage/mysqldb 等 CloudBase 业务 API，请优先使用 OpenAPI / Swagger 或 searchKnowledgeBase(mode=\"openapi\")，而不是优先使用 callCloudApi。",
                     ),
             },
             annotations: {

scripts/tools.json

@@ -2463,7 +2463,7 @@
     },
     {
       "name": "callCloudApi",
-      "description": "通用的云 API 调用工具，主要用于 CloudBase / 腾讯云管控面与依赖资源相关 API 调用。调用前请先确认 service、Action 与 Param，避免猜测 Action 名称。如果你的目标是通过 HTTP 协议直接集成 auth/functions/cloudrun/storage/mysqldb 等 CloudBase 业务 API，请不要优先使用 callCloudApi，而应优先查看对应 OpenAPI / Swagger。现有 OpenAPI / Swagger 能力不是通用的管控面 Action 集合；管控面 API 请优先参考 CloudBase API 概览 https://cloud.tencent.com/document/product/876/34809 与云开发依赖资源接口指引 https://cloud.tencent.com/document/product/876/34808。对于 tcb service，常用 Action 分类如下：\n\n**环境管理**: `CreateEnv`、`ModifyEnv`、`DescribeEnvs`、`DestroyEnv`\n**用户管理**: `CreateUser`、`ModifyUser`、`DescribeUserList`、`DeleteUsers`\n**认证配置**: `EditAuthConfig`、`DescribeAuthDomains`\n**云函数**: `DescribeFunctions`、`CreateFunction`、`UpdateFunctionCode`、`DeleteFunction`\n**数据库**: `CreateMySQLInstance`、`DescribeMySQLInstances`、`DestroyMySQLInstance`\n\n销毁环境时，常见做法是至少带上 `EnvId` 和 `BypassCheck: true`，如果环境已经处于隔离期再按文档补 `IsForce: true`。",
+      "description": "通用的云 API 调用工具，主要用于 CloudBase / 腾讯云管控面与依赖资源相关 API 调用。调用前请先确认 service、Action 与 Param，避免猜测 Action 名称。如果你的目标是通过 HTTP 协议直接集成 auth/functions/cloudrun/storage/mysqldb 等 CloudBase 业务 API，请不要优先使用 callCloudApi，而应优先查看对应 OpenAPI / Swagger。现有 OpenAPI / Swagger 能力不是通用的管控面 Action 集合；管控面 API 请优先参考 CloudBase API 概览 https://cloud.tencent.com/document/product/876/34809 与云开发依赖资源接口指引 https://cloud.tencent.com/document/product/876/34808。对于 tcb service，常用 Action 分类如下：\n\n**环境管理**: `CreateEnv`、`ModifyEnv`、`DescribeEnvs`、`DestroyEnv`\n**用户管理**: `CreateUser`、`ModifyUser`、`DescribeUserList`、`DeleteUsers`\n**认证配置**: `EditAuthConfig`、`DescribeAuthDomains`\n**云函数**: `DescribeFunctions`、`CreateFunction`、`UpdateFunctionCode`、`DeleteFunction`\n**数据库**: `CreateMySQLInstance`、`DescribeMySQLInstances`、`DestroyMySQLInstance`\n\n**CreateUser 快速提醒**：首次调用 `tcb/CreateUser` 时，`params` 至少带上 `EnvId` 与 `Name`；参数键名使用官方 PascalCase：`Name` / `Type` / `UserStatus`，不要写成 `UserName` / `UserType` / `Status`。如果手头只有环境别名或当前会话环境，请先解析出真实 `EnvId` 再调用。\n\n销毁环境时，常见做法是至少带上 `EnvId` 和 `BypassCheck: true`，如果环境已经处于隔离期再按文档补 `IsForce: true`。",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -2483,12 +2483,12 @@
           "action": {
             "type": "string",
             "minLength": 1,
-            "description": "具体 Action 名称，需符合对应服务的官方 API 定义。若不确定正确 Action，请先查官方文档；不要用近义词或历史命名进行猜测。tcb 常用 Action：环境管理 CreateEnv/ModifyEnv/DescribeEnvs/DestroyEnv、用户管理 CreateUser/ModifyUser/DescribeUserList/DeleteUsers、认证配置 EditAuthConfig、云函数 DescribeFunctions/CreateFunction、数据库 CreateMySQLInstance 等。"
+            "description": "具体 Action 名称，需符合对应服务的官方 API 定义。若不确定正确 Action，请先查官方文档；不要用近义词或历史命名进行猜测。tcb 常用 Action：环境管理 CreateEnv/ModifyEnv/DescribeEnvs/DestroyEnv、用户管理 CreateUser/ModifyUser/DescribeUserList/DeleteUsers、认证配置 EditAuthConfig、云函数 DescribeFunctions/CreateFunction、数据库 CreateMySQLInstance 等。特别是创建用户时，Action 固定为 `CreateUser`，不要自行改写名称。"
           },
           "params": {
             "type": "object",
             "additionalProperties": {},
-            "description": "Action 对应的参数对象，键名需与官方 API 定义一致。某些 Action 需要携带 EnvId 等信息；如不确定参数结构，请先查官方文档。tcb 示例：`{ \"service\": \"tcb\", \"action\": \"DestroyEnv\", \"params\": { \"EnvId\": \"env-xxx\", \"BypassCheck\": true } }`，如果环境已经处于隔离期，可再补 `IsForce: true`；更新环境别名则可用 `{ \"service\": \"tcb\", \"action\": \"ModifyEnv\", \"params\": { \"EnvId\": \"env-xxx\", \"Alias\": \"demo\" } }`。若你的场景是通过 HTTP 协议直接集成 auth/functions/cloudrun/storage/mysqldb 等 CloudBase 业务 API，请优先使用 OpenAPI / Swagger 或 searchKnowledgeBase(mode=\"openapi\")，而不是优先使用 callCloudApi。"
+            "description": "Action 对应的参数对象，键名需与官方 API 定义完全一致（区分大小写）。如果是 `tcb/CreateUser`，请先记住两个高频约束：`params` 必填 `EnvId` 与 `Name`，并且参数键名必须使用官方 PascalCase（`Name` / `Type` / `UserStatus`），不要写成 `UserName` / `UserType` / `Status`。某些 Action 需要携带 EnvId 等信息；如不确定参数结构，请先查官方文档。tcb 示例：销毁环境 `{ \"service\": \"tcb\", \"action\": \"DestroyEnv\", \"params\": { \"EnvId\": \"env-xxx\", \"BypassCheck\": true } }`，如果环境已经处于隔离期，可再补 `IsForce: true`；更新环境别名 `{ \"service\": \"tcb\", \"action\": \"ModifyEnv\", \"params\": { \"EnvId\": \"env-xxx\", \"Alias\": \"demo\" } }`；创建用户 `{ \"service\": \"tcb\", \"action\": \"CreateUser\", \"params\": { \"EnvId\": \"env-xxx\", \"Name\": \"username\", \"NickName\": \"昵称\", \"Phone\": \"13800138000\", \"Email\": \"user@example.com\", \"Type\": \"internalUser\", \"UserStatus\": \"ACTIVE\" } }`（注意：使用 `Name` 而不是 `UserName`，`Type` 而不是 `UserType`，`UserStatus` 而不是 `Status`）。若你的场景是通过 HTTP 协议直接集成 auth/functions/cloudrun/storage/mysqldb 等 CloudBase 业务 API，请优先使用 OpenAPI / Swagger 或 searchKnowledgeBase(mode=\"openapi\")，而不是优先使用 callCloudApi。"
           }
         },
         "required": [