observe-whatsapp

observe-whatsapp 技能概览

observe-whatsapp 技能可帮助你排查 Kapso 中的 WhatsApp 运行问题：消息送达、webhook 重试、API 错误以及号码健康状态。它面向支持工程师、运维人员和集成人员，目标是让你快速从“出了问题”定位到具体原因，而不是先把整个 repo 的每个文件都读一遍。

当你需要确认一条消息是否已发送、已送达或已读；判断 webhook 为什么没有到达；或者确认 WhatsApp 配置是否降级、被阻断或仍然健康时，适合使用 observe-whatsapp 技能。它的核心价值不只是诊断本身，更在于提供更清晰的排查路径：告诉你先看什么，以及哪些证据最关键。

这个技能最适合什么场景

observe-whatsapp 最擅长生产环境排障，尤其是当用户手里有 message ID、电话号码、webhook 失败信息，或者健康检查失败结果时。它关注的不是通用 WhatsApp 指南，而是 Kapso 中的运行状态。

observe-whatsapp 的不同之处

这个技能是以工作流为导向、以证据为基础的。它既包含直接的 Kapso CLI 路径，也提供回退脚本，因此无论你是在已登录的 CLI 会话里，还是只能用 API 凭据工作，都能用上。相比那种只描述症状的提示词，observe-whatsapp for Observability 更适合实际排障。

什么时候适合用

如果你需要查看送达时间线、webhook 尝试记录、健康信号或 API 日志，就选 observe-whatsapp。如果你只是想要一段现成回答，或者临时解释一下，一个普通提示词可能就够了；但如果你需要可重复的诊断流程，这个技能更合适。

如何使用 observe-whatsapp 技能

安装上下文和前置条件

推荐的安装方式是：

npx skills add gokapso/agent-skills --skill observe-whatsapp

为了获得最佳效果，建议先使用 Kapso CLI：先通过 kapso login 完成认证，再运行 kapso status，确认项目访问权限以及可用的 WhatsApp 号码。如果无法使用 CLI，这个技能也支持通过 KAPSO_API_BASE_URL 和 KAPSO_API_KEY 走 API 回退方案。

把模糊问题变成可用提示词

这个技能在你的提示词包含最小且可执行的信息时效果最好：电话号码、message ID、webhook 事件、时间窗口，或者准确的错误文本。例如，不要只说“WhatsApp 挂了”，而是说：“使用 observe-whatsapp 检查 wamid.HBgMMTIzNDU2Nzg5 为什么停在 delivered，以及 10:00 UTC 之后 webhook 重试是否失败。”

通常最快得到答案的工作流

先从用户可见的症状入手，再收敛到四条路径之一：消息送达、webhook 送达、错误排查或健康检查。实际使用中，这个技能默认你先确认配置，再检查具体工件。这样的顺序能减少误判，也能避免把错误归因到不对的电话号码或会话上。

优先阅读的文件

如果是为了安装时理解，先读 SKILL.md，然后看 references/health-reference.md、references/message-debugging-reference.md 和 references/triage-reference.md。如果需要示例，再查看 assets/health-example.json、assets/message-debugging-example.json 和 assets/triage-example.json。如果想了解回退工具链，重点看 scripts/messages.js、scripts/message-details.js、scripts/webhook-deliveries.js 和 scripts/whatsapp-health.js。

observe-whatsapp 技能 FAQ

使用 observe-whatsapp 一定要有 Kapso CLI 吗？

不需要，但这是首选路径。这个技能的设计就是与 kapso status 和 WhatsApp 子命令配合使用效果最好。如果你不能用 CLI，脚本和 API 环境变量可以作为回退方案。

observe-whatsapp 需要什么输入？

给它标识符，而不是只给症状：message ID、显示号码或 E.164 格式手机号、phone-number ID、时间范围、webhook 事件名，或者原始错误信息。你的输入越具体，技能需要自行推断的内容就越少。

observe-whatsapp 适合新手吗？

如果你已经知道问题的大致轮廓，那么是适合的。它比空白提示词更容易上手，因为它会告诉你先检查什么，但它仍然默认你至少能提供一个具体的 WhatsApp 工件。

什么情况下不该用这个技能？

不要把 observe-whatsapp 用在非 WhatsApp 的可观测性任务上，也不要用来回答产品层面的战略问题。如果你没有任何 ID、没有时间戳，也拿不到日志或状态信号，它也不太适合。

如何改进 observe-whatsapp 技能

提供准确的失败点

提升输出质量最快的方法，是明确工作流卡在哪一步：“已发送但未送达”、“webhook 收到 Connection refused”或者“健康状态降级且 webhook 验证失败”。这样 observe-whatsapp 就能跳过泛泛解释，直接聚焦在失败的检查项上。

加入技能可以验证的证据

高质量输入通常包括 message ID、使用的电话号码、时间窗口，以及任何响应载荷或错误码。比如，“使用 observe-whatsapp 检查 whatsapp.message.received 在 10:00 到 10:15 UTC 之间的 webhook delivery；最后一次尝试返回 502”就远比“webhook 挂了”更有用。

利用参考文件提升首轮输出质量

如果第一次返回太泛，可以对照 references/health-reference.md 中的判定规则，以及 references/triage-reference.md 里的排障逻辑。这些参考文件会说明什么应视为 critical、degraded 或 retryable，从而同时提升诊断质量和你返回给用户的表述。

每次只迭代一个变化

如果初次结果不完整，就只补充一个新信息来收窄范围：换一个 ID、缩小时间窗口，或者给出具体失败的检查项。对 observe-whatsapp 来说，这通常比把整个问题重说一遍更有效，因为这个技能本来就是围绕单一路径追踪根因来设计的。