Communitygithub.com

Marketing Site Dev (Volcengine) – Übersetzung

Opinionierter End-to-End-Workflow zum Erstellen und Bereitstellen einer zweisprachigen statischen Unternehmens-Website auf Volcengine – Astro 6 + React 19 Islands + Tailwind 4, deployed auf TOS + CDN mit HTTPS, Force-Redirect, HSTS und HTTP/2, vollständig über die `ve` CLI und Node SDKs.

Was ist Marketing Site Dev (Volcengine) – Übersetzung?

Diese Skill ist ein stark opinionierter Workflow, der speziell für den Bau und die Bereitstellung einer zweisprachigen (Chinesisch/Englisch) statischen Unternehmens-Website auf der Volcengine-Cloud-Plattform entwickelt wurde. Sie ist optimiert für Unternehmen oder Produkte, die sich an Nutzer in Festlandchina richten und eine ICP-Lizenzierung benötigen oder bereits besitzen. Der Workflow besteht aus zwei Hauptphasen: Zunächst wird die Website mit Astro 6, React 19 Islands (nur für das mobile Menü) und Tailwind 4 erstellt, wobei eine einzige Konfigurationsdatei (`src/content/site.ts`) als einzige Quelle der Wahrheit dient. Anschließend erfolgt die Bereitstellung über idempotente Node-Skripte, die TOS-Buckets (kompatibel mit S3) und CDN mit HTTPS, HSTS und automatischer Cache-Invalidierung einrichten. Die Skill unterstützt Plattformen wie Claude Code, Cursor und Codex und ist besonders nützlich, wenn Benutzer die Bereitstellung auf Volcengine, TOS, CDN oder die ICP-Lizenzierung erwähnen. Sie umfasst detaillierte Entscheidungstabellen, um festzustellen, ob diese komplexe Lösung notwendig ist, und empfiehlt einfachere Alternativen wie Vercel oder GitHub Pages für Projekte ohne China-Schwerpunkt. Kritische Aspekte wie die Vermeidung von Fallstricken (z. B. Konflikte mit HTTPS_PROXY, TOS-SDK-Eigenheiten) und die strikte Einhaltung von Verhaltensregeln (Planung vor destruktiven Aktionen, Auslesen des aktuellen Zustands vor Änderungen) sind dokumentiert.

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

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Marketing-Website-Entwicklung (Volcengine)

End-to-End-Skill zum Erstellen und Bereitstellen einer zweisprachigen statischen Unternehmens-Website auf Volcengine. Zwei Phasen:

  1. Build – Astro 6 + React 19 Islands (nur mobiles Menü) + Tailwind 4. Inline-SVG überall. Eine einzige Inhaltsdatei (src/content/site.ts) ist die alleinige Quelle der Wahrheit.
  2. Deploy – TOS-Bucket + CDN + kostenloses DV-Zertifikat + HTTPS-Härtung, alles in idempotenten Node-Skripten über die ve CLI und Volcengine OpenAPI (SigV4-signiert via volc-api.mjs für Aktionen, die ve nicht bereitstellt).

Wie Erfolg aussieht: Der Benutzer führt ~6 Befehle Ende-zu-Ende aus und erhält https://<ihre-domain>/, das eine produktionsreife zweisprachige Website mit HTTPS, Force-Redirect zu HTTPS, HSTS, HTTP/2, Edge-Caching und automatischer Cache-Invalidierung ausliefert. Jeder Infrastrukturschritt ist als idempotentes Skript versioniert.


Ist dieser Skill die richtige Wahl?

Dies ist ein bewusst opinionierter Workflow, der für ein bestimmtes Szenario optimiert ist. Bevor Sie in die Tiefe gehen, prüfen Sie, ob dieses Szenario tatsächlich der Situation des Benutzers entspricht. Wenn nicht, zeigen Sie die bessere Alternative auf, anstatt den Benutzer durch einen schwereren Pfad zu zwingen.

Verwenden Sie diesen Skill, wenn:

  • Die Website für ein chinesisches Unternehmen oder ein Produkt, das sich an Nutzer in Festlandchina richtet, bestimmt ist – die Latenz vom Festland zu nicht-chinesischen CDNs ist schlecht genug (200-400 ms, oft schlimmer zu Spitzenzeiten), dass Besucher es bemerken und abspringen.
  • ICP 备案 ist erforderlich oder bereits vorhanden – die Auslieferung in China benötigt legal die beim Ministerium registrierte Datei, die an eine in einer chinesischen Cloud gehostete Domain gebunden ist. Volcengine bündelt 备案-Unterstützung und bietet sie für die hier bereitgestellte Domain an.
  • Der Benutzer befindet sich bereits im Volcengine-Ökosystem (andere Volcengine-Dienste, vorhandene TOS-Buckets usw.) und Konsolidierung ist wertvoll.
  • Das zweisprachige zh/en-Muster ist gewünscht – die Inhaltsebene (site.ts) ist darauf ausgelegt.

Verwenden Sie eine einfachere Alternative, wenn:

SzenarioEmpfohlene AlternativeWarum
Persönliche Website / Portfolio / Nebenprojekt, keine Anforderung an chinesisches PublikumGitHub PagesKostenlos, automatisches HTTPS, Bereitstellung bei git push, keine zu verwaltende Infrastruktur. Keine der Volcengine-Fallstricke treffen zu.
Internationales Publikum (USA/EU/SEA), keine China-Präsenz geplantVercel (oder Cloudflare Pages / Netlify)Kostenloses Kontingent, sofortige Bereitstellungen aus Git, Vorschau-URLs pro PR, automatisches HTTPS, globales Edge-Netzwerk. Überspringen Sie den gesamten ve CLI + ICP-Workflow vollständig.
Website benötigt serverlose Funktionen (Formulare, Authentifizierung, dynamische Inhalte)Vercel oder Cloudflare Pages mit deren Edge-FunktionenDieser Skill liefert rein statische Inhalte aus – Volcengine hat serverlose Produkte, aber der Workflow hier deckt sie nicht ab.
Sie wünschen Vorschau-URLs pro Branch / PR-basierte ÜberprüfungVercelDie Vorschau-URL-Benutzererfahrung von Vercel ist erstklassig. Dieser Skill erzeugt eine Produktions-Bereitstellung pro Push; keine Branch-Vorschauen.

Wenn die Situation des Benutzers mit der Spalte "Verwenden Sie eine einfachere Alternative" übereinstimmt, teilen Sie ihm dies explizit mit, bevor Sie etwas gerüsten. Ein 2-minütiger Vercel-Deploy ist eine bessere Erfahrung als ein 30-minütiger Volcengine-Bootstrap, wenn der Benutzer nicht braucht, was Volcengine bietet. Drängen Sie sie nicht in den falschen Stack, nur weil sie diesen Skill aufgerufen haben.

Fragen Sie im Zweifelsfall: "Werden Nutzer in Festlandchina einen bedeutenden Teil Ihres Publikums ausmachen, und haben Sie (oder planen Sie) die ICP 备案 für die Domain einzureichen?" Wenn beide Antworten nein lauten, verweisen Sie auf Vercel / GitHub Pages und hören Sie auf.


Schritt 1: Absicht erfassen (IMMER ZUERST FRAGEN)

Schreiben Sie keinen Code, bevor Sie diese sechs Eingaben vom Benutzer haben. Wenn sie in der Aufforderung fehlen, fragen Sie via AskUserQuestion. Die meisten Teams werden alles haben, außer möglicherweise die öffentliche Sicherheitsnummer – diese ist als Platzhalter in Ordnung.

#EingabeVerwendet fürHinweise
1Unternehmensname (Chinesisch + Englisch)COMPANY.nameZh / COMPANY.nameEn in site.ts; Footer; SEO
2Domain (z. B. example.com)Überall – Bucket-Bindung, CDN, DNS, Zertifikats-SANMUSS bereits ICP-gemeldet und idealerweise auf Volcengine DNS gehostet sein. Wenn anderswo gehostet, muss der Benutzer manuell CNAME- + TXT-Einträge hinzufügen.
3Marken-Assets-Verzeichnis (Pfad zu SVG-Logodateien)Inline-Extraktion von BrandMark.astro (die letzten 3 Pfade des kurzen Logo-SVGs)Normalerweise so etwas wie assets/logo/svg/Tenshow_short1.svg – kurze / symbol-only Variante.
4ProduktlistePRODUCTS[] in site.tsJedes Produkt benötigt zweisprachigen Namen + Beschreibung, URL, Akzent-Hex-Farbe, Icon-Enum.
5ICP-RegistrierungsnummerFooterDie vom MIIT ausgestellte 备案号.
6ArbeitsverzeichnisProjekt-RootSollte Neuland (leer) sein, oder Sie müssen mit vorhandenen Dateien koordinieren.

Optional:

  • 公安备案号 (Nummer der öffentlichen Sicherheitsbehörde) – normalerweise ein Platzhalter zum Zeitpunkt des Gerüstbaus. Markieren Sie es deutlich in der README, damit der Benutzer es vor dem Start ersetzt.
  • Markenakzentfarbe – extrahieren Sie sie aus den Hex-Werten des Logo-SVGs. Wenn nicht entscheidbar, verwenden Sie standardmäßig die dominante nicht-neutrale Farbe.

Schritt 2: Die statische Website erstellen

Vollständige Details in references/phase-1-static-site.md. Die Kurzfassung:

  1. Gerüst – kopieren Sie assets/templates/package.json und assets/templates/astro.config.mjs in das Projekt-Root. Aktualisieren Sie name in package.json und site in astro.config.mjs.
  2. Pakete installieren – pnpm install.
  3. Den Astro-Agent-Skill installieren – nur nach erfolgreichem pnpm install:
    npx skills add https://github.com/astrolicious/agent-skills --skill astro
    
    Wenn die Skill-Installation fehlschlägt, setzen Sie den Website-Bau fort und notieren Sie den Fehler, damit der Benutzer es später erneut versuchen kann; blockieren Sie den Workflow nicht darauf.
  4. Erstellen Sie die Quellstruktur entsprechend dem Layout in 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. Extrahieren Sie das Markenzeichen aus dem SVG des Benutzers – verwenden Sie assets/templates/BrandMark.astro als Ausgangspunkt. Die letzten 3 <path>-Elemente des Short-Logo-SVGs sind das Zeichen; kopieren Sie sie wörtlich und wählen Sie Füllungen aus der Markenpalette.
  6. Erstellen Sie die Abschnitte – Hero (mit dem genauen Rezept in phase-1-static-site.md – Gitterhintergrund + radialer Glow + Farbverlaufsüberschrift + Status-Pille + 2 CTAs), Über uns, Produkte, Fokus, Updates, Kontakt, Footer. Header fixiert, mobiles Menü = die einzige React-Insel.
  7. Lokal überprüfen – pnpm dev zum Entwickeln, pnpm build && pnpm preview zur Plausibilitätsprüfung der statischen Ausgabe, bevor Sie die Infrastruktur berühren.

Stack-Festlegung (nicht abweichen)

Astro 6, React 19 (nur mobiles Menü), Tailwind 4 via @tailwindcss/vite, pnpm 10, Node 22+, TypeScript strict, null externe Bilder, null UI-Bibliotheken, null Schriftdienste, Systemschriftstapel. Begründung und vollständige Details in phase-1-static-site.md.


Schritt 3: Bereitstellungsinfrastruktur einrichten

Vollständige Details in references/phase-2-volcengine-deploy.md. Lesen Sie ZUERST references/landmines.md – die Hälfte Ihrer Zeit in dieser Phase wird damit verbracht, die Fallstricke zu vermeiden, nicht Befehle auszuführen.

  1. Skripte kopieren – kopieren Sie das gesamte Verzeichnis assets/scripts/ und assets/cdn-payloads/ in das scripts/ bzw. scripts/cdn-payloads/ des Benutzers. Kopieren Sie assets/templates/deploy.config.mjs in das Projekt-Root und füllen Sie bucket, region, endpoint, cdnDomains aus.
  2. Platzhalter in Payloads ersetzen – {{DOMAIN}}, {{BUCKET}}, {{REGION}} in scripts/cdn-payloads/apex.json und www.json. OriginHost muss die Domain selbst sein, nicht leer – die Vorlagen sind sofort einsatzbereit; wenn Sie sie bearbeiten, bewahren Sie OriginHost. Siehe landmines.md #3.
  3. Erstellen Sie .env im Projekt-Root (gitignoriert):
    VOLC_ACCESS_KEY=AK...
    VOLC_SECRET_KEY=...
    
    Volcengine AK/SK benötigt TOSFullAccess, CDNFullAccess, DNSFullAccess, CertificateFullAccess (oder entsprechende Least-Privilege-Äquivalente).
  4. Überprüfen, ob ve installiert ist: ve version – benötigt Version 1.0.x oder höher. Wenn fehlend, über die offizielle Volcengine-Dokumentation installieren.

Schritt 4: Die erste Bereitstellung ausführen

pnpm install                        # falls noch nicht erledigt
npx skills add https://github.com/astrolicious/agent-skills --skill astro  # falls noch nicht erledigt
pnpm build                          # lokalen Build überprüfen
pnpm run setup:bucket               # idempotent: Bucket + Website-Routing + Custom-Domain-Bindung
pnpm run deploy:upload              # dist/ → Bucket synchronisieren
# an diesem Punkt: https://<bucket>.tos-<region>.volces.com/index.html sollte 200 zurückgeben
pnpm run setup:cdn                  # Verifizierung → CDN hinzufügen → CNAME → Zertifikat → HTTPS-Härtung
# 1-3 Minuten für DNS-Propagation warten
pnpm run cdn:refresh                # Edge-Cache leeren, damit erste Aufrufe kein Bucket-Listing-JSON zurückgeben

Nach diesem ersten Durchlauf wird die tägliche Iteration zu einem Befehl:

pnpm run deploy && pnpm run cdn:refresh

Immer pnpm run verwenden, NICHT pnpm allein

pnpm deploy ist ein eingebauter pnpm-Workspace-Befehl – er wird außerhalb eines Workspaces mit dem Fehler ERR_PNPM_CANNOT_DEPLOY fehlschlagen. Verwenden Sie pnpm run deploy und pnpm run cdn:refresh. Dokumentieren Sie dies in der README des Projekts. Siehe landmines.md #6.


Schritt 5: Überprüfung

Führen Sie die curl + openssl-Checkliste in references/verification.md aus. Erwartet: 5× HTTP 200 auf Schlüsselrouten, 1× 301 auf HTTP → HTTPS, gültiges Zertifikat mit SAN, das Apex + www abdeckt, HTTP/2 + HSTS bestätigt, Cache-Control-Header, die den Regeln in deploy.config.mjs entsprechen.

Wenn eine Prüfung fehlschlägt, ordnet verification.md jeden Fehlermodus der Ursache und der Behebung zu.


Kritische Fallstricke, die Sie vor der Ausführung kennen müssen

Vollständige Aufzählung in landmines.md. Diejenigen, auf die Sie stoßen, wenn Sie das Lesen überspringen:

  1. HTTPS_PROXY-Verschmutzung – TOS SDK + ein lokaler HTTP-Proxy = Protocol "http:" not supported. Jedes Skript in assets/scripts/ löscht bereits Proxy-Umgebungsvariablen am Anfang – bewahren Sie diese Präambel, wenn Sie sie kopieren / anpassen.
  2. TOS SDK-Eigenheiten – headBucket(string) nicht headBucket({bucket}); listObjectsType2-Signatur bricht, wenn continuationToken: undefined in der Eingabe ist; putObject standardmäßig auf privat, selbst bei öffentlich lesbaren Buckets – setzen Sie immer acl: 'public-read'.
  3. TOS hat keinen separaten Website-Endpunkt-Hostnamen – derselbe <bucket>.tos-<region>.volces.com gibt entweder Bucket-Listing-JSON oder index.html zurück, abhängig vom Host-Header. Sie MÜSSEN (a) putBucketCustomDomain pro Apex-/www-Domain aufrufen UND (b) OriginHost im CDN AddCdnDomain-Payload auf die Domain des Benutzers setzen (nicht leer).
  4. CDN ≠ DCDN für die Verifizierung – CDN (内容分发网络) möchte TXT-Host volccdnauth und cdn:CheckCdnDomain (nicht in der ve CLI – verwenden Sie volc-api.mjs). DCDN (全站加速) verwendet _dnsauth und ve dcdn VerifyDomainOwnership. Verwechslung = endlose Verifizierungsschleife.
  5. TXT-Änderungen benötigen ~10 min zur Propagation beim Volcengine-Verifizierer. Holen Sie den Wert beim ersten Schreiben richtig; vermeiden Sie Wechsel.
  6. pnpm deploy ist ein eingebauter Befehl. Verwenden Sie pnpm run deploy.
  7. Kostenloses DV-Zertifikat ANTRAG ist nur über die Konsole möglich. Die API-Ausstellung ist mit permanentem AK/SK blockiert (OperationDenied.RequestFreeInstance). Aber das Auflisten bereits ausgestellter Zertifikate funktioniert einwandfrei – und kostenlose DV-Zertifikate werden oft bei der Domain-Registrierung automatisch ausgestellt. Führen Sie immer zuerst CertificateGetInstanceList durch; suchen Sie in Result.Instances[] (NICHT InstanceList, NICHT Data) nach einem, dessen San sowohl Apex als auch www abdeckt.

Verhaltensregeln

  • Zuerst planen; vor destruktiven Operationen bestätigen. Vor createBucket, AddCdnDomain, DeleteRecord auf vorhandenem TXT oder BatchDeployCert fassen Sie zusammen, was passieren wird, und bitten Sie den Benutzer um Bestätigung.
  • Vor dem Schreiben den aktuellen Zustand auslesen. Führen Sie immer zuerst ListRecords / ListCdnDomains / CertificateGetInstanceList durch – kostenlose Zertifikate sind oft vorausgestellt, CDN-Domains können bereits existieren, DNS-Einträge können bereits auf das Richtige zeigen. Idempotenz ist der springende Punkt.
  • Wenn ve eine Aktion nicht hat, verwenden Sie volc-api.mjs, anstatt dem Benutzer zu sagen, er solle ve aktualisieren oder die Konsole verwenden. Der einzige wirklich konsolen-exklusive Pfad ist die Ausstellung des kostenlosen DV-Zertifikats (landmines.md #4).
  • Wechseln Sie nicht ständig DNS-Einträge. Jede TXT-Änderung fügt ~10 min Cache hinzu. Holen Sie den Host/Wert beim ersten Mal richtig – volccdnauth für CDN, _dnsauth für DCDN, sie sind nicht austauschbar.
  • Jede Konfigurationsentscheidung in deploy.config.mjs auslagern, niemals in Skripten hartcodieren. Bucket, Region, Endpunkt, CDN-Domains, Cache-Regeln – alles lebt in der Konfiguration, damit der Benutzer eine Datei bearbeiten kann, um alles zu ändern.
  • /usr/bin/curl ist zuverlässiger als curl bei der Durchführung von Prüfungen nach langen Befehlen in derselben Shell – die Bash-PATH-Suche wird gelegentlich komisch. Gleiches gilt für Tests in CI-Skripten.

Gebündelte Assets und Referenzen

assets/scripts/ (wörtlich in das scripts/-Verzeichnis des Benutzers kopieren)

  • lib/volc-api.mjs – SigV4-Signer, keine Abhängigkeiten. Verwenden Sie für jede Aktion, die in der ve CLI fehlt.
  • setup-bucket.mjs – idempotentes Bucket + Website + Custom-Domain-Binding.
  • deploy.mjs – TOS-Sync-Uploader mit präfix-bezogenem Cache-Control, Löschung von Verwaisten.
  • cdn-setup.mjs – CDN-Orchestrierung: Eigentumsverifizierung → AddCdnDomain → CNAME → Zertifikat → HTTPS-Härtung.
  • cdn-refresh.mjs – Cache-Invalidierung via cdn:SubmitRefreshTask (signiert von volc-api.mjs, funktioniert in CI ohne ve).

assets/cdn-payloads/ (in scripts/cdn-payloads/ kopieren)

…[für die Übersetzung gekürzt]

Verwandte Skills