fix: uploadFiles MCP 工具 cloudPath 格式不清且缺少部署验证能力，导致静态托管部署后 404

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

@@ -149,7 +149,29 @@ Example structure for operation recording:
    - Combine with static hosting file paths to construct final access addresses
    - **Important**: If access address is a directory, it must end with `/`
 
-3. **Cloud Storage Public URL**:
+3. **Static Hosting Deployment (`uploadFiles`)**:
+   - Use `uploadFiles` tool to deploy Web sites to static hosting (not for cloud storage uploads)
+   - **`cloudPath` format**: Relative to hosting root, NO leading `/`
+     - Correct: `cloudPath: 'vite-test'` (deploys to `https://domain/vite-test/`)
+     - Wrong: `cloudPath: '/vite-test'` or `cloudPath: './vite-test'`
+   - **Subdirectory deployment requirements** (CRITICAL to avoid 404):
+     - Must set `base`/`publicPath`/`assetPrefix` in build config to match deployment path
+     - For Vite: `base: '/vite-test/'` (absolute path with leading AND trailing slashes)
+     - **Forbidden**: `base: './'` (causes 404 when URL lacks trailing slash)
+     - Must rebuild after changing config
+     - Must verify built `index.html` references assets with correct paths (not absolute root `/`)
+   - **Pre-deployment checklist** (must complete before calling `uploadFiles`):
+     - [ ] Build config (`base`/`publicPath`/`assetPrefix`) matches deployment path
+     - [ ] Project has been rebuilt after config change
+     - [ ] Built assets reference correct paths (not root `/`)
+     - [ ] `cloudPath` has no leading `/`
+   - **Post-upload verification** (mandatory):
+     - Call `findFiles` with prefix matching `cloudPath`
+     - Confirm `index.html` AND emitted JS/CSS/assets all exist under target prefix
+     - Do NOT treat deployment as complete if only `index.html` exists
+   - **Common 404 cause**: Using `./` relative paths in build config → when accessing `https://domain/vite-test` (no trailing slash), relative paths resolve incorrectly
+
+4. **Cloud Storage Public URL**:
    - **CRITICAL**: `manageStorage(action=upload)` and `queryStorage(action=url)` return `temporaryUrl` which is a temporary signed URL that expires (default 1 hour). Do NOT use this as a permanent public URL.
    - To get the permanent public access URL for a cloud storage object:
      1. Call `envQuery(action=info)` to get environment details

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

@@ -126,6 +126,9 @@ Use this skill for Web engineering work such as:
    - Use CloudBase Web SDK and static hosting guidance only when the project actually needs CloudBase platform features.
    - Reuse `auth-tool` and `auth-web` for login or provider readiness instead of re-describing those flows here.
 
+**⚠️ CRITICAL: Subdirectory deployment (≠ root deployment)**
+When deploying to a subdirectory (e.g., `/vite-test`), you MUST follow the mandatory checklist in `references/deployment-checklist.md` BEFORE calling `uploadFiles`. Skipping any step causes 404 errors. Read that file first if the task involves subdirectory deployment.
+
 ## Core workflow
 
 ### 1. Choose the right engineering path
@@ -169,10 +172,22 @@ 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
+- For root deployment, keep root-compatible asset paths; for subdirectory deployment, set `base` / `publicPath` / `assetPrefix` to the exact absolute deploy path and do not use `./`.
 - 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 (⚠️ MANDATORY checklist)
+
+**⚠️ CRITICAL: You MUST follow the complete checklist in `references/deployment-checklist.md` before calling `uploadFiles` for subdirectory deployment.**
+
+Quick reference:
+- `cloudPath` format: no leading `/` (e.g., `'vite-test'`, NOT `'/vite-test'`)
+- Build config: `base: '/vite-test/'` (absolute path, leading AND trailing slashes)
+- Upload scope: entire `dist/` directory, not only `index.html`
+- Post-upload: call `findFiles` to verify all files exist
+
+**READ THIS FILE FIRST**: `references/deployment-checklist.md` (contains mandatory step-by-step workflow with confirmation requirements)
+
 ### CloudBase quick start
 
 ```js

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

@@ -19,6 +19,32 @@
 - Keep environment-specific values in `.env` or the project's existing config pattern instead of hardcoding them into UI files.
 - Check route base paths, asset paths, and build output behavior before deployment.
 
+### Vite base configuration for subdirectory deployment
+
+When deploying to a subdirectory (e.g., `https://example.com/vite-test/`), the Vite `base` configuration is critical:
+
+1. **Required format**: Set `base` to an absolute path with leading and trailing slashes, matching the deployment path:
+   ```js
+   // vite.config.ts
+   export default defineConfig({
+     base: '/vite-test/',  // Correct: absolute path with leading and trailing slashes
+   })
+   ```
+
+2. **Forbidden patterns** - These will cause 404 errors when URL lacks trailing slash:
+   ```js
+   base: './',      // WRONG: relative path breaks when URL is /vite-test (no trailing slash)
+   base: '',        // WRONG: empty base means root deployment
+   base: 'vite-test', // WRONG: missing leading and trailing slashes
+   ```
+
+3. **Why this matters**: When a user accesses `https://example.com/vite-test` (without trailing slash), relative paths like `./assets/index.js` resolve to `https://example.com/assets/index.js` instead of `https://example.com/vite-test/assets/index.js`, causing 404 errors.
+
+4. **Pre-deployment checklist**:
+   - [ ] `vite.config.ts` has `base: '/your-subdirectory/'` set correctly
+   - [ ] Build command has been re-run after config change
+   - [ ] Built `dist/index.html` references assets with correct paths (e.g., `/vite-test/assets/...`)
+
 ## Routing and build defaults
 
 - Use the existing router if present; do not switch routing libraries without an explicit requirement.

config/source/skills/web-development/references/deployment-checklist.md

@@ -0,0 +1,126 @@
+# ⚠️ MANDATORY: Subdirectory Deployment Checklist
+
+**You MUST complete ALL steps below before calling `uploadFiles` for subdirectory deployment. Skipping any step will cause 404 errors.**
+
+---
+
+## Pre-Deployment (MUST complete in order)
+
+### Step 1: Read and confirm build configuration
+**Action**: Read `vite.config.ts` (or `next.config.js`, `vue.config.js`, `webpack.config.js`)
+
+**Check**:
+- [ ] `base` (Vite) / `publicPath` (Webpack/Vue) / `assetPrefix` (Next.js) is set
+- [ ] Value is `'/your-subdirectory/'` format (absolute path, leading AND trailing slashes)
+- [ ] NOT `./`, NOT `''`, NOT `'your-subdirectory'` (missing slashes)
+
+**Example (Vite)**:
+```ts
+// vite.config.ts
+export default defineConfig({
+  base: '/vite-test/',  // ✓ Correct
+  // base: './',         // ✗ WRONG - causes 404
+  // base: '',           // ✗ WRONG - deploys to root
+  // base: 'vite-test', // ✗ WRONG - missing slashes
+})
+```
+
+**YOU MUST OUTPUT**: "Step 1 completed: read vite.config.ts, base is set to '/vite-test/'"
+
+---
+
+### Step 2: Rebuild after config change
+**Action**: Run build command (e.g., `npm run build`)
+
+**Check**:
+- [ ] Build command was run AFTER changing config
+- [ ] Build completed successfully (zero errors)
+- [ ] `dist/` (or build output dir) contains updated files
+
+**YOU MUST OUTPUT**: "Step 2 completed: rebuilt project with `npm run build`"
+
+---
+
+### Step 3: Verify build output paths
+**Action**: Read `dist/index.html` (or equivalent build output)
+
+**Check**:
+- [ ] Resource references use `/your-subdirectory/...` format
+- [ ] Example: `<script src="/vite-test/assets/index.js">` ✓
+- [ ] NOT `<script src="/assets/index.js">` (missing prefix)
+- [ ] NOT `<script src="./assets/index.js">` (relative path)
+
+**YOU MUST OUTPUT**: "Step 3 completed: verified dist/index.html references paths correctly (e.g., /vite-test/assets/...)"
+
+---
+
+### Step 4: Confirm upload scope
+**Action**: Prepare `uploadFiles` call
+
+**Check**:
+- [ ] `localPath` points to ENTIRE build directory (e.g., `/path/to/dist`)
+- [ ] NOT `localPath: '/path/to/dist/index.html'` (only uploads one file)
+- [ ] `cloudPath` has NO leading `/` (e.g., `'vite-test'`, NOT `'/vite-test'`)
+- [ ] `cloudPath` matches the `base` config (e.g., base `'/vite-test/'` → cloudPath `'vite-test'`)
+
+**YOU MUST OUTPUT**: "Step 4 completed: localPath='/path/to/dist', cloudPath='vite-test' (no leading /)"
+
+---
+
+### Step 5: Output pre-deployment confirmation
+**Action**: Before calling `uploadFiles`, output ALL of the above confirmations in your response.
+
+**Template**:
+```
+Pre-deployment checklist (subdirectory deployment):
+✓ Step 1: Read vite.config.ts, base is set to '/vite-test/'
+✓ Step 2: Rebuilt project with `npm run build`
+✓ Step 3: Verified dist/index.html references paths correctly
+✓ Step 4: localPath='/path/to/dist', cloudPath='vite-test' (no leading /)
+→ Now calling uploadFiles...
+```
+
+**DO NOT CALL `uploadFiles` without this confirmation output.**
+
+---
+
+## Post-Upload Verification (MUST complete)
+
+### Step 6: Verify uploaded files
+**Action**: Call `findFiles` with prefix matching your `cloudPath`
+
+**Check**:
+- [ ] `findFiles({ prefix: 'vite-test/' })` returns results
+- [ ] Results include `index.html`
+- [ ] Results include JS/CSS/assets (not just index.html)
+- [ ] If only `index.html` exists → upload is INCOMPLETE, re-check `localPath`
+
+**YOU MUST OUTPUT**: "Step 6 completed: verified uploaded files exist via findFiles"
+
+---
+
+## Common 404 Causes
+
+1. **`base: './'` in Vite**: When URL lacks trailing slash (e.g., `/vite-test`), relative paths resolve incorrectly
+2. **Missing rebuild**: Changed `base` but didn't re-run build → old paths in dist/
+3. **Only uploaded index.html**: Forgot to set `localPath` to dist/ directory → JS/CSS missing
+4. **`cloudPath` with leading `/`**: Causes incorrect path mapping in hosting
+5. **URL without trailing slash**: Always access with trailing slash, or configure server redirects
+
+---
+
+## Framework-Specific Notes
+
+### Vite
+- Config: `base` in `vite.config.ts`
+- See `../frameworks.md` for detailed examples
+
+### Next.js
+- Config: `assetPrefix` in `next.config.js`
+- Also set `basePath` if using App Router
+
+### Vue CLI
+- Config: `publicPath` in `vue.config.js`
+
+### Webpack
+- Config: `output.publicPath` in `webpack.config.js`