Rasepi Blog

读者和写作者的思维模式不同。为什么每种工具都给他们提供相同的用户界面？

2026-04-03T00:00:00Z

现在打开 Confluence，找到您需要阅读的文档。您会看到什么？

工具栏。编辑按钮。评论框页面历史链接满是你不需要的导航的侧边栏。面包屑元数据字段权限指示器整个创作界面都围绕着你来这里阅读的文本。

现在想想你真正想要的是什么：问题的答案、流程的下三个步骤、十分钟后开会前需要参考的政策。

你是来消费的。界面假定你是来创造的。

这几乎是所有文档平台的默认设置。Confluence、Notion、SharePoint、GitBook、Nuclino、Slite。它们都为读者和作者提供了相同的环境。页面就是页面。每个人都能获得相同的视图，或多或少会有一些权限按钮。

这感觉很正常，因为我们从来没有过其他的东西。但这只是一个设计决定，而不是自然法则。而且这是个错误的决定。

读写界面相同会造成认知开销](/zh/blog/img/readers-writers-ui.svg)

阅读和写作不是同一种认知任务

这不是用户界面的偏好。这是大脑工作方式的根本区别。

当你写作时，你处于生成模式。你在构思、组织、决定包含什么、省略什么。你需要工具：格式选项、结构控制、媒体嵌入、元数据字段、版本历史、协作功能。界面应该给你带来力量和灵活性。

阅读时，你处于接受模式。你在扫描、过滤、提取相关内容，并试图继续前进。你需要清晰：简洁的排版、集中的布局、最小的干扰。界面应该让路。

认知心理学对此有一个清晰的框架。认知负荷理论由约翰-斯韦勒（John Sweller）在 20 世纪 80 年代末提出，它将负荷分为内在负荷（材料本身的难度）、外在负荷（学习和整合的努力）和外在负荷（环境中添加的一切无用的东西）。读者可以看到的每一个工具栏、侧边栏和编辑按钮都是无关负荷。它们无助于读者理解内容。它们会主动争夺读者的注意力。

梅尔和莫雷诺（2003 年）](https://doi.org/10.1207/S15326985EP3801_6) 对多媒体学习的研究表明，减少无关元素可以提高理解能力和保留率。他们的连贯性原则很直接：如果文档界面向读者显示编写控件，则在每次页面加载时都违反了这一原则。

**读者不需要看到作者的工具。无论如何显示它们都不是中立的。这对理解是有害的。

##目前的平台如何处理这个问题（它们大多不处理）

让我们看看现有的平台。

Confluence有阅读模式和编辑模式，但阅读模式仍被平台的导航、元数据和页面树所包围。当你不编辑时，编辑工具栏就会消失，但 "这是一个可编辑的维基页面 "这一心理框架却从未完全消失。每个读者都能看到 "编辑 "按钮。页面在低语你可以修改它。

在这方面，Notion的情况更糟。它的核心设计理念是一切都可以编辑。点击任何地方，你就可以打字。这对作家来说很好。但对于那些只想吸收内容而不想担心不小心修改了什么的读者来说，这就糟透了。Notion 自己的模板库就说明了这一点：每个模板都是一个工作区，而不是出版物。

从技术上讲，SharePoint支持用于查看和编辑的不同页面布局，但整体体验仍然是企业内部网。读者感觉自己是在使用企业工具，而不是在阅读一份为理解而优化的文档。

GitBook以其简洁的文档式输出最接近阅读优先的体验。但即使是这样，读者体验也是基于这样一个假设，即读者是一名正在阅读技术文档的开发人员。它不是为普通知识消费者设计的。

这些平台都没有将阅读视为与写作有本质区别的活动。它们将阅读视为隐藏工具栏的写作。

当前工具：一个界面，所有受众](/zh/blog/img/readers-writers-current-tools.svg)

单一界面的代价

这不仅仅是一个美学问题。它的后果是可以衡量的。

信息过载降低理解能力

发表在《消费者研究杂志》上的一项研究](https://doi.org/10.1086/209336) 发现，信息超载会导致决策质量下降，随着无关信息与相关信息的比例增加，这种影响也会增加。文档页面上有可见的编写控件、导航树和元数据字段，这就增加了非编写读者的信息比例。

###上下文切换需要付出实际代价

当一个界面信号说 "你可以编辑这个 "时，它激活的认知框架与 "阅读这个 "是不同的。格洛丽亚-马克（Gloria Mark）在加州大学欧文分校进行的关于注意力和多任务处理的研究发现，在上下文切换之后，平均需要 23 分 15 秒才能完全重新集中注意力。如果读者一时考虑编辑（哪怕是修改错别字），就会被拉出阅读模式。这不是假设。使用过 Notion 的人都知道点击选择文本后不小心开始打字的经历。

读者和作者对相同内容的需求不同

写作者需要看到结构、格式标记、块类型、元数据和协作信号。他们需要完整的机制。

读者需要看到简洁的文本、清晰的层次结构，以及通往所需信息的最快路径。他们需要的是内容，而不是机器。

在同一个界面上为两者提供服务，意味着两者都无法获得针对其实际工作进行优化的体验。

第三种受众：人工智能

这就是问题变得复杂的地方，也是现有平台完全没有准备好的地方。

2026 年的文档有三个不同的消费者，而不是两个：

1.创建和维护内容的撰稿人 2.直观消费内容的读者 3. 3.以编程方式检索、解析和合成内容的人工智能系统

这些受众对相同的底层内容都需要一个基本不同的界面。

写作者需要丰富的编辑工具、协作功能和结构控制。读者需要简洁、重点突出、干扰最少的呈现方式。人工智能需要结构化、机器可解析的输出，并带有明确的元数据：新鲜度信号、分类标签、块级寻址和简洁的语义标记。

正如我们在《建设者，不是开发者》（/blog/builders-not-developers-how-claude-changed-devrel/）一文中所讨论的，人工智能中介已经成为越来越多知识工作者的主要文档消费者。GitHub的2024年开发者调查发现，97%的企业开发者使用过人工智能编码工具。到 2026 年，84% 的开发人员经常使用人工智能工具，41% 的代码都是人工智能生成的。

这些人工智能系统并不关心你的侧边栏或工具栏。它们需要的是干净的数据。而将读者视图与作者视图混为一谈的平台，也是将人工智能可消费表面与人类创作表面混为一谈。这就是一个界面中的三个不匹配。

三个受众，三种不同需求](/zh/blog/img/readers-writers-three-audiences.svg)

##Rasepi 如何分离体验

创建内容和消费内容是不同的活动，因此需要不同的界面。

作者环境

当您在拉塞皮中写作时，您将获得一个完整的写作环境。使用 TipTap 进行富文本编辑、块级控件、翻译状态指示器、过期管理、协作工具、内容结构视图，以及作者创建和维护高质量文档所需的其他一切。

撰稿人看到机器是因为他们需要机器。

读者环境

当读者阅读 Rasepi 文档时，他们看到的是简洁、集中的阅读体验。没有编辑铬。没有工具栏。没有 "您可以修改这个 "的信号。只有内容，以最适合理解和扫描的布局呈现。

读者看不到编辑按钮，因为他们不是来编辑的。他们是来学习知识、遵循流程或寻找答案的。界面尊重这种意图。

人工智能表面

对于人工智能消费者而言，Rasepi 通过结构化的应用程序接口（API）提供带有完整元数据的内容。每个区块都有其新鲜度得分、翻译状态、内容哈希值和分类标签。人工智能系统可以在区块级别查询内容，根据新鲜度进行过滤，排除陈旧或草稿材料，并准确检索所需的结构化数据。

无需刮擦维基页面，也无需寄希望于最好的结果。人工智能获得一个专门设计的界面，就像读者和作者一样。

一个内容层，三个界面

重要的是，我们并没有维护三份内容。这不是我们在【停止维护同一文档的五个副本】（/blog/stop-maintaining-five-copies-of-the-same-document/）一文中讨论过的入职五份副本的问题。

这是一个内容层，以结构化块的形式存储，通过三个不同的视图为三个不同的受众提供优化服务。

撰稿人编辑区块。读者看到的是组装好的、风格化的内容。人工智能查询带有元数据的结构化数据。相同的块。相同的真相来源。为每个消费者提供不同的呈现层。

只有块级架构才能做到这一点。每块内容都是可单独寻址的单元，有自己的元数据。您可以根据用户的需求，以不同的方式呈现这些内容块：

| 受众 | 需求 | 获取 | 内容 |----------|-------|------| | 撰稿人 | 格式、结构、协作、元数据 | 具有块级控制功能的完整撰稿环境 | 读者 | 格式、结构、协作、元数据 | 具有块级控制功能的完整撰稿环境 Reader | 简洁的文本、清晰的层次结构、快速扫描 | 集中阅读视图，无编辑铬 AI | 结构化数据、新鲜度评分、分类 | 具有完整元数据的块级应用程序接口

为什么这比看起来更重要

读到这里，你可能会想："这只是用户界面。对同一事物的不同看法。能有多重要？"

事实证明，它非常重要。

读者的信任

人们会信任那些看起来已经发布的内容。当一个页面看起来像一个任何人都可以编辑的 wiki 时，读者会不自觉地对它打折扣。当同样的内容以简洁、具有出版质量的阅读视图呈现时，它就更有权威性。这并非不合理。这是一个信号，表明有人认真对待了页面展示，这意味着他们也认真对待了内容。

尼尔森-诺曼集团对此进行了广泛的研究。他们的关于内容可信度的研究表明，设计质量和表现形式是用户评估内容可信度所依赖的最强信号之一。杂乱无章的编辑视图会主动削弱所显示内容的可信度。

撰稿人的工作效率

在专用创作环境中工作的写作者不必在 "我是在阅读还是在写作？"之间进行上下文切换。这些工具之所以存在，是因为它们理应存在，而不是因为界面无法确定谁在看它。

人工智能的可靠性

当人工智能系统有了一个带有结构化元数据的专用表面时，它们就能更好地决定检索什么、排除什么。它们可以在将区块纳入答案之前检查新鲜度得分。它们可以尊重分类标签。它们可以根据语言、状态或受众进行过滤。而当人工智能刮取的是为人类读者设计的 HTML 页面时，这些都是不可能实现的。

思维模式的转变

大多数文档平台的基本假设都是页面是单位，每个人都与页面交互。

拉塞皮的假设则不同：拉塞皮的假设则不同：_块是单元，不同的受众通过特制的表面与块进行交互。

这听起来像是一个很小的建筑区别。其实不然。这就是一个偶然向人工智能系统展示内容的工具和一个刻意为人工智能系统服务的工具之间的区别。是碰巧可读的写作环境，还是从头开始设计的阅读体验。一个足够好的界面和三个很棒的界面之间的区别。

文档不再只是写和读。它需要编写、阅读、查询、翻译、评分、分类，并大规模地提供给人工智能系统。单个界面不可能对所有这些进行优化，而假装可以优化的结果就是，维基文档无人问津，人工智能助手从页面中提取答案，而这些页面的设计根本不适合机器使用。

读者和作者处于不同的思维模式中。人工智能则处于完全不同的模式。界面应该反映出这一点。

2026 年的文档现状：定义下一个时代的五大趋势

2026-04-03T00:00:00Z

每隔几个月，我都会抽出一个上午来阅读。不是阅读 Rasepi 代码，也不是阅读 GitHub 上的问题。竞争对手的博客、行业报告、主题演讲公告、开发者调查。只要是上个季度出货的、涉及文档、知识管理或人工智能辅助工作流的内容。

上周我做了这项工作，结果比我预想的更清晰。这并不是因为任何一项公告都具有突破性意义，而是因为有五种不同的趋势正在汇聚在一起，当你把它们排列在一起时，就会非常清晰地描绘出文档平台在未来两年需要做的事情。

以下是我的发现。

1.人工智能现在是主要的阅读者。而不是人类。

GitBook 在他们的 AI 文档数据报告中公布了一个惊人的数字：2025 年，人工智能对文档的阅读量增长超过 500%。百分之五百。这可不是四舍五入的误差。

同时，Stack Overflow 的 2024 年开发人员调查显示，61% 的开发人员每天花 30 分钟以上的时间搜索答案。但他们的搜索方式已经发生了变化。GitHub 自己的调查发现，97% 的企业开发人员使用过人工智能编码工具。到 2026 年，84% 的开发人员每天都会使用人工智能工具，41% 的代码现在都是人工智能生成的。这些人不是在浏览你的维基侧边栏。他们在询问克劳德或 Copilot，而人工智能正在代表他们阅读你的文档。

这其中的含义不言而喻。最常阅读文档的人不再是打开浏览器标签的人。而是一个正在进行检索调用的语言模型。而这个模型没有能力眯着眼睛看一页，然后想 "嗯，这个看起来过时了"。

GitBook 很早就发现了这一点，并通过他们的State of Docs 2026 report和向机器可读格式的推进做出了回应。他们还发布了 skill.md，这是一种专门为人工智能代理构建产品信息的惯例。谷歌更进一步，推出了Gemini API Docs MCP，通过模型上下文协议将编码代理与当前文档连接起来。他们的理由很明确：代理会生成过时的代码，因为它们的训练数据有截止日期。MCP 修正使他们的评估通过率达到 96.3%。

因此，第一个趋势已经确定。人工智能是主要的阅读器。将此作为核心设计约束而非后期添加功能的平台将拥有结构性优势。

2.新鲜度和信任元数据成为必备条件

Anthropic 于 2025 年 12 月采访了 81,000 名克劳德用户，并于 2026 年 3 月公布了调查结果。这是迄今为止对人工智能用户进行的最大规模的定性研究（159 个国家，70 种语言）。最受关注的问题是什么？不可靠。27%的受访者将其列为最担心的问题，其中79%的人有过亲身经历。

这个数字应该会让每个文档团队彻夜难眠。

当人工智能的答案不可靠时，问题并不总是出在模型上。通常情况下，模型只是忠实地再现了它在陈旧文档中发现的内容。模型并没有产生幻觉。你的文档只是出错了，却没有人标注出来。

Stack Overflow 的数据从另一个角度强化了这一点：81%的开发人员预计人工智能将在未来一年中更多地融入他们的代码文档中。如果 81% 的用户正在将文档提供给人工智能，而 27% 的人工智能用户表示不可靠是最大的问题，那么你就遇到了信任问题，这是任何及时的工程设计都无法解决的。解决之道在于源头。

这就是为什么新鲜度元数据很重要。而不是 "最后编辑 "的时间戳（这些时间戳告诉你什么时候有人碰过文件，而不是内容是否仍然准确）。真正的新鲜度：审核状态、链接健康、翻译对齐、读者信号、内容漂移检测。机器可以读取的元数据，并利用这些元数据来决定文件是否可以安全引用。

我一直在回想一个简单的框架。你的文档需要一个信用评分。不是时间戳。而是信用评分。(我们一直在使用 Rasepi 的新鲜度评分系统来实现这一点。）

3.翻译从 "项目 "转向 "管道"

DeepL 在二月份发表了一篇名为"全球企业不能错过的 6 个翻译转型"的文章。他们的论点是：翻译正在成为一项持续运营的挑战，而不是每季度进行一次的批量项目。

这与我所看到的一切不谋而合。

以前的模式很简单。用英语写作。当你有预算时，聘请翻译或通过服务机构进行翻译。翻译回来。上传。完成，直到下次。问题是，当你的产品每周发货，文档不断更新时，"下一次 "来得越来越快。当德文版从审核中返回时，英文源代码已经更改了两次。

DeepL 自己的 Customization Hub现在提供了词汇表、样式规则和格式设置，这很好。但是，如果这些工具不在文档平台上，你就需要管理一个翻译工具链：编辑器、导出、翻译、审核、重新导入、重复。每一步都有可能出现偏差。

Notion 完全没有本地多语言支持。Confluence 通过市场插件提供多语言支持。GitBook于 2025 年 8 月添加了自动翻译功能，这是一个步骤，但它是在页面级别运行的。

真正的转变是从页面级到块级。当你在段落层面跟踪翻译时，你只能重译实际发生变化的内容。一般情况下，40 个段落中可能有两个段落需要编辑。这就减少了 94% 的翻译工作。(这就是 Rasepi 的核心翻译架构，老实说，这也是我最引以为豪的地方。但即使抛开我们不谈，行业的发展方向也是明确的：持续、渐进、嵌入式翻译是未来的发展方向）。

4.人工智能代理需要结构化的内容，而不是维基页面

当 Notion 在二月份发布 Custom Agents时，我就意识到了这一点。在早期访问期间，共创建了 21000 个代理。这些代理可以回答知识库中的问题、路由任务、编制状态报告。仅 Ramp 就有 300 多个代理。

Atlassian 也朝着类似的方向发展。Confluence 中的 Rovo AI从 Atlassian 和第三方应用程序中提取上下文来生成内容。他们的口号是"以团队现有工作为基础，提供语境丰富的高质量内容"。

然后 Anthropic 推出了Claude Code 中的代理团队，多个人工智能代理可自主协调完成复杂任务。Opus 4.6 在 8 针 100 万 MRCR 基准测试中的得分率为 76%（比前一型号的 18.5% 有所提高），这意味着它能真正检索到深埋在海量文档集中的信息，而不会迷失方向。

这三家公司都在开发能消耗文档的代理。它们都没有解决源质量问题。

Notion 的定制代理文档明确承认，当代理读取不受信任的内容时，存在提示注入风险。Atlassian 的 Rovo 会抓取在 Confluence 中找到的任何内容。如果这些内容已经过期三个月，Rovo 也不会知道。无论如何，它都会在此基础上进行构建。

要让代理可靠地工作，它们需要的不仅仅是几页文本。它们需要具有稳定标识符的结构化内容、明确的新鲜度信号、清晰的分类元数据，以及区分 "这是最新的并已审核过的内容 "和 "这是存在的但一年来没人碰过的内容 "的能力。维基页面不具备这些功能。而具有信任元数据的结构化块级内容则能做到这一点。

5.开源和自托管正在卷土重来

最后一条更像是一种有数据支持的直觉，而不是一个单一的公告。

2024 年底，GitBook 将其发布的文档开源，并启动了开源软件基金。他们的理由是：开源项目理应获得免费、高质量的文档工具。但此举也预示着更广泛的意义。

Notion 仅提供云服务。没有自托管选项。Confluence Data Center 存在，但需要许可证。当您的文档平台保存着最敏感的操作知识（事件操作手册、合规程序、架构决策）时，"谁来控制这些数据？"这个问题并不抽象。

Anthropic 在二月份发表的"Claude is a space to think"一文中就信任和商业模式提出了一个有趣的论点。他们的核心主张是：广告激励与真正有用的人工智能助手是不相容的。他们选择了无广告的方式，这样用户就能信任这个工具。

我认为文档平台也有类似之处。如果你的文档系统是封闭源代码的，而且仅限云端，你就无法验证它向人工智能提供了什么。你无法审核新鲜度计算。你无法确保数据在你的掌控之中。对于在知识库之上部署人工智能助手的团队（越来越多的人都在这么做）来说，可审计性非常重要。

这并不是一场关于开源在道德上更优越的论战。闭源产品绝对值得信赖。但当你在内部文档的基础上构建人工智能驱动的工作流程时，检查和验证系统的能力是一个实际的优势。对我们来说，MIT 许可 Rasepi 并不是事后才想到的。它是基于同样的逻辑做出的设计决定：文档基础架构应该是可审计的。

这五大趋势的共同含义

单独来看，每种趋势都是可控的。人工智能会阅读你的文档？好吧，添加一些机器可读的元数据。新鲜度很重要？好，添加审核日期。翻译需要连续性？当然，整合 DeepL。代理需要结构？很好，改进内容模式。主权很重要？很好，提供自托管选项。

但综合来看，它们所描述的平台与大多数团队目前使用的平台有着本质区别。

差距在于架构。这并不是你可以随意添加的五项功能。它们是需要嵌入到基础中的五个假设。内容的存储方式（块级，而非页面级）。如何建立信任模型（新鲜度分数，而非时间戳）。翻译如何进行（增量、嵌入式、按段落）。人工智能代理如何访问内容（带元数据的结构化应用程序接口，而不是页面搜刮）。如何控制数据（开放、可审计、可自托管）。

没有一个成熟的平台是同时围绕这五个方面设计的。有些平台正在逐一添加。GitBook 在人工智能可读性方面进展最快。Notion 正在构建代理基础架构。Atlassian 拥有企业级发行版。

但从一开始就为这五个方面进行设计？这就是在环境发生变化时重新开始的优势。

我意识到自己有失偏颇。我们之所以建立 Rasepi，就是因为我们看到了这些趋势的交汇点，并希望有一个平台能从一开始就考虑到所有这些趋势。块级翻译、强制过期、新鲜度评分、结构化人工智能就绪内容、开源。这是整个项目的论点。

但即使我们不存在，我认为任何对 2026 年第一季度发生的事情的诚实解读都指向同一个方向。文档正在成为基础设施。而基础设施与维基页面有着不同的要求。

最先意识到这一点的团队将不仅仅拥有更好的文档。他们还将拥有更可靠的人工智能代理、更低的翻译成本、更少的合规意外，以及长期保持可信度的知识库。

这就是 2026 年的文档现状。问题不在于这些趋势是否真实存在。而是您的平台是否为这些趋势而设计。

五大趋势。一个架构问题：你的文档平台是为 2026 年设计的，还是仍在为 2016 年的假设服务？

Sources：GitBook AI 文档数据报告、GitBook State of Docs 2026、GitBook skill.md、Google Gemini API Docs MCP、Stack Overflow 2024 开发者调查、GitHub 2024 开发者调查、Index.dev 开发者生产力统计、Anthropic "What 81,000 People Want from AI", Anthropic "Claude is a space to think", Claude Opus 4.6, Notion Custom Agents, Atlassian Rovo in Confluence, DeepL "6 Translation Transformations", DeepL Customization Hub, GitBook open source documentation, GitBook auto-translate..

建设者，而非开发者：克劳德如何改变文档的对象

2026-04-02T00:00:00Z

此时此刻，有人正在某处集成你的 API。他们不在你的文档网站上。他们没有打开你的入门指南。他们从未见过你的互动游乐场或精心设计的侧边栏导航。

他们正坐在 Claude 中。或 Copilot。或光标。他们输入类似于_"使用应用程序路由器将 Stripe 账单 API 与我的 Next.js 应用程序集成"_这样的内容，然后等待工作代码的返回。人工智能代表他们阅读你的文档。它找到了相关的端点，理解了身份验证流程，选择了正确的 SDK 方法，并生成了一个实现。

两周前，在圣加仑举行的 Start Summit 黑客马拉松上，我亲眼目睹了这一切的发生。我与一群计算机科学专业的学生和几位早期初创企业的创始人讨论了他们如何开发新的应用程序接口，他们每个人都描述了同样的工作流程：把问题粘贴到人工智能中，得到代码反馈，再从那里开始迭代。当我问她是否读过文档时，其中一位学生笑了。"我为什么要读？克劳德都帮我读了"。

这个人从未访问过你的网站。他们可能永远都不会访问你的网站。而这正是软件越来越多的构建方式。

核心转变

文档现在有两个根本不同的消费者：阅读文档的人类和代表构建者阅读文档的人工智能助手。大多数文档都是专门为人类优化的。人工智能已经成为主要的阅读者。

这将改变下游的一切：

当人工智能提供过期内容时，构建者无法发现问题。损害无声无息地扩大。
**"开发者 "这个词太狭隘了。**产品经理、设计师和分析师正在通过人工智能助手开发软件，而他们自己往往连一行文档都没读过。
简洁的标记符、自成一体的区块和明确的元数据能让人工智能准确地呈现你的产品。
**格式要求已经分化。**人类读者需要叙述。人工智能中介需要结构化、可解析的规范。你需要为两者服务。

这篇文章的其余部分将阐述我们是如何走到这一步的，这对 DevRel 意味着什么，以及你现在可以做些什么。

无人计划的旅程

长期以来，开发人员关系遵循的是一条众所周知的道路。你编写了全面的文档。出版快速入门指南。在会议上发表演讲。你在 Stack Overflow 上保持存在。你让你的 API 参考可被搜索，让你的 SDK 简明易懂，让你的错误信息很有帮助。

这条路径假定开发人员会阅读你的内容。浏览你的结构。遵循你的步骤。

GitHub 的 2024 年开发人员调查发现，97% 的企业开发人员在某个阶段使用过人工智能编码工具。Stack Overflow 的年度调查显示，76% 的开发人员正在使用或计划使用人工智能工具，其中 62% 的专业人员每天都在积极使用这些工具。到 2026 年，这一数字攀升至 84%，41% 的代码由人工智能生成，51% 的专业开发人员每天都在使用人工智能工具。这些数字不会放缓。

新的旅程看起来有所不同。有人用自然语言描述他们想要什么。人工智能助手会阅读文档，找到相关部分并生成集成。构建者审查输出结果，也许会完善提示，也许会提出后续问题。只需几分钟，无需数小时。

DevRel 团队花费数年时间完善的启动漏斗？它被绕过了。并不是因为它不好。只是切入点变了。

两个消费者，一套文档

现在，文档有两个根本不同的受众。

第一种是人类读者。这个人仍然存在。他们为架构决策、边缘案例调试、合规性审查和概念理解而出现。他们需要的是叙述性的解释、条理清晰的参考资料和清晰的权衡推理。

第二种是人工智能中介。它代表构建者阅读您的文档。它不关心你的侧边栏。它不会欣赏你的视觉设计。它需要的是结构化的、机器可解析的内容：简洁的标记符、一致的格式、明确的规范，它可以毫不含糊地进行推理。

如今，几乎所有的文档网站都只针对第一类受众进行了优化。第二类受众已经成为主流消费者。

杰里米-霍华德（Jeremy Howard）在 2024 年提出 /llms.txt 标准时就发现了这种紧张关系。他的观察非常准确：_"大型语言模型越来越依赖于网站信息，但却面临着一个关键的限制：上下文窗口太小，无法处理大多数网站的全部内容。在_______________________________________________________________________中，一个经过策划的标记符文件可以为人工智能模型提供产品的结构化概述以及最重要资源的链接。FastHTML、Anthropic自己的文档以及不断增长的项目目录现在都提供了这样的文件。

这是一个有用的惯例。但这也是更深层次问题的表象。真正的问题不在于格式。而是大多数文档在设计时从未考虑过机器的使用。

建造者没有偷工减料

看着那些不阅读文档而是提示 Claude 的人，我们很容易得出结论：他们在走捷径。他们并不真正理解代码中发生了什么。他们在某种程度上是低级的开发人员。

这样的对话我已经听过很多次了，所以我知道这通常是错误的。

这些开发者中的许多人都是高级工程师，他们会有意识地提高效率。他们理解代码，只是不想翻阅四页文档来查找实际需要的三行代码。他们已经了解到，人工智能助手提取这些行的速度比他们扫描这些行的速度还要快，所以他们把阅读工作委托给了人工智能助手。(老实说，我自己也是这么做的。我都不记得上一次从头到尾阅读入门指南是什么时候了）。

Anthropic公司在构建模型上下文协议时就意识到了这种模式。现在，克劳德、ChatGPT、VS Code、光标等公司都支持 MCP。它的明确设计目的是让人工智能助手可以进入外部系统，获取上下文，并根据上下文采取行动。规范将其描述为提供_"对数据源、工具和应用程序生态系统的访问，这将增强功能并改善最终用户体验"_。

请仔细阅读。这是基础架构语言，不是便利语言。使用这些工具的构建者并不是在逃避工作。他们正在通过一个新的层进行工作，而无论你是否设计了文档，你的文档都是这个层的一部分。

数字证明了这一点。目前，仅 Claude 一家就处理了每月 250 亿次 API 调用，在 159 个国家/地区拥有 3000 万月活跃用户。70%的财富 100 强公司都在使用 Claude。根据门罗风险投资公司（Menlo Ventures）的一项调查，Anthropic 占据了按模型使用率计算的 32% 的企业人工智能市场份额，领先于 25% 的 OpenAI。汇丰银行（HSBC）的一份研究报告则认为这一比例更高：按人工智能总支出计算，Anthropic 占 40%。这些都不是实验工具。它们是主要的基础设施。

开发者关系是为不同的时代而建立的

如果你的 DevRel 战略是在 2023 年之前设计的，那么它是为开发人员直接阅读文档的世界设计的。这个世界并没有消失，但对于越来越多的构建者来说，这已不再是主要的交互模式。

这就改变了一些长期存在的 DevRel 活动。

**会议演讲：**在开发者大会上进行 45 分钟的演讲，可以吸引几百人的关注。而结构良好的/llms.txt文件和简洁的机器可读文档则能让每一位随时随地向任何人工智能助手询问您的产品的开发人员了解。讲座是一次性活动。机器可读文档是复合型的。我并不是说会议毫无价值（我刚参加完一次会议），但杠杆等式已经发生了变化。

入门指南 经典的五步快速入门教程越来越流于形式。建设者并不按部就班。他们只需描述自己的需求，并期望人工智能能够实现集成。如果应用程序接口以机器友好的格式进行了详细说明，人工智能就能比任何教程更有效地处理入门体验。相反，教程应该成为概念性材料：解释为什么你会选择方法 A 而不是方法 B。但在解释如何取舍方面，人工智能就不那么可靠了。

Stack Overflow. 他们自己的调查数据显示，84%的开发者直接使用技术文档，其中90%依赖于API和SDK包中的文档。但他们访问这些文档的方式越来越多地是通过人工智能层，而不是浏览器标签。Stack Overflow 上仍然存在的问题往往是难题。边缘案例、生产调试、需要细微差别的问题。当然，这些问题很有价值。当然，这些问题很有价值，但已经不再重要。

当人工智能阅读你的文档时，新鲜度变得至关重要

这是大多数团队没有考虑到的部分。

当人类阅读文档页面时，他们可以做出判断。他们可能会注意到截图看起来很旧，或者底部的注释说流程改变了。他们会眯着眼睛看，然后想 "这感觉过时了"。

人工智能助手做不到这些。它能读取文本，将其作为事实进行处理，并满怀信心地生成答案。如果文档中描述的是已过时的端点，人工智能会欣然推荐与之集成。如果文档中提到的基础架构在六个月前已被替换，人工智能会将旧设置描述为当前设置。毫不犹豫。

这里的问题比听起来更糟糕：66%的开发人员已经表示，人工智能工具的最大问题是它们给出的结果 "几乎正确，但又不完全正确"。陈旧的文档直接导致了这个问题。人工智能并没有产生幻觉。它是在忠实地复制过时的内容，而构建者根本无法分辨。

建设者信任人工智能。人工智能相信文档。如果文档是过时的，信任链就会提供一个完全错误的答案。

显然，这一直是个问题。陈旧的内容总是让人感到困惑。但由于人类读者有时可以发现，因此这种损害得到了控制。人工智能中介却做不到。它们通过大规模、权威性地向那些没有理由怀疑的人提供陈旧内容，从而扩大了陈旧内容的影响。

新鲜度不再是一个内容质量问题。对于每一个接触文档的人工智能工作流来说，这都是一个可靠性问题。

##"开发者 "这个词过于狭隘

2026 年的软件开发人员并不都是开发人员。有些人是设计师，他们会提示克劳德构建工作原型。有些是产品经理，他们使用 Cursor 发布内部工具。有些是数据分析师，他们用自然语言描述数据管道，然后让代理进行组装。在 Start Summit 上，有一半的黑客马拉松团队成员没有编程背景，但他们在周末结束时都开发出了可运行的软件。

Ramp就是一个很好的例子。这家金融科技公司的估值从2023年的58亿美元上升到2025年末的320亿美元，年收入一路突破10亿美元。这是历史上发展最快的初创公司之一。他们的方法中有一个被广泛讨论的部分：产品经理直接使用人工智能工具构建功能，而不是在工程积压中等待。Ramp 的项目经理不仅仅是编写规格。他们会发送代码。人工智能负责实现。项目经理负责意图。

这不是捷径。这是一种全新的运营模式，而且其规模之大，让人很难将其视为一种实验。

Anthropic公司自己的内部研究揭示了这一点。当他们调查了 132 名自己的工程师了解他们如何使用 Claude 时，工程师们报告说，他们约有 60% 的工作任务使用 Claude。最常见的用途是什么？调试现有代码、了解代码库的各个部分在做什么，以及实现新功能。工程师们表示，他们倾向于将 "不复杂、不重复、代码质量不重要 "的任务交给 Claude。他们现在使用 Claude 所做的工作中，有 27% 以前根本无法完成。

这就是 Anthropic 自己的团队。建立模型的人将其用作文档阅读器、代码库导航器和初稿生成器。其他人也在做同样的事情，只是用的是你的文档，而不是他们的。

Anthropic 一直有意将其称为 "构建者 "角色。他们的工具不仅是为专业软件工程师设计的，也是为任何能够描述自己想要构建的东西的人设计的。当 Claude 可以通过 MCP 从 Figma 设计中构建一个全栈应用程序时，"开发者 "和 "非开发者 "之间的传统界限就消失了。

这对任何维护文档或关注开发人员体验的人都有实际意义。你的受众不再局限于知道什么是 REST 端点的人。它包括任何人工智能助手可能与你的产品进行交互的人。Ramp 的项目经理会使用你的 API 发布功能吗？他可能永远不会直接阅读您的文档。但他们的人工智能代理绝对会。

这对文档意味着什么

如果文档现在要为人类读者和人工智能中介这两种受众服务，那么它就需要同时为这两种受众服务。听起来很明显。但实际上，几乎没人这么做。

以下是我认为真正重要的内容：

**机器可读格式与人类可读格式并存。**如果你的 API 文档是一个精美的 HTML 页面，而 LLM 不得不对其进行搜刮和解析，那么人工智能的工作就会比它应该做的更辛苦。在提供渲染版本的同时，也要提供原始的 OpenAPI 规范。提供简洁的标记符。无需人工智能解释页面布局即可访问规范。

**人工智能助手不会一页一页地阅读文档。它们会提取相关部分。对于人工智能来说，标题清晰、段落自足、块级语义明确的文档，要比需要阅读整页才能了解上下文的流畅叙述有用得多。

信任机器可以阅读的信号 这份文档上一次审核是什么时候？是否仍然有效？内容是否被标记过？这些信号需要以人工智能可以访问的形式存在，而不仅仅是网页上的视觉提示。新鲜度评分、过期状态、审核日期，这些元数据可以让人工智能决定是否可以安全地将文档用作信息源。

**新鲜度是先决条件，而不是特征。**当人工智能助手根据一个已废弃的端点向构建者提供一个有把握的答案时，所造成的损失比404更严重。构建者会在此基础上进行构建。将其交付使用。然后它就在生产中崩溃了，没人知道原因，直到有人追溯到几个月前就应该更新的文档。人工智能可能参考的每一份文档都需要一种机制来证明它仍然是最新的。(这正是我们构建 Rasepi 所要解决的问题。文件块强制过期，这样陈旧的内容就无法隐藏）。

开始：审核当前文档

如果你读到这里还在想 "好吧，但我周一到底要做什么呢？"那么，以下是你本周可以检查的四件具体事情。

1.通过人工智能测试你的文档。 打开 Claude 或 ChatGPT，让它在现实场景中整合你的产品。不要使用你的内部知识。只需查看人工智能生成的结果。是否正确？是否最新？是否使用了正确的端点、正确的 SDK 版本和正确的认证流程？如果人工智能弄错了，那就是构建者现在得到的结果。

2.检查是否有过时的内容。 挑选五个访问量最大的文档页面，并询问：上次审查是什么时候？它是否仍然描述了产品的当前状态？如果你不能自信地回答这个问题，人工智能也无法回答。对于大多数团队来说，这是最有效的修复方法。

3.提供机器可读格式 如果您没有 /llms.txt文件，请创建一个。如果您的 API 参考只能以渲染 HTML 的形式提供，请导出原始 OpenAPI 规范并使其可访问。如果你的文档使用的 CMS 不能输出干净的标记符，这也是一个值得现在就解决的问题。

4.添加审核日期和新鲜度元数据。 即使是很简单的事情，在内容管理系统中添加last-reviewed字段，为高流量页面设定一个强制审核周期。这将为人类和人工智能提供内容是否可信的信号。像 Rasepi 这样的工具可以通过在区块级别强制过期来实现自动化，但即使是手动流程也聊胜于无。

产品表现方式的悄然转变

这一切还有一个更广泛的结果值得直接说明。

您的文档不再仅仅是开发人员的参考手册。它是人工智能助手用来向世界展示产品的原始资料。当一个开发者向克劳德询问如何使用你的产品时，克劳德的回答会根据它能从你的文档中找到并解析的内容来确定。

文档好，答案就好。过时的、含糊不清的、锁定在模型难以解析的 HTML 中？那就是更差的答案，或者是不正确的答案。就这么简单。

现在，人工智能对产品的回答质量直接代表了开发人员的体验。大多数公司还没有这样做。

在这方面走在前面的团队，如 Stripe、Vercel、Cloudflare 和 Anthropic 本身，都将人工智能的可读性视为头等大事。这是一项基础性要求，决定了文档的编写、结构和维护方式。而不是下一季度的积压项目。

现在，构建者坐在克劳德的办公室里，描述着他们想要构建的东西，期待着几分钟内就能完成代码。他们可能再也不会访问文档网站了。但为他们提供服务的人工智能会。持续不断

该人工智能现在是您最常见的读者。问题是，您的文档是否已经为此做好了准备。

2026 年最佳开发人员体验战略不是会议演讲或快速入门指南。而是要确保人工智能能够正确处理。

本文章参考了公开的研究和产品文档。统计数据来自 GitHub 2024 年开发人员调查、Stack Overflow 2024 年开发人员调查、Index.dev 2026 年开发人员生产力报告、Incremys Claude 统计数据，以及 Fortune 关于 Anthropic 的报道。/llms.txt规范由llmstxt.org维护。模型上下文协议在 modelcontextprotocol.io. 进行了记录。

Rasepi 翻译是如何工作的？

2026-03-31T00:00:00Z

如果你曾通过 Google 翻译或任何翻译工具运行过文档，你就会知道结果如何。技术上正确。语气错误。你的产品突然叫法不同了。你团队的内部速记消失了。正式的 "你"，你的公司用非正式的，或者反过来。

虽然翻译出来了，但听起来不像你。

这就是我建立 Rasepi 翻译系统的初衷。不是 "我们能不能翻译文档"（现在每个工具都能做到），而是 "我们能不能翻译得让它听起来像我们团队写的"。

答案是肯定的。而且不需要专业翻译团队就能实现。

听起来像您团队的翻译](/zh/blog/img/natural-translations.svg)

##只有改变的内容才会被翻译

大多数文档平台都会翻译整个页面。你改了一句话，整个文档就会被重新翻译。每种语言、每个段落，无论是否有改动。

拉塞皮的工作方式与此不同。它可以单独跟踪每个段落。当您编辑 20 个段落中的一个段落时，只有该段落会被重新翻译。其他 19 个段落则保持原样。

这意味着两件事：

1.**您的翻译成本会大幅下降。**我们所说的是典型编辑成本的 94%。大多数更新只涉及一两个部分，而不是整个页面。 2.**如果您的德国团队上周批准了一个译文，那么编辑一个无关的英文段落不会影响他们批准的文本。

系统知道哪些内容发生了变化，因为每个段落都有一个唯一的身份和内容指纹。当指纹发生变化时，该特定段落就会被标记为需要重译。除此之外，别无其他。

##你的词汇表，你的术语

有趣的地方就在这里。

每个公司都有自己的词汇。在德语文档中，"Sprint Review "可能保留为 "Sprint Review"，因为柏林团队使用的是英语术语。也可能变成 "Sprint-Überprüfung"，因为慕尼黑团队更喜欢德语版本。"知识库 "可能是 "Wissensdatenbank "或 "Knowledge Base"，也可能是团队内部创造的完全不同的术语。

拉塞皮让您为每种语言建立词汇表。基本上是一个术语及其认可翻译的列表。当翻译一个段落时，系统会首先检查您的词汇表。词汇表中的每个术语都会按照您的定义翻译。每次都是如此。每份文档都是如此。

您可以直接在 Rasepi 中管理您的词汇表：

当您发现术语不一致时，可逐个添加术语**。
导入 CSV**，如果您已经从其他系统中获得了术语表
导出词汇表**，与外部翻译人员或其他工具共享

词汇表按语言对工作。英译德词汇表与英译法词汇表是分开的。这很重要，因为同一个英语术语在不同的语言中可能需要不同的处理方式。"Sprint Review "在德语中可能仍然是英语，但在日语中可能会被翻译成英语。

当您更新词汇表时，下一次将任何段落翻译成该语言时，更改就会生效。无需手动重新翻译所有内容。下一个自然编辑周期就会接收。

样式规则：让译文听起来像你写的一样

词汇表可以处理单个词汇。但译文可以使用所有正确的术语，但仍会让人感觉不对。错误的语气。日期格式不对。数字的分隔符不对货币符号放错位置。

这就是风格规则的作用。

您可以为每种语言设置一系列规则，控制翻译的样式：

格式约定

这些细节能让文档给人母语的感觉，而不是 "明显是从英语翻译过来的"：

日期和时间格式：** 德语为 24 小时制，英语为上午/下午，等等。
数字格式：** 德语中用逗号作为小数分隔符（3,14 而不是 3.14），用句号表示千位数
**标点符号规则。**学位格式、引号样式和其他地区性惯例

您可以选择符合贵公司标准的惯例。Rasepi 会将其应用于该语言的所有翻译，以及所有文档。

###自定义说明

这就是功能强大的地方。自定义指令是一种纯语言指令，它告诉翻译引擎如何处理您的内容。您可以将其写入普通句子中，然后引擎就会按照这些句子进行翻译。

举几个例子

对于需要平易近人的文档的公司，*"使用友好的外交语气
"始终使用正式的'Sie'形式，而不是'du'"* 用于专业德语交流
使用英式英语拼写：color、organisation、licence "* 适用于英语受众为英国人的情况
在数字金额后加上货币符号 "* 以符合欧洲惯例
"在描述应用程序接口端点时，使用命令式语气 " 适用于应该让人感觉直接的技术文档

每种语言最多可添加 200 条自定义说明。它们与词汇表和格式化规则一起工作，翻译引擎会在每次翻译时一并考虑它们。

###格式

德语有 "du "和 "Sie"。法语有 "tu "和 "vous"。日语有多级礼貌。即使是没有明显正式/非正式代词的语言，其声调差异也很重要。

通过 Rasepi，您可以设置每种语言的正式程度。配置完成后，每个翻译段落都会与该语气相匹配。如果您的公司用法语正式地称呼读者（"vous"），而用德语非正式地称呼读者（"du"），那么每个译文都会这样做。

一切协同工作

重要的是：术语表、格式约定、自定义说明和正式性设置都同时适用于每份译文。你不能选择其中一个或另一个。您只需将它们全部设置一次，然后翻译的每个段落都要遵循同一套规则。

这样，译文读起来就像本地团队的人写的一样。而不是由一台机器在对贵公司一无所知的情况下翻译出每一个句子。

##每种语言都有自己的内容

这是最令人惊讶的功能。

在拉塞皮，翻译文件并不是原文件的锁定副本。每个语言版本都可以拥有只存在于该语言中的内容。

**为什么这很重要？

因为不同的市场需要不同的东西：

您的德文文档可能需要符合 DSGVO（GDPR）的部分，而这部分不适用于美国版本
您的日本团队可能需要一份关于当地工具的说明，而其他人都不使用这些工具
您的巴西办事处可能需要有关地区税务法规的背景信息

在大多数翻译工具中，向一种语言版本添加内容意味着下次有人从英语重新翻译时，这些内容会被覆盖。团队很快就发现了这一点，并停止添加本地内容。他们会在 Notion、Slack 或其他地方创建影子文档，现在你就拥有了两个没有人完全信任的系统。

在 Rasepi 中，独一无二的内容会被标记为属于该语言。它不会被重译覆盖。当英语源发生变化时，它也不会被删除。它与翻译内容并存，是文档的自然组成部分。

结构也是如此。如果您的日语翻译人员喜欢使用编号列表，而英语版本则使用子弹（日语技术写作中的常见惯例），他们可以更改格式。拉塞皮会在今后的更新中保留这一选择。

每个语言版本都是一流的文档，而不是只读镜像。

自动与人工：共同协作

Rasepi 不会强迫您在机器翻译和人工翻译之间做出选择。它同时支持机器翻译和人工翻译，而且知道两者的区别。

当一个段落被机器翻译后，源文件发生变化时，拉塞皮会自动重新翻译。无需人工干预。词汇表和风格规则保持一致。

当一个段落经过人工翻译时，也许他们为了文化上的细微差别进行了改写，或者添加了机器无法捕捉的上下文，拉塞皮都会尊重他们的工作。如果源文件发生变化，系统会将该段落标记为需要审核，但不会默默覆盖人工编辑。译员可以看到源代码中的变化，并决定如何更新自己的版本。

这意味着您的翻译质量会随着时间的推移而提高。机器翻译会处理大部分内容。人工译员则专注于需要人工润色的段落。两者互不影响对方的工作。

两种模式：始终保持当前状态或按需翻译

对于每种语言，您都可以选择何时进行翻译：

每次有人保存源文件时，都会立即重新翻译已更改的段落。最适合最重要的语言，因为读者希望获得最新的准确性。
更改的段落会被标记，但不会翻译，直到有人实际打开该语言的文档。非常适合使用频率较低的语言。不会在无人阅读的内容上浪费翻译成本。

两种模式使用相同的词汇表、相同的样式规则和相同的质量。唯一的区别在于时间。

##实际效果

假设您经营一家公司，在伦敦、慕尼黑、巴黎和东京都有团队。您的文档是用英语编写的。

伦敦的产品经理更新了部署指南。其中一节涉及新的 CI/CD 步骤。

情况如下

**德语（始终翻译）。**更改后的部分在几秒钟内被重新翻译。"Sprint Review "变成了 "Sprint-Überprüfung"，因为这是术语表中的术语。正式的 "Sie"，因为这是您的正式设置。日期使用 24 小时格式，因为这是您的配置规则。自定义指令 "使用直接、命令式的语气 "决定了措辞。慕尼黑团队添加的 DSGVO 部分？未经修改。
** 法文（始终翻译）。** 相同部分，立即重新翻译。采用 "Vous "形式。使用法语词汇表术语。根据您的自定义指示，在数字后添加货币符号。文件的其余部分与巴黎办事处上次审阅时的内容保持一致。
** 日语（查看时翻译）。** 更改的部分标记为过期。当东京的某个人打开文档时，文档会被即时翻译。他们自定义的数字列表格式将被保留。他们的本地工具注释保持不变。

一次编辑。更新三种语言。零文档重译。术语一致、语气一致，尊重每个团队的本地补充。

##谈到语言质量

所有这一切背后的翻译引擎是 DeepL，该技术与 Rasepi 的与文档对话功能相同。您可以与文档对话，并大声得到答案。DeepL Voice 处理口语交互，这意味着书面翻译中的术语一致性、风格规则和语言质量也同样适用于语音对话。无论您的团队是在读还是在听，您的词汇表术语和自定义说明都能听起来准确无误。

让您的团队听起来像您的团队的翻译并不奢侈。对于跨语言运营的公司来说，它们是人们信任的文档与人们应付的文档之间的区别。词汇表、风格规则、自定义说明、智能重译和每种语言的独特内容使之成为可能。从第一天起，自动实现。

您的文档在每种语言中都应该听起来像您的团队。而不是一台机器。不像另一家公司。像你自己。

查看多语种出版操作 →

翻译引擎内部：词汇表、风格规则和智能重译

2026-03-31T00:00:00Z

我们的[上一篇架构文章]（/en/blog/how-plugin-guardrail-and-pipeline-systems-work/）介绍了插件、动作保护和管道系统。这篇文章深入探讨了翻译引擎，我认为它是 Rasepi 与其他文档平台的根本区别所在。

这不是关于翻译段落而非页面的营销宣传。而是实际代码。每个租户如何解决词汇表问题，DeepL 的样式规则和自定义指令如何影响每次翻译，内容散列如何驱动陈旧检测，以及协调器如何决定哪些区块需要重新翻译。

翻译引擎：词汇表、样式规则和智能重译](/zh/blog/img/translation-engine-deep-dive.svg)

翻译流水线

当用户保存文档时，系统不会简单地重新翻译所有内容。它会运行一个相当特定的序列：

1.将 TipTap JSON 解析为单个块 2.比较内容哈希值，检测哪些区块发生了实际变化 3.对于已更改的区块，解析语言对的租户词汇表和样式规则列表 4.应用租户配置中的样式规则、自定义说明和格式 5. 5.仅向 DeepL 发送已更改的块 6.更新翻译块并同步内容哈希值

每个步骤都有自己的服务和接口。这一点很重要，因为任何一个步骤都可以换成其他东西，不同的翻译提供商、不同的哈希算法、不同的词汇表来源。

词汇表解析：租户范围、DeepL 同步

DeepL 词汇表有一个大多数人不知道的限制：** 它们是不可变的。** 您无法编辑 DeepL 词汇表。任何更改都意味着删除旧的词汇表并创建新的词汇表。

Rasepi 将数据库视为真理之源，将 DeepL 词汇表视为可丢弃的运行时工件。TenantGlossary 实体在本地存储所有内容：

代码块_0_

当用户添加词汇表条目时，例如将 EN→DE 的 "Sprint Review "映射为 "Sprint-Überprüfung"，数据库记录会立即更新，IsDirty会被设置为 true。DeepL 词汇表不会在此时重新创建。它会在下一次翻译实际需要它时被懒散地重新创建。

同步流程

在每次翻译调用之前，系统都会解析词汇表：

代码块_1__

这里有三点值得注意：

1.**我们只在真正需要翻译时才调用 DeepL API。批量编辑词汇表条目不会触发数十次 API 调用。 2.2. 租户隔离。 查询通过 EF 全局查询过滤器运行，因此 TenantGlossaries 会被自动范围化。租户 A 的词汇表条目绝不会泄漏到租户 B 的翻译中。 3.每对语言只使用一个词汇表。 DeepL 会强制执行这一规定。一个 EN→DE 词汇表，一个 EN→FR 词汇表，以此类推。每个租户的 (SourceLanguage, TargetLanguage) 对是唯一的。

词汇表条目

单个词条只是术语映射：

代码块_2___

API 为您提供完整的 CRUD 和 CSV 导入/导出功能，以便进行批量管理：

代码块_3_

CSV 导入对于从现有翻译记忆库系统迁移的团队来说非常有用。导出术语、清理术语、导入 Rasepi，下一次翻译运行就会自动使用新的术语表。

风格规则、自定义说明和正式性

词汇表处理术语。但术语只是其中的一半。翻译可以使用所有正确的词汇，但听起来仍然是错误的。错误的语气、错误的日期格式、错误的标点习惯。

DeepL 的 ** 样式规则 API** (v3) 解决了这个问题。您可以创建可重复使用的样式规则列表，将两种类型的控件结合起来：

1.** 配置规则**，预定义的日期、时间、标点符号、数字等格式约定 2.自定义说明，自由文本指令，可塑造语气、措辞和特定领域的惯例

Rasepi 为每个租户、每种目标语言创建并管理这些指令。TenantStyleRuleList 实体将 DeepL style_id 与租户配置的规则和自定义指令一起存储：

代码块_4_

创建样式规则列表

当管理员为德语设置翻译规则时，Rasepi 会调用 DeepL 的 v3 API 创建样式规则列表。如下所示

codeblock_5

与词汇表不同，DeepL 样式规则列表是可变的。您可以使用 _______________________________________________________________________替换已配置的规则，也可以单独添加、更新或删除自定义指令。这对于迭代改进来说要友好得多。

配置的规则看起来像什么

配置规则涵盖了因语言或公司偏好而异的格式约定。比如

codeblock_6

这些规则听起来很琐碎，但复合起来却很快。一份使用 AM/PM 时间格式和以句号分隔的小数点的德文文档，对于德文读者来说只是 "从英文翻译过来的"。为所有德语翻译的小数分隔符设置 use_24_hour_clock 和 use_comma_，可以立即消除这种情况。

自定义指令：这才是真正的力量

自定义指令是自由文本指令，每个样式规则列表最多 200 条，每条指令最多 300 个字符。基本上，您可以用简洁的语言告诉 DeepL 如何塑造翻译：

codeblock_7

来自我们租户的真实例子：

"Always use 'Sie' form, never 'du'" 适用于一家德国律师事务所
__DEBLOCK_28___用于需要根据上下文处理的术语，而非简单的词汇表映射
___DEBLOCK_29____用于英国公司的英语变体之间的翻译

自定义指令对于不适合放在词汇表条目中的特定领域惯例来说非常强大。词汇表将一个术语映射到另一个术语。自定义指令可以说 "翻译 API 文档时，使用命令式语气而不是被动语态"。这是一种完全不同的控制方式。

形式

DeepL 的 formality 参数（default, more, less, prefer_more, prefer_less）仍可作为单独的控件与样式规则一起使用。德语 "du "与 "Sie"、法语 "tu "与 "vous"、日语礼貌等级。这些都是通过TenantLanguageConfig_为每种租户语言设置的：

代码块_8__

格式、风格规则和词汇表都是一个整体。一次翻译调用可包含所有三项内容：

代码块 9

这里有两点值得注意：

1.**我们将相邻的代码块作为上下文传递，以提高翻译质量。DeepL 使用它来解决歧义问题，但不翻译或计费。一个关于 "单元格 "的段落，当周围的上下文是生物文档和电子表格手册时，翻译效果就会不同。 2.**任何带有 style_id 或 custom_instructions 的请求都会自动使用 DeepL 的 quality_optimized 模型。这是最高质量层。您不能将它们与 latency_optimized 结合使用，这是 DeepL 故意作出的限制。风格定制需要完整的模型。

###为什么这比你想象的更重要

想象一下，一家公司在用德语编写内部文档时使用非正式的 "du"，而在翻译部分突然改用正式的 "Sie"。说得好听点是不一致，说得难听点就是不专业。正规性可以解决这个问题。但是，如果您的德国办公室使用 24 小时制，而您的文档却使用 AM/PM 时间戳，或者将货币符号放在数字前而不是数字后，那么仅凭正式性是无法解决这个问题的。

所有这些叠加在一起（样式规则、自定义说明、格式化、词汇表）产生的译文读起来就像你团队中的某个人写的一样。而不是从一台不知道贵公司存在的机器上输出。

DeepL 服务层

所有 DeepL 通信都要通过 IDeepLService。它封装了官方 DeepL .NET SDK，并处理样式规则的 v3 API 调用：

代码块_10_

实现处理语言代码规范化。DeepL 需要 EN-US 或 EN-GB，而不是简单的 en，还需要 PT-PT 或 PT-BR，而不是 pt：

代码块_11_

批量翻译使用 50 个项目的分块，以保持在 DeepL 的 API 限制范围内，同时最大限度地提高吞吐量：

代码块 12

由于我们只发送陈旧的分块，而不是整个文档，因此单个编辑的典型翻译批次只包含 1-3 个分块，而不是 40 多个。这就是成本降低 94% 的原因所在。

翻译协调器

当源文件发生变化时，TranslationOrchestrator_ 会决定如何处理每个区块。让我们来看看决策树：

代码块_13__

关键点**如果译员手动调整了一个语块，可能是添加了文化背景或重新措辞以求清晰，系统会尊重译员的工作。系统会将区块标记为 "过期"，以便译员知道源代码发生了变化，但不会默默替换他们的编辑。

启用 AlwaysTranslate 的机器翻译区块会被立即重译。使用 TranslateOnFirstVisit 的机器翻译块会被标记为过时，并在有人实际打开该语言文档时进行翻译。

翻译触发器：翻译何时发生

每种语言都有一个 _DEBLOCK_53，用于控制时间：

codeblock_14

AlwaysTranslate_对于需要立即翻译的高优先级语言非常有用。法语适用于在巴黎设有大型办事处的公司。德语适用于总部设在慕尼黑的公司。

_CODEBLOCK_55__适用于偶尔需要但不值得花费 API 成本使其始终保持完全最新的语言。当有人用该语言打开文档时，过时的语块会被即时翻译。

这两种模式使用相同的词汇表分辨率、相同的格式设置和相同的内容散列。唯一的区别在于时间安排。

独特的内容和结构适应性

这就是架构的真正价值所在，而不仅仅是翻译。

当德语翻译人员添加英语中不存在的 DSGVO 合规性部分时，他们会将其作为一个新块添加到德语版本中。系统从未将其发送给重新翻译，因为没有翻译源。它只存在于德语版中。

当日语翻译人员将项目列表改为编号列表时（这是日语技术写作中的一种常见习惯），该语块的 IsStructureAdapted 标记会在今后的重译周期中保留下来：

代码块_15_

IsNoTranslate 标志用于处理应逐字复制的内容：代码块、URL、产品名称、数学符号。翻译提供程序会完全跳过这些内容。

将所有内容放在一起

让我们来看看整个流程。伦敦的一位用户编辑了英文源文档中的一个段落，而慕尼黑办公室将德语设置为 _____________________________________________：

1.用户保存 TipTap 发送 JSON 到 API。 2.**CreateBlocksFromDocumentAsync 解析 JSON，重新计算内容哈希值，并比较新旧哈希值，以确定哪些区块实际发生了更改。 3.**找到德语 EntryTranslation，检查德语区块。它是机器翻译的，没有锁定，也未经人工编辑，因此符合重译条件。 4.**通过 GetOrSyncDeepLGlossaryIdAsync("en", "de")解决词汇 ID 问题，通过 GetOrSyncStyleRuleListAsync("de")解决风格规则问题，格式设置为 "more"（正式名称为 "Sie"），相邻区块作为上下文进行消歧义处理。 5.DeepL call. 发送包含词汇表 ID、样式 ID、格式和上下文的单个块。 6.**存储翻译内容，同步 SourceContentHash，状态设置为 UpToDate。翻译了一个区块，而不是 40 多个。其余 39 个区块呢？没动。

与此同时，东京办公室的日语设置为 TranslateOnFirstVisit_。同样的编辑将日语翻译块标记为 Stale。当东京的某个人打开文档时，第 5-9 步会自动执行。它们的结构调整（编号列表）被保留下来。它们的独特块会保持原样。

我认为翻译引擎是 Rasepi 中最能体现价值的部分。翻译使用您的术语，遵循您的格式约定，遵从您的自定义指令，符合您的语气，尊重您的译员的工作，而且成本仅为全文重译的一小部分。该架构可自动完成所有这些工作，并在人类想要接手时不插手。

支持书面翻译的 DeepL 引擎同样支持 Talk to Docs（我们的会话文档界面），DeepL Voice 负责口语交互。同样的词汇表、同样的风格规则、同样的形式、同样的一致性。无论您的团队是阅读文档还是与文档对话，语言质量都是相同的。

探索翻译 API →

停止保留同一文档的五个副本

2026-03-31T00:00:00Z

现在打开公司维基，搜索 "onboarding"。你会得到多少结果？

如果你是一家全球性公司，我猜一个都没有。可能是这样的

编码块_0_
编码块_1_
编码块_2_
编码块_3_
编码块_4_

五份文件。内容大致相同。都略有不同。都由不同的人按照不同的时间表维护。有些是当前的，有些是三个月后的，还有一份已经没人能确定了。

这就是文档平台无法正确处理多语言内容的后果。最终，你会为每个市场复制整个文档，而每个副本都会慢慢地与其他副本相去甚远。

一份文档，多种语言](/zh/blog/img/one-document-all-languages.svg)

复制和本地化陷阱

开始时很简单。你有一份很好的英文版入职指南。柏林办事处需要德文版，于是有人复制、翻译并添加了德国特有的内容：DSGVO 培训、Betriebsrat 信息、当地医疗保险注册。

然后东京也需要一份。再次复制。翻译。添加日本特有的内容：韩流登记、通勤证办理流程、办公室礼仪指南。

接下来是圣保罗。也是一样。复制、翻译、添加有关 CLT 要求、餐券和税务文件的本地内容。

现在您有了四份文件。英文原文会定期更新。德文版在上个季度更新过。日文版......有人认为田中先生在 10 月份更新过。巴西版是由一个承包商创建的，他离开后就没人再碰过了。

每个副本都是维护负担，每个副本都包含共享内容（各地相同的内容）和本地内容（该市场特有的内容）。但平台并不知道其中的区别。所有内容都只是页面上的文字。

因此，当有人更新英文原文中的安全策略部分时，没有人会更新其他四个部分。更糟糕的是，有人更新了德文版，却没有更新日文版。现在，你有五份文件，对同一公司政策的表述都略有不同。

真正的问题：共享内容和本地内容混在一起

问题是，这些文件中的大部分有 70-80% 是相同的。入职步骤、工具设置、安全政策、公司价值观部分、"联系人 "列表。无论你在柏林、东京还是圣保罗，这些都是一样的。

本地内容可能只占文件的 20-30%。具体的合规要求、当地福利、地区流程、该办事处的团队联系人。

但是，如果所有内容都按语言放在一个大的平面文档中，就无法分辨哪些是共享内容，哪些是本地内容。更新共享内容意味着要手动检查和更新每一份副本。没有人会始终如一地这样做。这就是拷贝漂移的原因。

一个文档。就是这样。

在拉塞皮，入职指南就是一份文件。不是每种语言一份。一份。

共享内容，即 70-80% 的内容在任何地方都是一样的，用英语编写一次，然后自动翻译成团队使用的每种语言。当有人用英语更新安全策略部分时，它就会在几秒钟内被重新翻译成德语、日语、葡萄牙语和法语。无需手动复制。不会出现 "应该有人更新其他版本 "的情况。

本地内容存在于各自的语言版本中。DSGVO 培训部分只存在于德语版本中。汉考流程只存在于日语版本中。CLT 要求仅存在于葡萄牙语版本中。这些部分被标记为独有内容，属于该语言，不会被重译覆盖。

我们在[Rasepi 翻译的工作原理]（/en/blog/how-rasepi-translations-work-and-why-they-sound-like-your-team/）一文中介绍了具体的工作原理。简而言之：每个段落都有自己的身份。共享段落会被翻译和跟踪。独有段落只属于自己的语言，其他任何语言都无法触及。

结果如何？在维基上搜索 "onboarding"，只有一个结果。只有 "入职"。用英语打开，你会看到包含所有共享内容的英语版本。打开德文版，你会看到德文版的相同共享内容，以及德国特有的部分。打开日文版，同样是日文版的共享内容，外加日本特有的部分。

一份文档。不是五个。而不是五个文件以不同的速度慢慢腐烂。

这实际上改变了什么

这不仅仅是更整洁。它从根本上改变了各办公室的文档工作方式。

###更新可以真正送达每个人

当您更新入职指南的共享部分时，每种语言都会更新。不是最终更新，也不是在有人记得更新之后更新。而是自动更新。您更改的段落会被重新翻译。其他内容则保持原样。

这就意味着，东京办公室和伦敦办公室读到的公司政策是一样的。而不是六个月前的版本，因为没有人去更新。

###本地团队拥有自己的本地内容

您的慕尼黑团队可以添加有关当地健身房折扣的内容，而不必担心这些内容会被下一次英文版更新所删除。他们的内容是独一无二的。这些内容将保留在德语版本中，不会因英语版本的任何更改而受到影响。

其他办公室也是如此。本地内容是真正的本地内容。它不会干扰共享内容，共享内容也不会干扰它。

###新员工获得正确的信息

圣保罗的新员工打开入职指南，就能看到所需的一切。共享部分（工具、安全、价值观）是葡萄牙语。巴西特有的部分（CLT、税务文件、餐券）就在旁边。一份文件，所有内容都用他们的语言编写，没有遗漏，没有过时。

他们不需要知道其他三个办事处有不同的本地部分。他们只需看到自己的版本。干净、完整。

页数减少

这是一个简单的数学问题。如果您有 50 个关键文档，并用复制和本地化的方法用 5 种语言进行维护，那么您就有 250 个文档。而在 Rasepi 中，您有 50 个文件。每个语言版本都有共同的内容，并维护各自的本地部分。

维护 250 个文档与维护 50 个文档相比。这样，200 页的维护开销就消失了。

不仅仅是入职培训

入职培训是一个明显的例子，因为每家全球性公司都存在这个问题。但同样的模式也随处可见：

** 部署指南。** 核心步骤相同，但柏林团队使用本地暂存服务器，东京则采用不同的审批流程。
合规文档：** 欧洲的 GDPR 部分，巴西的 LGPD 部分，日本的 APPI 部分。所有文件都在同一个文档中，只在相关的地方出现。
每个国家的育儿假政策都不同。公司价值观在任何地方都是一样的。
** 面向客户的帮助文档。** 产品在任何地方都能正常运行，但支付方式、支持时间和地区法规各不相同。

大多数公司都会为每个市场保留不同的文件副本。而每一份文档都可以是具有共享内容和本地内容的单一文档。

复合效应

这就是问题的关键所在。一家在 4 个市场中拥有 200 个文档的公司并不是在维护 200 个文档。他们要维护 800 份文件。但他们的人员编制是 200 人。所以实际情况是

英文版本是最新的
德语版本大部分是最新的
法语版本落后
日语版本是个问号

听起来熟悉吗？

在拉塞皮，他们维护着 200 份文件。共享内容自动翻译。本地内容由本地团队添加。每个版本都与英文版本一样新，再加上地区团队添加的本地内容。

翻译成本也更低。当您更新一个英文段落时，只有该段落会被重新翻译成所有语言。不是整个文档，也不是所有 200 个文档。只对实际发生变化的段落进行翻译。我们详细介绍了如何工作，包括术语表和使翻译内容听起来自然的风格规则。

快速直觉检查

如果您正在管理一个全球性团队，请扪心自问：

1.你有多少重复的文档？搜索相同的主题，并计算特定语言的副本。 2.2. 非英语版本的最新情况如何？ 检查德语、法语或日语文档的最后编辑日期。它们落后多少？ 3.**本地团队是否会在其版本中添加内容？ 4.**4. **非英语办事处的入职培训需要多长时间？

如果这些答案让你感到不舒服，那么你并不孤单。大多数公司在实际清点副本之前，都不会意识到自己造成了多少开销。

文档应该与公司同步发展，而不是成倍增加。你维护的每一份副本都可能落后于时代，使新员工感到困惑，或与其他人正在阅读的版本相矛盾。每个主题一份文档，共享内容翻译成本地内容，这才是全球化公司的文档工作方式。

您的维基站点不需要同一文档的五个副本。一份就够了。共享步骤已翻译，本地步骤按语言划分。就是这样。

查看多语种发布操作 →

块级本地化的商业案例

2026-03-24T00:00:00Z

每家跨国运营的公司都有这样的模式。英文文档很可靠。德语版本落后三个月。日文版只由承包商翻译过一次，之后就再没人碰过。巴西葡萄牙语版本还不存在，尽管圣保罗是增长最快的办事处。

每个人都认为这是一个问题。但没人有好的解决方案。到目前为止，本地化一直被视为一个项目，是一次性的工作，你需要为其编列预算、执行，然后悄悄地忽视它，直到下一次大修。

这种做法是错误的。以下是原因，以及我认为真正有效的方法。

翻译不是本地化

让我们把术语搞清楚。翻译是将一种语言的文本翻译成另一种语言的等效文本。本地化是让知识在特定市场发挥作用。它们有重叠，但不是一回事。

翻译后的文件阅读正确。本地化文件读起来自然。它考虑到了文化背景、地区法规、本地工具以及该市场中人们的实际工作方式。

这一区别很重要，因为大多数文档平台都将本地化视为一项翻译任务。你用英语写作，按下按钮，然后得到法语输出。这就完成了。但这并没有完成，因为

法国团队有不同的部署流程，而英文文档没有涵盖这些流程
德国的合规性要求增加了一个额外的审批步骤，而这在其他地方是不存在的
日本办事处在相同的工作流程中使用了不同的内部工具
巴西葡萄牙语读者需要了解当地税务规则的背景，而这些规则在其他地方并不相关

**在所有这些情况下，直接翻译英文文档在技术上都是正确的，但实际上也都是无用的。

文档级翻译的问题

传统的本地化工作是在文档层面进行的。您有一份英文文档。您将整个文档翻译成德语。当英文版本发生变化时，您又将整个文档重新翻译。这会产生三个问题：

1.费用昂贵

如果您的入职指南有 15 个部分，而您只改动了一个段落，那么您就需要支付重新翻译所有 15 个部分的费用。再乘以 8 种语言，每次编辑都是一次预算对话。

2.速度慢

发送完整的文件进行翻译需要时间。即使使用现代机器翻译，一份完整文档的审校周期也要比审校一个有改动的部分长很多。其他语言的团队总是跟不上。

3.不支持独特内容

这是真正的杀手。如果德文版需要一个关于 DSGVO 合规性的额外章节，它该放在哪里？在文档级翻译系统中，任何添加到德语版本的内容都会在下一次有人从英语重新翻译时被覆盖。德语团队很快就明白了：不要添加任何内容，因为这些内容都会被覆盖掉。

块级本地化：不同的架构

Rasepi 不翻译文档。它翻译的是：单独的段落、标题和章节，每个段落、标题和章节都有自己的标识和内容哈希值。

这在实践中意味着什么？

当您编辑一个英文段落时，Rasepi 会通过比较 SHA256 内容哈希值来检测哪个段落发生了变化。只有这一个区块会通过 DeepL 发送翻译。文档中的其他 14 个区块则保持原样。您的翻译成本最多可降低 94%。

当德语翻译人员需要添加 DSGVO 部分时，他们会将其作为一个新的块添加到德语版本中。该区块只存在于德语版本中。它不会影响英文源文件。当英文版本发生变化时，它也不会被覆盖。它被标记为独一无二的内容，因此每个人都知道这是有意为之。

当日文版需要不同的结构时，例如，由于日文技术写作的惯例，需要用编号列表代替项目符号，译者可以更改语块类型。系统会将此作为 "结构调整 "进行跟踪，并在今后的更新中予以保留。

每个语言版本都将成为一流的文档，而不是影子副本。

技术上的工作原理

Rasepi 中的每个区块都有

一个 UUID**，在所有编辑和翻译中持续存在
一个内容哈希值**（SHA256），当文本发生变化时，哈希值也随之变化
一个位置索引**，以便区块保持正确的顺序
软删除标志**，因此删除英文区块不会破坏其他语言的对齐方式

创建翻译区块时，系统会存储源区块的内容哈希值。每次保存时，系统都会比较哈希值。如果它们匹配，翻译就是当前的。如果不匹配，翻译就会被标记为过时，只有该特定块需要关注。

这就是成本降低 94% 背后的机制。大多数编辑都是修改一两个部分。文档的其余部分，包括所有语言，则保持不变。

每种语言的独特内容

这是与其他平台真正不同的地方。

在 Rasepi 中，每种语言版本都可以包含以下内容

翻译区块**源语言的直接翻译，并对其陈旧性进行跟踪。
独特的区块：** 仅存在于该语言中的内容，由本地团队添加
** 结构调整区块。** 相同的源内容，不同的格式或区块类型

不同语言的单个文档可能是这样的：

| 块 | 英语（源） | 德语 | 日语 | 英语（源） | 德语 | 日语 | 英语（源） | 德语 | 日语 |-------|------------------|--------|----------| | 1 | 简介 | 已翻译 | 已翻译 | 已翻译 | 已翻译 | 2 | 设置步骤 | 已翻译 | 结构调整（编号列表） | | 3 | - | 设置步骤 | 3 | - | DSGVO 合规性（唯一性） | - | | | 4 | 部署 | 已翻译 | 已翻译 | 5 | - | - | 本地工具说明（唯一 6 | 故障排除 | 已翻译 | 已翻译 | | | | | | | | | | | | | | | | | | | | | 翻译

每个团队都能准确获得所需的文档。没有妥协。没有变通办法。没有一刀切的限制。

跨语言的新鲜度跟踪

每种语言版本都独立跟踪自己的新鲜度。英文版的新鲜度可能达到 94 分（最近审核、所有链接有效、阅读量高）。法文版可能得分为 71 分（两个陈旧的区块，一个法文内容特有的断开链接）。日文版可能得 88 分（所有翻译都是最新的，但读者数量正在下降）。

这种按语言进行的新鲜度跟踪意味着：

您可以清楚地知道哪些语言需要关注
过时的翻译会自动浮出水面，而不是意外发现
人工智能工具可在提供答案时考虑特定语言的新鲜度
仪表板按语言而不仅仅是文档显示内容健康状况

商业案例

跨语言运营的公司面临着一个简单的现实：在您服务的每个市场中，您的文档要么是资产，要么是负债。

如果您的柏林团队使用的德文译本比英文译本晚三个月，他们就会根据过时的信息做出决策。当你的东京办事处因为翻译系统会覆盖文档而无法在共享文档中添加本地上下文时，他们就会停止使用维基，创建自己的影子文档。当你的圣保罗团队根本没有葡萄牙语文档时，入职培训需要花费双倍的时间。

成本不仅仅是翻译费。而是

在非英语市场，入职时间缩短
重复劳动**，因为团队要在本地工具中维护并行文档
当官方维基无法为所有人提供服务时，会形成**知识孤岛
当地区特定要求未被记录时**合规风险
对文档系统本身***失去信任

块级本地化可以解决所有这些问题，它不是通过降低翻译成本来实现的（虽然确实如此），而是通过使每种语言版本都成为活的、可维护的、值得信赖的文档来实现的。

开始

如果您正在任何文档平台上运行一个多语言团队，这里有一个快速的直觉检查：

1.** 挑选你最重要的文档。每个版本都是最新的吗？ 2.询问您的非英语团队：他们信任翻译文档吗？他们会使用吗？ 3.**查找影子文档。**团队是否在维护本地维基、Notion 页面或 Slack 固定消息，因为官方文档不适合他们？ 4.**计算你的翻译费用。**每次更新你要支付多少费用，其中有多少是重新翻译没有改变的内容？

如果答案让人不舒服，那您并不孤单。大多数公司都是在出现真正问题时才发现差距的：合规性问题、部署失败、新员工花了两周时间遵循过时的指令。

多语言知识并不是锦上添花。对于任何一家跨国运营的公司来说，多语言知识是团队协调、决策和运输的基础。问题是，你的文档平台是否这样对待它。

** 每种语言都应成为知识库中的一等公民。不是复制。不是影子。而是一份真实的、经过维护的、值得信赖的文档。

这正是 Rasepi 所能提供的。块级翻译、每种语言独有的内容、独立的新鲜度跟踪以及 94% 的翻译成本缩减。全部自动完成。从第一天开始。

查看多语言出版的实际效果 →

内容新鲜度，第二部分：超越有效期限

2026-03-18T00:00:00Z

这是我们内容新鲜度系列的第二部分。[第 1 部分]（/en/blog/why-freshness-matters-more-than-ever/）介绍了新鲜度的重要性及其实际意义。本篇将继续讨论：为什么仅有保质期是不够的，以及持续监控是什么样子。

假设你做了一件负责任的事情。假设你做了一件负责任的事，你维基中的每份文档都有一个审核日期。创建后六个月，对于稳定的参考资料，也许是十二个月。日期一到，所有者就会收到通知：审查此文档，否则就会被标记。

这比大多数公司做的都要好。大多数公司什么都不做。文档放在那里，慢慢腐烂，没人注意到，直到有人按照指示去做，结果出了问题。

但这里有一个让人不舒服的事实：**有效期是必要的，也是完全不够的。**我见过文件在最后一次审核后几天就变质的危险情况，而审核日期并不能解决这个问题。

有效期能解决什么问题

有效期解决了责任问题。它们回答了一个问题：_"谁负责确认这是否仍然准确，何时确认？

这是真正有价值的。如果没有它，文档就会进入我们所说的 "所有权空白 "状态，即每个人都认为是别人在维护文档，因此没有人维护文档。设定审核日期，就是在特定日期为一个人分配一项义务。简单。清晰。有效。

以下是有效日期的实际应用：

创建一份文件，审查日期为 90 天后
到期前 14 天，所有者收到通知
在到期日，文档被标记为 "需要审核"。
所有者审查，确认仍然准确，并延长日期
或者更新，或者重新分配，或者存档

这是一个可靠的系统。它能捕捉到缓慢衰减的文档，即一年来都没人考虑过的文档。它创造了定期审查的节奏。它让所有权清晰可见。

**但它有一个盲点，面积相当于一个大陆。

失效日期会错过什么

在审查日期之间，文件就像一个黑盒子。你在 1 月 15 日审查了它。下一次审核是 4 月 15 日。在 2 月 3 日，这些事情都有可能发生：

###链接突然中断

您引用的外部 URL 返回 404。内部链接指向已存档的文档。代码库被重命名，文档中的所有 GitHub 链接都已失效。您的文档看起来仍然正常。有效期还有两个月。没人知道链接已损坏。

读者数量降至零

你的文档曾经每月有 40 人阅读。后来流程改变了，没有人再需要它了，但也没有人把它存档。它被放在搜索结果中，占用了空间，偶尔还会让不知道它无关紧要的新员工感到困惑。过期日期并不在乎读者数量。无论如何，它都会如期向所有者发送信息。

翻译落后

英文源于 2 月 10 日更新。法语、德语和日语翻译现在已经过时。但这些翻译版本的有效期要到 5 月份。三个月来，非英语团队阅读着过时的内容却浑然不知。

###读者标记问题

一位读者留言"第 3 步不再起作用了，CLI 标志已被弃用"。这条评论被搁置在那里。有效期还有几个星期。下一个阅读文档的人可能不会看到这条评论。下一个人肯定不会看到。

**有效期是一个预定的检查点。这些是计划外事件。这两者之间的差距是陈旧文档造成最大损害的地方。

新鲜度：持续监控

新鲜度评分填补了有效期留下的空白。新鲜度不是每隔 90 天检查一次文档的健康状况，而是持续跟踪。每天都在后台进行，无需任何人做任何事情。

以下是它在 Rasepi 中的工作原理：

每个文档都会获得一个实时新鲜度分数，分数从 0 到 100，由多个信号计算得出：

信号	检测到的内容	重要原因
链接健康状况	断开、重定向或无法访问的 URL	断开的链接会降低信任度并浪费时间
审阅状态**	文档是否已按计划审阅	基线责任检查
阅读量趋势**	是否有人在阅读该文档	低阅读量表明文档可能无关紧要。
文档最后修改的时间与相关内容的对比	检测相对于周围知识库的漂移	翻译对齐度
翻译一致性**	是否所有语言版本都是最新的	过时的翻译意味着其他市场的团队是根据旧信息工作的
读者标记**	读者是否报告了问题	众包陈旧性检测
交叉引用	此文档链接到的文档本身是否陈旧	陈旧会传染

每个信号都对总分有贡献。一份文档今天可能会因为一个断开的链接而失去新鲜度得分，尽管它的审核日期还要等上几周。这就是关键所在。

两者如何协同工作

有效期和新鲜度并不是相互竞争的。它们是相辅相成的：

有效期是治理层。它们创建了一个定期的人工审核周期。必须有人按计划查看该文档，并确认其仍然准确。这就抓住了自动化无法做到的事情：内容是否仍然正确，建议是否仍然合理，所描述的流程是否仍然反映现实。

新鲜度评分是监控层。它能捕捉到审核日期之间的一切：断开的链接、翻译漂移、废弃的文档、当世界在变化而文档没有变化时发生的上下文衰减。

它们共同创建了一个系统，在这个系统中：

1.每份文档都由专人定期审核（过期作废） 2.在两次审查之间，自动信号会及时发现问题（新鲜度） 3.这两个系统都会提供一个大家都能看到的信任分数 4.该分数会影响文档在搜索中的排名，以及人工智能工具是否将其用作信息来源

评分的影响

这就是实用的地方。在 Rasepi 中，文档的新鲜度得分会直接影响其可见度：

80-100分：** 完全可见。正常出现在搜索结果中。有资格成为人工智能答案的来源。无标记。
得分 50-79：** 可见度降低。出现在搜索结果中，带有陈旧性指示器。人工智能工具可能会降低其作为来源的优先级。所有者会收到通知。
分数低于 50：** 标记。在搜索结果中的排名大幅下降。完全排除在人工智能答案之外。所有者收到紧急通知。

这就形成了一个反馈回路。当文档得分下降时，文档所有者就会被催促去修复它，这不是因为某个任意的日期到了，而是因为确实发生了什么变化。断开的链接、陈旧的翻译、下降的阅读量，这些都是真实的信号，现在就需要关注，而不是六周后。

一个实际例子

让我们来看一个场景：

3 月 1 日： 您的 "事件响应手册 "得分为 92 分。两周前对其进行了审核，所有链接都有效，阅读率很高，所有四种语言版本都是最新的。

3月8日： 有人调整了工程状态页面。游戏手册中的三个 URL 现在可以重定向。新鲜度得分降至 78。所有者收到通知"检测到 3 个断开的链接。

3 月 10 日： 所有者修复了链接。得分回升到 89。

3月15日： 英文版更新了新的升级路径。法文和德文翻译已过时（内容哈希值不匹配）。得分降至 74。

3月17日： 翻译已更新。得分恢复到 91 分。

3月20日： 读者数据显示，日文版已有30天未被访问。得分降至 86 分。这是一个微妙的信号，但有迹可循。

**4月1日：**预定审核日期到来。由于读者信号仍然存在，得分保持在 86 分。

团队并没有等到审核日期才发现问题。新鲜度系统在几天内就能发现问题。审核日期提供了管理检查点。两个层面都在尽职尽责。

为什么 "只设定审核日期 "已经不够了？

五年前，有效期可能已经足够。文档是由人来阅读的，人们可以做出判断。如果文件看起来有点问题，他们会四处打听。

如今，文档是基础设施。它为人工智能工具、入职自动化、合规系统以及提供无上下文结果的搜索引擎提供支持。这些系统不做判断。它们按原样消费内容，并进行大规模再分发。

一份有断开链接和陈旧翻译的文档，如果距离审核日期还有三周时间，就会在这三周内造成巨大损失，尤其是当人工智能助手自信满满地据此提供答案时。

**有效期是文档治理的最低可行方法。当文档被无法独立思考的系统消耗时，新鲜度评分才是你所需要的。

开始

如果你已经在文档上标注了有效期（这对你有好处，说真的，大多数团队甚至都没有这样做），下面是如何对新鲜度进行分层的方法：

1.** 开始跟踪链接。** 对排名前 50 位的文档进行断链检查。这个数字可能会让你大吃一惊。 2.**如果您有多语言文档，请比较源文档和译文的最后编辑日期。有多少文件落后一个月以上？ 3.**哪些文档的流量为零？是否还需要它们，还是应该将它们归档？ 4.**如果你有一个内部人工智能助手，询问它从哪些文件中获取资源。然后检查这些文件的新鲜度。

你很可能会发现，技术上没有过期的文档存在很多问题，而过期日期是永远无法发现的。

有效期告诉你最近是否有人检查过文档。新鲜度告诉你文档现在是否健康。一个是日历事件。另一个是活的信号。

两者都需要。但如果你只有有效期，你就会在检查点之间盲目飞行。

文件不会在审核日期过期。文件过期是指文件内容发生变化，但没有人注意到。新鲜度评分会引起注意。

Rasepi 将强制到期日期与持续的新鲜度监测相结合。每份文档都能实时获得或失去信任分值。审查时无需等待，没有盲点，没有意外。

了解新鲜度评分的工作原理 →

*本文是两部分系列文章中的第二部分。如果您还没有阅读，请从[第 1 部分：您的团队没有跟踪的指标]（/en/blog/why-freshness-matters-more than ever/）开始。

内容新鲜度，第 1 部分：你的团队没有跟踪的指标

2026-03-16T00:00:00Z

每个工程团队都经历过这样的时刻。有人在内部维基上找到一份文档，按照说明操作，结果出了问题。他们给频道发信息：没有人知道。写这个文档的人八个月前就离开了。文档上说最后一次编辑是在 2024 年。

这就是新鲜度问题而且越来越严重

##旧合同正在崩溃

长期以来，文档都有一个隐含的契约：有人编写，大家信任，偶尔有人更新。也许吧。当文档只被有判断能力的人使用时，这种契约还能勉强起作用。如果设置指南看起来有点偏差，高级工程师就会临时调整。

但那个世界已经结束了。如今，你的文档不仅仅由人类阅读。它被人工智能工具、内部聊天机器人、入职自动化和搜索系统所使用，这些系统将每个字都视为等价真理。人工智能助手不会眯着眼睛看文档，然后想_"嗯，这看起来有点过时了。"_它会阅读文本，将其作为事实进行处理，并满怀信心地提供服务。

**陈旧的文档加上人工智能就等于大规模的自信错误答案。

新鲜度的实际意义

新鲜度不仅仅是 "这是什么时候最后编辑的"。文档可能是昨天编辑的，但仍然引用了已废弃的 API。真正的新鲜度是一个综合信号：

** 审核状态。** 是否有人明确确认过这一点仍然准确？
**链接健康状况。**文档中的URL是否仍在解析？
** 阅读量。** 是否有人真正在使用它，还是它已被放弃？
** 上下文漂移。** 相关文档是否发生了变化，而本文档保持不变？
如果有五种语言版本，所有语言版本都是最新的吗？
**社区信号.**读者是否将其标记为过时？

每种情况都会告诉你一些不同的信息。这些信息加在一起，就能得出一个信任度分数：一个代表你现在应该对某篇内容有多大信心的数字。

##为什么现在很重要，特别是

有三件事让新鲜度变得刻不容缓：

1.人工智能正在消耗你的知识库

无论你是部署了内部 RAG 系统，在集成开发环境中使用 Copilot，还是让人工智能助手回答文档中的问题，源材料的质量直接决定了输出的质量。垃圾进，垃圾出，从来没有像现在这样直白。

当一个开发人员问你的人工智能助手 "如何部署到暂存阶段？"，而人工智能助手回答使用的是两年前的运行手册，其中引用了你已经迁移的基础架构。而是对整个系统失去信任。

2.团队比以往更加分散

一个团队在柏林，另一个在圣保罗，第三个在东京。所有人都在阅读相同的文档，但语言往往不同。当英文源文件过时时，建立在其上的所有翻译也会过时，但没有人会注意到，因为翻译都是单独维护的。

3.合规和审计压力与日俱增

受监管的行业开始问："你能证明这些文档在引用时是最新的吗？如果你的回答是 "嗯，可能有人检查过"，那就站不住脚了。

新鲜度第一的方法是什么样子的

核心思想很简单：**每份文档都必须不断赢得被信任的权利。

这意味着

1.**每份文件在创建时都有一个有效期。没有例外。日期一到，文件所有者就会收到通知，文件会被标记，直到有人明确重新批准为止。

2.**在后台，系统会持续检查断开的链接、读者趋势和上下文变化。这些信号会反馈到实时评分中，无需任何人做任何事情即可更新。

3.新鲜度影响可见度这是关键机制。高分文档会出现在搜索结果的顶部，并有资格被用作人工智能答案的来源。低分文档的排名会下降。如果低于某个阈值，它就会被完全排除在人工智能答案之外。

4.透明度。每个人都能看到文件得分的原因。断链、逾期审核、阅读量低，这些信号都是可见的，而不是隐藏在无人阅读的后台报告中。

无所事事的代价

以下是不跟踪新鲜度的后果：

新员工按照过时的入职文档入职，第一周就会无所适从
人工智能工具提供了错误的答案，却没人知道原因何在
合规文档悄然过时，带来审计风险
翻译不同步，不同地区的团队根据不同的现实版本开展工作
工程师不再完全信任维基，转而使用 Slack 消息，这就形成了自己的知识孤岛

陈旧文档带来的复合成本是巨大的，但在出现问题之前，这种成本是无形的。

一个实用的起点

你不需要一次性彻底修改所有文档。从这些开始：

1.**审核您阅读次数最多的前 20 份文件。**它们上次审核是什么时候？链接是否仍然有效？内容是否仍然准确？

2.** 设置审核日期。** 即使不做其他事情，在每份文档上注明 "审核日期 "也会产生责任感。

3.** 跟踪人工智能工具的来源。** 如果你有一个内部人工智能助手，看看它从哪些文档中提取信息。这些文件是最新的吗？

4.**将评分放在人们可以看到的地方，如文档标题旁边、搜索结果中、侧边栏中。可见性会产生保持的压力。

文档新鲜度不是一项功能。它从根本上改变了我们对组织知识的看法。在人工智能工具大规模消耗和重新分配文档的世界里，问题不是你是否有能力关注文档的新鲜度。而是你是否有能力不去关心。

** 每份文档都应该证明它仍然值得信任。不是一次。要持续不断。

这就是我们在 Rasepi 正在建设的。在这个平台上，"新鲜 "不是事后才想到的。它是其他一切的基础。审查强制执行、实时健康评分、新鲜度加权搜索以及只使用您可以信任的来源的人工智能答案。

了解如何使用 →

*这是两部系列的第一部分。在第二部分：超越保质期中，我们将探讨如何通过持续的新鲜度监控来填补保质期留下的空白。

教会人工智能忽略陈旧的文档

2026-03-12T00:00:00Z

以下是在内部知识库基础上部署人工智能助手时发生的情况：

一位新工程师问"如何设置暂存环境？"

人工智能会搜索你的文档，找到三份相关文档，合成一个答案，并自信地给出它。工程师按照指示操作。前两个步骤成功了。第三步引用的 CLI 工具在六个月前就已过时。第四步描述了在迁移过程中被替换的基础架构设置，但没有记录在案。

工程师被卡住了。他们在团队频道留言。有人说："哦，那个文档真的很老了。人工智能并不知道这一点。它不可能知道它只是把找到的东西都拿来当作事实。

**这是每一个 RAG 系统、每一个人工智能搜索工具，以及每一个你在内部文档中使用过的 LLM 驱动的助手的默认行为。它们获取一切。它们不加区分。它们分不清新鲜和陈旧。

这种情况正在摧毁人们对人工智能工具的信任，其速度比人工智能工具建立信任的速度还要快。

为什么人工智能助手对质量视而不见？

大型语言模型和检索增强生成（RAG）系统的工作原理是找到与查询语义相关的文本，然后利用这些文本生成答案。相关性匹配通常非常出色。矢量搜索和嵌入在查找与问题相关的内容方面确实很出色。

但相关性并不等于可靠性。

一份写于 2023 年的关于 Kubernetes 部署流程的文档与 "如何部署到生产环境？"这个问题高度相关。如果你在 2024 年迁移到了另一个平台，那么它也是完全错误的。人工智能看到的是相关文本。人工智能看到的是相关的文本，而不是一份已经过期 18 个月、链接已损坏、阅读量为零的文档。

大多数人工智能系统只有一个排名信号：**与查询语义相似。它们不检查

这份文件最后一次被审查是什么时候？
其中的链接是否仍然有效？
是否有人真正在阅读这份文档？
内容是否被读者标记为过时？
这是草稿、存档页面还是当前文档？
如果有多种语言版本，译文是否是最新的？

如果没有这些信号，人工智能在进行关键词匹配时就会增加额外的步骤。关键词匹配的确令人印象深刻，但从根本上说，它无法告诉你它给出的答案是否基于你可以信赖的内容。

信心问题

如果人工智能工具在给出不确定的答案时加上适当的注意事项，这就不会那么危险。但它们没有。LLM不是这样工作的。无论源材料是当前的还是古代的，它们都能生成流畅、自信的文本。

人类在阅读维基文章时可能会注意到它看起来过时了。页面布局陈旧。截图显示的用户界面已不复存在。底部的注释说 "这是过时的"。人类可以做出判断。

人工智能却不能。它读取文本，将其等同于其他文本进行处理，然后生成一个听起来很权威的答案。用户，尤其是不了解当前流程的新员工，没有理由怀疑它。

**人工智能听起来越自信，陈旧的原始材料就会造成越严重的损害。

人工智能的实际需求

要让人工智能助手从你的知识库中给出值得信赖的答案，它需要的不仅仅是文本和嵌入。它需要元数据来告诉它哪些文档值得用作来源。具体来说

1.新鲜度得分

表示文档当前健康程度的数字信号。不是最后一次编辑的时间，那只是一个输入值。真正的新鲜度得分是将评论状态、链接健康度、读者群、翻译对齐度和上下文漂移等综合为一个数字。

当一份文档的得分高于一个阈值（比如满分 100 分中的 70 分）时，它就有资格被用作人工智能答案的来源。低于该阈值，则被排除在外。没有例外。

这种单一机制消除了最危险的人工智能错误类别：基于陈旧来源的自信错误答案。

2.过期状态

该文件目前是在审查窗口内，还是已经过期而没有重新批准？无论过期文件的内容与查询的相关性有多大，都应严重降低其优先级或将其完全排除在外。

在 Rasepi 中，过期文档会被标记，其新鲜度分数也会自动下降。查询知识库的人工智能系统可以看到这一状态，并据此采取行动。

3.分类标签

并非每份文档都有相同的用途。草稿不应作为资料来源。存档文件不应出现在人工智能答案中。仅供内部使用的文档不应出现在面向外部工具的查询中。

分类标签能让人工智能了解它正在查看的文档类型：

已发布** 当前、已批准、可安全使用
草稿：** 工作进展中，不应引用
审查中** 过期，等待重新批准
已存档。** 不再有效，仅供参考
** 内部** / ** 外部.** 控制可见性范围

当人工智能助手处理查询时，它甚至可以在查看内容相关性之前先按分类进行过滤。与查询完全匹配的草稿文档永远不会作为答案提供。

4.语言级信号

如果您的知识库是多语种的，那么人工智能就需要知道它所使用的版本是否是最新的。比英语版本晚三个月的法语翻译在技术上与法语相关，但信息可能已经过时。

Rasepi 在语言层面跟踪新鲜度。每个译文都有自己的分数，其依据是译文源块自上次更新以来是否发生了变化。人工智能在查询法文知识库时，就会发现法文版的文档已经过时，要么是法文版，要么是法文版：

回退到英文源（英文源是最新的）
加入法文版本可能已经过时的注意事项
完全排除该文档

5.读者信号

如果有多个读者将某文档标记为过时，那么该信号应降低该文档在人工智能响应中的权重。众包质量信号会产生噪音，但它们很有价值，尤其是与其他新鲜度指标相结合时。

实践中如何操作

让我们来看看人工智能助手查询 Rasepi 知识库时会发生什么：

查询： "我们在凌晨 2 点处理 P1 事件的流程是什么？

第1步：通过过滤检索 系统搜索语义相关的文档。在排序之前，它会过滤掉

新鲜度得分低于阈值的文档
过期且未重新批准的文档
草稿和存档内容
语言版本过时的文档（如果查询使用的是非主要语言）

第 2 步：新鲜度加权排序 在剩余的文档中，新鲜度得分越高的文档排名越靠前。即使 72 分的文档语义相似度稍高，94 分的文档也比 72 分的文档排名靠前。

第 3 步：生成答案 人工智能会根据过滤后的新鲜度排名来源生成答案。在引用每个来源时，都会显示其新鲜度得分。

第 4 步：陈旧性警告。 如果最佳可用来源的新鲜度得分处于边缘状态，人工智能就会发出警告：_"注意：本答案的主要来源最近一次审核是在 60 天前。您可能需要向团队进行核实。

将此与默认行为进行比较：查找相关文本，生成有把握的答案，期待最佳结果。

如果不这样做会出现什么情况

人工智能系统在未经过滤的知识库上运行的后果是可以预见的，而且代价高昂：

新员工的困惑* 内部文档最常见的人工智能用例是入职培训。顾名思义，新员工不知道什么是最新的，什么是过时的。他们信任人工智能。人工智能信任一切。陈旧的文档可以放心送达。

合规风险 如果您的人工智能助手使用过时的文件为监管流程提供指导，那么这些建议可能不仅是错误的，而且可能是不合规的。"人工智能告诉我 "在审计中站不住脚。

**每当人工智能给出一个错误的答案，用户对它的信任度就会降低一点。三四次糟糕的经历之后，他们就会停止使用。对人工智能工具的投资没有任何价值，因为底层内容并不值得信任。

**当人们对官方知识库（以及建立在其之上的人工智能）失去信任时，他们就会创建自己的知识库：Slack消息、个人笔记、会议中分享的部落知识。维基本应防止的碎片化现象还是发生了，只是方式不同而已。

##解决之道在于源头，而非模型

有一种诱惑是在人工智能层解决这个问题：更好的提示、更复杂的 RAG 管道、经过微调的模型，这些都能以某种方式从文本中检测出陈旧性。这种方法是错误的。

解决之道在于源头。如果您的文档带有关于其当前状态的丰富、准确的元数据（新鲜度评分、过期状态、分类、语言对齐、读者信号），那么任何人工智能系统都可以利用这些元数据做出更好的决策。你不需要更智能的模型。你需要的是更智能的文档。

这正是 Rasepi 所能提供的：

每份文档都有一个实时新鲜度评分**，该评分会根据链接健康状况、读者数量、审核状态等因素不断更新。
每份文档都有有效期**，当文档到达时会触发审核
每份文档都有一个分类**（已发布、草稿、审核中、存档）
每个语言版本都有自己的新鲜度信号**，以便独立检测过期翻译
读者标记和交叉引用跟踪** 增加了额外的质量信号

当人工智能系统查询 Rasepi 的知识库时，所有这些元数据都可用。人工智能无需猜测文档是否可信。文档会告诉它

一个实用的起点

如果你今天在知识库中运行了人工智能助手，你可以在 30 分钟内开始评估问题：

1.**向你的人工智能助手提问 10 个你知道答案的问题。你可能会发现 10 个问题中至少有 2-3 个是基于过时的内容。

2.检查源文件。对于人工智能给出的每个答案，查看源文件。最后一次审查是什么时候？链接是否有效？如果你亲自阅读，你会相信它吗？

3.** 寻找最糟糕的情况。** 找出仍然出现在搜索结果中的最古老、最被忽视的文档。向人工智能提问，让它出现在搜索结果中。人工智能会使用它吗？几乎可以肯定。

4.估算影响人工智能助手每天要处理多少查询？如果有 20%-30% 的回答是基于陈旧的内容，那么在浪费时间、错误决策和失去信任方面的成本是多少？

人工智能助手的好坏取决于它们所基于的内容。现在，大多数人工智能助手将知识库中的每份文档都视为同样有效。它们会获取所有文档，包括昨天审查过的文档和两年来从未有人碰过的文档，并以同样的信心来展示它们。

这不是模型问题。这是数据质量问题。解决方法很简单：给文档提供元数据，告诉人工智能工具应该信任什么。

您的人工智能助手不应该对来自 18 个月内从未有人审阅过的文档的答案充满信心。有了正确的信号，它就不会这样了。

拉塞皮让每份文档都有自己的信任分值：新鲜度、过期状态、分类、语言一致性。人工智能工具对知识库进行查询，获取的不仅是内容，还有上下文。可信来源浮出水面。过期的则不会。这就是人工智能驱动文档的工作原理。

查看 Rasepi 如何与人工智能工具配合使用 →

与文档对话比阅读它们更有意义

2026-03-10T00:00:00Z

当事情比较复杂时，人们会说_"让我们来讨论一下"_，这是有原因的。

当我们试图理解一个新想法、解决一个问题或在压力下回忆一个过程时，对话往往比阅读更容易。这并不是因为阅读不好。阅读是人类发展至今最强大的工具之一。但阅读是一种学习技能，它的基础是更古老的语言。

早在阅读之前，我们就已经会说话了。

这一点比人们意识到的更为重要，尤其是现在，世界上更多的知识都存在于文档、维基、PDF 和冗长的内部页面中，除非万不得已，否则没人愿意打开它们。

阅读是学来的。对话是天生的。

人类在写下任何东西之前，已经说了很长时间的话。儿童自然而然地学会理解口语。阅读则需要明确的指导、反复的练习和多年的实践。

即使是识字率很高的成年人，阅读仍然比听或说更需要深思熟虑。它要求视觉集中、持续关注、工作记忆以及对页面结构的解读。你要解码符号、解析句子、建立上下文，并决定什么是重要的。

对话的工作方式则不同。当信息以口语、互动的形式传递时，大脑会获得不同的体验：

它给人的感觉是连续的，而不是视觉上的压倒性
它能提供即时反馈和说明
减少了扫描和过滤大段文字的需要
它反映了人们在现实生活中寻求帮助的方式

最后一点非常重要。在不确定的情况下，大多数人不会本能地想要阅读 1500 字的内容。他们想问：_"接下来我该怎么做？

交谈降低认知摩擦

文件是静态的。它一次性包含所有内容。

这听起来很有用，而且经常如此。但它也会产生摩擦。满页的标题、提示、链接、注释、示例和边缘案例迫使读者决定忽略哪些内容。这在认知上是很昂贵的。

当你与信息系统交谈时，通常会得到相反的体验：相关性第一，细节第二。

你只问一个问题。得到一个答案。然后再追问。

这种互动模式在几个重要方面减少了心理开销：

1.缩小问题空间

一份完整的文档展示了整个情况。一次对话展示下一个有用的步骤。

当有人问_"我怎样才能让新工程师入职？"_时，他们通常不会立即想要整个手册。他们需要的是指导。对话可以让他们从小处入手，只在需要时才扩展。

2.保留工作记忆

阅读要求你在寻找相关部分的同时在脑子里记住多方面的内容。而口语或对话交互则将这种努力外部化。系统会为你做更多的筛选工作。

3.社会熟悉感

人类深深地适应了来来回回的交流。我们问。有人回答。我们完善。他们澄清。这种循环是我们最古老的学习方式之一。

即使 "有人 "是一个系统，这种结构仍然让人感觉自然。

阅读不是被动的。这正是问题所在。

说话让人感觉轻松的一个原因是，阅读并不像人们想象的那样毫不费力。熟练的阅读者会让阅读看起来毫不费力，但阅读过程却是非常主动的。

要想读得好，你必须

识别结构
推断重要性
消除歧义
记住上下文
将一个章节与另一个章节联系起来
决定何时略读，何时慢读

这才是真正的认知工作。

在很多情况下，这种工作是值得的。深层阅读有助于细微差别、精确性和长篇理解。但在其他情况下，尤其是当一个人感到疲惫、压力过大、负担过重或只是想摆脱困境时，交谈往往是精神上更轻松的选择。

在工作场所尤其如此，因为人们通常不是在理想状态下处理文件的。他们是

任务进行中
中断
情境切换
试图快速解决问题
往往已略显沮丧

在这种状态下，以对话方式获取信息会比以页面优先方式获取信息感觉好得多。

##说话改变了与信息的关系

这里还有一个情感维度。

文件会让人感觉正式而疏远。它们意味着对于参考资料来说，这可能很有用，但也可能让人犹豫不决。

对话给人一种放任的感觉。你可以含糊其辞。你可以问得不好。你可以承认困惑。你可以说_"我真的不知道我在找什么，但我需要关于访问请求的东西"_。

这很重要，因为人们经常回避文件，不是因为他们不喜欢信息，而是因为他们不喜欢在寻找信息的正确部分时所付出的努力和不确定性。

交谈可以减少这种障碍。

为什么这很重要

在很长一段时间里，人们必须阅读文档，因为没有其他切实可行的选择。搜索帮助人们找到页面，但并没有改变交互模式。你仍然需要打开页面、扫描并提取所需内容。

这种情况正在改变。

随着界面变得更加对话化，人们越来越期待信息能够做出回应，而不仅仅是存在。他们希望用通俗易懂的语言询问所需的信息，并获得符合当下需要的信息。

这并不会使阅读过时。它只是改变了阅读的角色。

阅读成为深层。对话则成为访问层。

最好的系统将同时支持这两种功能：

在需要定位或速度时进行对话
需要深度、验证或完整上下文时进行阅读

过度简化的风险

有一个重要的注意事项：只有在答案可靠的情况下，与信息交谈才会感觉更好。

如果对话界面给出的答案片面、误导或过于自信，那么这种体验就会比阅读更糟糕，因为它剥夺了用户直接查看源材料的能力。

因此，未来不是 "用语音取代所有文档"。未来是让人们以更人性化的方式访问文档，同时又不失去书面知识所提供的深度和精确性。

这种平衡很重要。对话更容易，但文件仍具有组织所需的持久结构、细节和责任。

更人性化的知识界面

更深层次的观点很简单：人们不会自然而然地用书页来思考。他们用问题、故事、片段和对话来思考。

我们问

这意味着什么？
我首先要做什么？
重要的部分是什么？
你能换个说法吗？
有什么变化？

这些是对话动作，不是阅读动作。

因此，当与信息对话感觉比阅读信息更容易时，这并不是智力懒惰的表现。这通常是一种迹象，表明界面与大脑喜欢接近不确定性的方式相匹配。

阅读仍然必不可少。但作为知识的切入点，交谈往往感觉更好，因为它更接近我们的天性。

我们首先不是读者。我们首先是交谈者。最直观的知识系统会记住这一点。

为另一个时代构建的文档平台

2026-03-08T00:00:00Z

Confluence 和 Notion 并不是糟糕的产品。这一点需要在一开始就说清楚。

它们成功的原因是充分的。Confluence成为许多公司内部文档的默认归属，因为它为团队提供了一个集中的地方来编写、组织和分享知识。Notion以其灵活性、更简洁的写作体验和更现代的产品外观赢得了人们的青睐](https://www.notion.com/about)。

这两个平台都解决了它们所处时代的实际问题。

现在的问题是，周围世界的变化比它们的基础变化得更快。

我们不再是一个只需要编写、存储和搜索文档的世界。我们所处的世界越来越需要文档：

机器可读
具有保鲜意识
可安全进行人工智能检索
结构化程度足以实现自动化
跨语言和受众的动态性
持续可信，而不仅仅是可用

这是一个不同的标准。

它们是为人工智能之前的知识模型而构建的

传统文档平台的设计基于一个简单的假设：如果页面存在并且可以搜索，问题就基本解决了。

当主要用户是人类打开维基、浏览页面并做出判断时，这种假设已经足够好了。在这种模式下，平台的工作就是让编写和导航变得更容易。

人工智能改变了工作描述。

现在，平台不仅仅是为人们存储知识。它正在为自动检索、排序、总结和回答问题的系统提供源材料。

这就提出了旧架构没有优先考虑的新要求：

哪些内容现在值得信赖？
哪些网页已经过时但仍可搜索？
哪些部分最近发生了变化？
哪些语言版本是最新的？
哪些内容是草稿、存档、特定区域或低可信度？
哪些文件应完全排除在人工智能答案之外？

没有围绕这些问题建立的平台必须对其进行改造。这总是比从一开始就为这些问题进行设计要困难得多。

传统优势变成传统拖累

成熟产品有其优势：分销、生态系统、品牌、客户熟悉度、集成以及知道如何发货的团队。但这些优势也会减缓结构性变革。

为什么？因为成熟的平台有承诺。

它们有

多年积累的产品决策
拥有现有工作流程的庞大安装基础
对向后兼容性的期望
依赖于旧有行为的插件和扩展
数据模型针对昨天的用例进行了优化

当 Confluence 或 Notion 等平台想要添加真正的新功能时，往往需要将该功能与现有系统相匹配，而不是通过现有系统来实现。

这就是现有系统所面临的挑战：你不仅在构建未来，还在拖着过去的后腿。

增加人工智能功能并不等于成为人工智能原生系统

很多成熟的平台现在都在人工智能的基础上进行分层。摘要。写作辅助。搜索改进。问答界面。Confluence 有Atlassian Intelligence，Notion 有Notion AI，GitBook 增加了AI-powered search。这些都是有用的功能。其中有些很不错。

但这两者之间存在着明显的区别：

为文档产品添加人工智能功能
建立一个文档产品，其核心架构从一开始就假定人工智能的使用

第一种方法通常会导致辅助功能的边缘化。第二种方法则会改变基础。

人工智能原生知识平台从一开始就提出了不同的设计问题：

应该如何构建文档，以便系统能够安全地对其进行推理？
如何表示信任？
哪些元数据必须是一流的，而不是可有可无的？
陈旧内容如何降低可见度？
当基础来源薄弱时，应如何限制答案？

这些都是架构问题，而不是功能问题。

新鲜平台具有暂时的优势

这就是新平台的优势所在，至少在一段时间内是这样。

新平台可以自由地根据当今的限制条件而不是昨天的习惯进行设计。它不必保留十年来关于文档是什么或维基应如何运行的假设。它可以尽早做出不同的选择：

将新鲜度作为头等概念
让人类和机器都能看到源信任
存储更丰富的内容状态元数据
在核心模型中建立多语言工作流程，而不是将其附加在核心模型上
决定搜索和人工智能检索应根据信任度而不仅仅是相关性进行排序

自由很重要。

在技术领域，现存企业往往在稳定时期最为强大。新进入者往往在模式本身发生转变时最为强大。

人工智能时代就是这种转变之一。

为什么这对 Confluence 尤为困难？

Confluence功能强大，但它的世界观比较陈旧。它是围绕团队空间、页面、分层导航和插件丰富的企业模型而构建的。这些选择是合理的。对于许多组织而言，它们仍然是合理的。

但这也意味着产品具有很大的复杂性。企业平台很少能干净利落地重塑自己。它们必须与自己的历史协商。

这使得现代化进程变得缓慢。并非不可能。只是慢一些。

当人工智能时代的要求需要更简洁的元数据、更明确的信任建模或更有主见的内容管理时，通过多年扩展而建立的最大灵活性系统就很难协调一致地前进。

为什么这对 Notion 来说尤为棘手

Notion 面临着不同的问题。它给人的感觉更新、更轻、更灵活。但灵活性也可能对它不利。

Notion 的优势在于几乎任何东西都可以成为页面、数据库、笔记、轻量级文档或协作空间。这种灵活性非常适合团队使用。但当你需要对内容的含义、内容所处的状态以及人工智能系统是否应将其作为可信来源提供强有力的保证时，这种灵活性就显得不那么重要了。

平台的形式越自由，以后就越难强加可靠的语义。

人工智能系统的发展离不开结构、明确的元数据和信任信号。灵活的通用工作区通常需要大量的解释工作，其内容才能安全使用。

这并不意味着它们注定要失败

如果说Confluence和Notion无法适应环境，那就太懒惰了。它们当然可以。

它们拥有精明的团队、大量的资源和强大的激励机制。它们将推出更多的人工智能功能。它们将改进检索、辅助撰写、摘要、管理和结构化工作流。随着时间的推移，它们可能会缩小很多差距。

但时机很重要。

当这样的转变发生时，谁愿意最快地重建假设，谁就能获得优势。较新的平台可以更连贯地行动，因为它们没有进行太多的改造。这给了他们一个窗口。

这可能不是一个永久的窗口。但它是真实存在的。

文件平台的下一阶段

下一代文档工具的评判标准将不再是如何让人们书写页面，而是如何将知识管理成一个可信的系统。

这意味着获胜者可能会做好以下五件事：

1.明确建立信任模型。 2.他们会区分最新知识和过时知识。 3.它们将把人工智能检索作为核心产品表面处理，而不是附加产品。 4.它们将支持多语言和特定受众的知识，而不会支离破碎。 5.5. 它们将使团队能够更有力地控制在什么条件下向谁、向什么人展示什么信息。

这与传统的维基不同。

新起点为何重要

在软件领域，有些时候，清一色的产品具有优势，不是因为现任者无能，而是因为历史代价高昂。

现在就是这样的时刻。

一个新的平台可以从一开始就决定，文档不仅仅是页面。它们是人类、代理、搜索系统和人工智能助手的活跃来源。这一假设将改变下游的一切。

Confluence 和 Notion 可以做到这一点。但这条路比较漫长，因为它们必须改造为另一个时代优化的系统。

这种转变需要时间。与此同时，较新的平台还有空间来定义现代知识基础设施应该是什么样的。

新平台的最大优势不是新颖性。而是在旧有假设不再起作用的时候，摆脱旧有假设的束缚。

*这是一篇透视文章。对竞争对手产品的评论基于截至 2026 年 3 月的公开产品文档和公告。我们对 Confluence 和 Notion 都怀有由衷的敬意--它们都是出色的产品，为数百万团队提供了良好的服务。

Rasepi 架构内部：插件、动作保护和管道

2026-03-06T00:00:00Z

大多数文档平台谈论 "可扩展性 "就像航空公司谈论 "腿部空间 "一样。技术上存在，实际上却令人失望。我希望 Rasepi 的架构既具有真正的可扩展性，又不会变得不可预测，因此我们建立了三个环环相扣的系统：插件负责功能，动作保护负责控制，管道负责确定性执行。

本篇文章将介绍每个系统在我们的实际代码库中是如何工作的。

插件系统：模块化设计

Rasepi 中的每一个插件都实现了 IPluginModule_，这是一个单一的接口，它声明了插件是什么、需要哪些服务、暴露哪些路由：

codeblock_0

PluginManifest 是纯数据。它描述插件而不执行任何操作：

codeblock_1

注意 UiContributions。该字典将前端扩展点映射到组件名称，因此 Vue 前端知道每个插件贡献了哪些 UI 组件（工具栏按钮、侧边栏面板、设置页面）。

每个插件只需注册一行

启动时，我们通过流畅的 API 注册插件：

codeblock_2

每次调用都会实例化模块，将其存储在注册表中，并调用 RegisterServices() 来连接其依赖关系。应用程序构建完成后，只需一行即可映射所有插件路由：

代码块_3_

在引擎盖下，每个插件都会在 /api/plugins/{pluginId}/ 处获得一个范围路由组，并自动应用授权。

真实例子：工作流插件

下面是一个真实的插件，即工作流程与审批模块：

codeblock_4

核心平台从不直接引用 WorkflowService或 WorkflowPublishGuard。它是通过 DI 容器发现它们的。这就是零耦合的关键所在。核心应用程序从不接触插件代码。

操作防护：控制层

插件添加功能。操作保护器决定是否允许继续执行该功能或任何核心操作。它们是同步验证器，可在执行前拦截操作。

行动保护评估流程](/zh/blog/img/action-guard-flow.svg)

该接口特意做到了最小：

codeblock_5

当 _ActionName_为 _null_时，防护程序会在每个操作中运行。当设置为 "Entry.Publish"_时，它只拦截特定的操作。

上下文和结果合约

每个 guard 都会收到一个类型化的上下文，其中包含操作名称、租户、用户、实体和一个属性包：

codeblock_6

每个监控程序都会返回一个可预测的结果：允许、拒绝或允许-带修改：

代码块_7_

Modifications 字段非常重要。保护程序可以批准一项操作，但重写部分内容（例如，在发布前编辑机密）。

###规范操作名称

我们将所有可拦截的操作都定义为字符串常量，因此防护程序的目标操作不会有任何歧义：

codeblock_8

真实例子：阻止未经批准的发布

工作流插件注册了一个拦截 _Entry.Publish的保护程序：

代码块_9__

核心平台对审批工作流一无所知。

操作管道：一切汇聚之处

ActionPipeline 是所有受保护操作的单一执行路径。它会确定哪些防护措施适用，对其进行评估，并阻止或执行操作。

代码块_10_

EvaluateAsync_方法负责执行繁重的工作：

代码块_11_

这里有三个重要的设计决定：

1.**TenantPluginResolver会检查每个租户安装并启用了哪些插件。禁用插件的防护程序永远不会运行。 2.2. 全部必须通过。 如果任何防护措施被拒绝，该操作就会被阻止。这是故意采取的安全立场。 3.**如果防护程序出现异常，它将被记录并被视为 Allow()。这可以防止损坏的插件锁定整个平台。

每租户插件解决方案

解析器会查询 TenantPluginInstallations 表（通过 EF 全局查询过滤器自动扩展到当前租户）：

代码块_12_

事件驱动的副作用

操作是同步的。而副作用不是。操作完成后，服务会发布一个域事件：

codeblock_13

事件被挂起到内存通道，并由后台 _________________________________________________处理。Worker 将事件路由到多个系统：

** 活动跟踪 ** 记录谁在何时做了什么。
跟踪每个提供商的成本
任何插件都可以订阅域事件

插件事件处理程序实现 IPluginEventHandler：

编码块_14_

Worker 只调用租户已启用插件的处理程序。这意味着插件 A 的副作用永远不会泄漏到只安装了插件 B 的租户中。

块级翻译引擎

这是该架构最明显的优势所在。

块级翻译：仅对已更改的块进行重译](/zh/blog/img/block-translation.svg)

传统平台翻译整个文档。我们翻译的是单个块：段落、标题、列表项。当用户编辑 50 块文档中的一个段落时，只有该段需要重新翻译。这就是我们节省 94% 成本的原因所在。

如何从 TipTap JSON 创建块

当用户保存文档时，TipTap 编辑器会发送这样的 JSON：

codeblock_15

BlockTranslationService_会解析该 JSON 并创建单独的EntryBlock_记录：

代码块_16_

SHA256 哈希算法用于过期检测

内容散列是过期检测的核心。我们使用 SHA256 对区块内容（去掉 blockId 和 deleted 等元数据属性后）进行散列：

代码块_17_

当源代码块发生变化时，它的哈希值也会发生变化。然后，系统会将每个翻译块的 SourceContentHash与当前的源哈希值进行比较，不匹配的部分会被标记为 Stale：

代码块_18_

结构适应

翻译人员可以改变不同语言的代码块类型。英语的项目列表可能会变成德语的编号列表，这是一种文化偏好。系统会对此进行跟踪：

codeblock_19

翻译提供者作为插件

外部翻译服务（DeepL、Google Translate 等）通过 _ITranslationProviderPlugin_插入：

代码块_20_

批处理方法接收内容块 ID 词典，翻译所有内容块，并返回翻译结果和计费字符数。由于我们只发送陈旧的块，而不是整个文档，因此成本保持在最低水平。

租户隔离：无形的安全网

上述每个系统都在严格的租户隔离内运行。

TenantContextMiddleware 会根据每次请求中的 JWT 解析租户，并验证成员身份：

代码块_21__

Entity Framework 全局查询过滤器可确保即使开发人员忘记按租户进行过滤，数据库层也会自动进行过滤：

代码块_22___

结果：db.Hubs.ToListAsync() 总是只返回当前租户的集线器。数据泄露需要主动绕过查询过滤器，这在我们的代码库中是禁止的。

完整图片

当用户点击 "发布 "条目时，会发生以下情况：

1.请求进入身份验证验证 JWT，TenantContextMiddleware_解析并验证租户。 2.控制器调用管道 IActionPipeline.ExecuteAsync("Entry.Publish", context, action) 3.** 管道解析保护** 查询租户启用了哪些插件，并选择适用的保护。 4.4. 防护装置进行评估。 工作流防护装置检查审批，保留防护装置检查策略，规则防护装置验证内容。全部通过？条目已发布。 5.事件触发 _CODEBLOCK_54__事件被触发。后台工作者记录活动、更新翻译计费并调用插件事件处理程序。 6.检查块翻译过时块将被识别，以便重新翻译。

各层各司其职。各层各司其职，互不影响。这就是架构。

我们建立这个平台并不是因为可扩展性很时髦。我们之所以构建它，是因为一个不能适应每个团队工作流程的文档平台最终会被一个能适应的平台所取代。而一个没有护栏的平台最终会破坏一些重要的东西。

Rasepi Blog

读者和写作者的思维模式不同。为什么每种工具都给他们提供相同的用户界面？

阅读和写作不是同一种认知任务

单一界面的代价

信息过载降低理解能力

读者和作者对相同内容的需求不同

第三种受众：人工智能

作者环境

读者环境

人工智能表面

一个内容层，三个界面

为什么这比看起来更重要

读者的信任

撰稿人的工作效率

人工智能的可靠性

思维模式的转变

2026 年的文档现状：定义下一个时代的五大趋势

1.人工智能现在是主要的阅读者。而不是人类。

2.新鲜度和信任元数据成为必备条件

3.翻译从 "项目 "转向 "管道"

4.人工智能代理需要结构化的内容，而不是维基页面

5.开源和自托管正在卷土重来

这五大趋势的共同含义

建设者，而非开发者：克劳德如何改变文档的对象

核心转变

无人计划的旅程

两个消费者，一套文档

建造者没有偷工减料

开发者关系是为不同的时代而建立的

当人工智能阅读你的文档时，新鲜度变得至关重要

这对文档意味着什么

开始：审核当前文档

产品表现方式的悄然转变

Rasepi 翻译是如何工作的？

样式规则：让译文听起来像你写的一样

格式约定

一切协同工作

自动与人工：共同协作

两种模式：始终保持当前状态或按需翻译

翻译引擎内部：词汇表、风格规则和智能重译

翻译流水线

词汇表解析：租户范围、DeepL 同步

同步流程

词汇表条目

风格规则、自定义说明和正式性

创建样式规则列表

配置的规则看起来像什么

自定义指令：这才是真正的力量

形式

DeepL 服务层

翻译协调器

翻译触发器：翻译何时发生

独特的内容和结构适应性

将所有内容放在一起

停止保留同一文档的五个副本

复制和本地化陷阱

真正的问题：共享内容和本地内容混在一起

一个文档。就是这样。

这实际上改变了什么

页数减少

不仅仅是入职培训

复合效应

快速直觉检查

块级本地化的商业案例

翻译不是本地化

文档级翻译的问题

1.费用昂贵

2.速度慢

3.不支持独特内容

块级本地化：不同的架构

技术上的工作原理

每种语言的独特内容

跨语言的新鲜度跟踪

商业案例

开始

内容新鲜度，第二部分：超越有效期限

有效期能解决什么问题

失效日期会错过什么

相关内容变更

读者数量降至零