LinLin00000000/aiops-vault-template

Skill Companheiro do Vault AIOps

Este skill é uma camada de procedimento. Ele não contém os ativos atuais do usuário. Os fatos atuais vivem no vault AIOps local, normalmente $AIOPS_ROOT ou ~/ai-ops.

Contrato de fonte de verdade

Use esta divisão:

• README.md: regras locais estáveis, papéis dos arquivos, limites de segurança e convenções específicas do projeto.
• resources.md: estado atual que deve ser confiável agora.
• maintenance-log.jsonl: histórico somente de acréscimos de decisões, manutenção, verificações, incidentes e correções.
• secrets-location.md: nomes de segredos, locais de armazenamento, notas de acesso/rotação; nunca valores secretos.
• services/<serviço>/service-card.md: runbooks e detalhes por serviço quando o arquivo de recursos central ficar muito grande.
• scripts/aiops.py: interface de comando de baixo token sobre o vault.

Não inferir a infraestrutura atual a partir deste skill. Leia o vault e inspecione o estado ativo onde for seguro.

Ordem de leitura padrão

1. Resolver o caminho do vault: $AIOPS_ROOT se definido, caso contrário ~/ai-ops.
2. Ler o README.md do vault local primeiro se a tarefa puder alterar arquivos, serviços, exposição, credenciais ou backups.
3. Executar a camada de comando antes de leituras completas:
   • python3 "$AIOPS_ROOT/scripts/aiops.py" index
   • python3 "$AIOPS_ROOT/scripts/aiops.py" resources --section "<seção>"
   • python3 "$AIOPS_ROOT/scripts/aiops.py" service "<nome>"
   • python3 "$AIOPS_ROOT/scripts/aiops.py" host "<nome>"
   • python3 "$AIOPS_ROOT/scripts/aiops.py" log --tail 20 --summary
4. Ler resources.md completo, cartões de serviço ou linhas de log apenas quando a saída segmentada for insuficiente.
5. Usar o histórico da sessão apenas quando o estado ativo e os documentos do vault não puderem responder à pergunta.

Limites de segurança

• Não ler, imprimir, copiar ou armazenar valores secretos. secrets-location.md é metadado, não um despejo de segredos.
• Não escrever segredos em resources.md, logs, cartões de serviço, prompts, comentários de issues, commits ou resumos de chat.
• Confirmar antes de operações irreversíveis ou de alta exposição: deletar, sobrescrever, rotacionar, restaurar, abrir portas públicas, alterar DNS, migrar dados, desabilitar backups ou tocar em recursos de terceiros/amigos.
• Manter pools de recursos explícitos. Não operar em infraestrutura de terceiros ou de amigos a menos que o usuário autorize especificamente esse alvo.
• Preferir menor exposição: localhost por trás de proxy reverso ou rede privada para caminhos administrativos; HTTPS público apenas quando pretendido e autenticado.

Fluxo de manutenção

1. Classificar o alvo: host, serviço, domínio/DNS, proxy reverso, dados/backup, localização de segredo, automação ou o próprio vault.
2. Identificar o pool de recursos e o limite de autoridade.
3. Carregar o contexto atual mínimo através do aiops.py e cartões de serviço.
4. Inspecionar estado ativo com comandos seguros quando necessário.
5. Planejar a menor ação reversível e destacar passos de alto risco.
6. Executar com privilégio mínimo.
7. Verificar com saída real do lado consumidor: health check, log, requisição HTTP, systemctl, docker ps, listagem de backup ou equivalente.
8. Atualizar a camada correta:
   • fatos atuais -> resources.md ou cartão de serviço;
   • histórico importante -> um objeto maintenance-log.jsonl anexado;
   • locais de segredos -> secrets-location.md sem valores;
   • detalhes locais do serviço -> README/cartão do serviço.
9. Se a alteração melhorar o fluxo de trabalho/ferramentas AIOps reutilizáveis em vez de apenas fatos locais privados, sincronizar a parte genérica para o repositório de template em ~/projects/aiops-vault-template, executar seus testes/verificações, então commitar e fazer push para que consumidores downstream do AIOS Kit recebam a melhoria. Nunca copiar recursos privados, logs ou segredos para o template público.
10. Executar python3 "$AIOPS_ROOT/scripts/aiops.py" check após alterações no vault.
11. Relatar arquivos alterados, comandos, verificação, itens ignorados/bloqueados e acompanhamentos.

Regras de write-back

• O estado atual pertence a resources.md ou a um cartão de serviço, não apenas ao log de histórico.
• O histórico pertence a maintenance-log.jsonl, um objeto JSON válido por linha.
• Correções devem ser novas entradas do tipo correction ou supersede; não reescrever histórico a menos que o usuário solicite uma migração.
• Evitar duplicar o mesmo fato entre README, resources, cartões de serviço e logs. Escolher a camada proprietária.
• Evidências brutas grandes devem viver em evidence/ ou fora do vault com uma referência de caminho.

Lista de verificação

Antes de finalizar:

• python3 "$AIOPS_ROOT/scripts/aiops.py" check passa ou as falhas são explicadas.
• Arquivos JSONL podem ser analisados.
• Nenhum valor secreto óbvio foi adicionado.
• Alterações de estado atual não estão apenas no log de manutenção.
• Afirmações na resposta são suportadas por arquivos do vault ou saída de comando ativa.
• Qualquer ação de alto risco foi confirmada ou explicitamente deixada como um passo proposto.

Se o vault estiver ausente

Se nenhum vault AIOps existir e o usuário quiser um, instalar o repositório de template ou criar a estrutura mínima:

ai-ops/
  README.md
  resources.md
  maintenance-log.jsonl
  maintenance-log.schema.md
  secrets-location.md        # privado, ignorado pelo Git
  secrets-location.example.md
  scripts/aiops.py

Então executar python3 scripts/aiops.py check.