Dataloupe

dataloupe

只需一条命令，即可将任意 CSV、JSON、NDJSON、Parquet 或 Excel 文件转换为一个独立、完全离线且可交互的 HTML 浏览器。

npx dataloupe data.csv --open

由 AI Agent 构建和维护（Aurelio Nakamura）。非常欢迎大家提交问题、创意和 PR。

▶ 在浏览器中试用 — 拖入自己的 CSV/JSON/Parquet/Excel 文件，即可立即生成浏览器。完全在客户端运行；你的数据不会离开当前标签页（与 CLI 使用相同的引擎）。

_{从生成的 HTML 中实时录制：搜索、排序、滚动虚拟化表格、切换主题——零网络请求。}

dataloupe 会读取你的数据文件，并在同一目录下生成一个 .html 文件。双击打开、通过邮件发送、拖入 Slack，或提交到代码仓库即可。它提供可排序、可搜索、可筛选的表格、逐列统计信息、自动生成的图表，以及一个完全在文件内运行的 SQL 控制台——同时零网络请求：没有 CDN、网页字体或遥测。你的数据永远不会离开你的设备。

这不只是承诺——每个生成的文件都带有严格的 内容安全策略 meta 标签 （default-src 'none'; connect-src 'none'; …），因此浏览器本身会阻止页面可能发出的任何网络请求。在隔离网络的设备上打开，表现也完全相同。

---

为什么选择它

大多数“CSV 转 HTML”工具都是会将文件上传到服务器的网站——对于财务、健康、内部或其他敏感数据而言，这完全行不通。优秀的本地替代方案又比实际需求更笨重：

	数据会离开你的设备	需要运行中的服务器	可分享的单个文件	支持读取 Parquet 和 Excel
在线 CSV→HTML 转换器	是 ❌	否	有时	很少
Datasette	否	是	否	通过插件
VisiData（TUI）	否	否	否	是
dataloupe	否 ✅	否 ✅	是 ✅	是 ✅

dataloupe 会生成一个可移植的 HTML 文件，你可以交给任何人。它可以永久离线使用，对方无需安装任何东西。

安装

使用 npx 运行——无需安装：

npx dataloupe sales.csv

也可以全局安装：

npm install -g dataloupe
dataloupe sales.csv

需要 Node.js ≥ 18。该软件包是一个预构建、独立的 CLI——无需编译，也无需获取运行时依赖。

想要固定到代码仓库，而不是使用注册表版本？npx github:aurelio-nakamura/dataloupe sales.csv 同样可用。

用法

dataloupe <file> [options]

ARGUMENTS
  <file>                CSV, TSV, JSON, NDJSON/JSONL, Parquet, or Excel (.xlsx)
                        Use "-" or pipe to read from stdin (text formats only)

OPTIONS
  -o, --output <file>   output HTML path (default: <input>.html, or dataloupe.html for stdin)
      --open            open the result in your browser when done
      --limit <n>       load at most n rows (default: all)
      --format <fmt>    force format: csv|tsv|json|ndjson|parquet|xlsx
      --delimiter <d>   field delimiter for csv/tsv (default: auto)
      --sheet <name>    worksheet to read from an .xlsx file (default: first)
      --title <text>    human title shown in the header + browser tab
      --note <text>     provenance note shown under the header (why this export
                        exists, what upstream transform produced it, etc.)
  -h, --help            show this help
  -v, --version         print version

示例：

npx dataloupe events.ndjson --open
npx dataloupe metrics.parquet -o report.html
npx dataloupe budget.xlsx --sheet Q3 --open
npx dataloupe big.csv --limit 100000
npx dataloupe q1.csv --title "Q1 Expenses" --note "Exported from ledger; nulls dropped, USD"

生成的文件已嵌入可检查的来源信息——源文件名、格式、生成时间、dataloupe 版本、行数，以及每列推断出的类型和统计信息——因此接收者始终能知道自己看到的是什么。文件还记录了报告是如何生成的：源数据的 SHA-256 值（及其字节大小），以及依次执行的操作（加载 → 筛选 → 分组 → 排序 → 限制），因此任何人都可以验证报告是否来自他们预期的确切字节，并重新生成报告。通过 MCP visualize_data 工具使用时，这一点尤其有用，因为生成报告的查询会被自动记录。 --title 和 --note 可让生成者将人工补充的上下文（导出原因、上游转换的内容）直接写入页眉。

点击查看器中的 ⓘ 关于，即可打开可折叠的来源信息面板，其中会列出所有这些元数据，以及当前应用的确切筛选、排序和列视图，并以通俗易懂的语言加以说明。面板还提供复制此视图链接按钮，方便接收者为当前视图添加书签或分享。显示的每个字段都随文件一起保存；无需获取任何外部内容。

它也支持读取 stdin，因此可以直接接入 Shell 管道（自动检测格式，也可使用 --format 强制指定）：

psql -c "copy (select * from orders) to stdout csv header" | npx dataloupe - --open
cat data.csv | npx dataloupe -o report.html
curl -s https://api.example.com/items | npx dataloupe --format json --open

diff — 数据文件的 git-diff

对 CSV 使用 git diff 会产生一堆噪声：行顺序调整、字段重新加引号，以及一处真正的更改，看起来都一样。dataloupe diff 会按键匹配行，并以一份独立的离线 HTML 报告展示实际更改。

▶ 查看实时差异报告 —— 一份真实的 dataloupe diff 输出（新增／删除／更改的行，并突出显示单元格级别的 old → new 变化），完全离线渲染。

npx github:aurelio-nakamura/dataloupe diff old.csv new.csv --key id --open

+3 added · −1 removed · ~5 changed · =1042 unchanged

• 新增／删除／更改的行以不同颜色标示，并显示发生变化的确切单元格，格式为 old → new。
• 按键匹配（--key id 或 --key region,date），避免行顺序调整和重新加引号被误判为更改。省略 --key 时，dataloupe 会自动检测类似 ID 的唯一列；如果找不到，则按整行匹配。
• 支持在任意两种受支持的格式之间比较——例如，对 .csv 导出文件和 .parquet 快照进行比较，或对比上周与本周的 .xlsx 文件。
• 同样保障隐私：不会发起任何网络请求，你的数据不会离开本机。你可以提交报告、通过电子邮件发送，或将其放入评审中。

在 CI 中使用 diff — 在 Pull Request 中审查数据更改

我们提供了一个 GitHub Action，让审查者可以直接在 PR 中查看数据文件的实际更改——以可下载的独立 HTML 报告和作业中的数量摘要呈现。你的数据不会离开运行器。

# .github/workflows/data-diff.yml
on:
  pull_request:
    paths: ["data/**.csv"]
jobs:
  diff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - run: git show "${{ github.event.pull_request.base.sha }}:data/people.csv" > base.csv || : > base.csv
      - uses: aurelio-nakamura/[email protected]
        id: diff
        with:
          before: base.csv
          after: data/people.csv
          key: id
          output: people-diff.html
      - uses: actions/upload-artifact@v4
        with: { name: data-diff, path: "${{ steps.diff.outputs.html }}" }

此步骤会提供 added / removed / changed / unchanged / changed-any 输出（例如，你可以在数据发生更改时让检查失败），并向作业写入 Markdown 摘要。可直接复制使用的工作流位于 examples/workflows/data-diff.yml。

编程式 API

dataloupe 也是一个库。安装它（npm install dataloupe），即可通过自己的代码生成相同的自包含、完全离线的 HTML——适用于构建流水线、查询结果或生成的数据。它包含 TypeScript 类型，并采用 ESM。

import { renderRows, renderFile, datasetFromRows, renderHtml } from "dataloupe";
import { writeFileSync } from "node:fs";

// From in-memory rows (array of plain objects):
const html = renderRows(
  [
    { name: "Ada", born: 1815, field: "math" },
    { name: "Alan", born: 1912, field: "cs" },
  ],
  { source: "pioneers" },
);
writeFileSync("report.html", html);

// From a file (CSV/TSV/JSON/NDJSON/Parquet/XLSX):
writeFileSync("data.html", await renderFile("data.csv"));

// Or build the dataset (schema + stats) and render separately:
const ds = datasetFromRows(rows);
console.log(ds.columns, ds.types, ds.stats); // inspect
const out = renderHtml(ds);

导出项	说明
renderRows(rows, meta?)	内存中的行 → 自包含的 HTML 字符串。
renderFile(path, opts?)	读取文件 → 自包含的 HTML 字符串。
renderText(text, format, opts?)	文本（csv/tsv/json/ndjson）→ 自包含的 HTML 字符串。
buildDataset(path, opts?)	读取文件 → 已分析的 Dataset（架构 + 统计数据）。
datasetFromRows(rows, meta?)	内存中的行 → 已分析的 Dataset。
buildDatasetFromText(text, format, opts?)	文本字符串 → 已分析的 Dataset。
renderHtml(dataset)	Dataset → 自包含的 HTML 字符串。
diffFiles(before, after, opts?)	对比两个文件 → 自包含的 HTML 差异报告。
diffDatasets(before, after, opts?)	两个 Dataset → 结构化的 DiffResult。
renderDiffHtml(result)	DiffResult → 自包含的 HTML 差异报告。
VERSION	dataloupe 的版本字符串。

<dataloupe-table> — 在任意网页中嵌入数据浏览器

想在自己的网页中使用交互式浏览器，而不是生成独立文件？只需添加 <dataloupe-table> Web 组件——无需框架、无需构建步骤，也无需服务。它会复用完全相同的渲染引擎，并将其挂载到沙盒化的 <iframe> 中（唯一的不透明来源 + 嵌入式 default-src 'none' CSP），因此你指定的数据绝不会离开浏览器，也无法接触宿主页面。

▶ 在线演示

直接从 CDN 加载——无需 npm、无需构建，也无需打包器。此捆绑包约为 110 KB，没有运行时依赖，并从带版本号的 git 标签提供：

<script type="module"
  src="https://cdn.jsdelivr.net/gh/aurelio-nakamura/[email protected]/dist/dataloupe-element.js"></script>


<dataloupe-table src="sales.csv" height="600"></dataloupe-table>

想要自行托管？同一文件也托管在 GitHub Pages 上： https://aurelio-nakamura.github.io/dataloupe/embed/dataloupe-element.js

// Imperative: hand it in-memory rows
const el = document.querySelector("dataloupe-table");
el.rows = [{ name: "Ada", born: 1815 }, { name: "Alan", born: 1912 }];
// ...or raw text: el.setText(csvString, "csv");

属性：src、format、limit、title、height。事件：dataloupe:load / dataloupe:error。你也可以通过打包器执行 import "dataloupe/element" 来注册它。

MCP 服务 — 让 AI 助手离线探索本地数据

dataloupe 提供了一个 MCP 服务，因此 Claude Desktop、 Cursor、VS Code 和其他 MCP 客户端可以直接检查和查询本地数据文件——无需数据库，无需运行中的服务，而且 不会向任何地方上传哪怕一个字节。dataloupe 的核心理念（数据永不离开你的设备）现在也适用于你的 AI Agent。

它与其他数据 MCP 服务的不同之处在于：出色的工具 visualize_data 可将一个文件——或查询结果——转换为 一个完全自包含、完全离线、可交互的 HTML 浏览器，并保存在磁盘上，然后返回其路径。Agent 无需在聊天中粘贴被截断的文本表格，而是可以提供一个可分享的实际文件，你可以在任何浏览器中打开（零外部请求，强制执行 CSP）。

将其添加到 MCP 客户端中（Claude Desktop / Cursor mcpServers 配置示例）：

{
  "mcpServers": {
    "dataloupe": {
      "command": "npx",
      "args": ["-y", "dataloupe", "mcp"],
      "env": { "DATALOUPE_MCP_ROOT": "/path/to/your/data" }
    }
  }
}

DATALOUPE_MCP_ROOT 是可选的，但建议设置：它会将所有文件访问限制在该目录中（可安全防止符号链接逃逸：检查前会将路径规范化）。还有两个可选的安全设置：

• DATALOUPE_MCP_MAX_BYTES — 单文件读取上限，以字节为单位（默认值为 512 MiB）。超过此大小的文件会在加载前被拒绝，因此单个请求不会耗尽内存。 设置为 0 可禁用。
• DATALOUPE_MCP_READONLY — 设置为 1/true 时，服务会拒绝将文件写入调用方指定的 out_path（这可能会覆盖任意文件）；visualize_data / diff_data 仍会返回文件，但只会写入新的临时文件。

提供的工具：

工具	功能
list_data_files	列出目录中的 CSV/TSV/JSON/NDJSON/Parquet/Excel 文件
describe_data	架构 + 行数/列数 + 每列统计信息（类型、空值、唯一值、最小值/最大值/平均值/中位数、热门值）
preview_data	将前 N 行作为 Markdown 表格展示
query_data	只读结构化查询：where / select / order_by / limit / group_by + count/sum/avg/min/max 聚合
sql_query	对文件执行只读 SQL SELECT（WHERE/GROUP BY/ORDER BY/LIMIT + 聚合）——编译为安全计划，不使用 eval，不写入数据。很实用，因为大模型生成 SQL 比生成结构化筛选条件更自然
visualize_data	生成一个自包含、离线、可交互的 HTML 浏览器（可选基于查询结果），并返回其路径
diff_data	以 git 风格比较两个文件（新增/删除/更改计数 + 可选的离线 HTML 报告）

所有工具对你的数据都是 只读的——dataloupe 绝不会修改你的文件。

以容器方式运行（无需 Node/npm）

dataloupe 的 MCP 服务已发布到官方 MCP Registry，名称为 io.github.aurelio-nakamura/dataloupe，并作为 OCI 镜像发布到 GitHub Container Registry。将任何 MCP 客户端指向该镜像即可（它通过 stdio 使用 JSON-RPC）：

{
  "mcpServers": {
    "dataloupe": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--mount", "type=bind,src=/path/to/your/data,dst=/data",
               "ghcr.io/aurelio-nakamura/dataloupe:latest"]
    }
  }
}

所有操作均保持离线：该镜像没有任何运行时依赖，且只会读取你挂载到 /data 的目录。

功能

• 真正离线输出。 生成的 HTML 将所有内容内嵌其中——没有 <script src>、没有 <link href>、没有字体，也没有 fetch。亲自验证：断开网络并打开文件。
• 支持所有常见格式。 CSV、TSV、JSON（对象数组）、NDJSON/JSONL、Parquet 和 Excel (.xlsx)——全部使用纯 JS 读取器，无需原生依赖。Excel 日期单元格会自动识别，并支持通过 --sheet 读取多工作表工作簿。
• 自动推断架构和类型。 整数、数字、布尔值、日期/日期时间、字符串。
• 逐列统计。 空值数、唯一值数、数字的最小值/最大值/平均值/中位数/标准差，以及分类数据的高频值。
• 自动生成图表。 为数值和日期列生成直方图，为分类数据生成频率条形图——以小型内嵌 SVG 绘制。
• 快速、可排序、可筛选的表格，支持跨所有列的全文搜索，并使用虚拟化表体，即使面对大型文件也能保持流畅。
• 内置 SQL 控制台。 在查看器中按 ▸_ SQL，即可对数据运行真正的 SELECT 查询——支持 WHERE、AND、LIKE、IN、GROUP BY、聚合函数（COUNT/SUM/AVG/MIN/MAX）、ORDER BY、LIMIT/OFFSET。它会在浏览器中直接于可分享文件内运行：无需服务端、无需下载 WASM、无需网络。其他单文件导出工具都做不到这一点。
• 可分享的视图。 当前搜索、排序、聚焦列和主题都保存在 URL 哈希中，因此任何筛选/排序视图都可以加入书签并分享——复制地址栏即可（即使是双击打开的 file://…#… 文件也有效），其他人打开同一个文件时会看到完全相同的视图。仍然完全离线；哈希不会触发请求。
• 来源信息面板。 ⓘ 关于面板会列出内嵌的来源/格式/时间戳/版本/数据形状及任何自定义标题/备注，还会以通俗易懂的语言描述当前筛选/排序/列视图——并提供一键式 复制此视图的链接。所有内容都已在文件中。
• diff 模式——用于数据文件的 git 差异比较：按键匹配新增/删除/变更的行，并以单元格为单位突出显示 old → new，生成一份离线 HTML 报告。
• 浅色和深色主题、响应式布局，支持键盘操作。
• 文件小巧。 一份典型报告仅占几十 KB，另加数据本身的大小。

工作原理

dataloupe 在 Node 中解析文件、推断架构、计算列统计信息，并将结果序列化到单个 HTML 文档中，同时内嵌一个精简的手写原生查看器（在构建时打包并内联）。输出文件没有运行时依赖，页面打开时也不会获取任何代码。

开发

git clone https://github.com/aurelio-nakamura/dataloupe
cd dataloupe
npm install
npm run build      # builds the inlined viewer + CLI into dist/
npm test           # vitest
node dist/cli.js path/to/data.csv --open

参与贡献

欢迎提交 Bug 报告、功能请求和拉取请求。如果 dataloupe 弄乱了你的文件或误读了类型，在 issue 中附上一份匿名样本是最快的修复方式。

请参阅 CONTRIBUTING.md，了解构建/测试流程、代码结构，以及如何添加新的输入格式。

许可证

MIT © Aurelio Nakamura