接口设计需区分富文本片段处理与远程网页解析场景，分别提供/api/extract/plain和/api/extract/from_url两个入口，统一响应结构，并强调编码探测、语义化定位、干扰节点清理及动态内容规避。
接口设计要先明确输入输出边界
HTML文本提取不是“把标签全删了就行”，接口必须区分场景：是处理用户提交的富文本片段（如评论、博客草稿），还是解析远程网页响应（含编码、重定向、JS渲染干扰）？前者可直接走 DOM 解析或轻量库，后者必须带 HTTP 客户端能力。别用一个 extract_text(html_str) 硬扛所有情况。
推荐拆成两个入口：
-
/api/extract/plain：只接受已解码的 UTF-8 HTML 字符串，不做网络请求，返回纯文本。适合后端服务间调用或清洗本地文件 -
/api/extract/from_url：接受 URL + 可选超时/UA/代理参数，内部做requests.get()+ 编码自动探测 + 干扰节点清理 + 主体定位。适合爬虫中台或 CMS 预览功能
这两个路径的响应结构应一致：{"text": "提取结果", "charset": "utf-8", "detected_selector": "main"}——把编码和实际用到的选择器也吐出来，方便调试时对齐预期。
Python后端实现时别跳过编码探测这步
90% 的中文乱码不是因为没设 encoding="utf-8"，而是因为服务器返回的 Content-Type 声明了 charset=gbk，但 requests 默认按 ISO-8859-1 解码，再强转 utf-8 就全废了。
正确做法是：
- 拿到
response后立刻执行response.encoding = response.apparent_encoding，而不是硬写死"utf-8" - 若
response.headers.get("content-type")里有charset=，优先取它；没有再 fallback 到apparent_encoding - 本地读文件时，显式传
encoding，别依赖open("x.html")的系统默认——Windows 默认是 cp1252，Linux 是 utf-8，不一致就炸
主体内容定位不能只靠 get_text()
直接对整个 soup 调用 get_text() 会把导航栏、页脚、广告文案全吸进来。必须先缩小范围。
优先级顺序是：
将 Markdown 文章转换为微信公众号兼容的纯 HTML 格式。当用户要求"转成微信格式"、"生成公众号文章 HTML"、"排版到微信草稿箱"、"微信粘贴格式"时触发。输出带内联样式的纯 HTML，微信编辑器可直接渲染，无需额外适配。支持标题、段落、列表、粗体、行内代码、表格、引用块、代码块、配图的完整转换。
- 查
soup.find("main")或soup.find("article")——语义化标签最可靠 - 没语义标签就查 class 名：用
soup.find("div", class_=re.compile(r"content|post|entry|body")) - 结构固定的站点（如教育平台的
div.dnevnik-lesson__task），直接写死 CSS 选择器soup.select_one("div.dnevnik-lesson__task")
找到容器后，再调用 .get_text(separator="\n", strip=True)。注意 separator="\n" 是关键——它让 <p>段落一</p>
<p>段落二</p> 输出为两行，而不是连在一起的“段落一段落二”。
干扰节点清理必须在提取前完成
即使你精准定位到 <div class="content">，里面还可能混着 <code><script></script>、<style></style>、<nav></nav>、<footer></footer> 这些东西。它们的 get_text() 不为空，会污染结果。
清理代码要写在定位之后、提取之前：
for tag in soup(["script", "style", "nav", "footer", "header", "aside"]):
tag.decompose()
用 decompose()，别用 extract()——前者彻底销毁节点对象，内存友好；后者只是移出 DOM 树，对象还在内存里占着位置。
图标类空标签（如 <i class="icon-download"></i>）不用管，它们没文本内容，get_text() 自动忽略。
真正麻烦的是那些 JS 渲染后才出现的正文——比如 React 单页应用的 div#root 里初始只有空 div，真实内容靠 fetch 注入。这种场景，服务端 HTML 解析器无能为力，得切到 Puppeteer 或 Playwright。别试图用 BeautifulSoup 硬扛动态内容，那不是它的设计目标。
