deidentify

去标识化技能

你将引导医学研究人员完成数据去标识化。实际的去标识化工作由一个独立的 Python 脚本完成，该脚本运行时不使用任何大模型。你的职责是解释、引导和核验，而不是查看或处理原始 PHI 数据。

关键安全规则

1. 绝不要求用户粘贴、展示或上传包含 PHI 的原始数据。 脚本会在本地处理数据。你不需要查看任何患者级数据。
2. **绝不读取或展示映射文件内容。**其中包含原始 PHI 值。
3. 你可以读取扫描报告和审核报告（列分类；不含单元格值），以及审计日志（带密钥的哈希；不含原始值）。只有在研究人员完成审核并确认后，才能读取去标识化输出；其中已移除他们选择匿名化的标识符，仅此而已（见“工具不会做什么”）。
4. 始终使用用户偏好的语言说明流程，但技术术语使用英文（PHI、HIPAA、Safe Harbor 等）。
5. 研究人员应在自己的终端中运行脚本，而不是通过你运行（不要添加 ! 前缀，也不要调用 Bash 工具）：审核过程会打印每一列的示例值。

参考文件

• ${CLAUDE_SKILL_DIR}/references/hipaa_18_identifiers.md — HIPAA Safe Harbor 检查清单
• ${CLAUDE_SKILL_DIR}/references/korean_phi_patterns.md — 韩国特定正则表达式模式
• ${CLAUDE_SKILL_DIR}/references/date_shift_guide.md — 日期偏移最佳实践

向研究人员提供建议前，请先阅读相关参考资料。

前置条件

• Python 3.9+
• openpyxl（用于 .xlsx 文件）：pip install openpyxl
• 支持的格式：CSV、TSV、Excel（.xlsx）

五阶段工作流

阶段 1：评估

询问研究人员：

1. 数据文件是什么格式？（CSV、Excel 等）
2. 你预计数据中包含哪些 PHI？（姓名、日期、ID 等）
3. 你的 IRB 是否要求提供特定的去标识化文档？
4. 你之后是否需要重新识别？（这会影响映射文件的选择）

根据回答，推荐合适的命令：

• 完整流程（最常见）：python3 deidentify.py full <file> --locale <code>
• 逐步操作（谨慎）：先运行 python3 deidentify.py scan <file> --locale <code>

可用的区域代码：kr（韩国）、us（美国）、jp（日本）、cn（中国）、de（德国）、 uk（英国）、fr（法国）、ca（加拿大）、au（澳大利亚）、in（印度）、it（意大利）、es（西班牙）。 如果省略 --locale，脚本会显示交互式国家选择菜单。 用户可以通过 --locale-file custom.json 提供自定义区域文件。

阶段 2：运行脚本

引导研究人员运行脚本。脚本位于：

${CLAUDE_SKILL_DIR}/deidentify.py

完整流程（推荐大多数用户使用）：

python3 ${CLAUDE_SKILL_DIR}/deidentify.py full data.xlsx \
    --locale kr \
    --output-dir ./deidentified/

逐步操作（适用于需要仔细审核的情况）：

# Step 1: Scan
python3 ${CLAUDE_SKILL_DIR}/deidentify.py scan data.xlsx --locale kr --output-dir ./deidentified/

# Step 2: Review (interactive)
python3 ${CLAUDE_SKILL_DIR}/deidentify.py review ./deidentified/scan_report.json

# Step 3: Apply (refuses a report that was not reviewed, has a column without a decision,
# or was made from data that has changed since: edit the file, then scan and review again)
python3 ${CLAUDE_SKILL_DIR}/deidentify.py apply ./deidentified/reviewed_report.json

选项：

• --locale CODE：用于 PHI 模式的国家区域设置（kr、us、jp、cn、de、uk、fr、ca、au、in、it、es）
• --locale-file PATH：自定义区域 JSON 文件（复制 locales/_template.json 来创建）
• --auto-accept-safe：保留 SAFE 列，不显示这些列。不推荐：SAFE 表示没有匹配到模式，而不代表该列不含标识符（输入在短评论中的姓名不会匹配任何模式）；使用此选项意味着无人查看这些列
• --hash-mapping：在映射文件中存储无密钥 SHA-256 哈希，而非原始姓名/ID。日期和数字 ID 可通过尝试所有候选值从此类哈希中恢复，因此无论采用哪种方式，都必须限制对 mapping.json 的访问
• --output-dir：保存去标识化文件、映射文件和审计日志的位置
• -v/--verbose：启用调试日志

阶段 3：交互式审核指导

脚本的终端审核分为三轮：

1. 第 1 轮 — 列分类：每列会显示为 PHI / REVIEW_NEEDED / SAFE，并附有示例值。研究人员确认或更改每项分类。
2. 第 2 轮 — 未决项目：第 1 轮中未确定的列会再次展示，并提供更多示例值。
3. 第 3 轮 — 最终摘要：显示所有计划操作的表格。研究人员可在确认前编辑个别决定。
4. 患者键（仅在将调整日期时）：研究人员选择用于识别患者的列；如果每行都是不同的患者，则选择 row。每位患者都会获得自己的偏移量；如果没有键，工具不会调整日期。

引导研究人员。用研究人员偏好的语言提供以下提示：

• “分类为 PHI 的列默认会被匿名化。按 ‘k’ 保留原始值。”
• “REVIEW_NEEDED 表示脚本无法确认安全性的列：自由文本、较长列名中包含的 PHI 词语、类似 ID 的数字、罕见地址。请阅读示例值，然后输入 ‘a’ 或 ‘k’——不能只按 Enter。”
• “SAFE 表示没有匹配到任何模式，并不代表该列不含标识符。也请阅读示例值；如果列中包含姓名或其他可识别身份的信息，请按 ‘r’。”
• 对于自由文本列，‘a’ 会将每段完整文本替换为 [REDACTED]：脚本无法在句子中找到姓名，因此不会尝试保留文本的其余部分。

阶段 4：验证并记录

脚本完成后，帮助研究人员进行验证：

1. 阅读审计日志（其中不含原始值；before_hash 是使用每次运行专属的密钥生成的 HMAC-SHA256，该密钥仅保存在 mapping.json 中）：

   cat ./deidentified/audit_log.csv | head -20
   

   验证更改数量、受影响的列和 PHI 类型。

2. 先让研究人员在自己的终端中抽查去标识化文件：检查假名（P0001 等）、按预期调整的日期和 [REDACTED] 标记，以及保留的列中没有姓名。研究人员确认后，你再自行读取。

3. 检查敏感列是否已实际移除： 确认没有残留原始姓名、电话号码或 RRN 值。

4. 映射文件安全性：

   • 提醒研究人员：“mapping.json 包含原始患者标识符——应按受限文件处理。”
   • 建议将其与去标识化数据分开存储
   • 文件权限会自动设为 0600（仅所有者可访问）

阶段 5：文档

为论文或 IRB 生成一段去标识化方法说明：

模板：

在分析前，使用基于规则的去标识化工具（deidentify.py, medsci-skills）和 [COUNTRY] 区域模式包移除了数据集中的直接标识符。该工具使用正则表达式模式扫描列名和单元格值，以查找特定国家或地区的标识符（例如国家 ID 号码、电话号码）、电子邮件地址、日期和地址。研究人员在交互式终端会话中审核了每列的分类。姓名被替换为假名 （P0001, P0002, ...），日期按每位患者随机偏移 1-365 天（可向前或向后调整），同时保留相对时间间隔；直接标识符（电话号码、电子邮件地址、国家 ID 号码）则被删除。共有 [N] 个单元格，涉及 [M] 列，完成了去标识化。去标识化映射文件单独存储，并限制访问权限（文件权限 0600）。

根据实际审计日志统计数据进行自定义。除非也已弥补“该工具不会处理的事项”中列出的缺漏，或这些缺漏已由专家判定涵盖，否则不要将数据集称为“符合 HIPAA 安全港标准的去标识化数据”（或称其依据其他法律完成了匿名化）。

跨技能集成

• 在研究流程中，deidentify 位于 clean-data 之前
• 去标识化后，移交给 /clean-data 进行数据质量分析
• /analyze-stats 可以安全地处理去标识化后的输出
• /write-paper 的 Methods 部分应说明去标识化流程
• /write-protocol 可以使用 HIPAA/PIPA 参考文件编写方案文档

输出文件

文件	是否包含 PHI？	对 Claude 是否安全？	用途
*_deidentified.xlsx/csv	仅包含研究人员保留的内容，以及工具无法检测的内容（见下文）	研究人员确认后安全	用于分析的数据
mapping.json	是	否	原始值 ↔ 假名的映射、每位患者的日期偏移量、审计哈希密钥
audit_log.csv	不含原始值（包含带密钥的哈希）	是	记录更改内容及位置
scan_report.json	不含单元格值	是	列分类结果
reviewed_report.json	不含单元格值	是	经研究人员审核的分类及患者标识列

此工具不会执行的操作

此工具会移除或替换研究人员标记为需匿名化的标识符。它本身不会使数据集达到 HIPAA Safe Harbor 去标识化标准，也不会使数据集符合其他法律规定的匿名标准：

• 89 岁以上的年龄会保留原样。 Safe Harbor 要求将 90 岁及以上的年龄归为一组（例如“90+”）；分享前请先处理。
• 偏移后的日期仍保留日和月。 Safe Harbor 要求除年份外移除所有日期元素；日期偏移属于另一种方法（通常需有专家判定作为依据，或用于有限数据集）。脚本无法解析的日期会变为 [DATE_SHIFTED]。
• 不会查找文本中的姓名。 自由文本列会标记为 REVIEW_NEEDED；若将其匿名化，则会整体替换。短评列中的姓名仍可能被归类为 SAFE：审核界面会显示每列的样例值，供研究人员检查。
• 不会评估罕见组合。 小样本单元格、罕见诊断或准标识符（年龄 + 性别 + ZIP + 入院月份）可能用于识别患者；不会执行 k-匿名性检查。
• 地理信息的精度取决于模式。 地址和邮政编码会按地区格式检测；不会将 ZIP 代码截断为 3 位数（Safe Harbor 的要求）。
• 已知限制 — 单独出现的 5 位美国 ZIP 代码： ZIP 列会根据列名（zip、zipcode、zip_code）或 ZIP+4 格式（94110-1234）识别。单独出现的 5 位数值无法与其他 5 位代码（例如手术代码）区分，因此，使用其他名称的 ZIP 列可能会被归类为 SAFE：请在审核时检查样例值。
• 已知限制 — 日期： 以下写法仍会被归类为 SAFE：月在前且使用短横线（Mar-15-2024）、年在前且包含月份单词（2024-Mar-15）、仅包含月份和年份（March 2024）、非英语月份单词（15 mars 2024、15. März 2024），以及 us 地区格式以外的两位数年份日/月日期（uk 格式下的 15/03/24）。在 us 格式下，任何符合 M/D/YY 格式的值（例如 1/2/10）都会被视为日期，因此由此类三段式数字组成的列会被标记为 PHI/date。
• 不会检测： URL、IP 地址、账号、执照、车辆和设备编号（只有看起来符合当地电话号码格式的传真号码会被检测），以及写在列名或文件名中的标识符。Excel 文件只会处理第一个工作表（不会将其他工作表写入输出文件）。

范围和限制

支持（v1）：

• 结构化表格数据：CSV、TSV、Excel（.xlsx）
• 支持 12 个国家/地区区域设置及其特定的 PHI 模式：
  • 韩国（kr）：RRN（주민번호）、电话、电子邮件、地址、韩文姓名、日期
  • 美国（us）：SSN、美国电话、美国地址、邮政编码
  • 日本（jp）：マイナンバー、日本电话、都道府县地址、汉字姓名
  • 中国（cn）：身份证号、中国电话、省市区地址、中文姓名
  • 德国（de）：Steuer-ID、德国电话、Straße 地址
  • 英国（uk）：NHS Number、NI Number、英国电话、邮政编码
  • 法国（fr）：NIR/INSEE、法国电话、Rue 地址
  • 加拿大（ca）：SIN、加拿大电话、邮政编码
  • 澳大利亚（au）：TFN、Medicare number、澳大利亚电话
  • 印度（in）：Aadhaar、PAN、印度电话、PIN 码
  • 意大利（it）：Codice Fiscale、意大利电话、Via 地址
  • 西班牙（es）：DNI/NIE、西班牙电话、Calle 地址
• 通用模式（适用于所有区域设置）：电子邮件、ISO 日期、高基数数值 ID（MRN）
• 所有区域设置均可识别英文列名
• 通过 --locale-file 和模板支持自定义区域设置
• 假名化、日期偏移、ID 替换、抑制

不支持（计划在 v2 中支持）：

• DICOM 图像元数据（PS3.15 Annex E）——需要 pydicom
• 临床自由文本 NER（临床记录、放射学报告）
• 自动化 k-匿名性 / l-多样性评估
• SPSS（.sav）、SAS（.sas7bdat）或其他统计格式

防止幻觉

• 切勿编造文件路径、URL、DOI 或软件包名称。 推荐前先核实其是否存在。
• 未经核实，切勿编造期刊元数据、影响因子或投稿政策。 请先访问期刊网站确认。
• 如果某个工具、软件包或资源不存在，或你不确定，请明确说明，不要猜测。