Health Vault — 个人健康信息管理系统

🚨 第一关：姓名确认（所有录入操作的前置条件）

⚠️ 任何病历/报告/数据录入操作，在写入任何文件之前，必须先通过此关卡。

收到文件/数据后，第一步永远是提取姓名并匹配：

1. 提取姓名 → OCR或视觉理解，在报告中找到「姓名」「患者姓名」字段
2. 匹配已有目录 → 检查 ~/.health-vault/ 下是否有同名目录
3. 确认规则：
   • ✅ 已存在目录 & 与提取姓名一致 → 直接使用
   • ⚠️ 提取到新姓名（目录中不存在） → 必须向用户确认： "报告中姓名为「XXX」，系统中无此档案。是否为 XXX 新建健康档案？"
   • ⚠️ 未提取到姓名 → 必须向用户确认： "未在报告中提取到姓名。请问这是谁的检查报告？"
4. 确认后方可继续 → 用户确认后才能创建目录、写入文件

🚫 严禁行为：

• 根据文件名推测姓名并直接录入
• 因为文件看起来像是某人的就跳过确认
• 在用户确认前创建任何文件

唯一例外： ~/.health-vault/ 下只有一个用户目录，且提取到的姓名与之精确匹配 → 可跳过确认。

已知坑与经验

1. 生成图表时中文显示为方块

• 现象： matplotlib 生成的 SVG/PNG 图中，中文标题、图例、坐标轴标签全部显示为方块
• 原因： matplotlib 默认字体不支持 CJK 字符
• 解决： 必须显式指定中文字体

  import matplotlib.font_manager as fm
  # macOS 可用字体：Heiti TC, Lantinghei SC, PingFang HK, Songti SC
  for f in fm.fontManager.ttflist:
      if f.name == 'Heiti TC' and 'Medium' in str(f.fname):
          font_path = f.fname
          break
  font_prop = fm.FontProperties(fname=font_path)
  # 所有中文文本必须传入 fontproperties=font_prop
  ax.set_title('标题', fontproperties=font_prop)
  

• 验证： savefig 后检查终端输出，不应有 Glyph missing from font(s) 警告

2. 飞书不支持 SVG 图片

• 现象： MEDIA 指令发送 SVG 时飞书收不到（replies=0）
• 解决： 生成图表时同时输出 PNG 和 JPG，JPG 兼容性最好

  plt.savefig('/tmp/chart.png', dpi=150)
  plt.savefig('/tmp/chart.jpg', dpi=150)
  

• 顺序： 先发 JPG，不行再试 PNG

3. PNG 在飞书上也不总是稳定

• 现象： 部分 PNG 在飞书上发送成功但对方收不到（MEDIA 指令有时失败）
• 解决： 同时生成 JPG 作为备选格式，JPG 飞书兼容性>PNG>SVG

4. OCR 提取日期不可靠

• 现象： 图片 OCR 可能正确提取数值但漏掉或错误识别日期（如报告实际日期 04-09 被误认为 04-22）
• 解决： OCR 提取后，明确向用户确认日期，特别是多份相关报告时
• 操作： "OCR 未提取到日期，请问这份报告是哪天的？"

技能位置

~/.openclaw/skills/health-vault/     ← 技能代码（所有 agent 共享）
├── SKILL.md
├── AGENTS.md
├── scripts/
│   ├── ocr_extract.py
│   └── parse_apple_health.py
├── references/
│   ├── lab_ranges.md
│   ├── medical_fields.md
│   └── advice_templates.md
└── assets/
    └── record_template.md

数据位置

~/.health-vault/                      ← 数据根目录（独立于技能代码）
└── {用户姓名}/                        ← 按姓名隔离
    ├── profile.md
    ├── diseases.md
    ├── CHANGELOG.md
    ├── apple_health_summary.json
    ├── records/                      ← 结构化病历
    │   └── YYYY-MM-DD_类型.md
    ├── originals/                    ← 原始报告（按年份归档）
    │   ├── 2019/
    │   ├── 2025/
    │   └── ...
    └── trends/                       ← Apple Health 时间序列
        ├── body_mass.json
        ├── bmi.json
        └── ...

用户姓名确认流程

首次处理报告时，或需要确定数据写入目标时，按以下优先级流程确定用户目录：

Step 0: 从报告中提取姓名

• OCR 或视觉理解报告内容后，在报告头部查找「姓名」「患者姓名」字段
• 如果提取到姓名（如「耿玉峰」），进入 Step 1

Step 1: 匹配已有目录

提取到姓名？
  ├─ 是 → 检查 ~/.health-vault/ 下是否存在同名目录
  │       ├─ 存在 ✅ → 直接使用该目录
  │       └─ 不存在 ⚠️ → 与用户确认：
  │           "报告中姓名为「XXX」，但 ~/.health-vault/ 下尚无该目录。
  │            是否为 XXX 新建健康档案？"
  │           ├─ 用户确认是 → 创建该目录，进入 Step 2
  │           └─ 用户修改姓名 → 用修改后的姓名继续判断
  │
  └─ 未提取到 ⚠️ → 与用户确认：
      "未在报告中提取到姓名。请问这是谁的检查报告？（请输入姓名）"
      → 用用户提供的姓名继续判断

Step 2: 创建新用户目录

用户确认姓名后：

• 在 ~/.health-vault/ 下创建同名目录
• 初始化以下结构：

  {姓名}/
  ├── profile.md       ← 从 assets/record_template.md 复制并填入姓名
  ├── diseases.md      ← 空疾病清单模板
  ├── CHANGELOG.md     ← 空变更日志
  ├── records/         ← 空目录
  ├── originals/       ← 空目录
  └── trends/          ← 空目录
  

• 后续所有读写操作以 ~/.health-vault/{姓名}/ 为根

Step 3: 多报告处理

• 同一会话中收到多份报告 → 先处理第一份，确认姓名后，后续报告自动沿用同一用户目录
• 跨会话再次收到报告 → 每次仍然执行 Step 0-1（防止用户发的是家人的报告）
• 如果 ~/.health-vault/ 下只有一个用户目录，且提取到的姓名与之匹配，可跳过确认直接使用

数据层级

查询规则：

• "身体怎么样" → 读 profile.md
• "体重趋势/心率变化" → 读 profile.md + trends/body_mass.json（如需详细数据）
• "体检报告" → 读 records/ 下对应文件
• "健康建议" → 读全部

重要原则：

• 所有数据本地存储，不上传云端
• 每次修改后更新 CHANGELOG.md
• 敏感数据不发送到外部 API（OCR 直接用模型视觉理解，tesseract 作为离线备选）
• trends/*.json 格式：[{date, value, count, min, max}, ...]，支持增量合并去重

Workflow 1: 添加病历（OCR + 结构化提取）

输入形式

• 用户上传 图片（拍照纸质报告/化验单）
• 用户上传 PDF（电子病历/体检报告）
• 用户直接提供 文字描述（"体检结果为…"）

处理步骤

Step 1: 确定用户姓名

按「用户姓名确认流程」执行，确定数据写入目标 ~/.health-vault/{姓名}/。

Step 2: 确定记录类型

询问或推断：

• 体检报告 / 门诊病历 / 住院记录 / 化验单 / 影像报告（B超/CT/X光/MRI）/ 处方

Step 3: 提取结构化信息

对于 清晰的图片/PDF：

• 直接使用多模态视觉能力，让模型看报告并提取为结构化内容
• AI 可以理解"白细胞计数升高提示感染"这种上下文，比纯 OCR 更智能
• 要求模型输出 Markdown 格式的表格和结构化字段

对于 模糊/手写/老旧扫描件：

• 运行 python3 ~/.openclaw/skills/health-vault/scripts/ocr_extract.py \x3C文件路径> 做离线 OCR
• OCR 输出纯文本后，再让模型做结构化提取和纠错

Step 4: 保存记录

• 保存原始文件： 将用户发来的原始图片/PDF 复制到 ~/.health-vault/{姓名}/originals/{年份}/ 目录，按 "日期_类型.扩展名" 命名
• 创建结构化记录： 创建 ~/.health-vault/{姓名}/records/YYYY-MM-DD_类型.md，使用标准模板
• 两个文件通过日期和类型关联，方便从结构化记录回溯原始报告

Step 5: 同步更新

• 更新 ~/.health-vault/{姓名}/profile.md 中的最新身体指标
• 更新 ~/.health-vault/{姓名}/diseases.md 中的疾病时间线（如有新诊断/新发现）
• 记录变更到 ~/.health-vault/{姓名}/CHANGELOG.md
• 确保原始文件和结构化记录都已保存

Workflow 2: Apple Health 数据导入

触发

• 用户发送 Apple Health 导出的 导出.zip（飞书文件消息）
• 用户说 "更新健康数据" / "同步 Apple Health"

处理步骤

Step 1: 确定用户姓名

按「用户姓名确认流程」执行。

Step 2: 接收文件

• 飞书文件消息会自动下载到 ~/.openclaw/media/inbound/
• 要求 mediaMaxMb ≥ 500（Apple Health 导出通常 50-300MB）

Step 3: 解析提取

python3 ~/.openclaw/skills/health-vault/scripts/parse_apple_health.py \
  \x3C导出.zip路径> \
  --output-dir ~/.health-vault/{姓名} \
  [--incremental]

• 流式解析 export.xml（避免内存溢出）
• 提取 14 个关键指标的时间序列
• 按日聚合（多条记录取均值）

Step 4: 合并存储

• 按日期去重（新数据覆盖旧数据），追加写入 ~/.health-vault/{姓名}/trends/*.json
• 重新计算 trends/all_stats.json
• 更新 profile.md 摘要
• 更新 CHANGELOG.md

Step 5: 输出摘要

• 展示关键指标的最新值和趋势方向
• 提醒异常值（如体重骤变 >2kg/月、静息心率异常升高等）

Workflow 3: 维护身体基础信息

数据结构：~/.health-vault/{姓名}/profile.md

支持简短的直接更新指令：

• "更新体重 71.5" → 写入 profile.md 体重趋势表
• "记录血压 118/78" → 写入血压趋势表
• "新增诊断 过敏性鼻炎 2026-06-03" → 写入 diseases.md

Workflow 4: 疾病发展历程

数据结构：~/.health-vault/{姓名}/diseases.md

所有新诊断自动追加时间线，标记来源记录文件。

Workflow 5: 健康分析与保养建议

触发

• "健康建议" / "保养建议" / "我的健康评估" / "我应该注意什么"
• 每次添加新病历后自动触发简短评估

分析逻辑

1. 读取所有数据源： ~/.health-vault/{姓名}/profile.md + diseases.md + 最新记录
2. 识别异常指标： 对比参考范围（参考 references/lab_ranges.md）
3. 趋势计算： 同一指标连续记录，计算变化方向
4. 综合评估： 结合年龄、家族史、生活习惯、现有疾病
5. 联网补充： 遇到不熟悉的项目 → web_search 查权威来源
6. 输出分层建议

Workflow 6: 趋势查询

用户说 "体重趋势" / "血压变化" / "[指标]趋势"：

1. 先读 ~/.health-vault/{姓名}/profile.md 获取摘要
2. 如需详细数据，读取 ~/.health-vault/{姓名}/trends/\x3Cmetric>.json
3. 计算变化量、方向、波动幅度
4. 用文字描述趋势
5. 如果波动异常主动提醒

异常检测规则

数据安全

1. 本地存储： 所有数据仅在 ~/.health-vault/ 内
2. 无云端上传： 病历数据绝不发送到第三方 API
3. 视觉理解： 使用 Agent 本地多模态能力看报告，不经过外部 OCR 服务
4. 联网仅用于查询医学知识： 仅当需要查正常值范围/药物信息/治疗指南时，才触发 web_search（且只搜公开医学知识，不传病历原文）
5. .gitignore： ~/.health-vault/ 加入 .gitignore，不进版本控制

依赖工具