# mdpolish 实验室共用的 Markdown 清洗研究与基础工具库。项目不属于 GovDoc 专用组件，也不只服务政务文档。 本仓库面向实验室内不同项目复用，用于清洗 PDF、DOCX、OCR、网页等上游管线生成的 Markdown，统一解决 格式噪声、结构损坏、内容异常、修改追踪和多用途派生问题。各项目共享通用清洗能力，再通过独立配置或 profile 表达论文、政务文档、RAG、文档对比等不同需求。 仓库当前已从纯文档治理进入第一版核心和 ClinDB 第一批组件实现阶段：已经提供可安装的 Python 内存处理包、 8 个论文清洗组件、本地实验入口，以及同仓但与清洗运行解耦的只读评审前端。实验可以保存指定论文的成功输出、 审计和 diff；评审前端可以同时查看清洗前后全文，并逐组件复放修改。仓库仍不提供面向任意数据集的完整规则集、 公共命令行工具、通用文件适配器或生产接口，因此目前还不是拿来即可完成任意 Markdown 清洗的成品工具。 ## 当前阶段 项目当前已经进入第一版可执行核心和真实组件验证阶段： - 提供可安装的 Python 3.11+ 内存处理包，运行时只依赖标准库； - 已实现不可变数据契约、组件基类、原子修改执行器、顺序流水线、审计记录和最终稳定性复查； - 已实现 ClinDB 第一批 8 个正式组件，覆盖 Word 批注、手稿行号、arXiv 戳、重复页眉、批准映射断词、 HTML 表格实体与布局、参考文献空行； - 已有仓库内实验运行层，能严格读取显式清单、保存成功 Markdown、JSON 审计、unified diff 和评审定位文件， 并保持输入不变； - 已有独立的 `reviewer/` 本地只读前端，服务只消费一次已发布的产物和定位文件，并与报告层共用纯 Python 快照重放逻辑， 不导入组件、不调用流水线，也不重新清洗； - 第一批流水线已对 5 份论文 Markdown 完成保存型实验，5/5 成功，共记录 155 条修改，第二次运行零修改； - 当前基础检查为 Ruff、mypy、229 项 pytest 测试，以及前端 ESLint、TypeScript、9 项 Vitest 测试和生产构建， 实际命令见本文“当前可用检查”。 项目还没有面向任意数据集的完整清洗规则集、Markdown/HTML 通用 parser、profile 格式、通用文件输入接口、公共 CLI、 通用批处理或生产接口。评审前端也不是公共 Web 服务：它只绑定本机回环地址，只读展示 Markdown 源文和审计，不提供 渲染预览、在线编辑或重新清洗。当前 first-batch 实验脚本只固定运行已批准的 5 份论文和 8 个组件；它只能证明当前 8 类确定规则已经闭环，不能据此认为论文中的缺失内容、乱码、复杂表格、图片或 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 忽略，清洗实验不得覆盖这些输入。 本地清洗实验产物位于 `artifacts//runs//`。产物可能包含完整原文；其中评审定位文件还包含 输入源的绝对路径，因此整个目录均受 Git 忽略，默认保留 30 个日历日，不得提交或复制到外部系统。当前只批准为上述 5 份论文副本保存产物，未批准保存 GovDoc 输出。 ## 面向复用的设计原则 - **通用核心**：只接收 Markdown；第一版只执行确定、可审计的精确修改，不读取 PDF、图片或转换器 JSON； - **输入边界**：PDF/OCR/DOCX/HTML 转换和外部材料核验由使用项目或上游流程负责，不写入共用组件契约； - **项目 profile**：论文、GovDoc、对比、RAG、公开脱敏等规则独立组合，不互相污染默认行为； - **保真优先**：不确定内容默认保留；当前核心不猜测修改，也不承担人工确认流程； - **可复现**：规则、配置、输入哈希、输出和每次变更都可以追踪； - **可扩展**：新增项目在自身边界处理上游适配，并主要组合或补充组件和 profile，而不是复制一套清洗器。 ## 目录结构 ```text mdpolish/ ├── .gitignore ├── AGENTS.md ├── CLAUDE.md ├── README.md ├── pyproject.toml # Python 包、构建和开发检查配置 ├── src/ │ └── mdpolish/ │ ├── __init__.py # 第一版核心公共导出 │ ├── _artifact_replay.py # 报告与评审器共用的纯快照重放 │ ├── component.py # 组件基类和元数据契约 │ ├── edits.py # 文本编辑验证与原子应用 │ ├── experiment.py # 本地实验输入预检与批量编排 │ ├── models.py # 不可变数据模型和运行状态 │ ├── pipeline.py # 顺序执行和最终稳定性复查 │ ├── reporting.py # JSON 审计、行列位置和 unified diff │ ├── artifact_store.py # 私有产物目录和原子发布 │ ├── _html_table.py # 严格 HTML 表格词法范围 │ ├── _text_ranges.py # 精确物理行与换行范围 │ ├── py.typed # 类型信息声明 │ └── components/ │ ├── __init__.py │ ├── arxiv_submission_stamp.py │ ├── html_table_double_escape.py │ ├── html_table_layout.py │ ├── manuscript_line_number.py │ ├── page_break_word_join.py │ ├── reference_spacing.py │ ├── repeated_running_header.py │ └── word_review_comment.py ├── scripts/ │ ├── run_clindb_arxiv_experiment.py # 只含 arXiv 组件的历史实验入口 │ └── run_clindb_first_batch_experiment.py # ClinDB 第一批 8 组件实验入口 ├── reviewer/ # 与组件和流水线解耦的本地只读评审器 │ ├── .nvmrc # 前端开发使用 Node.js 24 │ ├── package.json # React 依赖、检查和构建命令 │ ├── server/ # Python 产物适配、快照重放接口和本地 HTTP 服务 │ ├── src/ │ │ ├── client/ # React 全文对比、组件时间线和审计界面 │ │ └── shared/ # 浏览器使用的内部 API 类型 │ └── tests/ # 前端响应、界面和源码安全测试 ├── tests/ │ ├── test_arxiv_submission_stamp.py │ ├── test_artifact_store.py │ ├── test_clindb_first_batch_pipeline.py │ ├── test_component.py │ ├── test_edits.py │ ├── test_experiment.py │ ├── test_html_table_double_escape.py │ ├── test_html_table_layout.py │ ├── test_manuscript_line_number.py │ ├── test_models.py │ ├── test_page_break_word_join.py │ ├── test_pipeline.py │ ├── test_reference_spacing.py │ ├── test_repeated_running_header.py │ ├── test_reporting.py │ ├── test_word_review_comment.py │ ├── test_artifact_replay.py │ ├── test_reviewer_artifacts.py │ └── test_reviewer_server.py ├── data/ # 本地测试数据；Git 忽略；此处只展开常用入口 │ └── md/ │ ├── dmp.md │ ├── ejhf.md │ ├── jama.md │ ├── sim.md │ └── springer.md ├── artifacts/ # 本地敏感实验产物；Git 忽略 │ └── /runs// │ ├── manifest.json │ ├── review-locator.json # 输入源定位和哈希；仅供本地评审 │ └── documents/ └── 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`，ClinDB 第一批组件见 `research-wiki/explanation/clindb-first-batch-components.md`，本地实验产物机制见 `research-wiki/explanation/local-experiment-artifacts.md`，本地评审器机制见 `research-wiki/explanation/local-markdown-reviewer.md`。实验和评审器的实际操作分别见 `research-wiki/guides/run-local-clindb-first-batch-experiment.md` 和 `research-wiki/guides/review-local-cleaning-run.md`。 解析器、CLI、文件适配器、profile 格式、图片资产打包和独立检查能力仍需分别设计；当前本地实验适配器和评审器不能 被推导成这些公共接口已经获批。 ## 当前可用检查 ```bash # 建立隔离环境并安装包与开发检查工具 python -m venv .venv .venv/bin/python -m pip install -e '.[dev]' # 第一版核心的基础验收 .venv/bin/ruff check . .venv/bin/mypy src tests scripts/run_clindb_arxiv_experiment.py scripts/run_clindb_first_batch_experiment.py .venv/bin/pytest # 本地评审器要求 Node.js 24 LTS；安装依赖后依次执行静态检查、测试和生产构建 cd reviewer nvm use npm ci npm run check cd .. # 两份 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 ``` 上述 Python 验收已于 2026-08-24 在 Python 3.13.11 环境实际运行：Ruff 通过，mypy 检查 43 个源码、测试和实验脚本文件 无问题，pytest 共 229 项测试通过。评审器验收也在当前用户 nvm 的 Node.js 24.19.0 环境实际运行：ESLint 和 TypeScript 通过，Vitest 共 9 项测试通过，生产构建成功；并以一批真实的 5 文档、8 组件、155 条修改产物验证了接口读取和逐阶段哈希。 当前环境没有可用的图形浏览器，因此页面视觉布局尚未进行真实浏览器人工验收。`requires-python` 仍以 `pyproject.toml` 声明的 Python 3.11 及以上为准；本次结果不等于已经在每个受支持版本上完成兼容性验证。