Communitygithub.com

tenshowinnovation/tenshow-se-skills

Workflow avisé de bout en bout pour livrer un site vitrine bilingue (中文/English) sur Volcengine — Astro 6 + React 19 islands + Tailwind 4, déployé sur TOS + CDN avec HTTPS, redirection forcée, HSTS et HTTP/2, entièrement via l'interface en ligne de commande `ve` et les SDK Node. À utiliser lorsque l'utilisateur mentionne la création, le déploiement ou la mise à jour d'un site marketing.

Qu'est-ce que tenshow-se-skills ?

Cette compétence fournit un workflow complet, standardisé et optimisé pour créer et déployer un site vitrine statique bilingue (chinois/anglais) sur la plateforme cloud chinoise Volcengine (火山引擎). Elle est idéale pour les sociétés chinoises ou les produits ciblant le marché chinois, où la faible latence, la conformité ICP 备案 et la consolidation des services sont cruciales. Le processus se déroule en deux phases : la construction du site avec Astro 6, React 19 pour l'interface mobile, Tailwind 4 et un fichier de contenu unique et centralisé (`src/content/site.ts`). La phase de déploiement utilise des scripts Node idempotents (via l'interface `ve` et les API Volcengine) pour automatiser la création d'un bucket TOS, la configuration du CDN, l'obtention d'un certificat DV gratuit, le renforcement HTTPS (redirection forcée, HSTS, HTTP/2) et l'invalidation du cache. Le workflow est conçu pour être reproductible : l'utilisateur exécute environ six commandes et obtient une URL `https://<domaine>/` opérationnelle. La compétence intègre également une logique de validation pour éviter une utilisation inappropriée : si l'audience internationale est visée (sans présence en Chine continentale), elle recommande des alternatives plus simples comme Vercel ou GitHub Pages. Elle insiste sur la lecture préalable d'un guide des pièges (landmines) pour éviter les erreurs courantes liées aux SDK TOS, à la configuration du CDN/DCDN ou à la pollution des variables d'environnement proxy. Enfin, elle automatise l'installation de la compétence Astro de l'agent après les dépendances pour que les futures sessions disposent de conseils spécifiques au framework.

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/tenshowinnovation/tenshow-se-skills/tree/HEAD/marketing-site-dev

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Développement Site Vitrine (Volcengine)

Compétence de bout en bout pour construire et livrer un site vitrine statique bilingue sur Volcengine. Deux phases :

  1. Construction — Astro 6 + React 19 islands (menu mobile uniquement) + Tailwind 4. SVG en ligne partout. Un seul fichier de contenu (src/content/site.ts) est la source de vérité.
  2. Déploiement — Bucket TOS + CDN + certificat DV gratuit + durcissement HTTPS, le tout scripté dans des scripts Node idempotents via l'interface en ligne de commande ve et les API Volcengine OpenAPI (signées SigV4 via volc-api.mjs pour les actions que ve ne propose pas).

À quoi ressemble le succès : l'utilisateur exécute ~6 commandes de bout en bout et obtient https://<son-domaine>/ servant un site bilingue de qualité production avec HTTPS, redirection forcée vers HTTPS, HSTS, HTTP/2, mise en cache périphérique et invalidation automatique du cache. Chaque étape d'infrastructure est dans le contrôle de version sous forme de script idempotent.


Cette compétence est-elle adaptée ?

Il s'agit d'un workflow délibérément avisé optimisé pour un scénario spécifique. Avant d'aller plus loin, vérifiez que ce scénario correspond réellement à la situation de l'utilisateur. Si ce n'est pas le cas, proposez la meilleure alternative plutôt que d'imposer un chemin plus lourd.

Utilisez cette compétence lorsque :

  • Le site est destiné à une société chinoise ou à un produit ciblant les utilisateurs en Chine continentale — la latence depuis le continent vers les CDN non chinois est suffisamment mauvaise (200-400ms, souvent pire aux heures de pointe) pour que les visiteurs la remarquent et quittent le site.
  • L'ICP 备案 est requis ou déjà en votre possession — distribuer en Chine de manière légale nécessite le dépôt lié à un domaine hébergé sur un cloud chinois. Volcengine fournit une assistance pour l'ICP et le propose pour le domaine que vous déployez ici.
  • L'utilisateur est déjà dans l'écosystème Volcengine (autres services Volcengine, buckets TOS existants, etc.) et la consolidation est précieuse.
  • Le modèle bilingue zh/en est souhaité — la couche de contenu (site.ts) est conçue autour de cela.

Utilisez une alternative plus simple lorsque :

ScénarioAlternative recommandéePourquoi
Site personnel / portfolio / projet secondaire, sans exigence d'audience chinoiseGitHub PagesGratuit, HTTPS automatique, déploiement sur git push, aucune infrastructure à gérer. Aucun des pièges Volcengine ne s'applique.
Audience internationale uniquement (US/EU/SEA), aucune présence en Chine prévueVercel (ou Cloudflare Pages / Netlify)Niveau gratuit, déploiements instantanés depuis git, URL de prévisualisation par PR, HTTPS automatique, réseau périphérique mondial. Ignorez complètement l'interface ve et le workflow ICP.
Le site nécessite des fonctions serverless (formulaires, authentification, contenu dynamique)Vercel ou Cloudflare Pages avec leurs fonctions périphériquesCette compétence livre uniquement du statique — Volcengine a des produits serverless, mais ce workflow ne les couvre pas.
Vous voulez des URL de prévisualisation par branche / révision basée sur les PRVercelL'UX d'URL de prévisualisation de Vercel est la meilleure de sa catégorie. Cette compétence produit un seul déploiement de production par push ; pas de prévisualisations de branche.

Si la situation de l'utilisateur correspond à la colonne « Utilisez une alternative plus simple », dites-le lui explicitement avant de structurer quoi que ce soit. Un déploiement Vercel de 2 minutes est une meilleure expérience qu'un amorçage Volcengine de 30 minutes lorsque l'utilisateur n'a pas besoin de ce que Volcengine fournit. Ne les enfermez pas dans une pile inadaptée parce qu'ils ont invoqué cette compétence.

En cas de doute, demandez : « Les utilisateurs de Chine continentale feront-ils partie significative de votre audience, et avez-vous (ou prévoyez-vous de déposer) l'ICP 备案 pour le domaine ? » Si les deux réponses sont non, orientez vers Vercel / GitHub Pages et arrêtez-vous.


Étape 1 : Capturer l'intention (DEMANDEZ TOUJOURS D'ABORD)

N'écrivez aucun code avant d'avoir obtenu ces six informations de la part de l'utilisateur. Si elles manquent dans l'invite, demandez via AskUserQuestion. La plupart des équipes auront tout sauf éventuellement le numéro de sécurité publique — celui-ci peut être un espace réservé.

#InformationUtilisé pourNotes
1Nom de l'entreprise (chinois + anglais)COMPANY.nameZh / COMPANY.nameEn dans site.ts ; pied de page ; SEO
2Domaine (ex. example.com)Partout — liaison du bucket, CDN, DNS, SAN du certificatDOIT déjà avoir l'ICP et idéalement être hébergé sur le DNS Volcengine. Si hébergé ailleurs, l'utilisateur doit ajouter manuellement les enregistrements CNAME + TXT.
3Répertoire des assets de marque (chemin vers les fichiers SVG du logo)Extraction en ligne de BrandMark.astro (les 3 derniers chemins du court logo SVG)Généralement quelque chose comme assets/logo/svg/Tenshow_short1.svg — variante courte / icône uniquement.
4Liste de produitsPRODUCTS[] dans site.tsChaque produit a besoin d'un nom et d'une description bilingues, d'une URL, d'une couleur d'accent hexadécimale, d'une énumération d'icône.
5Numéro d'enregistrement ICPPied de pageLe numéro de dépôt délivré par le MIIT.
6Répertoire de travailRacine du projetDoit être vierge (vide) ou vous devrez coordonner avec les fichiers existants.

Optionnellement :

  • Numéro de sécurité publique (公安备案号) — généralement un espace réservé au moment de la structuration. Signalez-le clairement dans le README pour que l'utilisateur le remplace avant le lancement.
  • Couleur d'accent de la marque — extrayez-la des valeurs hexadécimales du SVG du logo. Si indécidable, utilisez par défaut la couleur non neutre dominante.

Étape 2 : Construire le site statique

Détails complets dans references/phase-1-static-site.md. La liste courte :

  1. Structurer — copier assets/templates/package.json et assets/templates/astro.config.mjs dans la racine du projet. Mettre à jour name dans package.json et site dans astro.config.mjs.
  2. Installer les paquets — pnpm install.
  3. Installer la compétence Astro de l'agent — seulement après que pnpm install a réussi :
    npx skills add https://github.com/astrolicious/agent-skills --skill astro
    
    Si l'installation de la compétence échoue, continuez la construction du site et notez l'échec pour que l'utilisateur réessaie plus tard ; ne bloquez pas le workflow pour cela.
  4. Créer l'arborescence source correspondant à la disposition dans phase-1-static-site.md (src/content/site.ts, src/components/, src/layouts/BaseLayout.astro, src/pages/index.astro, src/pages/en/index.astro, src/styles/global.css).
  5. Extraire la marque du SVG de l'utilisateur — utilisez assets/templates/BrandMark.astro comme point de départ. Les 3 derniers éléments <path> du court SVG du logo sont la marque ; copiez-les textuellement et choisissez les remplissages dans la palette de la marque.
  6. Construire les sections — Hero (avec la recette exacte dans phase-1-static-site.md — fond de grille + lueur radiale + titre dégradé + pastille de statut + 2 CTA), À propos, Produits, Focus, Mises à jour, Contact, Pied de page. En-tête collant, menu mobile = le seul îlot React.
  7. Vérifier localement — pnpm dev pour développer, pnpm build && pnpm preview pour vérifier la sortie statique avant de toucher à l'infrastructure.

Verrouillage de la pile (ne pas dévier)

Astro 6, React 19 (menu mobile uniquement), Tailwind 4 via @tailwindcss/vite, pnpm 10, Node 22+, TypeScript strict, zéro image externe, zéro bibliothèque UI, zéro service de polices, pile de polices système. Justification et détails complets dans phase-1-static-site.md.


Étape 3 : Configurer l'infrastructure de déploiement

Détails complets dans references/phase-2-volcengine-deploy.md. Lisez references/landmines.md EN PREMIER — la moitié de votre temps dans cette phase consiste à éviter les pièges, pas à exécuter des commandes.

  1. Copier les scripts — copier l'intégralité du répertoire assets/scripts/ et assets/cdn-payloads/ dans les répertoires scripts/ et scripts/cdn-payloads/ de l'utilisateur respectivement. Copier assets/templates/deploy.config.mjs à la racine du projet et remplir bucket, region, endpoint, cdnDomains.
  2. Remplacer les espaces réservés dans les charges utiles — {{DOMAIN}}, {{BUCKET}}, {{REGION}} dans scripts/cdn-payloads/apex.json et www.json. OriginHost doit être le domaine lui-même, pas vide — les modèles sont corrects par défaut ; si vous les modifiez, préservez OriginHost. Voir landmines.md #3.
  3. Créer .env à la racine du projet (ignoré par git) :
    VOLC_ACCESS_KEY=AK...
    VOLC_SECRET_KEY=...
    
    La clé AK/SK Volcengine nécessite TOSFullAccess, CDNFullAccess, DNSFullAccess, CertificateFullAccess (ou équivalents au moindre privilège).
  4. Vérifier que ve est installé : ve version — nécessite la version 1.0.x ou ultérieure. Si manquant, installez via la documentation officielle de Volcengine.

Étape 4 : Exécuter le premier déploiement

pnpm install                        # si pas encore fait
npx skills add https://github.com/astrolicious/agent-skills --skill astro  # si pas encore fait
pnpm build                          # vérifier que la construction locale fonctionne
pnpm run setup:bucket               # idempotent : bucket + routage de site web + liaison de domaine personnalisé
pnpm run deploy:upload              # synchroniser dist/ → bucket
# à ce stade : https://<bucket>.tos-<region>.volces.com/index.html devrait répondre 200
pnpm run setup:cdn                  # vérification → ajout CDN → CNAME → certificat → durcissement HTTPS
# attendre 1 à 3 minutes pour la propagation DNS
pnpm run cdn:refresh                # vider le cache périphérique pour que les premières visites ne renvoient pas de JSON de liste de bucket

Après cette exécution initiale, l'itération quotidienne devient une commande :

pnpm run deploy && pnpm run cdn:refresh

Utilisez TOUJOURS pnpm run, PAS pnpm nu

pnpm deploy est une commande d'espace de travail intégrée à pnpm — elle générera une erreur ERR_PNPM_CANNOT_DEPLOY en dehors d'un espace de travail. Utilisez pnpm run deploy et pnpm run cdn:refresh. Documentez cela dans le README du projet. Voir landmines.md #6.


Étape 5 : Vérifier

Exécutez la liste de contrôle curl + openssl dans references/verification.md. Attendu : 5× HTTP 200 sur les routes clés, 1× 301 sur HTTP → HTTPS, certificat valide avec SAN couvrant apex + www, HTTP/2 + HSTS confirmés, en-têtes cache-control correspondant aux règles de deploy.config.mjs.

Si une vérification échoue, verification.md associe chaque mode d'échec à la cause racine et au correctif.


Pièges critiques à connaître avant d'exécuter

Énumération complète dans landmines.md. Ceux que vous rencontrerez si vous sautez la lecture :

  1. Pollution HTTPS_PROXY — SDK TOS + proxy HTTP local = Protocol "http:" not supported. Chaque script dans assets/scripts/ supprime déjà les variables d'environnement proxy en haut — préservez ce préambule si vous les copiez/adaptez.
  2. Particularités du SDK TOS — headBucket(string) pas headBucket({bucket}) ; la signature listObjectsType2 se casse quand continuationToken: undefined est dans l'entrée ; putObject est par défaut privé même sur les buckets en lecture publique — définissez toujours acl: 'public-read'.
  3. TOS n'a pas de nom d'hôte de point de terminaison de site web séparé — le même <bucket>.tos-<region>.volces.com renvoie soit du JSON de liste de bucket, soit index.html selon l'en-tête Host. Vous DEVEZ (a) appeler putBucketCustomDomain par domaine apex/www, ET (b) définir OriginHost dans la charge utile AddCdnDomain du CDN sur le domaine de l'utilisateur (pas vide).
  4. CDN ≠ DCDN pour la vérification — CDN (内容分发网络) veut l'hôte TXT volccdnauth et cdn:CheckCdnDomain (pas dans l'interface ve — utilisez volc-api.mjs). DCDN (全站加速) utilise _dnsauth et ve dcdn VerifyDomainOwnership. Les confondre = boucle de vérification sans fin.
  5. Les modifications TXT mettent ~10 min à se propager chez le vérificateur de Volcengine. Obtenez la bonne valeur dès la première écriture ; ne changez pas.
  6. pnpm deploy est une commande intégrée. Utilisez pnpm run deploy.
  7. La demande de certificat DV gratuit est réservée à la console. L'émission via API est bloquée avec une clé AK/SK permanente (OperationDenied.RequestFreeInstance). Mais la liste des certificats déjà émis fonctionne — et les certificats DV gratuits sont souvent émis automatiquement lors de l'enregistrement du domaine. Faites toujours CertificateGetInstanceList d'abord ; cherchez dans Result.Instances[] (PAS InstanceList, PAS Data) celui dont San couvre à la fois apex + www.

Règles de comportement

  • Planifiez d'abord ; confirmez avant les opérations destructrices. Avant createBucket, AddCdnDomain, DeleteRecord sur un TXT existant, ou BatchDeployCert, résumez ce qui va se passer et demandez la confirmation de l'utilisateur.
  • Lisez l'état existant avant d'écrire. Faites toujours ListRecords / ListCdnDomains / CertificateGetInstanceList d'abord — les certificats gratuits sont souvent pré-émis, les domaines CDN peuvent déjà exister, les enregistrements DNS peuvent déjà pointer au bon endroit. L'idempotence est tout l'intérêt.
  • Quand ve manque d'une action, utilisez volc-api.mjs plutôt que de dire à l'utilisateur de mettre à jour ve ou d'utiliser la console. Le seul chemin véritablement réservé à la console est l'émission de certificat DV gratuit (landmines.md #4).
  • Ne changez pas les enregistrements DNS inutilement. Chaque modification TXT ajoute ~10 min de cache. Obtenez le bon hôte/valeur du premier coup — volccdnauth pour le CDN, _dnsauth pour le DCDN, ils ne sont pas interchangeables.
  • Exposez chaque décision de configuration dans deploy.config.mjs, ne durcissez jamais dans les scripts. Bucket, région, point de terminaison, domaines CDN, règles de cache — tout vit dans la configuration pour que l'utilisateur puisse modifier un seul fichier pour tout changer.
  • /usr/bin/curl est plus fiable que curl nu lors de l'exécution de vérifications après de longues commandes dans le même shell — la recherche du chemin bash peut parfois devenir étrange. Idem pour les tests dans les scripts CI.

Assets et références inclus

assets/scripts/ (copier textuellement dans le répertoire scripts/ de l'utilisateur)

  • lib/volc-api.mjs — signataire SigV4, zéro dépendance. Utilisez pour toute action manquante dans l'interface ve.
  • setup-bucket.mjs — bucket idempotent + site web + liaison de domaine personnalisé.
  • deploy.mjs — téléchargeur de synchronisation TOS avec Cache-Control par préfixe, suppression des orphelins.
  • cdn-setup.mjs — orchestration CDN : vérification de propriété → AddCdnDomain → CNAME → certificat → durcissement HTTPS.
  • cdn-refresh.mjs — invalidation de cache via cdn:SubmitRefreshTask (signé par volc-api.mjs, fonctionne en CI sans ve).

assets/cdn-payloads/ (copier dans scripts/cdn-payloads/)

Skills associés