eiway112/agent-wiki

Fluxo de Trabalho de Operação da Base de Conhecimento (Padrão LLM Wiki)

Posicionamento e Aplicabilidade

Este Skill é uma metodologia independente de plataforma: transformar conhecimento externo em regras de comportamento que o agente pode invocar durante a execução (Memória/Normas/Skill). A base de conhecimento não é uma pasta de favoritos, é um motor de crescimento de capacidade do agente — cada conhecimento inserido deve passar por destilação, e o único critério para julgar valor é: ele pode alterar diretamente a decisão de comportamento do agente em um cenário específico?

• Se o projeto já possui seu próprio arquivo de normas da base de conhecimento (ex.: normas_do_projeto.md), este arquivo é a referência autoritativa; em caso de conflito, prevalecem as normas do projeto
• Ao aplicar em diferentes plataformas/projetos, siga a arquitetura e o fluxo de três camadas deste Skill; os nomes dos diretórios podem ser localizados; o diretório examples/ deste repositório fornece amostras mínimas executáveis

Arquitetura de Três Camadas

Camada	Diretório Recomendado	Natureza
Raw Sources	coleta_original/ (artigos/discussões/vídeos)	Somente leitura, imutável após coleta
The Wiki	base_de_conhecimento/ (indice.md, experiencias_de_coleta.md, log_de_operacoes.md)	Conteúdo derivado mantido pelo LLM
The Schema	normas_do_projeto.md + arquivos_de_programa/configuracao/	Mantido em conjunto por humanos e LLM

Princípio chave: os arquivos originais permanecem sempre em Raw Sources, não são movidos para o Wiki; após a validação, estabelecer uma referência no indice.md é considerado "inserido".

Separação de Papéis (Obrigatória)

Papel	Entidade	Responsabilidade	Proibições
Planner	Humano	Definir alvo de coleta, definir contrato de valor, orientar direção da análise	Não operar arquivos diretamente
Generator	LLM	Executar coleta, complementar metadados, escrever resumo, manter índice e log	Proibido autoavaliar a qualidade da saída
Evaluator	Ferramenta de validação (ex.: scripts/validate.py)	Validar formato, codificação, metadados, referências cruzadas independentemente	Não participar da geração

Regra central: o modelo não pode se dar nota. A avaliação de valor é registrada pelo Generator no log de operações; a aprovação ou não na validação é decidida pelo Evaluator; quando o humano discorda, prevalece o julgamento humano. Se o projeto não possui ferramenta de validação, siga a verificação item a item das seis dimensões do Lint manualmente, mas a conclusão ainda não pode ser auto-atestada pelo gerador.

Ingest (Ingestão)

Copie esta lista de verificação para acompanhar o progresso:

- [ ] 1. Contrato de valor antes da coleta (três perguntas)
- [ ] 2. Coletar e complementar metadados
- [ ] 3. Ler conteúdo, extrair informações chave
- [ ] 4. Julgamento de valor (se não atender, interromper)
- [ ] 5. Atualizar indice.md (resumo + referências cruzadas)
- [ ] 6. Adicionar ao log de operações
- [ ] 7. Avaliar destilação e marcar status de implementação
- [ ] 8. Commit Git

Passo 1 · Contrato de valor antes da coleta — Antes de agir, responda a três perguntas e registre:

1. Que problema este artigo resolve? Qual é a relação com o conhecimento existente? (complementar/contrastar/estender)
2. Sob quais condições é considerado "valioso"? Pelo menos uma deve ser atendida: introduzir novo conceito, fornecer perspectiva de comparação, ter referência prática direta
3. Em qual nível do indice.md ele se encaixa? (Teoria fundamental/Paradigma de arquitetura/Prática de engenharia/Ferramentas e recursos/Dinâmica da comunidade)

Passo 2 · Coleta e Metadados — Use o mecanismo de coleta da plataforma atual para obter o texto original (veja "Abstração do Mecanismo de Coleta"), armazene no subdiretório correspondente de Raw Sources, nome do arquivo seguindo {fonte}_{topico}_{data}.{ext} (ex.: github_karpathy_llm_wiki_20260630.md). Campos obrigatórios de metadados: URL, Data de coleta, Comando de coleta; campos recomendados: Por, Site, Publicado, Fonte original. O mecanismo de coleta geralmente só extrai alguns campos automaticamente; o restante deve ser complementado.

Passo 4 · Julgamento de valor (incluindo interrupção) — Avalie em relação ao contrato do Passo 1. Se claramente não atender a nenhuma condição de valor (conteúdo vazio, repetição grave, irrelevante para o posicionamento da base), registre explicitamente o motivo da interrupção no log de operações e saia, não force a conclusão do fluxo de inserção.

Passo 6 · Formato do log de operações: ## [data] ingest | título (append-only).

Passo 7 · Avaliação de destilação — Este item contém regras atômicas que podem orientar diretamente o comportamento do agente?

Marcação	Significado	Ação
🟢 Implementado	Possui regra atômica executável	Extrair e escrever em Memória/Normas/Skill, anotar no item do indice.md o título da Memória
🟡 Parcialmente implementado	Parcialmente	Anotar o que foi implementado e o que não foi, com motivo
🔵 Referência de índice	Nenhuma regra executável	Descrever brevemente o motivo no log de operações

Padrão de destilação: a regra deve ser capaz de alterar a decisão de comportamento do agente em um cenário específico, não apenas uma ideia abstrata ou informação de referência.

Adaptação de destilação entre plataformas: No Qoder, o produto da destilação é escrito no sistema de Memória (metodologia→task_experience, armadilhas→common_pitfalls_experience, decisão de arquitetura→important_decision_experience, etc.); em outras plataformas de agente, mapeie para o mecanismo de memória persistente/regras de comportamento da própria plataforma, mantendo o mesmo critério de julgamento e as três marcações de cor.

Passo 8: git add -A && git commit -m "ingest: título".

Query (Consulta)

1. Primeiro, leia base_de_conhecimento/indice.md para localizar a página relevante
2. Leia o(s) arquivo(s) relacionado(s) em profundidade, sintetize a resposta
3. Boas respostas são retornadas como nova página — faça a própria exploração gerar juros compostos
4. Adicione ao log de operações: ## [data] query | pergunta
5. Após criar nova página: git add -A && git commit -m "query: pergunta"

Lint (Auditoria)

Priorize executar a ferramenta de validação do projeto (este repositório fornece um exemplo sem dependências: python scripts/validate.py <raiz_da_base_de_conhecimento>); a decisão da ferramenta prevalece sobre o julgamento manual. Sem ferramenta, siga a verificação item a item das seis dimensões:

1. Integridade dos metadados — campos obrigatórios (URL, Data de coleta, Comando de coleta) estão presentes?
2. Correção de codificação — codificação dupla, BOM, caractere de substituição (U+FFFD)
3. Conformidade de formato — Markdown deve começar com H1 e metadados separados do corpo por ---; JSON deve ter campo _metadata
4. Convenção de nomenclatura — segue o padrão {fonte}_{topico}_{data}?
5. Referências cruzadas — os links no indice.md apontam para arquivos reais? Detecção de páginas órfãs
6. Validação de fonte — a URL pertence à lista branca de fontes?

Adicione ao log de operações: ## [data] lint | escopo de verificação; se houver correção, git commit -m "lint: escopo de verificação".

Harness decrescente: As ferramentas e o fluxo são mecanismos auxiliares para compensar as fraquezas do modelo, e devem diminuir monotonamente à medida que o modelo evolui. A cada Lint, examine: quais regras de validação não são mais acionadas? Quais etapas o modelo já internalizou? Remova-as.

Abstração do Mecanismo de Coleta (Adaptação entre Plataformas)

O fluxo central não está vinculado a nenhuma ferramenta de coleta; o mecanismo de coleta é escolhido conforme a disponibilidade da plataforma:

Ambiente da plataforma	Método de coleta
Windows + navegador Edge	AutoCLI: autocli read "URL" -f markdown -o "caminho de saída", extrai automaticamente Por/Site/URL; atenção: no PowerShell, informações de progresso em stderr podem causar ExitCode=1 falso, saída contendo "Saved to ..." indica sucesso
Plataforma de agente com capacidade de leitura de páginas web	Ferramenta de leitura web (WebFetch, etc.) captura diretamente e converte para Markdown
Fontes de API pública	Hacker News, Lobsters, etc. sem necessidade de navegador, solicitação direta via API
Sem ferramenta de rede	Usuário cola o texto original, salva manualmente e registra honestamente o Comando de coleta como "cola manual"

Independentemente do mecanismo, os requisitos de metadados, validação e destilação após a inserção são completamente idênticos. O campo Comando de coleta deve registrar honestamente o mecanismo e o comando realmente usados (incluindo downgrade), garantindo reprodutibilidade.

Consulta Rápida de Convenções

• Nome de arquivo: {fonte}_{topico}_{data}.{ext}, fonte em minúsculas
• Log de operações: append-only, formato ## [data] {ingest|query|lint} | descrição breve
• Mensagem de commit: {ingest|query|lint}: {descrição breve}; inicialização: init: baseline da base de conhecimento
• Lições aprendidas estruturadas são registradas em experiencias_de_coleta.md, não misturadas com o log de operações