AI 功能的文档怎么写：能力、限制与示例

只罗列能力的文档帮不了用户。本文给出能力该怎么具体写、限制必须包含哪些（不适合场景/失败模式/上限/数据处理）、示例怎么选、出错怎么办专章，以及六个部分的最小结构。

文档写的是"能力清单"，用户要的是"怎么用"

AI 功能的文档常见写法是罗列能力 ✗："支持总结、支持问答、支持翻译" ✔。

用户读完仍然不知道：**什么时候该用它、什么时候不该用、出错了怎么办** ✗。

**好文档的结构应该是"能力 + 限制 + 示例"** ✔。

用**用户语言**描述（"把长文档压成一页要点" ✔ 而不是"长文本摘要能力" ✗）；

给出**输入要求**（格式、长度上限、语言 ✔）；

说明**典型耗时**（"约 5 秒" ✔），让用户有预期 ✔。

必须写：

**不适合的场景**（"不用于法律/医疗结论" ✔）；

**已知的失败模式**（"表格较多的文档可能丢格式" ✔）；

**输入上限**与超限后的行为 ✔；

**数据如何被处理**（是否外发、保存多久 ✔ —— 合规要求 ✔）。

**写清限制能显著降低支持成本** ✔，也能减少误用导致的事故 ✔。

**3~5 个真实示例** ✔（从日志里挑高频且答得好的 ✔，见空状态那篇 ✔）；

每个示例给出：**输入 → 输出要点 → 为什么这样用** ✔；

好例子之外，给 **1 个反面例子** ✔（"这样问效果不好，改成……" ✔）。

**常见错误与处理**（格式不符、超出上限、上游繁忙 ✔）；

**如何降级**（换关键词、分批提交、改用人工 ✔）；

**怎么反馈问题**（带上请求 id ✔ —— 见可复现那篇 ✔）。

1. **先说结论**：第一段就写"这个功能适合什么、不适合什么" ✔；

2. **可执行**：每条限制都给出"那该怎么办" ✔（见长尾输入那篇的拒绝文案对照 ✔）；

3. **有版本**：文档随功能版本更新 ✔（模型换代后旧说明会变成错误信息 ✔）。

```

1. 一句话说明（做什么、给谁用）

2. 能做什么（具体能力 + 输入要求 + 耗时）

3. 不能做什么（不适合场景 + 已知失败模式 + 上限）

4. 怎么用（3~5 个真实示例 + 1 个反面例子）

5. 出错怎么办（常见错误 + 降级路径 + 反馈方式）

6. 数据与合规（如何处理、保存多久）

```

> 用户**只看第 3 节（不能做什么）** ✔，能否避免最常见的误用 ✔？

> 不能，说明限制写得太笼统 ✗。