前言¶

在 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 歸納的四類典型事故與對應機制如下：

1. 原始數據被順手改掉 —— curation_init 對源文件做 sha256 基線；驗收檢查 manifest_intact。
2. 單通道冒充多通道 —— 各通道必須獨立 curation_submit，禁止先合併再提交。
3. 衝突被靜默抹平 —— curation_compare 逐格寫入結論；不一致進入待裁定，不會自動寫表。
4. 驗收只看結果不看過程 —— 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「真實項目裏的用法」）¶

1. 建項目：curation_init({ cwd, sources: ["raw/"], tables: ["esd_main"] })。
2. 編寫 pin：先 curation_pin({ ..., dryRun: true }) 覈對 hash 與字段，再正式簽署。
3. 各通道獨立抽取並提交，例如：

curation_submit({ table: "esd_main", channel: "text", batch: "B001", records: [...] })

不要把 text 通道結果再餵給 vision 通道。

4. curation_compare({ table: "esd_main" })；用 curation_query({ what: "pending" }) 查看待裁定。
5. curation_apply({ table: "esd_main" })（建議先 dryRun）。
6. curation_verify() —— PASS 之前不要宣稱覈對完成。
7. curation_export({ format: "sqlite" }) 或按表導出 csv/jsonl/markdown。
8. 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。

• 社區目錄：https://www.skillhub.cn/plugins/Antigen-1/dsh-data-curation
• 源碼與文檔：https://github.com/Antigen-1/dsh-data-curation