文件(.xlsx/.xlsm/.mdb/.accdb/.parquet)
   │  ingest(零拷贝 Parquet 注册 / 转换落盘)
   ▼
data/parquet/<source>/<table>.parquet ──► data/warehouse.duckdb(表以 VIEW 注册)
   │                                            │
   │  profile(聚合 SQL 画像)                   │  cards(M-Schema 表卡片)
   ▼                                            ▼
data/catalog/profiles/*.json ──────► data/catalog/cards(_md)/*.json(md)
   │                                            │
   │                                            ▼
   │                     index(LanceDB 向量 + BM25,术语直通)
   │                                            │
   └──────────────────► retrieve(Top-K 表卡片,token 预算贪心)
                                                ▼
                                    generate(LLM → SQL,诚实反问)
                                                ▼
                                    guard(sqlglot 静态护栏)
                                                ▼
                                    run(只读沙箱执行 + 结果压缩)
                                                ▼
                                    interpret(第二次 LLM 解读)
                                                ▼
                                    答案 + SQL + 行数/耗时/token + 明细位置

export LLM_BASE_URL="https://your-llm-provider/v1"
export LLM_API_KEY="sk-..."
export LLM_MODEL="your-chat-model"
export EMB_BASE_URL="https://your-emb-provider/v1"
export EMB_API_KEY="sk-..."
export EMB_MODEL="your-embedding-model"

git clone https://github.com/Zhu-Guang-Scion/Duckseek.git && cd Duckseek
uv sync                                   # 创建 .venv 并安装依赖（锁定于 uv.lock）

# 1) 接入数据（三种来源任选；零拷贝注册或转换落盘；表名 = 文件名，clean_name 规则）
uv run nl2data ingest excel  path/to/订单.xlsx            # 多 sheet → 每 sheet 一表
uv run nl2data ingest access path/to/legacy.mdb            # 需 mdbtools（Linux/macOS/WSL）
uv run nl2data ingest parquet samples/nyc-taxi/yellow_tripdata.parquet --name yellow_tripdata

# 2) 画像 → 3) 卡片 → 4) 检索索引（幂等，可重复执行）
uv run nl2data profile --all
uv run nl2data cards build --all
uv run nl2data index build

# 5) 提问（答案附实际执行的 SQL）
uv run nl2data ask "2026年3月黄色出租车的总订单量是多少？"
# 交互模式（/retry [补充] /show sql /export csv <路径> /tables /exit）：
uv run nl2data ask

{
  "mcpServers": {
    "duckseek": {
      "command": "uv",
      "args": ["--directory", "<本仓库绝对路径>", "run", "nl2data", "mcp", "serve"],
      "env": {
        "LLM_BASE_URL": "<LLM 网关地址>",
        "LLM_API_KEY": "<LLM 密钥>",
        "LLM_MODEL": "<模型名>",
        "EMB_BASE_URL": "<embedding 网关地址>",
        "EMB_API_KEY": "<embedding 密钥>",
        "EMB_MODEL": "<embedding 模型名>"
      }
    }
  }
}

uv run nl2data eval e2e [--save-baseline]   # golden 20 条 × N=3 多数决
uv run nl2data eval recall                  # 仅召回层
uv run nl2data audit 10                     # 最近问答审计