用途:把团队反复在工单、issue 和聊天中回答的失败问题沉淀为文档,使开发者粘贴错误字符串即可命中,读完即解除阻塞。
主要能力:从已报告来源(工单、issue、社区帖)与未报告来源(错误遥测、文档搜索日志、AI 未答查询日志)收集证据;用脚本聚类并排序失败簇;对每个簇做“写文档还是修产品”的取舍;按错误参考、排障操作指南、已知问题三种形态撰写条目;建议由机器可读源生成错误目录;发布前验证;并让页面可被检索与 AI 索引。
使用方式:先访谈确认信号来源、错误标识符形态、受众与时间约束;运行 python3 scripts/error-cluster.py tickets.csv issues.jsonl --min-count 3 --top 40 聚类;按读者小时收益排序并确认队列;每条目按消息、适用版本、原因、修复、验证、仍卡住六部分撰写;发布前复现并冷读验证。
适用场景:自助开发者与合同制工程团队共存的排障文档建设,或建立每周期持续捕获的 KCS 习惯。
限制:不调试用户当前故障、不改写产品错误字符串、不做全站 SEO;无任何信号源时应停止并先建立捕获习惯;无法复现的条目须标注“未复现”;需去除凭据与客户标识;标识符与 URL 应保持稳定。