dsh-medical-anonymizer

简体中文 | English

DeepSeek Harness（Cordis）插件， 用于批量匿名化病历文本和表格。它发现直接标识符，用稳定假名替换，保持文件结构不变， 并输出审计报告和可还原的映射库。

这是数据处理工具，不是合规认证。发布任何输出之前，请对照适用法律和本机构的政策进行审查。

特点

• 结构天然保持。 模型只负责标注文本；插件定位精确片段，只替换这些片段。 行数、CSV 列、JSON 键和 Excel 非文本单元格都不会变动。
• 规则优先，模型可选。 身份证校验位、电话/邮箱模式、带标签字段、列名/键名策略 无需模型即可运行。模型轮次用于提高自由文本的召回率，并复核结果。
• 有界修复循环。 复核轮次的发现会回到发现阶段，受轮次上限约束。未解决的条目 标记为人工复核，而不是被静默接受。
• 本地优先。 无遥测。插件只访问你配置的 OpenAI 兼容端点；指向本机运行时， 数据就不会离开本机。
• 输出可审计。 每个文件的实体统计、结构校验、残留问题、人工复核清单，以及唯一 保存原值的映射库。报告不打印标识符原值。

功能

方面	说明
格式	.txt、.md、.csv、.json、.xlsx
直接标识符	姓名、医生/职工姓名、身份证号、电话、邮箱、地址、病历号、住院号、就诊号、社保号、银行卡号、医院名称
列名/键名策略	姓名、身份证号、电话、住址 等表头，以及 PTT_NM、ID_CRD_NO、CTCT_TEL_NO、CURR_ADDR*、*_DCT_NM、MDC_ORG_NM、PID、INHOS_NO 等键整体替换为假名；PRM_KEY/RCD_NO 等记录键按记录标识符遮盖
假名	按值和类型稳定生成，如 化名-9F3A2C、证件-1F0B67；共用同一输出根的文件和批次中，同一个值得到同一个假名
可配置规则	按标识符类型选择：稳定假名（默认）、部分遮盖、类型标签或保留；可选处理准标识符（日期、年龄、性别、邮编）：平移、泛化或标签——见匿名化规则
校验	模型复核、规则复扫、原值残留检查、结构比对
模式	演练（只检测与校验，不写数据和映射库）、正式运行、取消
报告	Markdown + JSON，按文件和批次汇总，附人工复核清单

安装

要求 DSH >= 0.2.1（在 0.2.1-rc.5 上测试）和 Node.js >= 20。

dsh plugin --profile <profile> add github:wld007/dsh-medical-anonymizer
# 或在发布到 npm 之后：
dsh plugin --profile <profile> add dsh-medical-anonymizer

安装后重启 DSH：插件层在启动时组装。

设置页位于 设置 → 医疗数据匿名化。主机端激活后即可使用 /anonymize 命令和 Agent 工具。

模型配置

插件从不调用内置的云端模型，只使用你配置的 OpenAI 兼容端点。

运行时	Base URL	说明
Ollama	http://127.0.0.1:11434/v1	推荐本地使用
LM Studio	http://127.0.0.1:1234/v1	需开启本地服务器
vLLM / llama.cpp	你的 /v1 端点	任意 OpenAI 兼容的 chat 服务

模型名称留空则只运行确定性的规则层。配置模型后，插件会把每批文本发送到该端点进行 发现和复核；如果端点在远程，文本就会离开本机。处理患者数据请使用本机或机构可控的端点。

推理模型（Qwen3 等）可能把全部 token 预算花在隐藏推理上。关闭思考模式默认开启； 保持勾选，或给 /anonymize 加 --no-think。只有模型确实需要推理时才取消勾选 （或传 --think）。不接受这些可选请求字段的服务器会自动去掉字段重试一次。

使用

设置 → 医疗数据匿名化（配置）

只放配置，分为 模型连接、匿名化规则、批次与界面、使用说明 几个标签页：

• 本地模型：端点、模型、API Key、关闭思考模式、测试连接（端点上没有该模型名时会提示）。
• 批次默认值：输出根目录、最大轮次、默认使用演练模式。
• 匿名化规则：每类标识符的处理方式、准标识符开关、每类准标识符的处理方式，均附实时示例。
• 界面：在左侧栏显示或隐藏 医疗数据匿名化 入口。隐藏后 /anonymize 和 Agent 工具仍可使用。
• 保存栏列出未保存的字段；保存 会写入该 profile 自己的配置层，重启和插件更新后依然保留。 API Key 只在你输入或清除时保存，之后不再显示，存放在 profile 配置文件中（权限 600）。 批次运行期间不允许保存，因为保存会重新加载插件。

左侧栏 → 医疗数据匿名化（运行批次）

1. 选择输入目录；可选覆盖输出根目录。
2. 首次运行保持勾选 演练模式，然后启动批次。模型、端点和轮次取自已保存的设置。
3. 点击批次查看文件明细和报告、复制输出路径，或取消正在运行的批次。

/anonymize 命令

/anonymize /path/to/records --model qwen2.5:14b --endpoint http://127.0.0.1:11434/v1

默认为演练模式。加 --apply 才写出匿名化文件。

选项：--rounds N、--output DIR、--no-think、--apply。

Agent 工具

工具	用途
anonymize_start	启动批次并返回 runId
anonymize_cancel	取消正在运行的批次；已写出的文件保留
anonymize_status	进度、实体统计、未解决问题
anonymize_report	读取 Markdown 报告
anonymize_runs	列出最近的批次

anonymize_start 参数：inputDir、outputRoot、dryRun、maxRounds。

Agent 工具不能选择模型端点、模型、API Key 或思考模式：这些始终取自用户已保存的设置， 因此 Agent 无法把患者文本转发到其他服务。工具描述中写明了插件名和这一数据边界， 有助于 Agent 在名称相近的工具中选中它。只有人工输入的 /anonymize 命令接受 --endpoint 和 --model 覆盖。

工作原理

1. 规则预扫描。 身份证号（校验位验证）、手机/座机、邮箱、银行卡（Luhn）、 病历号/住院号/就诊号，以及带标签的姓名/地址/医院/医生。
2. 列名与键名策略。 专用字段整体替换为假名，包括常见医院导出键，如 PTT_NM、 ID_CRD_NO、CTCT_TEL_NO、*_ADDR*、*_DCT_NM、*_STFF_NM、MDC_ORG_NM、 PID、INHOS_NO。
3. 可选的模型发现。 文本分批发送到配置的端点。模型返回 {segment, type, text}； 插件在原文中定位精确文本。从不信任模型给出的坐标。
4. 假名化。 HMAC-SHA256(salt, type + value) 为每个值和类型生成稳定标记。 只改动匹配到的片段。
5. 校验。 模型复核、规则复扫、原值残留检查，以及结构比对（行数、CSV 形状/表头、 JSON 键/类型结构、Excel 非文本单元格）。
6. 有界修复。 错误回到发现阶段再跑一轮，最多 maxRounds 轮。如果没有进展， 该文件标记为 review 并列入人工复核清单。

匿名化规则

默认行为与早期版本一致：所有标识符替换为稳定假名，准标识符不处理。

标识符策略	示例（张三、13800138000）	可还原
pseudonym（默认，稳定假名）	化名-9F3A2C、电话-7A8ED8	是，通过映射库
mask（部分遮盖）	张*、138****8000	否；保留部分原值
redact（类型标签）	[姓名]、[电话]	否
keep（保留）	不变	—

遮盖规则：姓名保留首字；身份证号保留前 3 位和后 4 位；电话保留前 3 位和后 4 位； 银行卡和各类编号保留后 4 位；邮箱保留首字母和域名；地址保留省/市/区前缀； 医院保留前 2 个字和后缀。

只有开启 quasiIdentifiers 时才处理准标识符。它们在标识符之后以确定性方式处理， 不使用模型：

类型	策略（开启后第一个为默认）	示例
日期	shift、month、year、redact、keep	2024-03-01 → 2024-04-07 / 2024-03 / 2024
年龄	band10、band5、redact、keep	45岁 → 40-49岁 / 45-49岁；90 岁及以上 → 90岁及以上
性别	keep、redact	男 → [性别]
邮编	prefix3、redact、keep	100020 → 100***

• 检测范围包括正文（2024-03-01、2024年3月1日、45岁、年龄：45、性别：男、 邮编：100020）以及 BTH_DT、*_DT、出生日期、AGE、GDR_NM、SEX、ZIP、 邮编 等字段；紧凑的 YYYYMMDD 格式只在日期字段中识别。
• 日期平移在每个输出根下使用同一个偏移量（±1–365 天），由映射库的盐值派生， 因此日期之间以及跨批次的间隔保持不变。偏移量不会出现在报告中。不要对平移后的 输出再次平移。
• 只修改文本值：Excel 数值/日期单元格和 JSON 数字保持原样，报告中会说明这一点。

输出

<outputRoot>/
  vault.json                 # 原值 <-> 假名，权限 0600
  index.json                 # 最近的批次
  runs/<runId>/
    output/...               # 匿名化副本，相对目录结构不变
    report.md
    report.json

vault.json 是还原身份的钥匙。请与输出分开存放并妥善保护。报告刻意不包含任何原值。 在插件配置中设置 vaultPassphrase 可用 AES-256-GCM 加密映射库；不设置时映射库为 权限 0600 的明文 JSON。

未显式指定也未配置 outputRoot 时，输出写到输入目录旁边的隐藏目录 .medical-anonymizer，因此相邻的批次（例如每位患者一个文件夹）共享同一个映射库， 假名保持一致。输出根不能与输入目录相同。如果放在输入目录内部，它会被排除在扫描之外， 映射库和之前的输出不会被当作病历重新读入。

演练模式会读取已有映射库以保持标记稳定，但从不写入新的映射库。扩展名不受支持的文件， 以及超出 maxFiles 的文件，会列在报告的 注意 部分；因 maxFiles 被截断的批次 标记为 review。

隐私与安全

• 无遥测、无统计、无隐藏的网络请求。唯一的出站请求是发往配置的 chat 端点 （以及点击测试时的 /models）。
• 模型能看到它被要求检查的文本。处理患者数据请使用本机运行时或位于信任边界内的端点。 共享网络上的明文 HTTP 不是安全的传输方式。
• 报告不含标识符原值，但包含输入/输出路径；报告和映射库都应按受保护健康信息（PHI）对待。
• 插件从不改写输入文件；输出写到你选择的输出根。
• 文件名和目录名原样复制。发布输出前，请重命名文件名中含有标识符的文件。
• 这不是合规认证。除非开启准标识符处理，日期、年龄、性别、机构和罕见诊断的组合 仍可能重新识别个人；报告会说明处理了哪些准标识符。
• mask 保留部分原值且不可还原；keep 会把标识符留在输出中。两者都会在报告的警告中列出。

配置

默认值位于 cordis.patch.yml，可在 profile 的 patch 层覆盖：

- id: medical-anonymizer
  config:
    baseURL: http://127.0.0.1:11434/v1
    model: qwen2.5:14b
    outputRoot: ''
    maxRounds: 3
    maxFiles: 200
    maxLlmCalls: 240
    timeoutMs: 120000
    temperature: 0
    disableThinking: true
    dryRun: true
    vaultPassphrase: ''
    identifierPolicy: { name: pseudonym, phone: mask, hospital: keep }  # 未列出的类型：pseudonym
    quasiIdentifiers: false
    quasiPolicy: { date: shift, age: band10, sex: keep, postalCode: prefix3 }

• maxFiles 限制单批文件数；maxLlmCalls 限制单批模型调用次数。
• timeoutMs 是单次模型调用的超时。
• outputRoot 为空表示 <输入目录的上级>/.medical-anonymizer。

支持的格式与限制

• 输入：.txt、.md、.csv、.json、.xlsx。
• 默认处理直接标识符；准标识符（日期、年龄、性别、邮编）需手动开启。科室、机构代码 和医嘱号从不泛化。匹配 PRM_KEY/RCD_NO 的记录键按记录标识符处理；医嘱号不处理。
• 字段提示覆盖常见的中英文医院数据结构。不常见的字段名需要在 lib/formats.js （HEADER_HINTS）中添加模式。
• 不支持 Word、PDF、图片或 DICOM。JSON 输出会格式化缩进；键、数组和值类型不变。
• 模型轮次是可选的，效果取决于模型。确定性规则层是基线。

开发

npm test                      # 字段提示、规则策略、端到端流程
node scripts/build.mjs 0.3.1  # 为本地 profile 构建带版本号的 dist/

npm test 使用确定性的模拟模型，不需要网络或真实数据。本地安装仅用于开发； 最终用户请从 GitHub 或 npm 安装。

故障排查

• 模型超时或返回空内容。 开启关闭思考模式、改用指令（非推理）模型，或把模型留空 只依赖规则层。批次会继续运行并记录模型警告。
• 结构化文件中没有发现标识符。 检查其字段名是否在 HEADER_HINTS 中；为你的数据结构 添加模式。
• 设置页不见了。 确认 profile 使用 DSH >= 0.2.1、插件包已启用，且安装后已刷新页面。
• vault.json 无法读取。 它是用 vaultPassphrase 加密的；配置相同的口令即可读取。

许可证

MIT，见 LICENSE。本包内置 SheetJS Community Edition 0.20.3（Apache-2.0）， 见 NOTICE 和 vendor/SheetJS-LICENSE.txt。