案例质量检查器
功能概述
本工具用于检查故障案例文件是否符合标准模板格式，验证必填字段完整性，确保入库案例质量统一。
检查项
- 必填字段检查 - 验证是否包含所有必填字段
- 字段内容检查 - 检查字段内容是否过短或为空
- 文件格式检查 - 验证文件类型和编码
- 格式错误检测 - 识别常见的格式问题
标准模板格式
标题 案例标题
内核版本 内核版本号（如：22.03 SP4）
问题现象 问题描述...
问题根因 根因分析...
解决方案 解决措施...
必填字段
| 字段 | 说明 | 别名 | | #标题 | 案例标题 | # 标题、标题 | | #内核版本 | 内核版本号 | # 内核版本、内核版本 | | #问题现象 | 问题描述 | # 问题现象、问题现象 | | #问题根因 | 根因分析 | # 问题根因、问题根因、#根因、# 根因 | | #解决方案 | 解决措施 | # 解决方案、解决方案、#解决措施、# 解决措施 |
触发场景
- 新增案例入库前质量检查
- 定期审核案例库质量
- 批量导入案例前的格式验证
- 发现并修复格式不规范的案例
执行方式
在 case-quality-checker 目录下运行：
# 基本用法 - 检查指定目录
python scripts/main.py <案例目录路径>
# 示例：检查 community_maintenance 目录
python scripts/main.py ../../community_maintenance
# 生成详细报告并保存到文件
python scripts/main.py ../../community_maintenance -o report.md -v
# 不递归扫描子目录
python scripts/main.py ../../community_maintenance --no-recursive
# 只显示简要信息
python scripts/main.py ../../community_maintenance -v
命令行参数
| 参数 | 说明 | 默认值 |
| input_dir | 案例文件所在目录路径（必填） | - |
| -o, --output | 输出报告文件路径（可选，支持 .md 格式） | 不保存 |
| -v, --verbose | 显示详细错误信息 | 不显示 |
| -r, --recursive | 递归扫描子目录 | 开启 |
| --no-recursive | 不递归扫描子目录 | - |
输出格式
控制台输出
======================================================================
案例质量检查报告
====================================================================== 总案例数: 332 有效案例: 328 (98.8%) 无效案例: 4
缺失字段统计: #内核版本: 2 个案例 #解决方案: 1 个案例
内容过短字段: #问题根因: 3 个案例
======================================================================
详细模式输出（-v）
无效案例详情:
文件: 缺少字段案例.txt 缺失字段: #内核版本, #解决方案
文件: 内容过短案例.txt 内容过短: #问题根因
Markdown 报告文件
使用 -o 参数保存报告时，生成 Markdown 格式的详细报告，包含：
统计摘要
缺失字段统计表
内容过短字段统计表
无效案例详情（包含文件路径、错误信息）
依赖
本工具仅使用 Python 标准库，无需额外安装依赖。
使用示例
示例 1：快速检查
python scripts/main.py ../../community_maintenance
输出简要统计信息，快速了解案例库质量。
示例 2：生成详细报告
python scripts/main.py ../../community_maintenance -o quality_report.md -v
生成详细的 Markdown 报告文件，包含所有无效案例的详细信息。
示例 3：检查特定目录
python scripts/main.py ./new_cases -o new_cases_report.md
检查新增案例目录，生成质量报告。
常见问题
Q: 如何修复检查出的问题？
A: 根据报告中的错误信息，手动编辑案例文件： 缺失字段：添加对应的字段标记和内容 内容过短：补充完整的问题描述、根因或解决方案 格式错误：按照标准模板格式调整
Q: 工具会修改案例文件吗？
A: 不会。工具只进行检查和报告生成，不会修改任何案例文件。
Q: 支持哪些文件格式？
A: 支持 .txt 和 .md 格式的案例文件。
Q: 如何自定义必填字段？
A: 修改 scripts/main.py 中的 required_fields 字典，添加或修改字段配置。
质量标准
有效案例标准
- 包含所有必填字段（#标题、#内核版本、#问题现象、#问题根因、#解决方案）
- 每个字段内容不少于 5 个字符
- 文件编码为 UTF-8
- 文件类型为 .txt 或 .md
质量评级
| 有效率 | 评级 | 说明 | | 95% - 100% | 优秀 | 案例库质量很高 | | 90% - 95% | 良好 | 案例库质量较好 | | 80% - 90% | 一般 | 存在部分格式问题 | | < 80% | 较差 | 需要大规模整改 |
集成建议
CI/CD 集成
将质量检查器集成到 CI/CD 流程中，在案例提交前自动检查：
# 在 CI 脚本中添加
python scripts/case-quality-checker/scripts/main.py ./cases
if [ $? -ne 0 ]; then
echo "案例质量检查失败，请修复格式问题"
exit 1
fi
定期检查
建议每周或每月定期运行质量检查，跟踪案例库质量变化趋势。