问题

当 AI 流水线（例如 RAG 架构）摄取文档时，它们会将 Markdown 源码切分成更小的“块”（例如每个块 500 个 token）。如果文档由冗长、杂乱且边界不明的段落组成，切分算法可能会在思绪中途切断上下文，从而破坏该块的效用，并导致 AI 的回答不完整或不正确。

为什么重要

如果 AI 检索到的一个块包含代码示例，但遗漏了前面解释 何时 使用该代码的段落，那么生成的答案将缺乏必要的条件说明。为“可分块性”组织您的文档可确保每个文本段落都包含足够的上下文，从而能够独立发挥作用。

方法

将您的页面组织成确定性的、原子化的块层级结构。使用 Markdown 标题清晰地描绘概念，并确保相关信息（如警告及其适用的代码）在源文件中物理位置紧密相连。

实施

1. 原子化标题部分

确保每个 ## 或 ### 标题都封装了一个单一的、原子化的概念。一个结构良好的部分应该能够作为一个有用的块独立存在，供 AI 模型使用。

• ✅ 正确：标题为“通过 OAuth 进行身份验证”，后跟简短解释和代码示例。
• ❌ 糟糕：一个庞大的“入门”页面，包含 15 个不同的概念且没有子标题。

2. 关键信息的紧密排列

不要用长段落将关键警告与其适用的代码分开。使用 标注 (Callouts) 将它们在纵向上绑定在一起。这增加了它们在摄取过程中保留在同一个向量块中的概率。

::: callout warning "破坏性操作"
运行此命令将永久删除所有日志。
:::

`docmd logs --clear`

3. 自动化串联

LLMs 插件 通过生成 llms-full.txt 文件来促进分块。该文件在页面之间使用标准分隔符 (---)，帮助摄取流水线识别自然的文档边界，同时保留项目的全局上下文。

权衡

这种方法更倾向于模块化、分段式的写作风格，而不是长篇大论。虽然这对人类读者来说可能感觉更具重复性，但它能显著提高依赖于您文档的 AI 驱动搜索和自动化支持代理的性能。