mdpolish

实验室共用的 Markdown 清洗研究与基础工具库。项目不属于 GovDoc 专用组件，也不只服务政务文档。

本仓库面向实验室内不同项目复用，用于清洗 PDF、DOCX、OCR、网页等上游管线生成的 Markdown，统一解决 格式噪声、结构损坏、内容异常、修改追踪和多用途派生问题。各项目共享通用清洗能力，再通过独立配置或 profile 表达论文、政务文档、RAG、文档对比等不同需求。

仓库当前已从纯文档治理进入第一版核心实现阶段：已经提供可安装的 Python 内存处理包和测试，用于验证 组件组合、精确修改和审计协议，并已有一个严格整行匹配的论文清洗组件。仓库仍不提供完整规则集、命令行工具、 文件读写适配器或生产接口，因此目前还不是拿来即可完成整篇文档清洗的成品工具。

当前阶段

项目当前已经进入第一版可执行核心和真实组件验证阶段：

• 提供可安装的 Python 3.11+ 内存处理包，运行时只依赖标准库；
• 已实现不可变数据契约、组件基类、原子修改执行器、顺序流水线、审计记录和最终稳定性复查；
• 当前唯一正式组件是 paper.arxiv_submission_stamp，只删除严格整行匹配的 arXiv 提交边栏戳；
• 该组件已在 5 份论文 Markdown 上只读验证，只命中 sim 和 springer 各一处，合法参考文献保持不变；
• 当前基础检查为 Ruff、mypy 和 87 项 pytest 测试，实际命令见本文“当前可用检查”。

项目还没有完整清洗规则集、Markdown/HTML parser、profile 格式、文件读写、CLI、批处理或生产接口。当前组件 只能证明第一条严格规则已经闭环，不能据此认为论文、GovDoc、表格或图片已经具备完整清洗能力。

服务对象与复用目标

当前已经明确的使用场景包括：

• 论文清洗：data/ 中现有内容来自师姐的项目，包含论文 PDF 的 Markdown、JSON、图片等转换产物；
• GovDoc：政务、招投标、采购、合同等文档的清洗、比对和 RAG 前处理；
• 未来实验室项目：后续可以继续接入其他需要 Markdown 质量检查、规范化或用途派生的项目数据。

当前用例只用于发现真实问题和验证通用能力，不能反过来限定库的设计。核心代码不得依赖论文 DOI、 GovDoc 目录、具体客户名称或某一转换器的固定输出路径。

测试数据

• 论文 Markdown：data/md/，共 5 份，按 ClinDB-ReviewBench 中使用的论文缩写命名， 供本地查看和组件只读验证；
• GovDoc Markdown：/home/lihaoze/gov_test_data/compare，共 7 组、45 份，输入位于各组 uploads/ 下， 保持仓库外只读，不复制到本项目。

两组数据都不是可提交的自动测试 fixture。data/ 已被 Git 忽略，清洗实验不得覆盖这些输入。

面向复用的设计原则

• 通用核心：只接收 Markdown；第一版只执行确定、可审计的精确修改，不读取 PDF、图片或转换器 JSON；
• 输入边界：PDF/OCR/DOCX/HTML 转换和外部材料核验由使用项目或上游流程负责，不写入共用组件契约；
• 项目 profile：论文、GovDoc、对比、RAG、公开脱敏等规则独立组合，不互相污染默认行为；
• 保真优先：不确定内容默认保留；当前核心不猜测修改，也不承担人工确认流程；
• 可复现：规则、配置、输入哈希、输出和每次变更都可以追踪；
• 可扩展：新增项目在自身边界处理上游适配，并主要组合或补充组件和 profile，而不是复制一套清洗器。

目录结构

mdpolish/
├── .gitignore
├── AGENTS.md
├── CLAUDE.md
├── README.md
├── pyproject.toml                    # Python 包、构建和开发检查配置
├── src/
│   └── mdpolish/
│       ├── __init__.py               # 第一版核心公共导出
│       ├── component.py              # 组件基类和元数据契约
│       ├── edits.py                  # 文本编辑验证与原子应用
│       ├── models.py                 # 不可变数据模型和运行状态
│       ├── pipeline.py               # 顺序执行和最终稳定性复查
│       ├── py.typed                   # 类型信息声明
│       └── components/
│           ├── __init__.py
│           └── arxiv_submission_stamp.py
├── tests/
│   ├── test_arxiv_submission_stamp.py
│   ├── test_component.py
│   ├── test_edits.py
│   ├── test_models.py
│   └── test_pipeline.py
├── data/                              # 本地测试数据；Git 忽略；此处只展开常用入口
│   └── md/
│       ├── dmp.md
│       ├── ejhf.md
│       ├── jama.md
│       ├── sim.md
│       └── springer.md
└── research-wiki/
    ├── README.md                       # Wiki 分类与维护规则
    ├── design/                         # 批准前的选择；批准后冻结
    ├── explanation/                    # 当前有效机制及原因
    ├── reference/                      # 稳定查询事实
    ├── guides/                         # 已验证操作步骤
    └── scratch/                        # 调研和未收敛材料

开始工作

进入仓库后依次阅读：

1. 本文件，确认当前阶段；
2. AGENTS.md 或 CLAUDE.md，确认协作与安全边界；
3. research-wiki/README.md，确认文档应放在哪里；
4. 与任务直接相关的 research-wiki/design/ 记录。

第一版核心的当前机制见 research-wiki/explanation/first-executable-core.md，首个真实组件见 research-wiki/explanation/arxiv-submission-stamp.md。下一项候选是 ClinDB 范围中的 HTML 实体双重转义， 但必须先用新 design 确定只在哪些 HTML 范围替换、如何避开字面示例以及实体替换边界。解析器、CLI、文件适配器、 profile 格式和独立检查能力仍需分别设计，不能从当前核心或单个组件存在推导为已经获批。

当前可用检查

# 建立隔离环境并安装包与开发检查工具
python -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'

# 第一版核心的基础验收
.venv/bin/ruff check .
.venv/bin/mypy src tests
.venv/bin/pytest

# 两份 Agent 入口除标题外必须一致；无输出且退出码为 0 表示通过
diff -u <(tail -n +2 AGENTS.md) <(tail -n +2 CLAUDE.md)

# 查看当前 Wiki 中实际存在的文档
find research-wiki -maxdepth 2 -type f | sort

# 检查本地变更
git status --short

上述安装和三项基础验收已于 2026-08-22 在 Python 3.13.11 环境实际运行：Ruff 通过，mypy 检查 12 个源码与 测试文件无问题，pytest 共 87 项测试通过。requires-python 仍以 pyproject.toml 声明的 Python 3.11 及以上为准； 本次结果不等于已经在每个受支持版本上完成兼容性验证。