Communitygithub.com

tenshowinnovation/tenshow-se-skills

An opinionated end-to-end workflow for building and deploying a bilingual (Chinese/English) static company marketing site to Volcengine — using Astro 6 + React 19 islands + Tailwind 4, deployed to TOS + CDN with HTTPS, force-redirect, HSTS, and HTTP/2, entirely via the `ve` CLI and Node SDKs.

What is tenshow-se-skills?

This skill provides a complete, opinionated workflow for building and shipping a bilingual (Chinese/English) static company marketing site to Volcengine (火山引擎). It is designed for developers who need to deploy a production-ready site for a Chinese company or a product targeting users in mainland China, where ICP 备案 and low-latency delivery are critical. The build phase uses Astro 6 with React 19 islands (only for the mobile menu) and Tailwind 4, with a single content file (`src/content/site.ts`) as the source of truth. The deployment phase scripts the entire infrastructure setup — TOS bucket, CDN, free DV certificate, and HTTPS hardening — using idempotent Node scripts via the `ve` CLI and Volcengine OpenAPI (SigV4-signed via `volc-api.mjs`). Success means the user runs approximately 6 commands end-to-end and gets `https://<their-domain>/` serving a production-quality bilingual site with HTTPS, force-redirect, HSTS, HTTP/2, edge caching, and automated cache invalidation. The skill is optimized for Volcengine + China mainland deployments and should only be used when that scenario matches; for simpler projects (personal sites, international audiences, or sites needing serverless functions), the skill recommends alternatives like Vercel, Cloudflare Pages, or GitHub Pages.

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

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

Site de site marketing (Volcengine)

Skill de bout en bout pour construire et déployer un site marketing statique bilingue (chinois/anglais) d'entreprise 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 la CLI ve et les API OpenAPI de Volcengine (signées SigV4 via volc-api.mjs pour les actions que ve ne fournit pas).

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


Cette skill est-elle adaptée ?

Il s'agit d'un workflow délibérément opinionated optimisé pour un scénario spécifique. Avant d'approfondir, vérifiez que ce scénario correspond réellement à la situation de l'utilisateur. Dans le cas contraire, proposez une meilleure alternative plutôt que de forcer l'utilisateur à suivre un chemin plus lourd.

Utilisez cette skill quand :

  • Le site est destiné à une entreprise chinoise ou à un produit ciblant les utilisateurs en Chine continentale — la latence depuis la Chine continentale vers des CDN non chinois est suffisamment mauvaise (200-400 ms, souvent pire aux heures de pointe) pour que les visiteurs la remarquent et quittent le site.
  • L'ICP 备案 est requis ou déjà en main — la distribution en Chine nécessite légalement l'enregistrement lié à un domaine hébergé sur un cloud chinois. Volcengine propose une assistance pour l'备案 et l'offre 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 quand :

ScénarioAlternative recommandéePourquoi
Site personnel / portfolio / projet secondaire, pas d'exigence de public chinoisGitHub PagesGratuit, HTTPS automatique, déploiement sur git push, aucune infrastructure à gérer. Aucune des complications de Volcengine ne s'applique.
Public uniquement international (US/UE/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 entièrement le workflow CLI ve + ICP.
Le site nécessite des fonctions serverless (formulaires, authentification, contenu dynamique)Vercel ou Cloudflare Pages avec leurs fonctions en périphérieCette skill livre uniquement du statique — Volcengine propose des produits serverless, mais le workflow ici ne les couvre pas.
Vous voulez des URL de prévisualisation par branche / révision basée sur les PRVercelL'expérience d'URL de prévisualisation de Vercel est la meilleure de sa catégorie. Cette skill produit un déploiement de production par push ; pas de prévisualisations par branche.

Si la situation de l'utilisateur correspond à la colonne "utilisez une alternative plus simple", dites-le-lui explicitement avant de mettre en place quoi que ce soit. Un déploiement Vercel de 2 minutes est une meilleure expérience qu'un bootstrap Volcengine de 30 minutes lorsque l'utilisateur n'a pas besoin de ce que Volcengine fournit. Ne les enfermez pas dans la mauvaise pile parce qu'ils ont invoqué cette skill.

En cas de doute, demandez : "Les utilisateurs de Chine continentale représenteront-ils une part significative de votre public, 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 tant que vous n'avez pas 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 peut-être le numéro de sécurité publique — celui-ci peut être un placeholder.

#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 BrandMark.astro (les 3 derniers chemins du SVG du logo court)Généralement quelque chose comme assets/logo/svg/Tenshow_short1.svg — variante courte / icône uniquement.
4Liste des produitsPRODUCTS[] dans site.tsChaque produit a besoin d'un nom bilingue + description, URL, couleur d'accent hexadécimale, énumération d'icône.
5Numéro d'enregistrement ICPPied de pageLe 备案号 délivré par le MIIT.
6Répertoire de travailRacine du projetDevrait être greenfield (vide) ou vous devrez coordonner avec les fichiers existants.

Optionnellement :

  • 公安备案号 (Numéro d'enregistrement de la sécurité publique) — généralement un placeholder au moment de la mise en place. 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. Mettre en place — Copiez assets/templates/package.json et assets/templates/astro.config.mjs dans la racine du projet. Mettez à jour name dans package.json et site dans astro.config.mjs.
  2. Installer les packages — pnpm install.
  3. Installer la skill de l'agent Astro — 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 skill échoue, continuez la construction du site et notez l'échec pour que l'utilisateur réessaye plus tard ; ne bloquez pas le workflow sur 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 SVG du logo court 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 déviez pas)

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 D'ABORD — la moitié de votre temps dans cette phase est consacrée à éviter les pièges, pas à exécuter des commandes.

  1. Copier les scripts — copiez tout le répertoire assets/scripts/ et assets/cdn-payloads/ respectivement dans les répertoires scripts/ et scripts/cdn-payloads/ de l'utilisateur. Copiez assets/templates/deploy.config.mjs à la racine du projet et remplissez bucket, region, endpoint, cdnDomains.
  2. Remplacer les placeholders dans les payloads — {{DOMAIN}}, {{BUCKET}}, {{REGION}} dans scripts/cdn-payloads/apex.json et www.json. OriginHost doit être le domaine lui-même, pas vide — les templates sont corrects par défaut ; si vous les modifiez, préservez OriginHost. Voir landmines.md #3.
  3. Créer .env à la racine du projet (gitignoré) :
    VOLC_ACCESS_KEY=AK...
    VOLC_SECRET_KEY=...
    
    L'AK/SK Volcengine nécessite TOSFullAccess, CDNFullAccess, DNSFullAccess, CertificateFullAccess (ou équivalents en privilèges minimaux).
  4. Vérifier que ve est installé : ve version — nécessite 1.0.x ou ultérieur. 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 du site web + liaison de domaine personnalisé
pnpm run deploy:upload              # synchroniser dist/ → bucket
# à ce stade : https://<bucket>.tos-<region>.volces.com/index.html devrait renvoyer 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 le 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 seul

pnpm deploy est une commande intégrée d'espace de travail 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. Résultat 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 fait correspondre chaque mode d'échec à la cause racine et au correctif.


Pièges critiques que vous devez 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 + un proxy HTTP local = Protocol "http:" not supported. Chaque script dans assets/scripts/ supprime déjà les variables d'environnement de proxy en haut — préservez ce préambule si vous les copiez / adaptez.
  2. Bizarreries du SDK TOS — headBucket(string) pas headBucket({bucket}) ; la signature listObjectsType2 se casse quand continuationToken: undefined est dans l'entrée ; putObject par défaut en 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 payload 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 la CLI ve — utilisez volc-api.mjs). DCDN (全站加速) utilise _dnsauth et ve dcdn VerifyDomainOwnership. Les mélanger = boucle de vérification sans fin.
  5. Les modifications TXT prennent ~10 min à se propager au vérificateur Volcengine. Obtenez la valeur correcte du premier coup ; ne faites pas de va-et-vient.
  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 par API est bloquée avec un AK/SK permanent (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. Utilisez toujours CertificateGetInstanceList d'abord ; cherchez dans Result.Instances[] (PAS InstanceList, PAS Data) un dont le San couvre à la fois apex et 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 à l'utilisateur.
  • Lisez l'état existant avant d'écrire. Utilisez 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 à niveau ve ou d'utiliser la console. Le seul chemin vraiment réservé à la console est l'émission de certificat DV gratuit (landmines.md #4).
  • Ne faites pas de va-et-vient sur les enregistrements DNS. Chaque modification TXT ajoute ~10 min de cache. Obtenez l'hôte/valeur correct du premier coup — volccdnauth pour CDN, _dnsauth pour DCDN, ils ne sont pas interchangeables.
  • Exposez chaque décision de configuration dans deploy.config.mjs, ne les codez jamais en dur dans les scripts. Bucket, région, point de terminaison, domaines CDN, règles de cache — tout se trouve 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 de chemin bash devient parfois étrange. Idem pour les tests dans les scripts CI.

Assets et références fournis

assets/scripts/ (copiez 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 la CLI 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/ (copiez dans scripts/cdn-payloads/)

...

[truncé pour la traduction]

Related Skills