前言¶

Web 前端任務一旦落到「改路由、接登錄、打包部署、接 CloudBase」，模型很容易把框架腳手架、靜態託管和 @cloudbase/js-sdk 混在一輪對話裏改，還缺少類型檢查與瀏覽器驗收的約束。下面介紹 SkillHub 上的 @tencent-adm/web-development（Web 開發 · CloudBase Web Development）：在方向已定的前提下，把實現、集成、調試、構建、部署和校驗收斂成可執行的工程流程。

這是什麼¶

一句話定位：騰訊雲 CloudBase Web 前端開發指南型 Agent Skill，覆蓋 React / Vue / Vite 工程化、靜態託管部署、@cloudbase/js-sdk 集成與內置認證相關邊界。

維護方：騰訊雲 CloudBase 團隊（SkillHub 分類 dev-programming，來源 enterprise）。

座標與版本：@tencent-adm/web-development，當前版本 2.36.0（以 SkillHub 頁面爲準）。

在 SkillHub 上的概況：評分 100000，下載 32184；標籤 requires_api_key=false，安裝 Skill 本身不需要額外 API Key。

解決什麼問題：把「何時用本 Skill、何時轉 ui-design / 認證 / 微信集成等兄弟 Skill」寫進激活契約；對 TypeScript、自驗、部署門禁和 History 模式 SPA 託管等常見坑給出硬性規則，減少泛泛的「應該可以了」式回答。

核心功能¶

以下內容均來自該 Skill 的 SKILL.md 說明，僅概括已寫明的能力邊界。

適用任務（Activation Contract）¶

在以下情況優先啓用本 Skill：

• 實現、集成、調試、構建、部署或校驗 Web 前端或靜態站點；
• 設計方向已確定，或用戶要的是工程執行而非視覺探索；
• 涉及 React、Vue、Vite、路由、瀏覽器側驗證或 CloudBase Web 集成。

不適用：純 UI 方向與美學探索（應先用 ui-design）、小程序、純原生 App、純後端服務；微信支付 / 公衆號 OAuth 合約細節應轉 cloudbase-wechat-integration。

工程規範（節選）¶

Skill 將部分規則標爲「不可妥協」：

1. TypeScript：禁止用 any、@ts-ignore 等繞過類型錯誤；邊界未知數據用 unknown 並收窄。
2. 完成前自驗：非平凡改動需遵循兄弟 Skill cloudbase-platform 中的 Change Safety Protocol；靜態託管發佈前需過 Deployment Gate。需跑 tsc --noEmit、lint、構建；涉及頁面交互時用 agent-browser 按 browser-testing.md 做瀏覽器層驗證。
3. SPA History 模式：使用 React Router / Vue Router History 模式時，CloudBase 靜態託管須把 404 錯誤文檔 設爲 index.html，否則刷新或直接訪問子路由會出現 NoSuchKey / 404。

CloudBase Web 集成要點¶

• SDK 安裝：Bundler 項目優先 npm install @cloudbase/js-sdk；純靜態 HTML 或片段可用 CDN https://static.cloudbase.net/cloudbase-js-sdk/latest/cloudbase.full.js。
• 初始化：使用完整環境 ID（EnvId），勿把別名直接傳入 cloudbase.init({ env })。
• 認證：Web 登錄須用 CloudBase SDK 內置能力，不要把 Web 登錄邏輯挪到雲函數；登錄與 Provider 配置轉 auth-tool-cloudbase、auth-web-cloudbase。
• 靜態託管：先構建再部署；默認傾向 hash 路由（無服務端重寫時）；首次前端應用部署路徑與「託管路徑上傳」在 Skill 中有區分（manageApps / manageHosting，並明確不要回退到 tcb deploy）。

SDK 快速初始化示例（Skill 原文）：

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

const app = cloudbase.init({
  env: "your-full-env-id", // 從控制台或 queryEnv 解析的完整 EnvId
});

const auth = app.auth;

History 模式 SPA 託管配置示例（通過 MCP 工具，Skill 原文）：

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

驗證：

queryHosting({ action: "websiteConfig" })

兄弟 Skill 與本地引用¶

CloudBase 系列 Skill 通常與插件一起安裝。本 Skill 要求通過本地相對路徑引用兄弟 Skill（例如 ../auth-tool-cloudbase/SKILL.md），缺失時應提示用戶安裝完整 CloudBase 插件，不要 HTTP 拉取遠程 Skill 文檔進上下文。

安裝與啓用¶

通過 SkillHub CLI¶

先確認是否已安裝 skillhub：

command -v skillhub && skillhub --version

未安裝時可按 SkillHub 官方安裝文檔執行（完整安裝或僅 CLI）：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

安裝本 Skill 時需用 --dir 指向當前 Agent 的 skills 目錄（裝到默認 ./skills/ 可能不會被識別）：

skillhub install @tencent-adm/web-development --dir <skills 目錄>

SkillHub 頁面給出的通用安裝提示爲：請根據 https://skillhub.cn/install/skillhub.md，安裝 @tencent-adm/web-development（可發給 AI 代爲執行）。

常見 Agent 的 skills 目錄¶

以 SkillHub 安裝文檔爲準：

其他客戶端路徑見 https://skillhub.cn/install/skillhub.md 第四節。

官方入口：

• SkillHub 展示頁：https://www.skillhub.cn/skills/tencent-adm/web-development
• API 座標頁：https://api.skillhub.cn/tencent-adm/web-development

典型用法¶

面向編碼 Agent 時，Skill 建議按以下順序工作（摘要）：

1. 明確執行面：區分腳手架、頁面實現、調試、部署、校驗還是 CloudBase 集成；已有項目按 TODO / 現有 handler 修補，避免平行造樣板頁。
2. 遵循倉庫約定：已有棧優先；新項目默認 Vite；代碼在 src、產物在 dist（除非倉庫另有約定）。
3. 瀏覽器驗證：交互、路由、渲染類改動按 browser-testing.md 用 agent-browser 冒煙，不能只看代碼。
4. CloudBase 作爲分支：僅在項目確實需要平臺能力時接 SDK、認證與靜態託管；視覺規範未定前須先加載 ui-design 並輸出 Design Specification。

核心工作流路徑（Skill 原文分類）：

• React / Vue 功能：在現有組件、路由、狀態約定內實現；
• 新 Web 應用：優先 Vite；
• 調試：瀏覽器復現 → 縮小到頁面或交互 → 再改代碼；
• CloudBase：基礎前端路徑清楚後再接 Web SDK、認證與託管。

更細的框架說明見 Skill 包內 frameworks.md，瀏覽器流程見 browser-testing.md（安裝後位於 Skill 目錄，勿編造未列出的配置項）。

適用場景與注意¶

適合誰

• 已在用或計劃用 CloudBase 做 Web 靜態託管與 @cloudbase/js-sdk 的團隊；
• 希望 Agent 在 React / Vue / Vite 任務裏強制類型紀律、構建與瀏覽器驗收的開發者；
• 需要與 CloudBase 認證、平臺協議（變更安全、部署門禁）對齊的前端集成工作。

限制與注意

• 純視覺方向、小程序、後端-only 任務應換用對應 Skill，避免範圍漂移。
• 完整體驗依賴同插件下的兄弟 Skill（如 cloudbase-platform、auth-web-cloudbase）；僅裝單個 Skill 時，引用路徑可能缺失，需按 Skill 提示補裝插件。
• Skill 要求使用文檔化的 SDK API，禁止臆造方法；環境 ID 必須解析爲完整 EnvId。
• SkillHub 統計（下載量、評分）會隨時間變化，以安裝前在 SkillHub 頁面看到的數值爲準。

結尾¶

@tencent-adm/web-development 把 CloudBase Web 前端從「寫頁面」擴展到「可交付」：框架與構建約定、SDK 與認證邊界、靜態託管與 SPA 路由、以及完成前的類型與瀏覽器驗證。若你的 Agent 經常處理 React / Vue / Vite 與 CloudBase 託管，可按上文命令安裝到對應 skills 目錄。

官方地址：https://api.skillhub.cn/tencent-adm/web-development
SkillHub 頁面：https://www.skillhub.cn/skills/tencent-adm/web-development