dsh-data-clean
v0.1.0
Published
Tabular dirty-data cleaning plugin for DeepSeek Harness: column type inference (boolean/integer/number/date/string/mixed with real-calendar date validation), a cleaning pipeline (trim, null-token normalization, safe numeric/boolean coercion, drop empty ro
Maintainers
Readme
dsh-data-clean
面向 DeepSeek Harness 生态的表格脏数据清洗插件(零运行时依赖):列类型推断、清洗流水线(去空白 → 空值归一 → 类型宽容转换 → 删全空行 → 填充 → 去重)、只读数据质量报告。全程内存内操作、不碰磁盘、不改原始输入。
- 源码:https://github.com/geeklei/dsh-plugins/tree/main/dsh-data-clean
- npm:https://www.npmjs.com/package/dsh-data-clean
- 协议:MIT
功能说明
| 工具 | 作用 | 返回 |
|---|---|---|
| infer_schema | 列类型推断 | 每列类型(boolean/integer/number/date/string/empty/mixed)、类型构成、缺失数/率、唯一数/率、常量列标记、数值列 min/max、样本值 |
| clean_rows | 清洗流水线 | 清洗后的行 + 逐项统计(去空白、空值归一、类型转换、填充、删行) |
| dirty_report | 数据质量报告(只读) | 整表完整度/重复行/全空行 + 逐列问题与可执行建议 |
核心口径:
- 输入形态:对象数组(推荐,
[{a:1,b:"x"},...])或数组数组(配可选header,缺省列名c0..cn) - 缺失定义:
null/undefined/空串/纯空白/命中null_tokens(默认["", "n/a", "na", "null", "none"],大小写不敏感)统一归一为null - 类型推断按列聚合:integer 与 number 混合归并为
number;其余混合标mixed并给出构成(如integer×4、string×1) - 日期识别:
YYYY-M-D、YYYY/M/D、ISO 日期时间,且做真实日历校验(2026-02-30不算日期,按字符串处理) - 宽容转换只做安全项:数值串→数值、
"true"/"false"→布尔;"12,000"(千分位)、"0x1A"(十六进制)、"yes"一律不转,防误读 - 去重与键序无关:内容相同、键顺序不同的行视为重复,保留首行
安装
# 从 npm 安装
dsh plugin --profile web add dsh-data-clean# 本地开发调试(Debug patch):新建 debug.patch.yml
# - insert:
# - id: data-clean
# name: "E:/dsh-plugins/dsh-data-clean/index.js"使用说明
1. infer_schema —— 列类型推断
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| rows | array | 必填 | 行数据:对象数组或数组数组 |
| header | array | 可选 | 数组数组输入时的列名 |
| null_tokens | array | ["", "n/a", "na", "null", "none"] | 视为缺失的字符串标记 |
// 输入 [{id:1,age:"34"},{id:null,age:"abc"}] 输出(节选)
{
"rowCount": 2,
"columns": [
{ "name": "id", "type": "integer", "missing": 1, "missingRatio": 0.5, "unique": 1 },
{ "name": "age", "type": "mixed", "kinds": { "integer": 1, "string": 1 } }
]
}2. clean_rows —— 清洗流水线
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| rows | array | 必填 | 行数据 |
| header | array | 可选 | 数组数组输入时的列名 |
| trim | boolean | true | 去字符串首尾空白 |
| coerce | boolean | true | 数值串/布尔串宽容转换 |
| dedupe | boolean | true | 删除重复行(保留首行) |
| drop_empty | boolean | true | 删除全空行 |
| fill | object | {} | 列名 → 填充值,只填缺失单元格 |
| null_tokens | array | 见上 | 缺失标记 |
处理顺序:去空白 → 空值归一 → 宽容转换 → 删全空行 → 去重 → 填充。统计口径:去空白/归一/转换计数含后被去重的行;填充只发生在存留行上。不修改原始输入(重建行对象)。
3. dirty_report —— 数据质量报告(只读)
参数同 infer_schema。输出整表 completeness(完整度)、duplicateRows、emptyRows,逐列问题与建议:
- 缺失少量值 → 建议用
clean_rows的fill填充 - 缺失过半 → 建议评估删列或补采
- 类型混杂 → 建议
coerce收敛 - 常量列 → 建模前可剔除
- 全唯一字符串列 → 疑似 ID 列,勿作特征
- 唯一率 <5% 且非常量 → 可作分类变量
典型场景
- 接手一口来路不明的 Excel/CSV 导出:先
dirty_report看整体质量,再infer_schema确认每列真实类型,最后clean_rows一次洗净——顺序固定:先报告后清洗 - 给 dsh-stats-toolkit 喂数据:stats-toolkit 严格要求有限数字(不做隐式转换),脏数据先过
clean_rows(coerce 收敛数值串、归一缺失),再用describe_stats/detect_outliers - 合并多来源同构表:各来源空值习惯不同(
""/"-"/"N/A"),用null_tokens统一归一后dedupe去重 - 建库前的 schema 草案:
infer_schema输出每列类型与唯一率,直接作为建表 DDL 的类型参考
安全边界
- 纯内存:不读文件、不联网、不写磁盘;数据由调用方(宿主/Agent)读入后传入
- 不改原始输入:清洗结果是新对象数组,原 rows 恒不变
- 转换保守:只做无损可逆的安全转换;千分位、十六进制、货币符号、日期→Date 均不自动处理,宁可保留原样
- 不带业务语义:
"yes"/"no"、中文布尔("是"/"否")不在默认转换范围(避免误判),可用null_tokens与预处理配合 - 大表注意:O(rows×cols),万行级无压力;十万行级建议分块
版本说明
- 0.1.0(2026-10-23):首版。
infer_schema/clean_rows/dirty_report三工具;150 测试断言(真实 dsh-tools 包装层环境全绿) - 已知边界:日期只识别公历(不处理农历/时区归一);
fill不做插值(只填常量);去重是精确匹配(不做模糊去重)
RoadMap
- v0.2:日期列归一输出(统一
YYYY-MM-DD);fill: "ffill"/"bfill"前向/后向填充;分块流式处理 - v0.3:模糊去重(编辑距离阈值);枚举列候选值收敛(
"男"/"M"/"male"归一);数值列边界校验(min/max 规则) - v0.4:与 dsh-xlsx-lite 联动的端到端清洗(读表→报告→清洗→回写)
其他插件集成说明
- dsh-stats-toolkit:黄金搭档。
clean_rows(coerce)→describe_stats/detect_outliers;严格数值口径由本插件前置保证 - dsh-xlsx-lite:
read_xlsx读出的对象数组直接喂dirty_report/clean_rows,洗净后可write_xlsx回写 - dsh-sql-query:清洗后的行数组作为
sql_query的数据源,WHERE/GROUP BY 前先归一空值 - dsh-expr-engine:
eval_column逐行计算前,用infer_schema确认列类型避免文本数字干扰 - 与 dsh-dedupe 类工具的分工:本插件做行级精确去重并连带整条清洗链;模糊/近似去重不在 v0.1 范围(RoadMap v0.3)
FAQ
Q1:为什么 "12,000" 不自动转成 12000?
千分位与多国Locale 语义冲突(德语里逗号是小数点)。自动转可能造成静默的数据损坏,本插件宁可保守。需要时先自行 replace 再传入。
Q2:"是"/"否" 能转布尔吗?
v0.1 不转(避免中文语义误判风险)。可以先用 null_tokens 思路自行预处理,RoadMap v0.3 的枚举收敛会覆盖此场景。
Q3:去重为什么保留首行?
与 pandas drop_duplicates(keep="first") 惯例一致。首行通常是最早/最权威的记录。
Q4:fill 能填计算值吗(如均值)?
v0.1 只填常量。均值/中位数填充属于统计口径决策,建议配 dsh-stats-toolkit 先算出值再传入 fill。
Q5:为什么空字符串和 "null" 字符串都变成 null?
真实数据里它们几乎总是"没填"。若你的业务把它们当合法字符串,用 null_tokens: [] 关闭归一(注意:空串/纯空白仍按缺失处理,这是硬口径)。
Q6:mixed 列 coerce 后还是 mixed 怎么办?
coerce 只收敛数值/布尔串;"abc" 这类真文本会保留。用 dirty_report 的类型构成看清楚混了什么,再决定删列、拆列或补数据。
许可证
MIT
