csv-quality-gate：AI Agent 工具实践指南

实际看csv-quality-gate，先要确认它的用途：csv-quality-gate 是一个命令行数据质量门，运行 CSV 预检验证，在 ML 或 LLM 管道摄取损坏、不完整、重复或垃圾输入之前快速失败。数据与知识处理里，数据结构、更新策略和可追溯性会决定结果是否可信。我会用一份规模可控且答案已知的数据集试跑，检查模式兼容、增量更新、查询结果和来源追踪。它适合需要保留数据来路与变更记录的使用者；采用前仍要看维护状态和试跑结果。

它对 CSV 运行批量质量检查，并在昂贵的管道步骤因错误输入而浪费时间之前返回 pass、warn 或 fail（具有匹配的退出代码）。它会检查是否缺少必需的列、空文件、空的关键单元格、重复的行，以及在 outreach 配置文件下的可疑公司名称模式。团队可以在小型 TOML/JSON 配置中声明自己的列、阈值和模式，每个问题都指向受影响的行号（绝不是单元格值），并且相同的门作为预提交挂钩或 GitHub 操作运行。它仅是 stdlib：没有第三方运行时依赖项。

它的构建目的是解决以下问题：

• “我们继续在损坏的 CSVs 上运行昂贵的管道步骤。”
• “批处理运行在 20 分钟后失败，因为输入 CSV 是垃圾。”
• “我们只有在工作开始后才发现缺少必需的列。”
• “重复的行和空的联系字段不断污染我们的批次运行。”
• “门上写着 12% 重复，但是哪些行呢？”
• “我们的CSVs有email和order_id，而不是company。”
• “我想要 CSV 飞行前验证，而不是整个数据平台。”

快速入门（60 秒）

pip install csv-quality-gate
python -c "from importlib.metadata import version; print(version('csv-quality-gate'))"   # confirm the installed release
csv-quality-gate check leads.csv --profile outreach

具有缺失列和临界重复率的 CSV 的示例输出：

csv-quality-gate: FAIL
file: leads.csv
profile: outreach
rows: 125
  ERROR: missing required column: person_name
  WARNING: duplicate rate 12% exceeds warning threshold 10%
    evidence: column=company affected=15 rows at line(s) 4, 9, 15, 22, 31 (+10 more)

该进程在通过时退出 0，仅在出现警告时退出 1，在失败时退出 2，因此您可以将其直接连接到 shell 脚本、预提交挂钩或 CI 步骤。

使用附带的装置尝试一下

您可以在将门连接到您自己的管道之前验证该门。来自一个 签出，安装包并运行包含的干净和损坏的输入：

git clone https://github.com/hermes-labs-ai/csv-quality-gate.git
cd csv-quality-gate
python -m pip install .
csv-quality-gate check examples/clean.csv
csv-quality-gate check examples/promptfoo-dataset/tests-broken.csv \
  --config examples/promptfoo-dataset/csv-quality-gate.toml \
  --profile promptfoo

第一条命令退出 0 为 PASS；第二个退出 2 有界 断行的行号证据。这提供了首次使用检查，无需 创建示例 CSV 或猜测要选择哪个配置文件和配置。

开发安装

对于日常使用，请按照上面的 快速入门 进行操作。对于一个 源签出、可编辑安装和 lint/test 命令，请参阅 开发如下。

作为特工技能（Claude Code、Codex CLI、Gemini CLI）

存储库根是一个便携式 代理插件 (plugin.json) 运送一项技能 skills/csv-quality-gate/SKILL.md。它 教代理在您命名的 CSV 文件上运行此门并报告 状态和行号证据，无需夸大其词。

每位主持人读到的内容：

• 克劳德代码读取 .claude-plugin/marketplace.json （来源 .）并且 .claude-plugin/plugin.json.
• Codex 读取回购市场 .agents/plugins/marketplace.json（来源 ./，根）和便携式 plugin.json。
• 双子座 CLI 读取 gemini-extension.json 并发现下面的技能 skills/。保留 --ref main：没有参考，Gemini CLI 安装最新版本 GitHub 发布存档，并发布至 v0.3.0 之前 gemini-extension.json.

安装技能不会安装Python包。该技能使用一个 安装 csv-quality-gate 或运行固定版本 uvx csv-quality-gate==0.3.1.

用途

csv-quality-gate check leads.csv
csv-quality-gate check leads.csv --profile outreach
csv-quality-gate check leads.csv --profile generic --json
csv-quality-gate check leads.csv --config csv-quality-gate.toml --profile leads
csv-quality-gate check leads.csv --max-examples 20
csv-quality-gate check data/*.csv

check 的选项：

• --profile NAME — 内置配置文件（generic、outreach）或在 --config 中声明的配置文件。
• --config FILE — 具有项目特定配置文件的 TOML 或 JSON 文件（请参阅 自定义配置文件）。
• --max-examples N — 每个问题列出了多少受影响的行号（默认 5；0 仅保留计数）。
• --json — 机器可读的输出。

一次调用可以检查多条路径。文本模式每个文件打印一个块， JSON 模式发出一个数组（单个路径保留普通对象），然后退出 code 是文件中最差的状态。

退出代码：

• 0通行证
• 1 仅警告
• 2 失败（或 2，当文件不存在、不是 UTF-8、配置文件未知或配置无效时）

型材

内置配置文件：

• generic
  • 检查所需的 company 列、空 company 单元格、重复的 company 值和空文件
• outreach
  • 需要 company 和 person_name，具有更高的空率容差，并为 GTM/contact 管道添加可疑公司名称启发式

每个配置文件的阈值在 src/csv_quality_gate/profiles.py 中定义。

定制配置文件

在 TOML (Python 3.11+) 或 JSON 文件中声明您自己的配置文件并传递它 与 --config。一个可复制的例子位于 examples/csv-quality-gate.toml.

[profiles.leads]
extends = "outreach"                 # optional: inherit a built-in's columns, patterns, and rates
required_columns = ["email", "company", "person_name"]
critical_columns = ["email", "person_name"]
duplicate_column = "email"
empty_warning_rate = 0.05
empty_fail_rate = 0.20
duplicate_warning_rate = 0.02
duplicate_fail_rate = 0.10
suspicious_column = "email"
suspicious_patterns = ['^[^@]+$']    # case-insensitive regular expressions
suspicious_warning_rate = 0.20
suspicious_fail_rate = 0.50

csv-quality-gate check data/leads.csv --config csv-quality-gate.toml --profile leads

规则：

• 每个键都是可选的。如果没有 extends，配置文件开始时没有列， 无模式，以及 generic 阈值。
• 0.0 的比率表示“任何发生”：没有受影响行的检查从不 引发了一个问题，所以干净的文件仍然可以通过。
• 配置仅是数据：列名称、0 和 1 之间的比率以及正则表达式 字符串。未知的密钥、超出范围的比率、高于其失败率的警告率、 无效的正则表达式会被拒绝并带有精确的消息，并且 CLI 返回 正常的 fail 收据（退出 2）而不是回溯。
• 内置插件在您的个人资料旁边可用。具有相同的自定义配置文件 name 作为内置名称仅替换该运行的名称。
• 正则表达式来自您自己的存储库；保持简单，因为门确实 不防范病理模式。

输出

文本模式（默认）：

csv-quality-gate: FAIL
file: leads.csv
profile: outreach
rows: 125
  ERROR: missing required column: person_name
  WARNING: duplicate rate 12% exceeds warning threshold 10%
    evidence: column=company affected=15 rows at line(s) 4, 9, 15, 22, 31 (+10 more)

每个空率、重复率和可疑值问题的影响都是有界的 证据：受影响的列、受影响的行总数以及最多 --max-examples 物理行号（标题为第 1 行；引用记录 跨越几行报告其最后一行）。单元格值永远不会被打印， 因此收据可以安全地附加到 CI 日志或票据上。重复的证据点 在第二次和以后出现时，所以这些是要删除的行。

JSON 模式（--json）发出一个带有 path、profile、rows、status 的对象， issues[]和（当使用--config时）config。每期都有severity 和 message；由行支持的问题添加 evidence 对象：

csv-quality-gate check leads.csv --json

{
  "path": "leads.csv",
  "profile": "outreach",
  "rows": 125,
  "status": "fail",
  "issues": [
    {"severity": "error", "message": "missing required column: person_name"},
    {
      "severity": "warning",
      "message": "duplicate rate 12% exceeds warning threshold 10%",
      "evidence": {"column": "company", "total": 15, "rows": [4, 9, 15, 22, 31]}
    }
  ]
}

限制/它不做什么

• 启发式方法有意变得简单：空率、重复率和基于正则表达式的名称模式。他们不会从您的数据中学习。
• 它验证形状和明显的噪声，而不是语义正确性 - 它无法判断 company 值是否真实，只能判断它们是否存在、唯一，而不是明显的垃圾。
• outreach 配置文件是固执己见的。其可疑名称模式和阈值是为 GTM 联系人列表选择的，不应被视为普遍事实。
• 对配置文件名称的列进行重复和空检查；它不会自动检测哪些列重要。内置使用company和person_name；使用配置文件做其他事情。
• 证据就是行号，只算数。它从不引用单元格值，因此它无法告诉您错误值“是什么”，只能告诉您它在哪里。
• 它独立验证每个 CSV 文件，并假定 UTF-8 (BOM- 容忍)、逗号分隔输入。
• 它不是一个数据质量平台：没有沿袭、没有分析报告、没有模式推断、没有行级修复。

何时使用它

• 在浓缩、外展、ETL 或批量评分运行之前
• 作为签入 CSV 输入的预提交挂钩或 CI 步骤
• 作为昂贵的管道工作之前的预检门

何时不使用它

• 当您需要对数据本身进行语义验证时
• 当您的输入不是 CSV 时
• 当您需要具有沿袭和分析功能的完整数据质量框架时

预提交

在提交之前，在暂存的 CSV 文件上运行相同的门。将其添加到 您的 .pre-commit-config.yaml （完整示例位于 examples/pre-commit-config.yaml):

repos:
  - repo: https://github.com/hermes-labs-ai/csv-quality-gate
    rev: v0.3.1
    hooks:
      - id: csv-quality-gate
        args: [--profile, outreach]
        # or: args: [--config, csv-quality-gate.toml, --profile, leads]

该钩子接收每个暂存的 .csv 文件，为每个文件打印一个报告块， 并阻止 warn 或 fail 上的提交，匹配 CLI 退出代码。窄 如果只有一些 CSVs 应该被门控，则它具有预提交的 files: 模式，并且 通过配置文件调整阈值而不是跳过挂钩。

要在固定版本之前尝试从本地结帐挂钩，请指向 结账路径上的配置和提交：

repos:
  - repo: /path/to/csv-quality-gate
    rev: 
    hooks:
      - id: csv-quality-gate
        args: [--profile, outreach]

pre-commit run --config that-file.yaml csv-quality-gate --files data/leads.csv

pre-commit try-repo . csv-quality-gate --files data/leads.csv 也适用于 默认的 generic 配置文件（try-repo 无法通过 hook args）。

CI / GitHub 操作

直接使用此存储库作为复合操作。它安装打包的CLI， 运行选定的配置文件，并始终在以下位置写入 JSON 收据 $GITHUB_WORKSPACE/csv-quality-gate-receipt.json。 status 和 receipt 即使操作因警告或失败而退出，输出仍然可用。

- id: csv_gate
  uses: hermes-labs-ai/csv-quality-gate@0b7bf4635b2db468620855e577cd0d9f09f09ec7 # hardened current main; annotations + batch
  with:
    csv-path: data/leads.csv
    profile: leads
    config: csv-quality-gate.toml   # optional; omit to use built-in profiles
    annotate: true                  # optional; defaults to false

- run: echo "${{ steps.csv_gate.outputs.status }}"

对于一批，请使用 csv-paths，每行一个路径。准确设置其中之一 csv-path 和 csv-paths；该操作故意不接受自由格式的命令 或 shell 参数。

- id: csv_gate_batch
  uses: hermes-labs-ai/csv-quality-gate@0b7bf4635b2db468620855e577cd0d9f09f09ec7 # hardened current main; batch support
  with:
    csv-paths: |
      data/leads.csv
      data/customers.csv
    profile: generic

单文件收据仍然是 JSON 对象。批量收据是一个 JSON 数组 与 csv-paths 的顺序相同，其状态和退出代码反映了最差的情况 文件。行动 返回与 CLI 相同的退出代码：0 表示通过，1 表示警告，2 表示 失败。收据包含与--json相同的有界证据，因此是安全的 作为工作流程工件上传。 如果您的工作流程需要检查，请在调用步骤上使用 continue-on-error: true 在决定如何继续之前输出警告或失败。

设置 summary: true 以将紧凑结果写入 GitHub 操作作业摘要。 它仅包含状态、配置文件、行数和问题数；它从不包括 CSV 路径或单元格值。证据列标签将被省略，除非您还 设置summary-columns: true；仅当这些标签适合时才启用 工作总结。加法 tool-version 和 summary-written 输出 识别已安装的软件包版本以及此调用是否呈现 总结； JSON 收据不变。

每个工作区的收据路径都是固定的，因此不要在其中运行多个实例 在同一工作空间中并行。该操作验证包的现有 CSV 仅启发式；它不添加模式推断、语义验证或 任意 CLI 选项。

设置 annotate: true 以在以下位置添加最多 50 个 GitHub 操作警告或错误 收据支持的 CSV 文件和物理行。注释使用门的现有 仅有界证据并省略单元格值、问题消息和列名称。 签出工作区之外的路径和没有行证据的问题不会 已注释。大于 1 MiB 的收据将被跳过，而不更改门的 状态。这是一个咨询定位辅助工具，而不是安全或 SARIF 报告。

准备复制、提交固定的复合操作工作流程也存在于 examples/github-action.yml.

GitHub 商城

action.yml 携带市场列表所需的元数据（名称、 描述、作者、品牌）。列出是维护者在 GitHub 上采取的步骤 发布形式，而不是存储库自己做的事情；步骤在 正在释放。您是否通过以下方式到达行动 Marketplace 或此存储库，在 uses: 行中使用完整提交 SHA。

食谱

简短的、可复制的设置将门置于特定工具的前面。各用 自定义配置文件，并附带一个可以运行的通过和一个失败的夹具 从结账处：

• dbt 种子 — dbt seed 之前的门 seeds/*.csv。
• Promptfoo 数据集 — 门控 CSV 测试集 在promptfoo eval之前。

发展

pip install -e ".[dev]"
ruff check .
python3 -m pytest -q
pre-commit try-repo . csv-quality-gate --files tests/fixtures/clean.csv   # optional hook smoke test

适合的地方

csv-quality-gate 保护进入管道的数据；它是代理级和提示级可靠性工具的补充，而不是替代。

更多来自爱马仕实验室

浏览 开源目录 或联系 [email protected]。