开发调试

## 任务目标

请改进本次 Python 模块或服务的异常处理和错误信息。

在现有授权范围内完成实际改动和验证；缺少外部条件时先完成可独立实现的部分，不能只停留在计划。

## 输入信息（选填）

两项均可留空，也可直接用一句话说明目标并附上已有资料。无需自行整理版本、配置或完整需求表；能读取的内容由执行者补齐。

异常改进对象：沿对话中的报错或当前模块公开入口追踪异常链；没有具体异常时优先处理吞错、宽泛捕获、不可定位提示和重复日志，同时保留已有对外错误协议。
代码或报错资料：读取目标模块、调用方、异常类、接口响应封装、日志配置和已有失败测试；使用已提供脱敏日志定位实际问题。

## 信息不完整时

先使用本次对话中已经说明的信息；用户留空、写“暂无／不清楚”或未替换输入标记，都按缺失处理，不当作真实路径、参数或业务值。已能从资料确定的内容不重复询问，不编造文件、日志、接口、业务值或执行结果。在用户已授权的范围内读取相关工程和材料，不为补齐输入擅自扩大操作范围。

### 优先确认

- 区分输入、数据不存在、前置条件、外部依赖和程序缺陷，确认哪一层具备恢复上下文。
- 追踪错误码、异常类型、客户端处理和日志记录，识别接口兼容约束及重复堆栈。
- 检查错误中的实际值、令牌或个人信息，以及可依据的重试、修改输入和维护处理路径。

### 可采用的默认处理

- 优先修正现有错误文案和异常传播，保留错误码、HTTP 约定及业务成功条件，不批量更换异常体系。
- 普通用户看到简短中文事实和下一步，内部保留必要因果链与请求标识，敏感原值默认脱敏。
- 无法证明可重试时不建议自动重试；不以空列表、默认值或捕获全部异常伪装成功。

### 必须有依据的事项

- 调用方依赖的错误码、异常类型或失败重试约定不清，而目标修正必须改变这些对外行为。

只有缺口会改变业务结果、权限边界或关键实现，且无法从现有资料确认时，才集中提出最多 3 个关键问题；说明影响，并继续完成不依赖答案的部分。一般命名、排版和可逆实现细节按现有约定决定，不逐项等待确认。

### 资料仍不足时的交付

- 只有日志时交付异常分类、脱敏文案对照和应取证的调用层，不臆造源码根因。
- 有代码无运行条件时给出完整局部实现及非法参数、超时等断言用例，标记复现待验证。

## 执行要求

错误信息应清楚描述错误事实、实际与预期的差异，并给出有依据的处理方向。面向 C++ 宏的长度限制和专用宏规则不作为普通 Python 项目的强制要求。

1. 先沿调用链区分输入错误、数据不存在、前置条件不满足、外部依赖失败和程序缺陷。明确谁能够处理每种错误，不把所有异常归为一个“系统错误”，也不能用宽泛捕获把失败变成空列表或默认成功。
2. 为每个对外入口列出需要验证的条件和合适的 Python 异常类型。优先在有足够上下文的位置报错，说明出错对象和具体约束，避免仅输出内部变量缩写或用户无法理解的内部函数名。
3. 能够安全给出差异时，显示实际类型、数量、范围或维度与预期的区别。日志中的值必须按敏感等级处理，不把令牌、密码、个人完整信息及大段业务原始数据直接拼到错误中。
4. 只给有证据支持的恢复建议，区分可重试、需要修改输入和必须联系维护人员的情况。不要在未知原因下建议反复重试或提高资源配置；外部服务报错应保留必要原因，便于定位故障发生在哪一层。
5. 核查错误传播与记录方式，保留有价值的异常因果关系，避免每一层重复记录同一堆栈。面向普通用户的中文提示应短且可操作，内部日志另保留请求标识和排查信息，二者不直接互相复制。
6. 通过非法参数、空数据、超时、外部服务失败和意外异常验证结果，断言异常类型、关键上下文及调用方处理行为。确认调整错误信息没有改变业务成功条件，也没有破坏已有错误码协议。

## 交付与验收

输出：异常场景表、旧新文案对照、传播与记录策略、必要实现和测试结果。每条建议写明适用条件；无法复现的异常保留待验证状态。缺少业务错误格式时先指出接口兼容风险，不自行批量更改客户端依赖的错误码。

### 本条完成检查

- 交付异常场景、可处理层、旧新提示与恢复条件，保留必要原因且避免多层重复记录。
- 验证非法输入、外部失败和意外异常的类型、上下文及调用方响应，检查秘密和个人信息不会进入提示。
- 说明实际修改与测试结果，确认成功条件和已知错误协议保持兼容。

按本条要求组织结果，使用简洁中文和一致的编号、术语、缩进及空行；已有项目格式优先。只说明实际完成的内容，将采用的假设、未完成项和缺少的条件写在相关位置，不额外生成无关文档。未执行、无法复现或缺少证据的检查如实标注，不宣称已通过或已有性能收益。

## 参考资料与适用边界

官方来源（2026-09-08 核验）：
- [百度飞桨《报错信息文案书写规范》](https://www.paddlepaddle.org.cn/documentation/docs/zh/dev_guides/style_guide_and_references/error_message_writing_specification_cn.html)