# 错误智慧库规范 (Error Wisdom Specification)

## 目录
- [概览](#概览)
- [设计理念](#设计理念)
- [核心概念](#核心概念)
- [数据结构](#数据结构)
- [错误分类体系](#错误分类体系)
- [根因分析框架](#根因分析框架)
- [预防知识生成](#预防知识生成)
- [时效性管理](#时效性管理)
- [与现有架构的集成](#与现有架构的集成)
- [API接口](#api接口)
- [最佳实践](#最佳实践)

---

## 概览

### 核心定位

错误智慧库是记录层的**第三轨存储**，专门用于记录、分析和复用错误经验，实现"从错误中学习"的智能体进化能力。

### 核心价值

- **避免重复犯错**：从历史错误中提取预防知识
- **加速学习曲线**：新错误立即转化为可复用知识
- **提升鲁棒性**：前置预防机制降低错误发生率
- **支持进化**：错误知识随时间积累和优化

### 设计原则

1. **超然性**：作为记录层的一部分，不主动干预主循环
2. **查询驱动**：由数学顶点/感知节点主动查询，而非被动推送
3. **渐进式披露**：工具性错误优先（规则明确），认知性错误后续扩展
4. **时效性**：错误知识具有生命周期，过期自动降权或清理

---

## 设计理念

### 从"纠错"到"预防"的进化

```
现有机制（事后纠错）：
用户输入 → 推理 → 错误 → 检测 → 纠错 → 输出

错误智慧库（事前预防）：
用户输入 → 查询预防知识 → 调整策略 → 推理 → 输出
                          ↓
                    （更少错误）
```

### 错误学习的闭环

```
发现问题 → 分析原因 → 解决问题 → 形成预防知识 → 避免重复犯错
    ↑                                                        ↓
    └────────────── 验证与优化 ←─────────────────────────────┘
```

---

## 核心概念

### 错误智慧条目 (Error Wisdom Entry)

错误智慧库的基本单元，记录一次完整的错误学习经验。

**核心组成**：
- **错误发现**：发生了什么错误
- **原因分析**：为什么犯错
- **解决方案**：如何解决
- **预防知识**：下次如何避免
- **验证历史**：预防效果追踪

### 预防规则 (Prevention Rule)

从错误智慧条目中提取的可执行规则，用于前置检查。

**特征**：
- 可程序化执行
- 有明确的触发条件
- 有明确的预防动作

### 时效性 (Timeliness)

错误知识的有效性随时间衰减。

**三重衰减机制**：
1. **时间衰减**：自然过期
2. **场景变化衰减**：环境变化导致失效
3. **反例衰减**：遇到反例时重新评估

---

## 数据结构

### 错误智慧条目结构

```json
{
  "id": "ew_20260305_001",
  "timestamp": "2026-03-05T14:30:00Z",
  "trace_id": "trace_20260305_abc123",
  "version": "1.0",
  
  "错误发现": {
    "错误类型": "工具性错误",
    "子类型": "参数构造错误",
    "错误码": "INVALID_ENUM_VALUE",
    "错误描述": "温度单位参数使用了'kelvin'，但工具仅支持['celsius', 'fahrenheit']",
    "严重程度": "mild",
    "触发场景": "用户询问'开尔文温度'",
    "影响范围": "单次调用"
  },
  
  "原因分析": {
    "根本原因": "模型知道开尔文是温度单位，但未检查工具支持的枚举范围",
    "认知偏差": "知识迁移过度（从物理知识迁移到工具参数）",
    "环境因素": "工具文档中枚举值不够显眼",
    "责任归属": "参数构造阶段",
    "可预防性": "high"
  },
  
  "解决方案": {
    "即时纠错": "将'kelvin'转换为'celsius'后重新调用",
    "纠错成本": "low",
    "有效性": "已验证有效",
    "用户体验补偿": "向用户说明单位转换过程"
  },
  
  "预防知识": {
    "预防策略": "调用工具前，检查枚举参数是否在允许范围内",
    "前置检查规则": {
      "rule_id": "enum_validation_001",
      "condition": "参数类型为enum",
      "check": "value in allowed_values",
      "action": "提示错误或自动转换",
      "auto_fixable": true,
      "fix_method": "convert_to_valid_value"
    },
    "适用场景": ["所有带enum参数的工具调用"],
    "不适用场景": [],
    "预防优先级": "high",
    "预防成本": "极低（<1ms）"
  },
  
  "验证历史": [
    {
      "timestamp": "2026-03-05T16:00:00Z",
      "trace_id": "trace_20260305_def456",
      "场景": "get_weather调用",
      "效果": "成功预防",
      "预防触发": "检测到非法枚举值'kelvin'，自动转换为'celsius'",
      "用户反馈": "positive"
    }
  ],
  
  "关联错误": {
    "相似错误ID": ["ew_20260304_003", "ew_20260303_007"],
    "共性模式": "枚举参数越界",
    "抽象规则ID": "rule_enum_validation"
  },
  
  "元数据": {
    "创建时间": "2026-03-05T14:30:00Z",
    "最后更新": "2026-03-05T16:00:00Z",
    "验证次数": 1,
    "成功预防次数": 1,
    "置信度": 0.95,
    "时效性标记": "active"
  }
}
```

### 字段说明

| 字段路径 | 类型 | 必需 | 说明 |
|---------|------|------|------|
| id | string | 是 | 唯一标识，格式：ew_YYYYMMDD_序号 |
| timestamp | string | 是 | ISO 8601 时间戳 |
| trace_id | string | 是 | 关联的全链路追踪ID |
| version | string | 是 | 数据结构版本 |
| 错误发现.错误类型 | string | 是 | 工具性错误/认知性错误 |
| 错误发现.子类型 | string | 是 | 细分错误类型 |
| 错误发现.错误码 | string | 否 | 系统错误码 |
| 错误发现.严重程度 | string | 是 | none/mild/moderate/severe/critical |
| 原因分析.根本原因 | string | 是 | 核心原因描述 |
| 原因分析.可预防性 | string | 是 | high/medium/low |
| 预防知识.预防策略 | string | 是 | 预防方法描述 |
| 预防知识.前置检查规则 | object | 否 | 可程序化的预防规则 |
| 验证历史 | array | 是 | 预防效果追踪记录 |
| 元数据.置信度 | float | 是 | 0.0-1.0，表示有效性 |
| 元数据.时效性标记 | string | 是 | active/deprecated/archived |

---

## 错误分类体系

### 一级分类

```
错误智慧库
├─ 工具性错误（Phase 1 重点）
│  ├─ 调用失败类
│  ├─ 参数构造类
│  ├─ 结果处理类
│  └─ 工具选择类
│
└─ 认知性错误（Phase 2 扩展）
   ├─ 幻觉倾向类
   ├─ 推理跳跃类
   ├─ 知识缺失类
   └─ 偏见影响类
```

### 二级分类详解

#### 工具性错误

| 子类型 | 常见场景 | 典型错误码 | 预防价值 |
|--------|---------|-----------|---------|
| **调用失败类** | 网络超时、权限拒绝、资源不存在 | TIMEOUT, 401, 403, 404, 429 | 高（可重试/降级） |
| **参数构造类** | 格式错误、缺少参数、值非法 | INVALID_FORMAT, MISSING_PARAM, INVALID_VALUE | 极高（前置检查） |
| **结果处理类** | 解析失败、类型转换错误 | PARSE_ERROR, TYPE_ERROR | 高（增加容错） |
| **工具选择类** | 选错工具、组合顺序错误 | - | 中（需推理优化） |

#### 认知性错误

| 子类型 | 常见场景 | 检测方法 | 预防价值 |
|--------|---------|---------|---------|
| **幻觉倾向类** | 编造事实、虚构API | 元认知检测 | 中高 |
| **推理跳跃类** | 遗漏前提、逻辑跳跃 | 客观性评估 | 中 |
| **知识缺失类** | 知识库中没有相关信息 | 自我评估 | 中 |
| **偏见影响类** | 刻板印象、选择性注意 | 偏见检测 | 中低 |

---

## 根因分析框架

### 工具性错误根因分析

```
工具性错误根因分析框架
    │
    ├─ 参数来源维度
    │  ├─ 用户输入错误
    │  ├─ 模型生成错误
    │  ├─ 知识库数据错误
    │  └─ 上下文推理错误
    │
    ├─ 工具接口维度
    │  ├─ 文档不完整
    │  ├─ 接口变更
    │  ├─ 版本不匹配
    │  └─ 约束不明确
    │
    ├─ 环境因素维度
    │  ├─ 网络问题
    │  ├─ 服务状态
    │  ├─ 资源限制
    │  └─ 并发竞争
    │
    └─ 调用时机维度
       ├─ 过早调用（前置条件未满足）
       ├─ 过晚调用（时效性过期）
       └─ 错误顺序（依赖关系错误）
```

### 认知性错误根因分析

```
认知性错误根因分析框架
    │
    ├─ 认知维度
    │  ├─ 知识缺陷
    │  │  ├─ 完全不知道
    │  │  ├─ 知道但不完整
    │  │  └─ 知道但记错
    │  ├─ 推理偏差
    │  │  ├─ 过度推断
    │  │  ├─ 遗漏前提
    │  │  └─ 逻辑跳跃
    │  └─ 注意力分配
    │     ├─ 忽略关键信息
    │     └─ 过度关注次要信息
    │
    ├─ 情境维度
    │  ├─ 任务复杂性
    │  ├─ 信息完整性
    │  └─ 时间压力
    │
    └─ 系统维度
       ├─ 人格特质影响
       ├─ 学习阶段影响
       └─ 资源约束影响
```

---

## 预防知识生成

### 从错误到预防规则的转化流程

```
错误记录
    ↓
相似错误聚合（≥3个相似错误）
    ↓
共性模式识别
    ↓
预防规则提取
    ↓
规则验证
    ↓
规则生效
    ↓
持续优化
```

### 预防规则结构

```json
{
  "rule_id": "rule_enum_validation_001",
  "rule_name": "枚举参数验证规则",
  "创建时间": "2026-03-05T16:00:00Z",
  "来源错误ID": ["ew_20260305_001", "ew_20260304_003", "ew_20260303_007"],
  
  "触发条件": {
    "工具类型": "any",
    "参数类型": "enum",
    "场景": "工具调用前"
  },
  
  "检查逻辑": {
    "条件": "参数值存在",
    "验证": "参数值 in 枚举范围",
    "失败处理": "提示或自动修正"
  },
  
  "预防动作": {
    "auto_fixable": true,
    "fix_method": "convert_to_nearest_valid_value",
    "fallback_action": "reject_with_suggestion"
  },
  
  "适用范围": {
    "工具列表": ["*"],
    "参数模式": ["*_type", "*_unit", "*_format"],
    "排除场景": []
  },
  
  "效果统计": {
    "应用次数": 47,
    "成功预防次数": 45,
    "失败次数": 2,
    "成功率": 0.957
  },
  
  "时效性": {
    "状态": "active",
    "置信度": 0.95,
    "最后验证": "2026-03-10T10:00:00Z",
    "衰减系数": 0.98
  }
}
```

---

## 时效性管理

### 三重衰减机制

#### 1. 时间衰减

```python
def time_decay(base_confidence: float, days_since_creation: int) -> float:
    """
    时间衰减公式
    
    Args:
        base_confidence: 初始置信度
        days_since_creation: 创建至今的天数
    
    Returns:
        衰减后的置信度
    """
    lambda_decay = 0.01  # 每天衰减1%
    return base_confidence * math.exp(-lambda_decay * days_since_creation)
```

#### 2. 场景变化衰减

**触发条件**：
- 知识库重大更新
- 模型版本升级
- 工具接口变更
- 领域迁移

**衰减策略**：
- 立即降低置信度 30-50%
- 需要重新验证

#### 3. 反例衰减

**触发条件**：
- 预防策略失效导致新错误
- 验证历史中出现失败记录

**衰减策略**：
```python
def counterexample_decay(current_confidence: float, counterexample_count: int) -> float:
    """
    反例衰减
    
    Args:
        current_confidence: 当前置信度
        counterexample_count: 反例数量
    
    Returns:
        衰减后的置信度
    """
    decay_factor = 0.7 ** counterexample_count  # 每个反例降低30%
    return current_confidence * decay_factor
```

### 时效性状态

| 状态 | 置信度范围 | 行为 |
|------|-----------|------|
| active | > 0.7 | 正常使用 |
| deprecated | 0.3 - 0.7 | 仅作参考，不自动执行 |
| archived | < 0.3 | 存档，不再使用 |

---

## 与现有架构的集成

### 记录层中的位置

```
记录层三轨存储
    │
    ├─ JSON轨（结构化记录）
    │
    ├─ Markdown轨（自我叙事）
    │
    └─ Error Wisdom 轨（错误智慧库）  ← 新增
       ├─ error_wisdom_entries.json
       ├─ prevention_rules.json
       └─ error_patterns.json
```

### 信息流向

```
感知节点工具调用
      ↓
错误发生
      ↓
记录层存储（现有）
      ↓
错误智慧库分析（新增）
      ↓
形成预防知识
      ↓
下次调用前查询（新增）
      ↓
应用预防策略
      ↓
减少错误发生
```

### 集成点

| 集成点 | 时机 | 数据流向 | 职责 |
|--------|------|---------|------|
| 感知节点 | 工具调用后 | 错误信息 → 错误智慧库 | 错误记录 |
| 感知节点 | 工具调用前 | 预防知识 ← 错误智慧库 | 预防查询 |
| 元认知检测 | 检测完成后 | 认知性错误 → 错误智慧库 | 错误记录 |
| 记录层 | 周期性 | 错误聚合 → 预防规则 | 规则生成 |

---

## API接口

### 错误记录接口

```python
def record_error(
    error_type: str,
    error_subtype: str,
    error_code: str,
    error_description: str,
    root_cause: str,
    solution: str,
    prevention_strategy: str,
    trace_id: str,
    metadata: dict = None
) -> str:
    """
    记录错误到智慧库
    
    Args:
        error_type: 错误类型（工具性/认知性）
        error_subtype: 错误子类型
        error_code: 错误码
        error_description: 错误描述
        root_cause: 根本原因
        solution: 解决方案
        prevention_strategy: 预防策略
        trace_id: 追踪ID
        metadata: 额外元数据
    
    Returns:
        错误智慧条目ID
    """
    pass
```

### 预防查询接口

```python
def query_prevention(
    context: dict,
    tool_name: str = None,
    params: dict = None
) -> List[dict]:
    """
    查询预防知识
    
    Args:
        context: 当前上下文
        tool_name: 工具名称（可选）
        params: 参数（可选）
    
    Returns:
        相关的预防规则列表
    """
    pass
```

### 前置检查接口

```python
def pre_check(
    tool_name: str,
    params: dict
) -> dict:
    """
    工具调用前的前置检查
    
    Args:
        tool_name: 工具名称
        params: 调用参数
    
    Returns:
        {
            "pass": bool,           # 是否通过检查
            "warnings": [],         # 警告信息
            "auto_fixes": {},       # 自动修正
            "suggestions": []       # 建议
        }
    """
    pass
```

---

## 最佳实践

### 错误记录最佳实践

1. **及时记录**：错误发生时立即记录，避免信息丢失
2. **完整记录**：包含完整的上下文信息
3. **根因深入**：不满足于表面原因，深挖根本原因
4. **预防导向**：记录时就思考如何预防

### 预防应用最佳实践

1. **优先级排序**：高预防价值规则优先应用
2. **成本控制**：预防成本应低于错误成本
3. **渐进式启用**：新规则先观察，验证后全面启用
4. **用户友好**：预防失败时给出清晰建议

### 时效性管理最佳实践

1. **定期审计**：定期检查错误知识的有效性
2. **快速响应**：场景变化时及时更新置信度
3. **反馈闭环**：验证结果及时反馈到置信度计算

---

## 示例

### 完整示例：工具调用参数错误

```json
{
  "id": "ew_20260305_015",
  "timestamp": "2026-03-05T18:45:32Z",
  "trace_id": "trace_20260305_xyz789",
  "version": "1.0",
  
  "错误发现": {
    "错误类型": "工具性错误",
    "子类型": "参数构造错误",
    "错误码": "INVALID_DATE_FORMAT",
    "错误描述": "日期参数使用了'2026/03/05'格式，但API要求ISO 8601格式'2026-03-05'",
    "严重程度": "mild",
    "触发场景": "调用日历API查询日程",
    "影响范围": "单次调用"
  },
  
  "原因分析": {
    "根本原因": "用户输入格式与API要求格式不一致，未做格式转换",
    "认知偏差": "无",
    "环境因素": "用户习惯使用斜杠分隔日期",
    "责任归属": "参数预处理阶段",
    "可预防性": "high"
  },
  
  "解决方案": {
    "即时纠错": "将'2026/03/05'转换为'2026-03-05'后重新调用",
    "纠错成本": "low",
    "有效性": "已验证有效",
    "用户体验补偿": "无"
  },
  
  "预防知识": {
    "预防策略": "对所有日期参数进行格式标准化",
    "前置检查规则": {
      "rule_id": "date_format_standardization",
      "condition": "参数包含日期",
      "check": "match ISO 8601 format",
      "action": "auto convert to ISO 8601",
      "auto_fixable": true,
      "fix_method": "normalize_date_format"
    },
    "适用场景": ["所有日期参数"],
    "不适用场景": [],
    "预防优先级": "high",
    "预防成本": "极低"
  },
  
  "验证历史": [
    {
      "timestamp": "2026-03-05T19:00:00Z",
      "trace_id": "trace_20260305_abc123",
      "场景": "日历API调用",
      "效果": "成功预防",
      "预防触发": "自动转换日期格式",
      "用户反馈": "positive"
    }
  ],
  
  "关联错误": {
    "相似错误ID": [],
    "共性模式": "日期格式不一致",
    "抽象规则ID": "rule_date_normalization"
  },
  
  "元数据": {
    "创建时间": "2026-03-05T18:45:32Z",
    "最后更新": "2026-03-05T19:00:00Z",
    "验证次数": 1,
    "成功预防次数": 1,
    "置信度": 0.90,
    "时效性标记": "active"
  }
}
```

---

## 版本历史

| 版本 | 日期 | 变更内容 |
|------|------|---------|
| 1.0 | 2026-03-05 | 初始版本，工具性错误支持 |
| 2.0 | 2026-03-15 | Phase 2: 认知性错误支持 |

---

## Phase 2: 认知性错误详解

### 概述

Phase 2 扩展错误智慧库以支持认知性错误的识别、分析和预防。认知性错误源于模型内部推理过程，包括幻觉倾向、推理跳跃、知识缺失和偏见影响四类。

### 认知性错误分类

#### 1. 幻觉倾向类（Hallucination）

**特征**：生成与事实不符或虚构的内容

**典型场景**：
- 编造不存在的API或函数
- 虚构统计数据或研究结果
- 生成不存在的引用或出处

**检测方法**：
- 元认知检测中的"幻觉检测模式"
- 客观性评估器的主观性维度检测
- 知识库交叉验证

**根因分析维度**：
- 知识缺陷：完全不知道或知道但不完整
- 推理偏差：过度推断
- 注意力分配：忽略关键信息

#### 2. 推理跳跃类（Reasoning Jump）

**特征**：推理过程中遗漏关键前提或逻辑步骤

**典型场景**：
- 直接给出结论而缺少论证
- 隐含假设未明确说明
- 因果关系过度简化

**检测方法**：
- 客观性评估器的逻辑完整性检测
- 推理链路验证

**根因分析维度**：
- 推理偏差：遗漏前提、逻辑跳跃
- 注意力分配：过度关注次要信息
- 情境维度：时间压力

#### 3. 知识缺失类（Knowledge Gap）

**特征**：知识库中缺少必要信息导致的错误

**典型场景**：
- 回答超出知识截止日期的问题
- 领域专业知识不足
- 最新事件或变化未更新

**检测方法**：
- 自我评估机制
- 置信度阈值检测

**根因分析维度**：
- 知识缺陷：完全不知道或知道但不完整
- 系统维度：学习阶段影响

#### 4. 偏见影响类（Bias Influence）

**特征**：刻板印象或选择性注意导致的偏见输出

**典型场景**：
- 性别、地域、职业等刻板印象
- 选择性引用信息
- 确认偏误

**检测方法**：
- 偏见检测模式
- 多角度平衡性检查

**根因分析维度**：
- 注意力分配：选择性注意
- 系统维度：人格特质影响

---

### 认知性错误条目示例

```json
{
  "id": "ew_20260315_001",
  "timestamp": "2026-03-15T10:30:00Z",
  "trace_id": "trace_20260315_cog001",
  "version": "2.0",
  
  "错误发现": {
    "错误类型": "认知性错误",
    "子类型": "幻觉倾向",
    "错误描述": "生成了不存在的API函数'get_realtime_stock_price'",
    "严重程度": "moderate",
    "触发场景": "用户询问实时股票价格",
    "影响范围": "功能可用性",
    "检测方法": "客观性评估器检测到高主观性分数"
  },
  
  "原因分析": {
    "根本原因": "模型推测存在获取实时股价的API，但未验证API是否真实存在",
    "认知维度分析": {
      "知识缺陷": "知道股票价格概念，但不知道当前环境无实时API",
      "推理偏差": "过度推断——认为既然有股票概念就应该有相关API",
      "注意力分配": "忽略了工具列表中无此API的事实"
    },
    "情境维度分析": {
      "任务复杂性": "中等",
      "信息完整性": "工具列表不完整",
      "时间压力": "无"
    },
    "系统维度分析": {
      "人格特质影响": "高开放性导致倾向于创造性回答",
      "学习阶段": "早期"
    },
    "可预防性": "high"
  },
  
  "解决方案": {
    "即时纠错": "明确告知用户当前无实时股价API，建议替代方案",
    "纠错成本": "low",
    "有效性": "已验证",
    "用户体验补偿": "提供其他可用的金融相关工具"
  },
  
  "预防知识": {
    "预防策略": "在提及任何API或工具前，先在工具列表中验证其存在性",
    "前置检查规则": {
      "rule_id": "api_existence_check",
      "condition": "准备调用或提及API",
      "check": "API名称 in 可用工具列表",
      "action": "若不存在则明确说明",
      "auto_fixable": false,
      "fix_method": "查询工具列表并确认"
    },
    "适用场景": ["所有工具/API相关回答"],
    "不适用场景": [],
    "预防优先级": "high",
    "预防成本": "低（查询工具列表）"
  },
  
  "验证历史": [],
  
  "关联错误": {
    "相似错误ID": [],
    "共性模式": "虚构工具/API",
    "抽象规则ID": "rule_tool_verification"
  },
  
  "元数据": {
    "创建时间": "2026-03-15T10:30:00Z",
    "最后更新": "2026-03-15T10:30:00Z",
    "验证次数": 0,
    "成功预防次数": 0,
    "置信度": 0.85,
    "时效性标记": "active",
    "认知性错误标记": true
  }
}
```

---

### 认知性错误检测流程

```
客观性评估器运行
        ↓
检测到严重程度 moderate/severe
        ↓
调用认知性错误分析器
        ↓
执行四类错误识别
├─ 幻觉倾向检测
├─ 推理跳跃检测
├─ 知识缺失检测
└─ 偏见影响检测
        ↓
多维度根因分析
├─ 认知维度
├─ 情境维度
└─ 系统维度
        ↓
生成预防建议
        ↓
记录到错误智慧库
```

---

### 与元认知检测的集成

认知性错误检测与元认知检测（客观性评估器）深度集成：

**触发时机**：
- 客观性评估器检测到 `severity` 为 `moderate` 或 `severe` 时

**数据流向**：
```
客观性评估结果
    ├── subjectivity_score
    ├── objectivity_score
    ├── gap
    ├── subjectivity_dimensions
    └── severity
            ↓
    认知性错误分析器
            ↓
    错误智慧库条目
```

**关键接口**：
- `ObjectivityEvaluator._record_cognitive_error()` - 在客观性评估后触发记录
- `CognitiveErrorAnalyzer.analyze()` - 执行认知性错误分析
- `CognitiveErrorAnalyzer.to_error_wisdom_entry()` - 转换为错误智慧库条目格式

---

### 认知性错误预防策略

#### 通用预防原则

1. **验证先行**：在做出断言前先验证
2. **明确边界**：清晰说明知识的边界和限制
3. **标注置信度**：对不确定内容标注置信度
4. **多角度思考**：避免单一视角导致的偏见

#### 分类预防策略

| 错误类型 | 预防策略 | 前置检查 |
|---------|---------|---------|
| 幻觉倾向 | API/工具验证、知识库交叉验证 | 工具存在性检查 |
| 推理跳跃 | 完整推理链路、明确前提 | 逻辑完整性检查 |
| 知识缺失 | 知识边界声明、替代方案提供 | 知识覆盖度检查 |
| 偏见影响 | 多角度分析、平衡性检查 | 偏见模式匹配 |

---

### 效果评估指标

**Phase 2 新增指标**：

| 指标 | 计算方法 | 目标值 |
|------|---------|--------|
| 认知性错误识别率 | 正确识别的认知性错误数 / 总认知性错误数 | > 80% |
| 根因分析准确性 | 准确的根因分析数 / 总根因分析数 | > 70% |
| 预防策略有效性 | 成功预防次数 / 预防策略应用次数 | > 75% |
| 幻觉倾向降低率 | (基线幻觉数 - 当前幻觉数) / 基线幻觉数 | > 50% |

---

### 最佳实践

#### 智能体开发者

1. 在响应生成后调用客观性评估器
2. 根据严重程度决定是否记录认知性错误
3. 定期分析错误智慧库中的认知性错误模式
4. 基于预防策略调整推理流程

#### 错误分析流程

```python
# 集成示例
from objectivity_evaluator import ObjectivityEvaluator
from cognitive_error_analyzer import CognitiveErrorAnalyzer
from error_wisdom_manager import ErrorWisdomManager

# 初始化组件
error_manager = ErrorWisdomManager("./agi_memory")
cognitive_analyzer = CognitiveErrorAnalyzer()
evaluator = ObjectivityEvaluator(
    error_wisdom_manager=error_manager,
    cognitive_error_analyzer=cognitive_analyzer
)

# 评估响应
metric = evaluator.evaluate(response, context_type)

# 如果严重程度较高，自动记录认知性错误
# （已集成在 evaluator 内部）
```

---

## Phase 3: 预防引擎与时效性管理

### 概述

Phase 3 实现错误智慧库的完整闭环：预防规则自动生成、时效性三重衰减、与主循环深度集成。

### 核心模块

#### 1. 时效性管理模块 (error_wisdom_timeliness.py)

**三重衰减机制**：

| 衰减类型 | 触发条件 | 衰减公式 | 说明 |
|---------|---------|---------|------|
| 时间衰减 | 自然过期 | `confidence = base × e^(-0.01×days)` | 每日衰减1% |
| 场景变化衰减 | 知识库更新/模型升级/工具变更 | `confidence × (1-0.35)` | 降低35% |
| 反例衰减 | 预防策略失效 | `confidence × 0.7^n` | 每个反例降低30% |

**状态转换**：

```
confidence > 0.7  →  active (正常使用)
0.3 ≤ confidence ≤ 0.7  →  deprecated (仅作参考)
confidence < 0.3  →  archived (存档)
```

#### 2. 规则自动生成模块 (error_wisdom_rule_generator.py)

**生成流程**：

```
错误条目
    ↓
相似度聚合（阈值 ≥ 0.60）
    ↓
形成聚类（最小规模 ≥ 3）
    ↓
提取共性特征
    ↓
匹配规则模板
    ↓
生成预防规则
    ↓
保存与验证
```

**相似度计算维度**：

| 维度 | 权重 | 计算方法 |
|------|------|---------|
| 错误类型 | 25% | 精确匹配 |
| 子类型 | 20% | 精确匹配 |
| 触发模式 | 25% | Jaccard相似度 |
| 根因类别 | 30% | Jaccard相似度 |

#### 3. 预防规则引擎 (error_wisdom_prevention.py)

**内置规则**：

| 规则 | 优先级 | 自动修正 | 说明 |
|------|--------|---------|------|
| 必需参数检查 | critical | 否 | 检查缺失的必需参数 |
| 枚举参数验证 | high | 是 | 自动转换到有效值 |
| 类型验证 | high | 否 | 检查参数类型 |
| 范围验证 | medium | 是 | 自动约束到边界值 |
| 格式验证 | low | 否 | 检查格式合规性 |

---

### 与主循环的集成

#### 集成点

```
主循环流程：
                    ┌─────────────────────┐
                    │   用户输入/任务     │
                    └─────────┬───────────┘
                              ↓
              ┌───────────────────────────────┐
              │  感知节点（工具调用前）        │
              │  → 预防查询（Phase 3新增）     │
              │  → 前置检查（预防引擎）        │
              └─────────┬─────────────────────┘
                        ↓
              ┌───────────────────────────────┐
              │   工具调用执行                 │
              └─────────┬─────────────────────┘
                        ↓
              ┌───────────────────────────────┐
              │  感知节点（工具调用后）        │
              │  → 错误记录（Phase 1/2已有）   │
              │  → 时效性同步（Phase 3新增）   │
              └─────────┬─────────────────────┘
                        ↓
              ┌───────────────────────────────┐
              │  元认知检测（客观性评估）      │
              │  → 认知性错误分析（Phase 2）   │
              └─────────┬─────────────────────┘
                        ↓
              ┌───────────────────────────────┐
              │  记录层（周期性）              │
              │  → 规则生成（Phase 3新增）     │
              │  → 时效性审计（Phase 3新增）   │
              └───────────────────────────────┘
```

---

### API接口

#### 时效性管理接口

```python
from error_wisdom_timeliness import TimelinessManager

# 初始化
timeliness = TimelinessManager("./agi_memory")

# 获取置信度
confidence = timeliness.get_confidence(entry_id, entry_data)

# 判断是否可用
is_usable = timeliness.is_usable(entry_id)

# 注册场景变化
timeliness.register_scene_change(
    change_type="model_upgrade",
    change_description="模型升级到新版本",
    affected_patterns=["ew_001", "ew_002"]
)

# 注册反例
timeliness.register_counterexample(entry_id, "预防策略失效")

# 运行审计
audit_report = timeliness.run_audit(entries_data)
```

#### 规则生成接口

```python
from error_wisdom_rule_generator import RuleGenerationManager

# 初始化
rule_manager = RuleGenerationManager("./agi_memory", timeliness_manager)

# 运行生成流水线
report = rule_manager.run_generation_pipeline(
    entries=error_wisdom_entries,
    min_cluster_size=3
)

# 输出
print(f"生成规则数: {report['rules_generated']}")
for rule in report['rules']:
    print(f"  {rule['rule_name']}: 置信度 {rule['confidence']:.3f}")
```

---

### 效果评估指标

**Phase 3 新增指标**：

| 指标 | 计算方法 | 目标值 |
|------|---------|--------|
| 规则自动生成率 | 自动生成规则数 / 总预防规则数 | > 60% |
| 时效性审计覆盖率 | 审计条目数 / 总条目数 | 100% |
| 聚类准确性 | 有效聚类数 / 总聚类数 | > 80% |
| 预防前置拦截率 | 前置拦截错误数 / 可预防错误数 | > 70% |

---

### 最佳实践

#### 时效性管理

1. 定期运行时效性审计（建议每日一次）
2. 场景变化时主动注册事件
3. 关注deprecated状态条目，决定是否重新验证或清理

#### 规则生成

1. 保持最小聚类规模 ≥ 3，确保规则可靠性
2. 对新生成规则先观察验证，再全面启用
3. 定期分析规则效果，移除低效规则

#### 预防应用

1. 工具调用前强制执行前置检查
2. 记录检查结果用于效果评估
3. 平衡预防成本与错误成本