From c5340517746461f6b1e4a112b2c8a697fc5feb41 Mon Sep 17 00:00:00 2001 From: Emanuel Almeida Date: Wed, 8 Apr 2026 17:17:17 +0100 Subject: [PATCH] =?UTF-8?q?feat(gestao/knowledge):=20v2.1.1=20=E2=80=94=20?= =?UTF-8?q?17=20tools=20LightRAG-HKU=20reais?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Actualização derivada da restauração do LightRAG-HKU no gateway (ver Hub/04-Stack/CHANGELOG.md sessão 3 extensão). A v2.1.0 tinha sido escrita assumindo FastMCP file-based com 11 tools (lightrag_query, lightrag_stats, etc) porque outra sessão tinha migrado temporariamente o backend. Essa migração foi revertida e o stack voltou ao LightRAG-HKU 1.4.13 completo com 17 tools originais. Mudanças: - Router Família A agora usa mcp__lightrag__query_document (não lightrag_query) - Documentada a lista completa de 17 tools MCP (query, insert, pipeline, graph edit) - Referência à UI rag.descomplicar.pt/webui - PG storage notado (331 docs workspace default) - Graceful fallback para mcp__memory-supabase__ quando MCP indisponível Co-Authored-By: Claude Opus 4.6 (1M context) --- gestao/skills/knowledge/SKILL.md | 42 ++++++++++++++++++++++++++------ 1 file changed, 34 insertions(+), 8 deletions(-) diff --git a/gestao/skills/knowledge/SKILL.md b/gestao/skills/knowledge/SKILL.md index a6bb192..4a308b5 100644 --- a/gestao/skills/knowledge/SKILL.md +++ b/gestao/skills/knowledge/SKILL.md @@ -1,9 +1,9 @@ --- name: knowledge -description: Router de conhecimento Família A/B. Família A (operacional interna) consultada em paralelo para qualquer pergunta sobre processos, projectos, decisões, histórico. Família B (NotebookLM externa) só para conhecimento conceptual/teórico. v2.1.0 +description: Router de conhecimento Família A/B. Família A (operacional interna) consultada em paralelo para qualquer pergunta sobre processos, projectos, decisões, histórico. Família B (NotebookLM externa) só para conhecimento conceptual/teórico. v2.1.1 --- -# /knowledge — Router Família A/B v2.1.0 +# /knowledge — Router Família A/B v2.1.1 > **Correcção arquitectural 08-04-2026:** a v2.0.0 tratava NotebookLM como fonte primária. Isso estava errado — NotebookLM não vê operações, não vê estado real, só tem ebooks e transcripts. Em `~/.claude/projects/-media-ealmeida-Dados-Hub/memory/feedback_knowledge-router-arquitectura.md` está o racional completo. @@ -19,7 +19,7 @@ description: Router de conhecimento Família A/B. Família A (operacional intern | Fonte | Tool | Conteúdo | |-------|------|----------| -| **LightRAG** | `mcp__lightrag__lightrag_query` (modo `hybrid`) | Knowledge graph interno. 337+ entidades. File-based em gateway (`/root/mcp-lightrag/data/`). **FastMCP directo** — tools reais: `lightrag_query`, `lightrag_insert`, `lightrag_stats`, `lightrag_get_entity`, `lightrag_get_graph`. | +| **LightRAG** | `mcp__lightrag__query_document` (modo `hybrid`) | Knowledge graph interno. **LightRAG-HKU 1.4.13** completo — REST API + WebUI em `rag.descomplicar.pt` + PG storage (workspace `default`) + AGE graph extension. **17 tools MCP disponíveis** (ver lista abaixo). 331 docs no Postgres (135 processed + 194 pending + 2 processing + 6 failed). | | **memory-supabase** | `mcp__memory-supabase__search_memories(query, threshold=0.7, limit=10)` | Memórias persistentes cross-sessão com embeddings. Decisões, contexto, lacunas anteriores. | | **Memória CC cross-projecto** | `Grep` recursivo em `~/.claude/projects/*/memory/*.md` | **101 ficheiros em 34 projectos (~261kB).** Harness só carrega automaticamente a memória do `cwd` — este grep é **obrigatório** para não perder contexto de outros projectos. | | **Obsidian / Hub** | `Grep` em `/media/ealmeida/Dados/Hub/**/*.md` | PROCs, QRs, INDEX, frontmatter, procedimentos, histórico. | @@ -30,8 +30,8 @@ description: Router de conhecimento Família A/B. Família A (operacional intern ``` 1. Classificar pergunta como operacional (default para queries internas) 2. Disparar em PARALELO (mesma mensagem, vários tool calls): - - lightrag_query(query, mode="hybrid") - - search_memories(query, threshold=0.65, limit=8) + - mcp__lightrag__query_document(query, mode="hybrid") + - mcp__memory-supabase__search_memories(query, threshold=0.65, limit=8) [graceful se MCP indisponível] - Grep ~/.claude/projects/*/memory/*.md - Grep Hub/**/*.md (limitar a pastas relevantes quando possível) - Desk CRM search (se query menciona cliente/projecto/tarefa) @@ -39,6 +39,31 @@ description: Router de conhecimento Família A/B. Família A (operacional intern 4. Se Família A insuficiente → perguntar ao utilizador ou escalar para Família B ``` +### 17 tools MCP LightRAG-HKU disponíveis + +**Consulta / leitura:** +- `query_document(query, mode)` — RAG query. **Principal para router.** Modos: `naive`, `local`, `global`, `hybrid`, `mix` (default: `hybrid`). +- `get_documents()` — lista docs com status (processed/pending/processing/failed) e metadata. +- `get_pipeline_status()` — estado do pipeline de ingestão (busy, job, batchs). +- `get_graph_labels()` — entity types no knowledge graph. +- `check_lightrag_health()` — health check do server. + +**Ingestão:** +- `insert_document(text)` — insere texto único, extrai entidades + relações. +- `insert_batch(texts[])` — batch de textos. +- `insert_file(path)` — insere ficheiro local. +- `upload_document(file)` — upload binário. +- `scan_for_new_documents()` — trigger scan do `INPUT_DIR` (`/root/mcp-lightrag/inbox/`). + +**Edição de grafo:** +- `create_entities`, `edit_entities`, `delete_by_entities`, `merge_entities` +- `create_relations`, `edit_relations` +- `delete_by_doc_ids` — remove doc + entidades órfãs. + +**UI web:** `https://rag.descomplicar.pt/webui/` com autenticação (`AUTH_ACCOUNTS` no `.env` do gateway). + +**Nota sobre graceful fallback:** as tools `mcp__*` podem estar indisponíveis em sessões específicas por razões de auto-discovery do harness. Se a chamada falhar com "No such tool available", continuar o paralelismo com as outras fontes e reportar a lacuna no output final. + ### Formato de resposta Família A ```markdown @@ -204,7 +229,7 @@ Router inverso por tipo: | Tipo | Destino | Tool | |---|---|---| | Decisão / contexto / lacuna | memory-supabase | `mcp__memory-supabase__save_memory` com tags | -| Entidade / relação / doc interno | LightRAG | `mcp__lightrag__lightrag_insert(content, source)` | +| Entidade / relação / doc interno | LightRAG | `mcp__lightrag__insert_document(text)` ou `insert_batch(texts)` | | Procedimento operacional | Hub/06-Operacoes/Procedimentos/ | `Write` PROC-*.md | | Conhecimento externo | NotebookLM notebook adequado | `mcp__notebooklm-mcp__source_add` | @@ -262,10 +287,11 @@ Depois sugerir acção: criar PROC, adicionar ao LightRAG, adicionar fonte ao no ```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":"tools MCP lightrag assumidas (get_pipeline_status, query_document) nao existem","fix":"tools reais sao lightrag_query, lightrag_stats, lightrag_get_entity — FastMCP file-based","source":"auto"} +{"date":"2026-04-08","issue":"v2.1.0 assumia FastMCP file-based (11 tools lightrag_*) apos migracao temporaria da outra sessao","fix":"v2.1.1 restaurado para LightRAG-HKU completo com 17 tools originais (query_document, insert_document, get_pipeline_status, etc), UI em rag.descomplicar.pt, PG storage 331 docs","source":"user"} {"date":"2026-04-08","issue":"memoria Claude Code fragmentada em ~/.claude/projects/*/memory/ (101 ficheiros, 34 projectos)","fix":"grep cross-projecto obrigatorio no router Familia A","source":"user"} +{"date":"2026-04-08","issue":"mcp__memory-supabase__search_memories pode estar indisponivel no harness","fix":"graceful fallback no router — continuar paralelismo com outras fontes e reportar lacuna","source":"auto"} ``` --- -**v2.1.0** | 08-04-2026 | Router Família A/B, LightRAG FastMCP tools reais, grep cross-projecto cwd→all +**v2.1.1** | 08-04-2026 | LightRAG-HKU restaurado com 17 tools reais, UI rag.descomplicar.pt, PG storage 331 docs, graceful fallback para MCPs indisponíveis