fix: MCP 云函数日志查询工具参数设计与错误提示不清晰

config/.claude/skills/cloud-functions/SKILL.md

@@ -245,9 +245,28 @@ The `scf_bootstrap` binary path must match the runtime — see the full mapping
 
 ### Logs
 
-- `queryFunctions(action="listFunctionLogs")`
-- `queryFunctions(action="getFunctionLogDetail")`
-- If these are unavailable, read `./references/operations-and-config.md` before any `callCloudApi` fallback
+**查询云函数日志**：使用 `queryFunctions` 工具
+
+- `queryFunctions(action="listFunctionLogs", functionName="xxx")` — 查询特定函数的执行日志
+- `queryFunctions(action="getFunctionLogDetail", requestId="xxx")` — 查看单条日志详情
+
+**区分 `queryLogs` 工具**：
+- `queryFunctions` 用于查询特定云函数的执行日志，需要提供 `functionName`
+- `queryLogs` 用于搜索 CLS 日志服务（跨服务日志聚合），使用 CLS 查询语法
+
+**示例**：
+```javascript
+// 查询云函数 my-function 的最近日志
+queryFunctions(action="listFunctionLogs", functionName="my-function", limit=10)
+
+// 查看特定请求的日志详情
+queryFunctions(action="getFunctionLogDetail", requestId="abc-123")
+
+// 使用 CLS 搜索所有服务的错误日志（跨服务）
+queryLogs(action="searchLogs", queryString="ERROR", service="tcb")
+```
+
+If these are unavailable, read `./references/operations-and-config.md` before any `callCloudApi` fallback
 
 ### Gateway exposure
 
@@ -260,3 +279,4 @@ The `scf_bootstrap` binary path must match the runtime — see the full mapping
 - `cloudrun-development` -> container services, long-lived runtimes, Agent hosting
 - `http-api` -> raw CloudBase HTTP API invocation patterns
 - `cloudbase-platform` -> general CloudBase platform decisions
+- `ops-inspector` -> AIOps-style inspection and log search across services

config/source/skills/cloud-functions/SKILL.md

@@ -245,9 +245,28 @@ The `scf_bootstrap` binary path must match the runtime — see the full mapping
 
 ### Logs
 
-- `queryFunctions(action="listFunctionLogs")`
-- `queryFunctions(action="getFunctionLogDetail")`
-- If these are unavailable, read `./references/operations-and-config.md` before any `callCloudApi` fallback
+**查询云函数日志**：使用 `queryFunctions` 工具
+
+- `queryFunctions(action="listFunctionLogs", functionName="xxx")` — 查询特定函数的执行日志
+- `queryFunctions(action="getFunctionLogDetail", requestId="xxx")` — 查看单条日志详情
+
+**区分 `queryLogs` 工具**：
+- `queryFunctions` 用于查询特定云函数的执行日志，需要提供 `functionName`
+- `queryLogs` 用于搜索 CLS 日志服务（跨服务日志聚合），使用 CLS 查询语法
+
+**示例**：
+```javascript
+// 查询云函数 my-function 的最近日志
+queryFunctions(action="listFunctionLogs", functionName="my-function", limit=10)
+
+// 查看特定请求的日志详情
+queryFunctions(action="getFunctionLogDetail", requestId="abc-123")
+
+// 使用 CLS 搜索所有服务的错误日志（跨服务）
+queryLogs(action="searchLogs", queryString="ERROR", service="tcb")
+```
+
+If these are unavailable, read `./references/operations-and-config.md` before any `callCloudApi` fallback
 
 ### Gateway exposure
 
@@ -260,3 +279,4 @@ The `scf_bootstrap` binary path must match the runtime — see the full mapping
 - `cloudrun-development` -> container services, long-lived runtimes, Agent hosting
 - `http-api` -> raw CloudBase HTTP API invocation patterns
 - `cloudbase-platform` -> general CloudBase platform decisions
+- `ops-inspector` -> AIOps-style inspection and log search across services

mcp/src/tools/functions.ts

@@ -1412,23 +1412,53 @@ export function registerFunctionTools(server: ExtendedMcpServer) {
     {
       title: "查询云函数域资源",
       description:
-        "函数域统一只读入口。通过更自解释的 action 查询函数列表、函数详情、日志、层、触发器和代码下载地址。",
+        "函数域统一只读入口。通过更自解释的 action 查询函数列表、函数详情、日志、层、触发器和代码下载地址。" +
+        "\n\n**查询云函数日志**：使用 `action=\"listFunctionLogs\"`，需要提供 `functionName` 参数。" +
+        "\n- 示例：`queryFunctions(action=\"listFunctionLogs\", functionName=\"my-function\")`" +
+        "\n- 如需查看日志详情：`queryFunctions(action=\"getFunctionLogDetail\", requestId=\"xxx\")`" +
+        "\n\n**区分 `queryLogs` 工具**：" +
+        "\n- 本工具用于查询特定云函数的执行日志" +
+        "\n- `queryLogs` 工具用于搜索 CLS 日志服务（跨服务日志聚合）",
       inputSchema: {
         action: z
           .enum(QUERY_FUNCTION_ACTIONS)
-          .describe("只读操作类型，例如 listFunctions、getFunctionDetail、listFunctionLogs"),
-        functionName: z.string().optional().describe("函数名称。函数相关 action 必填"),
-        limit: z.number().optional().describe("分页数量。列表类 action 可选"),
-        offset: z.number().optional().describe("分页偏移。列表类 action 可选"),
-        codeSecret: z.string().optional().describe("代码保护密钥"),
-        startTime: z.string().optional().describe("日志查询开始时间"),
-        endTime: z.string().optional().describe("日志查询结束时间"),
-        requestId: z.string().optional().describe("日志 requestId。获取日志详情时必填"),
-        qualifier: z.string().optional().describe("函数版本，日志查询时可选"),
-        runtime: z.string().optional().describe("层查询的运行时筛选"),
+          .describe(
+            "只读操作类型：" +
+            "\n- `listFunctions`: 列出所有云函数" +
+            "\n- `getFunctionDetail`: 获取函数详情（需要 functionName）" +
+            "\n- `listFunctionLogs`: 查询函数执行日志（需要 functionName）" +
+            "\n- `getFunctionLogDetail`: 获取日志详情（需要 requestId）" +
+            "\n- `listFunctionLayers`: 列出函数绑定的层" +
+            "\n- `listLayers`: 列出所有层" +
+            "\n- `listLayerVersions`: 列出层的版本" +
+            "\n- `getLayerVersionDetail`: 获取层版本详情" +
+            "\n- `listFunctionTriggers`: 列出函数触发器" +
+            "\n- `getFunctionDownloadUrl`: 获取函数代码下载地址"
+          ),
+        functionName: z
+          .string()
+          .optional()
+          .describe("函数名称。`getFunctionDetail`、`listFunctionLogs`、`listFunctionLayers`、`listFunctionTriggers` 等操作必填"),
+        limit: z.number().optional().describe("分页数量。列表类 action 可选，默认值由后端决定"),
+        offset: z.number().optional().describe("分页偏移。列表类 action 可选，默认 0"),
+        codeSecret: z.string().optional().describe("代码保护密钥，用于解密函数代码"),
+        startTime: z
+          .string()
+          .optional()
+          .describe("日志查询开始时间，格式：`YYYY-MM-DD HH:mm:ss`。`listFunctionLogs` 和 `getFunctionLogDetail` 可选"),
+        endTime: z
+          .string()
+          .optional()
+          .describe("日志查询结束时间，格式：`YYYY-MM-DD HH:mm:ss`。`listFunctionLogs` 和 `getFunctionLogDetail` 可选"),
+        requestId: z
+          .string()
+          .optional()
+          .describe("日志请求 ID。`getFunctionLogDetail` 操作必填，可从 `listFunctionLogs` 结果中获取"),
+        qualifier: z.string().optional().describe("函数版本别名，如 $LATEST、$DEFAULT。日志查询时可选"),
+        runtime: z.string().optional().describe("层查询的运行时筛选，如 Nodejs18.15"),
         searchKey: z.string().optional().describe("层名称搜索关键字"),
-        layerName: z.string().optional().describe("层名称。层相关 action 必填"),
-        layerVersion: z.number().optional().describe("层版本号。获取层版本详情时必填"),
+        layerName: z.string().optional().describe("层名称。`listLayerVersions`、`getLayerVersionDetail` 操作必填"),
+        layerVersion: z.number().optional().describe("层版本号。`getLayerVersionDetail` 操作必填"),
       },
       annotations: {
         readOnlyHint: true,

mcp/src/tools/logs.ts

@@ -37,16 +37,55 @@ export function registerLogTools(server: ExtendedMcpServer) {
     "queryLogs",
     {
       title: "查询日志服务",
-      description: "日志域统一只读入口。支持检查日志服务状态并搜索 CLS 日志。",
+      description:
+        "日志域统一只读入口。支持检查日志服务状态并搜索 CLS 日志。" +
+        "\n\n**重要区分**：" +
+        "\n- 查询云函数日志：使用 `queryFunctions(action=\"listFunctionLogs\", functionName=\"xxx\")`" +
+        "\n- 查询 CLS 日志（跨服务日志聚合）：使用本工具 `queryLogs(action=\"searchLogs\")`" +
+        "\n\n**适用场景**：" +
+        "\n- 检查 CLS 日志服务是否开通：`action=\"checkLogService\"`" +
+        "\n- 跨服务日志搜索（如搜索所有 ERROR 日志）：`action=\"searchLogs\"`" +
+        "\n- 按 CLS 语法检索特定服务的日志：`action=\"searchLogs\", service=\"tcb|tcbr\"`",
       inputSchema: {
-        action: z.enum(QUERY_LOG_ACTIONS),
-        queryString: z.string().optional(),
-        service: z.enum(["tcb", "tcbr"]).optional(),
-        startTime: z.string().optional(),
-        endTime: z.string().optional(),
-        limit: z.number().optional(),
-        context: z.string().optional(),
-        sort: z.enum(["asc", "desc"]).optional(),
+        action: z
+          .enum(QUERY_LOG_ACTIONS)
+          .describe(
+            "操作类型：" +
+            "\n- `checkLogService`: 检查 CLS 日志服务是否开通" +
+            "\n- `searchLogs`: 搜索 CLS 日志（需要提供 queryString）"
+          ),
+        queryString: z
+          .string()
+          .optional()
+          .describe(
+            "CLS 查询语句。**action=\"searchLogs\" 时必填**。" +
+            "\n\n**常用查询语法**：" +
+            "\n- `ERROR`: 搜索包含 ERROR 的日志" +
+            "\n- `functionName:myFunc AND level:ERROR`: 搜索函数 myFunc 的错误日志" +
+            "\n- `timeout OR 超时`: 搜索超时相关日志" +
+            "\n- `coldStart OR 冷启动`: 搜索冷启动日志" +
+            "\n- `statusCode:>499`: 搜索 5xx 错误" +
+            "\n\n**注意**：查询云函数日志时，优先使用 `queryFunctions(action=\"listFunctionLogs\")`"
+          ),
+        service: z
+          .enum(["tcb", "tcbr"])
+          .optional()
+          .describe(
+            "日志来源服务：" +
+            "\n- `tcb`: 云函数、数据库、存储等基础服务日志" +
+            "\n- `tcbr`: CloudRun 容器服务日志"
+          ),
+        startTime: z
+          .string()
+          .optional()
+          .describe("查询开始时间，格式：`YYYY-MM-DD HH:mm:ss`，如 `2024-01-01 00:00:00`"),
+        endTime: z
+          .string()
+          .optional()
+          .describe("查询结束时间，格式：`YYYY-MM-DD HH:mm:ss`，如 `2024-01-01 23:59:59`"),
+        limit: z.number().optional().describe("返回日志条数限制，默认 20"),
+        context: z.string().optional().describe("翻页上下文，用于继续上一次查询"),
+        sort: z.enum(["asc", "desc"]).optional().describe("按时间排序：`asc` 升序，`desc` 降序"),
       },
       annotations: {
         readOnlyHint: true,
@@ -89,7 +128,14 @@ export function registerLogTools(server: ExtendedMcpServer) {
         }
 
         if (!queryString) {
-          throw new Error("action=searchLogs 时必须提供 queryString");
+          throw new Error(
+            "action=\"searchLogs\" 时必须提供 queryString 参数。" +
+            "\n\n常用查询示例：" +
+            "\n- `ERROR`: 搜索所有错误日志" +
+            "\n- `functionName:xxx AND level:ERROR`: 搜索特定函数的错误日志" +
+            "\n- `timeout`: 搜索超时日志" +
+            "\n\n如果需要查询特定云函数的执行日志，建议使用 `queryFunctions(action=\"listFunctionLogs\", functionName=\"xxx\")`"
+          );
         }
         const result = await cloudbase.log.searchClsLog({
           queryString,