ERRORS.md - 错误记录与规避

🎯 核心原则

> 错误不是失败，是进化的阶梯。 > 记录、分析、规避、进化——从错误中学习，让系统更强大。

---

📊 错误分类体系

按类型分类

| 错误类型 | 优先级 | 处理策略 | |---------|--------|---------| | API 错误 | P0 | 立即记录，检查凭证，优化重试机制 | | 权限错误 | P0 | 立即记录，检查权限配置，提供解决方案 | | 格式错误 | P1 | 记录并分析，优化输入验证逻辑 | | 逻辑错误 | P1 | 记录并分析，优化算法和流程 | | 性能问题 | P2 | 记录并监控，优化性能瓶颈 | | 兼容性错误 | P2 | 记录并标记，提供兼容方案 |

按来源分类

| 来源 | 说明 | |------|------| | 系统错误 | API 不可用、服务超时等 | | 用户输入错误 | 参数错误、格式错误等 | | 工具调用错误 | 工具不可用、版本不兼容等 | | 逻辑错误 | 流程错误、决策错误等 | | 权限错误 | 访问拒绝、权限不足等 |

---

📝 错误记录模板

标准错误记录格式

```yaml 错误ID: ERR-20260321-001 发生时间: 2026-03-21 10:30:00 错误类型: API错误错误来源: 系统错误

错误描述: 尝试调用 IMA API 获取笔记本列表时，返回认证失败错误码 100001

复现步骤: 1. 配置 ClientID 和 APIKey 2. 调用 /notebooks 接口 3. 返回 code: 100001

根本原因: APIKey 可能配置错误或已过期

解决方案: 1. 检查 IMA_OPENAPI_APIKEY 环境变量是否正确 2. 访问 https://ima.qq.com/agent-interface 重新获取 API Key 3. 确认 ClientID 正确：59a1edb848ec905552c0fbc8041213bf

规避措施: - 添加 API 连接测试脚本 - 每次调用前验证凭证有效性 - 设置重试机制（最多 3 次）

状态: ✅ 已解决影响范围: 低相关文档: IMA_API_测试指南.md ```

---

📚 错误案例库

案例 1: IMA API 认证失败

```yaml 错误ID: ERR-20260321-001 发生时间: 2026-03-21 10:30:00 错误类型: API错误状态: ✅ 已解决 ```

错误描述: 尝试调用 IMA API 时返回错误码 100001 根本原因: APIKey 配置不完整或格式错误 解决方案: 重新从 IMA OpenAPI 控制台获取正确的 API Key 规避措施: 添加 API 连接测试脚本，每次调用前验证凭证

---

案例 2: PowerShell 执行权限错误 (spawn EPERM)

```yaml 错误ID: ERR-20260321-002 发生时间: 2026-03-21 10:15:00 错误类型: 权限错误状态: ⏳ 已记录，待解决 ```

错误描述: 在 WorkBuddy 环境中执行 PowerShell 命令时出现 `spawn EPERM` 错误 根本原因: WorkBuddy 执行环境对网络请求和系统命令有权限限制 解决方案: 1. 改用 WorkBuddy 内置工具 2. 创建测试指南，让用户手动执行 3. 使用 Python 脚本替代 PowerShell 命令 规避措施:

优先使用 WorkBuddy 内置工具

避免直接执行系统命令

提供手动执行指南作为备选方案

---

案例 3: 文件路径编码问题

```yaml 错误ID: ERR-20260321-003 发生时间: 2026-03-20 14:20:00 错误类型: 格式错误状态: ✅ 已解决 ```

错误描述: Windows 系统上执行包含中文路径的 PowerShell 脚本时出现编码错误 根本原因: PowerShell 默认编码为 GBK，而脚本文件为 UTF-8 解决方案: 1. 避免在脚本文件中使用中文字符 2. 使用绝对路径而非相对路径 3. 直接执行命令而非创建脚本文件 规避措施:

文件命名使用英文

避免在中文名路径下执行脚本

优先使用直接命令而非脚本

---

🔄 错误学习机制

从错误中进化的三阶段

#### 阶段一：记录（Record）

记录错误详情（时间、类型、描述）

记录复现步骤和根本原因

记录解决方案和规避措施

#### 阶段二：分析（Analyze）

分析错误模式

识别系统性问题

提出改进方案

#### 阶段三：规避（Avoid）

实施规避措施

更新系统配置

验证改进效果

自动化学习流程

``` 错误发生 ↓ 自动记录到 ERRORS.md ↓ 分析错误模式 ↓ 更新系统配置/代码 ↓ 验证改进效果 ↓ 归档到知识库 ```

---

🎯 错误预警机制

高频错误监控

| 错误类型 | 频率阈值 | 触发动作 | |---------|---------|---------| | API 错误 | 3次/小时 | 检查服务状态，发送预警 | | 权限错误 | 2次/天 | 检查权限配置，发送提醒 | | 逻辑错误 | 5次/周 | 优化算法，更新文档 | | 性能问题 | 10次/月 | 性能优化，系统升级 |

错误恢复策略

```python

伪代码：智能重试机制

def retry_with_backoff(func, max_retries=3): retry_count = 0 while retry_count < max_retries: try: return func() except Error as e: retry_count += 1 if retry_count >= max_retries: log_error(e) raise wait_time = 2 ** retry_count # 指数退避 sleep(wait_time) ```

---

📊 错误统计分析

错误统计模板

```yaml 统计周期: 2026-03-01 ~ 2026-03-21 总错误数: 15 已解决: 12 待解决: 3 解决率: 80%

错误类型分布: - API错误: 5 (33%) - 权限错误: 3 (20%) - 格式错误: 4 (27%) - 逻辑错误: 3 (20%)

高频错误: 1. spawn EPERM (4次) → 已有规避措施 2. API 认证失败 (2次) → 已解决 3. 路径编码错误 (3次) → 已解决 ```

---

🔍 错误查询系统

快速查询命令

``` 查询所有未解决的错误: 搜索: "状态: ⏳"

查询本周 API 错误: 搜索: "错误类型: API错误" + 时间范围

查询高频错误: 统计: 按错误ID计数

查询特定错误ID: 搜索: "ERR-20260321-001" ```

---

📚 相关文档

LEARNINGS.md - 从错误中学习的知识积累

MEMORY.md - 记忆系统架构

SOUL.md - 核心身份与自我进化机制

USER.md - 用户偏好与习惯（含错误处理偏好）

---

🎯 持续改进

改进建议收集

如果遇到错误或改进建议，请按以下格式记录：

```yaml 改进ID: IMP-20260321-001 类型: 功能改进/性能优化/用户体验描述: [具体描述] 优先级: P0/P1/P2/P3 提出时间: 2026-03-21 ```

---

文档版本: 1.0 最后更新: 2026-03-21 维护者: 龙龟神将 下次审查: 2026-04-21