311 lines
14 KiB
Markdown
311 lines
14 KiB
Markdown
---
|
|
name: knowledge
|
|
description: Router de conhecimento unificado. Classifica pergunta por tipo e encaminha para fonte certa (Hub granular/NLM/Context7/CC memory/Supabase/Desk CRM/Git). v3.1.0
|
|
---
|
|
|
|
# /knowledge — Router Unificado v3.1.0
|
|
|
|
> **Reescrita 13-04-2026:** v2.2.0 usava modelo Familia A/B com NLM restrito a "externo".
|
|
> v3.0.0 classifica por tipo de pergunta (8 rotas), adiciona Hub granular
|
|
> (QR/KB/APIs/Manuais/PROCs/Troubleshooting), reclassifica NLM como referencia
|
|
> tecnica primaria, e torna Supabase complementar (nao alicerce).
|
|
> Racional: `plans/atomic-fluttering-flame.md`
|
|
|
|
## Principio
|
|
|
|
**Classificar pergunta → fonte certa.** Nao e fallback linear, nao e "Familia A depois B". E routing directo por tipo.
|
|
|
|
---
|
|
|
|
## Router principal (8 tipos)
|
|
|
|
### 1. Facto rapido (ID, path, comando, credencial)
|
|
|
|
**Sinais:** "qual e o ID de", "path para", "comando para", "porta do"
|
|
|
|
**Fontes (sequencial — parar ao primeiro hit):**
|
|
1. `Grep` em `/media/ealmeida/Dados/Hub/06-Operacoes/Documentacao/Quick-Reference/QR-*.md`
|
|
2. `Grep` em `~/.claude/projects/*/memory/*.md` (cross-projecto)
|
|
|
|
**QR routing por keyword:**
|
|
|
|
| Keywords | Ficheiro |
|
|
|----------|----------|
|
|
| servidor, ip, porta, ssh | QR-Servidores.md |
|
|
| cwp, virtualhost, conta cwp | QR-CWP.md |
|
|
| site cwp, dominio cwp | QR-Sites-CWP.md |
|
|
| easypanel, servico, container | QR-EasyPanel.md |
|
|
| desk, tabela, campo bd, relacao | QR-Desk-BD.md |
|
|
| staff id, project id, category id | QR-IDs-Frequentes.md |
|
|
| moloni, serie, imposto, metodo | QR-Moloni.md |
|
|
| path, directorio, pasta | QR-Paths-Locais.md |
|
|
| backup, rota backup, destino | QR-Backups.md |
|
|
| sync, syncthing, rsync | QR-Sync-Ficheiros.md |
|
|
| script, claudedev | QR-Scripts.md |
|
|
| credencial, password, api key | QR-Credenciais.md |
|
|
| rank math, seo wp-cli | QR-RankMath-WP-CLI.md |
|
|
| capa, cover, podcast imagem | QR-Cover-Generator.md |
|
|
| alurin, desktop, laptop | QR-Alurin-Desktop.md |
|
|
|
|
### 2. Como funciona X / Como fazer Y (referencia tecnica)
|
|
|
|
**Sinais:** "como funciona", "como configurar", "como fazer", "melhores praticas", "tutorial", "deep dive"
|
|
|
|
**Fontes (paralelo — consolidar):**
|
|
1. **Hub Knowledge-Base** — `Grep` em `/media/ealmeida/Dados/Hub/06-Operacoes/Knowledge-Base/*.md` (preferir ficheiro local se existir match directo)
|
|
2. **NotebookLM** — max 2 notebooks por query (routing por tema abaixo)
|
|
3. **Hub Manuais** — `Grep` em `/media/ealmeida/Dados/Hub/06-Operacoes/Documentacao/Manuais/**/*.md`
|
|
4. **Context7** — `resolve-library-id` → `query-docs` (para frameworks/bibliotecas com docs oficiais)
|
|
5. **CC memory cross-projecto** — `Grep` em `~/.claude/projects/*/memory/*.md`
|
|
6. **Supabase** — `search_memories(query, threshold=0.5, limit=5)` [graceful se indisponivel]
|
|
|
|
**Prioridade por tipo de tema:**
|
|
- Framework/biblioteca com docs oficiais (Next.js, React, Laravel...) → **KB local primeiro** + **Context7** + NLM
|
|
- Stack interna (CWP, Perfex, n8n...) → **NLM primeiro** (fonte mais densa para estes) + KB
|
|
- Conceito generico (design patterns, boas praticas...) → **NLM primeiro**
|
|
|
|
**NLM routing por tema (top 15):**
|
|
|
|
| Tema | Notebook | ID |
|
|
|------|----------|----|
|
|
| Claude Code, skills, hooks, plugins | Claude Code | `2876d1fe-5cea-4d98-8140-b0e1a81c6bc4` |
|
|
| CWP, servidor, hosting, virtualhost | CWP | `0ded7bd6-69b3-4c76-b327-452396bf7ea7` |
|
|
| WordPress, WP-CLI, temas, config | WordPress Config CLI | `fb2f26bd-8cb0-4d4c-bafc-4f1ebb51c51d` |
|
|
| Elementor, widgets, templates | WordPress e Elementor | `5be0d1a6-00f2-4cd9-b835-978cb7721601` |
|
|
| Seguranca WP, malware, hardening | Ciberseguranca WordPress | `5f60adfd-2435-4725-8c12-9c11c5f51d75` |
|
|
| Perfex/Desk CRM, modulos, hooks | Perfex CRM | `df4688bb-c2c0-4aba-98c1-38c3b50a353c` |
|
|
| n8n, automacoes, workflows | n8n | `f2c809b8-1cb5-4dd0-aa7e-be2cfb6704d1` |
|
|
| Marketing digital, SEO, ads, funil | Marketing Digital PT | `4c595973-ba10-420a-a3bf-e4389e424ad3` |
|
|
| AI agents, orquestracao, MCPs | AI Agents e Orquestracao | `bc480d68-5835-415e-82bc-4583f36b8c29` |
|
|
| Proxmox, VMs, clustering, HA | Proxmox | `276ccdde-6b95-42a3-ad96-4e64d64c8d52` |
|
|
| Design, branding, visual, automacao | Design Profissional | `b568b13b-0eed-48c9-b513-5c5b7ec0b102` |
|
|
| UI/UX, WCAG, acessibilidade | UI/UX Design | `081ca512-8279-4850-b2b9-dff090267482` |
|
|
| Gestao operacoes, KPIs, agencia | Gestao Operacoes | `f9dc59c2-718b-4b12-bd06-095d4bfa3e34` |
|
|
| Remotion, video programatico | Remotion | `f2b75baa-1ab1-48d3-8f7c-a6a9e516934c` |
|
|
| Obsidian, vault, Claude workflow | Obsidian + Claude | `ebee9fe1-78fd-4f85-8938-f19f3ea32131` |
|
|
| Programacao, padroes, api design | Programacao | `24947ffa-0019-448a-a340-2f4a275d2eb1` |
|
|
| Copywriting, persuasao, texto | Copywriting e Persuasao | `7b8fec17-d34f-4e3f-a8c6-8231e51f6323` |
|
|
| Video, producao, youtube | Producao de Video e Youtube | `058a896e-6c9a-4e51-ae7d-9adb2738bc5f` |
|
|
| WooCommerce, loja, produtos | Documentacao WooCommerce | `bd06acff-4b9d-44aa-b3f7-60434bbd6b49` |
|
|
|
|
> Inventario completo 65 notebooks: `~/.claude/projects/-media-ealmeida-Dados-Hub/memory/notebooklm-inventory.md`
|
|
|
|
**Hub KB: ficheiros locais densos (usar quando match directo):**
|
|
|
|
| Keywords | Ficheiro KB |
|
|
|----------|-------------|
|
|
| next.js, app router, server components | `Next.js 14_15 App Router Deep Dive.md` |
|
|
| php, laravel | `PHP 8+ e Laravel 11_12_ Pesquisa Profunda.md` |
|
|
| core web vitals, ga4, performance | `Core Web Vitals, GA4, Performance Web.md` |
|
|
| n8n, automacao | `Base-Conhecimento-n8n.md` |
|
|
| perfex crm, modulos | `Base-Conhecimento-Perfex-CRM.md` |
|
|
| remotion, video codigo | `Base-Conhecimento-Remotion-Video.md` |
|
|
| ui, ux, design systems | `Base-Conhecimento-UI-UX-Design-Systems.md` |
|
|
| tipografia, cor, web design | `Base-Conhecimento-Web-Design-Tipografia-Cor.md` |
|
|
| youtube, video producao | `Base-Conhecimento-Video-YouTube.md` |
|
|
| openrouter, modelos ai | `OpenRouter-Matrix-v1.1.md` |
|
|
| postfix, email security | `Postfix Email Security Best Practices.md` |
|
|
| wcag, acessibilidade | `Relatório Acessibilidade Web WCAG 2.2.md` |
|
|
| gestao, operacoes, agencia | `Gestao-Operacoes-Agencias-Marketing-Tecnologia.md` |
|
|
|
|
**Context7 para docs oficiais:** usar `resolve-library-id` → `query-docs` quando a pergunta e sobre uma biblioteca/framework com documentacao oficial actualizada (Next.js, React, Tailwind, Laravel, etc). Context7 tem docs mais frescos que NLM.
|
|
|
|
### 3. API / implementacao (endpoint, payload, autenticacao)
|
|
|
|
**Sinais:** "endpoint", "API de", "payload", "autenticacao", "integrar com"
|
|
|
|
**Fontes (sequencial — Read directo do ficheiro):**
|
|
|
|
| Keywords | Ficheiro em `Hub/06-Operacoes/Documentacao/APIs/` |
|
|
|----------|----------------------------------------------------|
|
|
| perfex, desk crm api | Perfex-CRM-API.md |
|
|
| cwp api, cwp endpoint | CWP-API.md |
|
|
| whatsms, sms api | WhatSMS-API.md + WhatSMS-Admin-API.md |
|
|
| paperclip api | Paperclip-API.md |
|
|
| dify api | Dify-API.md |
|
|
| bookstack api | BookStack-API.md |
|
|
| mcp desenvolvimento | MCP-Dev-Manual.md |
|
|
|
|
Se API nao listada → NLM notebook relevante + Context7.
|
|
|
|
### 4. Processo / procedimento (como fazemos X internamente)
|
|
|
|
**Sinais:** "procedimento", "como fazemos", "PROC", "workflow interno", "passo-a-passo"
|
|
|
|
**Fontes:**
|
|
1. `Grep` em `/media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/**/*.md` (38 PROCs)
|
|
2. `Grep` em `/media/ealmeida/Dados/Hub/06-Operacoes/Documentacao/Manuais/**/*.md`
|
|
|
|
**Departamentos PROC:**
|
|
|
|
| Tema | Pasta |
|
|
|------|-------|
|
|
| Comercial, CRM, catalogo | D1-Comercial/ |
|
|
| Suporte, tickets | D2-Suporte/ |
|
|
| Contabilidade, facturas | D3-Contabilidade/ |
|
|
| RH | D4-RH/ |
|
|
| Design | D5-Design/ |
|
|
| Marketing, conteudo | D6-Marketing/ |
|
|
| Tecnologia, MCP, Claude, infra | D7-Tecnologia/ |
|
|
| Multi-departamental | Cross-Departamental/ |
|
|
|
|
### 5. Troubleshooting (erro, problema, nao funciona)
|
|
|
|
**Sinais:** "erro", "nao funciona", "problema com", "fix para", "troubleshoot"
|
|
|
|
**Fontes (paralelo):**
|
|
1. `Grep` em `/media/ealmeida/Dados/Hub/06-Operacoes/Documentacao/Troubleshooting/*.md`
|
|
2. CC memory cross-projecto — `Grep` em `~/.claude/projects/*/memory/*.md`
|
|
3. Supabase — `search_memories(query, threshold=0.5, limit=5)` [graceful]
|
|
4. NLM notebook relevante (contexto tecnico)
|
|
|
|
### 6. Estado actual (quem, quando, quanto, aberto/fechado)
|
|
|
|
**Sinais:** nome de cliente, "#" + numero, "tarefas abertas", "horas", "facturas", "tickets"
|
|
|
|
**Fontes:** Directo ao **Desk CRM** via MCP:
|
|
- `get_tasks`, `get_projects`, `get_tickets`, `get_customers`
|
|
- `get_timesheets`, `get_invoices`, `get_estimates`
|
|
|
|
**NLM e Hub NAO entram** — nao veem estado vivo.
|
|
|
|
### 7. Decisao / historico (porque fizemos X, quando decidimos Y)
|
|
|
|
**Sinais:** "decisao", "porque fizemos", "historico de", "quando decidimos", "ultima vez que"
|
|
|
|
**Fontes (paralelo):**
|
|
1. **Supabase** — `search_memories(query, threshold=0.5, limit=8)` [graceful]
|
|
2. **CC memory cross-projecto** — `Grep` em `~/.claude/projects/*/memory/*.md`
|
|
3. **Desk CRM discussions** — `get_discussion_comments` (#31 worklogs, #32 reflexoes, #33 accoes)
|
|
4. **Git log** — `git log --oneline --grep="keyword"` nos repos relevantes
|
|
|
|
### 8. Codigo / projecto (o que mudou, como esta o repo)
|
|
|
|
**Sinais:** "changelog", "ultimo commit", "o que mudou em", "estado do repo"
|
|
|
|
**Fontes:**
|
|
1. `Read` CHANGELOG.md do projecto
|
|
2. `git log` do repo
|
|
3. CC memory do projecto especifico
|
|
|
|
---
|
|
|
|
## Classificador de pergunta (heuristica)
|
|
|
|
| Sinal | Tipo |
|
|
|-------|------|
|
|
| ID, path, porta, comando concreto | **1. Facto rapido** |
|
|
| "como funciona", "como configurar", "melhores praticas" | **2. Referencia tecnica** |
|
|
| "endpoint", "API", "payload" | **3. API** |
|
|
| "procedimento", "PROC", "como fazemos internamente" | **4. Processo** |
|
|
| "erro", "nao funciona", "problema" | **5. Troubleshooting** |
|
|
| Cliente, tarefa #N, ticket, factura, horas | **6. Estado actual** |
|
|
| "decisao", "porque", "historico", "ultima vez" | **7. Decisao/historico** |
|
|
| "changelog", "commit", "repo" | **8. Codigo** |
|
|
| **Ambiguo** | **Perguntar ao utilizador** |
|
|
|
|
---
|
|
|
|
## Formato de resposta
|
|
|
|
```markdown
|
|
## [pergunta]
|
|
|
|
**[Fonte 1]:** [excerto] _(origem especifica)_
|
|
**[Fonte 2]:** [excerto] _(origem especifica)_
|
|
|
|
**Sintese:** [consolidacao em 2-3 frases citando as fontes mais fortes]
|
|
```
|
|
|
|
Origens possiveis: `QR:ficheiro`, `NLM:notebook`, `KB:ficheiro`, `API:ficheiro`, `PROC:codigo`, `Manual:ficheiro`, `Troubleshooting:ficheiro`, `memory/projecto:ficheiro`, `Supabase:id`, `Desk CRM:task #N`, `Git:commit`
|
|
|
|
**Regra:** nunca responder sem citar fonte. Se 0 fontes, dizer explicitamente.
|
|
|
|
---
|
|
|
|
## Comandos
|
|
|
|
| Comando | Uso |
|
|
|---------|-----|
|
|
| `/knowledge [pergunta]` | Router automatico por tipo |
|
|
| `/kb [pergunta]` | Alias curto |
|
|
| `/kb-save [conteudo]` | Guardar na fonte adequada (ver abaixo) |
|
|
| `/kb-gaps` | Listar lacunas detectadas em Supabase |
|
|
|
|
---
|
|
|
|
## Gravar conhecimento (/kb-save)
|
|
|
|
| Tipo | Destino | Tool |
|
|
|------|---------|------|
|
|
| Decisao / solucao tecnica / workaround | Supabase | `save_memory` com tags `[tipo, dominio, projecto?, data]` |
|
|
| Feedback / regra estavel | CC memory | `Write` em `~/.claude/projects/*/memory/` |
|
|
| Procedimento operacional | Hub PROCs | `Write` PROC-*.md |
|
|
| Referencia rapida (ID, path) | Hub QR | `Edit` QR-*.md |
|
|
| Conhecimento externo | NotebookLM | `source_add` no notebook adequado |
|
|
|
|
---
|
|
|
|
## Deteccao de lacunas
|
|
|
|
Quando 0 hits uteis em todas as fontes consultadas para o tipo:
|
|
|
|
```javascript
|
|
mcp__memory-supabase__save_memory({
|
|
content: `LACUNA: "${query}" — tipo ${tipo}, 0 hits`,
|
|
tags: ["lacuna-kb", tipo, dominio]
|
|
});
|
|
```
|
|
|
|
Sugerir accao: criar PROC, actualizar QR, adicionar fonte a NLM, guardar em Supabase.
|
|
|
|
---
|
|
|
|
## Regras operacionais
|
|
|
|
1. **Classificar primeiro, consultar depois.** Nao despejar todas as fontes para todas as perguntas.
|
|
2. **Paralelismo obrigatorio** dentro de cada tipo quando ha multiplas fontes.
|
|
3. **Grep cross-projecto obrigatorio** para tipos 2, 5, 7 — `~/.claude/projects/*/memory/*.md`.
|
|
4. **Nunca responder sem citar fonte.**
|
|
5. **Max 2 notebooks NLM** por query (performance).
|
|
6. **Supabase sempre graceful** — se indisponivel ou 0 resultados, continuar com outras fontes.
|
|
7. **Estado presente = Desk CRM directo** — nunca NLM/Hub para tarefas/facturas/tickets.
|
|
8. **PT-PT sempre.**
|
|
|
|
---
|
|
|
|
## Anti-patterns
|
|
|
|
- Consultar NLM para "quantas tarefas abertas tem o projecto X" (estado vivo → Desk CRM)
|
|
- Fazer grep generico em `Hub/**/*.md` quando a pergunta e claramente sobre um QR especifico
|
|
- Consultar Supabase como unica fonte (usar como complemento, nao alicerce)
|
|
- Classificar "como funciona o nosso router /knowledge" como referencia externa (e interno → CC memory + Hub)
|
|
- Ignorar CC memory cross-projecto (harness so carrega cwd)
|
|
- Disparar 5 fontes para um facto rapido que esta num QR (sequencial, parar ao hit)
|
|
|
|
---
|
|
|
|
## Referencias
|
|
|
|
- `~/.claude/plans/atomic-fluttering-flame.md` — plano RAG-System completo
|
|
- `~/.claude/projects/-media-ealmeida-Dados-Hub/memory/feedback_knowledge-router-arquitectura.md` — decisao arquitectural
|
|
- `~/.claude/projects/-media-ealmeida-Dados-Hub/memory/notebooklm-inventory.md` — inventario 65 notebooks NLM
|
|
|
|
---
|
|
|
|
## Healing log
|
|
|
|
```jsonl
|
|
{"date":"2026-04-08","issue":"v2.0.0 tratava NotebookLM como fonte primaria para tudo","fix":"v2.1.0 router Familia A/B — NotebookLM so para externo","source":"user"}
|
|
{"date":"2026-04-08","issue":"v2.1.0 assumia FastMCP file-based (11 tools lightrag_*)","fix":"v2.1.1 restaurado LightRAG-HKU 17 tools","source":"user"}
|
|
{"date":"2026-04-13","issue":"LightRAG com 0 docs, servico sem utilidade","fix":"v2.2.0 removido LightRAG da Familia A","source":"user"}
|
|
{"date":"2026-04-08","issue":"memoria CC fragmentada por projecto","fix":"grep cross-projecto obrigatorio","source":"user"}
|
|
{"date":"2026-04-13","issue":"Supabase degradado (stats/paginacao/embeddings raw)","fix":"MCP reparado — stats, paginacao e sanitize embeddings corrigidos. 6 registos com credentials eliminados","source":"fase-2"}
|
|
{"date":"2026-04-13","issue":"v2.2.0 modelo A/B subestimava Hub e NLM para queries operacionais","fix":"v3.0.0 router por tipo (8 rotas), Hub granular (QR/KB/APIs/Manuais/PROCs/Troubleshooting), NLM referencia tecnica primaria, Supabase complementar","source":"plano RAG-System"}
|
|
{"date":"2026-04-13","issue":"v3.0.0 nao tinha routing para frameworks (Next.js foi ao notebook errado), KB local subutilizado","fix":"v3.1.0 prioridade por tipo de tema (KB local > Context7 > NLM para frameworks), 13 ficheiros KB mapeados, 4 notebooks NLM adicionados, Context7 como fonte para docs oficiais","source":"testes fase 5"}
|
|
```
|
|
|
|
---
|
|
|
|
**v3.1.0** | 13-04-2026 | KB local mapeado (13 ficheiros), Context7 para docs oficiais, prioridade por tipo de tema, 19 notebooks NLM
|