Communitygithub.com

Desarrollo de Sitio Web de Marketing (Volcengine)

Flujo de trabajo integral y dogmático para construir y desplegar un sitio web estático bilingüe (中文/English) de marketing empresarial en Volcengine: Astro 6 + React 19 islas + Tailwind 4, desplegado en TOS + CDN con HTTPS, redirección forzada, HSTS y HTTP/2, todo a través de la CLI `ve` y los SDKs de Node.

¿Qué es Desarrollo de Sitio Web de Marketing (Volcengine)?

Esta skill proporciona un flujo de trabajo completo y altamente opinado para desarrolladores que necesitan construir y publicar un sitio web de marketing estático y bilingüe (chino e inglés) en la plataforma cloud china Volcengine (火山引擎). Cubre desde la generación inicial del proyecto con Astro 6, React 19 (usando islas solo para el menú móvil) y Tailwind 4, hasta el despliegue en un bucket TOS con CDN, certificado DV gratuito, y configuraciones de seguridad HTTPS como redirección forzada y HSTS. La skill está diseñada para ser usada con agentes de IA (como Claude Code o Cursor) y se activa cuando el usuario menciona la creación, despliegue o actualización de un sitio web corporativo o de marketing, especialmente si el destino es Volcengine y el mercado es China continental. El proceso incluye la captura de información clave del usuario (nombre de la empresa, dominio, assets de marca, lista de productos, número de registro ICP), la construcción del sitio con un único archivo de contenido (`site.ts`), y la ejecución de scripts de infraestructura idempotentes que gestionan buckets, CDN y certificados. La skill es deliberadamente restrictiva y recomienda alternativas más simples (Vercel, GitHub Pages) si el público objetivo no es principalmente chino o si no se requiere el registro ICP.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿Qué hace Desarrollo de Sitio Web de Marketing (Volcengine)?

Skill integral para construir y publicar un sitio web estático bilingüe de marketing empresarial en Volcengine. Dos fases:

  1. Construcción — Astro 6 + React 19 islas (solo menú móvil) + Tailwind 4. SVG en línea en todas partes. Un único archivo de contenido (src/content/site.ts) es la fuente de verdad.
  2. Despliegue — Bucket TOS + CDN + certificado DV gratuito + endurecimiento HTTPS, todo escrito en scripts Node idempotentes a través de la CLI ve y la API OpenAPI de Volcengine (firmada con SigV4 a través de volc-api.mjs para las acciones que ve no incluye).

¿Cómo se ve el éxito?: el usuario ejecuta ~6 comandos de principio a fin y obtiene https://<su-dominio>/ sirviendo un sitio bilingüe de calidad de producción con HTTPS, redirección forzada a HTTPS, HSTS, HTTP/2, caché perimetral e invalidación de caché automatizada. Cada paso de infraestructura está en control de versiones como un script idempotente.


¿Esta skill es la adecuada?

Este es un flujo de trabajo deliberadamente dogmático optimizado para un escenario específico. Antes de profundizar, verifica que ese escenario realmente coincida con la situación del usuario. Si no es así, presenta la mejor alternativa en lugar de forzar al usuario a pasar por un camino más pesado.

Usa esta skill cuando:

  • El sitio es para una empresa china o un producto dirigido a usuarios en China continental — la latencia desde China continental a CDNs no chinas es lo suficientemente mala (200-400 ms, a menudo peor durante las horas pico) que los visitantes lo notan y se van.
  • Se requiere o ya se tiene el registro ICP — la distribución en China necesita legalmente el registro vinculado a un dominio alojado en una nube china. Volcengine ofrece asistencia para el registro ICP y lo ofrece para el dominio que despliegues aquí.
  • El usuario ya está en el ecosistema de Volcengine (otros servicios de Volcengine, buckets TOS existentes, etc.) y la consolidación es valiosa.
  • Se desea el patrón bilingüe zh/en — la capa de contenido (site.ts) está diseñada para ello.

Usa una alternativa más simple cuando:

EscenarioAlternativa recomendadaPor qué
Sitio personal / portafolio / proyecto secundario, sin requisito de audiencia chinaGitHub PagesGratuito, HTTPS automático, se despliega con git push, sin infraestructura que gestionar. No aplica ninguno de los problemas de Volcengine.
Audiencia exclusivamente internacional (EE. UU./UE/SEA), sin presencia planificada en ChinaVercel (o Cloudflare Pages / Netlify)Nivel gratuito, despliegues instantáneos desde git, URLs de vista previa por PR, HTTPS automático, red perimetral global. Omite todo el flujo de trabajo ve CLI + ICP.
El sitio necesita funciones serverless (formularios, autenticación, contenido dinámico)Vercel o Cloudflare Pages con sus funciones perimetralesEsta skill publica contenido puramente estático — Volcengine tiene productos serverless, pero este flujo de trabajo no los cubre.
Quieres URLs de vista previa por rama / revisión basada en PRVercelLa experiencia de URL de vista previa de Vercel es la mejor de su clase. Esta skill produce un despliegue de producción por push; sin vistas previas de rama.

Si la situación del usuario coincide con la columna "usa una alternativa más simple", díselo explícitamente antes de empezar a construir. Un despliegue de 2 minutos en Vercel es una mejor experiencia que un inicio de 30 minutos en Volcengine cuando el usuario no necesita lo que Volcengine ofrece. No les hagas perder el tiempo con la pila incorrecta solo porque invocaron esta skill.

En caso de duda, pregunta: "¿Los usuarios de China continental serán una parte significativa de tu audiencia y tienes (o planeas solicitar) el registro ICP para el dominio?" Si ambas respuestas son no, señala Vercel / GitHub Pages y detente.


Paso 1: Capturar la intención (PREGUNTA SIEMPRE PRIMERO)

No escribas ningún código hasta que tengas estas seis entradas del usuario. Si faltan en el prompt, pregunta a través de AskUserQuestion. La mayoría de los equipos lo tendrán todo excepto posiblemente el número de seguridad pública — ese está bien como marcador de posición.

#EntradaSe usa paraNotas
1Nombre de la empresa (chino + inglés)COMPANY.nameZh / COMPANY.nameEn en site.ts; pie de página; SEO
2Dominio (ej. example.com)En todas partes — enlace de bucket, CDN, DNS, SAN del certificadoDEBE tener registro ICP y, idealmente, estar alojado en el DNS de Volcengine. Si está alojado en otro lugar, el usuario debe agregar manualmente los registros CNAME y TXT.
3Directorio de activos de marca (ruta a los archivos SVG del logotipo)Extracción SVG en línea BrandMark.astro (las últimas 3 rutas del SVG del logotipo corto)Generalmente algo como assets/logo/svg/Tenshow_short1.svg — variante corta / solo icono.
4Lista de productosPRODUCTS[] en site.tsCada producto necesita nombre y descripción bilingües, URL, color hexadecimal de acento, enumeración de icono.
5Número de registro ICPPie de páginaEl número de registro emitido por el MIIT.
6Directorio de trabajoRaíz del proyectoDebe ser un campo verde (vacío) o tendrás que coordinarte con los archivos existentes.

Opcionalmente:

  • Número de registro de seguridad pública (公安备案号) — generalmente un marcador de posición en el momento de la generación. Márcalo claramente en el README para que el usuario lo reemplace antes del lanzamiento.
  • Color de acento de la marca — extraído de los valores hexadecimales del SVG del logotipo. Si no se puede decidir, usa por defecto el color no neutro dominante.

Paso 2: Construir el sitio estático

Detalles completos en references/phase-1-static-site.md. El resumen:

  1. Generar — copia assets/templates/package.json y assets/templates/astro.config.mjs en la raíz del proyecto. Actualiza name en package.json y site en astro.config.mjs.
  2. Instalar paquetes — pnpm install.
  3. Instalar la skill del agente Astro — solo después de que pnpm install se haya ejecutado correctamente:
    npx skills add https://github.com/astrolicious/agent-skills --skill astro
    
    Si la instalación de la skill falla, continúa con la construcción del sitio y anota el fallo para que el usuario lo reintente más tarde; no bloquees el flujo de trabajo.
  4. Crear el árbol fuente que coincida con el diseño en 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. Extraer la marca del SVG del usuario — usa assets/templates/BrandMark.astro como punto de partida. Los últimos 3 elementos <path> del SVG del logotipo corto son la marca; cópialos textualmente y elige los colores de relleno de la paleta de la marca.
  6. Construir las secciones — Hero (con la receta exacta en phase-1-static-site.md — fondo de cuadrícula + resplandor radial + titular degradado + píldora de estado + 2 CTAs), Acerca de, Productos, Enfoque, Actualizaciones, Contacto, Pie de página. Encabezado fijo, menú móvil = la única isla de React.
  7. Verificar localmente — pnpm dev para desarrollar, pnpm build && pnpm preview para verificar la salida estática antes de tocar la infraestructura.

Stack fijo (no te desvíes)

Astro 6, React 19 (solo menú móvil), Tailwind 4 a través de @tailwindcss/vite, pnpm 10, Node 22+, TypeScript estricto, cero imágenes externas, cero librerías de UI, cero servicios de fuentes, pila de fuentes del sistema. Justificación y detalles completos en phase-1-static-site.md.


Paso 3: Configurar la infraestructura de despliegue

Detalles completos en references/phase-2-volcengine-deploy.md. Lee references/landmines.md PRIMERO — la mitad de tu tiempo en esta fase es para evitar los problemas, no para ejecutar comandos.

  1. Copiar scripts — copia todo el directorio assets/scripts/ y assets/cdn-payloads/ en los directorios scripts/ y scripts/cdn-payloads/ del usuario respectivamente. Copia assets/templates/deploy.config.mjs en la raíz del proyecto y completa bucket, region, endpoint, cdnDomains.
  2. Reemplazar marcadores de posición en los payloads — {{DOMAIN}}, {{BUCKET}}, {{REGION}} en scripts/cdn-payloads/apex.json y www.json. OriginHost debe ser el propio dominio, no vacío — las plantillas son correctas desde el primer momento; si las editas, conserva OriginHost. Ver landmines.md #3.
  3. Crear .env en la raíz del proyecto (gitignorado):
    VOLC_ACCESS_KEY=AK...
    VOLC_SECRET_KEY=...
    
    El AK/SK de Volcengine necesita TOSFullAccess, CDNFullAccess, DNSFullAccess, CertificateFullAccess (o equivalentes de mínimo privilegio).
  4. Verificar que ve esté instalado: ve version — necesita 1.0.x o posterior. Si falta, instálalo a través de la documentación oficial de Volcengine.

Paso 4: Ejecutar el primer despliegue

pnpm install                        # si no se ha hecho aún
npx skills add https://github.com/astrolicious/agent-skills --skill astro  # si no se ha hecho aún
pnpm build                          # verificar que la construcción local funciona
pnpm run setup:bucket               # idempotente: bucket + enrutamiento web + enlace de dominio personalizado
pnpm run deploy:upload              # sincronizar dist/ → bucket
# en este punto: https://<bucket>.tos-<region>.volces.com/index.html debería devolver 200
pnpm run setup:cdn                  # verificación → añadir CDN → CNAME → certificado → endurecimiento HTTPS
# esperar 1-3 minutos para la propagación de DNS
pnpm run cdn:refresh                # purgar la caché perimetral para que las primeras visitas no devuelvan JSON de listado de bucket

Después de esta ejecución inicial, la iteración diaria se convierte en un comando:

pnpm run deploy && pnpm run cdn:refresh

Usa SIEMPRE pnpm run, NO pnpm directamente

pnpm deploy es un comando integrado del espacio de trabajo de pnpm — dará error con ERR_PNPM_CANNOT_DEPLOY fuera de un espacio de trabajo. Usa pnpm run deploy y pnpm run cdn:refresh. Documenta esto en el README del proyecto. Ver landmines.md #6.


Paso 5: Verificar

Ejecuta la lista de verificación de curl + openssl en references/verification.md. Se espera: 5× HTTP 200 en rutas clave, 1× 301 en HTTP → HTTPS, certificado válido con SAN que cubra apex + www, HTTP/2 + HSTS confirmados, encabezados de control de caché que coincidan con las reglas de deploy.config.mjs.

Si falla alguna comprobación, verification.md asigna cada modo de fallo a la causa raíz y la solución.


Problemas críticos que debes conocer antes de ejecutar

Enumeración completa en landmines.md. Los que te encontrarás si te saltas la lectura:

  1. Contaminación de HTTPS_PROXY — SDK de TOS + un proxy HTTP local = Protocol "http:" not supported. Cada script en assets/scripts/ ya elimina las variables de entorno del proxy al principio — conserva ese preámbulo si los copias / adaptas.
  2. Peculiaridades del SDK de TOS — headBucket(string) no headBucket({bucket}); la firma de listObjectsType2 se rompe cuando continuationToken: undefined está en la entrada; putObject por defecto es privado incluso en buckets de lectura pública — siempre establece acl: 'public-read'.
  3. TOS no tiene un nombre de host de endpoint de sitio web separado — el mismo <bucket>.tos-<region>.volces.com devuelve JSON de listado de bucket o index.html dependiendo del encabezado Host. DEBES (a) llamar a putBucketCustomDomain por dominio apex/www, Y (b) establecer OriginHost en el payload de AddCdnDomain del CDN al dominio del usuario (no vacío).
  4. CDN ≠ DCDN para verificación — CDN (内容分发网络) quiere volccdnauth como host de TXT y cdn:CheckCdnDomain (no en la CLI ve — usa volc-api.mjs). DCDN (全站加速) usa _dnsauth y ve dcdn VerifyDomainOwnership. Mezclarlos = bucle de verificación interminable.
  5. Los cambios de TXT tardan ~10 min en propagarse en el verificador de Volcengine. Obtén el valor correcto en la primera escritura; no cambies constantemente.
  6. pnpm deploy es un comando integrado. Usa pnpm run deploy.
  7. La solicitud de certificado DV GRATUITO es solo a través de la consola. La emisión de API está bloqueada con AK/SK permanente (OperationDenied.RequestFreeInstance). Pero listar los certificados ya emitidos funciona bien — y los certificados DV gratuitos a menudo se emiten automáticamente en el registro del dominio. Siempre ejecuta CertificateGetInstanceList primero; busca en Result.Instances[] (NO en InstanceList, NO en Data) uno cuyo San cubra tanto apex como www.

Reglas de comportamiento

  • Planifica primero; confirma antes de operaciones destructivas. Antes de createBucket, AddCdnDomain, DeleteRecord en TXT existente, o BatchDeployCert, resume lo que está a punto de suceder y pide confirmación al usuario.
  • Lee el estado existente antes de escribir. Siempre ejecuta ListRecords / ListCdnDomains / CertificateGetInstanceList primero — los certificados gratuitos a menudo están preemitidos, los dominios CDN pueden existir ya, los registros DNS pueden ya apuntar al lugar correcto. La idempotencia es el objetivo principal.
  • Cuando a ve le falte una acción, usa volc-api.mjs en lugar de decirle al usuario que actualice ve o que use la consola. El único camino verdaderamente solo de consola es la emisión de certificados DV gratuitos (landmines.md #4).
  • No cambies constantemente los registros DNS. Cada modificación de TXT añade ~10 min de caché. Obtén el host/valor correcto la primera vez — volccdnauth para CDN, _dnsauth para DCDN, no son intercambiables.
  • Expón cada decisión de configuración en deploy.config.mjs, nunca la codifiques en los scripts. Bucket, región, endpoint, dominios CDN, reglas de caché — todo vive en la configuración para que el usuario pueda editar un archivo para cambiarlo todo.
  • /usr/bin/curl es más fiable que curl solo al ejecutar comprobaciones después de comandos largos en el mismo shell — la búsqueda de PATH de bash ocasionalmente se vuelve extraña. Lo mismo para las pruebas en scripts de CI.

Activos y referencias incluidos

assets/scripts/ (cópialo textualmente en el directorio scripts/ del usuario)

  • lib/volc-api.mjs — firmante SigV4, cero dependencias. Úsalo para cualquier acción que falte en la CLI ve.
  • setup-bucket.mjs — enlace de bucket + sitio web + dominio personalizado idempotente.
  • deploy.mjs — cargador de sincronización TOS con Cache-Control por prefijo, eliminación de huérfanos.
  • cdn-setup.mjs — orquestación de CDN: verificación de propiedad → AddCdnDomain → CNAME → certificado → endurecimiento HTTPS.
  • cdn-refresh.mjs — invalidación de caché a través de cdn:SubmitRefreshTask (firmado por volc-api.mjs, funciona en CI sin ve).

assets/cdn-payloads/ (cópialo en scripts/cdn-payloads/)

...

[truncado para la traducción]

Skills relacionados