/kb-article

如果您看到不熟悉的占位符或需要检查已连接的工具，请参阅 CONNECTORS.md。

根据已解决的支持问题、常见问题或已记录的变通方案，起草一篇可发布的知识库文章。为便于搜索和自助服务而结构化内容。

用法

/kb-article <已解决的问题、工单引用或主题描述>

示例：

• /kb-article 如何配置 Okta SSO——上个月为 3 位客户解决了此问题
• /kb-article 工单 #4521——客户无法导出超过 1 万行的数据
• /kb-article 常见问题：如何设置 webhook 通知
• /kb-article 已知问题：仪表盘图表在 Safari 16 上无法加载

工作流

1. 理解源材料

解析输入以识别：

• 问题是什么？ 原始问题、疑问或错误
• 解决方案是什么？ 解决方案、变通方案或答案
• 这影响谁？ 用户类型、套餐级别或配置
• 这有多常见？ 一次性事件还是反复出现的问题
• 哪种文章类型最合适？ 操作指南、故障排除、FAQ、已知问题或参考资料（见下面的文章类型）

如果提供了工单引用，请查找完整的上下文：

• ~~support platform：拉取工单线程、解决方案和任何内部备注
• ~~knowledge base：检查是否已存在类似文章（更新 vs. 创建新文章）
• ~~project tracker：检查是否有相关的错误或功能请求

2. 起草文章

使用下面的文章结构、格式标准和搜索最佳实践：

• 遵循所选文章类型的模板（操作指南、故障排除、FAQ、已知问题或参考资料）
• 应用搜索最佳实践：客户语言的标题、通俗易懂的开篇句、确切的错误信息、常见同义词
• 保持易于浏览：标题、编号步骤、短段落

3. 生成文章

呈现草稿并附带元数据：

## 知识库文章草稿

**标题：** [文章标题]
**类型：** [操作指南 / 故障排除 / FAQ / 已知问题 / 参考资料]
**类别：** [产品领域或主题]
**标签：** [可搜索的标签]
**受众：** [所有用户 / 管理员 / 开发者 / 特定套餐]

---

[完整文章内容——使用下面的适当模板]

---

### 发布说明
- **来源：** [工单号、客户对话或内部讨论]
- **需要更新的现有文章：** [如果与现有内容重叠]
- **需要审阅人员：** [如果需要验证技术准确性的主题专家或团队]
- **建议审阅日期：** [何时重新检查准确性]

4. 提供后续步骤

生成文章后：

• "需要我检查您的 ~~knowledge base 中是否已存在类似文章吗？"
• "需要我为不同的受众调整技术深度吗？"
• "需要我起草一篇配套文章吗（例如，配合这篇故障排除指南的操作指南）？"
• "需要我创建一份仅限内部使用的包含更多技术细节的版本吗？"

文章结构和格式标准

通用文章要素

每篇知识库文章都应包含：

1. 标题：清晰、可搜索、描述结果或问题（非内部行话）
2. 概述：1-2句话，说明本文涵盖的内容及其目标读者
3. 正文：适合文章类型的结构化内容
4. 相关文章：指向相关配套内容的链接
5. 元数据：类别、标签、受众、最后更新日期

格式规则

• 使用标题（H2、H3） 将内容分成易于浏览的部分
• 使用编号列表 表示顺序步骤
• 使用项目符号列表 表示非顺序项目
• 使用粗体 表示 UI 元素名称、关键术语和强调
• 使用代码块 表示命令、API 调用、错误消息和配置值
• 使用表格 表示比较、选项或参考数据
• 使用标注/注释 表示警告、提示和重要的注意事项
• 保持段落简短——最多 2-4 句话
• 每节一个主题——如果一节涵盖两个主题，请拆分

面向搜索的写作

如果客户找不到文章，文章就没用。优化每篇文章以利搜索：

标题最佳实践

关键词优化

• 包含确切的错误消息——客户将错误文本复制粘贴到搜索中
• 使用客户语言，而非内部术语——"无法登录"而非"认证失败"
• 包含常见同义词——"删除/移除"、"仪表盘/主页"、"导出/下载"
• 添加替代表述——在概述中从不同角度描述同一问题
• 使用产品领域标签——确保类别和标签与客户对产品的认知方式一致

开篇句公式

每篇文章以一句用通俗语言复述问题或任务的句子开头：

• 操作指南："本指南向您展示如何 [完成 X]。"
• 故障排除："如果您遇到 [症状]，本文说明如何解决。"
• FAQ："[用客户的话提出的问题]？以下是答案。"
• 已知问题："部分用户遇到 [症状]。以下是我们的了解情况和变通方法。"

文章类型模板

操作指南文章

目的：完成某项任务的分步说明。

结构：

# 如何 [完成任务]

[概述——本指南涵盖的内容及何时使用]

## 前置条件
- [开始前需要准备什么]

## 步骤
### 1. [操作]
[带有具体细节的说明]

### 2. [操作]
[说明]

## 验证是否成功
[如何确认操作成功]

## 常见问题
- [问题]：[修复]

## 相关文章
- [链接]

最佳实践：

• 每个步骤以动词开头
• 包含具体的路径："前往 设置 > 集成 > API 密钥"
• 提及每个步骤后用户应看到的内容（"您应看到一条绿色的确认横幅"）
• 亲自测试步骤或通过最近的工单解决方案验证

故障排除文章

目的：诊断并解决特定问题。

结构：

# [问题描述——用户看到的内容]

## 症状
- [用户观察到的情况]

## 原因
[为什么会发生——简洁、无行话的解释]

## 解决方案
### 选项 1：[主要修复方法]
[步骤]

### 选项 2：[选项 1 无效时的替代方案]
[步骤]

## 预防
[如何将来避免此问题]

## 仍有问题？
[如何获得帮助]

最佳实践：

• 以症状开头，而非原因——客户搜索他们看到的内容
• 尽可能提供多种解决方案（最可能的修复方法放在前面）
• 包含"仍有问题？"部分，指向支持渠道
• 如果根本原因复杂，保持面向客户的解释简单

FAQ 文章

目的：快速回答常见问题。

结构：

# [问题——用客户的措辞]

[直接答案——1-3 句话]

## 详情
[额外的背景、细微差别或解释（如需）]

## 相关问题
- [链接到相关 FAQ]
- [链接到相关 FAQ]

最佳实践：

• 在第一句话中回答问题
• 保持简洁——如果答案需要分步指导，那是操作指南而非 FAQ
• 将相关 FAQ 分组，并在它们之间建立链接

已知问题文章

目的：记录带有变通方案的已知错误或限制。

结构：

# [已知问题]：[简要描述]

**状态：** [调查中 / 有变通方案 / 修复中 / 已解决]
**影响范围：** [谁/什么受影响]
**最后更新：** [日期]

## 症状
[用户遇到的情况]

## 变通方案
[变通问题的步骤，或"无可用变通方案"]

## 修复时间线
[预期的修复日期或当前状态]

## 更新
- [日期]：[更新]

最佳实践：

• 保持状态的及时性——没有什么比过时的已知问题文章更破坏信任
• 修复发布后更新文章并标记为已解决
• 如果已解决，保留文章 30 天，供仍在搜索旧症状的客户使用

审查和维护节奏

知识库如不维护就会退化。请遵循此时间表：

文章生命周期

1. 草稿：已撰写，需要审查
2. 已发布：上线并对客户可见
3. 需要更新：标记为需要修订（产品变更、反馈或时效）
4. 已归档：不再相关但保留供参考
5. 已退役：从知识库中移除

何时更新 vs. 创建新文章

更新现有文章的情况：

• 产品发生变化，步骤需要刷新
• 文章大体正确但缺少某个细节
• 反馈显示客户对某个特定部分感到困惑
• 找到了更好的变通方案或解决方案

创建新文章的情况：

• 新功能或产品领域需要文档
• 已解决的工单暴露出空白——该主题尚无文章
• 现有文章涵盖太多主题，需要拆分
• 不同受众需要以不同方式解释相同信息

链接和分类法

类别结构

按客户思考方式组织文章层级：

入门指南
├── 账户设置
├── 首次配置
└── 快速入门指南

功能与操作指南
├── [功能领域 1]
├── [功能领域 2]
└── [功能领域 3]

集成
├── [集成 1]
├── [集成 2]
└── API 参考

故障排除
├── 常见错误
├── 性能问题
└── 已知问题

计费与账户
├── 套餐与定价
├── 计费问题
└── 账户管理

链接最佳实践

• 从故障排除链接到操作指南："有关设置说明，请参阅 [如何配置 X]"
• 从操作指南链接到故障排除："如果您遇到错误，请参阅 [X 的故障排除]"
• 从 FAQ 链接到详细文章："如需完整教程，请参阅 [X 指南]"
• 从已知问题链接到变通方案：保持从问题到解决方案的路径简短
• 在知识库中使用相对链接——它们比重排结构后的绝对 URL 更稳定
• 避免循环链接——如果 A 链接到 B，B 不应链接回 A，除非两者都确实是有用的入口点

知识库写作最佳实践

1. 为正在寻找答案的沮丧客户写作——要清晰、直接、有用
2. 每篇文章都应能通过客户会输入的关键词搜索到
3. 测试您的文章——亲自遵循步骤，或让不熟悉该主题的人遵循
4. 保持文章专注——一个问题，一个解决方案。如果文章过长，请拆分
5. 积极维护——一篇错误的文章比没有文章更糟糕
6. 追踪缺失内容——每张本可以是知识库文章的工单都是内容缺口
7. 衡量影响——没有流量或不能减少工单的文章需要改进或退役