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 --all3.2 安装完整评测套件可选但推荐如果你想体验docmancer bench功能对比不同检索后端或者需要让LLM自动为你的文档生成评测问题你需要安装功能更全的[bench]扩展。这里有一个关键坑点需要特别注意如果你已经用pipx install docmancer安装了基础版直接运行pipx install docmancer[bench]可能会被pipx忽略因为它认为docmancer已经安装了。正确的做法是向已有的pipx环境“注入”依赖# 方案一分别注入各个组件推荐清晰可控 pipx inject docmancer qdrant-client1.7.0 fastembed0.2.0 # 向量后端 pipx inject docmancer rlms0.1.0 # RLM后端 pipx inject docmancer ragas0.2.0 # 答案评分Judge pipx inject docmancer anthropic0.40 openai1.50 google-genai0.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 jsonJSON格式包含了更丰富的信息如每个片段的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_KEYyour-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_rlmcompare命令会生成一个对比表格清晰地展示各后端在检索命中率、答案精确度、响应时间等维度的表现。这为你决定在生产工作流中使用哪个后端提供了数据支撑。踩坑记录在运行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。查看命令输出确认技能文件被复制到了正确位置。原因2AI助手需要重启或重新加载插件。解决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环境变量。解决安装LLM扩展pipx inject docmancer anthropic openai google-genai。设置至少一个API Key例如export OPENAI_API_KEYsk-...。如果不想用付费API可以启动本地Ollama然后使用--provider ollama。确保ollama serve正在运行。问题bench run时Qdrant或RLM后端出错。原因依赖未正确安装或初始化失败。解决确认已安装对应扩展[vector]或[rlm]。对于Qdrant首次运行会自动下载嵌入模型需要网络通畅。查看详细的错误日志。运行命令时添加--verbose标志可以获得更多输出。尝试删除.docmancer/bench/runs/下的相关运行目录重新开始。维护建议定期更新使用docmancer update来更新你添加的在线文档源确保AI获取的是最新信息。清理空间~/.docmancer/extracted/目录保存了原始文件如果磁盘紧张可以手动清理一些不再需要的文档源对应的文件夹。使用docmancer remove source会同时删除索引和提取文件。备份配置你的~/.docmancer/docmancer.yaml配置文件是核心。如果重装系统或迁移环境备份此文件以及.db文件可以快速恢复状态。经过一段时间的深度使用我认为Docmancer精准地切入了一个细分但高价值的痛点。它没有追求大而全的RAG解决方案而是专注于“为编码AI减负”这一件事并通过本地优先、简单可靠的设计把它做到了极致。虽然它在配置灵活性如Token预算调整和爬虫适应性上还有提升空间但其带来的开发效率提升是立竿见影的。尤其是当你将其集成到日常的Claude Code或Cursor对话中那种无需反复复制粘贴文档、AI就能精准理解上下文的感觉会显著改变你与AI协作的流畅度。
Docmancer：本地化文档压缩工具，为AI编码助手节省60%-90%上下文Token
发布时间：2026/7/26 5:57:14
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 --all3.2 安装完整评测套件可选但推荐如果你想体验docmancer bench功能对比不同检索后端或者需要让LLM自动为你的文档生成评测问题你需要安装功能更全的[bench]扩展。这里有一个关键坑点需要特别注意如果你已经用pipx install docmancer安装了基础版直接运行pipx install docmancer[bench]可能会被pipx忽略因为它认为docmancer已经安装了。正确的做法是向已有的pipx环境“注入”依赖# 方案一分别注入各个组件推荐清晰可控 pipx inject docmancer qdrant-client1.7.0 fastembed0.2.0 # 向量后端 pipx inject docmancer rlms0.1.0 # RLM后端 pipx inject docmancer ragas0.2.0 # 答案评分Judge pipx inject docmancer anthropic0.40 openai1.50 google-genai0.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 jsonJSON格式包含了更丰富的信息如每个片段的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_KEYyour-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_rlmcompare命令会生成一个对比表格清晰地展示各后端在检索命中率、答案精确度、响应时间等维度的表现。这为你决定在生产工作流中使用哪个后端提供了数据支撑。踩坑记录在运行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。查看命令输出确认技能文件被复制到了正确位置。原因2AI助手需要重启或重新加载插件。解决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环境变量。解决安装LLM扩展pipx inject docmancer anthropic openai google-genai。设置至少一个API Key例如export OPENAI_API_KEYsk-...。如果不想用付费API可以启动本地Ollama然后使用--provider ollama。确保ollama serve正在运行。问题bench run时Qdrant或RLM后端出错。原因依赖未正确安装或初始化失败。解决确认已安装对应扩展[vector]或[rlm]。对于Qdrant首次运行会自动下载嵌入模型需要网络通畅。查看详细的错误日志。运行命令时添加--verbose标志可以获得更多输出。尝试删除.docmancer/bench/runs/下的相关运行目录重新开始。维护建议定期更新使用docmancer update来更新你添加的在线文档源确保AI获取的是最新信息。清理空间~/.docmancer/extracted/目录保存了原始文件如果磁盘紧张可以手动清理一些不再需要的文档源对应的文件夹。使用docmancer remove source会同时删除索引和提取文件。备份配置你的~/.docmancer/docmancer.yaml配置文件是核心。如果重装系统或迁移环境备份此文件以及.db文件可以快速恢复状态。经过一段时间的深度使用我认为Docmancer精准地切入了一个细分但高价值的痛点。它没有追求大而全的RAG解决方案而是专注于“为编码AI减负”这一件事并通过本地优先、简单可靠的设计把它做到了极致。虽然它在配置灵活性如Token预算调整和爬虫适应性上还有提升空间但其带来的开发效率提升是立竿见影的。尤其是当你将其集成到日常的Claude Code或Cursor对话中那种无需反复复制粘贴文档、AI就能精准理解上下文的感觉会显著改变你与AI协作的流畅度。
