Skip to content

knowledge-error-patterns.md

Latest commit

 

History

History
365 lines (284 loc) · 10.4 KB

knowledge-error-patterns.md

File metadata and controls

365 lines (284 loc) · 10.4 KB
Raw

知识工程错误模式库

基于18项增强的实际错误追踪经验 版本：v1.0 | 2026-05-17

概述

本文档将知识工程中遇到的错误模式固化到 debug skill 中，供 auditor 和 agent-planner 在执行知识工程任务时快速诊断问题。每种错误模式包含：特征描述、根因分析、诊断命令、解决方案。

1. 子代理超时错误模式

错误模式1.1：调研超时

属性 内容
错误特征 子代理输出为空或仅含部分内容
根因 调研+写入双任务耗时长，5分钟超时不够
高风险任务 任务描述含"调研"/"研究"/"调研+写入"
预防 调研类→2分钟超时+主会话备选
诊断命令 sessions_history <session-key> limit=5

诊断流程：

子代理超时通知
    ↓
检查sessions_history输出
    ↓
若仅含部分内容 → 内容已写入，grep验证
若为空 → 主会话备选直接输出

错误模式1.2：写入超时

属性 内容
错误特征 子代理输出含写入指令但文件未变更
根因 Windows文件锁/编码问题/BOM问题
高风险操作 跨平台写入/含中文内容写入/BOM敏感文件
预防 使用 qclaw-text-file skill 处理写入
诊断命令 Select-String "章节标题" 文件.md

诊断流程：

子代理报告完成但文件未变更
    ↓
grep确认章节标题是否已存在
    ↓
若已存在 → 标记✅完成（超时前已写入）
若不存在 → 使用qclaw-text-file skill补写

错误模式1.3：验证超时

属性 内容
错误特征 增强内容已写入但子代理报告超时
根因 子代理内部超时（Agent Result timeout）先于操作完成触发
诊断命令 Get-Content 文件.md | Select-String "章节标题"
教训 超时是效率问题，不是结果问题

超时与结果的4种组合：

状态 超时 结果 含义
✅ 否 成功 正常完成
⚠️ 是 成功 超时前已写入，主会话grep验证
⚠️ 是 部分成功 超时中断，需检查文件
❌ 是 失败 完全未执行，需补做

2. 内容插入错误模式

错误模式2.1：位置错误

属性 内容
错误特征 章节插入到文件末尾而非指定位置
根因 指令不明确（用"末尾"而非"在XX之后"）
诊断命令 Select-String "^## X\.Y " 文件.md（精确匹配）
解决方案 明确"在现有第X节之后新增"

位置错误检测脚本：

# check_position.py
import re
from pathlib import Path

def check_section_position(file_path, section_title, expected_after):
    content = Path(file_path).read_text(encoding='utf-8')
    lines = content.split('\n')
    
    # 找目标章节
    target_lines = [i for i, line in enumerate(lines) 
                    if re.match(rf'^\s*##\s*{re.escape(section_title)}', line)]
    
    # 找期望的前置章节
    prev_lines = [i for i, line in enumerate(lines)
                  if re.match(rf'^\s*##\s*{re.escape(expected_after)}', line)]
    
    if not target_lines or not prev_lines:
        print("❌ 章节未找到")
        return False
    
    target_idx = target_lines[0]
    prev_idx = prev_lines[-1]  # 取最后一个匹配（最新的章节）
    
    if target_idx > prev_idx:
        print(f"✅ 位置正确: 第{prev_idx+1}节之后 → 第{target_idx+1}节")
        return True
    else:
        print(f"❌ 位置错误: 应在第{prev_idx+1}节之后，实际在第{target_idx+1}节")
        return False

错误模式2.2：内容覆盖

属性 内容
错误特征 原有内容被覆盖，文件行数未增长
根因 文件已有同名章节，写入模式为替换而非追加
诊断命令 Get-Content 文件.md).Count（行数对比）
解决方案 grep先检查是否存在；增强前备份文件

覆盖检测：

# 增强前行数
$before = (Get-Content 文件.md).Count

# 增强后行数
$after = (Get-Content 文件.md).Count

# 若$after <= $before → 覆盖风险
if ($after -le $before) {
    Write-Host "⚠️ 行数未增长，覆盖风险"
}

错误模式2.3：格式破坏

属性 内容
错误特征 文件插入后内容乱码或格式错乱
根因 BOM/编码问题/CRLF vs LF换行符差异
诊断命令 Get-Content 文件.md -Encoding Byte -TotalCount 3
解决方案 使用 qclaw-text-file skill 处理写入

BOM检测：

# EF BB BF = UTF-8 with BOM
$bytes = Get-Content 文件.md -Encoding Byte -TotalCount 3
if ($bytes[0] -eq 0xEF -and $bytes[1] -eq 0xBB -and $bytes[2] -eq 0xBF) {
    Write-Host "BOM: UTF-8 with BOM"
} else {
    Write-Host "BOM: UTF-8 without BOM"
}

3. 并行执行错误模式

错误模式3.1：Gateway过载

属性 内容
错误特征 多个子代理同时失败（同一批次内）
根因 并发数>5，Gateway处理能力超限
诊断命令 sessions_list activeMinutes=5
解决方案 单批次并行度≤3；超出拆分为多个批次

过载诊断：

# 当前活跃session数
openclaw sessions list
# 若>5个 → 存在过载风险

错误模式3.2：Session冲突

属性 内容
错误特征 子代理间session key混乱，结果写入错误文件
根因 并行任务session管理不当
诊断命令 sessions_list messageLimit=1
解决方案 每个子代理使用独立sessionKey，互不干扰

Session健康检查：

# 检查是否有异常session
openclaw sessions list --active
# 确认每个session对应正确的任务

错误模式3.3：批次依赖缺失

属性 内容
错误特征 P1在P0验证完成前启动，P2在P1完成前启动
根因 批次间依赖管理缺失
诊断命令 grep "增强来源：" 文件.md（逐批次验证）
解决方案 批次间设串行门控：前置批次验证→下一批次启动

依赖检查流程：

P0批次启动前 → 检查前置条件
P0完成后 → grep验证 → 启动P1
P1完成后 → grep验证 → 启动P2

4. 知识库特定错误模式

错误模式4.1：公式无渲染

属性 内容
错误特征 LaTeX公式在markdown中无法正确渲染
根因 公式内含中文（如$净利润$）或特殊字符
诊断命令 Select-String '\$[^$]*[\u4e00-\u9fff]' 文件.md
解决方案 全部改为英文变量名

公式修复对照表：

错误写法 正确写法
$净利润$ $NetIncome$
$毛利率$ $GrossMargin$
$净资产收益率$ $ROE$
$总资产周转率$ $AssetTurnover$

错误模式4.2：增强来源缺失

属性 内容
错误特征 增强章节无专家来源标注
根因 子代理未按模板添加来源标注
诊断命令 Select-String "增强来源：" 文件.md
解决方案 建立统一模板：*{来源专家（机构）}*{主题}*{年份}*

错误模式4.3：触发词缺失

属性 内容
错误特征 知识文件无触发词，无法被agent识别
根因 新建文件时未添加触发词章节
诊断命令 Select-String "触发词" 文件.md
解决方案 每文件需含≥3个触发词

5. 错误诊断命令速查

错误类型 诊断命令 期望结果
章节是否存在 Select-String "^## X\.Y " 文件.md 返回行号
行数增长 (Get-Content 文件.md).Count 增长>50行
增强来源 Select-String "增强来源：" 文件.md 返回来源行
BOM编码 Get-Content 文件.md -Encoding Byte -TotalCount 3 EF BB BF
公式错误 Select-String '\$[^$]*[\u4e00-\u9fff]' 文件.md 无返回
活跃session sessions_list activeMinutes=5 <5个
超时诊断 sessions_history <key> limit=5 查看实际输出

6. 错误恢复决策树

6.1 子代理超时恢复决策树

子代理超时通知
    │
    ├─→ 检查sessions_history输出
    │       │
    │       ├─→ 有输出且含"增强完成" → grep验证 → ✅完成
    │       │
    │       ├─→ 有输出但不含"增强完成" → 检查文件是否变更
    │       │       │
    │       │       ├─→ 文件已变更 → grep验证 → ✅完成
    │       │       │
    │       │       └─→ 文件未变更 → 补做任务
    │       │
    │       └─→ 无输出 → 主会话备选
    │
    └─→ 主会话备选直接输出增强内容

6.2 增强验证失败决策树

增强验证失败
    │
    ├─→ grep章节标题 → 无返回 → 插入位置错误
    │       │
    │       └─→ 确认正确插入位置 → 重新插入
    │
    ├─→ grep章节标题 → 有返回 → 检查行数
    │       │
    │       ├─→ 行数未增长 → 内容覆盖/插入失败
    │       │       │
    │       │       └─→ git还原 → 重新插入
    │       │
    │       └─→ 行数正常增长 → ✅完成
    │
    └─→ 检查增强来源 → 无返回 → 来源补标注

7. 错误日志模板

每次错误发生时，按以下格式记录：

## 错误日志

### YYYY-MM-DD HH:MM
- **错误类型**：子代理超时/位置错误/内容覆盖/格式破坏
- **涉及文件**：文件路径
- **现象描述**：
- **根因分析**：
- **解决方案**：
- **教训**：
- **预防措施**：

8. 附录：错误模式索引

错误模式 页码 优先级
调研超时 §1.1 P0
写入超时 §1.2 P0
验证超时 §1.3 P1
位置错误 §2.1 P0
内容覆盖 §2.2 P1
格式破坏 §2.3 P0
Gateway过载 §3.1 P0
Session冲突 §3.2 P1
批次依赖缺失 §3.3 P0
公式无渲染 §4.1 P1
增强来源缺失 §4.2 P2
触发词缺失 §4.3 P2