OpenWiki 实战：Markdown + CLI + AI Agent 构建可问答知识库

1. 从命令行到知识库OpenWiki 到底解决了什么问题第一次听到 OpenWiki 这个名字很多人会下意识觉得它又是一个维基百科的克隆。我最初也是这么想的直到在一个内部知识管理项目里被文档同步折磨了整整两周才真正理解它为什么会在开发者圈子里悄悄火起来。简单说OpenWiki 是一套以 Markdown 为内容载体、以 CLI 为主要交互入口、可以对接 AI Agent 做自动整理与问答的开源知识库方案。它要解决的核心痛点非常具体团队里散落各处的文档、笔记、接口说明、踩坑记录怎么在不改变大家写作习惯的前提下自动汇聚成一个可检索、可问答、可版本管理的知识中枢。这件事听起来简单做起来全是坑。传统 Wiki 系统要求你登录网页、点新建、选模板、填表单写一篇文档的成本高得离谱结果就是没人写。而纯 Markdown 文件夹虽然写作成本低但检索靠 grep、结构靠自觉、新人上手全靠口口相传。OpenWiki 的定位恰好卡在中间内容仍然是纯 Markdown你甚至可以直接用 VS Code 写但索引、检索、问答、关联推荐这些重活交给背后的 AI Agent 和向量检索去干。这就是它和 LangChain 生态天然契合的原因——LangChain 负责把文档切片、向量化、接上大模型做 RAG 问答OpenWiki 负责把这一切包装成一个openwiki命令就能跑起来的东西。适合谁来用我观察下来主要是三类人。第一类是中小研发团队的技术负责人需要一个低成本、可自托管、不绑定云厂商的知识库第二类是喜欢折腾 AI Agent 的独立开发者想拿一个真实项目练手 LangChain、LangGraph、MCP 这些概念第三类是写作者和研究者手头积累了大量 Markdown 笔记想要一个能问自己笔记的工具。如果你属于这三类中的任何一类接下来的内容应该能帮你少走不少弯路。2. 整体设计思路为什么是 Markdown CLI AI Agent 这个组合2.1 内容层选 Markdown 的底层逻辑先说内容载体为什么必须是 Markdown。这不是赶时髦而是被现实逼出来的选择。团队协作里最怕的就是格式锁定——你用某个私有格式写的东西三年后软件停更了文档全成乱码。Markdown 是纯文本任何编辑器都能打开Git 能 diffgrep能搜就算 OpenWiki 这个项目哪天不维护了你的内容资产依然完好无损。这一点在选型时权重极高我见过太多团队被私有 Wiki 格式坑过。另一个关键原因是 Markdown 天然适合被程序处理。标题层级就是天然的文档结构代码块就是天然的语义边界表格就是天然的结构化数据。AI Agent 在做文档切片chunking时如果按 Markdown 的标题层级来切效果远好于按固定字符数硬切。比如一个##二级标题下的内容通常是一个完整语义单元按这个边界切出来的 chunk检索命中率和回答质量都会明显提升。这也是为什么很多 RAG 方案在处理 Markdown 时会专门用MarkdownHeaderTextSplitter这类工具而不是简单的RecursiveCharacterTextSplitter。提示如果你打算自己搭类似系统务必在切片阶段保留标题路径信息。把## 部署下的内容切片时给每个 chunk 的元数据打上{h1: 运维手册, h2: 部署}检索时把标题路径拼进上下文回答准确率会有肉眼可见的提升。2.2 CLI 交互为什么比 Web 界面更香很多人第一反应是都什么年代了还做 CLIWeb 界面不香吗我一开始也这么质疑直到实际用了一段时间才改观。CLI 的优势在于它离内容生产现场最近。你在终端里写代码、跑测试、查日志顺手敲一个openwiki ask 上次那个数据库连接池的配置是怎么调的答案直接出来全程不用切窗口、不用等网页加载、不用登录。这种零上下文切换的体验是 Web 界面给不了的。而且 CLI 天然适合自动化和脚本化。你可以把它挂到 Git hook 上每次 commit 自动更新索引可以写个定时任务每天把新文档同步进知识库可以接进 CI在 PR 里自动检查文档是否引用了不存在的链接。这些在 Web 界面里要么做不了要么得调 API 绕一大圈。CLI 还有个隐性好处它强迫你把接口设计得干净。一个命令、几个参数、清晰的输入输出这种约束反而让整个系统更容易维护和组合。2.3 AI Agent 在其中的角色定位这里要澄清一个常见混淆AI Agent、LLM、AI 模型到底啥区别拿大家熟悉的 DeepSeek 举例DeepSeek 本身是一个大语言模型LLM它能理解问题、生成文本但它不会主动去查你的文档、不会决定先检索再回答、不会调用工具。而 AI Agent 是在 LLM 外面套了一层决策与执行的框架——它知道什么时候该去检索知识库、什么时候该调用某个工具、什么时候该把多个步骤串起来。LangChain 就是干这个的它提供了 Agent 的骨架、工具的封装、记忆的管理。在 OpenWiki 里AI Agent 承担的是知识管家的角色。用户问一个问题Agent 先判断这个问题需不需要查文档需要的话就去向量库里检索相关片段把片段和问题一起喂给 LLM 生成回答最后可能还会附上引用来源。如果问题复杂Agent 还能拆成多步先查概念定义再查具体配置最后综合。这套流程用 LangChain 的create_retrieval_chain或者更灵活的 LangGraph 都能实现。理解了这个分层你就明白为什么 OpenWiki 这类项目会同时出现在 LangChain 和 AI Agent 的讨论里——它们是同一套技术栈的不同切面。3. 核心细节拆解从文档到可问答知识库的完整链路3.1 文档采集与预处理的关键细节知识库的第一步永远是把文档弄进来这一步的坑比想象中多。OpenWiki 通常支持几种采集方式直接扫描本地目录、从 Git 仓库拉取、通过 API 接收推送。我建议新手从本地目录扫描开始因为最容易调试。扫描时要处理几个问题忽略哪些文件.git、node_modules、二进制文件、识别哪些扩展名.md、.mdx、.markdown、怎么处理图片路径。Markdown 图片路径是个高频坑。文档里写在本地编辑器里能显示但一旦文档被移动或知识库做了路径重写图片就全挂了。我的做法是统一用相对于仓库根目录的路径并在预处理阶段把图片路径转成绝对 URL 或者复制到统一的静态资源目录。另外 Markdown 换行也是个经典问题——行尾两个空格才是硬换行很多人不知道导致渲染出来全挤在一起。预处理时可以考虑用工具统一格式化避免不同人写法不一致。# 一个简单的 Markdown 采集与清洗示例 import os import re from pathlib import Path IGNORE_DIRS {.git, node_modules, dist, build, .venv} VALID_EXT {.md, .mdx, .markdown} def collect_markdown(root_dir): docs [] for path in Path(root_dir).rglob(*): if any(part in IGNORE_DIRS for part in path.parts): continue if path.suffix.lower() not in VALID_EXT: continue text path.read_text(encodingutf-8, errorsignore) # 统一换行符避免 Windows/Linux 混用 text text.replace(\r\n, \n) docs.append({path: str(path), content: text}) return docs这段代码看着简单但errorsignore这个参数救过我很多次——有些老文档编码混乱不加这个直接抛异常整个采集流程就断了。宁可丢几个乱码字符也别让流程挂掉。3.2 切片策略决定问答质量的分水岭切片chunking是 RAG 系统里最容易被低估、却最影响效果的环节。切太大检索出来的内容冗余LLM 抓不住重点还浪费 token切太小语义不完整检索到了也答不上来。我的经验值是技术文档按标题层级切单个 chunk 控制在 300 到 800 字之间代码块尽量不切断。具体做法是先用 Markdown 标题切分得到粗粒度的块如果某个块还是太大比如一个超长的##章节再用字符递归切分兜底。LangChain 里可以这样组合from langchain_text_splitters import ( MarkdownHeaderTextSplitter, RecursiveCharacterTextSplitter, ) headers_to_split_on [ (#, h1), (##, h2), (###, h3), ] md_splitter MarkdownHeaderTextSplitter( headers_to_split_onheaders_to_split_on, strip_headersFalse, ) char_splitter RecursiveCharacterTextSplitter( chunk_size600, chunk_overlap80, separators[\n\n, \n, 。, , ], ) def split_doc(text): coarse md_splitter.split_text(text) final [] for chunk in coarse: if len(chunk.page_content) 800: final.extend(char_splitter.split_documents([chunk])) else: final.append(chunk) return finalchunk_overlap设成 80 是有讲究的。重叠部分是为了防止关键信息正好卡在切分边界上被切断80 个字符大约是一两句话的长度能覆盖大部分边界情况。设太大浪费存储和检索成本设太小起不到保护作用。这个值我调过好几轮600/80 这个组合在中文技术文档上表现比较均衡。注意中文和英文的切片参数不能照搬。英文按空格切很自然中文没有空格RecursiveCharacterTextSplitter的默认分隔符对中文不友好一定要手动加上。、、这些中文标点作为分隔符否则会切出一堆语义断裂的碎片。3.3 向量化与检索选型与参数调优切片之后就是向量化。这一步要选 embedding 模型常见的有本地模型和 API 模型两类。本地模型的好处是数据不出内网、没有调用成本缺点是效果和速度取决于你的硬件API 模型效果好、省心但要考虑成本和数据合规。中小团队我一般建议先用 API 模型快速验证效果跑通了再考虑换本地模型降本。检索环节有个容易被忽略的点单纯向量检索dense retrieval对专有名词、代码标识符的召回效果一般。比如你搜create_retrieval_chain向量检索可能给你返回一堆语义相近但函数名不对的文档。这时候需要混合检索hybrid search把向量检索和关键词检索BM25结合起来。有意思的是热词里提到langchain 和 langchain4j 的默认 rrf 实现去重逻辑存在缺陷这说的正是混合检索里的 RRFReciprocal Rank Fusion倒数排名融合算法。RRF 用来合并多路检索结果但如果两路结果里有重复文档去重逻辑没处理好就会出现同一篇文档被算两次分、排名虚高的问题。自己实现时一定要在融合前按文档 ID 去重。检索方式优势劣势适用场景纯向量检索语义理解强专有名词召回弱概念性问答纯关键词检索精确匹配强无法理解同义表达查函数名、配置项混合检索 RRF兼顾两者实现复杂、需去重生产环境推荐3.4 Agent 编排LangChain 与 LangGraph 怎么选到了 Agent 编排这一层很多人会纠结 LangChain 和 LangGraph 的区别。简单说LangChain 提供的是链chain的抽象适合线性的、步骤固定的流程比如检索→拼接→生成这种一条道走到黑的场景。LangGraph 提供的是图graph的抽象适合有分支、有循环、有状态管理的复杂流程比如先判断问题类型→简单问题直接答→复杂问题拆解→多轮检索→综合这种。OpenWiki 这种知识库问答如果只是简单的 RAG用 LangChain 的create_retrieval_chain就够了代码量少、上手快。但如果要做多轮对话、要做查询改写、要根据检索结果决定是否二次检索那就该上 LangGraph。我的建议是先用 LangChain 把最小可用版本跑通等遇到线性流程表达不了的需求时再迁移到 LangGraph。别一上来就上最复杂的框架那是给自己找罪受。4. 实操落地从零搭一个 OpenWiki 风格的知识库4.1 环境准备与依赖选择环境这块我强烈建议用 conda 或 venv 做隔离。LangChain 生态依赖更新快不同版本之间 API 变动不小全局安装迟早出问题。conda 的好处是能同时管 Python 版本和包对新手友好venv 更轻量适合已经熟悉 Python 环境管理的人。# 用 conda 创建环境 conda create -n openwiki python3.11 -y conda activate openwiki # 核心依赖 pip install langchain langchain-community langchain-text-splitters pip install chromadb # 本地向量库轻量够用 pip install openai # 如果用 API 模型 pip install typer rich # 做 CLI 界面选 Python 3.11 是因为它在性能和兼容性之间比较平衡3.12 有些库还没跟上3.10 又偏老。向量库选 Chroma 是因为它能本地持久化、零配置启动适合中小规模知识库。文档量上到十万级再考虑换 Milvus 或 Qdrant 这类专业向量库。4.2 索引构建的完整流程索引构建是整个系统的地基流程是采集→清洗→切片→向量化→入库。我把它封装成一个build命令方便重复执行。import typer from rich.console import Console from langchain_community.vectorstores import Chroma from langchain_openai import OpenAIEmbeddings app typer.Typer() console Console() app.command() def build(docs_dir: str ./docs, db_dir: str ./wiki_db): console.print(f[bold]扫描目录:[/bold] {docs_dir}) docs collect_markdown(docs_dir) console.print(f共发现 {len(docs)} 篇文档) all_chunks [] for doc in docs: chunks split_doc(doc[content]) for c in chunks: c.metadata[source] doc[path] all_chunks.extend(chunks) console.print(f切片完成共 {len(all_chunks)} 个 chunk) embeddings OpenAIEmbeddings(modeltext-embedding-3-small) vectordb Chroma.from_documents( documentsall_chunks, embeddingembeddings, persist_directorydb_dir, ) vectordb.persist() console.print([green]索引构建完成[/green]) if __name__ __main__: app()跑完这个命令你的wiki_db目录里就有了持久化的向量索引。下次启动不用重新构建直接加载即可。这里有个实操心得构建索引时一定要打印进度和统计信息。我第一次跑的时候没加日志一个几千篇文档的库跑了十几分钟中途卡住了都不知道卡在哪只能干等。加上rich的进度输出后一眼就能看出是采集慢还是向量化慢。4.3 问答命令的实现与调优问答命令是用户最常打交道的部分体验好坏直接决定这个工具会不会被用起来。核心逻辑是加载索引→检索→构造 prompt→调用 LLM→输出答案和引用。from langchain_openai import ChatOpenAI from langchain.chains import create_retrieval_chain from langchain.chains.combine_documents import create_stuff_documents_chain from langchain_core.prompts import ChatPromptTemplate app.command() def ask(question: str, db_dir: str ./wiki_db, top_k: int 4): embeddings OpenAIEmbeddings(modeltext-embedding-3-small) vectordb Chroma(persist_directorydb_dir, embedding_functionembeddings) retriever vectordb.as_retriever(search_kwargs{k: top_k}) llm ChatOpenAI(modelgpt-4o-mini, temperature0) prompt ChatPromptTemplate.from_template( 你是一个知识库助手。请仅根据以下资料回答问题 如果资料中没有相关信息直接说不知道不要编造。\n\n 资料:\n{context}\n\n问题: {input} ) combine_chain create_stuff_documents_chain(llm, prompt) rag_chain create_retrieval_chain(retriever, combine_chain) result rag_chain.invoke({input: question}) console.print(result[answer]) console.print(\n[dim]参考来源:[/dim]) for doc in result[context]: console.print(f - {doc.metadata.get(source)})temperature0是必须的。知识库问答要的是准确和稳定不是创意温度调高只会让模型开始发挥。prompt 里那句如果资料中没有相关信息直接说不知道也是血泪教训——不加这句模型遇到检索不到的问题会一本正经地胡说八道这在技术文档场景里是致命的。4.4 接入 MCP 与工具扩展热词里反复出现 ai agent skill memory mcp这其实是当前 Agent 开发的三个关键能力技能skill即能调用哪些工具、记忆memory即多轮对话的上下文保持、MCPModel Context Protocol一种让模型标准化调用外部工具和数据的协议。OpenWiki 要往真 Agent方向走这三块都得考虑。技能方面除了检索还可以给 Agent 加写文档更新索引查 Git 历史等工具。记忆方面简单场景用对话历史窗口就够复杂场景需要做摘要压缩避免上下文无限增长。MCP 方面如果你的知识库要对接多个数据源比如同时查文档、查数据库、查工单系统用 MCP 统一接口会比每个都写一套适配器清爽得多。不过我要泼盆冷水这些扩展别一次性全上先把核心的检索问答打磨好再逐步加。我见过太多项目功能列表列了一长串结果最基础的问答都不准本末倒置。5. 常见问题与排查技巧实录5.1 检索不准的排查思路为什么我问的问题它检索不到相关文档这是最高频的问题。排查要按顺序来别一上来就怀疑模型。第一步确认文档确实进了索引——直接查向量库的文档数量对不上就是采集或切片环节漏了。第二步把检索到的原始 chunk 打印出来看如果 chunk 内容本身就是乱的那是切片问题如果 chunk 内容对但没被检索到那是 embedding 或检索参数问题。第三步试试把top_k调大如果调大后能检索到说明是召回数量不够可以考虑加混合检索。我踩过的一个坑是文档里全是中文但 embedding 模型对中文支持一般导致语义相似度算不准。换成对中文优化过的模型后效果立竿见影。所以选 embedding 模型时一定要看它在你的语言和领域上的表现别盲目用默认的。5.2 索引更新与增量同步知识库是活的文档天天在变总不能每次都全量重建索引。增量同步的思路是记录每个文档的修改时间和内容哈希构建时只处理新增和变更的文档删除的文档从索引里移除。Chroma 支持按 metadata 过滤删除可以给每个 chunk 打上source和content_hash更新时先删旧的再插新的。问题现象可能原因排查方法解决方案检索不到相关文档切片过大/过小打印 chunk 内容调整 chunk_size答案答非所问prompt 约束不足检查 prompt加仅根据资料回答专有名词搜不到纯向量检索换关键词搜试试上混合检索索引更新后搜到旧内容未删除旧 chunk查文档数量按 source 删除重建中文效果差embedding 不适配换模型对比选中文优化模型5.3 成本与性能的平衡用 API 模型跑知识库成本是绕不开的话题。embedding 调用相对便宜但每次问答都要调 LLM量大起来也不便宜。几个降本思路一是缓存常见问题的答案相同问题直接返回二是检索阶段多召回、生成阶段少喂把 top_k 控制在合理范围别一股脑塞十几篇文档进去三是简单问题用小模型复杂问题才上大模型做个路由判断。性能方面向量检索本身很快瓶颈通常在 LLM 生成如果嫌慢可以考虑流式输出让用户先看到字一个个蹦出来体感上快很多。提示流式输出对 CLI 工具的体验提升巨大。用户敲完问题后如果干等五秒才出结果会以为卡死了如果字是逐渐出现的哪怕总时间一样感受也完全不同。LangChain 的stream方法配合rich的Live组件就能实现。5.4 几个容易忽视的细节最后分享几个我踩过的细节坑。第一Markdown 表格转换。很多人问 markdown 表格怎么转 Excel其实在知识库场景里表格最好在切片时单独处理因为表格的语义和普通段落不同混在一起切容易破坏结构。第二代码块里的内容检索。代码块里的函数名、参数名是高频查询对象但它们在向量空间里和自然语言距离较远建议对代码块单独建索引或走关键词检索。第三文档里的相对链接。文档 A 链接到文档 B如果只索引了内容没索引链接关系Agent 就没法做相关文档推荐。把链接关系也存进 metadata能解锁不少高级玩法。6. 我个人的一些实践体会折腾 OpenWiki 这类工具大半年最大的感受是技术选型只是开始真正决定成败的是内容质量和迭代习惯。我见过团队把工具搭得漂漂亮亮结果文档半年不更新知识库成了考古现场问出来的答案全是过时的。反过来有些团队工具很朴素但坚持写完代码顺手更新文档知识库越用越准形成了正循环。另一个体会是别追求一步到位。我最初想做一个全能 Agent能查文档、能写代码、能提工单结果每个功能都半吊子。后来砍到只做文档问答这一件事把它做到 90 分反而真正被团队用起来了。工具的价值不在于功能多而在于它能不能无缝嵌进大家已有的工作流。OpenWiki 之所以越来越多人用本质上就是因为它足够轻、足够开放、足够贴近开发者本来的写作和查询习惯——你不用为它改变什么它来适应你。这个思路我觉得比任何具体的技术细节都值得记住。