web-development

同级技能（仅限本地）

同级 CloudBase 技能会与此技能一同提供。请使用 ../auth-tool-cloudbase/SKILL.md 之类的本地相对路径。

如果此环境中缺少引用的同级技能文件，请让用户安装完整的 CloudBase 插件（或缺失的技能）。不要通过 HTTP 将远程技能或协议 Markdown 获取到 Agent 上下文中。

跨领域协议（更改代码或部署前必须遵循）：

• 更改安全协议：../cloudbase-platform/references/protocols/change-safety-protocol.md
• 部署门禁：../cloudbase-platform/references/protocols/deployment-gate.md

Web 开发

激活约定

以下情况请先使用此技能

• 请求内容是实现、集成、调试、构建、部署或验证 Web 前端或静态网站。
• 设计方向已经确定，或者用户要求的是工程实施，而非视觉探索。
• 工作涉及 React、Vue、Vite、路由、浏览器验证或 CloudBase Web 集成。

编写代码前请阅读

• 任务涉及项目结构、框架约定、构建配置、部署、路由，或前端测试与验证流程。
• 请求涉及 UI 实现，且视觉方向已确定；否则请先阅读 ui-design。
• ⚠️ 任何涉及界面样式、布局、配色方案或字体选择的任务——在编写第一行 CSS/Tailwind 之前，必须加载 ui-design 技能并输出设计规范。 跳过此步骤会导致前端样式退化为千篇一律的 AI 模板默认风格。必须在开始任何视觉实现之前加载 ui-design 技能，而不是等用户抱怨外观后再补做。

然后还需阅读

• React / Vue / Vite 通用指南 -> frameworks.md
• 浏览器流程检查或页面验证 -> browser-testing.md
• 登录流程 -> ../auth-tool-cloudbase/SKILL.md，然后是 ../auth-web-cloudbase/SKILL.md
• CloudBase 上的公众号 JSAPI 支付、Native 扫码支付或微信 OAuth -> ../cloudbase-wechat-integration/SKILL.md（官方文档：https://docs.cloudbase.net/integration/introduce.md）
• CloudBase 数据库相关工作 -> 对应的数据库技能

请勿用于

• 设定视觉方向、以原型为先的设计工作，或纯审美探索。
• 小程序、原生 App 或仅涉及后端的服务。
• 微信支付或公众号 OAuth 的协议细节；确认 Web 场景后，请使用 cloudbase-wechat-integration。

常见错误 / 注意事项

• 未先确认任务属于设计还是工程实施就开始动手。
• 将框架配置、部署和 CloudBase 集成问题混在一个含糊的改动中。
• 默认将云函数视为 Web 身份验证的解决方案。
• UI 或路由更改后跳过浏览器级验证。
• CloudBase 静态托管中的 History 模式 SPA：使用 History 模式（React Router / Vue Router）部署单页应用，却未将静态托管的“404 错误文档”配置为 index.html。这会导致用户刷新页面或直接访问任何子路由时出现 NoSuchKey / 404 错误。
• 在现有应用中，尚未修补当前处理程序和服务，就转而重新设计 UI 或大范围检查代码库。

工程准则（不可妥协）

这些规则优先于便利性。在说“完成”之前，必须先通过这道门槛。

1. TypeScript — 不要屏蔽类型系统

• 不要使用 any 来绕过类型错误。 不要写 : any、as any、@ts-ignore、@ts-nocheck，也不要在没有书面说明的情况下使用 @ts-expect-error。any 会悄无声息地传播，让本项目唯一的编译时安全保障形同虚设。
• 出现类型错误时，请修复根本原因：
  • 缺少或错误的库类型 → 安装 @types/...，或缩小导入范围，或针对实际使用的数据结构编写精确的 interface / type。
  • 边界处的数据结构确实未知（来自 API 的 JSON、postMessage 负载、window.* 注入）→ 将其类型设为 unknown，并通过类型守卫（typeof、in、判别字段，或 zod / 等效方案）缩小类型范围。
  • 第三方类型有误 → 在本地 .d.ts 中通过 declare module 扩充类型，而不是使用 any。
  • 确实需要动态处理的情况（例如泛型事件总线）→ 使用带约束的泛型 <T>，而不是 any。
• 使用 unknown 并缩小类型范围是可接受的变通方案。any 不可接受。
• 如果确实无法避免在某一行使用 any（极其罕见），请留下一行注释，说明原因以及如何消除该用法，以便审查者核查。
• ESLint 也应遵循同样的原则：不要到处添加 // eslint-disable 来屏蔽真正的问题。请修复规则违规，或在禁用前进行讨论。

2. 声称完成前先自行验证

进行任何非简单的代码或配置更改前，必须先遵循 cloudbase-platform/references/protocols/change-safety-protocol.md 中的变更安全协议（声明影响 → 用户确认 → 编辑后验证）。 进行任何静态托管发布或自定义域名相关工作前，必须完成 cloudbase-platform/references/protocols/deployment-gate.md 中的检查。

没有证据就声称“已实现”“已修复”或“应该可以运行”，不可接受。宣布完成前，必须实际运行检查并报告结果。

静态／构建层（适用时始终执行）：

• tsc --noEmit（或 vue-tsc --noEmit）通过，且没有错误，也没有你新增的被屏蔽诊断。
• eslint / 项目代码检查工具通过对已更改文件的检查。
• 项目的构建命令（npm run build / pnpm build / vite build）成功完成，且没有引入新的警告。
• 如果项目有单元测试，且测试覆盖了修改部分，则这些测试通过。

运行时／浏览器层（更改影响渲染、路由、表单、身份验证或异步流程时执行）：

• 使用 agent-browser 工具实际打开页面并复现用户可见的流程。具体操作步骤请遵循 browser-testing.md。
• 确认：目标路由能够加载；你声称已修复的交互行为符合预期；没有引入新的控制台错误；你改动的相邻路由没有回归问题。
• 记录检查内容（路由、操作、预期结果、实际结果）。

只有两个层面的检查都通过后，才能说任务已完成。如果无法在本地执行其中任何一项（例如凭据受限、缺少后端、需要付费 API），请明确说明，并准确列出仍未验证的步骤，不要含糊带过。

3. 不要掩盖失败

• 不要用 try { ... } catch {} 包裹有问题的逻辑来消除错误。
• 不要删除或跳过失败的测试来让 CI 变绿——请修复测试，或说明测试为何有误，并提供理由后再修改测试。
• 不要因为“代码能编译”就宣布任务完成。编译只是最低要求，不是目标。

何时使用此技能

在进行 Web 工程开发工作时使用此技能，例如：

• 实现 React 或 Vue 页面和组件
• 搭建或维护基于 Vite 的前端项目
• 处理路由、数据加载、表单和构建配置
• 运行基于浏览器的验证和冒烟测试
• 在项目需要 CloudBase 功能时，集成 CloudBase Web SDK 和静态托管

请勿用于：

• 仅进行 UI 方向或视觉系统设计；请使用 ui-design
• 小程序开发；请使用 miniprogram-development
• 后端服务实现；请使用 cloudrun-development 或 cloud-functions

如何使用此技能（面向编码 Agent）

1. 明确执行范围

   • 确认任务属于框架搭建、页面实现、调试、部署、验证还是 CloudBase 集成。
   • 将工作限制在实际的 Web 应用范围内，不要扩展到无关的后端变更。
   • 如果工作区是一个带有 TODO 的现有应用，应将其视为有针对性的修复任务，而不是从零开始构建。

2. 遵循框架和构建约定

   • 如果项目已有技术栈，优先沿用。
   • 对于新项目，除非仓库或用户的约束另有要求，否则将 Vite 作为默认打包工具。
   • 除非仓库已有不同约定，否则将可复用的应用代码放在 src 下，将构建输出放在 dist 下。
   • 在结构固定的现有应用中，应先检查已负责相关流程的文件，再阅读范围较广的文档：src/lib/backend.*、src/lib/auth.*、src/lib/*service.*、路由守卫，以及绑定到提交按钮的页面处理程序。

3. 通过浏览器验证，而不只是阅读代码

   • 对于交互、路由、渲染或回归检查，请使用 browser-testing.md 中的 agent-browser 工作流。
   • 在宣布前端工作完成前，优先对变更涉及的流程进行轻量级冒烟验证。

4. 将 CloudBase 视为独立集成分支

   • 仅当项目确实需要 CloudBase 平台功能时，才使用 CloudBase Web SDK 和静态托管指南。
   • 对于登录或身份提供方准备工作，请复用 auth-tool-cloudbase 和 auth-web-cloudbase，不要在此处重复描述相关流程。

核心工作流

1. 选择合适的工程路径

• React / Vue 功能开发：按照应用现有的组件、路由和状态管理约定进行实现
• 新建 Web 应用：除非仓库已统一采用其他工具链，否则优先使用 Vite
• 调试和回归：在浏览器中复现问题，缩小到具体页面或交互，然后修复
• CloudBase 集成：只有在明确基础前端实现路径后，才接入 Web SDK、身份验证、数据或静态托管

2. 让实现立足于项目实际情况

• 遵循仓库的包管理器、脚本和 lint / 测试惯例
• 除非用户明确要求，否则避免重写框架
• 优先采用满足任务要求的最小可行页面、组件或配置变更
• 对于基于 TODO 的应用，直接完成现有实现，不要创建并行辅助工具、示例页面或独立原型

3. 明确验证变更涉及的流程

• 如有相关命令，运行相应的本地构建 / lint / 类型检查 / 测试命令。通过 tsc --noEmit 并成功构建项目是最低要求，但不能证明实现正确。
• 对于任何用户可见的内容（路由、表单、渲染、身份验证、异步流程），都应使用 agent-browser 在浏览器中打开受影响的页面或流程。仅阅读代码不足以作为证据；请参阅上文的工程准则。
• 记录检查内容：路由、操作、预期结果、实际结果以及任何尚未解决的问题。

CloudBase Web 集成

仅当 Web 项目需要 CloudBase 平台功能时，才使用本节。

Web SDK 规则

• 对于 React、Vue、Vite 和其他基于打包器的项目，优先使用 npm 安装：npm install @cloudbase/js-sdk
• CDN 仅用于静态 HTML 页面、快速演示、嵌入式代码片段或 README 示例：https://static.cloudbase.net/cloudbase-js-sdk/latest/cloudbase.full.js
• 仅使用有文档说明的 CloudBase Web SDK API；不要臆造方法或选项
• 保留共享的 app 或 auth 实例，不要在每次调用时都重新初始化
• 如果用户只提供环境别名、昵称或其他简称，请先将其解析为规范的完整 EnvId，再编写 SDK 初始化代码、控制台链接或配置文件。不要将类似别名的简称直接传入 cloudbase.init({ env })。

身份验证边界

• 身份验证必须使用 CloudBase SDK 内置功能
• 不要将 Web 登录逻辑移到云函数中
• 如果涉及提供商就绪情况、登录方式设置或可发布密钥问题，请转交给 auth-tool-cloudbase 和 auth-web-cloudbase

静态托管默认规则

• 明确说明部署路径——不要只说“部署到静态托管”。 前端首次部署应通过 manageApps({ action: "deployApp", ... }) 进行：每个应用都会分配自己的子域名并保留版本历史（queryApps({ action: "getAppVersion" }) 会列出发布版本，manageApps({ action: "deleteAppVersion" }) 会删除某个版本），因此可以回滚。最初通过托管方式部署的项目（使用共享域名路径）应继续使用 manageHosting({ action: "upload", ... })。绝不要回退到 tcb deploy。

• 部署前先构建

• 为兼容静态托管，优先使用相对资源路径

• 如果项目没有服务器端路由重写，默认使用哈希路由

• 如果用户未指定根路径，默认避免直接部署到站点根目录

• SPA 路由（History 模式）：使用 React Router / Vue Router 的 History 模式（而非哈希模式）时，请将 CloudBase 静态托管的 “404 错误文档” 配置为 index.html。否则，刷新或直接访问任何子路由都会返回 NoSuchKey / 404 错误，因为静态托管会尝试查找该路径下的文件，而不会回退到 index.html 交由 SPA 处理路由。

  使用 MCP 工具进行配置：

  manageHosting({ action: "setWebsiteDocument", indexDocument: "index.html", errorDocument: "index.html" })
  

  然后验证：

  queryHosting({ action: "websiteConfig" })
  

CloudBase 快速入门

// 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