Support kb article writer

支持知识库文章撰写

何时使用

当一次工单解决、常见问题或临时绕过方案值得沉淀为客户可自助检索的知识库（KB）文章时使用。典型触发：

• 一个工单的解决方案值得文档化以减少重复工单。
• 同一个问题反复被问（内容缺口）。
• 某绕过方案需要对外发布。
• 某已知问题需要主动告知客户。

不该用的边界：

• 面向单个客户的工单/邮件回复（那是一次性沟通，不进 KB）。
• 内部 Runbook / 排障手册（面向工程师、含敏感内部细节）。
• 事故复盘 / Postmortem 报告本身（KB 文章只引用其链接，不写根因分析）。
• 营销博客、产品发布说明。

步骤

1. 解析源材料，识别五要素：原始问题是什么 / 解决方案或答案是什么 / 影响谁（用户类型、套餐、配置） / 频率（一次性 vs 反复） / 适配哪种文章类型。
2. 拉取上下文（若给了工单号）：从支持平台拉完整工单线程与内部备注；查 KB 是否已有相似文章（决定更新 vs 新建）；查关联 bug/需求。
3. 选文章类型并套模板（见示例的 5 类模板）。
4. 按检索优化写作：标题用客户语言、首句平实复述问题、嵌入精确报错原文、加同义词与别名。
5. 输出草稿 + 元数据 + 发布注记（见指令的输出结构）。
6. 给后续动作：是否检查重复文章 / 调整受众技术深度 / 写配套文章 / 出内部增强版。

指令

判定「更新已有 vs 新建」：产品变更需刷新步骤、文章大体正确仅缺细节、客户反馈某节困惑、发现更优方案 → 更新；新功能/新领域、解决工单暴露空缺、旧文混入太多主题需拆分、不同受众需另一种讲法 → 新建。

检索优化（文章找不到 = 无用）：

• 标题要具体含客户搜索词：用「如何用 Okta 配置 SSO」而非「SSO 设置」；用「修复：仪表盘显示空白页」而非「仪表盘问题」；含精确报错原文「报错：导入数据时 'Connection refused'」。
• 用客户语言而非内部术语：「登录不了」而非「认证失败」。
• 加同义词（删除/移除、导出/下载、仪表盘/首页）与多种问法。

首句公式（按类型）：How-to=「本指南教你如何〈完成 X〉」；排障=「如果你看到〈症状〉，本文说明如何修复」；FAQ=「〈客户原话问题〉？答案如下」；已知问题=「部分用户遇到〈症状〉，以下是已知情况与绕过方法」。

格式规则：用 H2/H3 分节；顺序步骤用有序列表、非顺序用无序列表；UI 元素名/关键词加粗；命令、API、报错、配置值用代码块；对比/选项用表格；警告与提示用 callout；段落 2-4 句封顶；一节只讲一件事，混了就拆。

输出结构：

## KB 文章草稿
**标题:** [客户语言、含搜索词]
**类型:** [How-to / 排障 / FAQ / 已知问题 / 参考]
**分类:** [产品域]   **标签:** [可检索标签]   **受众:** [全部/管理员/开发者/某套餐]
---
[正文 — 按下方对应类型模板]
---
### 发布注记
- 来源: [工单号/对话/内部讨论]
- 待更新的已有文章: [若有重叠]
- 需谁评审: [技术准确性需 SME 把关时]
- 建议复查日期: [何时回看]

示例

How-to 模板：# 如何〈完成任务〉 → 概览 / 前置条件 / 步骤（每步动词开头、给精确路径如「进入 设置 > 集成 > API 密钥」、说明操作后应看到什么如「应出现绿色确认横幅」）/ 验证是否成功 / 常见问题 / 相关文章。

排障模板：# 〈用户看到的问题〉 → 症状（先写症状，客户按看到的搜）/ 原因（简短非术语）/ 解决（方案 1 主修复、方案 2 备选）/ 预防 / 仍有问题？（指向支持）。多方案时最可能的修复放最前。

FAQ 模板：# 〈客户原话问题〉 → 直接答案（1-3 句、首句即答）/ 细节 / 相关问题。需要走查的就该是 How-to 而非 FAQ。

已知问题模板：

# 已知问题：〈简述〉
**状态:** [排查中 / 有绕过方案 / 修复中 / 已解决]
**影响:** [谁/什么受影响]   **最后更新:** [日期]
## 症状
[用户遇到的现象]
## 绕过方案
[绕过步骤，或「暂无绕过方案」]
## 修复时间线
[预期修复日期或当前状态]
## 更新记录
- [日期]: [更新]

状态务必保持最新（陈旧的已知问题最毁信任）；修复上线后标记「已解决」并保留 30 天供仍按旧症状搜索的客户。

注意事项

• 一文一题：一篇文章只解决一个问题，过长就拆，用链接互串。
• 可检索压倒一切：客户搜不到的文章等于不存在；把精确报错原文与客户口语词放进标题和概览。
• 互链方向：排障→How-to（「配置步骤见〈如何配置 X〉」）、How-to→排障、FAQ→详细指南、已知问题→绕过方案；KB 内用相对链接（重构后更稳）；避免无意义循环链接。
• 激进维护：错的文章比没有文章更糟。建议节奏——已知问题状态每周更新、月度排查 6 个月未更新的陈旧内容、季度审计高流量文章准确性与内容缺口。
• 技术准确性：涉及命令/配置/API 的文章需 SME 评审；步骤要自己实测或用近期工单解决过程核对。
• 引用的事实（版本号、影响面、报错）应来自工单与系统，不确定要标注。
• 本条采编自 anthropics/knowledge-work-plugins（Apache-2.0），保留其 5 类文章模板、检索优化（客户语言标题/精确报错/同义词）、首句公式、格式规则、更新 vs 新建判据、维护节奏与文章生命周期等关键约束。

互见

• related：internal-comms —— 对内/对外的事故与状态公告写法可复用，已知问题文章可引用其 status update。
• related：ai-customer-support —— 一线工单解决方案是 KB 文章的主要素材源，KB 反过来降低重复工单。
• combines_with：ai-customer-support —— 工单解决 → 沉淀 KB → 自助分流，形成支持闭环。