前言¶

对账、报表核对、库存或订单校验，常见做法是手工指定主键列、在 Excel 里 VLOOKUP，或在脚本里写 join。列名不一致、编码不统一、两边导出格式不同时，前期清洗往往占掉大部分时间。下面介绍 SkillHub 社区 Skill Data Compare Engine（坐标 @user_26bdbd50/data-compare-engine）：在 Agent 或命令行场景下，用 pandas 解析双文件，可选 AI 做列匹配，再输出差异统计与 Markdown 报告。

这是什么¶

Data Compare Engine 是社区发布（community）、分类为 data-analysis 的 Agent Skill，当前版本 1.0.0，由发布者 user_26bdbd50 维护。SkillHub 页面标注 requires_api_key=true：列匹配与差异解读依赖你自备的模型 API Key；计费侧还需配置妙搭相关 Token（见下文）。

它解决的核心问题是：两份结构化数据文件（CSV / XLSX）如何在对齐列语义的前提下，快速得到匹配行、单边行、金额差异和可读报告。

核心功能¶

以下能力均来自 Skill 包内 SKILL.md、README.md 与实现说明，可按需裁剪使用。

双文件解析¶

1. 支持 CSV / XLSX 两个输入文件。
2. 使用 pandas 读取，并做编码识别（依赖 chardet 等）。
3. 运行时会使用工作目录 /tmp/data-compare-engine/（不存在则创建），用于存放上传或中间路径相关数据。

AI 自动列匹配¶

1. 通过环境变量传入 OPENAI_API_KEY 或 ANTHROPIC_API_KEY（文档亦写明可扩展为「等」其他 Key 方式）。
2. AI 推断左右文件中语义对应的列；也可用 --join-key 手动指定 Join Key（多列用逗号分隔）。
3. CLI 支持 --ai-model 选择 openai 或 anthropic（默认 openai）；--skip-ai-match 可跳过 AI 列匹配，仅用手动 Join Key。

数据对比与统计¶

对比维度包括：完全匹配、仅左文件、仅右文件、金额差异。输出包含完全匹配行数、差异行数、差异占比，以及在指定金额列时的差异合计（--amount-col）。

差异分析报告¶

1. 默认生成 Markdown 报告（--output，默认 diff_report.md），含差异统计摘要、AI 对差异原因的解读、按组分类的明细。
2. 可通过 --export-csv 导出 CSV 形态的差异结果。

文档列出的典型场景包括：银行对账单核对、财务报表比对、库存校验、订单核对、数据库同步验证等（属适用方向说明，非单独案例）。

安装与启用¶

在 SkillHub 安装 Skill¶

先确认本机已安装 SkillHub CLI（未安装可参考 SkillHub 安装文档）。安装 Skill 时必须用 --dir 指向当前 Agent 的 skills 目录，否则可能装到默认 ./skills/ 而未被识别。

command -v skillhub && skillhub --version

skillhub install data-compare-engine --namespace user_26bdbd50 --dir ~/.cursor/skills/

也可让 Agent 按 SkillHub 页面提示，读取 https://skillhub.cn/install/skillhub.md 后执行等价安装。常见路径示例：

• Cursor：~/.cursor/skills/
• Claude Code：~/.claude/skills/
• Codex：~/.codex/skills/ 或项目下 .agents/skills/

安装完成后，在支持 Skills 的客户端中启用或重启 Agent，使其加载包内 SKILL.md 中的工作流说明。

Python 依赖与本地运行¶

Skill 文档中的快速开始示例为：

pip install -r scripts/requirements.txt
python run.py --left left_file.csv --right right_file.csv

当前 1.0.0 包根目录提供 requirements.txt（含 pandas>=1.5.0、openpyxl>=3.0.0、chardet>=4.0.0、requests>=2.28.0）。若解压后没有 scripts/requirements.txt，可在 Skill 根目录执行：

pip install -r requirements.txt
python run.py --left left_file.csv --right right_file.csv

环境变量¶

计费校验接口：POST https://api.yk-global.com/v1/verify。套餐（来自官方说明）：

收费版购买入口文档指向 YK-Global.com。

典型用法¶

在 Skill 根目录配置好依赖与环境变量后，可用 CLI 完成一次完整对比。下面示例综合 README.md 中的参数说明。

export OPENAI_API_KEY="your-key"
export YK_TOKEN="your-yk-token"

python run.py \
  --left ./exports/ledger_left.xlsx \
  --right ./exports/ledger_right.csv \
  --join-key order_id,sku \
  --amount-col amount \
  --output diff_report.md \
  --export-csv diff_rows.csv \
  --ai-model openai

若列名已对齐、只需按主键比对，可跳过 AI 匹配：

python run.py \
  --left left.csv \
  --right right.csv \
  --join-key id \
  --skip-ai-match \
  --output diff_report.md

未传 --left / --right 时，run.py 会进入交互式路径输入（实现于 src/main.py）。

在 Cursor 等 Agent 中安装 Skill 后，可将自然语言任务（例如「对比这两份对账单并标出金额差」）与文件路径交给 Agent；Agent 按 SKILL.md 调用上述脚本或等价步骤即可。

适用场景与注意¶

适合谁：需要频繁做双表核对、列名不统一、又希望报告可直接归档（Markdown + 可选 CSV）的数据分析、财务运营、仓储或电商后台同学；也适合在 Agent 会话里把「比对」固化成可重复流程的开发者。

限制与注意：

1. API Key 与计费：SkillHub 标签要求 API Key；运行时还涉及 YK_TOKEN 与行数/次数套餐上限，大文件需对照套餐表或 Enterprise 方案。
2. 数据规模：Free 档单次最大 200 行，Pro 为 5,000 行，超出需升级或自行拆分文件。
3. 路径与文档：官方快速开始写的是 scripts/requirements.txt，与部分包布局可能不一致，以安装后的目录为准。
4. 隐私与合规：列匹配与解读会把表头/样本发往所选 AI 服务商，敏感数据请先脱敏或仅用 --skip-ai-match 做本地 join。
5. 平台数据：SkillHub 抓取信息显示该 Skill 评分 100000、下载 821 次（页面统计会变动，以 SkillHub 为准）。

结尾¶

Data Compare Engine 把「读表 → 对齐列 → 统计差异 → 出报告」收成一条可脚本化、也可交给 Agent 执行的链路；列名语义对齐交给 AI，主键与金额列仍可人工兜底。如需安装或查看元数据，可访问 SkillHub 页面：Data Compare Engine；API 坐标：https://api.skillhub.cn/user_26bdbd50/data-compare-engine。