fix(attribution): MCP工具cloudPath参数格式约定不明确导致路径不一致 (issue_mnri8zp3_vsojwy)

Author: CodeBuddy Attribution Bot

doc/mcp-tools.md

@@ -426,10 +426,10 @@ classDiagram
 <thead><tr><th>参数名</th><th>类型</th><th>必填</th><th>说明</th></tr></thead>
 <tbody>
 <tr><td><code>localPath</code></td><td>string</td><td></td><td>本地文件或文件夹路径，需要是绝对路径，例如 /tmp/files/data.txt。</td></tr>
-<tr><td><code>cloudPath</code></td><td>string</td><td></td><td>静态托管云端文件或文件夹路径，例如 files/data.txt。若部署到子路径，请同时检查构建配置中的 publicPath、base、assetPrefix 等是否为相对路径。云存储对象路径请改用 manageStorage。</td></tr>
+<tr><td><code>cloudPath</code></td><td>string</td><td></td><td>静态托管云端文件或文件夹路径，例如 /、/vite-test/ 或 /vite-test/index.html。可带或不带前导 /，服务端会自动规范化；/ 表示托管根目录。若部署到子路径，请同时检查构建配置中的 publicPath、base、assetPrefix 等是否为相对路径。云存储对象路径请改用 manageStorage。</td></tr>
 <tr><td><code>files</code></td><td>array of object</td><td></td><td>多文件上传配置 默认值: []</td></tr>
 <tr><td><code>files[].localPath</code></td><td>string</td><td>是</td><td></td></tr>
-<tr><td><code>files[].cloudPath</code></td><td>string</td><td>是</td><td></td></tr>
+<tr><td><code>files[].cloudPath</code></td><td>string</td><td>是</td><td>静态托管路径，可带或不带前导 /；服务端会自动规范化</td></tr>
 <tr><td><code>ignore</code></td><td>string \| array of string</td><td></td><td>忽略文件模式</td></tr>
 </tbody>
 </table>
@@ -444,7 +444,7 @@ classDiagram
 <table>
 <thead><tr><th>参数名</th><th>类型</th><th>必填</th><th>说明</th></tr></thead>
 <tbody>
-<tr><td><code>cloudPath</code></td><td>string</td><td>是</td><td>云端文件或文件夹路径</td></tr>
+<tr><td><code>cloudPath</code></td><td>string</td><td>是</td><td>云端文件或文件夹路径，可带或不带前导 /；服务端会自动规范化，/ 表示根目录</td></tr>
 <tr><td><code>isDir</code></td><td>boolean</td><td></td><td>是否为文件夹 默认值: false</td></tr>
 </tbody>
 </table>
@@ -459,7 +459,7 @@ classDiagram
 <table>
 <thead><tr><th>参数名</th><th>类型</th><th>必填</th><th>说明</th></tr></thead>
 <tbody>
-<tr><td><code>prefix</code></td><td>string</td><td>是</td><td>匹配前缀</td></tr>
+<tr><td><code>prefix</code></td><td>string</td><td>是</td><td>匹配前缀，可带或不带前导 /；服务端会自动规范化，/ 表示根目录前缀</td></tr>
 <tr><td><code>marker</code></td><td>string</td><td></td><td>起始对象键标记</td></tr>
 <tr><td><code>maxKeys</code></td><td>number</td><td></td><td>单次返回最大条目数</td></tr>
 </tbody>

mcp/DOC.md

@@ -105,10 +105,10 @@
 
 | 工具标识                  | 功能描述                                  | 核心参数                                                                                     |
 |---------------------------|-----------------------------------------|---------------------------------------------------------------------------------------------|
-| `uploadFiles`             | 上传文件到静态网站托管                    | `localPath`（选填，本地文件或文件夹路径），`cloudPath`（选填，静态托管相对路径，不带前导 `/`），`files`（选填，多文件上传配置，`files[].cloudPath` 同样使用不带前导 `/` 的托管相对路径），`ignore`（选填，忽略文件模式） |
+| `uploadFiles`             | 上传文件到静态网站托管                    | `localPath`（选填，本地文件或文件夹路径），`cloudPath`（选填，静态托管云端路径，可带或不带前导 `/`，`/` 表示托管根目录），`files`（选填，多文件上传配置，`files[].cloudPath` 同样可带或不带前导 `/`，服务端会自动规范化），`ignore`（选填，忽略文件模式） |
 | `listFiles`               | 获取静态网站托管的文件列表                | 无                                                                                           |
-| `deleteFiles`             | 删除静态网站托管的文件或文件夹            | `cloudPath`（必填，托管相对路径，不带前导 `/`），`isDir`（选填，是否为文件夹，默认为 `false`）     |
-| `findFiles`               | 搜索静态网站托管的文件                    | `prefix`（必填，托管相对路径前缀，不带前导 `/`），`marker`（选填，起始对象键标记），`maxKeys`（选填，单次返回最大条目数） |
+| `deleteFiles`             | 删除静态网站托管的文件或文件夹            | `cloudPath`（必填，托管云端路径，可带或不带前导 `/`，`/` 表示根目录），`isDir`（选填，是否为文件夹，默认为 `false`）     |
+| `findFiles`               | 搜索静态网站托管的文件                    | `prefix`（必填，托管路径前缀，可带或不带前导 `/`，`/` 表示根目录前缀），`marker`（选填，起始对象键标记），`maxKeys`（选填，单次返回最大条目数） |
 | `createHostingDomain`     | 绑定自定义域名                            | `domain`（必填，自定义域名），`certId`（必填，证书 ID）                                       |
 | `deleteHostingDomain`     | 解绑自定义域名                            | `domain`（必填，自定义域名）                                                                 |
 | `getWebsiteConfig`        | 获取静态网站配置                          | 无                                                                                           |

mcp/Intro.md

@@ -105,10 +105,10 @@
 
 | 工具标识                  | 功能描述                                  | 核心参数                                                                                     |
 |---------------------------|-----------------------------------------|---------------------------------------------------------------------------------------------|
-| `uploadFiles`             | 上传文件到静态网站托管                    | `localPath`（选填，本地文件或文件夹路径），`cloudPath`（选填，静态托管相对路径，不带前导 `/`），`files`（选填，多文件上传配置，`files[].cloudPath` 同样使用不带前导 `/` 的托管相对路径），`ignore`（选填，忽略文件模式） |
+| `uploadFiles`             | 上传文件到静态网站托管                    | `localPath`（选填，本地文件或文件夹路径），`cloudPath`（选填，静态托管云端路径，可带或不带前导 `/`，`/` 表示托管根目录），`files`（选填，多文件上传配置，`files[].cloudPath` 同样可带或不带前导 `/`，服务端会自动规范化），`ignore`（选填，忽略文件模式） |
 | `listFiles`               | 获取静态网站托管的文件列表                | 无                                                                                           |
-| `deleteFiles`             | 删除静态网站托管的文件或文件夹            | `cloudPath`（必填，托管相对路径，不带前导 `/`），`isDir`（选填，是否为文件夹，默认为 `false`）     |
-| `findFiles`               | 搜索静态网站托管的文件                    | `prefix`（必填，托管相对路径前缀，不带前导 `/`），`marker`（选填，起始对象键标记），`maxKeys`（选填，单次返回最大条目数） |
+| `deleteFiles`             | 删除静态网站托管的文件或文件夹            | `cloudPath`（必填，托管云端路径，可带或不带前导 `/`，`/` 表示根目录），`isDir`（选填，是否为文件夹，默认为 `false`）     |
+| `findFiles`               | 搜索静态网站托管的文件                    | `prefix`（必填，托管路径前缀，可带或不带前导 `/`，`/` 表示根目录前缀），`marker`（选填，起始对象键标记），`maxKeys`（选填，单次返回最大条目数） |
 | `createHostingDomain`     | 绑定自定义域名                            | `domain`（必填，自定义域名），`certId`（必填，证书 ID）                                       |
 | `deleteHostingDomain`     | 解绑自定义域名                            | `domain`（必填，自定义域名）                                                                 |
 | `getWebsiteConfig`        | 获取静态网站配置                          | 无                                                                                           |

mcp/src/tools/hosting.ts

@@ -280,11 +280,11 @@ export function registerHostingTools(server: ExtendedMcpServer) {
       description: "上传文件到静态网站托管，仅用于 Web 站点部署，不用于云存储对象上传。部署前请先完成构建；如果站点会部署到子路径，请检查构建配置中的 publicPath、base、assetPrefix 等是否使用相对路径，避免静态资源加载失败。若需要上传 COS 云存储文件，请使用 manageStorage。对于本地评测、现有脚手架补全或仅需本地开发服务器验证的任务，通常不需要调用此工具，除非用户明确要求部署站点。",
       inputSchema: {
         localPath: z.string().optional().describe("本地文件或文件夹路径，需要是绝对路径，例如 /tmp/files/data.txt。"),
-        cloudPath: z.string().optional().describe("静态托管云端文件或文件夹路径，例如 vite-test 或 vite-test/index.html；应使用不带前导 / 的托管相对路径。若部署到子路径，请同时检查构建配置中的 publicPath、base、assetPrefix 等是否为相对路径。云存储对象路径请改用 manageStorage。"),
+        cloudPath: z.string().optional().describe("静态托管云端文件或文件夹路径，例如 /、/vite-test/ 或 /vite-test/index.html。可带或不带前导 /，服务端会自动规范化；/ 表示托管根目录。若部署到子路径，请同时检查构建配置中的 publicPath、base、assetPrefix 等是否为相对路径。云存储对象路径请改用 manageStorage。"),
         files: z.array(z.object({
           localPath: z.string(),
-          cloudPath: z.string().describe("静态托管相对路径，不带前导 /")
-        })).default([]).describe("多文件上传配置，其中每个 cloudPath 都应使用不带前导 / 的托管相对路径"),
+          cloudPath: z.string().describe("静态托管路径，可带或不带前导 /；服务端会自动规范化")
+        })).default([]).describe("多文件上传配置，其中每个 cloudPath 都可带或不带前导 /；服务端会自动规范化"),
         ignore: z.union([z.string(), z.array(z.string())]).optional().describe("忽略文件模式")
       },
       annotations: {
@@ -386,7 +386,7 @@ export function registerHostingTools(server: ExtendedMcpServer) {
       title: "删除静态文件",
       description: "删除静态网站托管的文件或文件夹",
       inputSchema: {
-        cloudPath: z.string().describe("云端文件或文件夹路径，使用不带前导 / 的托管相对路径"),
+        cloudPath: z.string().describe("云端文件或文件夹路径，可带或不带前导 /；服务端会自动规范化，/ 表示根目录"),
         isDir: z.boolean().default(false).describe("是否为文件夹")
       },
       annotations: {
@@ -423,7 +423,7 @@ export function registerHostingTools(server: ExtendedMcpServer) {
       title: "搜索静态文件",
       description: "搜索静态网站托管的文件",
       inputSchema: {
-        prefix: z.string().describe("匹配前缀，使用不带前导 / 的托管相对路径前缀"),
+        prefix: z.string().describe("匹配前缀，可带或不带前导 /；服务端会自动规范化，/ 表示根目录前缀"),
         marker: z.string().optional().describe("起始对象键标记"),
         maxKeys: z.number().optional().describe("单次返回最大条目数")
       },

mcp/src/tools/storage-hosting-guidance.test.ts

@@ -37,7 +37,8 @@ describe("storage and hosting tool guidance", () => {
     expect(tools.uploadFiles.meta.description).toContain("manageStorage");
     expect(tools.uploadFiles.meta.description).toContain("通常不需要调用此工具");
     expect(tools.uploadFiles.meta.inputSchema.cloudPath.description).toContain("云存储对象路径请改用 manageStorage");
-    expect(tools.uploadFiles.meta.inputSchema.cloudPath.description).toContain("不带前导 /");
+    expect(tools.uploadFiles.meta.inputSchema.cloudPath.description).toContain("可带或不带前导 /");
+    expect(tools.uploadFiles.meta.inputSchema.cloudPath.description).toContain("/ 表示托管根目录");
     expect(tools.manageStorage.meta.description).toContain("仅用于 COS/Storage 对象");
     expect(tools.manageStorage.meta.description).toContain("不用于静态网站托管");
   });