# mdpolish

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

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

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

## 当前阶段

2026-08-20 已完成仓库重置与最小文档治理骨架：

- 原有 Python 实现、YAML 规则、测试和打包配置已经移除；
- `AGENTS.md` 与 `CLAUDE.md` 提供同步的协作规则；
- `research-wiki/` 按文档生命周期区分设计、说明、参考、指南和草稿；
- `research-wiki/design/0001-repository-foundation.md` 记录本次基础架构选择。
- `research-wiki/reference/GOVDOC_SAAS_CLEANING_SCOPE.md` 保存 45 份外部测试 Markdown 的只读问题审计；
- `research-wiki/scratch/markdown-cleaning-ecosystem-research-2026-08-20.md` 完成首轮生态与架构调研。
- 2026-08-21 完成师姐项目（ClinDB-ReviewBench）5 份论文 Markdown 的问题审计
  （`research-wiki/scratch/data-5papers-cleaning-audit-2026-08-21.md`），并确定其第一版清洗范围
  （`research-wiki/reference/CLINDB_REVIEWBENCH_CLEANING_SCOPE.md`，8 类自动清洗候选）。
- 2026-08-21 明确本项目定位为实验室共用库；GovDoc 和论文清洗都是使用场景，不是核心边界。
- 2026-08-21 批准并冻结 `research-wiki/design/0002-composable-cleaning-pipeline.md`，确定只接收 Markdown、
  项目显式组装组件、单轮修改加最终只读复查的总体组织方式。
- 2026-08-22 批准并冻结 `research-wiki/design/0003-first-executable-core-architecture.md`，确定第一版只建设
  Python 内存自动清洗核心：组件只提出确定可执行的精确修改，不同时建设独立检查、人工建议或真实清洗规则。
- 2026-08-22 按 `0003` 实现第一版内存核心和测试：包括不可变数据契约、组件基类、原子修改执行器、
  顺序流水线和最终稳定性复查；58 项测试以及 Ruff、mypy 检查均通过。
- 2026-08-22 批准并实现 `research-wiki/design/0004-arxiv-submission-stamp-component.md`：新增严格整行匹配的
  arXiv 提交边栏戳删除组件；5 份论文只读复核只命中 sim 和 springer 各一处，两处合法参考文献保持不变，
  第二次运行零修改，源文件没有变化。
- 2026-08-21 完成 HTML 表格清洗专题调研
  （`research-wiki/scratch/html-table-cleaning-ecosystem-research-2026-08-21.md`）：核实 Pandoc 表格
  方言能力边界、Turndown 不处理合并单元格、Docling Markdown 导出重复合并单元格内容、MinerU 全
  HTML 输出，印证审计 T001 的分流方向。
- 2026-08-21 完成 45 份测试 Markdown 中 HTML 表格的只读结构分析
  （`research-wiki/scratch/html-table-real-data-analysis-2026-08-21.md`）：剔除空 `<tr>` 后
  简单表 53% / 合法合并表 8% / 损坏表 40%，并定位标签不闭合、丢失 colspan 标注、无表头三类主因。
- 2026-08-21 仓库由 `govdoc-md-cleaner` 更名为 `mdpolish`，GitHub 远程仓库与本地目录同步改名；
  冻结的 design 记录和带日期的 scratch 笔记保留当时的旧名。

当前已有只处理内存字符串的底层执行机制和函数级契约，运行时只依赖 Python 标准库。组件可以针对当前
Markdown 快照提出精确修改，流水线负责原子应用、审计记录、失败隔离和最终稳定性复查。当前唯一正式组件只删除
完整匹配的 arXiv 提交边栏戳，不能把这一项能力理解为已经具备完整论文、GovDoc、表格或图片清洗能力。
调研报告中的解析器、内部 IR、具体 profile 和其他真实清洗规则仍是候选方案，尚未批准。

## 服务对象与复用目标

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

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

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

## 面向复用的设计原则

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

## `data/` 的职责

`data/` 是实验室项目的本地数据工作区。当前存放师姐论文清洗项目的输入和转换产物，未来可能继续加入
其他项目的数据。新增数据时应逐步按项目命名空间组织，例如 `data/<project_id>/...`，避免不同项目的
输入、产物和评测结果混在一起。

数据目录与通用库保持以下边界：

- `data/` 已被 Git 忽略，不作为库源码、公开 fixture 或发布包的一部分；
- 默认把项目数据视为只读输入，清洗结果写到独立输出位置，不覆盖原文件；
- 数据可以推动通用规则设计，但项目专属规则必须进入对应 profile；
- 测试需要的公开样例应单独制作脱敏、最小化 fixture，不能直接复制真实项目文档；
- `/home/lihaoze/gov_test_data` 等仓库外真实材料同样保持只读，不复制、不修改、不提交。

任何清洗语义、规则格式、评估指标、代码目录或运行依赖，都应先形成设计记录并获得确认。研究结果进入
具体项目或生产系统前，还需要在使用方范围内独立验证。

## 目录结构

```text
mdpolish/
├── AGENTS.md
├── CLAUDE.md
├── README.md
├── pyproject.toml          # Python 包、构建和开发检查的唯一配置
├── src/mdpolish/           # 第一版内存核心和已批准的业务组件
├── tests/                  # 核心契约和组合行为测试
├── data/                   # 本地项目数据；Git 忽略，未来按项目分区
└── research-wiki/
    ├── README.md
    ├── 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 格式和独立检查能力仍需分别设计，不能从当前核心或单个组件存在推导为已经获批。

## 当前可用检查

```bash
# 建立隔离环境并安装包与开发检查工具
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 及以上为准；
本次结果不等于已经在每个受支持版本上完成兼容性验证。