Dify 技术文档工程实践:如何构建面向 AI 时代的知识系统?


如果文档是产品的一部分,你希望获得怎样的阅读体验?文档又应该以何种姿态面向新读者——即无所不在的 LLM?

Dify 技术文档工程实践:如何构建面向 AI 时代的知识系统?

大家好,我是 Allen,来自 dify 的技术文档工程师。

从 2025 年 4 月开始,我主导并完成了 Dify 帮助文档框架的一次全量迁移工程——从 Gitbook 到 Mintlify。完成从调研选型、Demo 实测、样式兼容、链接重构到最终上线的全过程。这不只是技术栈的替换,更是一次面向 AI 时代内容服务的基础设施重构。

以下是迁移前后对比。乍一看好像没啥区别,这一切值得吗?

Dify 技术文档工程实践:如何构建面向 AI 时代的知识系统?
原文档(Powered by Gitbook)
Dify 技术文档工程实践:如何构建面向 AI 时代的知识系统?
现文档(Powered by Mintlify)

AI 时代下的知识服务

要回答这件事是否值得,取决于你是否愿意专门为 AI 提供一套适应它们阅读习惯的文档。如果单独抛开迁移这件事本身而言,而是升华到行为背后的动机,则必须回答关键问题:面向 AI 时代的内容的知识体系,应该如何重新组织信息?

AI 革命爆发以前,所有的软件文档皆是为人类设计的。排版布局需要考虑美观吸睛、阅读友好。信息要分层递进,逐步深入。拿常规的 SEO 而言,想要让搜索引擎精准的在茫茫内容中找到你的内容,你需要在 HTML、元数据或内容地图上下足功夫。

哪怕抛开 SEO 要素,面向人类的文档通常要求设计简洁优美,布局清晰;而对于 LLM 来说,外在都是表象,它需要的是足够长的上下文。不求精巧的排版,但求内容的充分详实。

不同时代下的信息检索路径

我们不妨假想一个场景,用户在什么情况下需要文档?很显然,TA 遇到了问题。过往的信息检索路径可能是:

传统检索:

输入遇到的问题 / 输入产品名称 + 问题关键词 → 由搜索引擎挑选排名权重靠前的网站中的内容 → 推荐合适的解决方案

用户行为可被抽象为三种路径:

  1. 通过搜索引擎查找内容
  2. 浏览文档层次结构
  3. 使用文档搜索功能

Stripe 文档 (https://docs.stripe.com/)可谓是在这条路上达成了登峰造极般的程度。团内任意角色的用户,都可以各自在文档内快速找到所需信息。文档甚至会为已登录的用户,自动生成专属于用户团队的测试代码。

Dify 技术文档工程实践:如何构建面向 AI 时代的知识系统?

而在 LLM 互动时代,问题的解决路径变为了:

询问 LLM → 由 LLM 给出推荐方案 → 用户提问反馈 → LLM 给出详细的手把手教学

用户无需浏览各个部分或搜索特定页面,而是转向 LLM 寻求即时答案,而不必自行将来自不同页面的信息拼凑在一起来获取结论。

LLM 所带来的改变

毫无疑问,大型语言模型 (LLM) 正在改变搜索引擎优化 (SEO)。这同时还催生出了一个新领域:生成式引擎优化 (GEO)。有研究预测,来自 LLM 的搜索流量将从 2024 年占所有搜索量的 0.25% 飙升至 2025 年底的 10%。

研究链接:AI SEO Study 2024(https://previsible.io/seo-strategy/ai-seo-study-2024/)

对于一切围绕产品的使用而设计的技术文档而言,这样的趋势将颠覆客户查找信息并最终通过产品获得成功的方式。

LLM 会优先考虑提供什么样的内容?当然是它最了解和熟悉的方法,亦或是互联网上大家通常采取的策略。

它俨然已成为最大的内容消费者,疯狂地吞噬互联网上的一切内容。甚至随着 Agent 工具的出现,它终将长出手和脚,基于它所掌握的信息,代替人类完成对物理世界的交互。

而在这场变革中,技术文档工程师(Technical Writer)所输出的内容,将显著影响 LLM 对于目标产品的掌握。

若要真正做到对 LLM 友好,技术文档需具备一个关键能力:自动生成 llm.txt 文件。

llms.txt 是一个纯 Markdown 文件,它以简洁的方式概括了您最重要的内容,并以易于 LLM 阅读的方式组织结构,避免了 HTML、JavaScript 或广告的杂乱。

除了 LLM 阅读友好,作为一个开发者工具文档,本就应该确保开发者用户的交互体验。最常见的功能便是 API 文档,最好支持所见即所得的在线调试体验。至此,整套升级行动所要实现的目标也就此确立:

  1. LLM 爬取友好

    全面兼容 GMO,让产品或解决方案更容易出现在 AI 的自然语言回答中,从搜索引擎到智能助手,全面提升可见性。

  2. 具备 API 文档

    提供完整且清晰的 API 文档,支持在线调试与示例调用,帮助开发者快速理解接入方式,显著提升人类程序员的开发效率与使用意愿。

  3. 支持 AI 文档对话

    支持基于文档的 AI 对话,让开发者或用户可以通过自然语言提问的方式获取接口使用说明、集成指南或排障建议,减少重复咨询,提升支持效率与产品好感度。

先谋而后动

1. 明确问题,弃用 Gitbook

此前 Dify 文档使用的框架为 Gitbook,它见证了第一版的文档和整个项目的开源。但随着时间的演进,它逐渐暴露出了非常多底层的问题。来看看我自接手文档写作以来所积攒的问题列表吧(否则我也不会这么想要换掉它):

序号
问题描述
问题类型
严重等级
1
添加超链接时经常出现异常,有时页面卡死,无法添加或删除内容
功能缺陷
2
多人共同编辑文档时出现异常白屏
功能缺陷
3
官方客服响应体验差,提交反馈后没有出现填写反馈的对话框
用户体验
4
目录结构过于垂直,阅读体验很糟糕,无法一眼看出层级关系
用户体验
5
评论时,第一次评论无法输入文字,需再点击一次评论框才能评论
功能缺陷
6
API 文档渲染异常
功能缺陷
7
自动添加多余字符,且有冲突内容需要自行排查,不提供自动排查功能
功能缺陷
8
会自动修改已创建的文档内容,导致原先的文档失效
功能缺陷
9
错误的数据应用,没有引用 GitHub 链接但自动替换为了 GitHub 链接
功能缺陷
10
不直观的隐藏更改
用户体验
11
前端显示预期不一致,代码仓库里已有正常内容,但英文前端显示异常(中日语言内容无异常)
功能缺陷
12
没有完整有效的预览地址,需要在 GitBook 内部生成,跨部门内容预览体验不畅
用户体验




根本原因在于该平台的产品定位面向不具备编程能力的业务人员,旨在提供技术写作与协作能力,因此大部分操作依赖图形化界面完成。尽管平台支持通过 IDE 拉取代码进行文档维护,但由于本地环境无法预览渲染效果,使用体验受到较大限制。

Gitbook 并不是一个 Doc as Code 的产品。

此外,平台内置编辑器的渲染效果与最终发布页面存在明显差异,实际呈现效果与预期之间常出现落差,技术实现上的不一致性为使用者带来了诸多困扰。

在处理外部用户投稿内容时也面临类似问题:部分样式或渲染代码无法实现实时预览,上线结果往往无法预测,类似”开盲盒”的体验。考虑到当前团队已明确新的发展方向,首要决策即为停止使用 GitBook 平台,寻找新的替代

2. 围绕目标,充分调研

我始终坚持这样一种观点:文档是产品的一部分。正因如此,任何对文档系统的重大调整,必须在充分思考与权衡之后再做决策,尤其是在迈向 AI 化转型的关键阶段。

据不完全统计,当时 Dify 的文档总量已超过 600 篇,且内部嵌套的引用链接繁多、结构复杂。如果将整个文档系统比作一座建筑,这座新”大楼”的设计寿命至少应为三年以上,甚至可能在较长时间内保持稳定。因此,新的文档框架不仅要延续既有的良好体验,还需具备良好的可维护性与未来可持续扩展的能力。

为此,我对市面上的主流技术文档框架进行了调研与实际使用,并整理成对比表格,供团队参考,也希望对有类似需求的朋友有所帮助。

如果微信表格渲染有异常,请在浏览器打开原文链接:https://docs.pflm.net/zh-hans/insights/dify-docs-restructure

功能分类
功能项
GitBook
Mintlify
Starlight
Docusaurus
Nextra
Gatsbyjs
内容展示
文档代码行高亮

⭐️ 本地文档预览
内容管理
⭐️ 文档版本控制
✅ 需配合插件

⭐️ 文档多语言
✅ using i18n

⭐️ 内容重定向
✅ for language only with middleware
内容输出
导出为 PDF
✅ 但需要更高级别的付费
✅ 通过插件支持
✅ 通过插件支持

⭐️ API 文档
✅ 但渲染异常有 Bug
✅ 需配合 RapidAPI 实施
✅ 需配合插件
✅ Can customize different kind of UI with JS

MCP Server
✅ 通过插件支持
部署与运维
本地部署
❌ 仅提供 SaaS 服务
✅ 官方提供部署 不支持手动打包为静态网页
✅ with Next.js
用户交互与编辑
文档可视化编辑后台
❌ 纯代码编辑
❌ 纯代码编辑

自定义能力支持
✅ 可更改范围受限
协作与管理
自动显示文档作者
✅ 需二次开发

文档页的 GitHub 地址关联
✅ 需二次开发
✅ 需二次开发
开发与集成
开发 SDK
商业与支持
费用
免费计划 / 79 美元起多人协作
免费计划/ Pro 计划 150 美元月
开源项目
开源项目
开源项目
开源项目

官方技术支持
参考信息
谁在用?
NordVPN、Raycast、Make 等 完整客户名单
Cursor、Anthropic、Perplexity、Zapier 了解更多:完整客户名单
Astro项目
各行各业 完整客户名单
Open-source project
各行各业

在深入试用和比较之后,我将候选框架聚焦于两款:Mintlify 与 Docusaurus

  • Mintlify 在视觉美观性与 API 文档自动生成方面表现成熟,默认样式即可满足大部分展示需求,是一款专注于商业化文档体验的框架。
Dify 技术文档工程实践:如何构建面向 AI 时代的知识系统?
  • Docusaurus 作为开源项目,在功能的可扩展性上略逊一筹。但 API 文档集成也需依赖额外的转换工具,虽然其开源生态活跃、可扩展性强,但其实更适合具备 React 前端开发能力的团队。
Dify 技术文档工程实践:如何构建面向 AI 时代的知识系统?

最终,综合考虑后期维护的便利性、开箱即用的表现力,以及背后团队对 AI 能力的整合与投入,我选择了 Mintlify 作为新的文档系统解决方案。同时也安利 Mintlify 的 Blog,他们输出了非常多面向 AI 时代文档建设的洞察。

Dify 技术文档工程实践:如何构建面向 AI 时代的知识系统?

行动

1. 熟悉框架,小步迭代

在确定使用 Mintlify 作为新一代文档框架后,我第一时间搭建了一个 Demo 网站,供内部技术写作团队进行实际体验。同时,我也主动组织了多轮沟通与宣讲,帮助团队充分理解新框架的优势与使用方式。通过持续的沟通与反馈收集,最终逐步赢得了团队其他成员的认同与支持。

整个迁移过程对我而言也是一次极具价值的学习经历。我几乎完整阅读并实践了 Mintlify 的官方文档(事实证明,他们在技术写作领域非常专业),对其支持的功能、可用的组件样式、内容组织方式等有了全面的掌握。

在实际使用过程中,最显著的区别之一在于:Mintlify 并未采用传统技术文档中常见的 .md(Markdown)格式,而是基于 .mdx 文件结构。这一格式结合了 Markdown 与 JSX 的能力,使文档在保持简洁语法的同时,也具备了更强的交互与组件调用能力。

但放在当下 AI 技术快速发展的背景下,内容格式的迁移与转换已不再是技术壁垒,反而是可以快速自动化解决的小问题。因此,我更看重的是其结构的未来可扩展性与智能工具的融合潜力。

Dify 技术文档工程实践:如何构建面向 AI 时代的知识系统?
原 Gitbook 语法结构
Dify 技术文档工程实践:如何构建面向 AI 时代的知识系统?
Mintlify 语法结构

2. 明确问题,逐个攻破

随着我对两个文档框架的深入对比与实践,逐步识别出几个历史遗留问题和核心问题。如果这些问题得到有效解决,其它次要问题也将随之迎刃而解。

问题 1:图片处理机制不清晰,影响长期可维护性

在原有的文档体系中,图片并未采用统一的在线图床方案进行管理。一方面,随着文档体量不断扩大,仓库体积也随之膨胀;另一方面,图片的命名方式和存储路径缺乏规范,管理混乱。现实中,很难指望每位写作者在上传图片时能做到手动重命名、规划路径、统一管理。

此外,GitBook 采用私有资源托管,查询后发现并未启用 CDN 服务。这导致在上传或访问图片时,尤其是在不同地区网络条件下,出现明显的加载延迟和不稳定性,进一步影响用户体验。

解决办法: 为解决上述问题,我采用 Pico + S3 存储 的方式自建在线图床,实现图片上传的自动化处理与统一索引管理:

  • 自动命名与归档:上传图片时系统自动生成规范化命名,避免重名与路径冲突
  • 图床独立部署:图片资源脱离主代码仓库存储,减轻 Git 压力
  • CDN 加速分发:结合 S3 及全球 CDN 服务,实现跨地域快速加载
  • 上传体验优化:写作者可”无脑上传”,后端自动完成分类与引用路径的整理

目前该方案已在内部启用,我顺带贡献了一篇面向内部的图床使用指南。

Dify 技术文档工程实践:如何构建面向 AI 时代的知识系统?

在引入图床方案之后,新上传图片的处理方式已有清晰方案,通过在线图床与自动命名机制,实现了流畅且可维护的上传体验。然而,对于大量历史文档中引用的本地图片,仍然存在迁移难题:这些图片分布零散、命名混乱,且手动替换成本极高。

我让实习生帮忙写了一套自动化处理脚本,实测效果也很不错。通过 Vibe Coding,我们用很少的人力就解决了可能是整个迁移工作中最繁琐的任务——本地图片统一上传至图床。

问题 2:语法格式不统一,易出错且缺乏可维护性

文档的语法格式,通常指的是页面中用于展示视觉提示的内容样式,例如高亮块、提示框、警告框等。这类样式在不同框架中通常通过特定语法标记来实现,写作者只需在 Markdown 中插入对应代码块,即可获得对应的页面效果。

Dify 技术文档工程实践:如何构建面向 AI 时代的知识系统?

但在实际使用过程中,我始终无法理解 GitBook 对这部分的设计逻辑。它所采用的语法不仅不直观,甚至可以说是”匪夷所思”。以下是一个简单的语法对比示例(目标是实现”信息提示”效果):

  1. ## Dify
  2. {% hint style="info"%}
  3. The name Dify comes from**D****I****F**or**Y**ou.
  4. {% endhint %}
  1. ## Dify
  2. <Info>
  3. The name Dify comes from**D****I****F**or**Y**ou.
  4. </Info>

可以看出,GitBook 采用了 {%%} 这一特殊语法标记,这种写法不仅可读性差,而且在大多数 Markdown 编辑器或网页渲染环境中容易引发错误。例如 { 和 % 是许多前端框架中保留的特殊符号,极易导致页面渲染失败或结构错乱。

解决办法:语法格式交由 AI 转换,构建自动化工具链

为解决这一问题,我提出了一个简单而高效的方案:将所有常用样式语法的对应关系梳理出来,并作为上下文注入到 Prompt 中,由 AI 自动完成文档语法格式的转换。

这对于 Dify 应用而言简直是小 Case,我选择使用最基础的 Chat 类型应用进行搭建,自动转换文档内容和结构。该工具支持:

  • 自动识别 GitBook 中的特殊语法
  • 根据预设规则转换为 Mintlify 所支持的 MDX 格式
  • 统一样式语义,避免渲染错误

经过实战检验,该工具在迁移过程中取得了良好效果,能够有效规避格式不统一带来的潜在问题。效率直接拉满。

MD 转 MDX 助手体验地址:https://cloud.dify.ai/app/4fd52bb9-ab93-40f1-8bb0-6c76bd336206/configuration

Dify 技术文档工程实践:如何构建面向 AI 时代的知识系统?

问题 3:文档内超链接引用结构复杂,需统一管理

在大型文档系统中,文档之间存在大量交叉引用是极为常见的现象。例如,A 文档中嵌套引用 B 文档的链接,以实现内容跳转与结构关联。然而在旧有系统中,这类链接格式极不统一,既有完整的线上链接(如 https://example.com/xxx),也有文档仓库中的相对路径引用(如 ../b.md)。不同写作者的习惯差异,加之缺乏系统性规范,导致迁移过程中链接处理变得尤为复杂、易错且繁琐。

面对这一问题,我继续采用 Vibe Coding 的方法论,并结合人类监督机制,设计了一套高效可控的处理流程,用 Python 脚本代替手动操作:

  1. 自动识别文档中的所有链接引用;
  2. 将引用目标在页面中高亮展示,并智能推荐替换后的链接路径;
  3. 由人工快速点击确认推荐是否正确;
  4. 确认后统一执行替换操作。

该流程既保留了 AI 的高效识别能力,又通过人工确认环节避免错误替换,极大缓解了需要逐个文档比对、核实的工作负担。

3. 最终上线:确保平稳过渡

在解决完所有显性问题后,我正式敲定了新文档框架的上线日期。在此之前,我对每一个页面的跳转路径与访问情况进行了逐一人工排查,确保用户在迁移后仍可顺利浏览各类内容。

值得一提的是,文档重定向问题同样是一个不可忽视的环节。由于 GitBook 与 Mintlify 所采用的文档结构存在较大差异,URL 路径的调整不可避免。为此,我一度考虑通过域名级的策略,在上线时引入 A/B 灰度测试,以实现平滑过渡与风险控制。然而,在尝试配置 Cloudflare 规则过程中遇到了一些技术阻碍,评估后认为对一个文档项目而言,引入过多部署复杂度并不划算,最终决定简化方案,回归核心目标:稳定、可访问、不影响用户体验

完成所有准备工作后,我联系了运维团队进行正式的流量切换。上线当天,我独自在会议室中不停刷新各个关键页面,实时监控迁移效果。幸运的是,没有翻车,甚至大多数用户都没有察觉到文档系统已完成更替。由于两套系统在视觉风格上保持了一定程度的一致性,再加上旧链接的跳转逻辑处理得当,整个迁移过程实现了”平滑切换,零感知”。

基建完成后,API 文档部分也在 DevRel 同事的协助下顺利上线,为整个文档体系的结构化建设补上了关键一环。

Dify 技术文档工程实践:如何构建面向 AI 时代的知识系统?

为进一步提升用户反馈的响应链路,文档也部署了辅助脚本,实现对所有文档页面的自动化反馈入口嵌入。该脚本会在每个页面底部统一添加反馈模块,方便用户对内容进行评价或提出建议。

这一机制不仅提升了用户参与度,也为后续的文档迭代与优化提供了数据基础,形成了“内容发布—用户反馈—内容更新”的正向循环。

Dify 技术文档工程实践:如何构建面向 AI 时代的知识系统?

文档的背后,是对阅读体验的全局掌控

这场迁移不仅是一项技术挑战,更是一种角色认知的重塑。

在完成文档系统迁移与结构优化后,我已尽可能完成所有能做的工作。而 Mintlify 功能的快速迭代,也进一步验证了我的判断:这是一个有品位、有追求的产品

2025 年 3 月,MCP 成为技术社区的热门议题。Mintlify 第一时间支持了文档的 MCP 化功能。我也迅速编写了相关指南,帮助我们的用户部署专属的文档问答服务:https://docs.dify.ai/zh-hans/learn-more/extended-reading/dify-docs-mcp

实际测试中,文档问答的效果令人惊喜,真正实现了”在文档中与 AI 对话”的体验。

Dify 技术文档工程实践:如何构建面向 AI 时代的知识系统?

MCP 功能发布不久后,Mintlify 官方也上线了内置的 AI 对话功能。无论是查阅复杂内容,还是理解长段代码,用户都可以直接在页面内与 AI 进行交互,获取实时帮助。这一能力极大提升了技术文档的可读性与用户自助解决问题的效率。

一键全文问 AI
实时文档对话功能
Dify 技术文档工程实践:如何构建面向 AI 时代的知识系统?
Dify 技术文档工程实践:如何构建面向 AI 时代的知识系统?

在那个瞬间,我突然意识到:这正是一场两个 PLG(Product-Led Growth)产品之间的梦幻联动

Dify 专注于构建生产级 Agentic 应用搭建平台,Mintlify 深耕技术文档领域。双方在各自擅长的方向上付出了充足的认知与打磨,无需反复营销”卖点输出”,就能在交汇点上自然地为用户带来真实价值。

如今,Mintlify 已成为 Claude、Cursor、Perplexity 等主流 AI 厂商的文档首选框架,它的演进路径正在印证技术产品应有的”好看、好用、可成长”。

Dify 技术文档工程实践:如何构建面向 AI 时代的知识系统?

而我也终于可以自豪地说:作为一个技术文档工程师,所能做的远不止是写好文档。TA 的职责,更应是文档产品的负责人,有责任为用户提供可信的内容、流畅的阅读体验与可持续的使用路径。

在信息密度与时间成本都极高的今天,如果每个人都能在自己的力所能及处做到极致,整个系统、乃至世界,本就会自然向好。

参考资料

How Generative Engine Optimization is Reshaping Docs 

https://mintlify.com/blog/how-geo-is-reshaping-docs

RAG技术前沿技术新闻资讯

Chonkie:开源、轻量、极速的 RAG 分块神器 🦛

2025-7-30 17:34:06

RAG技术前沿技术新闻资讯

AI问答系统崩溃?这篇RAG优化实战指南,教你解决90%的检索问题

2025-7-30 19:18:25

0 条回复 A文章作者 M管理员
    暂无讨论,说说你的看法吧
购物车
优惠劵
搜索