feat(errors): 错误消息面向最终用户友好化

- memory::MemoryError 英文 → 中文 + 操作建议（namespace 拼写 / 后端存储 / 数据兼容性）
- llm::LlmError 各变体补充修复建议（API key / 超时 / 上下文压缩）
- tools::ToolError 各变体补充修复指引（注册工具 / 检查 Schema / 调权限 / MCP 握手）
- prompt::PromptError 各变体补充修复指引（注册子模板 / 检查语法 / 调深度限制）
- agent::AgentError::Config 中文化 + 提示需调用的 builder 方法名

src/llm/error.rs

@@ -5,33 +5,35 @@ use std::time::Duration;
 /// 错误按可重试性分为两类：
 /// - **可重试**：`RateLimit`、`Timeout`、状态码 >= 500
 /// - **不可重试**：`Authentication`、`ContextLength`、状态码 4xx（除 429）
+///
+/// 错误消息面向最终用户（中文），并尽量附带可操作的修复建议（如检查 API key、减少上下文）。
 #[derive(thiserror::Error, Debug)]
 pub enum LlmError {
-    /// API 认证失败（如 API key 无效）。
-    #[error("认证失败: {0}")]
+    /// API 认证失败（API key 无效、过期或权限不足）。
+    #[error("LLM 认证失败: {0}。请检查环境变量中的 API key（如 OPENAI_API_KEY / ANTHROPIC_API_KEY）是否正确")]
     Authentication(String),
 
-    /// 请求被限流，可选地附带重试等待时间。
-    #[error("限流(retry_after={retry_after:?})")]
+    /// 请求被限流，可选地附带重试等待时间。可重试。
+    #[error("LLM 限流（服务方），建议等待 {retry_after:?} 后重试")]
     RateLimit { retry_after: Option<Duration> },
 
-    /// HTTP 请求失败，包含状态码和响应体。
-    #[error("请求失败(status={status}): {body}")]
+    /// HTTP 请求失败（网络错误或非 2xx 状态码），包含状态码与响应体。
+    #[error("LLM 请求失败（HTTP {status}）: {body}")]
     Request { status: u16, body: String },
 
-    /// 请求超时。
-    #[error("请求超时(duration={duration:?})")]
+    /// 请求超时。可重试。
+    #[error("LLM 请求超时（{duration:?}）。请检查网络连接，或调大 LlmCycle 超时配置")]
     Timeout { duration: Duration },
 
-    /// 流式响应处理错误（预留）。
-    #[error("流式响应错误: {0}")]
+    /// 流式响应处理错误（SSE 解析失败、流中断等）。可重试。
+    #[error("LLM 流式响应错误: {0}。可重试或改用非流式接口")]
     Stream(String),
 
-    /// 上下文长度超限。
-    #[error("上下文超限(actual={actual}, limit={limit})")]
+    /// 上下文长度超出模型窗口限制。
+    #[error("LLM 上下文超限：当前 {actual} tokens > 模型上限 {limit} tokens。请减少消息历史、缩短 prompt，或启用 auto-compaction（llm::compact）")]
     ContextLength { actual: u32, limit: u32 },
 
     /// 其他未分类的 LLM 调用失败。
     #[error("LLM 调用失败: {0}")]
     Other(String),
-}
+}