md-chunk-lite

md-chunk-lite

免费工具，可按标题将 Markdown 拆分为多个块。每个块都包含其标题路径和来源行号。 需要将 PDF、Word 或网页文件转换成块（PDF 还会附带页码），或处理整个文件夹？付费工具 doc2md 可以做到：在 Gumroad 上获取 doc2md

适用于 AI 搜索（RAG）、嵌入和文档机器人。它使用普通代码，而非 AI，因此同一文件始终会生成相同的块。可在自己的电脑上运行。采用 MIT 许可证。适用于 Windows、Mac 和 Linux，需要 Python 3.10 或更新版本。

安装

pip install md-chunk-lite

也可以使用 pipx，它会将程序安装在独立环境中：

pipx install md-chunk-lite

想直接获取 GitHub 上的最新代码？

pip install git+https://github.com/tidybytetools/md-chunk-lite

使用方法

md-chunk-lite guide.md                     # writes guide.chunks.jsonl
md-chunk-lite docs/*.md -o all.jsonl       # many files into one file
md-chunk-lite guide.md -o -                # print the chunks on screen
md-chunk-lite guide.md --max-chars 800     # smaller chunks
md-chunk-lite guide.md --outline           # just show the headings
cat guide.md | md-chunk-lite -             # read from stdin

运行示例：

Saved: guide.chunks.jsonl  (7 chunks, biggest 151 chars)

.jsonl 文件的每一行都是一个块：

{
  "id": "guide.md#3",
  "source": "guide.md",
  "index": 3,
  "heading_path": ["Garden Guide", "Planting", "Tomatoes"],
  "heading_level": 3,
  "anchor": "tomatoes",
  "start_line": 16,
  "end_line": 24,
  "part": 1,
  "parts": 1,
  "chars": 151,
  "text": "### Tomatoes\n\nPlant tomatoes after the last frost. Give them sun.\n\n```python\n..."
}

• heading_path：此块上方的所有标题，从顶层标题开始。
• anchor：GitHub 为该标题生成的 #link，可直接链接到该标题。
• start_line 和 end_line：块在文件中的位置（第一行为第 1 行）。
• part 和 parts：较大的章节会拆分成多个部分。part 2, parts 3 表示第 3 部分中的第 2 部分。
• chars：text 的长度。

--outline 会打印标题：

Garden Guide  [line 8, #garden-guide, 14 chars]
  Tools  [line 10, #tools, 47 chars]
  Planting  [line 14, #planting, 11 chars]
    Tomatoes  [line 16, #tomatoes, 151 chars]

在终端中运行时，程序结束前会显示一行简短信息，介绍付费工具 doc2md。使用 --quiet 可关闭此信息；通过管道传输或重定向输出时则不会显示。

它如何拆分

1. 每个标题都会开始一个新章节。一个分块绝不会混合两个章节，因此每个分块都有清晰的标题路径。
2. 较短的章节会成为一个分块。其文本直接从你的文件中复制，因此行号保持一致。
3. 较长的章节会在空行处分割。只要能放得下，列表、表格和代码块都会保持完整。
4. 太大的表格会按行拆分，并在每个部分中再次加入表头行。
5. 太大的代码块会按行拆分，并为每个部分重新添加自己的 ``` 围栏，同时保留相同的语言。
6. 超长行会先在句末截断；必要时再在空格处截断。
7. 没有正文（下面只有更多标题）的标题不会单独生成分块，但仍会显示在其下方分块的 heading_path 中。

它可以识别 # 标题和下划线标题（=== 和 ---）。它会跳过代码块和 YAML front matter（最顶部的 --- 块）中的标题。

选项：

• --max-chars N：分块的最大字符数（默认 1500，最小 200）。英文中约 4 个字符相当于 1 个 token。
• --overlap-chars N：拆分章节时，每个部分的开头最多包含前一部分末尾的 N 个字符（默认 0）。代码块或表格内部不会添加重叠内容，不同章节之间也不会添加。
• --prefix-path：在每个分块的文本开头加入标题路径，例如 Garden Guide > Planting > Tomatoes。这通常有助于搜索。该路径计入 --max-chars。
• --json：为脚本和 AI Agent 打印一个 JSON 对象，而不是保存文件。

已知限制

• 大小按字符计算，而不是按 token 计算。 它不会加载分词器。
• 仅支持 Markdown 和纯文本。 不会读取 PDF、Word 和 HTML。付费版 doc2md 会将这些格式转换为分块（PDF 还会附带页码）。
• 不支持文件夹。 请传入文件（你的 shell 可以展开 docs/*.md）。付费版 doc2md 会遍历整个文件夹。
• 不是完整的 Markdown 解析器。 HTML 块中的标题，或跨越多行的下划线标题，可能会处理错误。
• 重叠内容使用前一部分中的完整单词，因此可能会比你指定的长度略短。

Lite 版与付费版

	md-chunk-lite（免费）	doc2md（付费）
可读取	Markdown 和文本文件	PDF、Word（.docx）和 HTML
分块包含标题路径	是	是
行号和锚点	是	否（PDF 改为提供页码）
每个分块的粗略 token 数量	否	是
支持整个文件夹及其子文件夹	否	是
MCP 服务	是	否

其他优质免费工具

选择适合你的工具。如果你已经在使用 LangChain，它的 MarkdownHeaderTextSplitter 也可以按标题拆分。Chonkie 和 semchunk 可以按 token 数量拆分任何文本。md-chunk-lite 体积小，采用 MIT 许可，不含 AI 或分词器组件，可提供行号和锚点，并内置 MCP 服务。

在 Claude Desktop 或 Cursor 中使用（MCP）

它内置了一个小巧的免费 MCP 服务。该服务需要 uv。

手动运行以检查它是否能启动（它会静静等待应用与其通信）：

uvx md-chunk-lite mcp

Claude Desktop（claude_desktop_config.json）或 Cursor（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "md-chunk-lite": {
      "command": "uvx",
      "args": ["md-chunk-lite", "mcp"]
    }
  }
}

uvx --from md-chunk-lite md-chunk-lite-mcp 会启动相同的服务。

工具（每个工具都接受文件 path 或 Markdown text）：

工具	功能	会修改文件吗？
chunk_markdown	将内容拆分为分块。每次返回 100 个；如需更多，请使用 start。	否
outline_markdown	列出标题及其行号和锚点。	否
get_section	按标题或锚点获取一个章节。	否
save_chunks_jsonl	将分块保存到 .jsonl 文件。	会写入一个 .jsonl 文件（如果文件已存在，则会替换）

这些工具都不会使用互联网。

在 GitHub Actions 中使用

每次推送时对文档进行分块，让 AI 搜索或文档机器人始终获取最新分块。如果某个章节太大，无法放入一个分块，它还会直接在拉取请求对应的行上发出警告。

name: Docs chunks
on: [push, pull_request]
permissions:
  contents: read
jobs:
  chunks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: tidybytetools/md-chunk-lite@v1
        with:
          files: docs/**/*.md
          max-chars: "1500"
          artifact-name: docs-chunks   # download the JSONL from the run page

想让过大的章节导致检查失败，而不只是发出警告？添加 fail-on-split: "true"。

它会使用你选择的同一标签运行代码，且只依赖 Python 标准库。无需 API 密钥或账户，也不会将任何内容发送到 GitHub 之外。它支持 Linux、Windows 和 Mac 运行器。

输入

输入	默认值	作用
files	**/*.md	要读取的文件。Glob 模式，每行一个，或用逗号分隔。
exclude	node_modules/**、**/node_modules/**、vendor/**	要跳过的模式。
max-chars	1500	单个分块的最大字符数（至少为 200）。
overlap-chars	0	将前一部分的多少个字符重复到下一部分的开头。
prefix-path	false	在每个分块的文本开头添加其标题路径。
output	md-chunks.jsonl	分块的保存位置。
fail-on-split	false	当某个章节太大，无法放入一个分块时使检查失败。
fail-if-no-files	true	没有文件匹配时使检查失败。
artifact-name	（空）	如果设置，则以此名称将 JSONL 上传为构建产物。
python-version	（空）	要设置的 Python 版本。留空则使用运行器上的 Python（3.10 或更高版本）。

输出

输出	含义
files	已读取的文件数。
chunks	已生成的分块数。
biggest	最大分块的字符数。
split-sections	被拆分的过大章节数。
output	JSONL 文件的路径。

运行页面还会显示一份简短报告：每个文件的分块数，以及所有被拆分章节的列表和对应行号。

面向 AI Agent

• 适用场景： 你有一个 Markdown 或文本文件（文档、笔记、README），需要生成带标题路径和行号的分块，以用于搜索、嵌入或引用来源。使用 outline_markdown 和 get_section 只读取长文件中的某一部分。
• 不适用场景： 文件是 PDF、Word 或 HTML（请先转换），或者你需要精确到 token 的大小。
• 输入： 文件路径或 Markdown 文本，以及 max_chars（默认值为 1500）、overlap_chars（默认值为 0）和 prefix_path（默认值为 false）。
• 输出： 包含 id、source、index、heading_path、heading_level、anchor、start_line、end_line、part、parts、chars、text 的分块。
• CLI 成功时退出代码为 0，出错时为 1（错误消息输出到 stderr；使用 --json 时输出 {"ok": false, "error": ...}）。另请参阅 llms.txt。

Python

from md_chunk_lite import chunk_file, chunk_markdown, outline, get_section

chunks = chunk_file("guide.md", max_chars=1000)
for c in chunks:
    print(c["heading_path"], c["start_line"], c["end_line"])

install = get_section(open("README.md").read(), heading="Install")

分块器文件仅使用 Python 标准库。使用 pip 安装也会为 MCP 服务安装 mcp 包。

测试

pip install "mcp>=1.10,<2"
python3 -m unittest discover -s tests

未安装 mcp 时，将跳过 MCP 测试。

许可证

MIT。请参阅 LICENSE。