企业官网建设流程全解析

好长时间没聊知识库这个话题了。最近好几个做 Agent 开发的朋友都在问，说手里有了一批个人文档、技术笔记、业务资料，想喂给 Agent 用，结果一试向量库、图库，发现要么太复杂，要么结果不对劲。我这半年把知识库方案从向量数据库一路换到图数据库，最后折腾出一个最笨也是最顺手的结构：Agent 原生知识库，本地优先，纯 Markdown 存储。这套东西不解决所有问题，但能解决绝大多数问题，而且谁都能自己搭，不用被厂商绑定，也不用烧钱买云端服务。

先给个明确的定义：我说的 Agent 原生知识库，指的是“直接为 Agent 阅读、检索、推理而设计的知识库”，不是给人看的文档中心。它的核心要求有三个——层级清晰、语义密度高、状态可感知。本地优先指的是所有数据都存你自己的硬盘上，Agent 直接读本地文件，不走 API、不上传云端。纯 Markdown 存储指的是物理文件全都是.md文本，用 Markdown 的标题结构、列表、链接、表格来表达知识之间的逻辑关系。这三个特性合起来，就是一套可控、可审计、可版本管理、离线可用的 Agent 知识底座。

这套方案适合谁？我觉得适合四类人：一是玩 AI Agent 的个人开发者，想给自己 Agent 喂高质量私有知识；二是中小团队想快速搭一个不依赖外部服务、又方便多人用 Git 协作的资料库；三是重度知识管理用户，手里攒了几千篇 Markdown 笔记想复用；四是对数据隐私敏感、不想把内部文档传到云向量库的从业者。无论哪一类，接下来这套思路都能给你一些可以落地的参考。

1. 为什么“Agent 原生知识库”不等于 RAG 知识库

先说清楚一个很容易混淆的点。现在行业里聊知识库，十有八九聊的是 RAG（检索增强生成），也就是把文档切片、做 embedding、存向量库、检索召回。RAG 很有用，但它只是“检索管道”，不是“知识库”。你给 RAG 喂一堆 Markdown 也好、PDF 也好，它只负责把它们变成向量，并不真正理解文档之间的从属关系、因果链条和状态流转。结果就是：RAG 回答单个事实型问题很好用，一涉及多跳推理、状态判断、流程约束，就露怯。

知识图谱（KG）呢？它擅长表达实体间关系，比如“A 依赖 B”“B 属于 C 模块”，但建图成本高，而且对幻觉的容忍度很低——图里一个错误边，推理结果能歪到离谱。结构知识库（比如数据库里的表、CSV、JSON Schema）表达精准，但特别死板，装不下半结构化的经验类知识。

这三种知识库各有所长，我做过一个对比，实际用下来大概是这样：

你发现问题没有？前三种方案，本质上都是“把人读的知识，转换成机器更容易处理的其他形态”，转换过程会丢信息、会走样。而 Agent 原生知识库的思路反过来：让 Agent 去适应用人写出来的、本来就已结构化的 Markdown 文档。人写 Markdown 时会自然地分标题、分层级、列要点、加链接，这些结构本身就是语义，Agent 做推理时不需要额外转换，直接顺着标题层级和链接就能定位上下文。这就像你给一个新员工入职培训，比起扔他一套数据库表和知识图谱，不如给他一本目录清晰、互相引用的 Markdown 文档仓库，他反而上手更快。

2. 本地优先不是“没有云”，而是“云是可选”

我见过很多人一听本地优先就以为是“拒绝云端”。其实是两码事。本地优先的准确表述是：所有数据的真实载体（source of truth）是我本地硬盘上的文件，云端只是可选的同步目的地和计算加速器。这份理念的核心是数据主权——谁拥有知识，谁说了算。

为什么这次我强烈建议本地优先？主要是四个现实原因。

第一，隐私和合规压力。我现在给一个团队做内部 Agent 系统的知识库，里面大量文档涉及客户数据、未公开产品计划、内部财务口径。这些内容别说上传云端，就是过一遍公共 LLM API 都不太敢。本地优先意味着 Embedding 可以在本地跑，向量索引存在本地，Agent 读文件走本地路径，数据不出内网。这不是不信任云厂商，而是有些数据它本质上就不应该离开你的控制边界。

第二，成本。向量数据库的云端费用看着不贵，但你算上 token、embedding API 调用、存储增长、并发吞吐，几个月下来就不是小数目。本地优先方案里，模型的 embedding 用本地开源模型跑，向量索引用轻量方案（后续会讲到），Agent 读 Markdown 文件直接走文件系统，成本几乎为零，只有电费。对个人和小团队来说，这是决定性优势。

第三，可审计性和可回滚性。知识库里的知识是活的，它会改、会错、会过期。云端向量库里改一条知识，你可能根本不知道什么时候改过、为什么改、改之前长什么样。但 Markdown 文件加 Git，每次变更都是 diff，每条记录都有 commit message。Agent 如果引用了过时内容，你可以直接 git log 查清楚是谁、在什么时候、把哪一条给改了。这个能力，向量库和云知识库都给不了。

第四，离线可用。我之前在飞机上调试 Agent，发现本地知识库毫秒级响应，而任何需要走网络的方案全部瘫痪。本地优先架构天然支持离线运行，你只需要一个有本地推理能力的模型（比如 Ollama 跑 Qwen），整套 Agent 就能在完全断网的环境下工作。对经常出差、在弱网环境干活、或者有保密网络要求的场景，这是硬需求。

3. 纯 Markdown 存储，用最少的技术换最大的收益

如果你接受“本地优先”这个大方向，那文件格式选什么？我试过 SQLite、JSON、CSV、AsciiDoc，最后稳定用纯 Markdown。不是因为 Markdown 最简单——它确实简单——而是因为 Markdown 的表达能力和 Agent 的解析能力刚好匹配。

Markdown 有一个常常被低估的特点：它用最少语法表达一个完整的语义层级。一个二级标题##告诉 Agent“这一节是一个独立主题”，一个三级标题###告诉它“这是二级某个主题下的子议题”，一个-列表项告诉它“这里是并列选项”，一个表格告诉它“这里是结构化对照”。这些结构信息，纯文本里的换行和句号完全表达不了，而 JSON 又过度结构化，写起来太啰嗦。人类读 Markdown 顺，Agent 解析 Markdown 也顺，因为规则够简单、格式够统一。

Markdown 存储另一个巨大优势是 Git 友好。纯文本文件用 Git 做版本管理是绝配——diff 清晰、合并方便、历史可溯。我在实践里经常用到这个功能：某个 Agent 把一条错误结论写进了知识库（Agent 也会产出知识的），我git diff看一眼就知道它改了哪里、为什么改，然后git revert就回滚了。这在其他存储格式里都是折磨。

还有可移植性。Markdown 文件不依赖任何特定软件、不依赖数据库版本、不依赖操作系统。从一个工具迁到另一个工具，从一个平台挪到另一个平台，你只需要把文件夹拷走。这点对知识库的长期主义来说太重要了——你积累了几千篇文档，最怕的就是平台倒闭、工具停更、格式私有化。Markdown 从 2004 年诞生到现在，没有任何被淘汰的迹象。

具体到存储规范，我确立了一套自己的规则，实际跑下来很稳：

• 物理路径即分类维度，文件路径就是知识的命名空间
• 每篇文档用 YAML front matter 写元信息（标题、标签、状态、更新时间、负责人）
• 正文按金字塔原理组织，结论前置，细节靠后
• 文档之间用相对链接互相关联，形成可遍历的知识图
• 所有资源文件（图片、附件）用相对路径引用，和 Markdown 文件放同一棵树内
• 每一篇文档体量控制在 200 行以内，超过就拆

这套规范的核心思想是：让 Markdown 文件自己成为知识库的 schema。你不需要额外建数据库表去描述文档之间关系，文件路径的层级和 Markdown 里的链接本身就承载了关系。

4. 实操：从零搭一个本地优先的 Markdown 知识库

接下来进入正题，我把完整的搭建步骤走一遍。这套流程我在 Mac 和 Linux 上都实操过，Windows 用 WSL 也兼容，所有工具都是开源的，不花一分钱。

4.1 设计目录结构与元数据规范

我先给知识库定一个物理目录结构。目录设计的原则是：一眼能看懂每一层放什么，命名长期稳定，避免频繁挪动。我用的结构是这样：

kb/ # 知识库根目录 ├── README.md # 知识库首页，也是 Agent 的入口索引 ├── projects/ # 项目类知识（按项目归档） │ ├── agent-demo/ │ │ ├── overview.md # 项目概览 │ │ ├── design.md # 设计文档 │ │ ├── tasks.md # 任务清单与状态 │ │ └── postmortem/ # 复盘记录 ├── domains/ # 领域知识（按技能方向归档） │ ├── rag/ # RAG 相关 │ ├── agent/ │ └── markdown/ ├── people/ # 团队与联系人知识 ├── resources/ # 通用资源、模板、素材 └── archive/ # 归档，不活跃但不可删

根目录的 README.md 是知识库的大门，我单独给 Agent 写了一份“使用说明”，告诉它知识库的整体布局、各类文档在哪个目录、怎样定位到一篇文档。

每篇文档的 front matter 是这个格式：

--- title: "Agent 原生知识库设计方案" type: design domain: agent status: active tags: [agent, knowledge-base, markdown, local-first] updated: 2025-06-01 owner: tom ---

status字段尤其重要。我给了四个枚举值：active（当前有效）、draft（草稿）、deprecated（已废弃）、review（待复核）。Agent 检索到文档时，第一优先读updated和status，然后才读正文——这能让它自动规避过时内容。

4.2 写一篇“Agent 友好”的 Markdown 文档

目录和元数据定好之后，最大的挑战是：你得让 Markdown 里的知识是 Agent 真正能用起来的形式。我用一个例子说明什么叫 Agent 友好。

我的一篇文档里，如果写这样一段文字：

我们项目目前有一些问题，部分功能延迟，原因是依赖的模块还没有完成，可能需要看看进度。

这种写法人勉强能懂，但 Agent 读起来会飘——没法确定“哪些功能”“哪个依赖”“什么进度”。我把同样的内容改成结构化表达后，效果完全不一样：

## 当前风险：支付模块延迟 **影响范围**：订单创建接口（POST /orders）依赖支付回调回调 **阻塞原因**：依赖 `payment-service` v2.0 的 webhook 通知功能，该功能尚未上线 **当前状态**： - 计划上线时间：2025-06-15 - 阻塞中，无临时绕行方案 - 负责人：@lihua **建议动作**：联系支付团队确认 webhook 上线时间，必要时调整项目排期

Agent 读到这篇文档时，能快速提取出“风险事项”“影响范围”“阻塞原因”“状态字段”“建议动作”，不需要再层层推理。这就叫语义密度高。写知识库文档和写博客最大的区别就在这里——博客讲究起承转合，知识库文档讲究结论在前、要点并列、状态明确。

4.3 给 Agent 装一个能读 Markdown 的检索接口

文件结构和文档质量都就绪了，接下来要让 Agent 用起来。这一步我拆成三个层级，你可以按需选择，不用一上来就做最复杂的。

第一层：直接让 Agent 通过工具调用读取文件系统。比如用 MCP 或者简单的脚本工具，让 Agent 执行find kb/ -name "*.md"+grep -r "关键词" kb/+read_file三步操作。对小型知识库（几百篇以内），这套组合拳已经够用。优点是不用建索引，零维护；缺点是 Agent 需要用“试错”的方式找到内容，有时会漏。

第二层：做一个轻量本地检索脚本，给 Agent 一个搜索入口。我之前写过一个kb_search.sh，本质就是文件名匹配加全文 grep，再加一些优先级排序（匹配标题 > 匹配 tag > 匹配正文）。Agent 调用一次就能拿到最相关的三五篇文档路径，再逐一精读。这一层对千篇级别的文档库很合适。

第三层：本地 Embedding + 向量检索兜底。如果你文档量上了五千篇以上，纯文件系统 grep 就开始力不从心了，语义相关的文档可能因为用词不同而搜不到。这时候可以接一个本地向量化方案——用sentence-transformers跑一个本地模型给文档分块做 embedding，向量存到sqlite-vec或者chroma（本地模式），检索时混合策略：先用关键词粗筛，再用向量做语义召回。但注意：这层只是补刀，主力依然是 Markdown 的结构化信息。

这三层方案可以渐进式升级。我的建议是先从第一层开始，亲身感受 Agent 阅读 Markdown 的方式，理解它需要什么信息，然后完善文档结构，再考虑要不要加向量检索。很多人一上来就做向量库，结果文档没整理好，检索效果差，反过来怪向量方案不行——其实问题是“垃圾进，垃圾出”。

4.4 让 Agent 把知识写回来

Agent 原生知识库和普通知识库最大的区别，是 Agent 不只是知识的消费者，它也可以是知识的生产者。与其让 Agent 只回答“读到的知识”，我允许它在受控范围内把知识写回 Markdown 文件。

比如，Agent 在排查一个问题后，我让它生成一条复盘记录，写入projects/agent-demo/postmortem/2025-06-01-payment-timeout.md，front matter 自动带上type: postmortem、status: active。这样下次有类似问题，Agent 直接就能检索到之前的处理过程。

写回操作的规则要明确，我这里定死了三条铁律：

1. Agent 只能写入archive/或domains/下由系统创建的特定目录，不许覆盖已有文档
2. 写入前必须生成 markdown 结构草稿，经我确认后才落盘
3. 所有 Agent 写入的 document 在 front matter 里标注author: agent-{name}，与人类写的区分开

为什么这么谨慎？因为 Agent 写知识的时候，一样会幻觉，一样会错误归因。但它的产出经过审核后，是对人类输入的有力补充。这套“人类定骨架、Agent 填内容、Git 做审计”的闭环，我用下来是知识库成长效率最高的模式。

4.5 版本管理与同步方案

本地优先不代表单机孤岛。多台设备间如何同步？我的答案是：Git + 自动提交。个人知识库用 GitHub 私有仓库或者自建 Gitea 都行，团队知识库用 GitLab 分支协作，提交策略是两条：

• 电脑端用git commit手动提交 + 写清楚 commit message
• 移动端或者临时修改的场景，用一个auto-commit.sh脚本在文件变更后自动提交，message 自动生成

这里有个我踩过坑后的重要心得：不要让 Agent 直接操作 Git。Agent 的心智跟人不一样，它经常在“调查模式”和“行动模式”之间切换，你让它顺手 commit，它可能把调试日志、临时文件、没写完的半截文档全提交进去。正确做法是给 Agent 提供一个kb_update(file_path, content, reason)工具，它只负责“改文件”和“写 reason”，由外部脚本统一做 Git 提交，reason 写进 commit message。这样 Git 历史永远清晰。

5. 升级：从知识库到 Agent 记忆和技能系统

做好了上面这些，你实际上已经拥有一个可以长期演进的 Agent 原生知识库。再往前走一步，这个知识库还能承担两个更高层的功能：Agent 的记忆系统和技能系统的底座。

先说记忆。很多 Agent 的短期记忆靠上下文窗口，长期记忆靠向量库。但在本地优先的 Markdown 框架下，长期记忆的形态可以落到一个.memory/目录，里面每个 Agent 维护一组 Markdown 文件，记录三件事：

• 用户偏好（比如“用户喜欢结构化输出，每次回答先给结论”）
• 当前任务的中间状态（比如“正在处理订单模块，已完成接口设计，待处理数据库迁移”）
• 过往任务的有效结论（比如“生产环境的数据库连接不要直接测试”）

Agent 在执行任务前先读自己的memory目录，任务结束后更新它。这种“把记忆当文件管理”的方式，比向量记忆库更透明、更可调、也更可控——你可以随时打开文件看一眼 Agent 到底记住了什么，发现错误直接改，这是不透明向量记忆给不了的。

再说技能。Markdown 格式的文档本身就可以构建技能的概念：skills/目录下每个技能是一个文件夹，里面有README.md（说明这个技能的触发条件和执行流程）、examples/（案例）、checks/（质量检查清单）。Agent 通过检索skills/目录来判断自己“现在该调用什么技能”，这比在代码里硬编码技能路由灵活得多。我之前给一个 Agent 加了个“复盘”技能，就是在skills/postmortem/README.md里写清楚了什么情况下触发复盘、按什么框架写复盘文档。Agent 到点自己就去调用了，我没写一行路由代码。

这也回答了一个常见问题：Agent 框架该怎么选，LangChain、Dify、CrewAI 哪个好？我的体会是——框架只是胶水，知识库才是骨架。你用任何框架都能接一个本地 Markdown 知识库，而一旦知识库的结构设计得好，框架的选择反而变成了次要问题。这也是为什么我一直说，先花时间把知识库搭好，比纠结选哪个框架值钱得多。

6. 常见问题与排查技巧实录

实操过程中每个人都会踩到一些坑，我把高频问题按“症状 → 原因 → 解决方案“整理成一张速查表，方便你遇到问题时直接对号入座。

除了表格里的问题，还有三个常见的认知类错误很多人会犯。

第一个错误：把知识库当成临时聊天记录的堆积。有人会把跟 LLM 的对话片段直接复制进 Markdown 存起来，这样出来的文件语义混乱、上下文缺失、几乎无法复用。我的对策是：知识库文档必须“面向未来读者”写，无论是人读还是 Agent 读，你在落盘前先判断一下，这篇文档脱离了对话现场后，读者单凭文本能不能读懂？读不懂就再补充上下文。

第二个错误：结构化过度，写什么都像写论文。有人为了“Agent 友好”，把每条知识都加上极复杂的嵌套列表和引用链接，结果是 Agent 反而迷失在结构里。知识库文档的复杂度应当正好匹配 Agent 的读取能力，一个经验指标是：一篇文档的 Markdown 结构层级不要超过三级（H2 -> H3 -> 列表），超过之后 Agent 的定位准确率明显下降。

第三个错误：忽视文档生命周期管理。知识库不是建完就完事了，它有出生、活跃、过时、退役的过程。我每个季度抽出半天做一次“知识清扫”：把status: deprecated的文档归档到archive/，把长期无访问的domains/文档降到冷存储，把 review 状态的文档逐篇复核。这个习惯让知识库始终保持在“Agent 能信赖”的状态，而不是一个越长越乱的坟场。

你想在 Agent 方向走得更远的话，我最后再分享一个个人体会：知识库花的力气永远不会白费。今天看起来只是“把文档整理好这个简单动作”，明天它就是 Agent 回答问题时准不准、推理时稳不稳、做事时靠不靠谱的分水岭。纯 Markdown 本地知识库看起来一点不性感，没有界面、没有算法、没有推荐，但它恰恰是这轮 Agent 应用浪潮里，最朴素也最扎实的一块压舱石。你在本地把这一套跑通了，后面接任何 Agent 框架、任何模型，都会比别人轻松一大截。