…` 单行压缩 → Markdown 管道表格 |
-| 60 | `strip_stray_html` | 散落标签 | `
` |
-| 70 | `rstrip_lines` | 行尾空白 | MinerU 每行行尾的双空格硬换行 |
-| 80 | `collapse_blank_lines` | 空行折叠 | 连续空行 → 1 行；裁掉文首文末 |
+当前没有清洗算法、可执行命令、运行依赖、测试套件或已批准的输入输出契约。
+目录存在只代表文档落点已经建立，不代表相应能力已经完成。
-### 防误伤设计（来自真实数据踩坑）
+## 项目边界
-- **protect 正则**：`投标人：（公章）`、`法定代表人签名:`、`日期: 年 月 日`、
- `致：xxx`、声明函结尾句——标书里逐章重复，**是正文模板不是页眉**，默认保护。
-- **内容形态豁免**：编号条款 `（1）…`、`1、…`、`一、…`、列表/表格行、
- `乙方：xxx` 字段行——平行结构天然重复，引擎侧直接不参与页眉判定。
-- **burst 检测**：同一短行连续刷屏 ≥5 次（间隔 ≤2 行）判为 OCR 重复崩坏，
- 直接删除（003-10 案例出现"审计程序"连续 1359 行）。
+- 研究对象是 MinerU、OCR 等 PDF→Markdown 管线产生的噪音与清洗方法；
+- `/home/lihaoze/gov_test_data` 中的真实材料属于外部只读数据，不复制、不修改、不提交；
+- 任何清洗语义、规则格式、评估指标、代码目录或运行依赖，都应先形成设计记录并获得确认；
+- 研究结果只有经过独立评审后，才能进入其他产品或生产仓库。
-## 安装
+## 目录结构
-```bash
-pip install -e . # 或直接 python -m cleaner.cli（仅需 PyYAML）
-```
-
-## 使用
-
-```bash
-# 单文件：清洗 + 打印统计
-md-clean single input.md -o output.md --diff
-
-# 批量：递归清洗目录下所有 .md，输出到平行目录 + JSON 报告
-md-clean batch /path/to/uploads -o /path/to/uploads_cleaned \
- --pattern "*.md" --report report.json
-
-# 用自定义规则集（复制 default.yaml 改参数即可）
-md-clean batch uploads/ --rules rules/strict.yaml
-```
-
-`--diff` 输出 unified diff，`report.json` 记录每个文件每条规则的命中数，
-清洗过程完全可审计、可回滚（重跑即得原结果的对照）。
-
-## 项目结构
-
-```
+```text
govdoc-md-cleaner/
-├── cleaner/
-│ ├── cleaner.py # 引擎：按序应用规则，输出 CleanResult(text, stats)
-│ ├── rules.py # 规则实现 + REGISTRY + YAML 加载
-│ └── cli.py # single / batch 两个子命令
-├── rules/
-│ └── default.yaml # 默认规则集（顺序、开关、参数、protect 列表）
-├── tests/
-│ └── test_rules.py # 每条规则的最小样例 + 防误伤回归
-└── docs/
- └── RULES.md # 规则编写指南（新增规则的方法）
+├── AGENTS.md
+├── CLAUDE.md
+├── README.md
+└── research-wiki/
+ ├── README.md
+ ├── design/ # 方案选择与冻结决策
+ ├── explanation/ # 当前有效机制及原因
+ ├── reference/ # 需要准确查询的稳定事实
+ ├── guides/ # 已实际验证的操作步骤
+ └── scratch/ # 调研笔记和未收敛草稿
```
-## 新增一条规则
+## 开始工作
-1. `cleaner/rules.py`：实现 `_your_rule(text, params, stats) -> text`，注册进 `REGISTRY`；
-2. `rules/default.yaml`：追加 `- name: your_rule / order: / params:`；
-3. `tests/test_rules.py`：加一个真实数据浓缩出的最小样例。
+进入仓库后依次阅读：
-原则：**规则只删噪音不删正文**；拿不准的形态默认保留，靠 protect/exempt 收紧。
+1. 本文件，确认当前阶段；
+2. `AGENTS.md` 或 `CLAUDE.md`，确认协作与安全边界；
+3. `research-wiki/README.md`，确认文档应放在哪里；
+4. 与任务直接相关的 `research-wiki/design/` 记录。
-## 测试
+下一项实质工作开始前，应新增下一编号的 design，明确问题、备选方案、输入范围、验收方法和非目标。
+
+## 当前可用检查
```bash
-python -m unittest discover tests -v
+# 两份 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
```
-## License
-
-MIT
+当前没有测试命令；在真实实现和测试体系获批并落地前，不应声明测试通过。
diff --git a/cleaner/__init__.py b/cleaner/__init__.py
deleted file mode 100644
index 2785bf4..0000000
--- a/cleaner/__init__.py
+++ /dev/null
@@ -1,11 +0,0 @@
-"""govdoc-md-cleaner: 政务文档 Markdown 清洗工具包。
-
-针对 PDF→Markdown 转换产物（MinerU / OCR 管线输出）的常见脏数据，
-提供基于 YAML 规则的、可复现、可审计的清洗能力。
-"""
-
-from cleaner.cleaner import MarkdownCleaner, CleanResult, load_rules
-from cleaner.cli import main
-
-__version__ = "0.1.0"
-__all__ = ["MarkdownCleaner", "CleanResult", "load_rules", "main"]
diff --git a/cleaner/cleaner.py b/cleaner/cleaner.py
deleted file mode 100644
index 7764ed9..0000000
--- a/cleaner/cleaner.py
+++ /dev/null
@@ -1,56 +0,0 @@
-"""清洗引擎：按规则顺序应用，输出清洗后文本 + 统计报告。"""
-
-from __future__ import annotations
-
-import difflib
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Dict, List, Optional
-
-from cleaner.rules import REGISTRY, Rule, load_rules
-
-
-@dataclass
-class CleanResult:
- """一次清洗的结果：产物 + 可审计的统计。"""
-
- text: str
- stats: Dict[str, int] = field(default_factory=dict)
- rules_applied: List[str] = field(default_factory=list)
-
- @property
- def total_hits(self) -> int:
- return sum(v for k, v in self.stats.items() if k != "collapsed_blanks")
-
-
-class MarkdownCleaner:
- def __init__(self, rules: Optional[List[Rule]] = None, rules_path: Optional[Path] = None):
- self.rules = rules if rules is not None else load_rules(rules_path)
-
- def clean_text(self, text: str) -> CleanResult:
- stats: Dict[str, int] = {}
- applied: List[str] = []
- for rule in self.rules:
- if not rule.enabled:
- continue
- func = REGISTRY[rule.name]
- text = func(text, rule.params, stats)
- applied.append(rule.name)
- return CleanResult(text=text, stats=stats, rules_applied=applied)
-
- def clean_file(self, src: Path, dst: Optional[Path] = None) -> CleanResult:
- raw = Path(src).read_text(encoding="utf-8")
- result = self.clean_text(raw)
- if dst is not None:
- Path(dst).parent.mkdir(parents=True, exist_ok=True)
- Path(dst).write_text(result.text, encoding="utf-8")
- return result
-
- @staticmethod
- def diff(before: str, after: str, context: int = 1) -> str:
- return "\n".join(
- difflib.unified_diff(
- before.splitlines(), after.splitlines(),
- fromfile="before", tofile="after", lineterm="", n=context,
- )
- )
diff --git a/cleaner/cli.py b/cleaner/cli.py
deleted file mode 100644
index d656411..0000000
--- a/cleaner/cli.py
+++ /dev/null
@@ -1,89 +0,0 @@
-"""命令行入口。
-
-用法:
- md-clean single [-o output.md] [--diff] [--rules rules.yaml]
- md-clean batch [-o outdir] [--pattern "*.md"] [--report report.json]
-"""
-
-from __future__ import annotations
-
-import argparse
-import json
-import sys
-from pathlib import Path
-from typing import List, Optional
-
-from cleaner.cleaner import MarkdownCleaner
-from cleaner.rules import load_rules
-
-
-def _build(path: Optional[Path]) -> MarkdownCleaner:
- return MarkdownCleaner(rules=load_rules(path))
-
-
-def cmd_single(args: argparse.Namespace) -> int:
- cleaner = _build(args.rules)
- src = Path(args.input)
- raw = src.read_text(encoding="utf-8")
- result = cleaner.clean_text(raw)
- if args.output:
- Path(args.output).parent.mkdir(parents=True, exist_ok=True)
- Path(args.output).write_text(result.text, encoding="utf-8")
- print(f"已写入 {args.output}")
- if args.diff:
- print(MarkdownCleaner.diff(raw, result.text))
- print(json.dumps(result.stats, ensure_ascii=False, indent=2))
- return 0
-
-
-def cmd_batch(args: argparse.Namespace) -> int:
- cleaner = _build(args.rules)
- src_dir = Path(args.directory)
- files = sorted(p for p in src_dir.rglob(args.pattern) if p.is_file())
- if not files:
- print(f"在 {src_dir} 下未找到匹配 {args.pattern} 的文件", file=sys.stderr)
- return 1
- out_dir = Path(args.output) if args.output else src_dir.parent / (src_dir.name + "_cleaned")
- report = []
- for f in files:
- rel = f.relative_to(src_dir)
- dst = out_dir / rel
- result = cleaner.clean_file(f, dst)
- report.append({"file": str(rel), "stats": result.stats})
- hits = result.total_hits
- print(f"[ok] {rel} 命中 {hits} 处")
- if args.report:
- Path(args.report).parent.mkdir(parents=True, exist_ok=True)
- Path(args.report).write_text(
- json.dumps({"files": report}, ensure_ascii=False, indent=2), encoding="utf-8"
- )
- print(f"报告已写入 {args.report}")
- print(f"共清洗 {len(files)} 个文件 → {out_dir}")
- return 0
-
-
-def main(argv: Optional[List[str]] = None) -> int:
- parser = argparse.ArgumentParser(prog="md-clean", description="政务文档 Markdown 清洗工具")
- sub = parser.add_subparsers(dest="command", required=True)
-
- p1 = sub.add_parser("single", help="清洗单个文件")
- p1.add_argument("input", help="输入 .md 文件")
- p1.add_argument("-o", "--output", help="输出路径（缺省打印统计不写文件）")
- p1.add_argument("--diff", action="store_true", help="打印 unified diff")
- p1.add_argument("--rules", type=Path, help="规则 YAML 路径")
-
- p2 = sub.add_parser("batch", help="批量清洗目录（递归）")
- p2.add_argument("directory", help="输入目录")
- p2.add_argument("-o", "--output", help="输出目录（缺省 _cleaned）")
- p2.add_argument("--pattern", default="*.md", help="文件 glob（默认 *.md）")
- p2.add_argument("--report", help="清洗报告 JSON 输出路径")
- p2.add_argument("--rules", type=Path, help="规则 YAML 路径")
-
- args = parser.parse_args(argv)
- if args.command == "single":
- return cmd_single(args)
- return cmd_batch(args)
-
-
-if __name__ == "__main__":
- sys.exit(main())
diff --git a/cleaner/rules.py b/cleaner/rules.py
deleted file mode 100644
index 5e0a25a..0000000
--- a/cleaner/rules.py
+++ /dev/null
@@ -1,281 +0,0 @@
-"""规则模型：一条清洗规则 = 名称 + 开关 + 参数 + 应用顺序。
-
-规则用 YAML 声明（rules/*.yaml），引擎按 order 依次应用，
-这样清洗过程可复现、可 diff、可回滚。
-"""
-
-from __future__ import annotations
-
-import re
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Any, Callable, Dict, List, Optional
-
-import yaml
-
-
-@dataclass
-class Rule:
- """一条清洗规则。
-
- name: 唯一标识（报告里引用）
- order: 应用顺序，小的先执行
- enabled: 开关，方便对某个用例单独关掉
- params: 传给处理函数的额外参数
- """
-
- name: str
- order: int = 100
- enabled: bool = True
- params: Dict[str, Any] = field(default_factory=dict)
-
- @staticmethod
- def from_dict(d: Dict[str, Any]) -> "Rule":
- return Rule(
- name=d["name"],
- order=int(d.get("order", 100)),
- enabled=bool(d.get("enabled", True)),
- params=dict(d.get("params") or {}),
- )
-
-
-# ---------------------------------------------------------------------------
-# 每条规则的具体实现。函数签名统一为 (text, params, stats) -> text。
-# stats 是 {rule_name: 删改行数}，用于生成清洗报告。
-# ---------------------------------------------------------------------------
-
-RuleFunc = Callable[[str, Dict[str, Any], Dict[str, int]], str]
-
-# 页码类：第X页 共Y页 / 第X页共Y页 / Page x of y / - 3 - 等
-_RE_PAGE_CN = re.compile(
- r"^[ \t]*第\s*[0-9０-９]+\s*页\s*(?:[,，/]?\s*共\s*[0-9０-９]+\s*页)?[ \t]*$"
-)
-_RE_PAGE_EN = re.compile(
- r"^[ \t]*(?:[-–—]?\s*Page\s+\d+(?:\s+of\s+\d+)?\s*[-–—]?"
- r"|[-–—]\s*\d{1,4}\s*[-–—]"
- r"|\d+\s*/\s*\d+)[ \t]*$",
- re.IGNORECASE,
-)
-# 纯页码数字行（单独一行只有 1-4 位数字，且不是标题编号场景）
-_RE_PAGE_BARE = re.compile(r"^[ \t]*\d{1,4}[ \t]*$")
-
-
-def _strip_page_lines(text: str, params: Dict[str, Any], stats: Dict[str, int]) -> str:
- keep_bare_numbers = bool(params.get("keep_bare_numbers", True))
- out, n = [], 0
- for line in text.splitlines():
- if _RE_PAGE_CN.match(line) or _RE_PAGE_EN.match(line):
- n += 1
- continue
- if not keep_bare_numbers and _RE_PAGE_BARE.match(line):
- n += 1
- continue
- out.append(line)
- stats["page_lines"] = stats.get("page_lines", 0) + n
- return "\n".join(out)
-
-
-# 页眉/页脚：同一短行在全篇重复出现 >= N 次（默认 3），视为页眉页脚删除。
-# 两道保险避免误伤正文：
-# 1. protect 正则 —— 标书里逐章重复的模板行（签章/日期/声明结尾）
-# 2. 内容形态行直接豁免 —— 编号条款 "(1)…"/"1、…"/"一、…"/列表/表格行
-# 在平行结构的标书里天然重复，但它们是正文不是页眉。
-_RE_CONTENT_LIKE = re.compile(
- r"^[\d０-９(（\[【\-–—*•·①-⑳一二三四五六七八九十百第章节条款、,.。:：|]"
- r"|[一-鿿]{1,6}[：:]\s*\S" # "乙方：xxx" / "地址：xxx" 这类字段行
- r"|^[一-鿿A-Za-z]{1,6}[：:]\s*$" # "乙方：" / "注：" 字段标签行
-)
-
-
-def _strip_repeated_short_lines(
- text: str, params: Dict[str, Any], stats: Dict[str, int]
-) -> str:
- threshold = int(params.get("threshold", 3))
- max_len = int(params.get("max_len", 40))
- # 同一短行在文中连续出现 >= burst_limit 次（间隔 <= burst_gap 行）视为
- # OCR 重复崩坏（如 003-10 案例"审计程序"连续刷屏 1359 次），无论阈值直接删。
- burst_limit = int(params.get("burst_limit", 5))
- burst_gap = int(params.get("burst_gap", 2))
- protect = [re.compile(p) for p in params.get("protect", [])]
- lines = text.splitlines()
- counts: Dict[str, int] = {}
- positions: Dict[str, List[int]] = {}
- for i, line in enumerate(lines):
- s = line.strip()
- if (
- 0 < len(s) <= max_len
- and not s.startswith("#")
- and not _RE_CONTENT_LIKE.match(s)
- and "![" not in s
- ):
- counts[s] = counts.get(s, 0) + 1
- positions.setdefault(s, []).append(i)
- repeated = {
- s
- for s, c in counts.items()
- if c >= threshold and not any(rx.search(s) for rx in protect)
- }
- # OCR 崩坏连续段：即使该行被 protect/内容豁免，连续刷屏也删
- for s, pos in positions.items():
- best_run = run = 1
- for a, b in zip(pos, pos[1:]):
- run = run + 1 if b - a <= burst_gap else 1
- best_run = max(best_run, run)
- if best_run >= burst_limit:
- repeated.add(s)
- if not repeated:
- return text
- out, n = [], 0
- for line in lines:
- if line.strip() in repeated:
- n += 1
- continue
- out.append(line)
- stats["header_footer_lines"] = stats.get("header_footer_lines", 0) + n
- return "\n".join(out)
-
-
-# 目录点线：标题文字 ………… 12 / ······ 3 之类（… U+2026 也算；# 前缀可选）
-_RE_TOC_DOTS = re.compile(
- r"^(#{1,6}\s+)?.*?[ \t]*[\.。·•‧…]{6,}[ \t]*[\d０-９]*[ \t]*$"
-)
-
-
-def _strip_toc_dots(text: str, params: Dict[str, Any], stats: Dict[str, int]) -> str:
- out, n = [], 0
- for line in text.splitlines():
- m = _RE_TOC_DOTS.match(line)
- if m:
- # 去掉点线和页码，保留标题文字；纯点线+页码的目录行整行删
- title = re.sub(r"[ \t]*[\.。·•‧…]{6,}[ \t]*[\d０-９]*[ \t]*$", "", line).rstrip()
- if title.strip() and not re.fullmatch(r"[\.。·•‧…\d０-９\s]+", title):
- out.append(title)
- n += 1
- continue
- out.append(line)
- stats["toc_dot_lines"] = stats.get("toc_dot_lines", 0) + n
- return "\n".join(out)
-
-
-# 图片引用： —— 图片目录不在交付物里，引用是死链
-_RE_IMAGE = re.compile(r"[ \t]*!\[[^\]]*\]\([^)]*\)[ \t]*")
-
-
-def _drop_images(text: str, params: Dict[str, Any], stats: Dict[str, int]) -> str:
- placeholder = params.get("placeholder") # None=整行删除；否则替换为占位文本
- out, n = [], 0
- for line in text.splitlines():
- if _RE_IMAGE.fullmatch(line):
- n += 1
- if placeholder:
- out.append(str(placeholder))
- continue
- new = _RE_IMAGE.sub("", line)
- if new != line:
- n += 1
- line = new.rstrip()
- out.append(line)
- stats["image_refs"] = stats.get("image_refs", 0) + n
- return "\n".join(out)
-
-
-# HTML 表格规范化： 压缩为合法 Markdown 管道表格
-_RE_TABLE = re.compile(r"]*>(.*?) |