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 能 diff，grep能搜，就算 OpenWiki 这个项目哪天不维护了，你的内容资产依然完好无损。这一点在选型时权重极高，我见过太多团队被私有 Wiki 格式坑过。

另一个关键原因是 Markdown 天然适合被程序处理。标题层级就是天然的文档结构，代码块就是天然的语义边界，表格就是天然的结构化数据。AI Agent 在做文档切片（chunking）时，如果按 Markdown 的标题层级来切，效果远好于按固定字符数硬切。比如一个##二级标题下的内容通常是一个完整语义单元，按这个边界切出来的 chunk，检索命中率和回答质量都会明显提升。这也是为什么很多 RAG 方案在处理 Markdown 时会专门用MarkdownHeaderTextSplitter这类工具，而不是简单的RecursiveCharacterTextSplitter。

提示：如果你打算自己搭类似系统，务必在切片阶段保留标题路径信息。把## 部署下的内容切片时，给每个 chunk 的元数据打上{"h1": "运维手册", "h2": "部署"}，检索时把标题路径拼进上下文，回答准确率会有肉眼可见的提升。

2.2 CLI 交互为什么比 Web 界面更"香"

很多人第一反应是：都什么年代了还做 CLI，Web 界面不香吗？我一开始也这么质疑，直到实际用了一段时间才改观。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 图片路径是个高频坑。文档里写![](./images/a.png)，在本地编辑器里能显示，但一旦文档被移动或知识库做了路径重写，图片就全挂了。我的做法是统一用相对于仓库根目录的路径，并在预处理阶段把图片路径转成绝对 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(encoding="utf-8", errors="ignore") # 统一换行符，避免 Windows/Linux 混用 text = text.replace("\r\n", "\n") docs.append({"path": str(path), "content": text}) return docs

这段代码看着简单，但errors="ignore"这个参数救过我很多次——有些老文档编码混乱，不加这个直接抛异常，整个采集流程就断了。宁可丢几个乱码字符，也别让流程挂掉。

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_on=headers_to_split_on, strip_headers=False, ) char_splitter = RecursiveCharacterTextSplitter( chunk_size=600, chunk_overlap=80, 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 final

chunk_overlap设成 80 是有讲究的。重叠部分是为了防止关键信息正好卡在切分边界上被切断，80 个字符大约是一两句话的长度，能覆盖大部分边界情况。设太大浪费存储和检索成本，设太小起不到保护作用。这个值我调过好几轮，600/80 这个组合在中文技术文档上表现比较均衡。

注意：中文和英文的切片参数不能照搬。英文按空格切很自然，中文没有空格，RecursiveCharacterTextSplitter的默认分隔符对中文不友好，一定要手动加上。、！、？这些中文标点作为分隔符，否则会切出一堆语义断裂的碎片。

3.3 向量化与检索：选型与参数调优

切片之后就是向量化。这一步要选 embedding 模型，常见的有本地模型和 API 模型两类。本地模型的好处是数据不出内网、没有调用成本，缺点是效果和速度取决于你的硬件；API 模型效果好、省心，但要考虑成本和数据合规。中小团队我一般建议先用 API 模型快速验证效果，跑通了再考虑换本地模型降本。

检索环节有个容易被忽略的点：单纯向量检索（dense retrieval）对专有名词、代码标识符的召回效果一般。比如你搜create_retrieval_chain，向量检索可能给你返回一堆语义相近但函数名不对的文档。这时候需要混合检索（hybrid search），把向量检索和关键词检索（BM25）结合起来。有意思的是，热词里提到"langchain 和 langchain4j 的默认 rrf 实现去重逻辑存在缺陷"，这说的正是混合检索里的 RRF（Reciprocal 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 python=3.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(model="text-embedding-3-small") vectordb = Chroma.from_documents( documents=all_chunks, embedding=embeddings, persist_directory=db_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(model="text-embedding-3-small") vectordb = Chroma(persist_directory=db_dir, embedding_function=embeddings) retriever = vectordb.as_retriever(search_kwargs={"k": top_k}) llm = ChatOpenAI(model="gpt-4o-mini", temperature=0) 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')}")

temperature=0是必须的。知识库问答要的是准确和稳定，不是创意，温度调高只会让模型开始"发挥"。prompt 里那句"如果资料中没有相关信息，直接说不知道"也是血泪教训——不加这句，模型遇到检索不到的问题会一本正经地胡说八道，这在技术文档场景里是致命的。

4.4 接入 MCP 与工具扩展

热词里反复出现 "ai agent skill memory mcp"，这其实是当前 Agent 开发的三个关键能力：技能（skill，即能调用哪些工具）、记忆（memory，即多轮对话的上下文保持）、MCP（Model 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 之所以越来越多人用，本质上就是因为它足够轻、足够开放、足够贴近开发者本来的写作和查询习惯——你不用为它改变什么，它来适应你。这个思路，我觉得比任何具体的技术细节都值得记住。