dsh-error-handling git:20261030.1b17503A

Immutable. This exact content never changes and is served at /api/v1/blob/28c4116addc27c9a.

---
name: "dsh-error-handling"
description: "实现或审查错误传播、部分成功、结果未知、恢复、重试、取消或失败反馈时使用，明确状态保证和错误处理责任。"
---

# 明确失败行为及处理责任

阅读[项目上下文](references/project-context.md)、[生命周期](references/lifecycle.md)和[验证证据](references/evidence.md)。沿用项目现有的错误约定。

1. 追踪操作的公开入口、状态负责方、外部副作用和最终报告。建立简短对应关系：触发条件 → 错误分类 → 状态保证 → 处理者 → 用户可见结果。区分响应失败与操作失败。
2. 用稳定标识区分已知业务错误；保留意外错误的原因，不把所有异常都转成成功默认值或同一个通用业务错误码。
3. 明确失败后状态属于未变化、部分完成、已提交还是结果未知。只有状态负责方能证明恢复和继续执行的前提；无法证明时停止依赖该状态的后续工作。写入结果不明确时，使用真实服务支持的核对或幂等机制，不能仅根据异常文字无条件重试。
4. 确保取消、回调错误和清理失败到达适当的处理位置。避免重复报告；保留足够的处理线索，不泄露秘密。
5. 通过真实调用方验证副作用发生前后的失败，包括“已经提交但响应丢失”。分别断言可观察状态和报告内容；支持恢复时，覆盖恢复成功和恢复失败。

完成时说明明确的状态保证、负责的处理者和实际测试的失败场景。服务行为约定不足以建立保证时，如实报告结果未知。