当前位置：首页 > news >正文

Docmancer：本地化文档压缩工具，为AI编码助手节省60%-90%上下文Token

news 2026/5/9 6:51:21

1. 项目概述：为AI编码智能体“瘦身”文档上下文

如果你和我一样，日常工作中重度依赖Claude Code、Cursor、Codex这类AI编码助手，那你肯定也遇到过这个让人头疼的问题：为了让AI理解一个框架或库的用法，你不得不把大段的官方文档塞进上下文窗口。结果就是，宝贵的Token预算被冗长的文档占去了一大半，真正留给AI写代码、调试和思考的空间所剩无几。我实测过，在一些复杂的项目中，原始文档内容能轻松吃掉30%到40%的上下文，这直接导致了对话轮次减少、AI“记忆力”变差，最终影响产出质量。

Docmancer就是为了解决这个痛点而生的。它不是一个云端服务，而是一个本地的、开源的命令行工具。它的核心思想非常直接：把文档“压缩”后再喂给AI。它通过爬取或读取你指定的文档（无论是线上URL、GitHub仓库还是本地文件夹），将其智能地切分成有意义的“章节”，然后用轻量级的SQLite FTS5全文搜索引擎建立索引。当你的AI助手需要查询某个功能时，Docmancer不再返回整篇文档，而是精准地检索出最相关的几个章节片段，打包成一个紧凑的“上下文包”返回。这个包不仅包含核心信息，还保留了来源标注，更重要的是，它通常能将文档部分的Token开销降低60%到90%。

想象一下，原本需要4800个Token来承载的文档，现在可能只需要900个Token。省下来的近4000个Token，足够让AI多进行好几轮复杂的代码推理和迭代。Docmancer的目标就是延长AI的“有效续航里程”，让它把算力真正花在刀刃上——也就是写代码本身。

2. 核心设计思路与架构解析

2.1 为什么选择本地化与SQLite FTS5？

市面上已经有很多基于向量数据库（Vector DB）的RAG（检索增强生成）方案，那Docmancer为什么反其道而行之，选择了看起来“古老”的SQLite FTS5？这背后是基于几个非常务实的考量，也是我在众多技术选型中最终认同它的原因。

首要原因是零依赖与极致轻量。AI开发工作流本身就已经够复杂了，你不想再引入一个需要独立部署、维护的向量数据库服务（比如Qdrant、Pinecone）。SQLite是一个单文件数据库，无需服务进程，docmancer setup命令瞬间就能在~/.docmancer/目录下初始化好一切。这意味着你可以毫无负担地在任何开发机、甚至是配置受限的环境中使用它。对于追求“开箱即用”的开发者工具来说，这种简洁性具有巨大的吸引力。

其次是速度与精准度。对于文档检索这个特定场景，关键词匹配（全文搜索）的效率和确定性往往比语义搜索（向量检索）更高。当你问“How do I use fixtures?”，你期望AI看到的是Pytest文档中标题明确包含“fixture”的章节。FTS5能毫秒级地完成这种精确匹配，而向量检索可能会返回一些语义相关但并非直接讲fixture用法的段落，需要额外的后处理来筛选。Docmancer的定位是“文档压缩器”，而非通用的知识问答系统，因此FTS5的精准和快速是更合适的选择。

最后是可控性与透明度。所有数据都在本地，索引过程完全离线，没有API调用，也没有数据泄露的风险。生成的索引和提取的原始Markdown文件都存储在本地，你可以随时用docmancer inspect查看状态，或用sqlite3命令行工具直接查询索引表，整个流程非常透明和可调试。

当然，Docmancer并没有完全放弃向量检索。它通过可选的[bench]扩展包，内置了一个完整的评测框架（docmancer bench），让你可以在自己的文档数据集上，公平地对比FTS、Qdrant向量搜索以及更先进的RLM（检索语言模型）等不同后端的效果。这种设计体现了其务实精神：核心路径追求极简和可靠，同时为有进阶需求的用户提供了探索更优方案的工具。

2.2 工作流程与核心组件拆解

理解了“为什么”之后，我们来看“怎么做”。Docmancer的工作流可以清晰地分为三个阶段：摄入（Ingest）、索引（Index）、查询（Query）。

第一阶段：摄入与规范化。当你执行docmancer add https://docs.pytest.org时，背后的爬虫引擎开始工作。它支持多种来源：

GitBook / Mintlify：这些流行的文档平台有特定的结构，爬虫会针对性解析。
通用网页爬取：对于普通网站，它会提取主内容区。
GitHub仓库：直接克隆仓库并读取Markdown文件。
本地路径：读取本地的.md,.txt,.json等文件。

爬取到的内容不会被直接塞进数据库。Docmancer会进行“规范化”处理，这是其智能化的关键。它会根据HTML标签（如<h1>,<h2>,<p>）或Markdown的标题结构，将文档自动切分成一个个有逻辑的“章节”（Section）。每个章节包含标题、层级、原始内容和清理后的纯文本。这些原始文件会被保存到~/.docmancer/extracted/目录下，方便你随时查验。

注意：对于JavaScript渲染严重（SPA）的网站，基础爬虫可能失效。这时你需要安装docmancer[browser]扩展，它会启用Playwright无头浏览器来获取渲染后的HTML，确保内容完整性。

第二阶段：索引。规范化后的章节文本会被送入SQLite数据库。Docmancer主要利用FTS5虚拟表来建立全文搜索索引。FTS5会对文本进行分词，并建立倒排索引，使得后续的关键词查询能够快速定位到包含这些词的章节。除了全文内容，数据库还会记录每个章节的元数据：来源URL、在文档中的路径、层级等，为后续的结果归因和展示提供支持。

第三阶段：查询与打包。这是魔法发生的时刻。当AI助手（通过集成的Skill）或你通过CLI执行docmancer query “fixtures”时：

检索：查询语句被送到FTS5索引中进行匹配，默认返回相关度最高的结果。
排序与去重：系统会根据匹配分数、章节位置等因素对结果进行排序，并合并来自同一页面或邻近的重复内容。
打包：根据预设的Token预算（默认2400），系统从最相关的结果开始，依次将章节内容填充到一个“上下文包”中，直到达到预算上限。
格式化输出：最终生成一个Markdown格式的包，每个片段都清晰标注了来源（如[来源: https://docs.pytest.org/en/stable/how-to/fixtures.html]），并在开头给出本次检索的“压缩比”统计。

这个流程确保了AI每次得到的，都是高度浓缩、靶向明确的文档精华，而不是信息噪音。

3. 从零开始：完整安装与配置实战

理论讲完了，我们动手把它用起来。我会带你走一遍最完整的安装和初始化流程，包括可选的性能评测套件。

3.1 基础安装与初始化

Docmancer通过pipx安装是最推荐的方式，因为它能为每个工具创建独立的虚拟环境，避免与你的项目依赖冲突。

# 1. 安装pipx（如果你还没有的话） python3 -m pip install --user pipx python3 -m pipx ensurepath # 重新打开终端或执行 source ~/.bashrc (或 ~/.zshrc) # 2. 使用pipx安装docmancer核心 pipx install docmancer --python python3.13 # 指定Python版本是为了确保兼容性，3.11或3.12也可以。 # 3. 初始化配置和数据库 docmancer setup

执行setup后，它会做以下几件事：

在~/.docmancer/目录下创建配置文件docmancer.yaml。
初始化SQLite数据库文件docmancer.db。
自动检测你系统上已安装的AI助手（如Claude Code、Cursor），并尝试为其安装对应的“Skill”（插件）。安装过程通常是自动的，比如向Claude Code的插件目录写入一个Python脚本。

如果你想跳过交互确认，一次性安装所有支持的Agent Skill，可以使用：

docmancer setup --all

3.2 安装完整评测套件（可选但推荐）

如果你想体验docmancer bench功能，对比不同检索后端，或者需要让LLM自动为你的文档生成评测问题，你需要安装功能更全的[bench]扩展。

这里有一个关键坑点需要特别注意：如果你已经用pipx install docmancer安装了基础版，直接运行pipx install 'docmancer[bench]'可能会被pipx忽略，因为它认为docmancer已经安装了。正确的做法是向已有的pipx环境“注入”依赖：

# 方案一：分别注入各个组件（推荐，清晰可控） pipx inject docmancer 'qdrant-client>=1.7.0' 'fastembed>=0.2.0' # 向量后端 pipx inject docmancer 'rlms>=0.1.0' # RLM后端 pipx inject docmancer 'ragas>=0.2.0' # 答案评分（Judge） pipx inject docmancer 'anthropic>=0.40' 'openai>=1.50' 'google-genai>=0.3' # LLM SDK # 方案二：强制重新安装完整版（会覆盖现有安装） pipx install 'docmancer[bench]' --force --python python3.13

对于使用普通pip的用户，安装就简单多了：

pip install 'docmancer[bench]'

安装完成后，你可以通过docmancer bench --help验证功能是否已就位。

3.3 添加你的第一批文档

安装配置好后，就可以开始构建你的个人知识库了。让我们以常见的Python开发文档为例：

# 添加Pytest官方文档 docmancer add https://docs.pytest.org/en/stable/ # 添加FastAPI官方文档 docmancer add https://fastapi.tiangolo.com/ # 添加本地项目文档 docmancer add ./my-project/docs # 添加一个GitHub仓库的文档（例如某个流行的UI库） docmancer add https://github.com/awesome-ui/lib/docs

执行add命令后，你会看到终端输出爬取和索引的进度。完成后，可以用docmancer list查看所有已索引的文档源。

实操心得：对于大型文档站，首次爬取和索引可能需要几分钟时间。建议在网络良好的环境下进行。如果中途失败，可以再次执行docmancer add，它会尝试续传或重新开始。所有原始文件都保存在~/.docmancer/extracted/下，如果怀疑爬取内容有问题，可以去那里检查原始Markdown文件。

4. 核心使用场景与高级技巧

4.1 集成到AI编码助手工作流

Docmancer的价值只有在与AI助手联动时才能最大化。它通过“Skill”机制与各种助手集成。

以Claude Code为例：运行docmancer setup时，如果检测到Claude Code，它会自动在Claude Code的插件目录安装一个Skill。安装后，你在Claude Code的聊天界面中，可以直接使用@docmancer来触发查询。例如，在编写测试时，你可以问：“@docmancer如何使用pytest的参数化测试？” AI会在其上下文中收到一个来自Docmancer的、精炼过的pytest文档片段，从而给出更准确的答案。

手动安装Skill：如果自动安装失败，或者你想为其他助手安装，可以手动执行：

docmancer install claude-code docmancer install cursor docmancer install codex # ... 支持列表见 `docmancer install --help`

对于Claude Desktop：它的集成方式略有不同。docmancer install claude-desktop会生成一个.zip文件，你需要手动打开Claude Desktop应用，进入设置（Settings） -> 开发者（Developer） -> 安装技能（Install Skill），然后上传这个zip包。

注意事项：所有Skill共享同一个本地的~/.docmancer/docmancer.db索引文件。这意味着你在CLI中添加的文档，立即对所有安装的Skill生效。这种设计保证了数据源的统一和便捷。

4.2 命令行查询与结果调优

除了在AI中调用，CLI本身就是一个强大的文档查询工具。

基础查询：

docmancer query "异步依赖注入"

这会返回一个Markdown格式的上下文包，最上方会醒目地显示本次检索的压缩效率，例如：“Context pack: ~1200 tokens vs ~6500 raw docs tokens (81.5% less docs overhead)”。

获取结构化数据（用于脚本处理）：

docmancer query "异步依赖注入" --format json

JSON格式包含了更丰富的信息，如每个片段的token数、来源URL、置信度分数等，适合进一步编程处理。

扩展上下文范围：有时候，光看最匹配的片段可能不够，需要看看它的“上下文”。--expand参数就派上用场了。

--expand：默认行为，在匹配片段前后各包含一个相邻片段。
--expand page：直接包含匹配片段所在的整个页面内容，但受总Token预算限制。

# 查看匹配片段及其前后文 docmancer query "pytest mark" --expand # 如果Token预算充足，直接拉取整个页面 docmancer query "fastapi Depends" --expand page

管理文档源：

docmancer list：列出所有索引的文档源及其状态。
docmancer update：更新所有文档源。这对于跟踪官方文档更新非常有用，它会重新爬取并重建索引。
docmancer remove <source>：删除某个特定的文档源。<source>可以是URL或你在list中看到的标识名。
docmancer remove --all：谨慎使用！清除所有索引数据（但保留配置和提取的原始文件）。

4.3 项目级本地化配置

默认的全局配置适用于个人机器。但在团队项目或需要隔离环境的情况下，你可能希望每个项目有自己的Docmancer索引。

cd /path/to/your-project docmancer init

这条命令会在当前目录下生成一个docmancer.yaml配置文件，并将数据库和提取文件目录指向项目内的.docmancer/子文件夹。之后在该项目目录下执行的所有docmancer命令，都会优先使用这个本地配置，与全局配置互不干扰。

一个典型的项目级docmancer.yaml如下：

index: db_path: .docmancer/docmancer.db # 数据库放在项目内 extracted_dir: .docmancer/extracted/ # 提取文件也放在项目内 bench: datasets_dir: .docmancer/bench/datasets # 评测数据集目录 runs_dir: .docmancer/bench/runs # 评测运行结果目录 backends: k_retrieve: 10 # 检索阶段返回多少候选片段 k_answer: 5 # 最终打包进上下文的片段数

这种配置非常适合将文档索引作为项目资产提交到Git仓库中（注意忽略.docmancer/extracted/里的大文件），确保所有团队成员有一致的AI辅助体验。

5. 深度评测：用数据选择最佳检索后端

Docmancer最酷的功能之一就是其内置的评测框架docmancer bench。它允许你基于自己的文档，科学地比较FTS、向量搜索（Qdrant）和RLM等不同检索技术的效果，而不仅仅是相信宣传。

5.1 快速上手：使用内置数据集

Docmancer贴心地准备了一个名为“Lenny”的内置数据集，它基于Lenny Rachitsky的时事通讯和播客数据，包含了30个人工编写的问题和答案。这是体验评测流程最快的方式。

# 1. 初始化评测环境（创建必要的目录结构） docmancer bench init # 2. 使用内置的lenny数据集 docmancer bench dataset use lenny # 首次运行会从GitHub下载约24MB的数据集，并需要你确认许可协议。 # 3. 使用FTS后端运行一次评测，并给这次运行起个ID docmancer bench run --backend fts --dataset lenny --run-id my_first_fts_run # 4. 查看评测报告 docmancer bench report my_first_fts_run

报告会以Markdown形式生成，包含检索命中率、答案相关性评分等关键指标，并保存在.docmancer/bench/runs/my_first_fts_run/report.md。

5.2 实战：为你自己的文档创建评测集

内置数据集只是演示，真正的价值在于评测你自己的项目文档。你需要让LLM根据你的文档，自动生成一批带标准答案的问题。

# 1. 确保已安装[llm]扩展并配置了API Key # 例如，设置OpenAI: export OPENAI_API_KEY='your-key' # 2. 从你的文档目录生成评测数据集 docmancer bench dataset create \ --from-corpus ./my-project-docs \ --size 30 \ --name my_project_qa \ --provider openai

--from-corpus: 指定你的文档文件夹路径。
--size: 生成多少个问题。
--name: 给你的数据集起个名字。
--provider: 指定使用的LLM。auto会按顺序尝试Anthropic、OpenAI、Gemini、Ollama。如果都没配置，会回退到简单的启发式方法（基于标题生成问题）。

执行后，LLM会阅读你的文档，生成涵盖“简单”、“中等”、“困难”不同难度的问题，并为每个问题标注答案所在的源文件和文本片段。生成的数据集保存在~/.docmancer/bench/datasets/my_project_qa/。

5.3 运行多后端对比测试

生成了自己的数据集后，就可以进行严肃的对比了。

# 1. 运行FTS后端测试 docmancer bench run --backend fts --dataset my_project_qa --run-id proj_fts # 2. 运行Qdrant向量后端测试 (需要[vector]扩展) docmancer bench run --backend qdrant --dataset my_project_qa --run-id proj_qdrant # 首次运行会自动下载嵌入模型（如BGE）。 # 3. 运行RLM后端测试 (需要[rlm]扩展) docmancer bench run --backend rlm --dataset my_project_qa --run-id proj_rlm # RLM（检索语言模型）是一种更智能的检索方式，但速度可能较慢。 # 4. 对比三个后端的结果 docmancer bench compare proj_fts proj_qdrant proj_rlm

compare命令会生成一个对比表格，清晰地展示各后端在检索命中率、答案精确度、响应时间等维度的表现。这为你决定在生产工作流中使用哪个后端提供了数据支撑。

踩坑记录：在运行bench时，尤其是RLM后端，可能会消耗大量内存和时间。建议第一次在小型数据集（比如10个问题）上跑通流程。另外，确保你的~/.docmancer/目录有足够的磁盘空间，因为嵌入模型和运行记录可能会占用几个GB。

5.4 理解评测结果与产出物

每次bench run都会在运行ID对应的目录下（例如.docmancer/bench/runs/proj_fts/）生成一系列文件，这是宝贵的调试和分析资源：

config.snapshot.yaml: 本次运行的完整配置快照。
retrievals.jsonl: 每一行记录了一次检索的查询、返回的片段ID和分数。
answers.jsonl: 记录系统根据检索片段生成的答案。
metrics.json: 核心评测指标的JSON数据。
report.md: 人类可读的评测总结报告。

通过分析这些文件，你不仅能知道“哪个后端更好”，还能深入理解“为什么”——比如向量搜索在哪些类型的问题上表现更好，FTS的短板在哪里。

6. 常见问题排查与维护技巧

即使设计得再完善，在实际使用中也可能遇到问题。下面是我总结的一些常见情况及解决方法。

6.1 安装与初始化问题

问题：pipx install失败，提示Python版本问题。

原因：pipx默认可能使用了系统的不兼容Python版本。
解决：明确指定Python解释器路径：pipx install docmancer --python /usr/local/bin/python3.13。使用which python3.13找到正确路径。

问题：docmancer setup后，AI助手（如Cursor）里没有出现Docmancer技能。

原因1：自动检测失败。某些AI助手的安装路径比较隐蔽或自定义。
解决1：尝试手动安装：docmancer install cursor。查看命令输出，确认技能文件被复制到了正确位置。
原因2：AI助手需要重启或重新加载插件。
解决2：完全退出Cursor或Claude Code再重新启动。
排查：运行docmancer doctor，它会检查技能安装状态并给出提示。

6.2 文档爬取与索引问题

问题：docmancer add https://some-site.com爬取失败或内容为空。

原因1：网站需要JavaScript渲染，基础爬虫无法获取内容。
解决1：安装浏览器扩展后重试：pipx inject docmancer 'docmancer[browser]'，然后再次执行add命令。
原因2：网站有反爬机制或结构特殊。
解决2：尝试使用crawl4ai扩展：pipx inject docmancer 'docmancer[crawl4ai]'。或者考虑先将网页手动保存为HTML或Markdown，再用docmancer add ./local-file.html添加。
排查：查看~/.docmancer/extracted/目录下对应网站的文件，确认爬取到了什么内容。

问题：索引后查询结果不相关。

原因：文档结构特殊，导致章节切分不合理。
解决：Docmancer的章节切分基于启发式规则。目前没有提供细粒度调整参数。可以尝试反馈给项目作者，或者对于结构特别差的文档，考虑预处理（如用其他工具转换格式）后再添加。

6.3 查询与性能问题

问题：查询速度慢。

原因1：首次查询或数据库较大时，SQLite可能需要预热。
解决1：通常后续查询会变快。确保你的.db文件在SSD上。
原因2：使用了--expand page且匹配的页面本身非常大。
解决2：避免对大型页面使用page扩展，或增加Token预算。
排查：使用docmancer inspect查看索引统计，了解数据规模。

问题：返回的上下文包总是很小，感觉信息不全。

原因：默认Token预算（2400）可能不够。
解决：目前Token预算是硬编码在代码中的，无法直接通过配置修改。这是一个已知限制。你可以关注项目GitHub的Issue或更新，未来版本可能会支持配置。临时方案是使用--expand page来获取整个页面内容（如果页面本身不大）。

6.4 评测框架 (`bench`) 相关问题

问题：docmancer bench dataset create报错，提示没有LLM提供商。

原因：未安装[llm]扩展或未设置API环境变量。
解决：
1. 安装LLM扩展：pipx inject docmancer 'anthropic' 'openai' 'google-genai'。
2. 设置至少一个API Key，例如export OPENAI_API_KEY='sk-...'。
3. 如果不想用付费API，可以启动本地Ollama，然后使用--provider ollama。确保ollama serve正在运行。

问题：bench run时Qdrant或RLM后端出错。

原因：依赖未正确安装或初始化失败。
解决：
1. 确认已安装对应扩展（[vector]或[rlm]）。
2. 对于Qdrant，首次运行会自动下载嵌入模型，需要网络通畅。
3. 查看详细的错误日志。运行命令时添加--verbose标志可以获得更多输出。
4. 尝试删除.docmancer/bench/runs/下的相关运行目录，重新开始。

维护建议：

定期更新：使用docmancer update来更新你添加的在线文档源，确保AI获取的是最新信息。
清理空间：~/.docmancer/extracted/目录保存了原始文件，如果磁盘紧张，可以手动清理一些不再需要的文档源对应的文件夹。使用docmancer remove <source>会同时删除索引和提取文件。
备份配置：你的~/.docmancer/docmancer.yaml配置文件是核心。如果重装系统或迁移环境，备份此文件以及.db文件可以快速恢复状态。

经过一段时间的深度使用，我认为Docmancer精准地切入了一个细分但高价值的痛点。它没有追求大而全的RAG解决方案，而是专注于“为编码AI减负”这一件事，并通过本地优先、简单可靠的设计把它做到了极致。虽然它在配置灵活性（如Token预算调整）和爬虫适应性上还有提升空间，但其带来的开发效率提升是立竿见影的。尤其是当你将其集成到日常的Claude Code或Cursor对话中，那种无需反复复制粘贴文档、AI就能精准理解上下文的感觉，会显著改变你与AI协作的流畅度。

查看全文

http://www.jsqmd.com/news/781403/