Marketing Site Dev (Volcengine)
Skill de ponta a ponta para construir e publicar um site estático de marketing bilíngue na Volcengine. Duas fases:
- Construir — Astro 6 + React 19 islands (apenas menu mobile) + Tailwind 4. SVG inline em todo lugar. Arquivo de conteúdo único (
src/content/site.ts) é a fonte da verdade. - Implantar — Bucket TOS + CDN + cert DV gratuito + hardening HTTPS, tudo roteirizado em scripts Node idempotentes via CLI
vee API Volcengine OpenAPI (assinada com SigV4 viavolc-api.mjspara as ações que ovenão oferece).
Qual é a aparência do sucesso: o usuário executa ~6 comandos de ponta a ponta e obtém https://<dominio-do-usuario>/ servindo um site bilíngue de qualidade de produção com HTTPS, redirecionamento forçado para HTTPS, HSTS, HTTP/2, cache de borda e invalidação de cache automatizada. Cada etapa de infraestrutura está no controle de versão como um script idempotente.
Esta skill é a escolha certa?
Este é um fluxo de trabalho deliberadamente opinativo otimizado para um cenário específico. Antes de se aprofundar, verifique se esse cenário realmente corresponde à situação do usuário. Se não corresponder, apresente a alternativa melhor em vez de forçar o usuário a um caminho mais pesado.
Use esta skill quando:
- O site é para uma empresa chinesa ou um produto voltado para usuários na China continental — a latência de CDNs não chinesas para a China continental é ruim o suficiente (200-400ms, muitas vezes pior durante horários de pico) que os visitantes notam e saem.
- ICP 备案 é necessário ou já está em mãos — distribuir na China legalmente precisa do registro vinculado a um domínio hospedado em uma nuvem chinesa. A Volcengine oferece assistência de 备案 e oferece para o domínio que você implantar aqui.
- O usuário já está no ecossistema Volcengine (outros serviços Volcengine, buckets TOS existentes, etc.) e a consolidação é valiosa.
- O padrão bilíngue zh/en é desejado — a camada de conteúdo (
site.ts) é projetada em torno dele.
Use uma alternativa mais simples quando:
| Cenário | Alternativa recomendada | Por quê |
|---|---|---|
| Site pessoal / portfólio / projeto paralelo, sem necessidade de público chinês | GitHub Pages | Grátis, HTTPS automático, implanta em git push, sem infraestrutura para gerenciar. Nenhuma das armadilhas da Volcengine se aplica. |
| Público apenas internacional (EUA/UE/SEA), sem planos de presença na China | Vercel (ou Cloudflare Pages / Netlify) | Camada gratuita, implantações instantâneas a partir do git, URLs de pré-visualização por PR, HTTPS automático, rede de borda global. Pule todo o fluxo ve CLI + ICP completamente. |
| O site precisa de funções serverless (formulários, autenticação, conteúdo dinâmico) | Vercel ou Cloudflare Pages com suas funções de borda | Esta skill envia apenas estático — a Volcengine tem produtos serverless, mas o fluxo de trabalho aqui não os cobre. |
| Você quer URLs de pré-visualização por branch / revisão baseada em PR | Vercel | A experiência de URL de pré-visualização do Vercel é a melhor da categoria. Esta skill produz uma implantação de produção por push; sem pré-visualizações de branch. |
Se a situação do usuário corresponder à coluna "use uma alternativa mais simples", diga a ele explicitamente antes de estruturar qualquer coisa. Uma implantação de 2 minutos no Vercel é uma experiência melhor do que uma inicialização de 30 minutos na Volcengine quando o usuário não precisa do que a Volcengine oferece. Não o force a usar a stack errada só porque ele invocou esta skill.
Quando em dúvida, pergunte: "Os usuários da China continental serão uma parte significativa do seu público e você tem (ou planeja solicitar) ICP 备案 para o domínio?" Se ambas as respostas forem não, aponte para Vercel / GitHub Pages e pare.
Etapa 1: Capturar a intenção (SEMPRE PERGUNTAR PRIMEIRO)
Não escreva nenhum código até ter estas seis entradas do usuário. Se estiverem faltando no prompt, pergunte via AskUserQuestion. A maioria das equipes terá tudo, exceto possivelmente o número de segurança pública — esse é OK como espaço reservado.
| # | Entrada | Usado para | Notas |
|---|---|---|---|
| 1 | Nome da empresa (chinês + inglês) | COMPANY.nameZh / COMPANY.nameEn em site.ts; rodapé; SEO | |
| 2 | Domínio (ex.: example.com) | Em todo lugar — vinculação de bucket, CDN, DNS, SAN do certificado | DEVE já ter ICP registrado e idealmente hospedado no DNS da Volcengine. Se hospedado em outro lugar, o usuário precisa adicionar manualmente os registros CNAME + TXT. |
| 3 | Diretório de ativos da marca (caminho para arquivos SVG de logotipo) | Extração inline BrandMark.astro (últimos 3 caminhos do logotipo SVG curto) | Geralmente algo como assets/logo/svg/Tenshow_short1.svg — variante curta / apenas ícone. |
| 4 | Lista de produtos | PRODUCTS[] em site.ts | Cada produto precisa de nome + descrição bilíngues, URL, cor de destaque hex, enum de ícone. |
| 5 | Número de registro ICP | Rodapé | O número de 备案 emitido pelo MIIT. |
| 6 | Diretório de trabalho | Raiz do projeto | Deve ser greenfield (vazio) ou você terá que coordenar com arquivos existentes. |
Opcionalmente:
- 公安备案号 (Número de registro do Bureau de Segurança Pública) — geralmente um espaço reservado no momento da estruturação. Sinalize-o claramente no README para que o usuário o substitua antes do lançamento.
- Cor de destaque da marca — extraia dos valores hex do logotipo SVG. Se indecidível, padrão para qualquer cor não neutra dominante.
Etapa 2: Construir o site estático
Detalhes completos em references/phase-1-static-site.md. A lista resumida:
- Estruturar — copie
assets/templates/package.jsoneassets/templates/astro.config.mjspara a raiz do projeto. Atualizenameno package.json esiteno astro.config.mjs. - Instalar pacotes —
pnpm install. - Instalar a skill do agente Astro — apenas depois que
pnpm installfor bem-sucedido:
Se a instalação da skill falhar, continue a construção do site e anote a falha para o usuário tentar novamente mais tarde; não bloqueie o fluxo de trabalho nisso.npx skills add https://github.com/astrolicious/agent-skills --skill astro - Criar a árvore de origem correspondente ao layout em 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). - Extrair a marca do SVG do usuário — use
assets/templates/BrandMark.astrocomo ponto de partida. Os últimos 3 elementos<path>do logotipo SVG curto são a marca; copie-os literalmente e escolha preenchimentos da paleta da marca. - Construir as seções — Hero (com a receita exata em phase-1-static-site.md — fundo de grade + brilho radial + título gradiente + pílula de status + 2 CTAs), About, Products, Focus, Updates, Contact, Footer. Cabeçalho fixo, menu mobile = a única ilha React.
- Verificar localmente —
pnpm devpara desenvolver,pnpm build && pnpm previewpara verificar a saída estática antes de tocar na infraestrutura.
Bloqueio de stack (não desvie)
Astro 6, React 19 (apenas menu mobile), Tailwind 4 via @tailwindcss/vite, pnpm 10, Node 22+, TypeScript estrito, zero imagens externas, zero bibliotecas de UI, zero serviços de fonte, pilha de fontes do sistema. Fundamentação e detalhes completos em phase-1-static-site.md.
Etapa 3: Configurar a infraestrutura de implantação
Detalhes completos em references/phase-2-volcengine-deploy.md. LEIA references/landmines.md PRIMEIRO — metade do seu tempo nesta fase é evitar as armadilhas, não executar comandos.
- Copiar scripts — copie todo o diretório
assets/scripts/eassets/cdn-payloads/parascripts/escripts/cdn-payloads/do usuário, respectivamente. Copieassets/templates/deploy.config.mjspara a raiz do projeto e preenchabucket,region,endpoint,cdnDomains. - Substituir espaços reservados nos payloads —
{{DOMAIN}},{{BUCKET}},{{REGION}}emscripts/cdn-payloads/apex.jsonewww.json.OriginHostdeve ser o próprio domínio, não vazio — os templates estão corretos prontos para uso; se você editá-los, preserveOriginHost. Consulte landmines.md #3. - Criar
.envna raiz do projeto (ignorado pelo git):
O AK/SK da Volcengine precisa deVOLC_ACCESS_KEY=AK... VOLC_SECRET_KEY=...TOSFullAccess,CDNFullAccess,DNSFullAccess,CertificateFullAccess(ou equivalentes de privilégio mínimo). - Verificar se
veestá instalado:ve version— precisa ser 1.0.x ou posterior. Se estiver faltando, instale via a documentação oficial da Volcengine.
Etapa 4: Executar a primeira implantação
pnpm install # se ainda não foi feito
npx skills add https://github.com/astrolicious/agent-skills --skill astro # se ainda não foi feito
pnpm build # verificar se a construção local funciona
pnpm run setup:bucket # idempotente: bucket + roteamento de site + vinculação de domínio personalizado
pnpm run deploy:upload # sincronizar dist/ → bucket
# neste ponto: https://<bucket>.tos-<region>.volces.com/index.html deve retornar 200
pnpm run setup:cdn # verificação → adicionar CDN → CNAME → certificado → hardening HTTPS
# aguarde 1-3 minutos para propagação de DNS
pnpm run cdn:refresh # limpar cache de borda para que os primeiros acessos não retornem JSON de listagem de bucket
Após esta execução inicial, a iteração diária se torna um comando:
pnpm run deploy && pnpm run cdn:refresh
Sempre use pnpm run, NÃO pnpm puro
pnpm deploy é um comando interno de workspace do pnpm — ele resultará em erro com ERR_PNPM_CANNOT_DEPLOY fora de um workspace. Use pnpm run deploy e pnpm run cdn:refresh. Documente isso no README do projeto. Consulte landmines.md #6.
Etapa 5: Verificar
Execute a lista de verificação curl + openssl em references/verification.md. Esperado: 5× HTTP 200 nas rotas principais, 1× 301 em HTTP → HTTPS, certificado válido com SAN cobrindo apex + www, HTTP/2 + HSTS confirmados, cabeçalhos de cache-control correspondentes às regras de deploy.config.mjs.
Se alguma verificação falhar, verification.md mapeia cada modo de falha para a causa raiz e a correção.
Armadilhas críticas que você deve conhecer antes de executar
Enumeração completa em landmines.md. Aquelas que você encontrará se pular a leitura:
- Poluição de
HTTPS_PROXY— SDK TOS + um proxy HTTP local =Protocol "http:" not supported. Cada script emassets/scripts/já exclui as variáveis de ambiente de proxy no topo — preserve esse preâmbulo se você copiá-los / adaptá-los. - Peculiaridades do SDK TOS —
headBucket(string)nãoheadBucket({bucket}); a assinatura delistObjectsType2quebra quandocontinuationToken: undefinedestá na entrada;putObjectpadrão é privado mesmo em buckets de leitura pública — sempre definaacl: 'public-read'. - TOS não tem um hostname de endpoint de site separado — o mesmo
<bucket>.tos-<region>.volces.comretorna JSON de listagem de bucket ouindex.htmldependendo do cabeçalhoHost. Você DEVE (a) chamarputBucketCustomDomainpara cada domínio apex/www, E (b) definirOriginHostno payload deAddCdnDomaindo CDN para o domínio do usuário (não vazio). - CDN ≠ DCDN para verificação — CDN (内容分发网络) quer host TXT
volccdnauthecdn:CheckCdnDomain(não na CLIve— usevolc-api.mjs). DCDN (全站加速) usa_dnsautheve dcdn VerifyDomainOwnership. Misturá-los = loop de verificação interminável. - As alterações de TXT levam ~10 min para propagar no verificador da Volcengine. Acertar o valor na primeira escrita; não fique alterando.
pnpm deployé um comando interno. Usepnpm run deploy.- A solicitação de certificado DV GRATUITO é apenas no console. A emissão via API é bloqueada com AK/SK permanente (
OperationDenied.RequestFreeInstance). Mas listar certificados já emitidos funciona bem — e certificados DV gratuitos são frequentemente emitidos automaticamente no registro do domínio. Sempre façaCertificateGetInstanceListprimeiro; procure emResult.Instances[](NÃOInstanceList, NÃOData) por um cujoSancubra apex + www.
Regras de comportamento
- Planeje primeiro; confirme antes de operações destrutivas. Antes de
createBucket,AddCdnDomain,DeleteRecordem TXT existente, ouBatchDeployCert, resuma o que está prestes a acontecer e peça confirmação ao usuário. - Leia o estado existente antes de escrever. Sempre faça
ListRecords/ListCdnDomains/CertificateGetInstanceListprimeiro — certificados gratuitos são frequentemente pré-emitidos, domínios CDN podem já existir, registros DNS podem já apontar para o lugar certo. A idempotência é o objetivo. - Quando
venão tiver uma ação, usevolc-api.mjsem vez de dizer ao usuário para atualizarveou usar o console. O único caminho verdadeiramente apenas no console é a emissão de certificado DV gratuito (landmines.md #4). - Não fique alterando registros DNS. Cada modificação de TXT adiciona ~10 min de cache. Acertar o host/valor na primeira vez —
volccdnauthpara CDN,_dnsauthpara DCDN, eles não são intercambiáveis. - Exiba cada decisão de configuração em
deploy.config.mjs, nunca codifique em scripts. Bucket, região, endpoint, domínios CDN, regras de cache — tudo no config para que o usuário possa editar um arquivo para mudar tudo. /usr/bin/curlé mais confiável quecurlpuro ao executar verificações após comandos longos no mesmo shell — a pesquisa de PATH do bash ocasionalmente fica estranha. O mesmo vale para testes em scripts de CI.
Ativos e referências incluídos
assets/scripts/ (copie literalmente para o scripts/ do usuário)
lib/volc-api.mjs— assinador SigV4, zero dependências. Use para qualquer ação que falte na CLIve.setup-bucket.mjs— bucket idempotente + site + vinculação de domínio personalizado.deploy.mjs— carregador de sincronização TOS comCache-Controlpor prefixo, exclusão de órfãos.cdn-setup.mjs— orquestração CDN: verificação de propriedade → AddCdnDomain → CNAME → certificado → hardening HTTPS.cdn-refresh.mjs— invalidação de cache viacdn:SubmitRefreshTask(assinado porvolc-api.mjs, funciona em CI semve).
assets/cdn-payloads/ (copie para scripts/cdn-payloads/)
…
[truncado para tradução]