1. 项目概述Dify 文档仓库的维护与贡献指南如果你正在使用或关注 Dify 这个开源的 AI 应用开发平台那么你一定接触过它的官方文档。这份文档是项目成功的关键一环它清晰、准确并且支持多语言。你可能不知道的是这份文档本身也是一个开源项目托管在 GitHub 的langgenius/dify-docs仓库里。这意味着任何开发者、技术写手甚至热心的用户都可以参与到这份文档的完善工作中来。今天我就以一个深度参与过多个开源文档项目维护者的视角为你彻底拆解这个文档仓库的结构、贡献流程以及背后的设计哲学。无论你是想提交一个简单的错别字修正还是计划撰写一篇完整的功能指南这篇文章都将是你最实用的“地图”。这个仓库的核心价值在于它不仅仅是一堆 Markdown 文件的集合更是一套经过精心设计的、高度自动化的文档工程体系。它解决了开源项目文档维护中最头疼的几个问题多语言同步的负担、内容格式的统一、以及贡献者体验的优化。理解这套体系不仅能让你更高效地为 Dify 做贡献其背后的思路和工具链对于你维护自己的任何技术文档项目都有着极高的参考价值。接下来我们就从仓库结构开始一步步深入。1.1 核心设计源语言与自动翻译的分离打开dify-docs仓库你首先会注意到它的目录结构非常清晰dify-docs/ ├── en/ # 英文文档源语言 ├── zh/ # 中文翻译自动生成 ├── ja/ # 日文翻译自动生成 ├── writing-guides/ # 写作与格式指南 ├── .claude/skills/ # AI 辅助写作技能 ├── tools/translate/ # 翻译流水线工具 ├── docs.json # 导航结构定义文件这个结构背后是一个至关重要的原则所有内容的修改只应在en/目录下进行。zh/中文和ja/日文目录中的内容是由自动化翻译流水线从英文源文件同步生成的。这是一个非常聪明且高效的设计它从根本上避免了多语言版本内容不同步的“幽灵页面”问题。注意这里有一个特例文件en/self-host/configuration/environments.mdx它的翻译需要手动处理。这是因为环境配置涉及大量技术术语和特定上下文机器翻译容易出错必须由熟悉该领域的人进行人工校对。这提醒我们自动化虽好但对于关键或易混淆的内容人工干预仍是保证质量的必要环节。为什么选择英文作为源语言这并非“英语中心主义”而是出于工程实践的考量。首先Dify 的核心开发者和最初的社区用户多以英语交流英文文档是迭代最快、最准确的。其次目前主流的机器翻译引擎如 DeepL、Google Translate对英译中的质量相对较高且稳定。将英文作为单一事实来源Single Source of Truth可以最大限度地保证所有语言版本在技术准确性上的一致性。作为贡献者你只需要专注于写好英文内容语言障碍由工具链来克服。docs.json文件的作用这个文件定义了文档网站的导航菜单结构。当你新增一个页面时必须在docs.json的英文部分添加对应的条目。翻译流水线会识别这个变化并自动在中文和日文导航中生成对应的条目。这意味着你几乎不需要操心多语言导航的维护工作。1.2 贡献流程全解析从 Fork 到 Merge为这个仓库做贡献遵循标准的 GitHub 开源协作流程但有一些细节值得特别注意。整个流程可以概括为Fork - Clone - 修改 - 提交 - 发起 Pull Request (PR) - 等待审核合并。第一步Fork 与克隆这步很常规在 GitHub 上点击 Fork 按钮将仓库复制到你的账号下。然后使用git clone命令克隆到你本地。我建议在克隆后立即添加上游远程仓库方便后续同步主仓库的更新git remote add upstream https://github.com/langgenius/dify-docs.git第二步创建特性分支永远不要在main分支上直接修改。创建一个描述性的新分支例如git checkout -b docs/add-workflow-tutorial。清晰的分支名能让维护者一眼就明白你的 PR 意图。第三步进行修改并本地预览这是核心步骤。所有内容修改都在en/目录下进行。Dify 文档使用 MDX 格式Markdown 的扩展允许嵌入 JSX 组件每个文件顶部必须有 YAML Frontmatter 来定义元数据例如--- title: Building Your First AI Agent description: A step-by-step tutorial to create an interactive AI agent using Difys workflow canvas. --- 正文内容从这里开始...title和description必须填写它们会用于网页的标题和 SEO 描述。修改完成后强烈建议在本地预览效果。仓库使用 Mintlify 作为文档生成器。你需要先全局安装 Mintlifynpm i -g mintlify然后在仓库根目录运行mintlify dev。这会启动一个本地开发服务器通常在http://localhost:3000你可以实时查看渲染效果检查链接、图片和格式是否正确。第四步提交更改与 PR 规范提交代码时信息格式有严格要求这体现了项目的专业性。格式为{type}: {description}。type必须是预定义的类型如docs,fix,feat等下文有详细表格。description使用小写、祈使语气动词开头不超过72个字符句末不加点。 例如docs: add advanced RAG configuration guide或fix: correct typo in quickstart.如果更改的原因不明显需要在提交信息中空一行后补充正文进行解释。例如fix: switch API response mode to streaming Blocking mode was causing HTTP 504 timeouts on large pages when generating documentation previews.完成本地提交后将分支推送到你的 Fork 仓库然后在 GitHub 界面向主仓库的main分支发起 Pull Request。第五步PR 审核与自动翻译维护者会审核你的 PR。审核的重点通常是技术准确性、内容清晰度、是否符合格式指南。一旦 PR 被批准合并项目的自动化流水线就会启动。它会将en/目录下的变更通过机器翻译自动同步到zh/和ja/目录并生成对应的翻译提交。整个过程无需你手动处理多语言问题。2. 内容创作与格式规范详解写好技术文档是一门艺术更是一门科学。dify-docs仓库通过一系列严格的指南和自动化工具试图将这门科学标准化同时为艺术的发挥留出空间。writing-guides/目录就是这份“写作宪法”的所在地。2.1 写作指南的核心要义writing-guides/目录下通常包含几个关键文件style-guide.md定义了行文风格。例如是使用“你”还是“用户”技术术语的首字母大小写代码示例的规范它确保了所有文档读起来像同一个人写的风格统一。formatting-guide.md这是格式的“法律条文”。它详细规定了标题层级的用法严禁跳级使用如从 H2 直接到 H4、代码块的标注语言、表格的样式、警告或提示框的写法等。在提交 PR 前你的内容必须通过这份指南的检验。glossary.md术语表。它定义了 Dify 生态中专有名词的标准译法和解释比如“Workflow”统一译为“工作流”“Knowledge Base”统一译为“知识库”。这是保证翻译一致性的基石尤其是对于tools/translate/中的自动化流程至关重要。实操心得很多贡献者会忽略这些指南直接凭感觉写。这是一个大坑。我曾经提交过一篇关于“模型推理参数”的文档自认为写得很清楚但被维护者打回原因就是文中“temperature”参数有时首字母大写有时小写并且没有链接到术语表进行统一解释。花10分钟通读一遍指南能为你节省数小时的返工时间。2.2 利用 AI 辅助提升效率与质量这个仓库最前沿的一点是它官方鼓励并集成了 AI 辅助写作。在.claude/skills/目录下预置了针对 Claude Code 编辑器的技能Skills。这些技能本质上是精心设计的提示词Prompts能指导 AI 如何帮助你撰写特定类型的文档。例如可能有一个“撰写操作指南”的技能当你激活它后AI 会引导你按照“概述 - 前置条件 - 分步步骤 - 预期结果 - 故障排查”的结构来组织内容。还有一个“检查格式”的技能它可以自动将你的草稿与formatting-guide.md对照指出不符合规范的地方。如何使用这些技能如果你使用 Claude Code 编辑器在克隆仓库并打开项目后这些技能通常会自动加载到编辑器的技能面板中。你可以选择对应的技能然后 AI 就会进入“角色”基于该技能的设定来协助你。即使你不使用 Claude Code阅读这些技能文件本身也是学习如何结构化技术文档的绝佳材料。注意事项AI 是强大的助手但不是作者。它生成的代码示例可能过时技术描述可能不够精确。你必须以领域专家的身份对 AI 产出进行严格的审查和修正。永远不要直接提交 AI 生成的、未经你深度校验的内容。2.3 提交类型Commit Type的精准运用提交信息的type字段不是随便填的它帮助维护者快速分类和审核变更。下表是完整的使用指南类型使用场景示例docs最常用。新增或更新任何文档内容。docs: add tutorial for API deploymentfix修正错别字、错误链接、错误的技术描述。fix: correct the default port in docker-compose.yml examplefeat非内容性的增强。如为文档站添加搜索功能、新增交互式组件。feat: add dark mode toggle to code snippetsrefactor重构内容结构而不改变实质信息。如重组章节顺序、拆分过长的页面。refactor: move advanced configuration to a separate pagetranslate手动更新翻译内容通常只用于那个特例文件或优化机器翻译。translate: refine Chinese translation for environments.mdxstyle仅修改格式如调整缩进、修正标题层级、统一标点。style: format all tables to use consistent alignmentchore更新依赖、配置文件等杂项。如升级 Mintlify 版本。chore: update mintlify to version 4.1.0一个常见的误区当你既修改了内容又修正了几个错别字时应该用docs还是fix原则是看主要目的。如果你的主要贡献是新增了大量内容附带修正了旧文中的小错误那么使用docs。如果这个 PR 纯粹是为了修正一系列错误则使用fix。保持 PR 的单一职责One topic per PR能让审核更高效。3. 本地开发与自动化工具链实战想要高效贡献光知道规则不够还得把环境玩转。本地开发环境的顺畅程度直接决定了你的贡献体验和效率。3.1 Mintlify 本地预览的细节与排错运行mintlify dev看似简单但有些细节能让你事半功倍。端口占用问题默认的 3000 端口可能被占用。你可以指定端口运行mintlify dev -p 8080。热重载Mintlify 支持热重载。修改en/目录下的.mdx文件并保存后浏览器中的预览页面会在几秒内自动刷新。但修改docs.json导航文件后通常需要重启服务才能生效。检查构建错误如果页面无法正常渲染首先查看终端运行mintlify dev的命令行窗口是否有红色的错误信息。常见的错误包括Frontmatter 格式错误如缺少结束的---、Markdown 语法错误、或引用了不存在的图片路径。一个真实踩坑案例有一次我写一篇教程里面包含一个复杂的代码片段我用了三个反引号加python标注。但预览时代码高亮始终不对。排查了半天才发现我在代码片段里某行不小心又写了三个反引号作为字符串内容的一部分这破坏了 Markdown 的解析。解决方案是在代码块内部的反引号前加反斜杠转义或者使用四个反引号来包裹整个代码块。这类问题只能在本地预览中发现如果直接提交会在 CI/CD 检查中失败。3.2 预提交钩子Pre-commit Hook的配置与原理仓库中有一个非常实用的自动化配置预提交钩子。通过运行git config core.hooksPath .githooks命令你将 Git 的钩子目录指向项目自带的.githooks文件夹。这个钩子具体做了什么它很可能关联着一个脚本当你执行git commit时这个脚本会自动运行。在dify-docs的上下文中这个钩子的一个关键作用可能是自动更新术语数据库。当你修改了writing-guides/glossary.md文件并尝试提交时钩子脚本会被触发它可能运行tools/translate/下的某个脚本将最新的术语表同步到翻译流水线所需的数据库中确保后续的自动翻译能使用最新的术语。如何启用只需在仓库根目录执行一次上述命令即可。之后你的每次提交都会自动经过这个钩子的处理。如果脚本执行失败例如术语表格式错误提交会被中止你就能在提交前发现问题而不是等到 CI 环节才报错。注意事项如果你之前为 Git 配置过其他全局钩子这个命令会覆盖它。如果你需要同时使用多个项目的钩子可能需要更复杂的方案比如使用像pre-commit一个管理 Git 钩子的框架这样的工具。但对于专注贡献 Dify 文档来说直接使用项目提供的钩子是最简单直接的方式。3.3 翻译流水线浅析虽然作为普通贡献者无需直接操作翻译流水线但了解其工作原理有助于你写出更“翻译友好”的文档。tools/translate/目录下存放着实现自动化翻译的脚本。其工作流程大致如下监听变更当main分支有新的合并通常是包含en/目录更改的 PRCI/CD 流水线如 GitHub Actions被触发。提取文本脚本会解析en/目录下变更的.mdx文件提取出需要翻译的文本块通常忽略代码块和 Frontmatter 中的部分字段。调用翻译 API将提取的文本发送至机器翻译服务如 DeepL API。应用翻译将翻译结果填充回zh/和ja/目录下对应的文件结构中。提交回仓库自动创建两个新的提交例如[Bot] Translate content into Chinese和[Bot] Translate content into Japanese并推送到仓库。这对你的写作意味着什么避免歧义句子机器翻译对复杂长句、带有大量代词的句子处理不好。尽量写短句主语明确。标记不需翻译的内容对于品牌名、专有名词如“Dify”、“GPT-4”、代码变量名确保它们在上下文中清晰可辨机器翻译通常会识别并保留它们。善用术语表你在glossary.md中定义的术语会成为翻译引擎的“记忆”确保关键术语在所有文档中翻译一致。4. 高质量贡献的进阶技巧与常见问题掌握了基本操作后如何让你的贡献脱颖而出更容易被维护者接受这里分享一些从实战中总结的进阶技巧和常见问题的解决方法。4.1 如何撰写一篇优秀的操作指南Tutorial新增一篇完整的操作指南是价值很高的贡献。以下是一个经过验证的结构模板你可以直接套用目标与前置条件开篇明义告诉读者学完这篇指南能做什么例如“部署一个带有自定义知识库的客服机器人”。并清晰列出所有前提如需要的 Dify 版本、必要的 API 密钥、已有的云端资源等。分步详解将过程分解为逻辑清晰的步骤。每个步骤以一个行动动词开头如“创建应用”、“配置模型”、“上传文档”。在步骤中不仅要写“怎么做”更要解释“为什么这么做”。例如“这里我们选择 GPT-4 模型因为它对长上下文的理解更好适合处理知识库问答。”代码与配置示例提供可直接复制的代码块、配置片段。对于关键参数以注释或表格形式说明其含义和推荐值。# docker-compose.yml 片段 services: dify-api: image: langgenius/dify-api:latest environment: - OPENAI_API_KEYsk-... # 你的 OpenAI API 密钥这是必填项 - MODEL_PROVIDERopenai # 指定模型提供商验证结果告诉读者如何验证步骤是否成功。例如“完成上述配置后访问http://localhost:3000你应该能看到 Dify 的登录界面。”故障排查预见新手可能遇到的问题并给出解决方案。用表格形式呈现一目了然。问题现象可能原因解决方案访问localhost:3000报连接错误Docker 容器未成功启动运行docker-compose logs查看具体错误日志知识库文件上传后处理失败文件格式不支持或过大确认文件为 .txt, .pdf, .docx 格式且大小小于 50MB后续步骤与参考提供延伸阅读的链接如相关的概念文档、API 文档让有兴趣的读者可以继续深入。4.2 常见提交错误与 PR 被拒原因分析根据我的观察和社区讨论以下是一些导致 PR 被要求修改或拒绝的常见原因直接修改了zh/或ja/目录的文件这是最常犯的错误。除非你明确在优化机器翻译且使用translate:提交类型否则所有内容修改必须仅在en/目录下进行。自动化流水线会覆盖你的手动修改。忽略了docs.json的更新新增了页面但忘记在docs.json中添加导航条目导致新页面在网站上“隐身”。记得导航结构也需要在英文部分更新。提交信息格式不规范使用了added、updates等非祈使语气或者类型错误如用feat提交文档内容。PR 包含多个不相关的改动例如在一个 PR 里既修正了错别字又重构了一个章节还更新了依赖版本。这会给审核带来巨大困扰。务必坚持“One topic per PR”原则。如果有多处修改请拆分成多个独立的 PR。技术描述不准确或过时文档的生命力在于准确。在撰写涉及具体版本号、API 参数或配置项的内容时务必基于最新的稳定版 Dify 进行验证。不要凭记忆或过时的博客文章来写。未进行本地预览提交的文档存在明显的格式错误、链接失效或图片无法显示。mintlify dev是提交前的必备检查步骤。4.3 如何高效地修正错误Fix发现文档中有个错误想快速修正怎么做最高效在 GitHub 上直接编辑对于显而易见的错别字或单个链接错误你可以直接在 GitHub 网站上浏览对应文件点击编辑按钮进行修改。GitHub 会自动为你完成 Fork、创建分支、提交和发起 PR 的全过程。这是最快捷的方式。使用命令行精准定位如果是更复杂的修改在本地操作更顺手。你可以使用git grep命令快速搜索需要修改的术语或代码片段。例如你想把所有“web site”的拼写改为“website”可以git grep -l web site en/找到所有包含该词的文件然后逐一修改。引用 Issue如果你是在解决一个已登记的 GitHub Issue在提交信息或 PR 描述中使用Fixes #123或Closes #456这样的关键字。当 PR 被合并时对应的 Issue 会自动关闭形成良好的工作闭环。4.4 参与社区讨论与获取帮助如果你对某个功能的文档化方式不确定或者遇到了本地环境无法解决的问题积极与社区沟通是上策。GitHub DiscussionsDify 仓库通常设有 Discussions 板块你可以在这里提出关于文档的疑问、分享写作思路或在动手前获得维护者的初步认可。Discord/Slack 社区很多开源项目有实时聊天社区。在相应的#documentation频道提问往往能得到快速响应。阅读已合并的 PR这是最好的学习材料。去看看别人是如何提交高质量 PR 的学习他们的描述方式、代码修改风格和与维护者的互动过程。为开源项目贡献文档是一项极具价值的工作。它直接帮助了成千上万的开发者更快地上手和解决问题。通过深入理解langgenius/dify-docs这套成熟的体系你不仅能成为 Dify 社区的优秀贡献者更能将这些文档工程学的实践应用到任何你需要维护知识库的场景中去。从修复一个标点开始到撰写一篇完整的教程每一步都是在构建更开放、更易用的技术世界。 Dify 开源文档贡献指南：从结构解析到自动化协作全流程
1. 项目概述Dify 文档仓库的维护与贡献指南如果你正在使用或关注 Dify 这个开源的 AI 应用开发平台那么你一定接触过它的官方文档。这份文档是项目成功的关键一环它清晰、准确并且支持多语言。你可能不知道的是这份文档本身也是一个开源项目托管在 GitHub 的langgenius/dify-docs仓库里。这意味着任何开发者、技术写手甚至热心的用户都可以参与到这份文档的完善工作中来。今天我就以一个深度参与过多个开源文档项目维护者的视角为你彻底拆解这个文档仓库的结构、贡献流程以及背后的设计哲学。无论你是想提交一个简单的错别字修正还是计划撰写一篇完整的功能指南这篇文章都将是你最实用的“地图”。这个仓库的核心价值在于它不仅仅是一堆 Markdown 文件的集合更是一套经过精心设计的、高度自动化的文档工程体系。它解决了开源项目文档维护中最头疼的几个问题多语言同步的负担、内容格式的统一、以及贡献者体验的优化。理解这套体系不仅能让你更高效地为 Dify 做贡献其背后的思路和工具链对于你维护自己的任何技术文档项目都有着极高的参考价值。接下来我们就从仓库结构开始一步步深入。1.1 核心设计源语言与自动翻译的分离打开dify-docs仓库你首先会注意到它的目录结构非常清晰dify-docs/ ├── en/ # 英文文档源语言 ├── zh/ # 中文翻译自动生成 ├── ja/ # 日文翻译自动生成 ├── writing-guides/ # 写作与格式指南 ├── .claude/skills/ # AI 辅助写作技能 ├── tools/translate/ # 翻译流水线工具 ├── docs.json # 导航结构定义文件这个结构背后是一个至关重要的原则所有内容的修改只应在en/目录下进行。zh/中文和ja/日文目录中的内容是由自动化翻译流水线从英文源文件同步生成的。这是一个非常聪明且高效的设计它从根本上避免了多语言版本内容不同步的“幽灵页面”问题。注意这里有一个特例文件en/self-host/configuration/environments.mdx它的翻译需要手动处理。这是因为环境配置涉及大量技术术语和特定上下文机器翻译容易出错必须由熟悉该领域的人进行人工校对。这提醒我们自动化虽好但对于关键或易混淆的内容人工干预仍是保证质量的必要环节。为什么选择英文作为源语言这并非“英语中心主义”而是出于工程实践的考量。首先Dify 的核心开发者和最初的社区用户多以英语交流英文文档是迭代最快、最准确的。其次目前主流的机器翻译引擎如 DeepL、Google Translate对英译中的质量相对较高且稳定。将英文作为单一事实来源Single Source of Truth可以最大限度地保证所有语言版本在技术准确性上的一致性。作为贡献者你只需要专注于写好英文内容语言障碍由工具链来克服。docs.json文件的作用这个文件定义了文档网站的导航菜单结构。当你新增一个页面时必须在docs.json的英文部分添加对应的条目。翻译流水线会识别这个变化并自动在中文和日文导航中生成对应的条目。这意味着你几乎不需要操心多语言导航的维护工作。1.2 贡献流程全解析从 Fork 到 Merge为这个仓库做贡献遵循标准的 GitHub 开源协作流程但有一些细节值得特别注意。整个流程可以概括为Fork - Clone - 修改 - 提交 - 发起 Pull Request (PR) - 等待审核合并。第一步Fork 与克隆这步很常规在 GitHub 上点击 Fork 按钮将仓库复制到你的账号下。然后使用git clone命令克隆到你本地。我建议在克隆后立即添加上游远程仓库方便后续同步主仓库的更新git remote add upstream https://github.com/langgenius/dify-docs.git第二步创建特性分支永远不要在main分支上直接修改。创建一个描述性的新分支例如git checkout -b docs/add-workflow-tutorial。清晰的分支名能让维护者一眼就明白你的 PR 意图。第三步进行修改并本地预览这是核心步骤。所有内容修改都在en/目录下进行。Dify 文档使用 MDX 格式Markdown 的扩展允许嵌入 JSX 组件每个文件顶部必须有 YAML Frontmatter 来定义元数据例如--- title: Building Your First AI Agent description: A step-by-step tutorial to create an interactive AI agent using Difys workflow canvas. --- 正文内容从这里开始...title和description必须填写它们会用于网页的标题和 SEO 描述。修改完成后强烈建议在本地预览效果。仓库使用 Mintlify 作为文档生成器。你需要先全局安装 Mintlifynpm i -g mintlify然后在仓库根目录运行mintlify dev。这会启动一个本地开发服务器通常在http://localhost:3000你可以实时查看渲染效果检查链接、图片和格式是否正确。第四步提交更改与 PR 规范提交代码时信息格式有严格要求这体现了项目的专业性。格式为{type}: {description}。type必须是预定义的类型如docs,fix,feat等下文有详细表格。description使用小写、祈使语气动词开头不超过72个字符句末不加点。 例如docs: add advanced RAG configuration guide或fix: correct typo in quickstart.如果更改的原因不明显需要在提交信息中空一行后补充正文进行解释。例如fix: switch API response mode to streaming Blocking mode was causing HTTP 504 timeouts on large pages when generating documentation previews.完成本地提交后将分支推送到你的 Fork 仓库然后在 GitHub 界面向主仓库的main分支发起 Pull Request。第五步PR 审核与自动翻译维护者会审核你的 PR。审核的重点通常是技术准确性、内容清晰度、是否符合格式指南。一旦 PR 被批准合并项目的自动化流水线就会启动。它会将en/目录下的变更通过机器翻译自动同步到zh/和ja/目录并生成对应的翻译提交。整个过程无需你手动处理多语言问题。2. 内容创作与格式规范详解写好技术文档是一门艺术更是一门科学。dify-docs仓库通过一系列严格的指南和自动化工具试图将这门科学标准化同时为艺术的发挥留出空间。writing-guides/目录就是这份“写作宪法”的所在地。2.1 写作指南的核心要义writing-guides/目录下通常包含几个关键文件style-guide.md定义了行文风格。例如是使用“你”还是“用户”技术术语的首字母大小写代码示例的规范它确保了所有文档读起来像同一个人写的风格统一。formatting-guide.md这是格式的“法律条文”。它详细规定了标题层级的用法严禁跳级使用如从 H2 直接到 H4、代码块的标注语言、表格的样式、警告或提示框的写法等。在提交 PR 前你的内容必须通过这份指南的检验。glossary.md术语表。它定义了 Dify 生态中专有名词的标准译法和解释比如“Workflow”统一译为“工作流”“Knowledge Base”统一译为“知识库”。这是保证翻译一致性的基石尤其是对于tools/translate/中的自动化流程至关重要。实操心得很多贡献者会忽略这些指南直接凭感觉写。这是一个大坑。我曾经提交过一篇关于“模型推理参数”的文档自认为写得很清楚但被维护者打回原因就是文中“temperature”参数有时首字母大写有时小写并且没有链接到术语表进行统一解释。花10分钟通读一遍指南能为你节省数小时的返工时间。2.2 利用 AI 辅助提升效率与质量这个仓库最前沿的一点是它官方鼓励并集成了 AI 辅助写作。在.claude/skills/目录下预置了针对 Claude Code 编辑器的技能Skills。这些技能本质上是精心设计的提示词Prompts能指导 AI 如何帮助你撰写特定类型的文档。例如可能有一个“撰写操作指南”的技能当你激活它后AI 会引导你按照“概述 - 前置条件 - 分步步骤 - 预期结果 - 故障排查”的结构来组织内容。还有一个“检查格式”的技能它可以自动将你的草稿与formatting-guide.md对照指出不符合规范的地方。如何使用这些技能如果你使用 Claude Code 编辑器在克隆仓库并打开项目后这些技能通常会自动加载到编辑器的技能面板中。你可以选择对应的技能然后 AI 就会进入“角色”基于该技能的设定来协助你。即使你不使用 Claude Code阅读这些技能文件本身也是学习如何结构化技术文档的绝佳材料。注意事项AI 是强大的助手但不是作者。它生成的代码示例可能过时技术描述可能不够精确。你必须以领域专家的身份对 AI 产出进行严格的审查和修正。永远不要直接提交 AI 生成的、未经你深度校验的内容。2.3 提交类型Commit Type的精准运用提交信息的type字段不是随便填的它帮助维护者快速分类和审核变更。下表是完整的使用指南类型使用场景示例docs最常用。新增或更新任何文档内容。docs: add tutorial for API deploymentfix修正错别字、错误链接、错误的技术描述。fix: correct the default port in docker-compose.yml examplefeat非内容性的增强。如为文档站添加搜索功能、新增交互式组件。feat: add dark mode toggle to code snippetsrefactor重构内容结构而不改变实质信息。如重组章节顺序、拆分过长的页面。refactor: move advanced configuration to a separate pagetranslate手动更新翻译内容通常只用于那个特例文件或优化机器翻译。translate: refine Chinese translation for environments.mdxstyle仅修改格式如调整缩进、修正标题层级、统一标点。style: format all tables to use consistent alignmentchore更新依赖、配置文件等杂项。如升级 Mintlify 版本。chore: update mintlify to version 4.1.0一个常见的误区当你既修改了内容又修正了几个错别字时应该用docs还是fix原则是看主要目的。如果你的主要贡献是新增了大量内容附带修正了旧文中的小错误那么使用docs。如果这个 PR 纯粹是为了修正一系列错误则使用fix。保持 PR 的单一职责One topic per PR能让审核更高效。3. 本地开发与自动化工具链实战想要高效贡献光知道规则不够还得把环境玩转。本地开发环境的顺畅程度直接决定了你的贡献体验和效率。3.1 Mintlify 本地预览的细节与排错运行mintlify dev看似简单但有些细节能让你事半功倍。端口占用问题默认的 3000 端口可能被占用。你可以指定端口运行mintlify dev -p 8080。热重载Mintlify 支持热重载。修改en/目录下的.mdx文件并保存后浏览器中的预览页面会在几秒内自动刷新。但修改docs.json导航文件后通常需要重启服务才能生效。检查构建错误如果页面无法正常渲染首先查看终端运行mintlify dev的命令行窗口是否有红色的错误信息。常见的错误包括Frontmatter 格式错误如缺少结束的---、Markdown 语法错误、或引用了不存在的图片路径。一个真实踩坑案例有一次我写一篇教程里面包含一个复杂的代码片段我用了三个反引号加python标注。但预览时代码高亮始终不对。排查了半天才发现我在代码片段里某行不小心又写了三个反引号作为字符串内容的一部分这破坏了 Markdown 的解析。解决方案是在代码块内部的反引号前加反斜杠转义或者使用四个反引号来包裹整个代码块。这类问题只能在本地预览中发现如果直接提交会在 CI/CD 检查中失败。3.2 预提交钩子Pre-commit Hook的配置与原理仓库中有一个非常实用的自动化配置预提交钩子。通过运行git config core.hooksPath .githooks命令你将 Git 的钩子目录指向项目自带的.githooks文件夹。这个钩子具体做了什么它很可能关联着一个脚本当你执行git commit时这个脚本会自动运行。在dify-docs的上下文中这个钩子的一个关键作用可能是自动更新术语数据库。当你修改了writing-guides/glossary.md文件并尝试提交时钩子脚本会被触发它可能运行tools/translate/下的某个脚本将最新的术语表同步到翻译流水线所需的数据库中确保后续的自动翻译能使用最新的术语。如何启用只需在仓库根目录执行一次上述命令即可。之后你的每次提交都会自动经过这个钩子的处理。如果脚本执行失败例如术语表格式错误提交会被中止你就能在提交前发现问题而不是等到 CI 环节才报错。注意事项如果你之前为 Git 配置过其他全局钩子这个命令会覆盖它。如果你需要同时使用多个项目的钩子可能需要更复杂的方案比如使用像pre-commit一个管理 Git 钩子的框架这样的工具。但对于专注贡献 Dify 文档来说直接使用项目提供的钩子是最简单直接的方式。3.3 翻译流水线浅析虽然作为普通贡献者无需直接操作翻译流水线但了解其工作原理有助于你写出更“翻译友好”的文档。tools/translate/目录下存放着实现自动化翻译的脚本。其工作流程大致如下监听变更当main分支有新的合并通常是包含en/目录更改的 PRCI/CD 流水线如 GitHub Actions被触发。提取文本脚本会解析en/目录下变更的.mdx文件提取出需要翻译的文本块通常忽略代码块和 Frontmatter 中的部分字段。调用翻译 API将提取的文本发送至机器翻译服务如 DeepL API。应用翻译将翻译结果填充回zh/和ja/目录下对应的文件结构中。提交回仓库自动创建两个新的提交例如[Bot] Translate content into Chinese和[Bot] Translate content into Japanese并推送到仓库。这对你的写作意味着什么避免歧义句子机器翻译对复杂长句、带有大量代词的句子处理不好。尽量写短句主语明确。标记不需翻译的内容对于品牌名、专有名词如“Dify”、“GPT-4”、代码变量名确保它们在上下文中清晰可辨机器翻译通常会识别并保留它们。善用术语表你在glossary.md中定义的术语会成为翻译引擎的“记忆”确保关键术语在所有文档中翻译一致。4. 高质量贡献的进阶技巧与常见问题掌握了基本操作后如何让你的贡献脱颖而出更容易被维护者接受这里分享一些从实战中总结的进阶技巧和常见问题的解决方法。4.1 如何撰写一篇优秀的操作指南Tutorial新增一篇完整的操作指南是价值很高的贡献。以下是一个经过验证的结构模板你可以直接套用目标与前置条件开篇明义告诉读者学完这篇指南能做什么例如“部署一个带有自定义知识库的客服机器人”。并清晰列出所有前提如需要的 Dify 版本、必要的 API 密钥、已有的云端资源等。分步详解将过程分解为逻辑清晰的步骤。每个步骤以一个行动动词开头如“创建应用”、“配置模型”、“上传文档”。在步骤中不仅要写“怎么做”更要解释“为什么这么做”。例如“这里我们选择 GPT-4 模型因为它对长上下文的理解更好适合处理知识库问答。”代码与配置示例提供可直接复制的代码块、配置片段。对于关键参数以注释或表格形式说明其含义和推荐值。# docker-compose.yml 片段 services: dify-api: image: langgenius/dify-api:latest environment: - OPENAI_API_KEYsk-... # 你的 OpenAI API 密钥这是必填项 - MODEL_PROVIDERopenai # 指定模型提供商验证结果告诉读者如何验证步骤是否成功。例如“完成上述配置后访问http://localhost:3000你应该能看到 Dify 的登录界面。”故障排查预见新手可能遇到的问题并给出解决方案。用表格形式呈现一目了然。问题现象可能原因解决方案访问localhost:3000报连接错误Docker 容器未成功启动运行docker-compose logs查看具体错误日志知识库文件上传后处理失败文件格式不支持或过大确认文件为 .txt, .pdf, .docx 格式且大小小于 50MB后续步骤与参考提供延伸阅读的链接如相关的概念文档、API 文档让有兴趣的读者可以继续深入。4.2 常见提交错误与 PR 被拒原因分析根据我的观察和社区讨论以下是一些导致 PR 被要求修改或拒绝的常见原因直接修改了zh/或ja/目录的文件这是最常犯的错误。除非你明确在优化机器翻译且使用translate:提交类型否则所有内容修改必须仅在en/目录下进行。自动化流水线会覆盖你的手动修改。忽略了docs.json的更新新增了页面但忘记在docs.json中添加导航条目导致新页面在网站上“隐身”。记得导航结构也需要在英文部分更新。提交信息格式不规范使用了added、updates等非祈使语气或者类型错误如用feat提交文档内容。PR 包含多个不相关的改动例如在一个 PR 里既修正了错别字又重构了一个章节还更新了依赖版本。这会给审核带来巨大困扰。务必坚持“One topic per PR”原则。如果有多处修改请拆分成多个独立的 PR。技术描述不准确或过时文档的生命力在于准确。在撰写涉及具体版本号、API 参数或配置项的内容时务必基于最新的稳定版 Dify 进行验证。不要凭记忆或过时的博客文章来写。未进行本地预览提交的文档存在明显的格式错误、链接失效或图片无法显示。mintlify dev是提交前的必备检查步骤。4.3 如何高效地修正错误Fix发现文档中有个错误想快速修正怎么做最高效在 GitHub 上直接编辑对于显而易见的错别字或单个链接错误你可以直接在 GitHub 网站上浏览对应文件点击编辑按钮进行修改。GitHub 会自动为你完成 Fork、创建分支、提交和发起 PR 的全过程。这是最快捷的方式。使用命令行精准定位如果是更复杂的修改在本地操作更顺手。你可以使用git grep命令快速搜索需要修改的术语或代码片段。例如你想把所有“web site”的拼写改为“website”可以git grep -l web site en/找到所有包含该词的文件然后逐一修改。引用 Issue如果你是在解决一个已登记的 GitHub Issue在提交信息或 PR 描述中使用Fixes #123或Closes #456这样的关键字。当 PR 被合并时对应的 Issue 会自动关闭形成良好的工作闭环。4.4 参与社区讨论与获取帮助如果你对某个功能的文档化方式不确定或者遇到了本地环境无法解决的问题积极与社区沟通是上策。GitHub DiscussionsDify 仓库通常设有 Discussions 板块你可以在这里提出关于文档的疑问、分享写作思路或在动手前获得维护者的初步认可。Discord/Slack 社区很多开源项目有实时聊天社区。在相应的#documentation频道提问往往能得到快速响应。阅读已合并的 PR这是最好的学习材料。去看看别人是如何提交高质量 PR 的学习他们的描述方式、代码修改风格和与维护者的互动过程。为开源项目贡献文档是一项极具价值的工作。它直接帮助了成千上万的开发者更快地上手和解决问题。通过深入理解langgenius/dify-docs这套成熟的体系你不仅能成为 Dify 社区的优秀贡献者更能将这些文档工程学的实践应用到任何你需要维护知识库的场景中去。从修复一个标点开始到撰写一篇完整的教程每一步都是在构建更开放、更易用的技术世界。