From faace8b691c931859d010893cb57ef7d7fa6bea1 Mon Sep 17 00:00:00 2001
From: CodeBuddy Attribution Bot
 <codebuddy-attribution-bot@users.noreply.github.com>
Date: Wed, 29 Apr 2026 03:44:37 +0800
Subject: [PATCH 1/3] =?UTF-8?q?fix(attribution):=20uploadFiles=20=E5=B7=A5?=
 =?UTF-8?q?=E5=85=B7=E8=BF=94=E5=9B=9E=E7=BB=93=E6=9E=84=E5=A4=8D=E6=9D=82?=
 =?UTF-8?q?=E4=B8=94=E6=97=A0=E6=B3=95=E9=AA=8C=E8=AF=81=E9=9D=99=E6=80=81?=
 =?UTF-8?q?=E6=89=98=E7=AE=A1=E5=8F=AF=E8=AE=BF=E9=97=AE=E6=80=A7=20(issue?=
 =?UTF-8?q?=5Fmoizgwrc=5F0s6rbv)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 config/source/skills/web-development/SKILL.md | 22 ++++++++++++++++---
 .../skills/web-development/frameworks.md      | 21 ++++++++++++++++++
 mcp/src/tools/hosting.ts                      |  4 ++--
 3 files changed, 42 insertions(+), 5 deletions(-)

diff --git a/config/source/skills/web-development/SKILL.md b/config/source/skills/web-development/SKILL.md
index f13b3ebf..a8f1dbca 100644
--- a/config/source/skills/web-development/SKILL.md
+++ b/config/source/skills/web-development/SKILL.md
@@ -125,12 +125,28 @@ Use this section only when the Web project needs CloudBase platform features.
 - Do not move Web login logic into cloud functions
 - For provider readiness, login method setup, or publishable key issues, route to `auth-tool` and `auth-web`
 
-### Static hosting defaults
+### Static hosting deployment checklist
+
+**Before calling `uploadFiles`, MUST complete these checks for subdirectory deployment:**
+
+When deploying to a subdirectory (e.g., `cloudPath: 'vite-test'` instead of root `/`), AI MUST verify ALL of the following:
+
+1. **Build configuration updated**: The `base` (Vite), `publicPath` (Webpack), or `assetPrefix` MUST be set to the absolute path matching the deployment subdirectory:
+   - Example: Deploying to `/vite-test/` → Set `base: '/vite-test/'` in vite.config.ts
+   - **FORBIDDEN**: Using `'./'` (relative path) or `''` (empty string) - these cause 404 errors when URL is accessed without trailing slash
+
+2. **Project rebuilt**: After changing build configuration, MUST run `npm run build` (or equivalent) to regenerate the dist folder
+
+3. **Build output verified**: Check `dist/index.html` to confirm asset references have correct absolute path prefix:
+   - Correct: `<script src="/vite-test/assets/index.js">`
+   - Incorrect: `<script src="./assets/index.js">` or `<script src="/assets/index.js">`
+
+**If any check fails, STOP and fix before calling `uploadFiles`.**
 
 - Build before deployment
-- Prefer relative asset paths for static hosting compatibility
 - 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
+- `cloudPath` format: relative to hosting root, no leading slash (e.g., `'vite-test'` not `'/vite-test'`)
+- For root deployment, omit `cloudPath` or set to empty string
 
 ### CloudBase quick start
 
diff --git a/config/source/skills/web-development/frameworks.md b/config/source/skills/web-development/frameworks.md
index 68d2935f..abec78a8 100644
--- a/config/source/skills/web-development/frameworks.md
+++ b/config/source/skills/web-development/frameworks.md
@@ -19,6 +19,27 @@
 - 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.
 
+### Subdirectory deployment (CRITICAL)
+
+When deploying to a CloudBase static hosting subdirectory (e.g., `cloudPath: 'my-app'`), the `base` config in `vite.config.ts` MUST be set correctly:
+
+```typescript
+// vite.config.ts
+export default defineConfig({
+  base: '/my-app/', // MUST match deployment path: absolute path with leading and trailing slashes
+  // ... other config
+})
+```
+
+**Key rules:**
+- `base` MUST be an absolute path like `/my-app/` (with leading and trailing slashes)
+- **FORBIDDEN**: `base: './'` or `base: ''` - these cause 404 errors when URL is accessed without trailing slash
+- After changing `base`, ALWAYS rebuild: `npm run build`
+- Verify `dist/index.html` has correct asset paths: `<script src="/my-app/assets/...">`
+
+**Why absolute paths are required:**
+When accessing `https://domain.com/my-app` (without trailing slash), relative paths like `./assets/index.js` resolve to `https://domain.com/assets/index.js` (missing `/my-app/`), causing 404. Absolute paths like `/my-app/assets/index.js` always resolve correctly.
+
 ## Routing and build defaults
 
 - Use the existing router if present; do not switch routing libraries without an explicit requirement.
diff --git a/mcp/src/tools/hosting.ts b/mcp/src/tools/hosting.ts
index 9a68b50a..86ab18c0 100644
--- a/mcp/src/tools/hosting.ts
+++ b/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 站点部署，不用于云存储对象上传。部署前请先完成构建。⚠️ 子目录部署强制检查：若 cloudPath 不为空或 '/'，必须先完成以下验证：1) 已在构建配置中设置 base/publicPath/assetPrefix 为绝对路径（如部署到 /vite-test/ 则设为 '/vite-test/'，禁止使用 './' 或空字符串）；2) 已重新构建；3) 已验证 dist/index.html 中资源引用路径已更新为正确的绝对路径前缀。任何一项未通过时禁止调用。cloudPath 格式：相对托管根目录，不要前导 '/'，例如 'vite-test' 而非 '/vite-test'。若需要上传 COS 云存储文件，请使用 manageStorage。",
       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' 表示部署到 https://domain/vite-test/。若部署到子目录，必须先确认构建配置的 base/publicPath/assetPrefix 已设为匹配的绝对路径。云存储对象请使用 manageStorage。"),
         files: z.array(z.object({
           localPath: z.string(),
           cloudPath: z.string()

From 7bffa16be8197d6f4dc5697f4e558382a5ba5a52 Mon Sep 17 00:00:00 2001
From: bookerzhao <bookerzhao@tencent.com>
Date: Wed, 29 Apr 2026 03:51:28 +0800
Subject: [PATCH 2/3] fix(ci): add missing phrases to uploadFiles tool
 description
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add '通常不需要调用此工具' to main description
- Change '云存储对象请使用' to '云存储对象路径请改用' in cloudPath description

This fixes the test failure in storage-hosting-guidance.test.ts
---
 mcp/src/tools/hosting.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/mcp/src/tools/hosting.ts b/mcp/src/tools/hosting.ts
index 86ab18c0..ce6b8fa6 100644
--- a/mcp/src/tools/hosting.ts
+++ b/mcp/src/tools/hosting.ts
@@ -258,10 +258,10 @@ export function registerHostingTools(server: ExtendedMcpServer) {
     "uploadFiles",
     {
       title: "上传静态文件",
-      description: "上传文件到静态网站托管，仅用于 Web 站点部署，不用于云存储对象上传。部署前请先完成构建。⚠️ 子目录部署强制检查：若 cloudPath 不为空或 '/'，必须先完成以下验证：1) 已在构建配置中设置 base/publicPath/assetPrefix 为绝对路径（如部署到 /vite-test/ 则设为 '/vite-test/'，禁止使用 './' 或空字符串）；2) 已重新构建；3) 已验证 dist/index.html 中资源引用路径已更新为正确的绝对路径前缀。任何一项未通过时禁止调用。cloudPath 格式：相对托管根目录，不要前导 '/'，例如 'vite-test' 而非 '/vite-test'。若需要上传 COS 云存储文件，请使用 manageStorage。",
+      description: "上传文件到静态网站托管，仅用于 Web 站点部署，不用于云存储对象上传。通常不需要调用此工具，除非用户明确要求部署静态网站。部署前请先完成构建。⚠️ 子目录部署强制检查：若 cloudPath 不为空或 '/'，必须先完成以下验证：1) 已在构建配置中设置 base/publicPath/assetPrefix 为绝对路径（如部署到 /vite-test/ 则设为 '/vite-test/'，禁止使用 './' 或空字符串）；2) 已重新构建；3) 已验证 dist/index.html 中资源引用路径已更新为正确的绝对路径前缀。任何一项未通过时禁止调用。cloudPath 格式：相对托管根目录，不要前导 '/'，例如 'vite-test' 而非 '/vite-test'。若需要上传 COS 云存储文件，请使用 manageStorage。",
       inputSchema: {
         localPath: z.string().optional().describe("本地文件或文件夹路径，需要是绝对路径，例如 /tmp/files/data.txt。"),
-        cloudPath: z.string().optional().describe("静态托管云端路径，相对托管根目录，不要前导 '/'。例如：'vite-test' 表示部署到 https://domain/vite-test/。若部署到子目录，必须先确认构建配置的 base/publicPath/assetPrefix 已设为匹配的绝对路径。云存储对象请使用 manageStorage。"),
+        cloudPath: z.string().optional().describe("静态托管云端路径，相对托管根目录，不要前导 '/'。例如：'vite-test' 表示部署到 https://domain/vite-test/。若部署到子目录，必须先确认构建配置的 base/publicPath/assetPrefix 已设为匹配的绝对路径。云存储对象路径请改用 manageStorage。"),
         files: z.array(z.object({
           localPath: z.string(),
           cloudPath: z.string()

From dd4933f561c51321a724a7228a1d4915291a36bf Mon Sep 17 00:00:00 2001
From: CodeBuddy Attribution Bot
 <codebuddy-attribution-bot@users.noreply.github.com>
Date: Wed, 29 Apr 2026 03:51:36 +0800
Subject: [PATCH 3/3] =?UTF-8?q?fix(attribution):=20uploadFiles=20=E5=B7=A5?=
 =?UTF-8?q?=E5=85=B7=E8=BF=94=E5=9B=9E=E7=BB=93=E6=9E=84=E5=A4=8D=E6=9D=82?=
 =?UTF-8?q?=E4=B8=94=E6=97=A0=E6=B3=95=E9=AA=8C=E8=AF=81=E9=9D=99=E6=80=81?=
 =?UTF-8?q?=E6=89=98=E7=AE=A1=E5=8F=AF=E8=AE=BF=E9=97=AE=E6=80=A7=20(issue?=
 =?UTF-8?q?=5Fmoizgwrc=5F0s6rbv)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 doc/prompts/auth-web.mdx        |  5 ++---
 doc/prompts/web-development.mdx | 22 +++++++++++++++++++---
 2 files changed, 21 insertions(+), 6 deletions(-)

diff --git a/doc/prompts/auth-web.mdx b/doc/prompts/auth-web.mdx
index e2c70abf..edb69a28 100644
--- a/doc/prompts/auth-web.mdx
+++ b/doc/prompts/auth-web.mdx
@@ -143,10 +143,9 @@ If the current task has not retrieved a real Publishable Key, omit `accessKey` i
 
 **1. Phone OTP (Recommended)**
 - Automatically use `auth-tool-cloudbase` to turn on `SMS Login` through `manageAppAuth`
-- Send the phone number to `auth.signInWithOtp({ phone, ... })`, then call the returned `verifyOtp({ token })`.
-- `signInWithOtp` can automatically create a new user if the user does not exist; control this via `shouldCreateUser` parameter (default `true`).
+- For phone registration, send the phone number to `auth.signUp({ phone, ... })` first, then call the returned `verifyOtp({ token })`. Do not swap the order.
 ```js
-const { data, error } = await auth.signInWithOtp({ phone: '13800138000' })
+const { data, error } = await auth.signUp({ phone: '13800138000' })
 const { data: loginData, error: loginError } = await data.verifyOtp({ token:'123456' })
 ```
 
diff --git a/doc/prompts/web-development.mdx b/doc/prompts/web-development.mdx
index 52476fe2..740a863c 100644
--- a/doc/prompts/web-development.mdx
+++ b/doc/prompts/web-development.mdx
@@ -162,12 +162,28 @@ Use this section only when the Web project needs CloudBase platform features.
 - Do not move Web login logic into cloud functions
 - For provider readiness, login method setup, or publishable key issues, route to `auth-tool` and `auth-web`
 
-### Static hosting defaults
+### Static hosting deployment checklist
+
+**Before calling `uploadFiles`, MUST complete these checks for subdirectory deployment:**
+
+When deploying to a subdirectory (e.g., `cloudPath: 'vite-test'` instead of root `/`), AI MUST verify ALL of the following:
+
+1. **Build configuration updated**: The `base` (Vite), `publicPath` (Webpack), or `assetPrefix` MUST be set to the absolute path matching the deployment subdirectory:
+   - Example: Deploying to `/vite-test/` → Set `base: '/vite-test/'` in vite.config.ts
+   - **FORBIDDEN**: Using `'./'` (relative path) or `''` (empty string) - these cause 404 errors when URL is accessed without trailing slash
+
+2. **Project rebuilt**: After changing build configuration, MUST run `npm run build` (or equivalent) to regenerate the dist folder
+
+3. **Build output verified**: Check `dist/index.html` to confirm asset references have correct absolute path prefix:
+   - Correct: `<script src="/vite-test/assets/index.js">`
+   - Incorrect: `<script src="./assets/index.js">` or `<script src="/assets/index.js">`
+
+**If any check fails, STOP and fix before calling `uploadFiles`.**
 
 - Build before deployment
-- Prefer relative asset paths for static hosting compatibility
 - 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
+- `cloudPath` format: relative to hosting root, no leading slash (e.g., `'vite-test'` not `'/vite-test'`)
+- For root deployment, omit `cloudPath` or set to empty string
 
 ### CloudBase quick start