连通性验证
验证的目标不是“请求没有报错”，而是证明凭据、权限、目标、平台处理和客户端展示组成的完整链路可用。测试消息使用明确的非业务文本，例如“通知渠道连通性测试”，并标注环境与时间。
- 网络层：从实际部署环境解析域名并建立 TLS 连接，确认代理和出口策略一致。
- 认证层：验证 Token、Secret、签名和可信 IP 属于当前应用与环境。
- 授权层：确认权限已审批、版本已发布、可用范围覆盖测试接收者。
- 业务层：同时判断 HTTP 状态和平台业务码，记录平台请求 ID。
- 到达层：由目标客户端确认消息、发送者、群或频道与时间均正确。
- 增强层：纯文本成功后，再逐项验证 Markdown、卡片、附件、提及和线程回复。
双向对话还需要验证入站事件、签名或长连接、事件去重、快速确认、确定性回复和 AI 超时降级。不要直接用模型回答作为第一条联调路径。
最小验证记录
Section titled “最小验证记录”| 字段 | 示例内容 |
|---|---|
| 平台与方式 | 飞书 / 企业自建应用 |
| 环境与版本 | 测试租户 / 应用版本号 |
| 验证时间 | ISO 日期时间和时区 |
| 接收目标 | 测试用户、测试群或脱敏 ID |
| HTTP 状态 | 200 |
| 平台结果 | 脱敏业务码、请求 ID、消息 ID |
| 客户端结果 | 已到达、未到达、格式异常 |
| 验证等级 | source-reviewed / sandbox-verified / production-verified |
记录中不包含完整 Webhook、Token、Secret、用户隐私信息或业务消息正文。
- 先向单个测试用户或专用测试群发送纯文本。
- 检查 HTTP 状态、平台业务码和返回消息标识。
- 在客户端确认消息来自预期应用或机器人。
- 再扩大到部门、标签、多个群或频道。
- 最后验证富文本、卡片、文件和高优先级等增强能力。
异步发送接口返回 task_id 只表示任务已受理，还需要调用结果查询接口或查看失败名单，不能直接标记全部接收人成功。
| 结果 | 更可能的问题 |
|---|---|
| 无法连接 | DNS、代理、TLS、出口网络或域名错误 |
401 / 403 | 凭据、签名、可信 IP、Scope 或应用归属 |
404 | API 路径、资源 ID、Bot 或应用不存在 |
429 | 平台级或目标级限流，需要按返回字段退避 |
HTTP 2xx、业务码失败 | 参数、目标、权限、版本或可用范围 |
| 业务成功、客户端未显示 | 目标错误、禁言、免打扰、过滤或客户端状态 |
请求失败时先回退到纯文本和单一接收者，不连续重放原批量请求。更多路径见故障排查中心。
异常与边界验证
Section titled “异常与边界验证”- 使用错误凭据时必须失败，且日志不能输出凭据。
- 超出时间窗口的签名必须失败。
- 同一入站事件重复发送时只执行一次业务和一次回复。
- 平台
429或临时5xx时按上限退避，不形成重试风暴。 - 接收者不在可用范围时能输出明确、脱敏的业务错误。
- 模型或下游 API 超时时，平台回调仍能及时确认并给出可恢复状态。
- 在与生产一致的出口网络和 Secret 注入方式下完成最小验证。
- 监控区分网络失败、HTTP 失败、平台业务失败和客户端未确认。
- 告警包含平台、方式、业务码和请求 ID，不包含敏感值。
- 凭据轮换、撤销、限流退避和故障回退有明确责任人。
- 测试机器人、测试群和临时凭据已删除，或登记用途与到期时间。
- 文档中的
reviewedAt与实际复核日期一致，验证等级没有被夸大。