lucid-skill

Connect data → infer semantics → query with natural language → get answers.

All output is JSON unless noted. No API key needed.

Quick Start

lucid-skill connect csv /path/to/sales.csv     # Connect data
lucid-skill overview                            # Check connected sources
lucid-skill search "月度销售额趋势"              # Find relevant tables + suggested SQL
lucid-skill query "SELECT month, SUM(amount) FROM sales GROUP BY month"  # Execute

Core Commands

| Command | Purpose | |---------|---------| | overview | Show all connected sources, tables, semantic status | | connect csv/excel/mysql/postgres | Connect a data source | | tables | List all tables with row counts | | describe <table> | Column details + sample data + semantics | | profile <table> | Deep stats: null rate, distinct, min/max, quartiles | | init-semantic | Export schemas for semantic inference | | update-semantic <file\|-> | Save semantic definitions (JSON from file or stdin) | | search <query> [--top-k N] | Natural language → relevant tables + JOIN hints + metric SQL | | join-paths <a> <b> | Discover JOIN paths between two tables | | domains | Auto-discovered business domains | | query <sql> [--format json\|md\|csv] | Execute read-only SQL | | serve | Start MCP Server (stdio JSON-RPC) |

For full command reference with all parameters: read references/commands.md

Smart Query Pattern (Recommended)

When a user asks a data question:

1. lucid-skill search "关键词" — find relevant tables, suggestedJoins, suggestedMetricSqls
2. If multi-table: lucid-skill join-paths table_a table_b — get JOIN SQL
3. Compose SQL from the returned context
4. lucid-skill query "SELECT ..." — execute and present results

Semantic Layer Setup

First-time setup to enable intelligent search:

lucid-skill init-semantic                               # Export schemas
# Analyze output → infer business meanings for each column
echo '{"tables":[...]}' | lucid-skill update-semantic -  # Save semantics

For JSON schema details: read references/json-schema.md

Key Tips

• Auto-restore: Previous connections survive restarts. Always overview first to check existing state.
• Read-only: Only SELECT allowed. INSERT/UPDATE/DELETE/DROP are blocked.
• Semantic files: Stored in ~/.lucid-skill/semantic_store/ (YAML, human-readable).
• Data directory: ~/.lucid-skill/ (override with LUCID_DATA_DIR env var).
• Embedding: Set LUCID_EMBEDDING_ENABLED=true for better multilingual search (downloads ~460 MB model on first use).
• No credentials stored: Database passwords are never written to disk.
• MCP mode: lucid-skill serve starts stdio JSON-RPC server for MCP integrations.

Detailed References

• references/commands.md — Full CLI command reference with all parameters
• references/json-schema.md — update-semantic JSON format specification
• references/workflow.md — Multi-step workflow guides (first-time setup, returning sessions, multi-source)