API de Imagens para Conta Oficial do WeChat
Usa exclusivamente a interface oficial api.weixin.qq.com para criar e verificar rascunhos de mensagens de imagem. Não inicia navegador, não chama interfaces de publicação, transmissão ou exclusão, e não oferece fallback via RPA.
Ambiente
Requer Windows e PowerShell 7.2+. O AppSecret é criptografado usando DPAPI do usuário atual do Windows, salvo por padrão em $env:CODEX_HOME\secrets; quando CODEX_HOME não está definido, usa $env:USERPROFILE\.codex\secrets. As requisições de rede são feitas dentro do processo PowerShell, sem passar o access token para comandos externos.
Entrada e Validação Offline
Leia completamente o references/package-contract.md antes de executar. O diretório de materiais deve conter image-post.json e 1 a 20 imagens; o campo account deve ser preenchido explicitamente, e o campo de comentários não pode ficar vazio.
Primeiro localize o Skill, depois faça a validação offline:
$codexHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $env:USERPROFILE '.codex' }
$skill = Join-Path $codexHome 'skills\wechat-image-api'
& (Join-Path $skill 'scripts\Test-WeChatImagePackage.ps1') -InputFolder 'D:\PastaDeMateriaisDeImagem'
Quando precisar de um exemplo completo, gere e valide em um novo diretório que ainda não contenha arquivos de exemplo:
& (Join-Path $skill 'scripts\New-WeChatImagePackageExample.ps1') -OutputFolder 'D:\ExemploDeImagem'
Configuração Inicial
Dois Skills da API do WeChat podem compartilhar a mesma credencial DPAPI. Se a credencial não existir, não permita que o usuário cole o AppSecret no chat; execute a configuração interativa local:
& (Join-Path $skill 'scripts\Set-WeChatOfficialAccountCredential.ps1')
& (Join-Path $skill 'scripts\Test-WeChatOfficialAccountApi.ps1')
O segundo comando verifica AppID, AppSecret, permissão de rascunho e lista de IPs permitidos. O campo account do pacote de materiais deve corresponder exatamente ao nome da conta oficial salvo durante a configuração.
Se o WeChat retornar 40164 invalid ip, pare imediatamente e informe ao usuário o IP público de saída contido no erro, lembrando-o de adicioná-lo em "Configurações e Desenvolvimento → Gerenciamento de Interface de Desenvolvimento → Lista de IPs Permitidos". Após confirmação do usuário, tente novamente apenas a mesma API oficial; é proibido usar navegador, RPA, perfil de cookie ou qualquer outro canal de publicação.
Criar e Verificar Rascunho
Execute apenas quando o usuário solicitar explicitamente a escrita de um rascunho:
& (Join-Path $skill 'scripts\Publish-WeChatImageDraft.ps1') -InputFolder 'D:\PastaDeMateriaisDeImagem'
O script faz upload de cada imagem para material/add_material, depois usa draft/add para criar o rascunho newspic; a primeira imagem é usada pelo WeChat como capa. Por fim, usa draft/get para ler e verificar conta, título, corpo, ordem das imagens, configuração de comentários e media_id.
Idempotência e Limites de Exceção
- Cada diretório de materiais usa um lock exclusivo; o mesmo diretório não pode ser executado concorrentemente.
- Os checkpoints avançam apenas após confirmação do recebimento de
media_id; quando um ID de rascunho já foi registrado, a execução repetida apenas lê e verifica, não recria o rascunho. - Se a rede ou o processo for interrompido durante o upload de imagem ou na fase de submissão
draft/add, o resultado pode ser indeterminado. A execução subsequente deve parar, sem tentativas automáticas; primeiro verifique manualmente o banco de materiais ou a caixa de rascunhos, depois continue com um novo diretório. - Se a impressão digital do material mudar, mas houver um checkpoint antigo, pare e não limpe o estado silenciosamente.
- O estado e os comprovantes usam substituição atômica de arquivos temporários no mesmo diretório, para evitar JSONs truncados.
- Somente quando todos os campos são verificados com sucesso via
draft/get, reporte "Rascunho criado e verificado com sucesso"; não reporte "Publicado". - O comprovante é gravado em
wechat-image-api-receipt.json. Se qualquer API oficial falhar, reporte imediatamente; este Skill não tem fallback via navegador/RPA.