fix: uploadFiles 工具 cloudPath 参数语义不清，导致静态托管部署路径错误

config/source/guideline/cloudbase/SKILL.md

@@ -291,6 +291,7 @@ Prefer long-term memory when available: write the scenarios and working rules th
 - 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`
 - Remind users that CDN has a few minutes of cache after deployment
+- **Subdirectory deployment**: when deploying to a subdirectory (e.g., `/vite-test`), `base`/`publicPath`/`assetPrefix` must be set to the absolute subdirectory path (e.g., `'/vite-test/'`), NOT `'./'` or empty. After changing the build config, rebuild and verify asset paths in the output before calling `uploadFiles`. The `cloudPath` parameter must not start with `/` (use `'vite-test'`, not `'/vite-test'`).
 
 **Backend Deployment:**
 - **Cloud Functions**: Refer to the `cloud-functions` skill - Runtime cannot be changed after creation, must select correct runtime initially

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

@@ -128,10 +128,24 @@ 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
+- Deploy the entire `dist/` directory contents, not just `index.html`
 - 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
 
+### Subdirectory deployment checklist
+
+When deploying to a subdirectory (e.g., `/vite-test`), the following must be verified **before calling `uploadFiles`**. If any item fails, stop and fix it first:
+
+1. **Build config `base`/`publicPath`/`assetPrefix` must be set to the absolute subdirectory path** (e.g., deploy target `/vite-test` → Vite `base: '/vite-test/'`, Webpack `publicPath: '/vite-test/'`). **Forbidden**: `'./'`, empty string, or `'/'` — these cause 404 for assets when the access URL lacks a trailing slash.
+2. **Rebuild after changing build config** — modifying `base`/`publicPath` without rebuilding leaves stale references in `dist/`.
+3. **Verify build output** — check that asset references in `dist/index.html` use the subdirectory prefix (e.g., `src="/vite-test/assets/..."`), not root-relative paths (`src="/assets/..."`).
+
+`uploadFiles` `cloudPath` format: relative to hosting root, **no leading `/`**. Example: `'vite-test'` (not `'/vite-test'`). The `localPath` should point to the `dist/` directory.
+
+### Root deployment
+
+When deploying to the site root (`/`), `cloudPath` can be omitted or left empty. For Vite projects, `base: '/'` (the default) works correctly.
+
 ### CloudBase quick start
 
 ```js

doc/mcp-tools.md

@@ -24,7 +24,7 @@
 <tr><td><code>modifyDataModel</code></td><td>基于Mermaid classDiagram创建数据模型。为保持兼容性，工具名仍为 modifyDataModel；当前仅支持创建新模型，不支持更新现有模型结构。内置异步任务监控，自动轮询直至完成或超时。</td></tr>
 <tr><td><code>queryFunctions</code></td><td>函数域统一只读入口。通过更自解释的 action 查询函数列表、函数详情、日志、层、触发器和代码下载地址。</td></tr>
 <tr><td><code>manageFunctions</code></td><td>函数域统一写入口。通过 action 管理函数创建、代码更新、配置更新、调用函数、触发器和层绑定。危险操作需要显式 confirm=true。</td></tr>
-<tr><td><code>uploadFiles</code></td><td>上传文件到静态网站托管，仅用于 Web 站点部署，不用于云存储对象上传。部署前请先完成构建；如果站点会部署到子路径，请检查构建配置中的 publicPath、base、assetPrefix 等是否使用相对路径，避免静态资源加载失败。若需要上传 COS 云存储文件，请使用 manageStorage。对于本地评测、现有脚手架补全或仅需本地开发服务器验证的任务，通常不需要调用此工具，除非用户明确要求部署站点。</td></tr>
+<tr><td><code>uploadFiles</code></td><td>上传文件到静态网站托管，仅用于 Web 站点部署，不用于云存储对象上传。部署前请先完成构建。若需要上传 COS 云存储文件，请使用 manageStorage。对于本地评测、现有脚手架补全或仅需本地开发服务器验证的任务，通常不需要调用此工具，除非用户明确要求部署站点。⚠️ 子目录部署必检项（部署到非根路径时，调用 uploadFiles 前必须逐项确认）：1. 构建配置中的 base/publicPath/assetPrefix 必须设为与部署目标一致的绝对路径（如部署到 /vite-test，则 base 设为 '/vite-test/'，带前导和尾部斜杠）。禁止使用 './' 或空字符串，否则子目录部署后静态资源会因路径解析错误而 404。2. 修改构建配置后必须重新 build。3. 必须验证构建产物中的资源引用路径已更新为非绝对根路径 '/'。任何一项未通过，禁止调用 uploadFiles。</td></tr>
 <tr><td><code>deleteFiles</code></td><td>删除静态网站托管的文件或文件夹</td></tr>
 <tr><td><code>findFiles</code></td><td>搜索静态网站托管的文件</td></tr>
 <tr><td><code>domainManagement</code></td><td>统一的域名管理工具，支持绑定、解绑、查询和修改域名配置</td></tr>
@@ -418,15 +418,21 @@ classDiagram
 ---
 
 ### `uploadFiles`
-上传文件到静态网站托管，仅用于 Web 站点部署，不用于云存储对象上传。部署前请先完成构建；如果站点会部署到子路径，请检查构建配置中的 publicPath、base、assetPrefix 等是否使用相对路径，避免静态资源加载失败。若需要上传 COS 云存储文件，请使用 manageStorage。对于本地评测、现有脚手架补全或仅需本地开发服务器验证的任务，通常不需要调用此工具，除非用户明确要求部署站点。
+上传文件到静态网站托管，仅用于 Web 站点部署，不用于云存储对象上传。部署前请先完成构建。若需要上传 COS 云存储文件，请使用 manageStorage。对于本地评测、现有脚手架补全或仅需本地开发服务器验证的任务，通常不需要调用此工具，除非用户明确要求部署站点。
+
+⚠️ 子目录部署必检项（部署到非根路径时，调用 uploadFiles 前必须逐项确认）：
+1. 构建配置中的 base/publicPath/assetPrefix 必须设为与部署目标一致的绝对路径（如部署到 /vite-test，则 base 设为 '/vite-test/'，带前导和尾部斜杠）。禁止使用 './' 或空字符串，否则子目录部署后静态资源会因路径解析错误而 404。
+2. 修改构建配置后必须重新 build。
+3. 必须验证构建产物中的资源引用路径已更新为非绝对根路径 '/'。
+任何一项未通过，禁止调用 uploadFiles。
 
 #### 参数
 
 <table>
 <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/ 子目录，而非 '/vite-test'。若上传整个 dist 目录到子目录，cloudPath 填子目录名（如 'vite-test'），localPath 填 dist 绝对路径。云存储对象路径请改用 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>

doc/prompts/web-development.mdx

@@ -164,7 +164,7 @@ 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
+- Deploy the entire `dist/` directory contents, not just `index.html`
 - 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
 

mcp/src/tools/hosting.ts

@@ -258,10 +258,10 @@ export function registerHostingTools(server: ExtendedMcpServer) {
     "uploadFiles",
     {
       title: "上传静态文件",
-      description: "上传文件到静态网站托管，仅用于 Web 站点部署，不用于云存储对象上传。部署前请先完成构建；如果站点会部署到子路径，请检查构建配置中的 publicPath、base、assetPrefix 等是否使用相对路径，避免静态资源加载失败。若需要上传 COS 云存储文件，请使用 manageStorage。对于本地评测、现有脚手架补全或仅需本地开发服务器验证的任务，通常不需要调用此工具，除非用户明确要求部署站点。",
+      description: "上传文件到静态网站托管，仅用于 Web 站点部署，不用于云存储对象上传。部署前请先完成构建。若需要上传 COS 云存储文件，请使用 manageStorage。对于本地评测、现有脚手架补全或仅需本地开发服务器验证的任务，通常不需要调用此工具，除非用户明确要求部署站点。\n\n⚠️ 子目录部署必检项（部署到非根路径时，调用 uploadFiles 前必须逐项确认）：\n1. 构建配置中的 base/publicPath/assetPrefix 必须设为与部署目标一致的绝对路径（如部署到 /vite-test，则 base 设为 '/vite-test/'，带前导和尾部斜杠）。禁止使用 './' 或空字符串，否则子目录部署后静态资源会因路径解析错误而 404。\n2. 修改构建配置后必须重新 build。\n3. 必须验证构建产物中的资源引用路径已更新为非绝对根路径 '/'。\n任何一项未通过，禁止调用 uploadFiles。",
       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/ 子目录，而非 '/vite-test'。若上传整个 dist 目录到子目录，cloudPath 填子目录名（如 'vite-test'），localPath 填 dist 绝对路径。云存储对象路径请改用 manageStorage。"),
         files: z.array(z.object({
           localPath: z.string(),
           cloudPath: z.string()