diffino

Declarative data diff & text-correction toolkit for tables and documents, powered by Polars. 声明式数据差异对比与文本校对工具包（表与文档），基于 Polars。 Compare Excel, CSV, Parquet, DuckDB, or DOCX files and generate detailed reports with character-level inline diffs — plus a reusable text-correction backend (diffino.correction). 对比 Excel、CSV、Parquet、DuckDB、DOCX，输出带字符级行内差异的详细报告；并提供可复用的文本校对后端（diffino.correction）。

Output formats / 输出格式：Excel、HTML、Typst PDF、DOCX track-changes / DOCX 修订、Changelog / 累积变更日志。

What's New / 版本更新（v0.5.0 · 2026-09-03）

• Text-correction backend / 文本校对后端（diffino.correction，CorrectBackend）：新增纯 Python/Polars 校对后端，面向“表格/文档文本修订评审”场景：
  • decisions 载入与迁移 / Load & migration：读取评审 decisions（accept/ignore），源内容变化后按关键字段自动继承旧 accept；
  • 歧义预检 / Ambiguity preflight：原文在单元格内出现多次时标记 ambiguous，永不自动误改（全局替换通道除外）；
  • V1 / V2 版本生成 / Version generation：V1 = 仅人工认可（accept + 高置信通道），V2 = 全建议预览（低置信通道可配置排除）；
  • 重叠合并与冲突清单 / Merge & conflicts：同位置多条建议按“模拟结果一致”合并，不一致写入冲突清单等待人工裁决，冲突不自动应用；
  • 清单与统计 / Manifest & type summary：版本清单（manifest）与按类型摘要（应用/歧义/已覆盖/合并/冲突/可疑）全量留痕；
• Domain-neutral core / 领域无关核心：输入列名与通道语义（全局替换通道、漏检补充通道、合并优先级等）经 CorrectionSchema 注入，默认英文列名开箱即用，核心不硬编码任何领域列名；中文等任意领域只需自定义 schema；
• Composable API / 可组合：不依赖 CLI 与 Kedro，可直接 import 组合进评审流程，并能与 diffino 的版本差异报告（V1/V2 → diff.pdf）天然衔接。

说明：v0.5.0a1 为同批实验性预发布；本版为正式发布，功能与 a1 一致。

Installation / 安装

pip install diffino-cli

For development / 开发模式：

pip install -e ".[dev]"

Quick Start / 快速开始

1. Prepare a config file / 准备配置文件：

sources:
  left:
    type: excel
    path: data/v0.2.5.xlsx
  right:
    type: excel
    path: data/v0.2.6.xlsx
    version: "0.2.6"

compare:
  - left_sheet: Sheet1
    key_columns:
      - ID
    ignore_columns:
      - Notes

output:
  project: 我的项目
  formats:
    - excel
    - changelog
  changelog:
    split: true
  report_dir: ./diffs

2. Run diffino / 运行对比：

diffino run config.yaml

3. Or generate a changelog from saved reports / 或从已保存报告生成变更日志：

diffino changelog generate --input-dir ./diffs --releases releases.yaml --split

Text correction / 文本校对（v0.5.0 新增）

diffino.correction 是一个纯 Python/Polars 后端，不依赖 CLI。以英文列名 CorrectionSchema 为例，生成 V1/V2 版本：

import polars as pl
from diffino.correction import CorrectionSchema, make_v1, make_v2

schema = CorrectionSchema.english()   # 列名: rule_code/column/original/suggestion/type/decision/note
source = pl.read_csv("rules.csv")
decisions = pl.read_csv("decisions.csv")   # 人工评审产物（accept/ignore）

v1, applied1 = make_v1(source, decisions, force_accept_types=("review",), cschema=schema)
v2, applied2, pending = make_v2(source, decisions, exclude_types=("low_precision",), cschema=schema)

领域（如中文列名 + 全局替换通道/合并优先级）由调用方提供自己的 CorrectionSchema 并注入，核心代码零领域硬编码。

Features / 功能

• Multi-format sources / 多格式数据源：Excel、CSV、Parquet、DuckDB、DOCX
• Key-based or fingerprint matching / 键或指纹匹配：复合键或整行哈希进行行匹配
• Column preprocessing / 列预处理：小数舍入、文本归一化、日期格式归一化、百分比换算
• Character-level inline diff / 字符级行内差异：删除内容红色删除线、新增内容绿色加粗
• DOCX paragraph diff / DOCX 段落对比：正文逐段对比并输出行内差异
• Text-correction backend / 文本校对后端（v0.5.0）：decisions 迁移 / 歧义预检 / V1/V2 生成 / 重叠合并与冲突清单 / manifest / 按类型摘要（diffino.correction）
• Six output formats / 六种输出格式：
  • Excel：新旧行并排、变更单元格黄色高亮、富文本行内差异；final / side_by_side / track 样式
  • HTML：自包含报告，<del>/<ins> 标签 + JS 过滤
  • Typst：带封面、彩色表格与字符级行内差异的 Typst PDF
  • DOCX track-changes / DOCX 修订：原生 Word 修订跟踪（<w:ins>/<w:del>）——DOCX 源就地输出，其他源生成对照表
  • Changelog / 变更日志：累积变更日志 Typst 文件（_summary.typ + _detail.typ），随每次运行自动生成并汇总同目录历史报告
  • json-summary / JSON 摘要：供 CI/CD 消费的结构化摘要
• Typst cover page / Typst 封面：可配置项目名——{{PROJECT}}对比报告
• DiffReport persistence / 报告持久化：自动保存 JSON 报告（{old}__{new}.json）供日志累积
• Version auto-detection / 版本自动识别：解析 name-vX.Y.Z.ext，也可在 YAML 中手动指定
• Changelog generation / 变更日志生成：diffino changelog generate——版本汇总表 + 逐版本明细，--split 拆分摘要/明细
• Release date config / 发布日期配置：releases.yaml 或内联配置映射版本→日期
• Parallel processing / 并行处理：ThreadPoolExecutor + 可配 max_workers，支持多 Sheet 并行
• CI/CD integration / CI/CD 集成：--fail-on-diff 退出码、--summary Markdown 表、json-summary 供流水线消费

CLI Commands / CLI 命令

diffino run

diffino run config.yaml                 # 运行对比 / Run comparison
diffino run config.yaml --fail-on-diff  # 有差异则退出码 1 / Exit 1 if differences found
diffino run config.yaml --summary       # 输出 Markdown 摘要到 stdout
diffino run config.yaml --summary --summary-detail  # 含单元格级明细

在 output.formats 加入 changelog，每次运行自动生成累积变更日志：

output:
  formats:
    - excel
    - changelog        # 自动生成 changelog_summary.typ + changelog_detail.typ
  changelog:
    path: changelog.typ     # 默认 / default
    split: true             # 默认 / default: true
    summary_keep: 3         # 默认 / default: 3
    max_summary_items: 3    # 默认 / default: 3
    releases: releases.yaml # 发布日期配置

formats 含 changelog 时 save_report 自动开启——DiffReport JSON 总会被保存。

diffino validate

diffino validate config.yaml    # 仅校验配置 / Validate config only

diffino changelog generate

diffino changelog generate                # 生成 changelog.typ
  --input-dir ./diffs                     #   diff JSON 目录
  --output changelog.typ                  #   输出 Typst 文件
  --releases releases.yaml                #   发布日期配置
  --summary-keep 3                        #   摘要展示版本数（默认 3）
  --max-summary-items 3                   #   每版本条目数上限（默认 3）
  --split                                 #   拆分为 _summary.typ + _detail.typ

Source Types / 数据源类型

DOCX mode / DOCX 模式

sources.*.type = docx 时，Sheet 按表格标题匹配（精确 / 模糊 / 1-based 序号）。 在对比单元里设 content: paragraphs 可对比文档正文而不是表格：

compare:
  # 按表格标题对比 / Table diff by caption
  - left_sheet: 表1-客户列表
    key_columns:
      - 客户ID
  # 正文段落对比 / Paragraph diff
  - content: paragraphs

Configuration Reference / 配置参考

完整示例见 config.example.yaml。

Column preprocessing rules / 列预处理规则

column_rules:
  - column: 金额
    type: decimal
    precision: 2
  - column: 名称
    type: text
    normalize_whitespace: true
    case_sensitive: false
  - column: 发布日期
    type: date
    format: "%Y-%m-%d"
    input_format: "%Y/%m/%d"   # 可选 / optional
  - column: 增长率
    type: percentage
    precision: 2

Releases config / 发布日期配置（releases.yaml）

支持两种格式：

带项目名（推荐）/ With project name (recommended)：

name: 穿透监管规则明细表
releases:
  - version: "v1.0"
    date: 2026-02-13
  - version: "v1.1"
    date: 2026-05-19

旧版扁平列表 / Legacy flat list：

releases:
  - version: "0.2.5"
    date: 2026-05-19
  - version: "0.2.6"
    date: 2026-05-20

releases 也可以内联写在主配置的 output.releases 下。

Changelog / 变更日志

通过 diffino run（推荐 / recommended）

在 output.formats 加 changelog。DiffReport JSON 自动保存到 output.report_dir （默认 ./diffs）并命名为 {old_version}__{new_version}.json。每次运行后，该目录下 所有 JSON 报告会被加载，生成累积 changelog_summary.typ + changelog_detail.typ。

output:
  formats:
    - changelog
  changelog:
    split: true

独立生成 / Standalone：diffino changelog generate

diffino changelog generate --input-dir ./diffs --split

输出内容 / Changelog output

• Summary / 摘要（_summary.typ）：版本表——每个版本的日期与变更计数
• Detail / 明细（_detail.typ）：逐版本段落——每条新增/删除/修改行及新旧值行内差异

不传 --split（或配置 split: false）时输出单一 changelog.typ。

Project Structure / 项目结构

├── src/diffino/
│   ├── comparator.py          # 行匹配与对比核心 | Row matching & comparison core
│   ├── loader.py              # 多格式数据加载 | Multi-format data loading
│   ├── preprocessor.py        # 列预处理 | Column preprocessing
│   ├── diff_model.py          # 差异数据模型 | Diff data model
│   ├── config.py              # 配置解析 | Config parsing
│   ├── correction/            # ★ 文本校对后端 CorrectBackend（v0.5.0）
│   │   ├── schema.py          #   CorrectionSchema（列映射/通道语义）
│   │   └── core.py            #   decisions/V1/V2/合并/冲突/manifest
│   ├── changelog/             # 累积变更日志 | Cumulative changelog
│   ├── renderers/             # Excel/HTML/Typst/DOCX 渲染器
│   ├── pdf/                   # PDF 提取与对比 | PDF extraction & compare
│   ├── docx_source.py         # DOCX 数据源 | DOCX source
│   └── main.py                # CLI（Typer）| CLI entry
├── config.example.yaml        # 配置示例 | Example config
└── pyproject.toml

Recent Changes / 近期变更

2026-09-03 · v0.5.1（文档修订 / docs revision）

• README 中英双语化并完善 v0.5.0 diffino.correction 功能介绍（纯功能向，不依赖任何下游项目语境）；同步 PyPI 描述。

2026-09-03 · v0.5.0（正式发布 / formal release）

功能与 0.5.0a1 实验版一致；0.5.0a1 为同批预发布（PyPI 保留，仓库标签以 v0.5.0 为准）。

• 新增 diffino.correction（CorrectBackend / 文本校对后端）：decisions 载入与迁移、歧义预检、V1/V2 版本生成、重叠建议合并与冲突清单、版本清单（manifest）与按类型摘要；输入列名与通道语义经 CorrectionSchema 注入（默认英文列名），核心不硬编码领域列名；
• 校对能力为纯 Python/Polars API，不依赖 CLI，可直接在评审工作流中组合使用。

2026-09-03 · v0.5.0a1（实验性预发布 / experimental pre-release）

• 与 v0.5.0 相同的 correction 后端能力（保留为发布历史）。

2026-05-22 · v0.4.1

• diffino run 支持 changelog 输出格式——每次运行自动生成累积 changelog_summary.typ + changelog_detail.typ；
• Changelog 渲染器自动创建输出目录；README 重写（DOCX 源、段落差异、changelog 格式、 完整配置参考）。

2026-05-21 · v0.4.0

• DOCX 源支持：按标题表格对比 + 正文段落对比；
• DOCX track-changes 渲染器（docx_track），原生 Word 修订跟踪。

2026-05-20 · v0.3.x

• Changelog 独立生成（diffino changelog generate）、Typst 封面、DiffReport JSON 持久化、releases 版本→日期配置、键列归一化等。

2026-05-19 · v0.1.0–0.2.x

• 初版：Excel/CSV/Parquet 加载、键与指纹匹配、列预处理、Excel/HTML/Typst 输出、 字符级行内差异、DuckDB 源、并行多 Sheet 处理、CI/CD 退出码与摘要。

License / 许可证

MIT