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

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

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

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

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

前
后
原文档(Powered by Gitbook)
现文档(Powered by Mintlify)

AI 时代下的知识服务

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

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

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

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

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

传统检索:

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

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

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

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

而在 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
内容展示
文档代码行高亮
✅
✅
✅
✅
✅
✅

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

⭐️ 文…
— 以上为试看内容(约 40%),开通会员后阅读全文 —