质量智能审计技能 — 文档与项目质量审计

概述

三种审计模式，每种模式均支持三种检查单来源配置：

模式一：单文档检查          模式二：多文档检查          模式三：项目活动+文档联合检查

├─ 1A: 单文件单sheet        ├─ 2A: 单文件单sheet         ├─ 3A: 单文件单sheet
├─ 1B: 单文件多sheet(选)    ├─ 2B: 单文件多sheet(名匹配) ├─ 3B: 单文件多sheet(名匹配)
└─ 1C: 多文件(选)           └─ 2C: 多文件(名匹配)        └─ 3C: 多文件(名匹配)

检查重点: 文档内容质量       检查重点: 文档内容质量         检查重点: 文件存在性 + 文档内容质量

支持的文档类型： Word（.docx/.doc）、PDF（.pdf）、纯文本（.txt/.md/.markdown）、Excel（.xlsx/.xlsm/.xls），CSV（.csv）按文本解析。旧格式 .doc/.xls 在环境支持时通过 LibreOffice（soffice）转换，并自动回退到 antiword/xlrd；.xlsm 由 openpyxl 直接读取。

检查单格式： Excel 文件，列结构灵活。解析器自动识别关键列。

检查单检查项类型（check_type）：
- 文档内容 — 检查文档内容是否满足要求（模式一/二/三通用）
- 文件存在性 — 检查项目目录中是否存在指定文件（仅模式三）
- 文档完整性 — 检查文档章节是否完整（所有模式通用）

快速开始

1. 安装依赖：

pip install -r requirements.txt

2. 把检查单解析为 JSON：

python3 scripts/parse_checklist.py <检查单.xlsx> --sheet <sheet名称> -o /tmp/checklist.json

3. 生成完整的覆盖度模板（批量或活动审计用）：

python3 scripts/scan_files.py <目录路径> --checklist /tmp/checklist.json --output-template -o /tmp/scan_template.json

4. 在模板中填写每个文件的 files[].findings，无问题时留 []。
5. 生成 Excel 报告：

python3 scripts/generate_report.py -i /tmp/scan_template.json -o <报告.xlsx>

覆盖度要求（模式二与模式三强制）

关键：对于批量审计（模式二/三），目录扫描发现的每一个文件都必须出现在 findings JSON 中。为确保这一点：

1. 始终使用 scan_files.py --output-template 生成列出全部文件的空白 findings 模板。
2. 为模板中每个文件填写 findings —— 即使文件全部通过，也以空 findings: [] 纳入。
3. generate_report.py 会校验覆盖度，并在概览页以红/绿显示通过与否。

违规：若报告显示"[警告] 仅覆盖 X/N 个文件"，说明审计不完整，必须重做。

环境配置

必需的 Python 包（纯 Python，跨平台）：

pip install -r requirements.txt

核心依赖（python-docx、pymupdf、openpyxl、xlsxwriter）均为跨平台预编译包，覆盖主要文档类型：.docx、.pdf、.xlsx/.xlsm、.txt/.md/.csv。完成这一步后，技能对上述格式即完全可用。

可选外部工具（仅旧格式 .xls/.doc 需要）：
这些工具缺失时，技能会优雅降级——绝不崩溃，仅报告旧格式文件无法解析并继续审计。
- LibreOffice（soffice / libreoffice）：.xls→.xlsx、.doc→.docx 转换的最佳路径，保留表格与结构。运行时自动探测（在 macOS 上也会探测标准安装路径）。
- antiword：Linux/macOS 上轻量的 .doc 纯文本回退方案。
- xlrd==1.2.0（已在 requirements.txt 中锁定版本）：LibreOffice 不可用时读取 .xls 的回退方案。切勿升级到 xlrd>=2.0——该版本已移除 .xls 支持。

若 LibreOffice 与回退方案均不可用，旧格式 .xls/.doc 文件会被跳过（并如实报告），而 .docx/.pdf/.xlsx/.xlsm/.txt 的审计照常进行。

脚本运行方式： 所有脚本位于 scripts/ 目录，使用 python3 scripts/<脚本名>.py 调用。中间 JSON 可能写入系统临时目录（Linux/macOS 为 /tmp，Windows 为 %TEMP%），最终报告写入调用方工作目录。

Python 版本： 已在 CPython 3.9–3.13 上测试。xlrd 回退方案需使用 xlrd 1.2.0 支持的 Python 版本。

模式一：单文档对照检查单检查

> 场景： 给定一份文档 + 一份检查单，审计文档内容质量。适合单份文档的深度质量审查。

1A — 单文件单sheet

检查单是 Excel 文件中的某一个 sheet。

工作流：

1. 解析文档：

python3 scripts/parse_document.py <文档路径> -o /tmp/doc.json

2. 解析检查单 sheet：

python3 scripts/parse_checklist.py <检查单.xlsx> --sheet <sheet名称> -o /tmp/checklist.json
# 如果不确定sheet名，先列出：
python3 scripts/parse_checklist.py <检查单.xlsx> --list-sheets

3. 读取两份 JSON 输出。对每条检查项，审查文档内容并判定符合性，记录不符合项。

4. 汇总发现项 → JSON（见"发现项 JSON 格式"一节）。

5. 生成报告：

python3 scripts/generate_report.py -i /tmp/findings.json -o <报告.xlsx>

1B — 单文件多sheet

检查单是一个 Excel 文件，包含多个 sheet。由用户手动选择适用的 sheet。

工作流同 1A，但步骤 2 改为：先 --list-sheets 列出所有 sheet，由用户选择后再用 --sheet 指定。

1C — 多文件

多个独立的检查单 Excel 文件。由用户手动选择适用的文件。

工作流同 1A，但步骤 2 使用对应的 Excel 文件路径。

模式二：多文档对照检查单检查

> 场景： 给定一个目录（含多个文档）+ 检查单来源，对所有文档批量审计。适合多份同类型文档的批量审查。

2A — 单文件单sheet（所有文档共用）

所有文档使用同一个 sheet 作为检查标准。

工作流：

1. 生成覆盖度模板（列出全部文件）：

python3 scripts/scan_files.py <目录路径> --checklist <检查单.xlsx> --sheet <sheet名称> --output-template -o /tmp/scan_template.json

2. 阅读模板。核对 _coverage_stats.total_files —— 这是你必须覆盖的文件总数。

3. 解析检查单：

python3 scripts/parse_checklist.py <检查单.xlsx> --sheet <sheet名称> -o /tmp/checklist.json

4. 对模板中的每一个文件，解析并执行审计：

python3 scripts/parse_document.py <文件路径> -o /tmp/doc.json
# 读取解析内容，对照检查项执行审计
# 在该文件的 "findings" 数组中填写发现项

5. 从 JSON 中移除 _template_note、_coverage_rule、_coverage_stats，另存为 findings。

6. 生成报告：

python3 scripts/generate_report.py -i /tmp/findings.json -o <报告.xlsx>

2B — 单文件多sheet（按文件名匹配）

工作流：

1. 生成自动匹配 sheet 的模板：

python3 scripts/scan_files.py <目录路径> --checklist <检查单.xlsx> --output-template -o /tmp/scan_template.json

每个文件自动携带 matched_sheet 字段。

2. 解析所有检查单 sheet：

python3 scripts/parse_checklist.py <检查单.xlsx> -o /tmp/checklist.json

3. 对模板中的每一个文件：解析 → 用匹配 sheet 审计 → 填写 findings。

4. 未匹配文件（无 matched_sheet）：在审计摘要中记为"未匹配文件"，不要使用 missing_files（该字段专用于模式三的文件存在性缺失）。

5. 移除元数据键，生成报告。

2C — 多文件（按文件名匹配检查单文件）

一个目录包含多个检查单 Excel 文件，每个文档文件按文件名匹配对应的检查单文件。

工作流：

1. 加载全部检查单：

python3 scripts/parse_checklist.py --checklist-dir <检查单目录> -o /tmp/all_checklists.json

2. 生成覆盖度模板（列出全部文件）：

python3 scripts/scan_files.py <目录路径> --output-template -o /tmp/scan_template.json

3. 核对 _coverage_stats.total_files。在 AI 层面执行文件名匹配：文档文件名 ↔ 检查单文件名。对每对匹配：解析文档 → 审计 → 填入 findings。

4. 移除元数据键，生成报告。

模式三：项目执行活动与文档的联合检查

> 场景： 给定一个项目根目录（顶层子目录=项目），检查单中包含两类检查项——文件存在性（某文档是否在项目目录中存在）和 文档内容（文档内容是否符合要求）。适合对项目执行过程的完整审计。

与模式一/二的核心区别：
- 不仅检查文档内容，还检查文件是否存在于项目目录中
- 两阶段审计流程：先验证文件存在性，再审计文档内容

检查单中检查类型的自动识别

检查单解析器自动识别"检查类型"列（中英文表头均可，如"检查类型"或"Check Type"），并识别该列的值，关键词包括：
- 文件存在性（File Existence）："文件存在性", "文件检查", "存在性", "交付物检查", "产物检查", "File Existence", "Existence", "Deliverable", "Artifact", "Presence", "Missing File"
- 文档内容（Document Content）："文档内容", "内容检查", "内容质量", "Document Content", "Content", "Content Quality"
- 文档完整性（Document Completeness）："文档完整性", "完整性", "结构完整性", "Completeness", "Structural Completeness", "Section Completeness"

无论检查单是中文还是英文，解析器都会把检查类型值统一映射为内部标准类型（文件存在性 / 文档内容 / 文档完整性），因此下游的扫描与报告生成对两种语言都开箱即用。

如果检查单没有"检查类型"列，则所有检查项默认为 文档内容 类型。

⚠️ 重要：如果检查单没有"检查类型"列，scan_files.py --mode activity 将无法自动识别文件存在性检查项（因为需要 check_type=="文件存在性"）。在这种情况下，你必须在 AI 审计时手动识别所有文件存在性检查项（在 check_item 或 category 中寻找"存在"、"交付"、"提交"等关键词），并手动验证这些文件是否存在于项目目录中。

3A — 单文件单sheet

工作流：

1. 首先把检查单解析为 JSON：

python3 scripts/parse_checklist.py <检查单.xlsx> --sheet <sheet名称> -o /tmp/checklist.json

2. 生成带文件存在性自动检查的覆盖度模板：

python3 scripts/scan_files.py <项目根目录> --mode activity --checklist /tmp/checklist.json --output-template -o /tmp/scan_template.json

模板中已包含：
- 所有文件列表（来自目录扫描）
- 预填充的"文件存在性"类发现项（标记为缺失的文件）
- _coverage_stats 显示应覆盖的文件总数

3. 核对 _coverage_stats.total_files → 这是你必须覆盖的文件数量。

4. 阶段一 — 模板中已经预填充了文件存在性检查结果，无需额外处理。

5. 阶段二 —— 对模板中的每一个文件：

python3 scripts/parse_document.py <文件路径> -o /tmp/doc.json
# 读取解析内容，对照检查单中的文档内容项进行审计
# 将发现项填入该文件的 "findings" 数组
# 注意：即使文件没有不符合项，也要保留该条目（findings: []）

6. 移除元数据键（_template_note、_coverage_rule、_coverage_stats），另存为 /tmp/findings.json。

7. 生成报告：

python3 scripts/generate_report.py -i /tmp/findings.json -o <报告.xlsx>

验证报告概览中的"覆盖度校验"行显示"[通过] 全部 N 个文件已覆盖"

3B — 单文件多sheet（按文件名匹配）

一个 Excel 包含多个 sheet，每个项目或文件按名称匹配对应 sheet。

工作流：

1. 解析所有 sheet 来源检查单：

python3 scripts/parse_checklist.py <检查单.xlsx> -o /tmp/checklist.json

2. 生成活动模式模板：

python3 scripts/scan_files.py <项目根目录> --mode activity --checklist /tmp/checklist.json --output-template -o /tmp/scan_template.json

3. 对每个项目：从检查单中匹配对应的 sheet（项目名→sheet 名），按 sheet 中的检查项执行两阶段审计。

3C — 多文件（按文件名匹配检查单文件）

多个检查单文件，每个项目按文件名匹配对应的检查单文件。

工作流：

1. 加载全部检查单：

python3 scripts/parse_checklist.py --checklist-dir <检查单目录> -o /tmp/all_checklists.json

2. 生成活动模式模板：

python3 scripts/scan_files.py <项目根目录> --mode activity --checklist /tmp/all_checklists.json --output-template -o /tmp/scan_template.json

3. 对每个项目，按项目名匹配检查单文件 → 执行两阶段审计。

脚本参考

parse_document.py

python3 scripts/parse_document.py FILE_PATH [--output OUTPUT_PATH]

将文档解析为带章节/标题信息的结构化 JSON。

输出：

{
  "file_type": "docx|pdf|txt|xlsx",
  "file_ext": ".docx",
  "file_name": "filename",
  "file_path": "/absolute/path",
  "sections": [...],
  "tables": [...],
  "full_text": "concatenated full text",
  "truncated": false
}

• file_ext：原始文件扩展名

• truncated：文本文件超过 20MB 被截断时为 true

• PDF 章节：含 "page" 字段（页码）

• 文本/TXT 文件：含 "start_line" 字段（行号）
• Markdown 文件：标题从 # 标记解析
• Excel 文件：每个 sheet → 一个含 "sheet_name"、"headers"、"rows" 的"section"
• CSV 文件：按文本解析

parse_checklist.py

python3 scripts/parse_checklist.py EXCEL_FILE [--sheet SHEET] [--match FILE_NAME] [--list-sheets]
python3 scripts/parse_checklist.py --checklist-dir DIR_PATH         # 多文件模式

说明：--sheet 与 --match 互斥 —— 用 --sheet 选择指定 sheet，或用 --match 按文件名自动匹配 sheet 名。

自动识别的列（中英文均可，不区分大小写）：
| 角色 | 关键词（中/英） |
|------|--------|
| 编号 | 编号, 序号, id, no., item id, number |
| 检查项 | 检查项, 检查内容, 审计项, 审查项, check item, activity, requirement, item |
| 判定标准 | 判定标准, 检查标准, 依据, 要求, criteria, standard, requirement, basis |
| 分类 | 分类, 类别, 类型, category, type, group, class |
| 严重等级 | 严重等级, 风险等级, severity, priority, level |
| 检查类型 | 检查类型, 审计类型, check type, audit type, review type, check_type |

ASCII 关键词按单词边界匹配（因此 "no" 不会误匹配 "notes"，"id" 不会误匹配 "guide"）。英文检查单因此无需额外配置即可识别。

识别的检查类型值：
- 文件存在性：文件存在性, 文件检查, 存在性, 交付物检查, 产物检查
- 文档内容：文档内容, 内容检查, 内容质量
- 文档完整性：文档完整性, 完整性, 结构完整性

若没有检查类型列或值无法识别 → 默认 文档内容。

scan_files.py

# 标准文档扫描（模式一/二）：
python3 scripts/scan_files.py DIR [--checklist EXCEL] [--sheet SHEET] [--output PATH]

# 活动审计扫描（模式三）：
python3 scripts/scan_files.py DIR --mode activity --checklist CHECKLIST_JSON [--output PATH]

# 生成覆盖度模板（模式二/三推荐）：
python3 scripts/scan_files.py DIR --output-template [--checklist ...] [--mode ...] [--output PATH]

--output-template 参数：启用后，输出一个列出扫描到的每一个文件的空白 findings JSON 模板。这强制了全覆盖 —— 审计者无法意外跳过文件。模板包含：
- _coverage_stats.total_files：必须覆盖的文件数量
- 预填充的空 findings: [] 文件条目
- 活动模式下：为文件存在性缺失预填充的 missing_files 条目
- 活动模式下：未匹配的文件存在性检查项归入特殊项目 (未匹配文件存在性检查项)

generate_report.py

python3 scripts/generate_report.py -i FINDINGS_JSON -o REPORT_XLSX

报告工作表（共 5 个）：
1. 审计概览 — 项目数、文件数、不符合项数、覆盖度校验（通过/警告）、严重等级分布
2. 审计明细 — 文件、检查类型、不符合项位置、描述、检查项、分类、严重等级
3. 按项目统计 — 各项目不符合项数量、文件缺失/文档内容分解
4. 按分类统计 — 跨项目合并分类统计（降序排列）
5. 柱状图分析 — 按分类降序 + 按项目降序两个柱状图

审计方法

第一步：理解检查项

阅读检查项的内容、判定标准与检查类型：

• 文件存在性：检查项目目录下是否存在指定文件。关键词：交付物、产物、文档名称。
• 文档内容：检查文档内容是否满足要求。遵循标准文档审计流程（第二至四步）。
• 文档完整性：检查文档结构是否完整。混合了存在性和内容检查。

第二步：针对"文档内容"类型 —— 检索文档

通读解析后的文档章节。策略：

• 存在性检查：文档是否包含要求的章节/内容？在 section 标题与内容中搜索检查单中的关键词。
• 内容检查：文档是否包含必要的信息？搜索特定术语、列表、表格或模式。
• 格式检查：文档是否符合格式规范？检查结构、编号、标题层级。
• 质量检查：是否存在质量问题？搜索 TODO、FIXME、占位符、空白章节等。

第三步：针对"文件存在性"类型 —— 检查目录

• 从检查单中提取文件名关键词（如"项目管理计划" → 搜索 *项目管理计划*.docx、*项目管理计划*.pdf 等）。
• 在项目目录中搜索匹配文件（支持模糊匹配）。
• 如果文件存在：符合（在模式三中接着做内容审计）。
• 如果文件不存在：记录为不符合项（location="缺失"，severity 默认="高"）。

第四步：记录不符合项

对每条不符合项，记录：
- check_type：文件存在性 | 文档内容 | 文档完整性
- check_item_id：检查项编号
- check_item：检查项内容文本
- criteria：判定标准
- category：检查类别
- severity：严重等级
- location：不符合项位置（章节级定位）
- description：具体的不符合描述
- file_section：相关文档章节

定位精度

章节级定位，示例：
- "第3章 3.2节"
- "2.1 架构设计"
- "缺失" — 文件或章节完全缺失
- "Sheet: 数据表" — Excel 文件
- "全文" — 问题贯穿整个文档

发现项 JSON 格式

{
  "_coverage_stats": {"total_files": 10, "total_projects": 1},
  "audit_type": "single_document|multi_document|project_activity",
  "audit_date": "2026-07-25",
  "auditor": "审计人",
  "projects": [
    {
      "project_name": "项目A",
      "files": [
        {
          "file_name": "技术方案.docx",
          "file_path": "/path/to/file.docx",
          "checklist_sheet": "技术方案",
          "checklist_file": "checklist.xlsx",
          "findings": [
            {
              "check_type": "文档内容",
              "check_item_id": "T001",
              "check_item": "文档必须包含项目概述章节",
              "criteria": "检查是否存在项目概述章节",
              "category": "结构完整性",
              "severity": "高",
              "location": "全文",
              "description": "文档缺少项目概述章节，直接从技术方案开始",
              "file_section": "1. 概述"
            }
          ]
        }
      ],
      "missing_files": [
        {
          "check_type": "文件存在性",
          "check_item_id": "A002",
          "check_item": "项目目录必须包含验收报告.docx",
          "criteria": "检查项目目录下是否存在验收报告.docx",
          "category": "交付物完整性",
          "severity": "高",
          "location": "缺失",
          "description": "项目目录中未找到文件：验收报告.docx"
        }
      ]
    }
  ]
}

字段说明：
- _coverage_stats — 可选但推荐。生成报告时会自动校验覆盖度。
- files[].findings — 与具体文件关联的不符合项
- projects[].missing_files — 文件完全缺失的不符合项（无法关联到任何已存在的文件）

重要说明

1. 覆盖度强制（模式二/三）：批量审计务必使用 --output-template。模板列出全部文件。填写 findings 后，确认报告覆盖度校验行显示"通过"。切勿跳过文件。

2. 文件路径处理：中间 JSON 保存到 /tmp/（或系统临时目录），最终报告保存到用户工作目录。

3. 大型目录：批量审计时逐个文件处理。解析 → 审计 → 累积 findings。不要同时加载所有已解析文档。

4. 未匹配文件/检查单：将未匹配项记入审计摘要，但不导致审计失败。

5. 模式三文件存在性匹配：使用模糊文件名匹配 —— 检查单写的是"项目管理计划"，而实际文件可能是"XX项目_项目管理计划_v2.docx"。

6. 检查类型默认值：若检查单没有"检查类型"列，所有项默认为"文档内容"类型。模式三仍可用，但 AI 需从上下文中判断哪些项是关于文件存在性的。

7. 报告颜色标记：高=红，中=黄，低=绿。文件存在性类不符合项固定为高严重等级（红色标记）。

8. 多项目结构：根目录下的顶层子目录 = 独立项目。根目录本身的文件视为单一项目（使用根目录名）。