version-dataset

版本数据集技能

分析必须基于其声称使用的数据运行，并使用固定的种子。此技能会显式提示运行之间的差异，而不是让差异悄然发生：它会记录确定性指纹（文件 SHA-256，以及表格文件的架构和每列值哈希；除非明确传入时间戳，否则不包含时间戳），以便后续运行能证明输入未发生变化。它绝不会修改数据，清单中保存的是哈希，而非数据本身。来源说明使用英文。

确定性脚本

# Build a manifest (record the analysis seed + provenance)
python "${CLAUDE_SKILL_DIR}/scripts/version_dataset.py" manifest data.csv \
  --out manifest.json --seed 42 --provenance "KNHANES 2018 extract v1"

# Verify a later copy against it (CI / pre-analysis gate)
python "${CLAUDE_SKILL_DIR}/scripts/version_dataset.py" verify --manifest manifest.json --strict

# Compare two manifests (what changed between versions)
python "${CLAUDE_SKILL_DIR}/scripts/version_dataset.py" diff --old v1.json --new v2.json

文件哈希仅使用标准库；表格架构/列哈希会在 pandas 可用时使用它。 --ignore-cols 用于排除易变列；--base 用于将清单键设为相对路径。

工作流

步骤 1：锁定版本（关卡）

在数据集冻结以供分析时生成清单。关卡： 锁定前与用户确认种子和来源说明是否正确 — 清单是他们会引用的记录，用来证明“结果基于这些数据得出”。 来源说明必须是用户提供的文本；绝不可自行编造。

步骤 2：每次运行前验证（关卡）

重新运行分析前（或在 CI 中），执行 verify --strict。未经 verify，绝不可声称数据集未发生变化。**关卡：**如果报告存在差异（MANIFEST_DRIFT，退出码为 1），请停止并向用户原样展示计算得出的差异报告 — 绝不可淡化已变更的列哈希。未经用户明确确认并重新锁定，不得继续使用已变更的数据。此技能旨在防止的正是基于已发生差异的数据静默重跑。

解读差异前，请先阅读 ${CLAUDE_SKILL_DIR}/references/manifest_schema.md — 该文件定义了每种差异类别。CSV/TSV 文件按其逻辑内容（架构 + 每列值哈希）进行比较，而非比较原始字节，因此重新添加引号、调整列顺序或使用 --ignore-cols 忽略易变列，都不会造成误报。二进制表格文件（Parquet/Stata/SAS/Excel）也会进行字节级检查，因为标签、元数据和其他工作表并未包含在列哈希中；但如果文件中存在 --ignore-cols 指定的列，则其变更会改变字节。

步骤 3：比较不同版本

有意更新数据集时，对旧版和新版清单执行 diff，并展示变更集（新增/移除/变更的列、行数差值），以便用户记录变更内容并重新锁定。**关卡：**用户批准新版本后，才能用它替换已锁定的版本。

非确定性产物

不要将 PPTX/DOCX 或图表二进制文件纳入严格字节验证 — 它们包含时间戳或渲染元数据，每次构建都会发生变化。仅将确定性输入和表格输出（数据文件、结果 CSV）纳入清单，或使用 --ignore-cols 忽略易变列；相关策略见 references/manifest_schema.md。每个捆绑的 demo/*/ 都附带一个 manifest.lock.json（输入数据 + 确定性结果表），可由 verify --strict 检查；参考文档中提供了演示命令。

范围

• 分享清单前，先运行 /deidentify：清单不会存储示例值，但来源说明可能包含上下文信息。
• 清洗、分析或去标识化数据 → /clean-data、/generate-codebook、/deidentify。/generate-codebook 用于记录数据中包含的内容；此技能用于锁定版本。