问题

当 AI 流水线摄取文档时，会将 Markdown 切分为更小的"块 (chunks)"。如果一篇文档由段落冗长、边界模糊的段落组成，算法会在思维中途切分上下文。这会破坏该块的可用性，并导致 AI 回答出错。

为什么重要

如果 AI 检索到一段代码块，却遗漏了前面解释何时使用它的段落，那么答案将缺少条件信息。为可分块性而构建文档，可确保每个片段单独拿出来都包含足够的上下文。

方法

将各页面构建为确定的、原子化的块所组成的层级结构。使用 Markdown 标题清晰划分概念。确保相关信息（例如一条警告以及它所适用的代码）在源文件中物理上彼此靠近。

实现

1. 原子化的标题段落

确保每个 ## 或 ### 标题封装单一、原子化的概念。一个结构良好的段落，应可独立成为一个对 AI 模型有用的块。

• ✅ 好：标题为 “通过 OAuth 进行身份验证”，随后是简要说明与代码示例。
• ❌ 差：一个庞大的 “Getting Started” 页面，包含 15 个不同概念，却没有子标题。

2. 让关键信息在物理上紧密相邻

不要用冗长的段落把关键警告与对应的代码隔开。使用 标注 (Callout) 将它们在垂直方向上绑定在一起。这能提高它们在摄取过程中保留在同一向量块中的概率。

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

`npx @docmd/core logs --clear`

3. 自动拼接

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

取舍

此方法偏向模块化、片段化的写作风格，而非长篇流畅的叙述。对人类读者来说可能显得重复，但它显著提升了 AI 驱动的搜索与自动化支持 Agent 的表现。