数据质量剖析 PerryLink/dsh-data-quality

dsh-data-quality

为 DeepSeek Harness 提供确定性的数据剖析、清洗与校验。

- 1024 商店渠道：先执行一次 npm i -g dsh1024，再执行 dsh1024 plugin --profile web add dsh-data-quality（计入 deepseek1024.com 的安装排名）。

dshfind

dsh-doctor
DSH Market

为 DeepSeek Harness 提供确定性的数据剖析、清洗与校验。

所有计算都是 harness 进程里的纯 TypeScript 代码 —— 模型从不参与算数。ctx.dataQuality 能力接缝（服务定义 / 本地服务商 / 工具消费方）对外暴露三个模型工具，外加一份冻结的跨插件引用校验契约。

English · 简体中文 · Español · Português · हिन्दी

dsh plugin --profile <name> add dsh-data-quality

📖 生态知识库 —— 实测数据，不是营销话术：插件开发指南 · 插件选型数据 · 维护标准。

安装与卸载

dsh plugin --profile web add dsh-data-quality # install (npm) — or the forms above
dsh plugin --profile web remove dsh-data-quality # uninstall

⭐ 如果它帮到了你

这个插件是 DSH 插件家族的一员（95 个，全部 Apache-2.0）。如果你在用，给个 star —— 它不会解锁任何功能，但会让下一个人在搜索里更容易找到它。

English: part of a 95 plugin family for DeepSeek Harness. If it is useful, a star helps the next person find it — nothing is gated behind it.

dsh-data-quality 是什么？

为 DeepSeek Harness 提供确定性的数据剖析、清洗与校验。

dsh-data-quality 的工作流示意图：问题 → 封存的数据源 → 报告。
工作流总览：提问 → 封存数据源 → 报告。下面示例用的都是真实命令接口。

对比

dsh-data-quality 实测对比图

fixtures/dirty-fund-holdings.csv（10 行 × 6 列）· 5 个可判定维度 · 本地运行

兼容性

| 组件 | 版本 |
| DeepSeek Harness | dsh-v0.2.1-alpha.1（2026-10-04 适配）：peer 范围现在接纳 alpha.2 系列；在 alpha.2 中，Session.append 的第三个参数只对 surface-eligible 类型存在，且类型为 SurfaceIntent，因此审计门仍然跳过，存储域报告仍是持久副本。2026-09-24 验证（双类型检查基准 + 全量测试套件通过）。 |
| Node.js | ^22.19.0 \|\| >=24.0.0 |
| 包管理器 | pnpm@11.7.0 |
| 平台 | Windows / macOS / Linux（仅宿主插件） |

你能得到什么

- ctx.dataQuality 服务 —— 一个 Cordis 服务，其他插件可以选择消费（inject = ['dataQuality']）。除了工具背后的三个数据集操作，它还实现了冻结的 verifyCitations(request) 契约：校验文档中引用的数字/字符串是否与数据集快照一致，数字比较采用相对容差，状态分为 verified / mismatch / not-found / unverifiable。
- data_profile 工具 —— 数据集画像：行数/列数、推断的列类型（number/date/boolean/string/empty/mixed）、缺失率、唯一值计数、数值分布（min/max/mean/median/p25/p75）、IQR 离群值计数、混合类型可疑提示，以及全表 sha256 内容哈希重复检测，给出重复率和有界的重复行索引样本。附带确定性的 DAMA 六维评分卡（完整性、唯一性、有效性、一致性、及时性、准确性 —— 未声明 schema 时准确性报告为未判定，绝不编造）。对大文件可选确定性的系统抽样。
- data_clean 工具 —— 有序的声明式清洗规则：dedupe（按列组）、fill-missing（常量/均值/中位数/前向填充）、coerce-type（number/date/boolean；失败计数并置为缺失）、normalize-unit（例如把 万/亿 后缀换算为基础单位）、trim、map-values（枚举映射）。返回逐规则审计日志、交付前的契约校验摘要（去重前后、唯一性、非空与类型回归），以及有界预览；只有给了 outputPath 才写出清洗后的数据集，且绝不覆盖源文件。
- data_verify 工具 —— 声明式校验规则：not-null、unique、range、regex、enum、cross-column（例如 startDate < endDate）、freshness（日期列距参考日期在 N 天内）。逐规则给出通过/失败，失败行证据有上限；整体失败是正常的 passed: false 结果，不是工具错误。
- data_report 工具 —— 从 data_quality 存储域读回已持久化的报告：按精确的 reportKey 读取（做路径安全校验，键不存在就直接报错），或按 kind 读取（按时间顺序列出）。返回报告信封——kind、dataset、时间戳，以及完整存储的报告。format: html 把单份 profile/clean 报告渲染成自包含的离线 HTML 文档（内联 CSS/JS，不发外部请求），带 DAMA 六维评分卡和 profile/清洗摘要表。
- 持久化报告 —— 每次 profile/clean/verify/citation 运行都会持久化到 data_quality 存储域（JSON 后端），键由运行时间戳加数据集路径指纹构成；该键在工具结果里以 reportKey 返回。clean 报告还会持久化有界预览和契约摘要，因此每个模型可见的结果都能从它的 reportKey 重建；每次 clean 运行还会额外持久化一份 clean-diff 前后 profile 报告。
- 会话事件 —— 在能安全承载的宿主上，运行会追加 data-quality/profile / data-quality/clean / data-quality/verify 事件（支持时带 ignorable 标记）。在已发布的 0.1.7-rc.2 线上（与更早的 rc 线一致），追加按设计跳过——存储域报告始终是持久副本（见「已知限制」）。

快速开始

dsh plugin --profile web add github:PerryLink/dsh-data-quality

npm 渠道

dsh plugin --profile web add dsh-data-quality

Tarball 渠道（无需构建权限）

pnpm pack # produces dsh-data-quality-<version>.tgz
dsh plugin --profile web add ./dsh-data-quality-<version>.tgz

Git 渠道

dsh plugin --profile web add github:YOUR_ORG/dsh-data-quality#<commit-sha>

第一次 add 会失败，因为 pnpm 拦截了包的 prepare 构建；把 pnpm 打印出的确切键复制到配置档的 pnpm-workspace.yaml，再重跑：

allowBuilds:
'dsh-data-quality': true

安装后重启配置档（bundle 在重启时激活）。然后在一个含 CSV 的工作区里对智能体说：

Profile holdings.csv，然后清洗它：去掉空白、按 fund_code 去重、把 holding_value 列的万/亿单位归一化；最后校验 fund_code 唯一且非空。

示例

这些是插件的真实入口；安装一次，然后调用其中一个。

详细示例

命令

~~~sh
data_profile({ path: "dirty-fund-holdings.csv" })

输出

~~~text
Profile of dirty-fund-holdings.csv: 10 rows x 6 columns
Duplicate rows: 1 (10.0%); sample row indexes: 8
- nav: mixed; missing 1 (10.0%); unique 7; note: mixed types among 9 present values: 8 numeric, 1 string
Scorecard (overall 93.2%, weighted 93.2%):

摘自 README.md:147-149; test/profile.spec.ts:130-132; test/loader.spec.ts:98-99; src/profile.ts:311-315

失败分支

输入

~~~text
dirty-fund-holdings.csv 的规则：

~~~json
{"path":"dirty-fund-holdings.csv","rules":[{"rule":"dedupe","columns":["nope"]}]}

输出

~~~text
isError=true; error.message=rule 0: unknown column "nope" (columns: fund_code, fund_name, nav, nav_date, holding_value, currency)

来源：plugins/dsh-data-quality/src/clean.ts:66-68; plugins/dsh-data-quality/fixtures/dirty-fund-holdings.csv; exercised through plugins/dsh-data-quality/test/harness.ts

简要示例

- data_clean
- data_verify

配置

所有键都可选（默认值见下表）；值不合法会在加载时直接报错。每个键都能在 cordis.yml 里设置（bundle 自带 cordis.patch.yml，默认值相同）。

| 键 | 默认值 | 说明 |
| enabled | true | 总开关；设为 false 时什么都不挂载。 |
| maxRows | 200000 | 每次加载数据集的硬性行数上限；超出直接报错（改用工具的 sample 参数）。 |
| maxFileSizeMB | 64 | 每次加载数据集的硬性文件大小上限，单位 MiB。 |
| defaultTolerance | 1e-9 | 引用省略 tolerance 时，数值引用比对使用的默认相对容差。 |
| evidenceRowLimit | 20 | 单次结果里失败行证据（verify）和预览行（clean）的上限。 |
| allowedExtensions | ['.csv', '.tsv', '.json', '.jsonl'] | 可作为数据集接受的扩展名。 |
| workspaceRoot | "" | SERVICE 级调用（如 verifyCitations）的绝对根目录，这类调用不带会话工作区；留空表示 harness 进程的启动目录。工具调用始终使用会话工作区的 cwd。 |
| storeReports | true | 把运行报告持久化到 data_quality 存储域，并返回 reportKey。 |
| scorecardWeights | 全部为 1（等权） | 评分卡加权总分的各维度权重（completeness/uniqueness/validity/consistency/timeliness/accuracy）；每个权重必须是非负数。 |

工具与接口

data_profile({ path, sample?, industryPreset? })

对工作区里的数据集做画像。path 是工作区相对路径（.csv/.tsv/.json/.jsonl；JSON 必须是扁平对象组成的数组）。sample 每隔 ceil(N/sample) 行取一行做列卡片（结果确定；行数仍保持精确）。industryPreset（retail/saas/fund/real-estate/e-commerce/healthcare/logistics/manufacturing/energy）会注入该行业预期的列，让评分卡的 accuracy 维度可以判定；未知 id 直接报错。返回结构化报告——重复率、有界的重复行索引、数值列的 count/distinct 分布、文件 encoding（UTF-8 BOM + 有效性），以及加权六维 DAMA 评分卡——并渲染出人可读的逐列摘要和评分卡。

data_clean({ path, rules, outputPath?, dryRun? })

按数组顺序应用 rules，每条规则看到的是上一条规则的输出。规则参考：

| 规则 | 额外字段 | 语义 |
| dedupe | columns? | 删除键列值与更早行重复的行（保留第一行；省略时使用全部列）。 |
| fill-missing | column、strategy、value? | 填充缺失单元格：constant（需要 value）、mean/median（数值列）、forward（前一个非缺失值）。 |
| coerce-type | column、to | 强制转换为 number/date（ISO）/boolean；转换失败的值变为缺失，并计入日志。 |
| normalize-unit | column、factors | 去掉单位后缀再相乘（{"万": 10000, "亿": 100000000}）；纯数字也会转换。 |
| trim | columns? | 去除字符串单元格首尾空白（省略时使用全部列）。 |
| map-values | column、map、else? | 精确匹配映射；未映射的值保持原样（keep，默认）或变为 missing。 |

源文件绝不会被覆盖。指定 outputPath 时，清洗后的数据集写入该路径（限定在工作区内，格式由扩展名决定）；不指定则只做预览。设置 dryRun: true 时不写文件、不持久化任何内容——结果返回逐列清洗计划和预期的 contract/diffPreview。结果还带有交付前的 contract 摘要（去重前后行数、去重键或整行的唯一性、fill-missing 列的非空回归、coerce-type 列的类型回归，以及逐列决策轨迹），并把 clean-diff 前后对比报告持久化到存储域。

data_report({ key?, kind?, format? })

从存储域读回已持久化的报告。传 key（先前某次运行返回的准确 reportKey）获取单份报告，或传 kind（profile/clean/clean-diff/verify/citations）按时间顺序列出该类型的全部报告；key/kind 必须且只能给一个。键格式错误或缺失会直接报错。format: html（配合 key）把报告渲染成自包含的离线 HTML 文档——内联 CSS/JS、无外部请求、DAMA 六维评分卡，以及 profile/清洗摘要表（仅 profile/clean 报告）。

data_verify({ path, rules, expectations? })

执行校验规则。规则参考：

| 规则 | 额外字段 | 语义 |
| not-null | column | 缺失单元格（null/空/空白）判失败。 |
| unique | columns | 键组合重复的每一行都判失败（缺失值也参与）。 |
| range | column、min?、max? | 缺失/无法解析的单元格以及超出闭区间边界的值判失败（至少给一个边界）。 |
| regex | column、pattern、flags? | 缺失或不匹配的单元格判失败（完整 JS 正则）。 |
| enum | column、values | 去除首尾空白后的文本不在列表中的单元格判失败。 |
| cross-column | left、op、rightColumn?、value? | 逐行比较：两侧都能解析时按数值比较，日期按时间戳比较，字符串仅支持 ==/!=（rightColumn/value 必须且只能给一个）。 |
| freshness | column、maxAgeDays、asOf? | 日期早于 asOf（默认：当前时间）往前推 maxAgeDays 天就判失败；无法解析或缺失也判失败。 |

expectations 把确定性指标与期望值比对：rowCount、columnSum、columnMean、uniqueCount、nullCount（除 rowCount 外都带 column，另加 expected 和可选的相对 tolerance，取值 [0, 1]）。每条期望产出 passed，外加 actual/expected/tolerance；不匹配是正常的 passed: false 判定，绝不是工具错误。指标非法、列缺失、容差越界都会直接报错。

单元格缺失时，读取它的每条规则都判失败。证据按每条规则最多保留 evidenceRowLimit 行失败记录。

ctx.dataQuality（供其他插件使用）

const result = await ctx.dataQuality.verifyCitations({
dataset: 'holdings.csv', // resolved against workspaceRoot
citations: [
{ id: 'c1', path: 'rows[3].nav', value: 1.234, tolerance: 0.01 },
{ id: 'c2', path: 'summary.annualReturn', value: '12.34%' },
],
})
// result.results[i] = { id, status: 'verified' | 'mismatch' | 'not-found' | 'unverifiable', actual?, note? }

定位符沿数据集文档逐层查找：CSV/TSV 加载为 { columns, rows }（所以 rows[3].nav 能解析），JSON 就是解析后的值，JSONL 是解析后各行组成的数组。数字按相对容差比较（|a-b| <= tolerance * max(|a|, |b|)）；CSV 字符串单元格若能解析成数字，就按数字比较；字符串精确比较；类型无法互比的组合判为 unverifiable。该服务还暴露 profileDataset / cleanDataset / verifyDataset（与工具调用的是同一套操作）。

权限与数据

- 读取工作区数据集文件（仅限允许列表中的扩展名）。
- 只写入：data_clean 的输出文件（显式 outputPath，限制在工作区内，绝不写输入文件），以及 harness 数据目录下 data_quality 存储域中的报告。
- 无网络、无凭据、无外部进程 —— 所有解析和统计都在进程内的 TypeScript 中完成。
- 报告可能包含你数据集里的样本单元格值（受 evidenceRowLimit 和显示截断限制）；会话日志照常记录工具参数和结果。

安全边界

- 路径限制 —— 数据集和输出路径必须解析到会话工作区内（verifyCitations 用 workspaceRoot）；.. 逃逸和外部绝对路径一律拒绝，比较前两边都会规范化（Windows 下斜杠安全）。
- 工作量有界 —— maxRows / maxFileSizeMB 守卫会直接拒绝超大输入；中止信号可在流式加载中途取消长时间加载。
- 不覆盖 —— data_clean 拒绝 outputPath 与输入路径相同。
- 确定性计算 —— 相同输入，相同输出；唯一的时钟来源是为 freshness 默认值和报告时间戳注入的那个。

已知限制

- 会话事件自适应。 已发布的 0.1.7-rc.2 版本（和更早的 rc 版本一样）没有插件会话事件注册接口，它的 Session.append 也无法打上 ignorable 标记。因此，追加未知的 data-quality/* 类型会让会话日志在恢复时无法读取。所以，只有当宿主认识这套词汇，或支持 ignorable 追加标志时，插件才会追加；在已发布版本上，存储域报告才是持久记录。
- CSV 方言 —— 逗号或制表符分隔，遵循 RFC-4180 引号规则，必须有表头行，跳过空行，不自动检测分隔符，不支持注释行。
- 类型解析是严格的 —— 数字不带千位分隔符；日期为 YYYY-MM-DD / YYYY/MM/DD / 类 ISO 日期时间（UTC）；布尔值为 true/false/yes/no/1/0。其余一律归为 string/mixed —— 如果本意是别的类型，用 coerce-type 清洗。
- JSON 必须是表格形式，工具才能处理（扁平对象数组）；verifyCitations 可以遍历任意 JSON 文档。
- 没有机器学习异常检测，没有 PII 脱敏，没有数据库，没有 SQL —— 只有基于规则的疑点提示。

开发

pnpm install
pnpm run typecheck && pnpm run typecheck:ci && pnpm run typecheck:checkout && pnpm test && pnpm run build
pnpm run verify:self-contained && pnpm run verify:artifacts && pnpm run verify:readme-sync && pnpm pack

- 测试用 vitest 针对 0.1.7-rc.2 对等依赖中真实的 Context/Session/ToolRuntime/存储域运行（不用手写的服务 mock），外加纯引擎规格；每条 clean/verify 规则都有正例和反例，verifyCitations 覆盖全部四种状态。
- scripts/loader-runner.mjs 启动真实的 Loader 组合，无需 API key 即可对 fixtures/ 执行 profile → clean → verify 链路。
- 发布：node scripts/release.mjs <x.y.z>（从不推送；由 tag 触发 release.yml）。

主题

dsh · dsh-plugin · deepseek-harness · cordis · data-quality · data-cleaning · data-profiling · data-verification

贡献者

感谢每一位塑造了这个插件的人。

- PerryLink —— 维护与发布（0.1.2/0.1.3）、对等依赖升级、npm 版本/下载量/CI 徽章，以及近期的修复。
- dsh-data-quality 贡献者 —— 初始脚手架、ctx.dataQuality 接缝与冻结的 verifyCitations 契约、确定性数据集层与纯引擎、data_quality 存储域报告、真实服务 vitest 测试套件、CI/兼容/发布工作流，以及五种语言的 README。

这个仓库还没有公开的 issue 或 pull request 历史；等有 PR/issue 编号后，会在这里逐一署名。

PerryLink DSH 插件家族

本项目属于 PerryLink 的 DeepSeek Harness 插件家族。下方名册默认折叠，让每个 README 的首屏都保持简短；展开即可看到每一行及其状态。

展开全部插件

| 插件 | 状态 |
| dsh-aqua-input-check | |
| dsh-archive-check | |
| dsh-auto-review | |
| dsh-autotier | |
| dsh-bid-ca-precheck | |
| dsh-bid-qual-check | |
| dsh-cert-mcp | |
| dsh-checkpoint-rewind | |
| dsh-click | |
| dsh-composer-history | |
| dsh-contract-stance | |
| dsh-customs-doc-check | |
| dsh-data-quality | |
| dsh-demurrage-ledger | |
| dsh-doublecheck | |
| dsh-drill-script-check | |
| dsh-eia-guide-check | |
| dsh-emergency-plan | |
| dsh-essay-rubric-check | |
| dsh-evidence-check | |
| dsh-export-ctl-check | |
| dsh-fast | |
| dsh-fmea-table-check | |
| dsh-forecast-penalty | |
| dsh-fund-research | |
| dsh-github | |
| dsh-gongwen-flow-check | |
| dsh-gongwen-word-check | |
| dsh-guard-plan-qc | |
| dsh-hazchem-check | |
| dsh-hazplan-check | |
| dsh-hidden-risk-map | |
| dsh-hs-classify | |
| dsh-icd-rule-check | |
| dsh-industry-research | |
| dsh-lawcite-adapter | |
| dsh-laya | |
| dsh-lc-doc-check | |
| dsh-learning-gap-check | |
| dsh-library | |
| dsh-local-ai | |
| dsh-lsp-actions | |
| dsh-mask | |
| dsh-mcp-panel | |
| dsh-medrec-qc | |
| dsh-memento | |
| dsh-nsfc-form-check | |
| dsh-nurse-record-check | |
| dsh-observe | |
| dsh-origin-rvc-check | |
| dsh-ota-review-check | |
| dsh-output-styles | |
| dsh-paper-doc-adapter | |
| dsh-permission-rules | |
| dsh-permit-report-check | |
| dsh-pipeline-check | |
| dsh-pleading-draft | |
| dsh-plugin-doctor | |
| dsh-plugin-guide | |
| dsh-plugin-kit | |
| dsh-plugin-upgrade | |
| dsh-policy-brief-draft | |
| dsh-power-loss-split | |
| dsh-power-ticket-check | |
| dsh-ppap-check | |
| dsh-protest-deadline | |
| dsh-railway-window | |
| dsh-repair-order-qc | |
| dsh-research-report | |
| dsh-review-reply-check | |
| dsh-rulefile-check | |
| dsh-safety-brief-check | |
| dsh-score | |
| dsh-session-sync | |
| dsh-site-log-check | |
| dsh-skill-pack-security | |
| dsh-soe-decision-check | |
| dsh-soilwater-check | |
| dsh-sop-sync-check | |
| dsh-spc-gbt-adapter | |
| dsh-talk | |
| dsh-tender-extract | |
| dsh-tender-matrix | |
| dsh-test-drive | |
| dsh-ticktick | |
| dsh-translate | |
| dsh-warranty-calc | |
| dsh-budget | 🧊 已冻结 —— 见仓库 README |
| dsh-claude-move | 🧊 已冻结 —— 见仓库 README |
| dsh-defend | 🧊 已冻结 —— 见仓库 README |
| dsh-draw | 🧊 已冻结 —— 见仓库 README |
| dsh-reach | 🧊 已冻结 —— 见仓库 README |
| dsh-background-agents | 🚫 已退役 —— 见仓库 README |
| dsh-session-pin | 🚫 已退役 —— 见仓库 README |
| dsh-team-rooms | 🚫 已退役 —— 见仓库 README |