Sibling skills (local only)

Sibling CloudBase skills ship beside this skill. Use local relative paths such as ../auth-tool-cloudbase/SKILL.md.

If a referenced sibling skill file is missing from this environment, ask the user to install the full CloudBase plugin (or the missing skill). Do not HTTP-fetch remote skill or protocol markdown into the agent context.

Cross-cutting protocols (required before code changes or deployments):
- Change Safety Protocol: ../cloudbase-platform/references/protocols/change-safety-protocol.md
- Deployment Gate: ../cloudbase-platform/references/protocols/deployment-gate.md

Web Development

Activation Contract

Use this first when

• The request is to implement, integrate, debug, build, deploy, or validate a Web frontend or static site.
• The design direction is already decided, or the user is asking for engineering execution rather than visual exploration.
• The work involves React, Vue, Vite, routing, browser-based verification, or CloudBase Web integration.

Read before writing code if

• The task includes project structure, framework conventions, build config, deployment, routing, or frontend test and validation flows.
• The request includes UI implementation but the visual direction is already fixed; otherwise read ui-design first.
• ⚠️ Any task involving interface styling, layout, color scheme, or font selection — before writing the first line of CSS/Tailwind, you MUST load the ui-design skill and output a Design Specification. Skipping this step causes frontend styling to degrade to generic AI template defaults. The ui-design skill must be loaded before any visual implementation begins, not retroactively after the user complains about the appearance.

Then also read

• General React / Vue / Vite guidance -> frameworks.md
• Browser flow checks or page validation -> browser-testing.md
• Login flow -> ../auth-tool-cloudbase/SKILL.md, then ../auth-web-cloudbase/SKILL.md
• Official Account JSAPI Pay, Native QR-code Pay, or WeChat OAuth on CloudBase -> ../cloudbase-wechat-integration/SKILL.md (official docs: https://docs.cloudbase.net/integration/introduce.md)
• CloudBase database work -> matching database skill

Do NOT use for

• Visual direction setting, prototype-first design work, or pure aesthetic exploration.
• Mini programs, native Apps, or backend-only services.
• WeChat payment or Official Account OAuth contract details; use cloudbase-wechat-integration after identifying the Web surface.

Common mistakes / gotchas

• Starting implementation before clarifying whether the task is design or engineering execution.
• Mixing framework setup, deployment, and CloudBase integration concerns into one vague change.
• Treating cloud functions as the default solution for Web authentication.
• Skipping browser-level validation after a UI or routing change.
• History mode SPA with CloudBase static hosting: deploying a single-page app using History mode (React Router / Vue Router) without configuring the static hosting "404 error document" to index.html. This causes NoSuchKey / 404 errors when users refresh or directly visit any sub-route.
• In an existing application, detouring into UI redesign or broad repo sweeps before patching the current handlers and services.

Engineering constitution (non-negotiable)

These rules override convenience. Treat them as a gate before saying "done".

1. TypeScript — do not silence the type system

• Do NOT use any to bypass type errors. Not : any, not as any, not @ts-ignore, not @ts-nocheck, not @ts-expect-error without a written justification. any propagates silently and defeats the only compile-time safety net this project has.
• When a type error appears, fix the root cause:
• Missing / wrong library types → install @types/..., or narrow the import, or write a precise interface / type for the shape you actually use.
• Shape is genuinely unknown at the boundary (JSON from an API, postMessage payload, window.* injection) → type it as unknown and narrow with a type guard (typeof, in, a discriminator field, or zod / equivalent).
• Third-party type is wrong → augment via declare module in a local .d.ts, not any.
• Truly dynamic case (e.g. generic event bus) → use a generic <T> with a constraint, not any.
• unknown + narrowing is the acceptable escape hatch. any is not.
• If you genuinely cannot avoid any for a specific line (extremely rare), leave a one-line comment with why and what would remove it, so reviewers can audit.
• The same spirit applies to ESLint: do not sprinkle // eslint-disable to mute the real signal. Fix the rule violation, or discuss before disabling.

2. Self-verify before claiming done

Before making any non-trivial code or configuration change, you must first follow the Change Safety Protocol in cloudbase-platform/references/protocols/change-safety-protocol.md (declare impact → user confirmation → post-edit verification).
Before any static hosting publish or custom domain work, complete the checks in cloudbase-platform/references/protocols/deployment-gate.md.

Saying "I've implemented it" / "fixed it" / "it should work" without evidence is not acceptable. Before declaring completion, you must actually run the checks and report the result.

Static / build layer (always, when applicable):

• tsc --noEmit (or vue-tsc --noEmit) passes cleanly — zero errors, zero suppressed diagnostics you added.
• eslint / project linter passes on changed files.
• The project's build command (npm run build / pnpm build / vite build) completes without new warnings that you introduced.
• The project's unit tests pass if they exist and cover the touched area.

Runtime / browser layer (whenever the change affects rendering, routing, forms, auth, or async flows):

• Use the agent-browser tool to actually open the page and reproduce the user-visible flow. Follow browser-testing.md for the concrete workflow.
• Confirm: the target route loads, the interaction you claim to have fixed behaves the way you claim, no new console errors are introduced, and no regression in the adjacent routes you touched.
• Record what you checked (route, action, expected result, actual result).

Only after both layers pass may you say the task is done. If either layer cannot be executed locally (e.g. blocked by credentials, missing backend, paid API), say so explicitly and list exactly which step is still unverified — do not gloss over it.

3. Do not paper over failures

• Do not wrap broken logic in try { ... } catch {} to make the error go away.
• Do not delete or skip a failing test to make CI green — fix it, or explain why the test is actually wrong and change the test with justification.
• Do not mark a task complete because "the code compiles". Compilation is the bare minimum, not the goal.

When to use this skill

Use this skill for Web engineering work such as:

• Implementing React or Vue pages and components
• Setting up or maintaining Vite-based frontend projects
• Handling routing, data loading, forms, and build configuration
• Running browser-based validation and smoke checks
• Integrating CloudBase Web SDK and static hosting when the project needs CloudBase capabilities

Do NOT use for:
- UI direction or visual system design only; use ui-design
- Mini program development; use miniprogram-development
- Backend service implementation; use cloudrun-development or cloud-functions

How to use this skill (for a coding agent)

1. Clarify the execution surface
   - Confirm whether the task is framework setup, page implementation, debugging, deployment, validation, or CloudBase integration.
   - Keep the work scoped to the actual Web app surface instead of spreading into unrelated backend changes.
   - If the workspace is an existing application with TODOs, treat it as a targeted repair task, not a greenfield build.

2. Follow framework and build conventions
   - Prefer the existing project stack if one already exists.
   - For new work, treat Vite as the default bundler unless the repo or user constraints say otherwise.
   - Put reusable app code under src and build output under dist unless the repo already uses a different convention.
   - In an existing application with fixed structure, inspect the files that already own the flow before reading broad docs: src/lib/backend.*, src/lib/auth.*, src/lib/*service.*, route guards, and the page handlers bound to submit buttons.

3. Validate through the browser, not only by reading code
   - For interaction, routing, rendering, or regression checks, use agent-browser workflows from browser-testing.md.
   - Prefer lightweight smoke validation for changed flows before claiming the frontend work is complete.

4. Treat CloudBase as an integration branch
   - Use CloudBase Web SDK and static hosting guidance only when the project actually needs CloudBase platform features.
   - Reuse auth-tool-cloudbase and auth-web-cloudbase for login or provider readiness instead of re-describing those flows here.

Core workflow

1. Choose the right engineering path

• React / Vue feature work: implement within the app's existing component, routing, and state conventions
• New Web app: prefer Vite unless the repo already standardizes on another toolchain
• Debugging and regressions: reproduce in browser, narrow to a specific page or interaction, then patch
• CloudBase integration: wire in Web SDK, auth, data, or static hosting only after the base frontend path is clear

2. Keep implementation grounded in project reality

• Follow the repo's package manager, scripts, and lint/test patterns
• Avoid framework rewrites unless the user explicitly asks for one
• Prefer the smallest viable page/component/config change that satisfies the task
• In TODO-based apps, complete the existing implementation directly instead of creating parallel helpers, sample pages, or detached prototypes

3. Validate changed flows explicitly

• Run the relevant local build / lint / typecheck / test command when available. A clean tsc --noEmit and a clean project build are the minimum bar — not proof of correctness.
• For anything user-visible (routing, forms, rendering, auth, async flows), open the affected page or flow in a browser with agent-browser. Code reading alone is not sufficient evidence — see the Engineering constitution above.
• Record what was checked: route, action, expected result, actual result, and any remaining gap.

🧰 脚手架速查与排障

> 上面是怎么做事；这一章 + references/scaffold_and_debug.md 是从一句需求到可运行页面的速查与急救台。

新项目开工、或线上报错一时看不出名堂时，先读 references/scaffold_and_debug.md，它覆盖四件事：

三条默认：能静态就别上框架；新项目默认 Vite + TS（src 源码 / dist 产物）；已有仓库一律贴合现状，不做顺手框架迁移。
排障顺序：先固定复现步骤 → 定位层级（构建 / 类型 / 运行时 / 网络 / 渲染）→ 看最近改了什么 → 最小复现二分 → 同一路径连试 2–3 次就换路子。

CloudBase Web integration

Use this section only when the Web project needs CloudBase platform features.

Web SDK rules

• Prefer npm installation for React, Vue, Vite, and other bundler-based projects: npm install @cloudbase/js-sdk
• Use the CDN only for static HTML pages, quick demos, embedded snippets, or README examples: https://static.cloudbase.net/cloudbase-js-sdk/latest/cloudbase.full.js
• Only use documented CloudBase Web SDK APIs; do not invent methods or options
• Keep a shared app or auth instance instead of re-initializing on every call
• If the user only provides an environment alias, nickname, or other shorthand, resolve it to the canonical full EnvId before writing SDK init code, console links, or config files. Do not pass alias-like short forms directly into cloudbase.init({ env }).

Authentication boundary

• Authentication must use CloudBase SDK built-in features
• Do not move Web login logic into cloud functions
• For provider readiness, login method setup, or publishable key issues, route to auth-tool-cloudbase and auth-web-cloudbase

Static hosting defaults

• 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
• SPA routing (History mode): when using React Router / Vue Router in History mode (not hash mode), configure the CloudBase static hosting "404 error document" to index.html. Otherwise refreshing or directly visiting any sub-route returns NoSuchKey / 404 error, because the static hosting looks for a file at that path instead of falling through to index.html for the SPA to handle routing.

Use the MCP tool to apply this:
json manageHosting({ action: "setWebsiteDocument", indexDocument: "index.html", errorDocument: "index.html" })

Then verify with:
json queryHosting({ action: "websiteConfig" })

CloudBase quick start

// npm install @cloudbase/js-sdk
import cloudbase from "@cloudbase/js-sdk";

const app = cloudbase.init({
  env: "your-full-env-id", // Canonical full CloudBase environment ID resolved from queryEnv or the console
});

const auth = app.auth

🧪 改完必做的浏览器验证

> 依据工程宪章 §2「自验证 before claiming done」与 browser-testing.md。构建通过 ≠ 页面能用；只跑 tsc / build 就宣称完成，等于没完成。

改动影响到任何用户能看到、点到、跳转到的东西时，六项逐条过一遍（详见 references/scaffold_and_debug.md §3 与 browser-testing.md）：

判定规则：

• 6 项任一未过 → 不许说"做完了"。
• 某项本地跑不了（缺凭证 / 缺后端 / 付费 API / 平台限制）→ 显式写明哪一项、卡在哪，不得含糊带过。
• 记录格式：路由 / 动作 / 预期 / 实测 / 缺口；一句"浏览器测了没问题"不算证据。
• 只改了构建配置、纯文档、或后端且不渲染 → 可免浏览器验证，但要在结论里说明为什么免。

常见触发场景（前端工程）

边界：什么时候不该用本技能 / 误用风险

• 纯视觉方向 / 审美探索 → 用 ui-design（前端美学·雕琢大师）。本技能是"实现层"，不是"设计层"；工程宪章明确要求动手写第一行 CSS 前必须先加载 ui-design 出设计规范。
• 小程序 / 原生 App → 用 miniprogram-development / http-api-cloudbase，别把 Web SDK 套路套过去。
• 纯后端服务 → 用 cloudrun-development / cloud-functions。
• 微信支付 / 公众号 OAuth 细节 → 先定 Web 面，再用 cloudbase-wechat-integration。
• 图标检索 / 纯素材 → 用 svg-icons-hunter。
• 需求还没定、先要方案 → 先走 spec-workflow。

> 误用典型：用户说"帮我把这个页面做得好看点"，其实是要视觉方向 → 直接改 CSS 会掉回 AI 模板默认风；应先调 ui-design 出设计规范再动手。

典型工作流示例（从一句需求到可验证交付）

下面用 3 个真实形态的需求演示本技能如何落地（示例为虚构，不指向真实账号/产品）：

示例 A — 新建一个 Vite + React 落地页
1. 澄清：确认是 greenfield、要部署到 CloudBase 静态托管 → 默认 Vite + TS。
2. 选路径：React feature work → 搭 src/ 骨架，index.html + vite.config.ts。
3. 写代码：组件 / 路由 / 表单；遵守宪章 §1（不写 any）。
4. 静态层：tsc --noEmit + eslint + vite build 全过。
5. 运行时层：agent-browser 打开 localhost:5173，走查进入/提交/异常/退出/回归 5 条路径。
6. 交付：CloudBase 静态托管（manageApps 首次部署，错误文档设 index.html），给控制台链接。

示例 B — 已有仓库里修一个路由 404
1. 澄清：是 targeted repair，不是 greenfield。
2. 定位：先读 src/lib/*router*、src/App.tsx、路由守卫，不广扫全仓。
3. 复现：agent-browser 直接刷子路由，确认 404。
4. 修复：托管错误文档设 index.html 或改 hash 路由。
5. 验证：重刷子路由正常；相邻路由无回归；无新 console 报错。

示例 C — 给页面接 CloudBase 登录
1. 澄清：确认项目真要用 CloudBase（wx.cloud 还是 Web SDK？）。
2. 路由：auth-tool-cloudbase → auth-web-cloudbase 先开 provider、拿 publishable key。
3. 实现：Web SDK 初始化（EnvId 用全称，不传 alias）、auth.getSession() 守卫（弃用 getLoginState）。
4. 验证：浏览器走「未登录 → 跳登录 → 成功 → 受保护路由可达 → 退出 → 重定向」。

常见问答 FAQ

Q1：我改了 CSS，构建过了，能说做完了吗？
A：不能。宪章 §2 明确：构建通过 ≠ 页面能用。涉及任何用户可见/可点/可跳转的东西，必须过浏览器验证 6 项（构建/无报错/多断点/关键交互/网络/性能），6 项任一未过不许说"做完了"。

Q2：类型一片红但我运行是好的，能 @ts-ignore 跳过吗？
A：不能。宪章 §1 红线：禁用 any / @ts-ignore / @ts-nocheck / @ts-expect-error（无书面理由）。正确做法是装 @types、用 unknown + 类型守卫、写精确 interface。

Q3：前端 History 路由刷新就 404？
A：CloudBase 静态托管按文件路径找文件。把「404 错误文档」设为 index.html（见 SKILL.md「Static hosting defaults」），或先用 hash 路由。

Q4：用户只要"把页面做得好看"，我直接改样式行吗？
A：不行。这是视觉方向，应先加载 ui-design 出设计规范，否则会掉回 AI 模板默认风。

Q5：云函数能当登录方案用吗？
A：不能。Web 登录必须用 CloudBase SDK 内置鉴权（auth.getSession()），不要把 Web 登录逻辑塞进云函数。