fix(attribution): MCP uploadFiles 工具上传成功后静态托管仍返回 404，缺少部署完整性校验与后置步骤引导 (issue_moj0dwx7_bkz1io)

Author: CodeBuddy Attribution Bot

config/source/guideline/cloudbase/SKILL.md

@@ -290,6 +290,8 @@ Prefer long-term memory when available: write the scenarios and working rules th
 - Use CloudBase static hosting after build completion
 - Refer to the `web-development` skill for deployment process
 - `uploadFiles` is for static hosting only; if the task needs a COS object that must be queried or polled with the storage SDK, use `manageStorage` / `queryStorage`
+- **Subdirectory deployment pre-check (most common 404 cause):** Before calling `uploadFiles` for a subdirectory deploy, confirm: (1) `base`/`publicPath`/`assetPrefix` is set to the absolute subdirectory path with leading and trailing slashes (e.g. `/vite-test/`), NOT `'./'`; (2) project rebuilt after config change; (3) built files reference assets with the subdirectory prefix; (4) entire `dist/` uploaded, not just `index.html`
+- `cloudPath` for `uploadFiles` is relative to hosting root — no leading `/` (e.g. `vite-test`, not `/vite-test`)
 - Remind users that CDN has a few minutes of cache after deployment
 
 **Backend Deployment:**

config/source/skills/cloudbase-platform/SKILL.md

@@ -102,6 +102,16 @@ Use this skill for **CloudBase platform knowledge** when you need to:
    - Cloud storage is suitable for files with privacy requirements, can get temporary access addresses via temporary file URLs
    - If the task needs COS SDK polling, file metadata lookup, or temporary URLs for an uploaded object, use cloud storage tools (`manageStorage` / `queryStorage`), not `uploadFiles`
 
+2. **Static Hosting Subdirectory Deployment (most common 404 cause)**:
+   - When deploying to a subdirectory (e.g. `/vite-test`), the build config `base`/`publicPath`/`assetPrefix` MUST be set to the absolute path matching the target with both leading and trailing slashes (e.g. `/vite-test/`)
+   - **NEVER use `'./'` or empty string** for subdirectory deployments — relative paths break when the access URL lacks a trailing slash, causing all JS/CSS assets to 404
+   - Before calling `uploadFiles` for a subdirectory deploy, confirm ALL of the following (any failure = deployment will break):
+     1. Build config `base`/`publicPath`/`assetPrefix` is set to the absolute subdirectory path (e.g. `/vite-test/`)
+     2. Project has been rebuilt after the config change
+     3. Built files in `dist/` reference assets with the subdirectory absolute path, not root `/`
+     4. The entire `dist/` directory is uploaded, not just `index.html`
+   - `uploadFiles` `cloudPath` format: relative to hosting root, do NOT include a leading `/` (e.g. `vite-test`, not `/vite-test`)
+
 2. **Static Hosting Domain**:
    - CloudBase static hosting domain can be obtained via `getWebsiteConfig` tool
    - Combine with static hosting file paths to construct final access addresses

config/source/skills/web-development/SKILL.md

@@ -128,9 +128,14 @@ Use this section only when the Web project needs CloudBase platform features.
 ### Static hosting defaults
 
 - Build before deployment
-- Prefer relative asset paths for static hosting compatibility
+- **Subdirectory deployment is the most common source of 404 errors.** When deploying to a subdirectory (e.g. `/vite-test`), the build config `base`/`publicPath`/`assetPrefix` MUST be set to an absolute path matching the target subdirectory with both leading and trailing slashes (e.g. `/vite-test/`). **NEVER use `'./'` or empty string** for subdirectory deployments — when the access URL lacks a trailing slash, relative paths resolve incorrectly and all JS/CSS assets will 404.
+- Before calling `uploadFiles`, verify all of the following (any item failing means deployment will break):
+  1. `base`/`publicPath`/`assetPrefix` is set to the absolute subdirectory path (e.g. `/vite-test/`)
+  2. The project has been rebuilt after changing build config
+  3. The built files in `dist/` reference assets with the subdirectory absolute path, not root `/`
+  4. The entire `dist/` directory is uploaded, not just `index.html`
+- `cloudPath` for `uploadFiles` is relative to the hosting root — do NOT include a leading `/` (e.g. `vite-test`, not `/vite-test`)
 - Use hash routing by default when the project lacks server-side route rewrites
-- If the user does not specify a root path, avoid deploying directly to the site root by default
 
 ### CloudBase quick start
 

config/source/skills/web-development/frameworks.md

@@ -17,6 +17,11 @@
 
 - Treat Vite as the default choice for new Web app setup unless the repo already standardizes on another bundler.
 - Keep environment-specific values in `.env` or the project's existing config pattern instead of hardcoding them into UI files.
+- **Subdirectory deployment base config (most common Vite 404 cause):**
+  - When deploying to a subdirectory like `/vite-test`, set `base: '/vite-test/'` in `vite.config.ts` — absolute path with leading AND trailing slash.
+  - **NEVER use `base: './'` or `base: ''`** for subdirectory deployments. When the browser accesses `https://domain.com/vite-test` (no trailing slash), relative paths resolve to `/` instead of `/vite-test/`, causing all JS/CSS assets to 404.
+  - After changing `base`, you MUST rebuild (`vite build`) before uploading — the built `dist/` files must reference assets with the subdirectory prefix.
+  - When uploading with `uploadFiles`, set `cloudPath` to the subdirectory without a leading slash (e.g. `vite-test`, not `/vite-test`).
 - Check route base paths, asset paths, and build output behavior before deployment.
 
 ## Routing and build defaults

mcp/src/tools/hosting.ts

@@ -60,7 +60,7 @@ function buildUploadFilesErrorMessage(error: unknown, localPath?: string): strin
       suggestions.push(`请先确认本地路径 \`${localPath}\` 存在且当前进程有读取权限。`);
     }
     suggestions.push("如果报错的是构建产物中的某个静态资源文件，请检查构建后的资源引用路径是否正确。");
-    suggestions.push("若站点部署到子路径，请确认 `publicPath`、`base`、`assetPrefix` 等配置没有把资源指向不存在的位置。");
+    suggestions.push("若站点部署到子路径，请确认 `base`/`publicPath`/`assetPrefix` 已设为与部署路径一致的绝对路径（如 `/vite-test/`），禁止使用 `./` 等相对路径。");
   }
 
   if (suggestions.length === 0) {
@@ -258,10 +258,10 @@ export function registerHostingTools(server: ExtendedMcpServer) {
     "uploadFiles",
     {
       title: "上传静态文件",
-      description: "上传文件到静态网站托管，仅用于 Web 站点部署，不用于云存储对象上传。部署前请先完成构建；如果站点会部署到子路径，请检查构建配置中的 publicPath、base、assetPrefix 等是否使用相对路径，避免静态资源加载失败。若需要上传 COS 云存储文件，请使用 manageStorage。对于本地评测、现有脚手架补全或仅需本地开发服务器验证的任务，通常不需要调用此工具，除非用户明确要求部署站点。",
+      description: "上传文件到静态网站托管，仅用于 Web 站点部署，不用于云存储对象上传。部署前请先完成构建。若需要上传 COS 云存储文件，请使用 manageStorage。对于本地评测、现有脚手架补全或仅需本地开发服务器验证的任务，通常不需要调用此工具，除非用户明确要求部署站点。\n\n⚠️ 子目录部署强制前置检查（部署到非根路径时必须逐项确认，任何一项未通过禁止调用此工具）：\n1. 已在构建配置中设置 base/publicPath/assetPrefix，值必须与部署目标子目录一致（如部署到 /vite-test 则设为 '/vite-test/'；必须使用绝对路径带前导和尾部斜杠，禁止使用 './' 等相对路径，因为访问 URL 不带尾部斜杠时会导致资源 404）\n2. 修改构建配置后已重新执行构建\n3. 已验证构建产物（dist/）中的资源引用路径已更新为子目录绝对路径（非 '/' 根路径）\n4. 上传整个构建产物目录（通常是 dist/），不能只上传 index.html\n\ncloudPath 格式：相对于托管根目录，不要带前导 '/'，例如 'vite-test' 而非 '/vite-test'。",
       inputSchema: {
         localPath: z.string().optional().describe("本地文件或文件夹路径，需要是绝对路径，例如 /tmp/files/data.txt。"),
-        cloudPath: z.string().optional().describe("静态托管云端文件或文件夹路径，例如 files/data.txt。若部署到子路径，请同时检查构建配置中的 publicPath、base、assetPrefix 等是否为相对路径。云存储对象路径请改用 manageStorage。"),
+        cloudPath: z.string().optional().describe("静态托管云端路径，相对于托管根目录，不要带前导 '/'，例如 'vite-test' 而非 '/vite-test'。若部署到子路径，请确保已将构建配置的 base/publicPath/assetPrefix 设为与部署路径一致的绝对路径（如 '/vite-test/'），禁止使用 './'。云存储对象路径请改用 manageStorage。"),
         files: z.array(z.object({
           localPath: z.string(),
           cloudPath: z.string()

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

@@ -35,8 +35,11 @@ describe("storage and hosting tool guidance", () => {
 
     expect(tools.uploadFiles.meta.description).toContain("仅用于 Web 站点部署");
     expect(tools.uploadFiles.meta.description).toContain("manageStorage");
-    expect(tools.uploadFiles.meta.description).toContain("通常不需要调用此工具");
+    expect(tools.uploadFiles.meta.description).toContain("子目录部署强制前置检查");
+    expect(tools.uploadFiles.meta.description).toContain("禁止使用 './'");
+    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.manageStorage.meta.description).toContain("仅用于 COS/Storage 对象");
     expect(tools.manageStorage.meta.description).toContain("不用于静态网站托管");
   });