correction-logger - 纠正记录插件

概述

correction-logger 是 Self-Improving + Proactive Agent (SIPA) 系统的第一个单功能拆分插件，负责记录用户纠正、代理错误、以及系统自我改进的关键事件。集成 NeverOnce 理念：修正优先级系统、有效性反馈、FTS5全文搜索。插件保持与现有 ~/self‑improving/corrections.md 文件格式完全兼容，同时提供结构化 API 与适配器接口，便于星型架构其他组件调用。

功能特性

NeverOnce 增强功能

• ✅ 修正优先级系统：修正固定优先级10/10，永不衰减，始终优先召回
• ✅ 有效性反馈系统：.helped() 反馈记录，动态有效性分数计算
• ✅ FTS5全文搜索：SQLite FTS5 全文搜索，BM25 相关性排序
• ✅ 行动前检查：check_corrections_for_action() 预检相关修正
• ✅ 增强统计报告：优先级分布、有效性分析、学习进度跟踪
• ✅ 向后兼容：保持现有 corrections.md 文件格式完全兼容

兼容性说明

• 文件格式：继续使用现有 Markdown 格式，新增 SQLite 数据库存储增强元数据
• API 兼容：原有 API 完全兼容，新增增强方法可选使用
• 数据迁移：自动迁移现有修正到增强存储格式

核心功能

• ✅ 纠正记录：将用户纠正、代理错误、改进建议以标准格式写入文件
• ✅ 记录查询：获取最近 N 条纠正记录（支持过滤、排序）
• ✅ 统计报告：生成纠正数量、时间分布、错误类型统计
• ✅ 健康检查：验证文件可写性、格式有效性、服务可用性

兼容性保证

• 🔄 文件格式不变：继续使用现有 Markdown 列表格式，确保现有工具（如 self‑improving 技能）无需修改
• 🔄 原子写入：使用文件锁避免多进程/多线程写入冲突
• 🔄 自动归档：当 corrections.md 超过 1000 行时自动创建归档文件（corrections_YYYY‑MM‑DD.md）

适配器接口

• 🧩 MemoryAdapter 兼容：实现 MemoryAdapter 基类，提供 log_correction、get_recent_corrections、get_stats、health_check 方法
• 🧩 星型架构注册：自动注册到星型架构注册表，依赖关系为 self‑improving

安装与配置

安装方法

# 从 ClawHub 安装（发布后）
clawhub install correction-logger

# 或本地开发模式
cp -r correction-logger /root/.openclaw/workspace/skills/

配置文件

config/default.yaml：

# 纠正记录配置
corrections_file: "~/self-improving/corrections.md"
max_lines_per_file: 1000
archive_directory: "~/self-improving/archive/"
enable_health_check: true
health_check_interval_seconds: 300

# 适配器配置
adapter:
  name: "correction_logger"
  version: "0.1.0"
  dependencies:
    - "self-improving"

使用方法

Python API

from correction_logger import CorrectionLogger

logger = CorrectionLogger()

# 记录纠正
correction_id = logger.log_correction(
    user_input="你刚才说的版本号错了",
    agent_response="当前版本是 v0.1.0",
    corrected_response="应该是 v0.5.0",
    context={"skill": "evolution-watcher", "timestamp": "2026-03-18T15:30:00Z"}
)

# 获取最近纠正
recent = logger.get_recent_corrections(limit=10)

# 获取统计
stats = logger.get_stats()
print(f"总纠正数: {stats['total_corrections']}")

# 健康检查
health = logger.health_check()

适配器调用

from integration.adapter.correction_logger_adapter import CorrectionLoggerAdapter

adapter = CorrectionLoggerAdapter()
health = adapter.health_check()
print(health['healthy'])  # True/False

命令行工具

# 记录纠正（测试用）
python3 scripts/correction_logger.py log --input "你错了" --response "旧答案" --corrected "新答案"

# 查看最近纠正
python3 scripts/correction_logger.py recent --limit 5

# 运行健康检查
python3 scripts/correction_logger.py health

集成示例

与 evolution‑watcher 集成

当 evolution‑watcher 检测到插件升级失败时，自动记录纠正：

def record_upgrade_failure(plugin_name, error_message):
    from correction_logger import CorrectionLogger
    logger = CorrectionLogger()
    logger.log_correction(
        user_input=f"升级 {plugin_name} 失败",
        agent_response="尝试自动升级插件",
        corrected_response="需要手动检查依赖冲突",
        context={"plugin": plugin_name, "error": error_message}
    )

与 self‑improving 技能集成

self‑improving 技能通过适配器调用纠正记录，无需直接操作文件：

# 原代码（直接写入文件）
with open("~/self-improving/corrections.md", "a") as f:
    f.write(f"- **{timestamp}** 用户纠正: ...")

# 新代码（通过适配器）
adapter = CorrectionLoggerAdapter()
adapter.log_correction(...)

文件格式

纠正记录格式

每行格式：

- **YYYY‑MM‑DD HH:MM:SS** 用户纠正: {用户输入} | 代理回应: {代理回应} | 纠正后: {纠正后内容} [上下文: {JSON}]

示例：

- **2026‑03‑18 15:30:00** 用户纠正: 你刚才说的版本号错了 | 代理回应: 当前版本是 v0.1.0 | 纠正后: 应该是 v0.5.0 [上下文: {"skill": "evolution-watcher"}]

归档文件命名

当主文件超过 1000 行时，自动创建：

corrections_2026‑03‑18.md  # 包含前1000行
corrections.md             # 重置为空，继续写入新记录

适配器接口规范

必需方法

健康检查响应格式

{
  "healthy": true,
  "status": "healthy",
  "message": "纠正记录服务正常",
  "stats": {
    "total_corrections": 42,
    "last_correction_time": "2026‑03‑18T15:30:00Z",
    "file_size_bytes": 12345,
    "file_writable": true
  },
  "plugin": "correction-logger",
  "version": "1.0.0",
  "timestamp": "2026‑03‑18T15:31:00Z"
}

故障排除

常见问题

1. 文件权限错误：确保 ~/self‑improving/ 目录对当前用户可写
2. 格式损坏：如果 corrections.md 格式损坏，插件会自动创建备份并新建文件
3. 适配器注册失败：检查星型架构注册表中 correction‑logger 条目是否存在

日志位置

• 插件日志：/tmp/correction‑logger.log
• 适配器日志：通过 adapter_cli.py health 查看

错误码

版本历史

v0.1.0 (2026‑03‑18)

• 初始版本
• 提供基本纠正记录、查询、统计功能
• 实现 MemoryAdapter 接口
• 保持与现有文件格式兼容

贡献与支持

• 问题反馈：通过 ClawHub 提交 Issue
• 开发指南：参见 DEVELOPMENT.md（待补充）
• 依赖关系：仅依赖 Python 标准库，无外部包要求

此插件为 SIPA 单功能拆分试点，旨在验证周边插件拆分模式，为后续 rule‑ranker、layer‑manager 等插件奠定基础。