# 隐溯 NymTrace 学生使用手册

## 1. 安装与界面

macOS 完整解压 `NymTrace-1.0.12-macOS-arm64.zip` 后，把 `NymTrace.app` 放入“应用程序”；Windows 完整解压 `NymTrace-1.0.12-Windows-x64.zip` 后运行 `NymTrace.exe`，并保持 `_internal` 文件夹与 EXE 在同一目录。不要直接在 ZIP 内运行，也不要单独移动 EXE。可用同名 `.sha256` 文件核对复制是否损坏。

主界面有三个页面：

1. “自动脱敏”：拖入源文件或文件夹，等待软件按资料实际内容生成可选项目，再选择输出目录并运行。
2. “对应表恢复”：用本机对应表把 Agent 结果中的代号恢复为原值或生成敏感字段清单。
3. “使用说明”：查看安全边界和正确的上传范围。

NymTrace 不提供 Agent，也不调用云端 API。恢复功能只在本机使用对应表，不读取原始源文件、不联网。

## 2. 自动脱敏

1. 点击“添加文件”“添加文件夹”，或直接把文件/文件夹拖入列表。此时没有预设选项；软件会自动开始只读本地分析。
2. 等待进度区显示“选项已生成”。界面只列出本批资料实际发现的敏感类型，并显示字段数、命中数和涉及文件数；不在界面显示患者原值。结构化表头与确定性规则优先，只有规则无法判断的自然语言才会惰性加载本地量化 NER。
3. 实际发现项默认全部勾选。只有研究方案明确要求保留某一发现项时才取消；软件会再次要求确认，未选项目可能保留，`PASS` 只代表所选范围通过。至少勾选一项才能运行。
4. 如果文件包含不支持或无法完整枚举的表面，或没有发现可明确分类的项目，软件不会凭空显示一套预设清单，而是自动启用不可缩小的“保守完整检查”。可安全处理的文件和表面继续脱敏；不能安全处理的原内容不会复制到数据目录，并写入匿名说明。
5. 项目名仅用于本机任务标识，建议使用普通课题名，不要填写患者姓名或病案号。
6. 选择脱敏输出目录；不存在时软件会新建。输出目录不能位于源文件夹内部，源文件也不能位于输出目录内部。
7. 点击“开始本地自动脱敏”。动态选项与源文件集合及 SHA-256 绑定；文件在分析后变化时，本次运行会停止并自动重新分析，绝不会沿用过期选择。进度区随后显示全局 0–100%、当前文件和阶段。大表行级进度会合并，避免界面队列阻塞。
8. 运行期间不要修改、移动或覆盖源文件；项目名、选项、输出目录、源列表和关闭窗口会暂时锁定，以保护对应表和输出完整性。
9. 查看最终闸门：

   - `PASS`：对应表与脱敏数据文件夹已原子化生成。
   - `PARTIAL`：能安全脱敏的内容已经生成；不能分析、不能安全脱敏或复检不通过的文件/表面没有复制原内容。先阅读 `NYMTRACE_EXCLUSIONS.csv`。
   - `NEEDS_REVIEW`：旧任务或特殊人工复核流程仍保留在本机私有区，不会自动外发。
   - `BLOCKED`：本次没有可安全形成的交付结果，或运行级安全条件失败。

如果解析组件或工作线程异常退出，软件会结束“处理中”状态、解除按钮锁定，并在本机私有目录生成不含源路径、单元格内容或患者标识的诊断 JSON。

## 3. PASS 或 PARTIAL 后得到什么

```text
NymTrace_<ProjectID>_<Timestamp>/
├── 1_NymTrace_脱敏对应表_禁止上传.xlsx
└── 2_NymTrace_脱敏后完整数据_可分析/
    ├── data/
    ├── README_FIRST.txt
    ├── AGENT_INSTRUCTIONS.md
    ├── NYMTRACE_MANIFEST.json
    ├── QUALITY_REPORT.html
    ├── TRACE_IDS.csv
    ├── NYMTRACE_EXCLUSIONS.csv  仅 PARTIAL/有省略时出现
    └── SHA256SUMS.txt
```

### 对应表

对应表包含“敏感类型、脱敏前原值、脱敏后值、关联病例 ID、关联 TraceID”。TraceID 用于在恢复时精确区分同一替换日期的不同来源位置。对应表仍是敏感医疗数据：

- 只能保存在授权的本地电脑或机构批准的受控存储。
- 禁止上传任何云端模型、Agent、网盘、邮箱、协作平台或公共聊天。
- 禁止把整个 `NymTrace_<ProjectID>_<Timestamp>` 目录交给 Agent，因为该目录同时包含对应表。
- 对应表中的值按纯文本写入，不会执行 Excel 公式。

### 脱敏数据文件夹

`data/` 中保存能安全生成的 TXT/Markdown、表格、DOCX、PDF、图片或 DICOM 脱敏派生文件。其余文件用于说明、安全质量检查和完整性校验。`PARTIAL` 时，`NYMTRACE_EXCLUSIONS.csv` 只包含匿名 SourceFileID、格式、处理结果和原因代码，不包含原文件名、路径或患者值。分析时只提交整个 `2_NymTrace_脱敏后完整数据_可分析` 文件夹。

## 4. 交给 Codex、Claude Code 或其他工具

NymTrace 不提供或调用 Agent。学生自行选择分析工具时：

1. 先确认课题伦理、机构政策、数据使用授权和跨境规则允许使用该工具。
2. 只提交脱敏数据文件夹，不提交对应表、原始数据或 NymTrace 私有存储。
3. 把文件夹内 `AGENT_INSTRUCTIONS.md` 一并交给工具，要求保留数据来源标识，不猜测或恢复被移除身份。
4. 分析时要求工具保留 `NymTrace_TraceID` 列、`[TraceID:...]` 标记和 `NT_*` 代号；不要让工具主动猜测或删除这些值。
5. 如果只需要汇总结果，可直接使用；如果要回填原字段，按下一节把结果带回本机。

去标识化不会自动产生云端上传权限。即使软件显示 `PASS`，仍应由研究负责人决定是否允许外发。

## 5. 用对应表在本机恢复

1. 打开“对应表恢复”，选择原任务生成的 `1_NymTrace_脱敏对应表_禁止上传.xlsx`。对应表不要上传给 Agent。
2. 拖入 Agent 处理后的 TXT/Markdown/JSON、CSV/TSV、Excel、DOCX、PDF、图片或 DICOM 文件，也可拖入整个结果文件夹。
3. 在恢复页顶部点击“选择保存目录…”，自定义恢复结果保存位置；也可直接输入一个尚不存在的目录。软件会在该位置新建带时间戳的敏感结果文件夹，不覆盖对应表或输入文件。
4. 确认敏感信息警告并运行。TXT、表格、DOCX 和 DICOM 元数据会生成含原值的恢复副本；无法唯一匹配的代号保持不变并列入报告。
5. PDF、图片和 DICOM 中已经永久遮挡的像素不会被“猜回去”。可识别的代号与原值写入 `NymTrace_恢复字段清单_含敏感原值.xlsx`。
6. 恢复目录、恢复副本和字段清单都含真实敏感信息，只能留在授权本机，严禁再次上传 Agent、云端、网盘、邮件或聊天。

同一个日期代号可能对应不同患者的不同原日期。只有结果保留关联 TraceID，或全表只有唯一原值时，软件才自动回填；否则保持代号并报告歧义。

## 6. 常见阻断

- `BILINGUAL_NER_MODEL_UNAVAILABLE`：本地模型包缺失、损坏或哈希不符；受影响文件不导出并进入 `PARTIAL` 说明。
- `UNSUPPORTED_OR_UNSAFE_FORMAT`：该文件不复制，同批其他文件继续；可转换为支持格式后单独重试。
- `PDF_EMBEDDED_ATTACHMENTS`：附件从图片型派生 PDF 中移除并说明；如需使用，离线提取后逐个重新脱敏。
- `DOCX_EMBEDDED_ACTIVE_OBJECTS`：OLE、ActiveX 或其他活动对象不复制；重建后的正文可继续导出并标为 `PARTIAL`。
- `DICOM_HEAD_VOLUME_REQUIRES_DEFACING`：头颅影像需经过验证的医学影像 defacing 工作流。
- `DICOM_PIXEL_DECODE_FAILED`：像素无法安全解码；安装相应无损解码器或转换为可信的未压缩 DICOM 后重试。
- `SOURCE_CHANGED_DURING_PROCESSING`：处理期间源文件发生变化；关闭编辑软件、恢复稳定副本后重跑。
- 资料分析失败或选项自动失效：关闭正在编辑源文件的 Excel/Word 等程序，确认文件可读且格式受支持，再点击“重新分析”。无法完整预分析时软件会保守扩大范围，不会静默漏掉选项。
- `INDEPENDENT_RESIDUAL_SCAN_FAILED`：最终独立扫描仍发现可能的敏感信息；该派生文件会被清除，同批安全文件继续导出。
- `RESIDUAL_ENTITY_IN_UNIT`：自动补充脱敏达到安全轮次上限后仍有疑似实体；相关文件不放行并写入说明。
- `LEGACY_WORKBOOK_LIMITED_SURFACE_ENUMERATION`：旧 `.xls/.xlsb` 可读单元格会重建脱敏；批注、宏、外链等无法保证的隐藏表面不复制，并在 `PARTIAL` 清单说明。

## 7. 使用边界

NymTrace 是本地去标识化/假名化工具，不是不可逆匿名化证明、临床诊断软件或合规认证。图片人脸、手写签名和复杂影像可能只形成区域遮挡，不一定存在可列入文本对应表的原值；这类处理会在质量报告中记录。请保留原始数据的机构备份，不要把 NymTrace 当作唯一存档工具。