质量检验记录知识库构建 Skill

Overview

将建设工程质量检验记录的原始资料（Word、Excel、PDF 文件）自动提取、分类、结构化，填入 knowledge_base.xlsx 知识库表格。覆盖三类检查记录：监理质量联检、每月质监站检查、三标建委检查。

核心策略：脚本做机械工作（文件转换、文本提取、Excel 读写），AI 做智能工作（问题分类、关键词提取、严重等级判定、原因分析推理、解决方案生成）。

核心质量要求（基于2026-04-26优化）：

• 所有13列必须100%填充，不允许留空
• solution 必须是具体操作步骤，禁止仅写"整改时限: X天"
• cause 必须基于专业常识推断根因
• severity 分布目标：高~40%、中~51%、低~9%

工作流程

步骤1: OLE2 .doc → .docx 转换（convert_doc_to_docx.py）
步骤2: 文档文本提取与结构化解析（extract_document.py）
步骤3: 检查问题-整改回复配对（pair_documents.py）
步骤4: AI 智能分类与字段填充（AI 层，本 SKILL.md 指引）
步骤5: 数据清洗与质量校验（clean_data.py + enrich_data.py）
步骤6: 写入 knowledge_base.xlsx（write_kb.py）

步骤 1: OLE2 .doc 批量转换

执行条件

当原始目录中存在 OLE2 格式 .doc 文件时执行。检测方法：文件头前 4 字节为 d0cf11e0。

执行命令

python scripts/convert_doc_to_docx.py "<source_dir>" --json

• source_dir：质量检验记录根目录（含三个子目录的上级）
• 转换结果保存到 /.workbuddy/temp/converted_docx/
• 增量处理：已转换的文件自动跳过
• --dry-run：仅检测不转换
• --method wordcom|libreoffice|auto：选择转换方法，默认 auto

步骤 2: 文档文本提取

执行命令

# 单文件提取
python scripts/extract_document.py "<file_path>" --output result.json

# 批量提取
python scripts/extract_document.py --batch "<source_dir>" --output-dir "<output_dir>"

三类文档的解析策略

质量联检记录（ZL-XXX）：纯表格结构，含编号/问题说明/整改时限

监理回复文档：表格结构，含序号/问题描述/整改措施

质监站/建委检查问题：段落文本，按编号拆分问题

质监站/建委整改回复：段落文本，针对各问题的整改措施

输出格式

每个文档提取为 JSON（详见 references/field_mapping.md）。

步骤 3: 检查问题-整改回复配对

python scripts/pair_documents.py "<source_dir>" --output pairs.json

步骤 4: AI 智能分类与字段填充

此步骤由 AI 执行。必须严格遵循 references/field_mapping.md 中的所有规则。

4.1 读取参考文件

1. references/field_mapping.md：字段映射规则、子类→标准字段映射表、严重等级校准规则、解决方案撰写规范（最重要）
2. references/category_taxonomy.md：问题分类体系（4大类75+子类）

4.2 核心填充规则（CRITICAL）

六个"不允许为空"的字段

以下字段必须100%填充，不得留空或写"待补充"：

| 字段 | 填充策略 |

|------|---------|

| cause（原因分析） | 基于 field_mapping.md 中的 CAUSE_TEMPLATES 按子类匹配，或基于问题描述推断根因 |

| solution（解决方案） | 从整改回复提取具体措施；无回复时按子类模板生成具体操作步骤 |

| applicable_condition（适用条件） | 从子类映射表获取简洁短语（4-15字），禁止复制整段检查内容 |

| estimated_time（预计耗时） | 从子类映射表获取标准耗时，格式如"2-4小时""1-3天" |

| required_resources（所需资源） | 从子类映射表获取所需设备/材料，格式如"焊机,角磨机,焊缝量规" |

| reference_spec（规范依据） | 从子类映射表获取规范条文号，格式如"GB 50205-2020 第5.2.1条" |

solution 撰写规范

• ❌ 禁止：仅写"整改时限: 1天""已整改""整改完毕"
• ✅ 必须：具体操作步骤 + 规范依据
• 示例："按GB 50755-2012第6.3.2条要求，对焊条进行300～350℃烘焙1～2h，烘焙后放入保温筒随用随取"

severity 校准规则

默认等级策略：

• 焊接核心（焊缝缺陷/焊材/焊工资质/螺栓终拧）→ 高
• 混凝土/钢筋/结构施工 → 高
• 构件加工/网架结构 → 高
• 管道/机电/资料管理 → 中
• 成品保护/标识/苫盖/文明施工 → 低
• 目标分布：高~40%，中~51%，低~9%

数据清洗规则

处理提取结果时必须：

1. 删除"整改进度"子类条目（非质量问题）
2. 删除重复表头行
3. "管理"大类归入"缺陷"类
4. "整改时限: X天"从 solution 移入 estimated_time，solution 需重新填充

4.3 批量处理建议

• 每次处理 10-20 条问题后暂存为 JSON
• 分批处理避免丢失进度
• 处理完成后运行 enrich_data.py 自动补全空字段和校准 severity

4.4 输出格式

每条知识条目 JSON：

{
    "kb_id": "CASE-ZL-001-01",
    "main_category": "缺陷",
    "sub_category": "焊缝表面缺陷",
    "phenomenon": "钢结构柱脚焊缝表面存在咬边和气孔缺陷，焊缝成型不良",
    "cause": "焊接操作不当，电流/电压参数设置不合理；焊工操作不规范",
    "solution": "对缺陷焊缝表面进行打磨修补，调整焊接参数后重新施焊",
    "applicable_condition": "焊接工程",
    "keywords": "焊缝,咬边,气孔,焊接",
    "severity": "高",
    "estimated_time": "4-8小时",
    "required_resources": "焊机,角磨机,焊缝量规",
    "reference_spec": "GB 50205-2020 第5.2.5条；GB 50755-2012 第6.4节",
    "source_case": "实例-质量联检ZL-001"
}

步骤 5: 数据清洗与质量校验

执行命令

python scripts/clean_data.py <input_json> -o <clean_json>
python scripts/enrich_data.py <clean_json> -o <enriched_json>

clean_data.py 功能：

• 删除重复表头行和"整改进度"条目
• 修复"整改时限"格式的 solution
• 重分类"管理"大类
• 缩短过长的 applicable_condition

enrich_data.py 功能：

• 基于 SUB_CATEGORY_MAP 填充 estimated_time/required_resources/reference_spec
• 基于 CAUSE_TEMPLATES 填充 cause
• 基于 sol_templates 填充空缺的 solution
• 细分"待细分"子类
• 校准 severity 分布

步骤 6: 写入 knowledge_base.xlsx

执行命令

# 创建新文件
python scripts/write_kb.py --input entries.json --output knowledge_base.xlsx

# 追加到已有文件
python scripts/write_kb.py --input entries.json --append --target knowledge_base.xlsx

文件格式

• 单行英文表头（与 knowledge_base_final.xlsx 模板一致）
• 13列：kb_id, main_category, sub_category, phenomenon, cause, solution, applicable_condition, keywords, severity, estimated_time, required_resources, reference_spec, source_case
• 自动设置列宽、冻结首行、单元格边框

资源文件说明

scripts/

| 脚本 | 功能 |

|------|------|

| convert_doc_to_docx.py | OLE2 .doc → .docx 批量转换 |

| extract_document.py | 文档文本提取与结构化 |

| pair_documents.py | 检查问题-整改回复配对 |

| write_kb.py | 写入 knowledge_base.xlsx |

references/

| 文件 | 内容 |

|------|------|

| field_mapping.md | 核心参考：字段映射规则、子类→标准字段映射表（含50+子类）、严重等级校准规则、解决方案撰写规范、原因分析模板 |

| category_taxonomy.md | 问题分类体系（4大类75子类）+ 工程实例新增子类 |

快速开始示例

当用户说"帮我整理质量检验记录"时，按以下流程执行：

# 1. 检测并转换 OLE2 .doc 文件
python scripts/convert_doc_to_docx.py "c:/.../质量检验记录" --json

# 2. 批量提取文档内容
python scripts/extract_document.py --batch "c:/.../质量检验记录" --output-dir "c:/.../temp"

# 3. 配对检查-回复
python scripts/pair_documents.py "c:/.../质量检验记录" --output "c:/.../temp/pairs.json"

# 4. [AI 层] 读取 references/field_mapping.md 和 category_taxonomy.md
#    逐条分类填充所有13个字段（特别注意 cause/solution/estimated_time 等6个必填字段）

# 5. 数据清洗
python scripts/clean_data.py entries.json -o cleaned.json
python scripts/enrich_data.py cleaned.json -o enriched.json

# 6. 写入知识库
python scripts/write_kb.py --input enriched.json --output knowledge_base.xlsx

故障排除

| 问题 | 原因 | 解决方案 |

|------|------|---------|

| 知识条目验证警告 | 部分字段为空 | 运行 enrich_data.py 自动补全 |

| severity 分布偏差 | 判定规则不当 | 参考 field_mapping.md 校准规则 |

| solution 仅含"整改时限" | extract_document.py 误提取 | 整改时限应存入 estimated_time，solution 需重新填充 |

| applicable_condition 过长 | 复制了整段检查内容 | 应提炼为4-15字简洁短语 |

| 列名与模板不一致 | write_kb.py 使用旧版双行表头 | 使用更新后的 write_kb.py（单行英文表头） |