feat(metabase): adiciona plugin metabase (agents, skills, knowledge e metadados do projeto)
This commit is contained in:
@@ -0,0 +1,17 @@
|
||||
# AGENTS.md — skills
|
||||
|
||||
Directrizes específicas deste projecto para agentes IA.
|
||||
|
||||
## Referências obrigatórias
|
||||
|
||||
- `ECOSYSTEM.md` — Hub/06-Operacoes/Documentacao/ECOSYSTEM.md
|
||||
- `PROC-DEV-STANDARD` — D7-SIS-006
|
||||
- `PROC-AUDIT-STANDARD` — D7-SIS-007
|
||||
|
||||
## Protocolo de sessão
|
||||
|
||||
Início: ler MEMORY.md + STATUS.md. Fim: actualizar ambos.
|
||||
|
||||
## Convenções específicas
|
||||
|
||||
- (a definir)
|
||||
@@ -0,0 +1,5 @@
|
||||
# CHANGELOG — skills
|
||||
|
||||
## 0.1.0 — 2026-06-30
|
||||
### Adicionado
|
||||
- Estrutura padrão (PROC-DEV-STANDARD)
|
||||
@@ -0,0 +1,4 @@
|
||||
# MEMORY.md — skills
|
||||
|
||||
## 2026-06-30
|
||||
- Estrutura padrão aplicada via propagate-structure.sh
|
||||
@@ -0,0 +1,3 @@
|
||||
# skills
|
||||
|
||||
Subprojecto skills do ecossistema Descomplicar.
|
||||
@@ -0,0 +1,8 @@
|
||||
# STATUS.md — skills
|
||||
|
||||
**Versão:** 0.1 | **Data:** 2026-06-30 | **Agente:** —
|
||||
|
||||
## Estado actual
|
||||
- Em curso: —
|
||||
- Bloqueios: —
|
||||
- Próximos passos: —
|
||||
@@ -0,0 +1,148 @@
|
||||
---
|
||||
name: dashboard
|
||||
description: Criação e gestão de dashboards Metabase — questions, visualizações e filtros para bi.descomplicar.pt.
|
||||
disable-model-invocation: true
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# Skill /dashboard - Metabase Dashboard Management
|
||||
|
||||
Criar e gerir dashboards Metabase com questions, visualizações e filtros para bi.descomplicar.pt.
|
||||
|
||||
## Sintaxe
|
||||
|
||||
```
|
||||
/dashboard [operação] [contexto]
|
||||
```
|
||||
|
||||
**Operações:**
|
||||
- `create [nome]` - Criar novo dashboard
|
||||
- `add-card [dashboard_id]` - Adicionar question/card a dashboard
|
||||
- `list` - Listar todos os dashboards
|
||||
- `view [id]` - Ver detalhes de um dashboard
|
||||
- `share [id]` - Obter link público de partilha
|
||||
- `export [id]` - Exportar dados de um dashboard
|
||||
|
||||
## Quando usar
|
||||
|
||||
- Criar dashboards de negócio (vendas, marketing, operações)
|
||||
- Adicionar visualizações a dashboards existentes
|
||||
- Organizar métricas em painéis visuais
|
||||
- Partilhar dashboards com equipa
|
||||
|
||||
---
|
||||
|
||||
## Protocolo de execução
|
||||
|
||||
### 1. Carregar MCP
|
||||
|
||||
```
|
||||
ToolSearch("metabase")
|
||||
```
|
||||
|
||||
### 2. Operação: create
|
||||
|
||||
**Workflow completo para criar dashboard:**
|
||||
|
||||
```
|
||||
1. CONFIRMAR objectivo com utilizador
|
||||
2. Identificar database e tabelas relevantes
|
||||
- mcp__metabase__list_databases
|
||||
- mcp__metabase__get_database_tables
|
||||
3. Escolher/criar collection destino
|
||||
- mcp__metabase__list_collections
|
||||
4. Criar questions/cards necessários
|
||||
- Definir query (SQL ou query builder)
|
||||
- Escolher tipo de visualização (bar, line, pie, table, number)
|
||||
5. Criar dashboard
|
||||
- mcp__metabase__create_dashboard (nome, descrição, collection_id)
|
||||
6. Adicionar cards ao dashboard
|
||||
7. Confirmar resultado com URL
|
||||
```
|
||||
|
||||
**Tipos de visualização recomendados:**
|
||||
|
||||
| Métrica | Visualização |
|
||||
|---------|-------------|
|
||||
| KPI singular (total vendas) | Number |
|
||||
| Evolução temporal | Line chart |
|
||||
| Comparação categorias | Bar chart |
|
||||
| Distribuição/proporção | Pie chart |
|
||||
| Dados detalhados | Table |
|
||||
| Geográfico | Map |
|
||||
|
||||
### 3. Operação: add-card
|
||||
|
||||
```
|
||||
1. Verificar dashboard existe: mcp__metabase__get_dashboard
|
||||
2. Criar question se necessário
|
||||
3. Adicionar card ao dashboard
|
||||
4. Confirmar posição e tamanho
|
||||
```
|
||||
|
||||
### 4. Operação: list
|
||||
|
||||
```
|
||||
1. mcp__metabase__list_dashboards
|
||||
2. Apresentar: ID, nome, collection, cards count, última actualização
|
||||
```
|
||||
|
||||
### 5. Operação: view
|
||||
|
||||
```
|
||||
1. mcp__metabase__get_dashboard (id)
|
||||
2. Mostrar: nome, descrição, cards, filtros, parâmetros
|
||||
3. URL directa: https://bi.descomplicar.pt/dashboard/{id}
|
||||
```
|
||||
|
||||
### 6. Operação: share
|
||||
|
||||
```
|
||||
1. Gerar link público se não existir
|
||||
2. Retornar URL de embed/partilha
|
||||
```
|
||||
|
||||
### 7. Operação: export
|
||||
|
||||
```
|
||||
1. Para cada card no dashboard, exportar dados
|
||||
2. Formatar em tabela Markdown ou sugerir CSV
|
||||
```
|
||||
|
||||
## Templates de dashboard
|
||||
|
||||
### Dashboard vendas
|
||||
- Total facturado (mês actual vs anterior)
|
||||
- Facturas por estado (paid/unpaid/overdue)
|
||||
- Top 10 clientes por valor
|
||||
- Evolução mensal receita
|
||||
|
||||
### Dashboard projectos
|
||||
- Projectos activos vs concluídos
|
||||
- Tarefas por estado
|
||||
- Tempo registado por projecto
|
||||
- Deadlines próximos
|
||||
|
||||
### Dashboard suporte
|
||||
- Tickets abertos vs fechados
|
||||
- Tempo médio de resposta
|
||||
- Tickets por departamento
|
||||
- Satisfação cliente
|
||||
|
||||
## Notas
|
||||
|
||||
- Objectos criados via AI usam prefixo `claude_ai_` (comportamento do MCP)
|
||||
- Sempre confirmar com utilizador antes de criar/modificar
|
||||
- Preferir collections organizadas por tema
|
||||
|
||||
---
|
||||
|
||||
## Healing Log
|
||||
|
||||
Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.
|
||||
|
||||
```jsonl
|
||||
{"date":"","issue":"","fix":"","source":"user|auto"}
|
||||
```
|
||||
|
||||
*Adicionar nova linha após cada erro corrigido.*
|
||||
@@ -0,0 +1,6 @@
|
||||
{
|
||||
"task_id": null,
|
||||
"project_id": null,
|
||||
"customer_id": null,
|
||||
"gitea_repo": null
|
||||
}
|
||||
@@ -0,0 +1,8 @@
|
||||
# skills
|
||||
|
||||
## Documentação
|
||||
|
||||
- [README](README.md)
|
||||
- [AGENTS](AGENTS.md)
|
||||
- [STATUS](STATUS.md)
|
||||
- [MEMORY](MEMORY.md)
|
||||
@@ -0,0 +1 @@
|
||||
## 2026-06-30 init | Estrutura padrão
|
||||
@@ -0,0 +1,132 @@
|
||||
---
|
||||
name: metabase
|
||||
description: Operações Metabase BI — explorar bases de dados, listar dashboards, gerir collections e questions via bi.descomplicar.pt.
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# Skill /metabase - Metabase BI Operations
|
||||
|
||||
Operações Metabase BI - explorar databases, listar dashboards, gerir collections e questions via bi.descomplicar.pt.
|
||||
|
||||
## Sintaxe
|
||||
|
||||
```
|
||||
/metabase [operação] [contexto]
|
||||
```
|
||||
|
||||
**Operações:**
|
||||
- `explore` - Explorar databases e tabelas disponíveis
|
||||
- `dashboards` - Listar e inspeccionar dashboards
|
||||
- `collections` - Gerir collections (pastas)
|
||||
- `questions` - Listar e inspeccionar questions/cards
|
||||
- `search [termo]` - Pesquisar conteúdo no Metabase
|
||||
- `users` - Listar utilizadores e permissões
|
||||
- `status` - Estado geral da instância
|
||||
|
||||
## Quando usar
|
||||
|
||||
- Explorar que dados estão disponíveis no Metabase
|
||||
- Ver dashboards existentes
|
||||
- Gerir collections e organização
|
||||
- Verificar estado da instância
|
||||
- Operações administrativas gerais
|
||||
|
||||
---
|
||||
|
||||
## Protocolo de execução
|
||||
|
||||
### 1. Carregar MCP Metabase
|
||||
|
||||
```
|
||||
ToolSearch("metabase")
|
||||
```
|
||||
|
||||
Verificar que as tools `mcp__metabase__*` estão disponíveis.
|
||||
|
||||
### 2. Operação: explore
|
||||
|
||||
**Objectivo:** Mapear dados disponíveis.
|
||||
|
||||
```
|
||||
1. Listar databases: mcp__metabase__list_databases
|
||||
2. Para cada database relevante: mcp__metabase__get_database_tables
|
||||
3. Para tabelas de interesse: mcp__metabase__get_table_fields
|
||||
4. Apresentar resumo estruturado
|
||||
```
|
||||
|
||||
**Output esperado:**
|
||||
```markdown
|
||||
## Databases disponíveis
|
||||
|
||||
| ID | Nome | Engine | Tabelas |
|
||||
|----|------|--------|---------|
|
||||
| 1 | ... | ... | N |
|
||||
|
||||
### Database: [Nome]
|
||||
| Tabela | Campos | Registos |
|
||||
|--------|--------|----------|
|
||||
| ... | ... | ... |
|
||||
```
|
||||
|
||||
### 3. Operação: dashboards
|
||||
|
||||
```
|
||||
1. Listar dashboards: mcp__metabase__list_dashboards
|
||||
2. Para cada dashboard: mostrar nome, descrição, cards
|
||||
3. Se pedido detalhe: mcp__metabase__get_dashboard
|
||||
```
|
||||
|
||||
### 4. Operação: collections
|
||||
|
||||
```
|
||||
1. Listar collections: mcp__metabase__list_collections
|
||||
2. Mostrar hierarquia de pastas
|
||||
3. Contar items por collection
|
||||
```
|
||||
|
||||
### 5. Operação: questions
|
||||
|
||||
```
|
||||
1. Listar questions/cards: mcp__metabase__list_cards
|
||||
2. Mostrar: nome, tipo, database, última execução
|
||||
```
|
||||
|
||||
### 6. Operação: search
|
||||
|
||||
```
|
||||
1. mcp__metabase__search_content com termo fornecido
|
||||
2. Agrupar resultados por tipo (dashboard, card, table)
|
||||
```
|
||||
|
||||
### 7. Operação: status
|
||||
|
||||
```
|
||||
1. Listar databases e verificar conectividade
|
||||
2. Contar dashboards, questions, collections
|
||||
3. Listar utilizadores activos
|
||||
4. Apresentar resumo
|
||||
```
|
||||
|
||||
## Metabase instance
|
||||
|
||||
- **URL**: https://bi.descomplicar.pt/
|
||||
- **MCP**: metabase (metabase-ai-assistant v4.2.0, 134 tools)
|
||||
- **Auth**: API key (configurada no MCP)
|
||||
|
||||
## Notas
|
||||
|
||||
- Todas as operações são **read-only** por defeito
|
||||
- Para operações de escrita (criar dashboard, etc.), usar `/dashboard`
|
||||
- Para queries SQL, usar `/query`
|
||||
|
||||
---
|
||||
|
||||
## Healing Log
|
||||
|
||||
Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.
|
||||
|
||||
```jsonl
|
||||
{"date":"","issue":"","fix":"","source":"user|auto"}
|
||||
```
|
||||
|
||||
*Adicionar nova linha após cada erro corrigido.*
|
||||
@@ -0,0 +1,161 @@
|
||||
---
|
||||
name: query
|
||||
description: Execução de queries SQL no Metabase com linguagem natural. Explorar tabelas, extrair métricas e criar relatórios ad-hoc.
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# Skill /query - Metabase SQL Query Assistant
|
||||
|
||||
Executar queries SQL no Metabase com assistência AI. Traduz perguntas em linguagem natural para SQL, explora tabelas e extrai métricas.
|
||||
|
||||
## Sintaxe
|
||||
|
||||
```
|
||||
/query [pergunta em linguagem natural ou SQL]
|
||||
```
|
||||
|
||||
**Exemplos:**
|
||||
- `/query quantos clientes temos activos?`
|
||||
- `/query total facturado em Janeiro 2026`
|
||||
- `/query top 10 produtos mais vendidos`
|
||||
- `/query SELECT COUNT(*) FROM customers WHERE active = true`
|
||||
|
||||
## Quando usar
|
||||
|
||||
- Extrair dados específicos das bases de dados
|
||||
- Responder perguntas de negócio com dados reais
|
||||
- Análise ad-hoc rápida
|
||||
- Validar hipóteses com números concretos
|
||||
- Criar queries para futuros cards/questions
|
||||
|
||||
---
|
||||
|
||||
## Protocolo de execução
|
||||
|
||||
### 1. Carregar MCP
|
||||
|
||||
```
|
||||
ToolSearch("metabase")
|
||||
```
|
||||
|
||||
### 2. Compreender o pedido
|
||||
|
||||
**Se linguagem natural:**
|
||||
1. Identificar a pergunta de negócio
|
||||
2. Determinar database e tabelas relevantes
|
||||
3. Usar AI SQL generation do MCP se disponível
|
||||
|
||||
**Se SQL directo:**
|
||||
1. Validar syntax
|
||||
2. Verificar que tabelas existem
|
||||
3. Executar
|
||||
|
||||
### 3. Explorar schema (se necessário)
|
||||
|
||||
```
|
||||
1. mcp__metabase__list_databases → identificar database
|
||||
2. mcp__metabase__get_database_tables → listar tabelas
|
||||
3. mcp__metabase__get_table_fields → ver campos disponíveis
|
||||
```
|
||||
|
||||
### 4. Construir e executar query
|
||||
|
||||
```
|
||||
1. Construir SQL baseado no schema real
|
||||
2. Executar via mcp__metabase__execute_sql
|
||||
3. Validar resultados (nulls, zeros, outliers)
|
||||
4. Formatar output
|
||||
```
|
||||
|
||||
### 5. Apresentar resultados
|
||||
|
||||
**Output format:**
|
||||
|
||||
```markdown
|
||||
## Query: [Descrição da pergunta]
|
||||
|
||||
**Database:** [nome] | **Tabelas:** [lista]
|
||||
|
||||
### Resultados
|
||||
|
||||
| Col1 | Col2 | Col3 |
|
||||
|------|------|------|
|
||||
| ... | ... | ... |
|
||||
|
||||
**Total registos:** N
|
||||
|
||||
### Insight
|
||||
[Interpretação breve dos dados]
|
||||
```
|
||||
|
||||
## Boas práticas SQL
|
||||
|
||||
### Performance
|
||||
- Usar `LIMIT` em queries exploratórias (default: 100)
|
||||
- Evitar `SELECT *` - especificar campos necessários
|
||||
- Usar `WHERE` para filtrar antes de agregar
|
||||
- Indexes: verificar campos indexados para JOINs
|
||||
|
||||
### Segurança
|
||||
- **Read-only**: o MCP opera em modo read-only por defeito
|
||||
- Nunca executar DDL (CREATE, ALTER, DROP) sem confirmação
|
||||
- Nunca executar DML (INSERT, UPDATE, DELETE) sem confirmação
|
||||
|
||||
### Padrões comuns
|
||||
|
||||
**Contagem com agrupamento:**
|
||||
```sql
|
||||
SELECT campo, COUNT(*) as total
|
||||
FROM tabela
|
||||
GROUP BY campo
|
||||
ORDER BY total DESC
|
||||
LIMIT 10;
|
||||
```
|
||||
|
||||
**Evolução temporal:**
|
||||
```sql
|
||||
SELECT DATE_TRUNC('month', created_at) as mes,
|
||||
COUNT(*) as total,
|
||||
SUM(valor) as valor_total
|
||||
FROM tabela
|
||||
WHERE created_at >= NOW() - INTERVAL '12 months'
|
||||
GROUP BY mes
|
||||
ORDER BY mes;
|
||||
```
|
||||
|
||||
**Comparação período actual vs anterior:**
|
||||
```sql
|
||||
SELECT
|
||||
SUM(CASE WHEN created_at >= DATE_TRUNC('month', NOW()) THEN valor END) as mes_actual,
|
||||
SUM(CASE WHEN created_at >= DATE_TRUNC('month', NOW() - INTERVAL '1 month')
|
||||
AND created_at < DATE_TRUNC('month', NOW()) THEN valor END) as mes_anterior
|
||||
FROM tabela;
|
||||
```
|
||||
|
||||
## Guardar query como question
|
||||
|
||||
Se o utilizador quiser reutilizar a query:
|
||||
```
|
||||
1. Confirmar nome e descrição
|
||||
2. Criar question/card no Metabase
|
||||
3. Associar a collection adequada
|
||||
4. Retornar URL directa
|
||||
```
|
||||
|
||||
## Notas
|
||||
|
||||
- Resultados limitados a 2000 linhas por defeito pelo MCP
|
||||
- Para datasets grandes, usar agregações
|
||||
- Queries complexas: delegar ao agente `metabase-analyst`
|
||||
|
||||
---
|
||||
|
||||
## Healing Log
|
||||
|
||||
Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.
|
||||
|
||||
```jsonl
|
||||
{"date":"","issue":"","fix":"","source":"user|auto"}
|
||||
```
|
||||
|
||||
*Adicionar nova linha após cada erro corrigido.*
|
||||
Reference in New Issue
Block a user