错误处理

AGENTS.md

@@ -1,5 +1,7 @@
 ## 设计约束
 
+[错误处理规范](./Error_handling_specification.md)
+
 0. 跟你审计报告 就要大刀阔斧的改 一次性先把问题一次改完 在批量检查 要大步前进
 1. 每个状态只能有一个权威来源，禁止在不同对象中重复保存并手工同步。
 2. 能通过计算、查询或快照得到的数据，不要保存为成员变量。

Error_handling_specification.md

@@ -0,0 +1,70 @@
+# 统一错误处理原则
+
+## 1. 已知结果处理规则
+
+属于 API 契约允许出现、调用方能够明确处理的情况，使用返回码表达，例如 `Xxx_Result`、`Xxx_Status`、`Xxx_Error`。
+
+返回码不等于错误码，`timeout`、`cancelled`、`not_ready`、`no_change` 等都可以是正常结果。
+
+判断依据只有一个：
+
+**该结果是否可预料，并且调用方是否具有明确的处理方式。**
+
+不按“内部/外部”区分。
+
+## 2. 未知失败处理规则
+
+不属于正常结果空间，或者当前调用路径没有可靠恢复方式的情况，统一视为 **Unknown Failure**。
+
+Unknown Failure 不得转换成 `unknown_error`、`internal_error` 等普通返回码。
+
+中间层没有恢复能力时不得层层处理，不增加无意义的 `catch`、包装或 catch/rethrow。
+
+Unknown Failure 应直接退出当前执行路径，由上层真正具有故障隔离能力的 request、task、worker、进程或服务边界处理。
+
+异步跨线程时可以使用 `std::exception_ptr`、`promise::set_exception()`、`future::get()` 搬运失败；这只是 transport，不属于错误处理。
+
+## 3. Unknown Failure Policy
+
+Unknown Failure 支持两种处置策略：
+
+```text
+fast_fail
+    -> 在实际故障位置尽快终止
+    -> 用于开发、调试和测试
+    -> 优先保留故障现场
+
+exception
+    -> 使用异常自然跨层传播
+    -> 中间层不处理
+    -> 到达上层故障隔离边界
+    -> 优先利用 task/thread/process 等隔离能力
+```
+
+`fast_fail` 只改变 Unknown Failure 的处置方式， **不得改变 Known Result / Unknown Failure 的分类。**
+
+## 4. 第三方库处理规则
+
+第三方库自身使用返回码还是异常，不决定本系统的处理方式。
+
+接入第三方库后必须重新按照本系统规则分类：
+
+```text
+第三方返回结果
+    -> 本系统可预料、可处理
+       -> 转换为本系统返回码
+
+    -> 本系统没有可靠恢复方式
+       -> 转换为 Unknown Failure
+       -> 交给当前 Unknown Failure Policy
+```
+
+不得机械透传第三方错误模型，也不得因为第三方返回了错误码，就强制在本系统中继续使用错误码。
+
+## 5. 其他要求
+
+`noexcept` 只用于明确保证异常不会逃逸的函数。
+
+不得为了错误处理增加重复检查、兼容层、无意义 `try/catch`，也不得改变原函数的既有语义。
+
+**最终原则：已知结果使用返回码；未知失败使用可配置的 Unknown Failure Policy；第三方错误进入系统后重新按同一规则分类。**

render_3D/AGENTS.md

@@ -5,4 +5,6 @@
 
 D:\ae\tools 可能会有有用的工具
 
-运行前使用环境脚本 env.ps1
+运行前使用环境脚本 env.ps1
+
+[错误处理规范](../Error_handling_specification.md)

render_3D/tool.md

@@ -1,14 +0,0 @@
-"C:\Program Files\JetBrains\CLion 2026.1\bin\cmake\win\x64\bin\cmake.exe" -DCMAKE_BUILD_TYPE=Debug --preset vs2022_debug
--S D:\ae\proj\Renderive -B D:\ae\proj\Renderive\cmake-build-vs2022_debug
-
-默认每次运行程序都通过CDB运行 D:\ae\ewdk\EWDK_22621_230929-1800\Program Files\Windows Kits\10\Debuggers\x64\cdb.exe
-
-D:\ae\tools 可能会有有用的工具
-
-运行前使用环境脚本 env.ps1
-
-注意错误处理机制
-
-可预料、可恢复的错误：返回专门的 enum class Xxx_Error。 不可预料的错误：使用异常传播。 不按“内部/外部”区分，全系统统一按“错误是否可预料”判断。
-异步接口保持异步语义，可预料错误通过异步结果返回，异常仍走异常通道。 明确不会抛异常的函数才加 noexcept。
-不为了错误处理增加多余检查、兼容层，或改变原函数语义。