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

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

npm version
npm downloads
CI

面向 DeepSeek Harness 的确定性数据剖析、清洗与校验。

所有计算都是在 harness 进程中运行的纯 TypeScript 代码——模型从不参与数学运算。一个 ctx.dataQuality 能力接缝（Service Definition / 本地 Provider / tool Consumers）对外暴露三个模型工具，以及一份冻结的跨插件引用校验契约。

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

兼容性

| 组件 | 版本 |
|---|---|
| DeepSeek Harness | dsh-v0.1.6-alpha.2（适配于 2026-09-18）：peer 范围现在接纳 alpha.2 系列；在该系列中，Session.append 的第三个参数仅对 surface-eligible 类型存在，且是一个 SurfaceIntent，因此审计门控仍然跳过，存储域报告仍作为持久化副本保留。已于 2026-09-18 验证（双 typecheck 标尺 + 完整测试套件全绿）。 |
| 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 工具 — 数据集剖析：行/列计数、推断的列类型（数字/日期/布尔/字符串/空/混合）、缺失率、唯一值计数、数值分布（最小值/最大值/均值/中位数/p25/p75）、IQR 离群值计数、混合类型可疑提示，以及全表 sha256 内容哈希重复检测，包含重复率和有界的重复行索引样本。添加确定性的 DAMA 六维度评分卡（完整性、唯一性、有效性、一致性、及时性、准确性——在没有声明 schema 的情况下准确性报告为未确定，绝不捏造）。对大型文件可选进行确定性的系统抽样。
- data_clean 工具 — 有序的声明式清洗规则：dedupe（按列组）、fill-missing（常量/均值/中位数/前向填充）、coerce-type（数字/日期/布尔；失败计数并置为缺失）、normalize-unit（例如 万/亿 后缀转换为基本单位）、trim、map-values（枚举映射）。返回逐规则审计日志、交付前契约验证摘要（去重前/后、唯一性、非空和类型回归）以及有界预览；仅在给出 outputPath 时写入清洗后的数据集，且绝不覆盖源文件。
- data_verify 工具 — 声明式验证规则：not-null、unique、range、regex、enum、cross-column（例如 startDate .tgz
dsh plugin --profile web add ./dsh-data-quality-.tgz

Git 通道
sh
dsh plugin --profile web add github:YOUR_ORG/dsh-data-quality#

第一次 add 会失败，因为 pnpm 会阻止该包的 prepare 构建；将 pnpm 打印出的确切键复制到该 profile 的 pnpm-workspace.yaml 中，然后重新运行：
yaml
allowBuilds:
'dsh-data-quality': true

安装后重启该 profile（bundle 在重启时激活）。然后在一个包含 CSV 的工作区中向 agent 提问：

Profile holdings.csv，然后通过去除空白、按 fund_code 去重，并规范化 holding_value 列的万/亿单位来清洗它；最后验证 fund_code 唯一且非空。

安装与卸载
sh
dsh plugin --profile web add dsh-data-quality      # 安装（npm）——或上述形式
dsh plugin --profile web remove dsh-data-quality   # 卸载

配置

所有键均为可选（显示默认值）；无效值会在加载时明确报错。每个键都可以从 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/cleaning 摘要表（仅限 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? | 逐行比较：两侧均可解析时按数值比较，日期按 epoch 比较，字符串仅支持 ==/!=（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（供其他插件使用）
ts
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| （从不推送；tag 会触发 release.yml）。

主题

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

贡献者

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

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

本仓库目前还没有公开的 issue 或 pull request 历史；随着它们陆续到来，各个 PR/issue 编号将在此处注明。

PerryLink DSH 插件家族

本项目是由 PerryLink 维护的 40 个 DeepSeek Harness 插件之一。如果这个对你有帮助，其他的很可能也会：

| dsh-budget | DeepSeek Harness 的成本治理：预算、碳排与延迟集于一个面板。 | |

| 插件 | 一句话简介 |
|---|---|
| dsh-auto-review | 审批链上的第二模型自动审查，默认故障关闭 | |
| dsh-autotier | 自动强/廉价模型层级路由，带确定性风险防护和 /tier 命令 | |
| dsh-background-agents | 持久化后台子代理，带 Web UI 侧边栏、消息传递与中断 | |
| dsh-catalog | PerryLink 家族的 DSH Desktop Market 标准目录源 | |
| dsh-cert-mcp | 只读 MCP 服务器，暴露认证注册表：等级、快照与五维证据 | |
| dsh-checkpoint-rewind | 统一的会话 + 工作区 + 配置检查点，一键 /rewind | |
| dsh-claude-move | 将 Claude Code、Codex、OpenCode 和 Hermes 的会话、记忆与技能迁移到 DSH | |
| dsh-click | 面向 DeepSeek Harness 的跨平台原生桌面控制——优先支持 Windows。 | |
| dsh-composer-history | 为 Web 输入框提供终端风格的输入历史：方向键、Ctrl+R 搜索 | |
| dsh-defend | 为 DeepSeek Harness 提供提示注入、越狱和机密泄露防御。 | |
| dsh-doublecheck | 工程纪律守卫：需求拷问、测试门禁、对抗性审查 | |
| dsh-draw | 面向 DeepSeek Harness 的统一静态图像生成路由。 | |
| dsh-fast | 只读性能诊断：负载、溢出、压缩和缓存命中率 | |
| dsh-fund-research | 中国公募基金研究，附带密封、可追溯的来源快照 | |
| dsh-github | GitHub PR/issue/CI 集成，所有写入操作均需审批 | |
| dsh-industry-research | 行业与公司研究包：产业链图谱、政策时间线、公司卡片 | |
| dsh-kit | 一键安装核心套件的入门包 | |
| dsh-library | 本地文档知识库，支持混合搜索和引用感知注入 | |
| dsh-local-ai | 本地 Ollama 模型发现与基于任务的路由，支持云端回退 | |
| dsh-lsp-actions | LSP 诊断、格式化、补全、代码操作、符号和重命名 | |
| dsh-mask | 在模型边界进行 PII 脱敏，并配有宿主侧还原表 | |
| dsh-mcp-panel | MCP 管理控制台：/mcp 命令、设置标签页和试调用 | |
| dsh-memento | 需审批的跨会话记忆协议（ctx.memory + SQLite） | |
| dsh-observe | 从会话事件流导出 OpenTelemetry 和 Langfuse 遥测数据 | |
| dsh-output-styles | 可在运行时切换的模型输出风格 | |
| dsh-permission-rules | 声明式允许/拒绝/询问规则，外加进程级网络策略 | |
| dsh-plugin-certification | 社区认证注册表，附带可复现检查的等级和徽章 | |
| dsh-plugin-doctor | 面向 DSH 插件的零依赖静态 + 沙箱冒烟检测器 | |
| dsh-plugin-guide | 插件开发知识库、agent skill 以及 dsh-plugin-dev CLI 工具链 | |
| dsh-plugin-kit | 面向 PerryLink DSH 插件的共享零运行时依赖工具包 | |
| dsh-plugin-portal | 零依赖静态门户，将整个插件家族渲染为单个页面 | |
| dsh-plugin-upgrade-015 | 合并 0.1.3-alpha.1 → 0.1.5-rc.1 升级通道卡片，外加零依赖接缝扫描器 | |
| dsh-reach | 多渠道审批/提问桥接：微信、Telegram、飞书 + 会话控制台 | |
| dsh-research-report | 可验证的研究报告：证据台账、清单密封、逐条断言裁定 | |
| dsh-score | 多维插件质量评分，附带基于证据的排行榜 | |
| dsh-session-pin | 在 Web 侧边栏中固定会话和工作区，支持每个固定项独立配色 | |
| dsh-session-sync | 基于 Git 的跨设备会话同步，支持保留双方的合并方式 | |
| dsh-skill-pack-security | 安全审计技能包，外加 plugin_vet 供应链门禁 | |
| dsh-talk | 语音优先的会话循环：语音转文字输入与文字转语音回复 | |
| dsh-team-rooms | 跨会话团队房间：共享消息总线、任务看板与时间线 | |
| dsh-test-drive | 隔离的安装与冒烟测试试驾，附带通过/失败矩阵 | |
| dsh-ticktick | TickTick/滴答清单任务桥接：会话头部面板外加十一个 agent 工具 | |
| dsh-translate | 厂商参数转换与确定性 JSON 修复 | |
| dsh-wechat | 微信 ↔ DSH 桥接（腾讯 iLink 机器人），与 pan17 共同开发，由其托管仓库 | |
| dsh-personal-directive | 个人指令注入器，带顶栏开关（liucai2026/dsh-personal-directive 的 fork） | |