DuckBI-DSH

DuckBI · 让 AI 直接分析你电脑里的 Excel 和日志

中文 | English

本地 DuckDB 引擎 · 对话式取数 · 一键出图出报表

不用上传文件、不用建仓库、不用学 BI 工具 —— 指一个目录，然后开始聊天。

前置条件

你需要先安装 DeepSeek Harness desktop，然后才能使用本项目的所有功能

本项目是一个dsh插件，核心用duckdb引擎做的，不建议单独运行。如果感兴趣，您可以尝试在codex, claude或者任何其他的code agent产品中安装，但是不保证使用效果。

#dsh-plugin · DuckDB · local-first · Excel / Log / CSV / JSON · MIT

30 秒看懂

· 传统做法 · DuckBI 数据怎么进来 · 手动上传到 SaaS / 建数仓 / 写 ETL · 指一个文件夹，自动建表 怎么取数 · 拖拽维度、写 DAX、找人提需求 · 说一句话，AI 写 SQL 大文件 · 网页传不动、Excel 打不开 · 1.3 GB 日志 9 秒入库，370 万行秒级聚合 报表 · 模板工具里拼 · 一次生成多节报告：KPI 卡 + 表 + 图 + 结论 数据边界 · 全量上传云 · 原始文件永不外发；计算全在本机

它不是一个"上传文件给 AI 看"的工具，而是一个装在你机器上的分析引擎，AI 只负责下命令。

三步装好（约 2 分钟）

前提：装了 DeepSeek Harness（桌面版或 dsh CLI），且至少启动过一次（这样 profile 已存在）。

git clone https://github.com/don2ccc/DuckBI-DSH.git
cd DuckBI-DSH\packages\dsh-plugin-duckbi
npm install
node install.mjs

装完确认一眼：

Get-Content "$env:USERPROFILE\.dsh\duckbi\plugin-loaded.json"

看到 "ok": true 就装好了 → 重启一次 Harness（首次加载需要）→ 在对话里说：

把 D:\数据\销售 加进来，看看有哪些数据

没装 git？用「Code → Download ZIP」解压后从 cd 那步继续。

换 profile、离线、手动安装、排错见下面的 安装详解。

它能做什么

① 指个目录，就变成数据库

你：把 D:\data\销售 加进来
AI：→ 扫描 13 个文件 → 建了 3 张表（1,099,083 行），9.4 秒

支持 .log .csv .tsv .json .jsonl .ndjson .parquet .xlsx .xlsm， 压缩包（.gz / .zst）直接读，GB18030 中文编码自动识别转码， Excel 多个工作表自动拆成多张表，中文表头原样保留。也可以直接指单个文件， 插件会只登记它、不扫描整个目录。

② 聊天就是 SQL 编辑器

你：North 区各产品月度退货率
AI：（发现每个格子只有 1–3 单 → 主动降维到半年口径重算，并告诉你为什么）

模型会先看表结构再写 SQL，跑完看结果，不对就改。你可以只聊业务，不说 SQL。

③ 图直接在对话里显示

柱状、折线、面积、环形、散点，服务端用 Canvas 渲染成 PNG，有附件服务时直接内嵌在聊天里。 中文标题、千分位刻度、自动折叠 Other 都处理好了。

④ 报表一句话落地

你：按这个口径做份报表，我要给总监汇报
AI：→ 一次生成多节 PDF + 同口径 Excel：KPI 卡 / 区域积分卡 / 同期增长 / 交叉表 / 图表 / 结论

给 duckbi_export 传 sections 就能一次调用产出多节 PDF + 多工作表 Excel：kpi 画成指标卡， table 出格式化表格，chart 把图直接嵌进 PDF，text 写结论。图表只渲染一次、PDF 与 Excel 共用同一批 SQL， 不用为每一节再往返一次模型。版式定下来后可以固化成模板，之后 node scripts/report.mjs 一条命令重跑，不经过模型、0 token，适合日报/周报。

Excel 带表头样式、冻结窗格、筛选、数字格式、生成信息页；PDF 是 A4 横向、跨页重复表头、页码、 中文字体内嵌，图表会按页面宽度自动缩放、避免标题与图分页。

⑤ 为对话省 token

• 工具描述压缩：5 个工具的描述常驻每次请求，控制在约 2.5 KB。
• 扫描/目录默认只回摘要：几十上百个文件不会把"每文件一行"的表灌进上下文；需要时再 detail: true。
• schema 搜索：duckbi_schema { query: "orders" } 命中一张表时直接返回列信息，省掉一次往返。
• 报表一次调用：多节报告只占一次工具往返，而不是"画图 + 导出"各来一遍。

数据到底去了哪儿（重要，请读完）

没有任何文件被上传。 具体边界如下：

环节 · 在哪执行 · 会离开你的机器吗 读 Excel / 日志、建表、SQL 聚合 · 本机 DuckDB（嵌入式，无服务、无端口） · 不会 图表渲染、Excel / PDF 生成 · 本机 Node.js · 不会 原始文件内容 · —— · 永不外发 列名、表结构、查询结果表（默认 ≤ 200 行） · 随对话发给模型 · 云端模型：会 你打的字、模型写的 SQL · 随对话发给模型 · 云端模型：会

也就是说：能本地算的绝不外发，模型只看到"你允许它看到的聚合结果"，看不到你的原始文件。

想要绝对零外发？换成本地模型即可

Harness 支持任意 OpenAI 兼容端点。把它指向你局域网里的推理服务（Ollama / vLLM / LM Studio 都行）， 再配合本插件，整条链路——数据、计算、模型推理——全部不出机器：

# cordis.patch.yml
- id: llm-pi-ai
  name: '@deepseek-ai/dsh-llm-pi-ai'
  config:
    providers:
      local:
        api: openai-completions
        baseURL: http://127.0.0.1:11434/v1   # 你的本地推理服务
        apiKeyEnv: LOCAL_LLM_KEY
        models: [{ id: qwen2.5-coder:14b, name: Qwen2.5 Coder 14B }]

再把 maxRows 调小、只让模型看聚合结果（GROUP BY 之后再问），外发面就趋近于零。

安装详解

安装 = 把包放进 profile 能解析的位置 + 在 profile 的补丁文件里加一条 insert。 仓库自带 install.mjs 把这两步做完，也可以手动做（见下文，脚本只做这两件事，不碰别的）。

0. 前置条件

要求 · 怎么确认 · 说明 DeepSeek Harness · 桌面版能打开，或 dsh --version 有输出 · 桌面版与 CLI 都可以 Node.js 20+ · node -v · 只用于安装与跑脚本；插件运行时用的是 Harness 自带的 Node 至少一个 profile · dir %USERPROFILE%.dsh\profiles（macOS/Linux：ls ~/.dsh/profiles） · 没看到 desktop 就先启动一次桌面版，或改用 --profile web

DSH_HOME 默认是 %USERPROFILE%.dsh（macOS/Linux 是 ~/.dsh）。装在别处的话所有命令加 --home 。

方式 A：git clone（推荐）

git clone https://github.com/don2ccc/DuckBI-DSH.git
cd DuckBI-DSH\packages\dsh-plugin-duckbi
npm install            # 按你的平台拉原生二进制（约 130 MB，首次约 10 秒）
node install.mjs       # 默认装到 desktop profile

要装到别的 profile、或顺便预登记数据目录：

node install.mjs --profile web
node install.mjs --sources D:\日志,D:\台账 --warmup eager

方式 B：下载 ZIP（没有 git）

1. 仓库页 → Code → Download ZIP → 解压，例如 D:\DuckBI-DSH-main
2. 然后同方式 A：

cd D:\DuckBI-DSH-main\packages\dsh-plugin-duckbi
npm install
node install.mjs

方式 C：一行命令装发布包（最快）

# 1) 直接把 GitHub Release 的包装进 profile（依赖随之安装；pnpm 会解析这个 tarball URL）
dsh plugin --profile desktop add https://github.com/don2ccc/DuckBI-DSH/releases/download/v0.2.0/duckbi-dsh-plugin-duckbi-0.2.0.tgz

# 2) 再写配置（包已在 node_modules 里，用 --no-link 跳过软链）
node "$env:USERPROFILE\.dsh\profiles\desktop\node_modules\@duckbi\dsh-plugin-duckbi\install.mjs" --no-link

也可以先用浏览器下载 Releases 里的 .tgz， 或者拿同事发你的包，把第一步换成本地路径：

dsh plugin --profile desktop add .\duckbi-dsh-plugin-duckbi-0.2.0.tgz

自己打包给同事：

cd packages\dsh-plugin-duckbi
npm pack          # -> duckbi-dsh-plugin-duckbi-0.2.0.tgz（约 80 KB，不含 node_modules）

不要把 `node_modules` 拷给别人。 @duckdb/node-api 和 @napi-rs/canvas 带平台原生二进制，

Windows 的 .node 文件在 macOS/Linux 上会直接加载失败。让对方自己 npm install。

安装器到底做了什么（可以逐条核对）

1. 把包链接到 /profiles/node_modules/@duckbi/dsh-plugin-duckbi

（Windows 用 junction，macOS/Linux 用 symlink）——不复制 `node_modules`；

1. 往 /profiles//cordis.patch.yml 追一段带标记的配置：

# >>> DuckBI (managed by install.mjs) >>>
   - insert:
       - id: duckbi
         name: '@duckbi/dsh-plugin-duckbi'
         config:
           dataDir: 'C:\Users\me\.dsh\duckbi'
           warmup: lazy
           sources: []
   # <<< DuckBI (managed by install.mjs) <<<

你原有的配置一行都不动；重复安装会原地替换这一段（不会写出两份）； 如果 profile 还是空层 []，安装器会把 [] 换掉而不是傻追加（否则 YAML 非法）。

1. 创建数据目录 /duckbi（DuckDB 文件、导出文件、临时转码副本都在这）。

除此之外不改任何东西，不需要管理员权限。

手动安装（不想跑脚本）

# 1) 建目录并链接（Windows；macOS/Linux 用 ln -s）
New-Item -ItemType Directory -Force "$env:USERPROFILE\.dsh\profiles\node_modules\@duckbi"
New-Item -ItemType Junction `
  -Path "$env:USERPROFILE\.dsh\profiles\node_modules\@duckbi\dsh-plugin-duckbi" `
  -Target "D:\DuckBI-DSH\packages\dsh-plugin-duckbi"

# macOS / Linux
mkdir -p ~/.dsh/profiles/node_modules/@duckbi
ln -s /path/to/DuckBI-DSH/packages/dsh-plugin-duckbi ~/.dsh/profiles/node_modules/@duckbi/dsh-plugin-duckbi

然后在 ~/.dsh/profiles/desktop/cordis.patch.yml 末尾追加（若文件只有 []，请把 [] 删掉）：

- insert:
    - id: duckbi
      name: '@duckbi/dsh-plugin-duckbi'
      config:
        dataDir: 'C:\Users\me\.dsh\duckbi'   # 必须单引号，双引号会把 \U 当转义
        warmup: lazy
        sources: []

最后 mkdir 一下 dataDir 再启动 Harness。

验证装好了

Get-Content "$env:USERPROFILE\.dsh\duckbi\plugin-loaded.json"
# macOS/Linux: cat ~/.dsh/duckbi/plugin-loaded.json

{
  "plugin": "@duckbi/dsh-plugin-duckbi",
  "version": "0.2.0",
  "pid": 41008,
  "electron": "44.0.0",
  "duckdb": "v1.5.6",
  "ok": true
}