ERRORS.md - 错误记录与规避

🎯 核心原则

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

---

📊 错误分类体系

按类型分类

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

按来源分类

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

---

📝 错误记录模板

标准错误记录格式

错误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 认证失败

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

错误描述: 尝试调用 IMA API 时返回错误码 100001

根本原因: APIKey 配置不完整或格式错误

解决方案: 重新从 IMA OpenAPI 控制台获取正确的 API Key

规避措施: 添加 API 连接测试脚本，每次调用前验证凭证

---

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

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

错误描述: 在 WorkBuddy 环境中执行 PowerShell 命令时出现 spawn EPERM 错误

根本原因: WorkBuddy 执行环境对网络请求和系统命令有权限限制

解决方案:

1. 改用 WorkBuddy 内置工具
2. 创建测试指南，让用户手动执行
3. 使用 Python 脚本替代 PowerShell 命令

规避措施:

• 优先使用 WorkBuddy 内置工具
• 避免直接执行系统命令
• 提供手动执行指南作为备选方案

---

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

错误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次/月	性能优化，系统升级

错误恢复策略

# 伪代码：智能重试机制
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)

---

📊 错误统计分析

错误统计模板

统计周期: 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 - 用户偏好与习惯（含错误处理偏好）

---

🎯 持续改进

改进建议收集

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

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

---

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