前言¶
在 DeepSeek Harness（DSH）里做表格或文档型字段抽取时，常见做法是：让模型直接改 CSV、或在对话里「合并两个来源」后再写表。一旦源文件被覆盖、冲突被静默抹平、或交付表缺少逐格证据，后续很难回答「这一格凭什么」。社区维护者 Antigen-1 的 dsh-data-curation 把「立项 → 签署口径 → 多通道采集 → 比对 → 落表 → 验收 → 导出 → 打包」拆成固定阶段，用工具约束 原始数据不可变、多通道独立、逐格留痕、未决不自动改表，而不是依赖模型自觉。下面介绍它是什么、核心机制、如何安装，以及 README 中的可复现流程。
这是什么¶
dsh-data-curation 是运行在 DSH 上的插件（当前版本 0.18.0，MIT 许可证）。定位是「契约驱动的数据核对 / 清洗模式」：一个项目由 只读源材料 + 单一工作区 SQLite（默认 .curation/project.sqlite）组成，使用 Node 内置 node:sqlite，不引入第三方数据库依赖；要求 Node >= 24（package.json 的 engines 已声明）。
pin、通道提交、裁定结论、逐格 ledger、curated 交付表与注册的导出器都落在该库中；导出文件只是派生物。多通道各自独立提交，只有当 pin 里声明的比对策略判定 至少两个有效通道一致 时，单元格才会被接受；落表前用 VACUUM INTO 备份，单事务 upsert 并回读；curation_verify 是项目级与各表统一的 PASS / CONDITIONAL / FAIL 门禁。本地文件读写，无网络、无遥测。
插件通过 cordis.patch.yml 向 DSH profile 插入一行插件配置（stateDir: .curation），注册 data-curation 技能族、/curation* 命令与 curation_* 工具，并注入 Web 客户端 UI slot；不单独拉起外部进程。
它解决什么问题¶
README 归纳的四类典型事故与对应机制如下：
- 原始数据被顺手改掉 ——
curation_init对源文件做 sha256 基线；验收检查manifest_intact。 - 单通道冒充多通道 —— 各通道必须独立
curation_submit，禁止先合并再提交。 - 冲突被静默抹平 ——
curation_compare逐格写入结论；不一致进入待裁定，不会自动写表。 - 验收只看结果不看过程 —— ledger 逐格留痕；
curation_verify用 SQL 复算覆盖、双通道、留痕与交付一致性。
核心功能¶
单一 SQLite 工作区¶
工作区默认目录 .curation/：project.sqlite 为权威状态；manifest.json 记录源基线；pin.json / pin.sha256 为人读镜像与封印（库内 pin 行为权威）。崩溃后只会是旧表或新表完整状态，不会出现「半张表」。归档时用 curation_pack 将工作区快照、pin、导出器、基线与被引用的项目内脚本打成 zip，可在别处解开继续核对漂移。
两层 pin（v5）¶
pin 是项目口径快照：defaults 提供通道、归一化、证据、门禁与裁定策略默认值；tables[] 按交付表声明主键、字段、记录来源与表级覆盖。签署时计算 pin_hash = sha256(canonical-json) 并封印；改口径需 curation_pin 带 force: true 重签，decision 绑定 pin_id / table_pin_id，旧结论与新 pin 不混用。
可选 rules 块支持 JSON 规则 DSL（validate / merge / decision / verify）；0.18.0 起还可用 R6RS 风格 Scheme 子集编写规则，经 lowering 到同一 v1 AST，详见仓库 docs/RULES.md。
八阶段与工具面¶
README 将流程固定为下列阶段（含立项前的导入、归一与 pin 草稿可选步骤）：
0 立项 curation_init
0b 导入 curation_records_import
0c 归一 curation_identity
0d 草稿 curation_pin_draft
1 签署 curation_pin
2 采集 curation_submit（规模化可用 curation_job）
3 比对 curation_compare
4 落表 curation_apply
5 验收 curation_verify
6 导出 curation_export
7 打包 curation_pack
8 汇报 curation_status / curation_query / curation_note
文档表格列出 19 个 curation_* 工具及主要参数；长任务可用 curation_progress 在 Web UI 输入框上方挂进度条（纯数据，不参与门禁）。
规模化提交（0.16.0）：curation_submit 与 curation_job 支持 from 指向 CSV/JSONL 文件或目录；curation_query({ what: "coverage", table: "..." }) 按字段查看 submitted / accepted / pending。
低门槛起步（0.15.0）：字段未定时可先 curation_records_import → curation_identity → curation_pin_draft → curation_pin({ draftPath: ... })，详见 docs/INTAKE.md。
完整交付（0.17.0）：curation_delivery_plan 与 curation_verify_delivery 生成交付包（curated 导出、pending.csv、review.md、delivery.json 等）；业务门禁仍以 curation_verify 为准。字段可设 "protected": true，落表与部分验收项会跳过该列。
裁定策略由 pin 的 adjudication.compare / select 配置（内置 exact、numeric、ordered-groups 等，或项目内命令 / 批量 batch 模式），非零退出或非法输出时该格进入待裁定，不回落默认策略。
安装与启用¶
环境：运行 DSH 的机器需满足 Node >= 24。安装前请阅读 GitHub 仓库 源码与 MIT 许可证；插件以当前 DSH 进程权限读写项目目录，pin 中的 verifyCmd、裁定外部命令与项目导出器会执行你项目内的脚本，只应放入可信项目。
从社区目录安装： SkillHub 插件页 标注当前可安装版本为 v0.18.0（与仓库 package.json 一致）。该页给出的安装提示原文为（页面未提供独立的 shell 安装命令）：
请安装 DSH 插件 Antigen-1/dsh-data-curation。先读取..
在 DSH 中按 SkillHub 与 DSH 文档约定完成插件安装后，profile 会通过 bundle patch 注册本插件；默认状态目录为 .curation。README 注明 0.18.0 尚未发布到 npm，以 GitHub / 目录分发为准。
典型用法¶
低门槛：从 CSV 到签署 pin¶
适合字段尚在迭代、尚未手写完整 pin 的场景：
curation_records_import({ path: "input/records.csv", key: "record_id" })
curation_identity({ path: "input/records.csv", rename: {...}, exclude: [...], fileMap: {...} })
curation_pin_draft({ recordsPath: ".curation/records/main.jsonl", table: "summary" })
curation_pin({ draftPath: ".curation/pin.draft.json" })
curation_records_import 支持 CSV/JSONL；Excel 需先导出为 CSV。
完整核对流程（README「真实项目里的用法」）¶
- 建项目：
curation_init({ cwd, sources: ["raw/"], tables: ["esd_main"] })。 - 编写 pin：先
curation_pin({ ..., dryRun: true })核对 hash 与字段，再正式签署。 - 各通道独立抽取并提交，例如：
curation_submit({ table: "esd_main", channel: "text", batch: "B001", records: [...] })
不要把 text 通道结果再喂给 vision 通道。
curation_compare({ table: "esd_main" })；用curation_query({ what: "pending" })查看待裁定。curation_apply({ table: "esd_main" })（建议先dryRun）。curation_verify()—— PASS 之前不要宣称核对完成。curation_export({ format: "sqlite" })或按表导出 csv/jsonl/markdown。curation_pack()归档；换环境后 manifest 仍可复算源基线漂移。
从文件批量提交¶
curation_submit({ channel: "text", batch: "B001", from: "input/text.jsonl" })
curation_job({ action: "start", channel: "text", batch: "B001",
from: "input/text/", chunkSize: 200 })
curation_job({ action: "status", jobId: "job-..." })
curation_query({ what: "coverage", table: "summary" })
适用场景与注意¶
适合：需要从 PDF/文档/多模态通道抽取结构化字段、要求双通道一致才入库、需要可 SQL 复算验收与 zip 归档的核对项目；多表交付（每张表独立 tables[] 条目，数据按 (table_id, …) 隔离）。
注意：
- 同一项目建议单写者（写操作持有
.curation/lock）。 - 一次 pin 覆盖整个项目；不存在只改一张表而不重签的路径。
curation_verify结论优先级为 FAIL > CONDITIONAL > PASS；仅有待裁定时为 CONDITIONAL。- 插件不加密工作区；通道同源检测、OCR 自动触发等能力 README 标明尚未内建。
- DSH 生态是「一切皆插件」；SkillHub 为社区目录站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-data-curation 把表格型核对从「对话里改表」拉回到 pin 契约 + 多通道证据 + SQLite 留痕 + 统一验收门禁 的可审计流水线。若要查看版本说明与安全策略，见仓库 CHANGELOG.md 与 SECURITY.md。
