shield_lock
JinDaGe
← Back to skills
extension
Category: Data & AnalyticsNo API key required

体检指标趋势分析

多年度体检报告趋势分析：解析电子/扫描/照片三种报告形态，产出统一指标字典、异常与趋好趋坏判定、权威医学解读、Markdown 报告与离线 HTML 工作台。

personAuthor: user_65c8c185hubcommunity
downloadDownload package

体检指标趋势分析系统

用途

将多年度、多形态（电子 PDF / 扫描件 / 照片）的体检报告统一解析为标准化指标时间序列，产出趋势分析报告 + 交互式健康管理工作台。全本地处理、自动脱敏、动态扩展（新增报告重跑流水线即可）。

触发词

  • 历年体检报告 / 多年度体检报告 / 历年的体检报告 / 历年体检
  • 体检报告数据化 / 体检数据解析 / 体检报告解析
  • 体检指标趋势 / 指标趋势分析 / 指标趋势
  • 历年体检指标对比 / 体检指标对比 / 逐年对比 / 逐年变化
  • 化验单分析 / 化验单解读 / 检验报告分析
  • 体检报告扫描件 / 扫描件体检报告 / 扫描件 OCR
  • 体检报告照片 / 照片版体检报告 / 手机拍的体检报告
  • 健康管理工作台 / 健康管理看板 / 健康数据看板 / 可视化看板
  • 血糖趋势 / 血糖变化 / 尿酸偏高 / 血脂趋势 / 血压趋势
  • 体检异常指标 / 异常指标解读 / 指标异常
  • 新增体检报告 / 新报告接入 / 加入新一年体检
  • 体检数据脱敏 / 脱敏数据集 / 脱敏版 / 可分享数据集

环境准备

export REPORT_DIR=/path/to/体检报告目录      # 报告存放目录（含 PDF 或 年度文件夹+JPG）
export WORK_DIR=/path/to/工作数据目录        # 数据产物目录（自动建 data/ 与 output/）
export PY=/path/to/python                    # 建议用带依赖的 python 解释器

Step 0（每个新会话第一步，必做）：

$PY scripts/check_deps.py            # 一键体检：缺什么、影响哪几个脚本、怎么装
$PY scripts/check_deps.py --json     # 机器可读，供自动化消费

退出码 0 = 必需依赖齐全可开工；1 = 缺必需依赖（主流程走不通，按提示装）；可选依赖缺失只影响对应输入形态，不阻断电子版 PDF 主路径。

依赖

完整清单（含「影响哪个脚本 / 哪项能力 / 怎么装」）由 scripts/check_deps.py 提供，可直接跑它自查；此处只列包名。

  • pymupdf — 必需：解析 PDF 文本层与坐标（parse_reports.py → extract.py）。缺失则电子版主路径走不通。
  • Pillow — 可选：照片 JPG 合成 PDF 与图像解码。缺失只影响照片输入形态。
  • 以下三项依赖 macOS 原生框架（仅 macOS 可用），供 vision_ocr.py 做扫描件 / 照片识别；缺失只影响非电子版输入形态：Vision（OCR 识别）、Quartz（图像解码）、Foundation（桥接）。

安装与降级：pip install pymupdf（必需）、pip install Pillow（可选）；macOS OCR 三件套对应的安装命令由 scripts/check_deps.py 按当前环境打印（同一条命令即可补齐）。缺可选依赖时不必停手——电子版 PDF 路径照常可跑，只是对应输入形态不可用，脚本会明确提示缺哪个包、影响哪项能力。

执行流程

所有脚本均支持 --help，参数优先于环境变量；不带参数运行 = 沿用环境变量的原有行为。

  1. 识别输入形态：遍历 REPORT_DIR
    • 根目录 *.pdf 含文本层 → 电子版（parse_reports.py 处理）
    • 根目录 *.pdf 无文本层 → 扫描件（vision_ocr.py + extract.py）
    • 年度子目录 YYYY体检报告/*.JPG → 照片版（make_year_pdfs.py 合成 → OCR → extract.py）
  2. 解析电子版 PDF（坐标定位法，列边界见 references/解析与口径.md）： 
    $PY scripts/parse_reports.py                        # → data/reports_raw.json
$PY scripts/parse_reports.py --year 2027 --dry-run  # 单年份试跑，不写盘
  3. 照片版合成 PDF + OCR + 提取（如存在 JPG 目录 / 扫描件）： 
    $PY scripts/make_year_pdfs.py --year 2015-2020      # 年度多张 JPG → 单份 PDF（横拍自动旋转校正）
$PY scripts/vision_ocr.py <pdf> data/ocr_2022.json  # 扫描件/照片 OCR → 带坐标 JSON
$PY scripts/extract.py --year 2022                  # OCR 结果 → 指标（策略自动判定）
$PY scripts/extract.py --years 2015-2020            # 多年份 dict 型 OCR（缩写+参考范围反推）
    extract.py 按年份参数化，新年份无需改代码：放入 data/ocr_<年份>.json 后直接 --year <年份>。 策略默认 auto（输入 JSON 顶层为 dict → abbr，为 list → row），可用 --strategy 强制。
  4. 归一化 + 构建数据集（名称/单位映射、脏数据过滤、OCR 自动注入、生成脱敏版）： 
    $PY scripts/build_dataset.py
    产出 data/dataset_std.json（完整版，本地受控）+ data/anonymized/anonymized_dataset_anon_shareable.json（脱敏版，独立子目录 + 只读 444 + 可分享）
  5. 趋势分析（当年口径判定异常、显著变化 ≥20% 或 ≥参考宽度 30%、趋好/趋坏、近三年聚焦）： 
    $PY scripts/trend_analysis.py                        # 默认近三年
$PY scripts/trend_analysis.py --focus-years 2020,2023,2026
  6. 生成交付物： 
    $PY scripts/report_generator.py    # output/体检指标趋势分析报告.md（默认**开启**正文脱敏）
$PY scripts/build_dashboard.py     # output/health_dashboard.html（单文件离线）

新报告接入指南

新增年度体检报告时，按形态走对应分支（详见 references/新报告接入指南.md）：

  1. 放入报告：REPORT_DIR 根目录放 *.pdf，或建年度目录 YYYY体检报告/ 放 JPG
  2. 识别形态：检查 PDF 文本层（get_text() 长度 >0 = 电子版）
    • 电子版 → 直接跑 parse_reports.py；列边界异常时先打印 1 页坐标样本
    • 扫描件/照片 → make_year_pdfs.py → vision_ocr.py → extract.py --year <年份>（不要新建按年份的脚本）
  3. 补字典（如有未收录指标）：indicator_dict.py 的 NAME_MAP 补一行映射（日志见 data/unrecognized） 
    $PY scripts/indicator_dict.py --search 尿酸      # 查是否已收录（含别名）
$PY scripts/indicator_dict.py --validate         # 自检字典完整性（悬空别名/重复键）
$PY scripts/indicator_dict.py --count            # 当前标准指标总数
  4. 重跑流水线：build_dataset → trend_analysis → report_generator → build_dashboard
  5. 验收：确认新年份出现在 trend_analysis.json["years"] 与工作台时间轴；抽查 3 个关键指标数值与报告一致；生成并校验脱敏版

关键规则

  • 隐私硬约束（零容忍）：全程本地，技能内不含任何外发网络调用；任务完成必须生成并校验脱敏版（不含姓名/证件号/电话/地址/单位/医院），分享只用 data/anonymized/anonymized_dataset_anon_shareable.json（与完整版 dataset_std.json 分目录强隔离、只读 444，防止误分享完整版）
  • 脱敏校验先于写盘：build_dataset.py 的 _write_anon_verified() 是脱敏版落盘的唯一出口——先在内存校验、通过后才写盘。脱敏版落盘即置只读 444，若校验在写盘之后，命中身份信息时带 PII 的文件已留在磁盘且改不动，[FAIL] 只是事后告警。禁止绕过该出口直接调 _write_anon()；--skip-verify 仅供排查，产物不可分享
  • 报告正文脱敏：report_generator.py 的 mask_identity_text 默认开启（机构名称、医师姓名、手机号、身份证号掩码）；--no-mask 才关闭，仅供本地核对原文，生成物切勿分享
  • 新增年度报告：放入 REPORT_DIR → 重跑 2→6 步即可；字典未收录指标在 data/unrecognized 记录，补 indicator_dict.py 的 NAME_MAP 一行即可
  • OCR 数据定位：OCR 提取的指标只用于图表展示（灰色 Ⓞ 标注），不参与显著变化判定，避免污染统计
  • 趋势聚焦：整体趋势与首末对比仅基于聚焦年份（默认近三年，可用 --focus-years 覆盖），历史数据仅作展示背景
  • 口径一致性：异常判定用当年报告自带参考范围（试剂更换自动适配，如直接胆红素 2025 年起 0.0–4.0 → 1.7–6.8）

交付物

  • output/体检指标趋势分析报告.md — 指标汇总表、异常高亮、权威解读、分层建议（生活方式/饮食/运动/就医指征）、方法学
  • output/health_dashboard.html — 健康总览、趋好/趋坏分组筛选、折线图+参考范围带、时间跨度切换（单文件、无外部依赖）
  • data/anonymized/anonymized_dataset_anon_shareable.json — 可分享脱敏数据集

脚本一览

| 脚本 | 用途 | 主要参数 | |---|---|---| | check_deps.py | 依赖自检（Step 0） | --json --quiet | | parse_reports.py | 电子版 PDF 解析 | --report-dir --data-dir --year --out --dry-run | | make_year_pdfs.py | 年度 JPG → PDF | --report-dir --year --out-dir --dry-run | | vision_ocr.py | 扫描件/照片 OCR | pdf out（位置参数）--dpi --quiet | | extract.py | OCR 结果 → 指标（参数化） | --year --strategy --ocr-json --out --data-dir --quiet | | build_dataset.py | 归一化 + 脱敏版 | --work-dir --data-dir --out --skip-verify --dry-run | | trend_analysis.py | 趋势判定 | --work-dir --focus-years --out --dry-run | | report_generator.py | Markdown 报告 | --work-dir --out --no-mask --dry-run | | build_dashboard.py | HTML 工作台 | --work-dir --data-dir --out --quiet | | indicator_dict.py | 指标字典（被 import） | --list --search --count --validate --category（仅在直接运行时生效） |

退出码统一为三态：0 成功 / 1 运行期失败 / 2 参数或前置条件不满足。

参考文档

| 文档 | 内容 | |---|---| | references/新报告接入指南.md | 新形态/新年份报告接入的完整步骤与排错 | | references/解析与口径.md | 电子版 PDF 的列边界坐标、口径定义 | | references/OCR方法学.md | 扫描件/照片 OCR 策略、缩写映射表维护 | | references/Changelog.md | 完整版本历史 | | evals/ | 8 条回归评测（含 3 条隐私防线），eval_loop.py --run 可跑 |

使用示例（一次完整会话）

用户：「帮我把 2027 年体检报告加进去，更新趋势分析。」

  1. Step 0：python3 scripts/check_deps.py → 必需依赖齐全
  2. 检查 REPORT_DIR：发现新文件 体检报告_270510004567.pdf（电子版，文本层完整）
  3. 小样本确认列边界：打印 1 页坐标，与 references/解析与口径.md 一致 → 无需调整
  4. 跑流水线： 
    export REPORT_DIR=体检报告 WORK_DIR=/path/to/work
python3 scripts/parse_reports.py
python3 scripts/build_dataset.py
python3 scripts/trend_analysis.py
python3 scripts/report_generator.py
python3 scripts/build_dashboard.py
  5. 解析日志显示：新年度 98 项指标，1 个未识别名 → indicator_dict.py --search 确认未收录，在 NAME_MAP 补 1 行后重跑 build_dataset
  6. 验收：trend_analysis.json["years"] 含 2027；工作台时间轴出现 2027；抽查血糖/血脂/BMI 数值与报告一致；grep 脱敏版无身份信息
  7. 交付：报告 + 工作台路径告知用户；说明 2027 年各异常指标的变化与建议

降本纪律（执行时强制）

  1. 小样本先行：解析新格式前先打印 1 页坐标样本确认列边界，再全量处理（避免整文件 dump）
  2. 输出压缩：调试命令统一 | head -N / python -c 精准提取，禁止整文件 cat 大 JSON
  3. 子代理隔离：大文件读取/格式探测交给 Explore 子代理，主线程只收结论
  4. 验证只做一次最终截图，中间迭代用 DOM/JS 检查替代

专业领域合规声明（平台强制）

依据《腾讯云WorkBuddy开放平台开发者服务协议》§5.4 专业领域特别义务。本技能属医疗健康类专业领域能力。

  1. AI 生成内容仅供参考，不构成且不能替代医生等专业人士的意见。
  2. 本技能只做指标趋势整理与公开来源的解读编排，不提供诊断、不提供用药建议、不做诊疗决策。
  3. 涉及诊疗建议等影响重大权益的场景时，请主动引导使用者寻求线下专业医疗帮助——报告模板已内置「就医指征」分层提示。
  4. OCR 提取的指标准确率有限，趋势参考为主；指标持续异常或伴随不适症状，请及时线下就医。
  5. 个人信息保护：身份信息脱敏校验先于写盘，脱敏版落盘后置只读；报告与数据集不得含姓名、身份证号、手机号、体检机构等可识别信息。