kb-article

/kb-article

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

根据已解决的支持问题、常见问题或已记录的变通方案，起草一篇可直接发布的知识库文章。对内容进行结构化处理，以提升可搜索性和自助服务体验。

用法

/kb-article <resolved issue, ticket reference, or topic description>

示例：

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

工作流程

1. 理解源材料

解析输入内容，识别以下信息：

• 问题是什么？ 最初的问题、疑问或错误
• 解决方案是什么？ 解决办法、变通方案或答案
• 受影响的是谁？ 用户类型、套餐等级或配置
• 发生频率如何？ 偶发问题还是反复出现的问题
• 哪种文章类型最合适？ 操作指南、故障排查、常见问题、已知问题或参考文档（参见下方文章类型）

如果提供了工单编号，请查询完整上下文：

• ~~支持平台：提取工单记录、解决结果和内部备注
• ~~知识库：检查是否已有类似文章（更新还是新建）
• ~~项目跟踪器：检查是否存在相关的缺陷或功能请求

2. 起草文章

依据下方的文章结构、格式标准和可搜索性最佳实践：

• 遵循所选文章类型（操作指南、故障排查、常见问题、已知问题或参考文档）的模板
• 应用可搜索性最佳实践：使用客户用语作为标题，开篇用通俗语言说明，写明准确的错误信息，并覆盖常见同义词
• 保持内容易于浏览：使用标题、编号步骤和简短段落

3. 生成文章

连同元数据一起呈现草稿：

## KB Article Draft

**Title:** [Article title]
**Type:** [How-to / Troubleshooting / FAQ / Known Issue / Reference]
**Category:** [Product area or topic]
**Tags:** [Searchable tags]
**Audience:** [All users / Admins / Developers / Specific plan]

---

[Full article content — using the appropriate template below]

---

### Publishing Notes
- **Source:** [Ticket #, customer conversation, or internal discussion]
- **Existing articles to update:** [If this overlaps with existing content]
- **Review needed from:** [SME or team if technical accuracy needs verification]
- **Suggested review date:** [When to revisit for accuracy]

4. 提供后续步骤

生成文章后：

• “需要我检查你的 ~~知识库中是否已有类似文章吗？”
• “需要为不同受众调整技术深度吗？”
• “需要我起草一篇配套文章吗（例如，为这篇故障排查指南配一篇操作指南）？”
• “需要我创建一个仅供内部使用、包含更多技术细节的版本吗？”

---

文章结构与格式标准

通用文章要素

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

1. 标题：清晰、便于搜索，描述结果或问题（避免内部术语）
2. 概述：1–2 句话，说明本文涵盖的内容及适用对象
3. 正文：根据文章类型组织的结构化内容
4. 相关文章：指向相关配套内容的链接
5. 元数据：分类、标签、受众、最后更新日期

格式规则

• **使用标题（H2、H3）**将内容划分为便于浏览的章节
• 使用编号列表表示有先后顺序的步骤
• 使用项目符号列表表示无先后顺序的条目
• 使用加粗标注界面元素名称、关键术语和强调内容
• 使用代码块展示命令、API 调用、错误信息和配置值
• 使用表格进行对比、列出选项或呈现参考数据
• 使用提示框/注意事项标注警告、提示和重要注意点
• 段落保持简短——最多 2–4 句话
• 每节只讲一个要点——如果某节涵盖两个主题，请拆分

为可搜索性撰写

如果客户找不到文章，文章就毫无价值。请针对搜索优化每篇文章：

标题最佳实践

好的标题	不好的标题	原因
"How to configure SSO with Okta"	"SSO Setup"	具体，包含客户会搜索的工具名称
"Fix: Dashboard shows blank page"	"Dashboard Issue"	包含客户遇到的症状
"API rate limits and quotas"	"API Information"	包含客户会搜索的具体术语
"Error: 'Connection refused' when importing data"	"Import Problems"	包含准确的错误信息

关键词优化

• 包含准确的错误信息：客户会把错误文本复制粘贴到搜索框中
• 使用客户的语言，而不是内部术语。例如用“无法登录”，不要用“认证失败”
• 包含常见同义词，例如“删除/移除”“仪表盘/首页”“导出/下载”
• 添加不同的表述方式：在概述中从不同角度说明同一个问题
• 标注产品领域标签：确保分类和标签与客户理解产品的方式一致

开篇句公式

每篇文章都应以一句话开头，用简单的语言重述问题或任务：

• 操作指南：“本指南将向您说明如何[完成 X]。”
• 故障排查：“如果您遇到[症状]，本文将说明如何解决。”
• 常见问题：“[用客户的措辞提出的问题]？答案如下。”
• 已知问题：“部分用户正在遇到[症状]。以下是我们目前掌握的情况以及临时解决办法。”

文章类型模板

操作指南文章

用途：提供完成某项任务的分步说明。

结构：

# How to [accomplish task]

[Overview — what this guide covers and when you'd use it]

## Prerequisites
- [What's needed before starting]

## Steps
### 1. [Action]
[Instruction with specific details]

### 2. [Action]
[Instruction]

## Verify It Worked
[How to confirm success]

## Common Issues
- [Issue]: [Fix]

## Related Articles
- [Links]

最佳实践：

• 每个步骤都以动词开头
• 写明具体路径，例如：“前往 Settings > Integrations > API Keys”
• 说明每一步之后用户应看到的结果，例如：“您应该会看到一条绿色的确认横幅”
• 自己测试这些步骤，或根据近期的工单解决记录进行核实

故障排查文章

用途：诊断并解决某个具体问题。

结构：

# [Problem description — what the user sees]

## Symptoms
- [What the user observes]

## Cause
[Why this happens — brief, non-jargon explanation]

## Solution
### Option 1: [Primary fix]
[Steps]

### Option 2: [Alternative if Option 1 doesn't work]
[Steps]

## Prevention
[How to avoid this in the future]

## Still Having Issues?
[How to get help]

最佳实践：

• 以症状开头，而不是以原因开头。客户搜索的是他们看到的现象
• 尽可能提供多种解决方案，并将最可能有效的方案放在最前面
• 加入“仍然有问题？”一节，引导客户联系支持团队
• 如果根本原因很复杂，面向客户的解释应保持简单

常见问题文章

用途：快速回答一个常见问题。

结构：

# [Question — in the customer's words]

[Direct answer — 1-3 sentences]

## Details
[Additional context, nuance, or explanation if needed]

## Related Questions
- [Link to related FAQ]
- [Link to related FAQ]

最佳实践：

• 在第一句话中直接回答问题
• 保持简洁。如果答案需要逐步演示，就应写成操作指南，而不是常见问题
• 将相关问题归为一组，并在它们之间互相链接

已知问题文章

用途：记录已知的缺陷或限制，并提供临时解决办法。

结构：

# [Known Issue]: [Brief description]

**Status:** [Investigating / Workaround Available / Fix In Progress / Resolved]
**Affected:** [Who/what is affected]
**Last updated:** [Date]

## Symptoms
[What users experience]

## Workaround
[Steps to work around the issue, or "No workaround available"]

## Fix Timeline
[Expected fix date or current status]

## Updates
- [Date]: [Update]

最佳实践：

• 保持状态信息及时更新。没有什么比过时的已知问题文章更快地削弱信任
• 修复发布后更新文章，并标记为已解决
• 问题解决后，将文章保留 30 天，以便仍在搜索旧症状的客户找到相关信息

审查与维护节奏

知识库若缺乏维护就会逐渐失效。请遵循以下时间表：

活动	频率	负责人
新文章审查	发布前	同行评审，技术内容需由 SME 审核
准确性审计	每季度	支持团队审查访问量最高的文章
过时内容检查	每月	标记 6 个月以上未更新的文章
已知问题更新	每周	更新所有未解决已知问题的状态
分析数据审查	每月	检查哪些文章的有用性评分较低或跳出率较高
内容缺口分析	每季度	找出工单中高频出现但没有知识库文章的主题

文章生命周期

1. 草稿：已撰写，待审查
2. 已发布：已上线，客户可以访问
3. 待更新：因产品变化、用户反馈或内容过时而被标记需要修订
4. 已归档：不再相关，但保留以供参考
5. 已下线：从知识库中移除

何时更新与何时新建

在以下情况更新现有文章：

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

在以下情况新建文章：

• 新功能或新产品领域需要文档
• 已解决的工单暴露出内容缺口，即该主题尚无对应文章
• 现有文章涵盖的主题过多，应当拆分
• 不同受众需要以不同方式理解同一信息

链接与分类体系

分类结构

按照客户的思考方式组织文章，形成层级结构：

Getting Started
├── Account setup
├── First-time configuration
└── Quick start guides

Features & How-tos
├── [Feature area 1]
├── [Feature area 2]
└── [Feature area 3]

Integrations
├── [Integration 1]
├── [Integration 2]
└── API reference

Troubleshooting
├── Common errors
├── Performance issues
└── Known issues

Billing & Account
├── Plans and pricing
├── Billing questions
└── Account management

链接最佳实践

• 从故障排查链接到操作指南："有关设置说明，请参阅 [如何配置 X]"
• 从操作指南链接到故障排查："如果遇到错误，请参阅 [X 故障排查]"
• 从常见问题链接到详细文章："有关完整的步骤说明，请参阅 [X 指南]"
• 从已知问题链接到解决方法：保持从问题到解决方案的链路简短
• 在知识库内使用相对链接：相比绝对 URL，它们在结构调整后更不容易失效
• 避免循环链接：如果 A 链接到 B，那么 B 不应再链接回 A，除非两者都确实是有价值的入口

知识库写作最佳实践

1. 面向那些感到沮丧、正在搜索答案的客户撰写内容，做到表达清晰、直接且有帮助
2. 每篇文章都应能通过客户可能输入的词语被搜索到
3. 测试你的文章：自己按步骤操作，或请不熟悉该主题的人员按步骤操作
4. 保持文章聚焦：一个问题，一个解决方案。如果文章变得过长，就进行拆分
5. 积极维护：错误的文章比没有文章更糟糕
6. 跟踪缺失内容：每一个本可以通过知识库文章解决的工单，都是一处内容缺口
7. 衡量影响：没有流量或未能减少工单量的文章，需要改进或下线