¿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:
- 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. - Despliegue — Bucket TOS + CDN + certificado DV gratuito + endurecimiento HTTPS, todo escrito en scripts Node idempotentes a través de la CLI
vey la API OpenAPI de Volcengine (firmada con SigV4 a través devolc-api.mjspara las acciones queveno 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:
| Escenario | Alternativa recomendada | Por qué |
|---|---|---|
| Sitio personal / portafolio / proyecto secundario, sin requisito de audiencia china | GitHub Pages | Gratuito, 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 China | Vercel (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 perimetrales | Esta 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 PR | Vercel | La 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.
| # | Entrada | Se usa para | Notas |
|---|---|---|---|
| 1 | Nombre de la empresa (chino + inglés) | COMPANY.nameZh / COMPANY.nameEn en site.ts; pie de página; SEO | |
| 2 | Dominio (ej. example.com) | En todas partes — enlace de bucket, CDN, DNS, SAN del certificado | DEBE 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. |
| 3 | Directorio 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. |
| 4 | Lista de productos | PRODUCTS[] en site.ts | Cada producto necesita nombre y descripción bilingües, URL, color hexadecimal de acento, enumeración de icono. |
| 5 | Número de registro ICP | Pie de página | El número de registro emitido por el MIIT. |
| 6 | Directorio de trabajo | Raíz del proyecto | Debe 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:
- Generar — copia
assets/templates/package.jsonyassets/templates/astro.config.mjsen la raíz del proyecto. Actualizanameen package.json ysiteen astro.config.mjs. - Instalar paquetes —
pnpm install. - Instalar la skill del agente Astro — solo después de que
pnpm installse haya ejecutado correctamente:
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.npx skills add https://github.com/astrolicious/agent-skills --skill astro - 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). - Extraer la marca del SVG del usuario — usa
assets/templates/BrandMark.astrocomo 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. - 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.
- Verificar localmente —
pnpm devpara desarrollar,pnpm build && pnpm previewpara 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.
- Copiar scripts — copia todo el directorio
assets/scripts/yassets/cdn-payloads/en los directoriosscripts/yscripts/cdn-payloads/del usuario respectivamente. Copiaassets/templates/deploy.config.mjsen la raíz del proyecto y completabucket,region,endpoint,cdnDomains. - Reemplazar marcadores de posición en los payloads —
{{DOMAIN}},{{BUCKET}},{{REGION}}enscripts/cdn-payloads/apex.jsonywww.json.OriginHostdebe ser el propio dominio, no vacío — las plantillas son correctas desde el primer momento; si las editas, conservaOriginHost. Ver landmines.md #3. - Crear
.enven la raíz del proyecto (gitignorado):
El AK/SK de Volcengine necesitaVOLC_ACCESS_KEY=AK... VOLC_SECRET_KEY=...TOSFullAccess,CDNFullAccess,DNSFullAccess,CertificateFullAccess(o equivalentes de mínimo privilegio). - Verificar que
veesté 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:
- Contaminación de
HTTPS_PROXY— SDK de TOS + un proxy HTTP local =Protocol "http:" not supported. Cada script enassets/scripts/ya elimina las variables de entorno del proxy al principio — conserva ese preámbulo si los copias / adaptas. - Peculiaridades del SDK de TOS —
headBucket(string)noheadBucket({bucket}); la firma delistObjectsType2se rompe cuandocontinuationToken: undefinedestá en la entrada;putObjectpor defecto es privado incluso en buckets de lectura pública — siempre estableceacl: 'public-read'. - TOS no tiene un nombre de host de endpoint de sitio web separado — el mismo
<bucket>.tos-<region>.volces.comdevuelve JSON de listado de bucket oindex.htmldependiendo del encabezadoHost. DEBES (a) llamar aputBucketCustomDomainpor dominio apex/www, Y (b) establecerOriginHosten el payload deAddCdnDomaindel CDN al dominio del usuario (no vacío). - CDN ≠ DCDN para verificación — CDN (内容分发网络) quiere
volccdnauthcomo host de TXT ycdn:CheckCdnDomain(no en la CLIve— usavolc-api.mjs). DCDN (全站加速) usa_dnsauthyve dcdn VerifyDomainOwnership. Mezclarlos = bucle de verificación interminable. - 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.
pnpm deployes un comando integrado. Usapnpm run deploy.- 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 ejecutaCertificateGetInstanceListprimero; busca enResult.Instances[](NO enInstanceList, NO enData) uno cuyoSancubra tanto apex como www.
Reglas de comportamiento
- Planifica primero; confirma antes de operaciones destructivas. Antes de
createBucket,AddCdnDomain,DeleteRecorden TXT existente, oBatchDeployCert, 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/CertificateGetInstanceListprimero — 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
vele falte una acción, usavolc-api.mjsen lugar de decirle al usuario que actualiceveo 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 —
volccdnauthpara CDN,_dnsauthpara 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/curles más fiable quecurlsolo 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 CLIve.setup-bucket.mjs— enlace de bucket + sitio web + dominio personalizado idempotente.deploy.mjs— cargador de sincronización TOS conCache-Controlpor 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 decdn:SubmitRefreshTask(firmado porvolc-api.mjs, funciona en CI sinve).
assets/cdn-payloads/ (cópialo en scripts/cdn-payloads/)
...
[truncado para la traducción]