GoldenCheck

已迁移。 此仓库已迁移至 benzsevern/goldenmatch 单体仓库中的 packages/python/goldencheck (and packages/typescript/goldencheck)/。此仓库已归档；后续开发将在单体仓库中进行。

GoldenCheck

数据验证工具，可从数据中发现规则，让你无需手动编写。 由 Ben Severn 构建。

每个竞品都要求你先编写规则。GoldenCheck 则反其道而行：先验证，再保留你关心的规则。

为什么选择 GoldenCheck？

	GoldenCheck	Great Expectations	Pandera	Pointblank
规则	从数据中发现	手动编写	手动编写	手动编写
配置	零配置即可开始	繁重的 YAML/Python 设置	装饰器/模式	YAML/Python
界面	CLI + 交互式 TUI	HTML 报告	异常	HTML/笔记本
学习曲线	一条命令	数小时/数天	中等	中等
大模型增强	支持（每次扫描 $0.01）	不支持	不支持	不支持
修复建议	支持，在 TUI 中提供	不支持	不支持	不支持
置信度评分	支持（每项发现标记 H/M/L）	不支持	不支持	不支持
DQBench 得分	88.40	21.68（尽力而为）	32.51（尽力而为）	6.94（自动）

安装

pip install goldencheck

支持 LLM 增强：

pip install goldencheck[llm]

支持深度分析和基线（scipy、numpy）：

pip install goldencheck[baseline]

支持基线语义类型推断（sentence-transformers）：

pip install goldencheck[baseline,semantic]

JavaScript / TypeScript

npm install goldencheck

适用于边缘环境的核心（浏览器、Cloudflare Workers、Vercel Edge）：

import { scanData, TabularData } from "goldencheck/core";

Node.js（文件读取、CLI、MCP）：

import { readFile, scanData } from "goldencheck/node";

快速开始

# Scan a file — discovers issues, launches interactive TUI
goldencheck data.csv

# CLI-only output (no TUI)
goldencheck data.csv --no-tui

# With LLM enhancement (requires API key)
goldencheck data.csv --llm-boost --no-tui

# Validate against saved rules (for CI/pipelines)
goldencheck validate data.csv

# JSON output for CI integration
goldencheck data.csv --no-tui --json

# Learn baseline (one-time, deep analysis)
goldencheck baseline data.csv

# Scan with drift detection (fast, uses saved baseline)
goldencheck scan new_data.csv

TypeScript 快速开始

// Scan an array of records (edge-safe — works anywhere)
import { scanData, TabularData, Severity } from "goldencheck";

const data = new TabularData([
  { id: 1, email: "[email protected]", age: 30, status: "active" },
  { id: 2, email: "[email protected]", age: -5, status: "inactive" },
  { id: 3, email: "not-an-email", age: 25, status: "active" },
]);

const { findings, profile } = scanData(data);
for (const f of findings) {
  console.log(`[${f.severity === Severity.ERROR ? "ERROR" : "WARNING"}] ${f.column}: ${f.message}`);
}

// Scan a CSV file (Node.js)
import { readFile, scanData, applyConfidenceDowngrade, healthScore } from "goldencheck/node";

const data = readFile("data.csv");
const result = scanData(data, { domain: "healthcare" });
const findings = applyConfidenceDowngrade(result.findings, false);

// Health score
const byCol = {};
for (const f of findings) {
  if (f.severity >= 2) {
    byCol[f.column] ??= { errors: 0, warnings: 0 };
    byCol[f.column][f.severity === 3 ? "errors" : "warnings"]++;
  }
}
const { grade, points } = healthScore(byCol);
console.log(`Health: ${grade} (${points}/100)`);

// Validate against pinned rules
import { readFile, scanData, validateConfig, validateData } from "goldencheck/node";
import { readFileSync } from "node:fs";
import YAML from "yaml";

const config = validateConfig(YAML.parse(readFileSync("goldencheck.yml", "utf-8")));
const data = readFile("data.csv");
const findings = validateData(data, config);

// Create baseline and detect drift
import { readFile, createBaseline, serializeBaseline, scanData } from "goldencheck/node";
import { runDriftChecks, deserializeBaseline } from "goldencheck";
import { writeFileSync, readFileSync } from "node:fs";

// Learn baseline
const data = readFile("reference.csv");
const baseline = createBaseline(data);
writeFileSync("baseline.json", serializeBaseline(baseline));

// Later: detect drift
const newData = readFile("production.csv");
const saved = deserializeBaseline(readFileSync("baseline.json", "utf-8"));
const driftFindings = runDriftChecks(newData, saved);

// LLM-enhanced scanning (edge-safe)
import { scanData, TabularData, callLlm, parseLlmResponse, mergeLlmFindings, buildSampleBlocks } from "goldencheck";

const data = new TabularData(records);
const result = scanData(data, { returnSample: true });
const blocks = buildSampleBlocks(result.sample, result.findings);
const { text } = await callLlm("anthropic", JSON.stringify(blocks));
const llmResponse = parseLlmResponse(text);
if (llmResponse) {
  const enhanced = mergeLlmFindings(result.findings, llmResponse);
}

工作原理

1. SCAN     →  goldencheck data.csv
                GoldenCheck profiles your data and discovers what "healthy" looks like

2. REVIEW   →  Interactive TUI shows findings sorted by severity
                Each finding has: description, affected rows, sample values

3. PIN      →  Press Space to promote findings into permanent rules
                Dismiss false positives — they won't come back

4. EXPORT   →  Press F2 to save rules to goldencheck.yml
                Human-readable YAML with your pinned rules

5. VALIDATE →  goldencheck validate data.csv
                Enforce rules in CI with exit codes (0 = pass, 1 = fail)

可检测内容

列级分析器

分析器	可检测的问题	示例
类型推断	实际上是数值的字符串列	"age 列是字符串，但 98% 的值为整数"
可空性	必填列与可选列	"5 万行中没有空值——很可能是必填列"
唯一性	主键候选列、近似重复项	"100% 唯一——很可能是主键"
格式检测	电子邮件、电话、URL、日期	"94% 符合电子邮件格式，6% 格式错误"
范围与分布	离群值、最小值/最大值界限	"3 行的值大于 10,000"
基数	低基数枚举建议	"有 4 个唯一值——可能是枚举"
模式一致性	列内格式混杂	"检测到 3 种电话格式"

跨列分析器

分析器	可检测的问题
时间顺序	start_date > end_date 违规
空值相关性	同时为空的列（例如，address + city + zip）
数值跨列校验	value > max 违规（例如，claim_amount > policy_max）
年龄与出生日期	年龄列与根据 date_of_birth 计算出的年龄不匹配

基线深度分析与漂移检测

运行一次 goldencheck baseline，即可构建健康数据的统计概况。在之后的每次扫描中，GoldenCheck 都会将新数据与已保存的基线进行比较，并报告 13 种检查类型中的数据漂移：

检查类型	可检测的问题
distribution_drift	值分布发生显著变化
entropy_drift	列值的熵发生变化
bound_violation	值超出历史最小值/最大值界限
benford_drift	首位数字分布偏离本福特定律
fd_violation	列之间的函数依赖关系遭到破坏
key_uniqueness_loss	之前唯一的列现在出现了重复值
temporal_order_drift	违反历史列顺序约束
type_drift	列的主导语义类型发生变化
correlation_break	之前相关的列不再相关
new_correlation	出现了新的意外相关性
pattern_drift	值格式/模式分布发生变化
new_pattern	列中出现了新的结构模式

基线通过 6 种技术构建：统计分析器（分布、本福特定律、熵）、约束挖掘器（函数依赖、时间顺序）、语义类型推断器（嵌入 + 关键词）、相关性分析器（Pearson、Cramér's V）、模式语法归纳器和置信度先验构建器。

领域包

使用特定领域的类型定义，提高检测准确性：

goldencheck scan data.csv --domain healthcare   # NPI, ICD, insurance, patient types
goldencheck scan data.csv --domain finance      # accounts, routing, CUSIP, transactions
goldencheck scan data.csv --domain ecommerce    # SKUs, orders, tracking, products

领域包会添加语义类型，以减少误报并改进对行业特定数据的分类。

架构差异

比较数据文件的两个版本：

goldencheck diff data.csv                  # compare against git HEAD
goldencheck diff old.csv new.csv           # compare two files
goldencheck diff data.csv --ref main       # compare against a branch

自动修复

应用自动修复来清理数据：

goldencheck fix data.csv                          # safe: trim, normalize, fix encoding
goldencheck fix data.csv --mode moderate          # + standardize case
goldencheck fix data.csv --mode aggressive --force # + coerce types
goldencheck fix data.csv --dry-run                # preview changes

监视模式

持续监控目录中的数据质量：

goldencheck watch data/ --interval 30        # re-scan every 30s
goldencheck watch data/ --exit-on error      # CI mode: fail on first error

REST API

将 GoldenCheck 作为微服务运行：

goldencheck serve --port 8000

# Scan via file upload
curl -X POST http://localhost:8000/scan --data-binary @data.csv

# Scan via URL
curl -X POST http://localhost:8000/scan/url -d '{"url": "https://example.com/data.csv"}'

数据库扫描

直接扫描表格，无需导出 CSV：

pip install goldencheck[db]
goldencheck scan-db "postgresql://user:pass@host/db" --table orders
goldencheck scan-db "snowflake://..." --query "SELECT * FROM orders WHERE date > '2024-01-01'"

定时运行

支持类似 Cron 的调度，并发送 Webhook 通知：

goldencheck schedule data/*.csv --interval hourly --webhook https://hooks.slack.com/...
goldencheck schedule data/*.csv --interval daily --notify-on grade-drop

LLM 增强

添加 --llm-boost，利用 LLM 智能增强分析器的发现结果。LLM 会接收一份具有代表性的数据样本，并：

1. 发现分析器遗漏的问题 — 通过语义理解进行判断（例如，名称列中的 "12345"）
2. 提升严重性级别 — 即使分析器只标记为“信息”，也能判断“电子邮件应为必填项”
3. 发现关联关系 — 识别列之间的时间顺序，例如 signup_date 和 last_login
4. 降低误报级别 — “电话格式混杂很常见，不算错误”

# Using OpenAI
export OPENAI_API_KEY=sk-...
goldencheck data.csv --llm-boost --llm-provider openai --no-tui

# Using Anthropic
export ANTHROPIC_API_KEY=sk-ant-...
goldencheck data.csv --llm-boost --no-tui

成本： 每次扫描约 0.01 美元（使用具有代表性的样本调用一次 API，而非逐行调用）。

预算控制：

export GOLDENCHECK_LLM_BUDGET=0.50  # max spend per scan in USD

配置（goldencheck.yml）

version: 1

settings:
  sample_size: 100000
  fail_on: error

columns:
  email:
    type: string
    required: true
    format: email
    unique: true

  age:
    type: integer
    range: [0, 120]

  status:
    type: string
    enum: [active, inactive, pending, closed]

relations:
  - type: temporal_order
    columns: [start_date, end_date]

ignore:
  - column: notes
    check: nullability

此文件中仅包含已固定的规则，并非所有发现项。ignore 列表可防止已驳回的发现项再次出现。

CLI 参考

命令	说明
goldencheck <file>	扫描并启动 TUI
goldencheck scan <file>	显式扫描（支持 --smart、--guided）
goldencheck validate <file>	根据 goldencheck.yml 验证
goldencheck review <file>	扫描并验证，然后启动 TUI
goldencheck init <file>	交互式设置向导（扫描 → 配置 → CI）
goldencheck diff <file> [file2]	比较两个文件，或与 git HEAD 比较
goldencheck watch <dir>	轮询目录，变更时重新扫描
goldencheck fix <file>	自动修复数据质量问题
goldencheck baseline <file>	深度分析数据，并将统计基线保存到 YAML
goldencheck learn <file>	生成大模型验证规则
goldencheck history	显示扫描历史记录和趋势
goldencheck serve	启动 REST API 服务
goldencheck scan-db <conn>	直接扫描数据库表
goldencheck schedule <files>	按 cron 计划运行扫描
goldencheck mcp-serve	启动 MCP 服务（19 个工具）

标志

标志	说明
--no-tui	在控制台打印结果
--json	JSON 输出
--fail-on <level>	当严重级别为 error 或 warning 时退出，代码为 1
--domain <name>	领域包：healthcare、finance、ecommerce
--llm-boost	启用大模型增强
--llm-provider <name>	大模型提供商：anthropic（默认）或 openai
--mode <level>	修复模式：safe、moderate、aggressive
--smart	自动分类：固定高置信度项，驳回低置信度项
--guided	逐项检查发现项
--webhook <url>	将发现项 POST 到 Slack、PagerDuty 或任意 URL
--notify-on <trigger>	Webhook 触发条件：grade-drop、any-error、any-warning
--baseline <path>	用于检测漂移的基线 YAML 路径
--no-baseline	跳过自动发现 goldencheck_baseline.yaml
--skip <technique>	跳过某项基线技术（可重复使用）
--update	更新现有基线，而非覆盖
-o <path>	基线文件的输出路径（默认：goldencheck_baseline.yaml）
--version	显示版本

TypeScript CLI

npx goldencheck-js scan data.csv --json
npx goldencheck-js scan data.csv --domain healthcare
npx goldencheck-js health-score data.csv
npx goldencheck-js profile data.csv
npx goldencheck-js validate data.csv --config goldencheck.yml
npx goldencheck-js baseline data.csv --output baseline.json
npx goldencheck-js fix data.csv --mode safe
npx goldencheck-js diff old.csv new.csv
npx goldencheck-js demo

TypeScript 架构

goldencheck (npm)
├── goldencheck/core    # Edge-safe: browsers, Workers, Edge Runtime
│   ├── types           # Finding, Severity, DatasetProfile, Config types
│   ├── data            # TabularData — zero-dep columnar abstraction
│   ├── profilers       # 10 column profilers + 4 relation profilers
│   ├── semantic        # Type classifier, suppression, 3 domain packs
│   ├── engine          # Scanner, confidence, validator, triage, differ, fixer
│   ├── baseline        # Statistical profiling, constraints, correlation, patterns
│   ├── drift           # 13 drift checks against saved baseline
│   ├── llm             # Anthropic + OpenAI via fetch(), merger, budget
│   ├── agent           # Strategy, handoff, review queue
│   └── reporters       # JSON, CI
└── goldencheck/node    # Node.js >= 20
    ├── reader          # CSV, Parquet (via nodejs-polars)
    ├── mcp             # MCP server (7 tools)
    ├── a2a             # Agent-to-Agent HTTP server
    ├── tui             # ANSI terminal output
    ├── db-scanner      # Postgres, MySQL, SQLite
    └── watcher         # Directory polling

基准测试

速度

数据集	耗时	吞吐量
1K 行	0.05s	19K 行/秒
10K 行	0.23s	43K 行/秒
100K 行	2.29s	44K 行/秒
1M 行	2.07s	482K 行/秒

DQBench v1.0 — 正面对比

工具	模式	DQBench 得分
GoldenCheck	零配置	88.40
Pandera	尽力而为的规则	32.51
Soda Core	尽力而为的规则	22.36
Great Expectations	尽力而为的规则	21.68

GoldenCheck 的零配置发现能力胜过所有竞争产品，即使对方使用了手写规则。

亲自运行基准测试：

pip install dqbench goldencheck
dqbench run goldencheck

检测准确率

模式	列召回率	成本
仅分析器（v0.1.0）	87%	$0
仅分析器（带置信度的 v0.2.0）	100%	$0
启用大模型增强	100%	~$0.003-0.01

在一项自定义基准测试中进行了测试，该测试涵盖 9 个类别的 341 个预置数据质量问题。

v0.2.0 改进：少数错误类型检测、范围分析器链式处理、更广泛的时间启发式方法，以及置信度评分，将仅分析器的召回率从 87% 提升至 100%。

Raha 基准数据集

数据集	列召回率
航班（2,376 行）	100%（4/4 列）
啤酒（2,410 行）	80%（4/5 列）

技术栈

依赖项	用途
Polars	所有数据操作
Typer	CLI 框架
Textual	交互式 TUI
Rich	CLI 输出格式化
Pydantic 2	配置验证

**可选：**用于 LLM Boost 的 Anthropic SDK / OpenAI SDK | 用于 MCP 服务的 MCP SDK | 用于深度基线分析的 scipy + numpy（[baseline]）| 用于基线语义类型推断的 sentence-transformers（[semantic]）

TypeScript / Node.js

依赖项	用途
无运行时依赖	核心包没有依赖项（适用于边缘环境）
nodejs-polars	Parquet 读取（可选，仅限 Node.js）
csv-parse	CSV 读取（仅限 Node.js）
@modelcontextprotocol/sdk	MCP 服务（仅限 Node.js）

MCP 服务（Claude Desktop）

GoldenCheck 包含一个用于与 Claude Desktop 集成的 MCP 服务：

pip install goldencheck[mcp]

添加到 Claude Desktop 配置（claude_desktop_config.json）中：

{
  "mcpServers": {
    "goldencheck": {
      "command": "goldencheck",
      "args": ["mcp-serve"]
    }
  }
}

可用工具：

工具	描述
scan	扫描文件以查找数据质量问题（可选启用 LLM Boost）
validate	根据 goldencheck.yml 中固定的规则进行验证
profile	获取列级统计信息和健康评分
health_score	快速评定数据文件的 A-F 等级
get_column_detail	深入分析特定列
list_checks	列出所有可用的分析器检查项

远程 MCP 服务

GoldenCheck 可作为托管的 MCP 服务通过 Smithery 使用 — 无需安装任何内容，即可从任意 MCP 客户端连接。

Claude Desktop / Claude Code：

{
  "mcpServers": {
    "goldencheck": {
      "url": "https://goldencheck-mcp-production.up.railway.app/mcp/"
    }
  }
}

本地服务：

pip install goldencheck[mcp]
goldencheck mcp-serve

提供 19 种工具：扫描文件、验证规则、分析列、评估数据集健康状况、自动配置验证、解释分析结果、比较领域、建议修复方案。

Jupyter / Colab

GoldenCheck 可在 Jupyter 笔记本中呈现丰富的 HTML 内容：

from goldencheck.engine.scanner import scan_file
from goldencheck.engine.confidence import apply_confidence_downgrade
from goldencheck.notebook import ScanResult

findings, profile = scan_file("data.csv")
findings = apply_confidence_downgrade(findings, llm_boost=False)

# Rich HTML display in notebooks
ScanResult(findings=findings, profile=profile)

API 快速参考

Python

import goldencheck

# Scan a CSV for quality issues
findings = goldencheck.scan_file("data.csv")
for f in findings:
    print(f"[{f.severity}] {f.column}: {f.check} — {f.message}")

# Create baseline and detect drift
from goldencheck import create_baseline, scan_file
baseline = create_baseline("data.csv")
baseline.save("goldencheck_baseline.yaml")
findings, profile = scan_file("data.csv", baseline="goldencheck_baseline.yaml")

# Health score
score = goldencheck.health_score("data.csv")
print(score)  # e.g. "B (78/100)"

TypeScript

import { scanData, TabularData, Severity } from "goldencheck";

// Scan records (edge-safe)
const data = new TabularData(records);
const { findings, profile } = scanData(data);
for (const f of findings) {
  console.log(`[${f.severity === Severity.ERROR ? "ERROR" : "WARNING"}] ${f.column}: ${f.message}`);
}

import { readFile, scanData, applyConfidenceDowngrade, healthScore } from "goldencheck/node";

// Scan a CSV file (Node.js)
const data = readFile("data.csv");
const result = scanData(data, { domain: "healthcare" });
const findings = applyConfidenceDowngrade(result.findings, false);

// Health score
const byCol = {};
for (const f of findings) {
  if (f.severity >= 2) {
    byCol[f.column] ??= { errors: 0, warnings: 0 };
    byCol[f.column][f.severity === 3 ? "errors" : "warnings"]++;
  }
}
const { grade, points } = healthScore(byCol);
console.log(`Health: ${grade} (${points}/100)`);

import { readFile, createBaseline, serializeBaseline } from "goldencheck/node";
import { runDriftChecks, deserializeBaseline } from "goldencheck";
import { writeFileSync, readFileSync } from "node:fs";

// Create baseline and detect drift
const data = readFile("reference.csv");
const baseline = createBaseline(data);
writeFileSync("baseline.json", serializeBaseline(baseline));

const newData = readFile("production.csv");
const saved = deserializeBaseline(readFileSync("baseline.json", "utf-8"));
const driftFindings = runDriftChecks(newData, saved);

参与贡献

开发环境设置和指南请参阅 CONTRIBUTING.md。

作者

Ben Severn

许可证

MIT — 详见 LICENSE

---

Golden Suite 的组成部分

工具	用途	安装
GoldenCheck	验证并分析数据质量	pip install goldencheck / npm install goldencheck
GoldenFlow	转换并标准化数据	pip install goldenflow
GoldenMatch	对记录去重并进行匹配	pip install goldenmatch
GoldenPipe	编排完整管道	pip install goldenpipe

配套项目：

• dbt-goldencheck — 将数据验证作为 dbt 测试。
• goldencheck-types — 社区贡献的领域类型包。
• goldencheck-action — 用于 CI 并支持 PR 评论的 GitHub Action。