将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
大型网站html拆分是工程存活线，需按语义标题层级（用htmlheadertextsplitter并显式配置headers_to_split_on）、功能区域静态拆（构建时合并，禁用iframe和前端includes）、加载时机动态拆（intersectionobserver控制）三类边界实施，并严格约束单块≤500kb、校验id/锚点/语义变更。
大型网站的 HTML 文档不能靠「一个文件硬扛」，拆分不是可选项，而是工程存活线。关键不在于「能不能拆」，而在于「按什么边界拆、谁负责组装、运行时怎么加载不卡顿」。
按语义标题层级拆：用 HTMLHeaderTextSplitter 保结构不丢元数据
技术文档、帮助中心、博客文章这类内容天然带 h1–h3 层级，直接按标题切最安全。但注意：HTMLHeaderTextSplitter 默认只在遇到指定标题时才切，不会把两个 h2 之间的段落再细分——这意味着如果某节内容超长（比如 8000 字的技术实现说明），后续向量化或渲染仍可能 OOM。
- 必须显式传入
headers_to_split_on=[("h1", "title"), ("h2", "section"), ("h3", "subsection")]，漏掉任意一级，对应层级就失效 - 若需保留每个
<p></p>、<ul></ul>元素及其所属标题路径，得加return_each_element=True，否则所有子元素被合并进同一块 - 它不处理表格跨行、代码块换行等语义断裂风险，含
<table> 或 <code><pre class="brush:php;toolbar:false;"><code></code> 的页面建议换 <code>HTMLSemanticPreservingSplitter</code> <h3>按功能区域静态拆：用构建时合并 + <code>include</code> 指令解耦维护</h3> <p>页头、导航、主内容区、页脚这种强复用模块，适合物理拆成独立文件（如 <code>header.html</code>、<code>sidebar.html</code>），再通过构建工具或服务端包含组装。Webpack 的 <code>html-webpack-plugin</code> 支持 <code>template</code> + <code>html-loader</code> 引入片段；Nginx/Apache 开启 SSI 后可用 <code><!--#include file="footer.html" --></code>。</p> </pre> <ul> <li>不要用 <code><iframe></iframe>做常规模块拆分——它创建独立 DOM 和 JS 上下文，CSS 隔离、事件穿透、SEO 抓取都成问题 - 避免在浏览器端用
fetch()+innerHTML动态插入（即所谓「前端 includes」），首屏白屏、CSP 限制、SSR 不友好 - 如果用 Web Components，确保自定义元素已注册再挂载，否则
<my-header></my-header>渲染为纯文本
按加载时机动态拆：用 loading="lazy" + IntersectionObserver 控制非首屏 HTML 片段
商品列表页、长图文页的「后半截内容」没必要随首屏加载。可将 DOM 结构拆成多个 <template></template> 或隐藏 <div>，等用户滚动到视口附近再解析并插入。
<ul>
<li>
<code><img> 的 loading="lazy" 对 HTML 片段无效，必须手写 IntersectionObserver 监听
fetch(url).then(r => r.text()) 而非 innerHTML = <script></script>，后者会执行脚本且无法拦截 XSS<script></script>，需手动 eval 或 createScript 执行，但极不推荐——应改为外部 JS + data 属性通信大文件落地前必做两件事：内存预估与块大小约束
无论用哪种拆法，最终输出的单个 HTML 块不能超过 500KB（Chrome 渲染线程对单次解析的 DOM 节点数有隐式限制）。HTMLHeaderTextSplitter 本身不控制字节数，必须链式接 RecursiveCharacterTextSplitter。
- 先用
len(html_string.encode('utf-8'))粗估原始大小，超 2MB 就得前置分片 - 组合使用时，
chunk_size=500是经验值，但实际要按目标场景调：向量库 embedding 通常要求 ≤300 token，对应 HTML 字符数约 400–600 - 切完务必检查
<table> 是否被截断——<code>HTMLSemanticPreservingSplitter的keep_separator=True参数能强制把表格当原子块处理真正难的不是「怎么拆」，而是「拆完之后，构建流程是否自动校验块间 ID 冲突、锚点是否仍有效、diff 工具能否识别语义块变更而非整行漂移」。这些细节不写进 CI 脚本，拆分策略三个月后就会退化成新包袱。
