实现第一版内存清洗核心

落实不可变数据契约、组件基类、原子修改执行器与顺序流水线。补充稳定性复查、审计记录、测试和当前机制文档。

README.md

@@ -6,8 +6,9 @@
 格式噪声、结构损坏、内容异常、修改追踪和多用途派生问题。各项目共享通用清洗能力，再通过独立配置或
 profile 表达论文、政务文档、RAG、文档对比等不同需求。
 
-仓库当前仍处于研究和方案设计阶段：用于澄清问题、记录设计选择、积累可复核证据，并在方案获得确认后
-再建立实现。它目前不是可安装的 Python 包，也不提供命令行工具或生产接口。
+仓库当前已从纯文档治理进入第一版核心实现阶段：已经提供可安装的 Python 内存处理包和测试，用于验证
+组件组合、精确修改和审计协议。仓库仍不提供真实清洗规则、命令行工具、文件读写适配器或生产接口，
+因此目前还不是拿来即可清洗文档的成品工具。
 
 ## 当前阶段
 
@@ -25,8 +26,10 @@ profile 表达论文、政务文档、RAG、文档对比等不同需求。
 - 2026-08-21 明确本项目定位为实验室共用库；GovDoc 和论文清洗都是使用场景，不是核心边界。
 - 2026-08-21 批准并冻结 `research-wiki/design/0002-composable-cleaning-pipeline.md`，确定只接收 Markdown、
   项目显式组装组件、单轮修改加最终只读复查的总体组织方式。
-- 2026-08-21 建立 `research-wiki/design/0003-first-executable-core-architecture.md` 草稿，等待评审第一版
-  Python 内存核心、精确修改协议、错误语义和测试边界。
+- 2026-08-22 批准并冻结 `research-wiki/design/0003-first-executable-core-architecture.md`，确定第一版只建设
+  Python 内存自动清洗核心：组件只提出确定可执行的精确修改，不同时建设独立检查、人工建议或真实清洗规则。
+- 2026-08-22 按 `0003` 实现第一版内存核心和测试：包括不可变数据契约、组件基类、原子修改执行器、
+  顺序流水线和最终稳定性复查；58 项测试以及 Ruff、mypy 检查均通过。
 - 2026-08-21 完成 HTML 表格清洗专题调研
   （`research-wiki/scratch/html-table-cleaning-ecosystem-research-2026-08-21.md`）：核实 Pandoc 表格
   方言能力边界、Turndown 不处理合并单元格、Docling Markdown 导出重复合并单元格内容、MinerU 全
@@ -34,9 +37,10 @@ profile 表达论文、政务文档、RAG、文档对比等不同需求。
 - 2026-08-21 仓库由 `govdoc-md-cleaner` 更名为 `mdpolish`，GitHub 远程仓库与本地目录同步改名；
   冻结的 design 记录和带日期的 scratch 笔记保留当时的旧名。
 
-当前没有清洗算法、可执行命令、运行依赖、测试套件或函数级输入输出契约。`0002` 只批准了总体组织方式；
-调研报告中的解析器、内部 IR、具体 profile 和实施路线仍是候选方案，尚未批准。
-目录存在只代表文档落点已经建立，不代表相应能力已经完成。
+当前已有只处理内存字符串的底层执行机制和函数级契约，运行时只依赖 Python 标准库。组件可以针对当前
+Markdown 快照提出精确修改，流水线负责原子应用、审计记录、失败隔离和最终稳定性复查。仓库尚无任何正式
+清洗组件，因此不能把测试专用假组件或核心执行成功理解为已经具备论文、GovDoc、表格或图片清洗能力。
+调研报告中的解析器、内部 IR、具体 profile 和真实清洗规则仍是候选方案，尚未批准。
 
 ## 服务对象与复用目标
 
@@ -51,10 +55,10 @@ GovDoc 目录、具体客户名称或某一转换器的固定输出路径。
 
 ## 面向复用的设计原则
 
-- **通用核心**：只接收 Markdown，提供结构检查、异常检测和可审计变换，不读取 PDF、图片或转换器 JSON；
+- **通用核心**：只接收 Markdown；第一版只执行确定、可审计的精确修改，不读取 PDF、图片或转换器 JSON；
 - **输入边界**：PDF/OCR/DOCX/HTML 转换和外部材料核验由使用项目或上游流程负责，不写入共用组件契约；
 - **项目 profile**：论文、GovDoc、对比、RAG、公开脱敏等规则独立组合，不互相污染默认行为；
-- **保真优先**：不确定内容默认保留或进入人工确认，不能为了格式整齐改写业务或学术内容；
+- **保真优先**：不确定内容默认保留；当前核心不猜测修改，也不承担人工确认流程；
 - **可复现**：规则、配置、输入哈希、输出和每次变更都可以追踪；
 - **可扩展**：新增项目在自身边界处理上游适配，并主要组合或补充组件和 profile，而不是复制一套清洗器。
 
@@ -82,6 +86,9 @@ mdpolish/
 ├── AGENTS.md
 ├── CLAUDE.md
 ├── README.md
+├── pyproject.toml          # Python 包、构建和开发检查的唯一配置
+├── src/mdpolish/           # 第一版内存核心；不含真实清洗组件
+├── tests/                  # 核心契约和组合行为测试
 ├── data/                   # 本地项目数据；Git 忽略，未来按项目分区
 └── research-wiki/
     ├── README.md
@@ -101,12 +108,23 @@ mdpolish/
 3. `research-wiki/README.md`，确认文档应放在哪里；
 4. 与任务直接相关的 `research-wiki/design/` 记录。
 
-下一项实质工作开始前，应评审并批准 `research-wiki/design/0003-first-executable-core-architecture.md`；
-草稿尚不授权创建源码、测试、依赖或公共接口。
+第一版核心的当前机制见 `research-wiki/explanation/first-executable-core.md`。下一项实质工作应从已经审计的问题中
+选择一个边界明确、能够唯一修复的真实清洗规则，新增 design 说明其语义、适用范围、误改风险和验收样例，
+经批准后再实现。解析器、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)
 
@@ -117,4 +135,6 @@ find research-wiki -maxdepth 2 -type f | sort
 git status --short
 ```
 
-当前没有测试命令；在真实实现和测试体系获批并落地前，不应声明测试通过。
+上述安装和三项基础验收已于 2026-08-22 在 Python 3.13.11 环境实际运行：Ruff 通过，mypy 检查 9 个源码与
+测试文件无问题，pytest 共 58 项测试通过。`requires-python` 仍以 `pyproject.toml` 声明的 Python 3.11 及以上为准；
+本次结果不等于已经在每个受支持版本上完成兼容性验证。