From 688933c228bbb297443b0e75107b438002d4ba79 Mon Sep 17 00:00:00 2001
From: lanyuanxiaoyao <lanyuanxiaoyao@gmail.com>
Date: Tue, 10 Mar 2026 11:08:51 +0800
Subject: [PATCH] =?UTF-8?q?fix:=20=E7=A7=BB=E9=99=A4=20cleaner.py=20?=
 =?UTF-8?q?=E9=A1=B6=E5=B1=82=E5=AF=BC=E5=85=A5=EF=BC=8C=E5=AE=8C=E5=96=84?=
 =?UTF-8?q?=20README=20=E6=B5=8B=E8=AF=95=E6=8C=87=E5=BC=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 移除 cleaner.py 中 beautifulsoup4 的顶层导入，改为完全依赖函数内动态导入
- 新增 README 快速开始章节，提供验证环境和基础测试命令
- 完善测试前置依赖说明，明确仅需 chardet 即可运行基础测试
- 更新所有测试命令，移除不必要的 --with beautifulsoup4
---
 README.md                       | 36 ++++++++++++++++++++++++++++++++-
 scripts/readers/html/cleaner.py |  2 --
 2 files changed, 35 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index c3ca897..eb0f0d0 100644
--- a/README.md
+++ b/README.md
@@ -70,8 +70,36 @@ DEPENDENCIES = {
 
 `--advice` 参数根据文件扩展名识别类型，检测当前平台，从 `config.DEPENDENCIES` 读取对应配置，生成 `uv run --with` 和 `pip install` 命令。
 
+## 快速开始
+
+### 验证环境
+
+首先验证项目可以正常运行：
+
+```bash
+# 测试 --advice 功能（仅需 chardet）
+uv run --with chardet python scripts/lyxy_document_reader.py test.pdf --advice
+```
+
+### 运行基础测试
+
+```bash
+# 运行 CLI 测试（验证项目基本功能）
+uv run \
+  --with pytest \
+  --with chardet \
+  pytest tests/test_cli/test_main.py::TestCLIAdviceOption -v
+```
+
 ## 开发指南
 
+### 测试前置依赖说明
+
+由于 `HtmlReader` 模块在导入时会加载 `cleaner.py`，但 `cleaner.py` 中的第三方库已改为动态导入，因此仅需基础依赖：
+- **chardet**：编码检测
+
+`beautifulsoup4` 仅在实际使用 HTML 清理功能时才需要，模块导入时不依赖。
+
 ### 如何添加新的 Reader
 
 1. 在 `scripts/readers/` 下创建新目录
@@ -177,12 +205,18 @@ uv run \
 
 #### 运行特定测试文件或方法
 ```bash
-# 运行特定测试文件
+# 运行特定测试文件（CLI 测试仅需 chardet）
 uv run \
   --with pytest \
   --with chardet \
   pytest tests/test_cli/test_main.py
 
+# 仅运行 --advice 相关测试（不需要额外依赖）
+uv run \
+  --with pytest \
+  --with chardet \
+  pytest tests/test_cli/test_main.py::TestCLIAdviceOption
+
 # 运行特定测试类或方法
 uv run \
   --with pytest \
diff --git a/scripts/readers/html/cleaner.py b/scripts/readers/html/cleaner.py
index 7ba0d87..2c35989 100644
--- a/scripts/readers/html/cleaner.py
+++ b/scripts/readers/html/cleaner.py
@@ -3,8 +3,6 @@
 import re
 from typing import Optional, Tuple
 
-from bs4 import BeautifulSoup
-
 
 def clean_html_content(html_content: str) -> Tuple[Optional[str], Optional[str]]:
     """