dsh-csv-explorer

CSV 数据探查插件（v0.3.0）：分隔符感知的预览分页、数值列统计与多条件过滤。轻量设计，不解析 Excel 二进制格式。

安装

npm install dsh-csv-explorer

工具

csv_preview

| 参数 | 类型 | 说明 | |------|------|------| | text / file | string | 源内容二选一（file 须在工作目录内） | | rows | number | 预览行数（默认 5，上限 50） | | offset | number | 可选，偏移量：head 时跳过开头 N 行，tail 时跳过末尾 N 行（默认 0，负数收敛为 0） | | order | string | 可选，采样方向：head（默认，从头取）或 tail（从末尾取） | | delimiter | string | 可选，显式分隔符；缺省自动嗅探（, ; \t \| 取前 10 行众数） |

输出：分隔符、总行数、列数、当前窗口行号范围 + Markdown 表格预览。head 模式下窗口之后仍有数据时提示下一个 offset 用于翻页；tail 模式反向翻页；offset 越界时提示窗口为空。自动处理 BOM 与 CRLF；引号内分隔符正确切分（csv-parse）；短行补齐、长行截断到表头宽度；空表头自动命名 列N。

csv_stats

| 参数 | 类型 | 说明 | |------|------|------| | columns | array | 可选，列名或 0 基下标；缺省统计全部数值列 | | text / file | string | 源内容二选一 | | delimiter | string | 可选，显式分隔符 |

数值识别：支持千分位（1,200.50）、百分号（85%）、货币符号前后缀（¥99、$1,000）、科学计数法。

每列输出：count（数值单元格数）、非数值个数、min / max / mean / median（偶数行取均值）/ std（总体标准差）/ sum。非数值列标注跳过。

csv_filter

| 参数 | 类型 | 说明 | |------|------|------| | conditions | array | 过滤条件列表，如 ["age>30", "city contains 深圳"]，每项格式为「列名 操作符 值」 | | logic | string | 可选，多条件组合方式：and（默认，全部满足）或 or（任一满足） | | column / op / value | string | 单条件简写（与 conditions 二选一） | | limit | number | 可选，最多预览行数（默认 10，上限 50） | | text / file / delimiter | - | 同 csv_preview |

操作符支持符号（= != > < >= <=）与英文名（eq/ne/gt/lt/ge/le），另有 contains 子串匹配；数值列自动按数值比较，否则按字符串比较。输出匹配行数、条件描述与 Markdown 表格预览。

匹配 3/5 行（region contains East OR qty gt 3）

使用步骤

1. 准备数据

CSV 文件放在工作目录内（如 ./data/sales.csv），或直接把 CSV 内容作为 text 传入。注意：本插件不解析 Excel（.xlsx）二进制，Excel 数据请先另存为 CSV。

2. 先预览再统计

推荐先 csv_preview 确认结构（分隔符、表头、行数），再 csv_stats 统计：

csv_preview({ file: "data/sales.csv", rows: 5 })
csv_stats({ file: "data/sales.csv" })

3. 只统计关心的列

columns 支持列名或 0 基下标（混用）：

csv_stats({ file: "data/sales.csv", columns: ["amount", "3"] })

列名不确定时先用不带 columns 的 csv_stats，输出会标注每列下标与是否为数值列。

4. 解读输出

• 预览开头会标注 分隔符（自动嗅探或显式指定）与 总行数，出现“数据行超过 50000”提示说明统计只覆盖前 5 万行
• 统计里 非数值 N 个 表示该列有 N 个单元格无法识别为数字（含空单元格）
• median 在偶数个数值时取中间两数均值；std 为总体标准差
• 出现 [输出已截断] 标记说明内容不完整，缩小 rows 或 columns 后重试

5. 非逗号分隔的文件

自动嗅探覆盖 , ; Tab | 四种；嗅探错了（如单列文件里恰好含逗号）用 delimiter 显式指定：

csv_preview({ file: "data.tsv", delimiter: "\t" })

限制

• 输入上限 2MB / 5 万行（超出部分不计入统计并明确提示）
• 文件路径必须在工作目录内
• 不解析 Excel（.xlsx）二进制；需要时先转 CSV
• 唯一依赖 csv-parse（健壮的 RFC4180 解析）

测试

npm test

覆盖 4 种分隔符嗅探、引号切分、BOM/CRLF、短长行对齐、9 例数值识别、列名/下标选列、统计口径（中位数/标准差）、分页采样（head/tail/offset/越界）、多条件组合过滤（AND/OR/数值比较/非法输入）、路径越界拒绝等 65 项断言。

版本历史

0.3.0（2026-09-30）

• csv_filter 支持多条件组合：新增 conditions 数组与 logic（and/or），条件格式为「列名 操作符 值」，支持符号与英文操作符，column+value 单条件简写保持可用
• csv_preview 支持分页采样：新增 offset 与 order（head/tail），输出窗口行号范围与下一页 offset 提示，越界时给出空窗口说明
• 测试断言 45 → 65

0.2.0（2026-09-13）

• 新增 csv_filter 工具：eq/ne/gt/lt/ge/le/contains 条件过滤
• stats 对非数值列输出 topN 频次（默认 5）

Roadmap（v0.4 候选）

• 大文件流式处理（按行增量解析，突破单次读入上限）
• 结果排序与 Top N（sort_by + desc）
• 按列去重与唯一值枚举

源码与发布地址

• 源码：https://github.com/geeklei/dsh-plugins/tree/main/dsh-csv-explorer
• npm：https://www.npmjs.com/package/dsh-csv-explorer

典型场景

1. 大 CSV 先看结构再决定怎么处理

用户：这个 CSV 有哪些列、大概长什么样

csv_preview 输出表头、前若干行与列类型推断，避免一次性载入超大文件。

2. 数据体检

用户：这个表数据质量怎么样

csv_stats 给出各列的非空率、唯一值数、数值列的 min/max/均值，快速发现缺失与异常。

3. 按条件抽样核对

用户：看看金额大于 10000 的记录

csv_filter 按条件过滤并只返回命中的行，适合抽样验证。

4. 报表前的数据摸底

用户：这些数据能做出什么结论

先用 csv_stats 摸清分布，再决定是否需要 dsh-table-render 出表或 dsh-json-yaml-toolkit 转换格式。

安全边界

• 只读：仅解析与统计，不修改原 CSV 文件。
• 规模保护：预览与统计按行数上限截断，避免超大文件拖垮会话；截断会显式标注。
• 编码假定：默认按 UTF-8 读取；含 BOM 会自动处理，其他编码可能显示为乱码（不做隐式转码）。
• 不做类型强转：统计中的数字推断仅用于展示，不改变原始文本。

其他插件集成说明

| 协作插件 | 集成方式 | |---|---| | dsh-table-render | 预览/过滤结果可直接用 render_table 渲染为对齐表格（CJK 表头对齐） | | dsh-json-yaml-toolkit | convert_csv 负责 CSV↔JSON/YAML 互转，本插件负责"看"，两者互补 | | dsh-jsonl-stream（二期 D14） | 行式 JSON 用 jsonl-stream，表格型 CSV 用本插件 | | dsh-fs-inspector | 先用 dir_size/recent_files 定位目标 CSV，再进入本插件分析 | | dsh-hash-checksum | 对导出/转换后的文件计算摘要，确认处理前后一致 |

FAQ

Q：能处理几百万行的文件吗？ 可以解析，但预览与统计会按上限截断以保证响应速度；需要全量精确统计请先用 dsh-fs-inspector 评估文件规模。

Q：分隔符不是逗号怎么办？ csv_preview 支持指定分隔符（如 \t、;），会自动识别常见分隔符并回显所用分隔符。

Q：中文列名对齐有问题？ 交给 dsh-table-render 渲染即可，它按显示宽度（CJK 计 2 列）补齐。

Q：会修改我的文件吗？ 不会，本插件严格只读。