Communitygithub.com

tenshowinnovation/tenshow-se-skills

Fluxo de trabalho opinativo de ponta a ponta para publicar um site estático de marketing bilíngue (chinês/inglês) na Volcengine — Astro 6 + React 19 islands + Tailwind 4, implantado no TOS + CDN com HTTPS, redirecionamento forçado, HSTS e HTTP/2, inteiramente via CLI `ve` e SDKs Node, com o agente Astro instalado após as dependências para que sessões futuras tenham orientação específica do framework. Use sempre que o usuário mencionar construir, estruturar, implantar ou atualizar um site de empresa / marca / produto / 公司官网 / 营销网站 / 品牌站 / marketing site, ESPECIALMENTE quando Volcengine (火山引擎), TOS, CDN, ICP 备案 ou implantação na China estiverem envolvidos. Também acione quando o usuário fornecer um resumo da empresa com lista de produtos + ativos de marca e pedir uma "implantação em comando único" ou "página de destino pronta para produção", ou fizer referência a arquivos como `astro.config.mjs`, `deploy.config.mjs`, `scripts/cdn-setup.mjs`, `scripts/setup-bucket.mjs`. Prefira esta skill em vez de orientação genérica de desenvolvimento web sempre que o destino da implantação for Volcengine + China continental.

O que é tenshow-se-skills?

Esta skill oferece um fluxo de trabalho completo e opinativo para construir e implantar um site de marketing estático bilíngue (chinês/inglês) na Volcengine, uma nuvem chinesa. Ela é ideal para empresas chinesas ou produtos que visam o mercado da China continental, onde a latência de CDNs não chinesas é um problema e o registro ICP é necessário. A skill automatiza todo o processo, desde a estruturação inicial do site com Astro 6, React 19 e Tailwind 4 até a implantação em produção, incluindo configuração de bucket TOS, CDN, certificado HTTPS e outros hardening de segurança. Tudo é feito via scripts Node idempotentes e a CLI `ve`, garantindo que cada etapa seja reproduzível e versionada. A skill também inclui validação e tratamento de armadilhas comuns (landmines) da plataforma Volcengine, evitando problemas como poluição de variáveis de ambiente, peculiaridades do SDK TOS e confusão entre CDN e DCDN. É particularmente útil para quem precisa de uma solução "pronta para produção" com um único comando, mas também alerta o usuário quando alternativas mais simples (como Vercel ou GitHub Pages) são mais adequadas para o seu cenário.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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:

  1. 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.
  2. Implantar — Bucket TOS + CDN + cert DV gratuito + hardening HTTPS, tudo roteirizado em scripts Node idempotentes via CLI ve e API Volcengine OpenAPI (assinada com SigV4 via volc-api.mjs para as ações que o ve nã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árioAlternativa recomendadaPor quê
Site pessoal / portfólio / projeto paralelo, sem necessidade de público chinêsGitHub PagesGrá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 ChinaVercel (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 bordaEsta 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 PRVercelA 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.

#EntradaUsado paraNotas
1Nome da empresa (chinês + inglês)COMPANY.nameZh / COMPANY.nameEn em site.ts; rodapé; SEO
2Domínio (ex.: example.com)Em todo lugar — vinculação de bucket, CDN, DNS, SAN do certificadoDEVE 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.
3Diretó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.
4Lista de produtosPRODUCTS[] em site.tsCada produto precisa de nome + descrição bilíngues, URL, cor de destaque hex, enum de ícone.
5Número de registro ICPRodapéO número de 备案 emitido pelo MIIT.
6Diretório de trabalhoRaiz do projetoDeve 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:

  1. Estruturar — copie assets/templates/package.json e assets/templates/astro.config.mjs para a raiz do projeto. Atualize name no package.json e site no astro.config.mjs.
  2. Instalar pacotes — pnpm install.
  3. Instalar a skill do agente Astro — apenas depois que pnpm install for bem-sucedido:
    npx skills add https://github.com/astrolicious/agent-skills --skill astro
    
    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.
  4. 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).
  5. Extrair a marca do SVG do usuário — use assets/templates/BrandMark.astro como 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.
  6. 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.
  7. Verificar localmente — pnpm dev para desenvolver, pnpm build && pnpm preview para 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.

  1. Copiar scripts — copie todo o diretório assets/scripts/ e assets/cdn-payloads/ para scripts/ e scripts/cdn-payloads/ do usuário, respectivamente. Copie assets/templates/deploy.config.mjs para a raiz do projeto e preencha bucket, region, endpoint, cdnDomains.
  2. Substituir espaços reservados nos payloads — {{DOMAIN}}, {{BUCKET}}, {{REGION}} em scripts/cdn-payloads/apex.json e www.json. OriginHost deve ser o próprio domínio, não vazio — os templates estão corretos prontos para uso; se você editá-los, preserve OriginHost. Consulte landmines.md #3.
  3. Criar .env na raiz do projeto (ignorado pelo git):
    VOLC_ACCESS_KEY=AK...
    VOLC_SECRET_KEY=...
    
    O AK/SK da Volcengine precisa de TOSFullAccess, CDNFullAccess, DNSFullAccess, CertificateFullAccess (ou equivalentes de privilégio mínimo).
  4. Verificar se ve está 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:

  1. Poluição de HTTPS_PROXY — SDK TOS + um proxy HTTP local = Protocol "http:" not supported. Cada script em assets/scripts/ já exclui as variáveis de ambiente de proxy no topo — preserve esse preâmbulo se você copiá-los / adaptá-los.
  2. Peculiaridades do SDK TOS — headBucket(string) não headBucket({bucket}); a assinatura de listObjectsType2 quebra quando continuationToken: undefined está na entrada; putObject padrão é privado mesmo em buckets de leitura pública — sempre defina acl: 'public-read'.
  3. TOS não tem um hostname de endpoint de site separado — o mesmo <bucket>.tos-<region>.volces.com retorna JSON de listagem de bucket ou index.html dependendo do cabeçalho Host. Você DEVE (a) chamar putBucketCustomDomain para cada domínio apex/www, E (b) definir OriginHost no payload de AddCdnDomain do CDN para o domínio do usuário (não vazio).
  4. CDN ≠ DCDN para verificação — CDN (内容分发网络) quer host TXT volccdnauth e cdn:CheckCdnDomain (não na CLI ve — use volc-api.mjs). DCDN (全站加速) usa _dnsauth e ve dcdn VerifyDomainOwnership. Misturá-los = loop de verificação interminável.
  5. As alterações de TXT levam ~10 min para propagar no verificador da Volcengine. Acertar o valor na primeira escrita; não fique alterando.
  6. pnpm deploy é um comando interno. Use pnpm run deploy.
  7. 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ça CertificateGetInstanceList primeiro; procure em Result.Instances[] (NÃO InstanceList, NÃO Data) por um cujo San cubra apex + www.

Regras de comportamento

  • Planeje primeiro; confirme antes de operações destrutivas. Antes de createBucket, AddCdnDomain, DeleteRecord em TXT existente, ou BatchDeployCert, 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 / CertificateGetInstanceList primeiro — 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 ve não tiver uma ação, use volc-api.mjs em vez de dizer ao usuário para atualizar ve ou 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 — volccdnauth para CDN, _dnsauth para 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 que curl puro 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 CLI ve.
  • setup-bucket.mjs — bucket idempotente + site + vinculação de domínio personalizado.
  • deploy.mjs — carregador de sincronização TOS com Cache-Control por 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 via cdn:SubmitRefreshTask (assinado por volc-api.mjs, funciona em CI sem ve).

assets/cdn-payloads/ (copie para scripts/cdn-payloads/)

…

[truncado para tradução]

Habilidades Relacionadas