add_note 是 python 3.11 新增的异常方法，用于向异常追加人类可读的上下文说明，仅影响 str(exc) 和打印输出末尾，不改变异常类型或 traceback；旧版本调用会报 attributeerror。
add_note 是什么，为什么 Python 3.11 才能用
add_note 是 Python 3.11 新增的异常方法，用于向异常对象追加人类可读的上下文说明，它不改变异常类型或 traceback，只影响 str(exc) 和打印时的末尾显示。Python 3.10 及更早版本调用会报 AttributeError: 'XXXError' object has no attribute 'add_note'。
怎么安全地调用 add_note（避免 AttributeError）
不能假设所有环境都是 3.11+，尤其当代码需兼容旧版本时。推荐用 hasattr 检查，而不是 try/except 包裹 add_note 调用——后者可能掩盖真实错误。
- ✅ 推荐写法：
if hasattr(exc, 'add_note'): exc.add_note("用户输入为空，但字段为必填") - ❌ 避免写法：
try: exc.add_note("...") except AttributeError: pass # 静默吞掉错误，后续调试难定位 - 注意：
add_note只接受str，传入None或int会触发TypeError
add_note 和 __notes__ 的关系与使用边界
add_note 内部操作的是异常对象的 __notes__ 列表（Python 3.11+ 新增的私有属性），每次调用都 append 一条字符串。它和 raise ... from 的异常链机制完全正交——add_note 不影响 __cause__ 或 __context__，也不会出现在 traceback 的 “During handling of the above exception…” 段落里。
python-docx Skill功能概述python-docx Skill是一项面向实际任务的技能，主要用于本Skill提供使用python-docx生成专业Word文档的标准方法和最佳实践；生成安全服务方案文档；核心要点生成技术架构设计文档；生成任何需要专业排版的Word文档；核心库 : python-docx；使用与执行辅助库 : docx.shared , docx.enum , docx.oxml.ns；标准代码模板；1. 文档初始化；2. 字体设置（必须！它将相关步骤、工具调用和结果整理方式集
- 打印效果示例：
ValueError: invalid literal for int() Addendum: 用户提交了非数字字符 Addendum: 已在 API 层校验过格式，此处应为 bug
-
__notes__是公开可读的：exc.__notes__返回list[str]，但不应直接修改它 - 同一异常上多次调用
add_note会累积，顺序即添加顺序
实际场景中 add_note 的典型用法
它最适合补充「运行时上下文」，而非替代日志或异常包装。比如解析配置、处理用户请求、桥接外部服务时，在不改变原始异常的前提下，附带关键现场信息。
- Web 请求中：
exc.add_note(f"Request ID: {request_id}, User: {user.email}") - 配置加载失败时：
exc.add_note(f"Config file path: {config_path.resolve()}") - 数据库操作后：
exc.add_note(f"Failed on row ID {row_id}, values={dict(row)}") - ⚠️ 注意：不要用它传敏感数据（如密码、token），因为
__notes__会随异常传播并可能被日志或监控系统捕获
真正容易被忽略的是：add_note 的内容不会自动进入 logging.exception() 的默认输出——除非你自定义 Formatter 或显式打印 exc.<strong>notes</strong>。它只对直接 print(exc) 或 str(exc) 可见。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
