clinical-note-extract-skill

临床笔记提取

根据用户定义的架构，从临床笔记中进行结构化提取，为每个值提供跨度引用，并对每个缺失项明确标记为 null。无论是一条笔记还是多条笔记，处理流程都相同：由隔离的无工具工作器提取每条笔记，然后通过确定性验证流程检查跨度和代码。

这是护理缺口推理、不良事件检测、试验资格筛查、事先授权证据整理和登记表抽取等工作的基础提取功能。

步骤

1  Define schema   — references/01-define-schema.md
2  Extract         — workflows/extract-batch.js (one isolated worker per note)
3  Validate        — span check + run each field's `check`
4  Report          — references/03-review.md

步骤 1 — 定义架构

阅读 references/01-define-schema.md。将用户的请求转换为架构：每个字段均为 {desc, finding?, check?}。desc 使用笔记本身的术语说明要查找的内容；finding: true 表示对断言进行分类；check 说明步骤 3 如何验证（开放式——{kind: "terminology"|"range"|"date"|"pattern"|"enum"|..., ...params}）。提取前先与用户确认。

步骤 2 — 提取

无论用户以何种方式提供笔记——粘贴文本、文件路径、目录、PDF、FHIR 连接器或数据库查询——都使用你拥有的工具将其解析为纯文本，然后调用已保存的工作流，每条笔记传入一个 {id, text}。工作流的输入契约是唯一严格要求；如何满足该要求由你自行处理。工作流会为每条笔记运行一个 note-extract-worker Agent（不提供工具——笔记文本不可信），每个 Agent 均遵循 references/rules.md，并为每条笔记返回一条符合架构的记录：

Workflow({
  scriptPath: "<this skill dir>/workflows/extract-batch.js",
  args: {
    notes:  [{id, text}, ...],     // one or many
    schema: <the schema from step 1>,
    rules:  <Read references/rules.md verbatim>
  }
})

工作器没有工具——它们只返回读取到的内容（value、span、presence/temporality/experiencer、null_reason、unit）。所有检查都在步骤 3 中进行。由于笔记文本会内联放在 args 中，每次调用工作流最多处理几十条笔记。对于更大的语料库，请改用 bun <this skill dir>/scripts/batch.ts <notes-dir> <schema.json> records.jsonl——它会在可信代码中读取文件，并按照相同规则为每条笔记启动一个禁用工具的提取流程，然后从步骤 3 开始处理生成的 records.jsonl。

步骤 3 — 验证

在调用会话中执行。验证是确定性的，不涉及模型判断。对每条记录：

1. 跨度检查。 对每个非 null 字段，确认 span 原样出现在该笔记的源文本中。添加 span_verified。
2. 运行每个字段的 check。 根据 check.kind 分派：
   • terminology——在所有记录中对 (check.via, value) 去重，通过能够响应 via 的任意连接器逐项查询，并添加 {code, code_status, display}。没有对应 via 的连接器 → code_status: "unvalidated"，并在报告中注明。
   • range——将 value 与 [min, max]、将 unit 与 check.unit 比较；添加 range_flag。
   • date——确认 value 能解析为日期；添加 date_ok。
   • pattern / enum——进行匹配；添加 check_ok。
   • 其他情况 / 未设置 check——无需添加任何内容。

当字段的 span_verified 已通过，且其检查（如有）也通过时，该字段才可信。添加检查类型只需在此处添加一个分支；上游无需改动。

步骤 4 — 报告

阅读 references/03-review.md。每个（笔记，字段）输出一行：note_id | field | value | presence/temporality/experiencer | span | check。其下方提供完成情况摘要：请求的字段数 / 已填充字段数 / null 字段数，并按 check.kind 列出通过和标记的问题（注明任何缺少连接器的术语 via）。切勿默默略过未通过的检查或未经验证的跨度。

提出将记录和报告写入 ~/.claude/data/healthcare/clinical-note-extract/<run-id>/。该目录是本地工作状态，不是档案：未经用户明确指示，不要将其复制到共享驱动器或外部系统；并告知用户在取得所需内容后可以删除该目录——提取的记录会包含源笔记中的任何 PHI。

输出约定

Worker 针对每个字段输出：{value, span, location, presence?, temporality?, experiencer?, null_reason?, unit?}——仅包含其读取到的内容。第 3 步会附加 span_verified，以及该字段的 check 所产生的内容（术语检查对应 code/code_status/display，范围检查对应 range_flag 等）。

可选 — 导出为 FHIR

如果用户需要 FHIR 资源，而不是扁平记录，则断言轴可直接映射：

记录	FHIR
experiencer != patient	FamilyMemberHistory.condition（而非 Condition）
presence: absent → verificationStatus: refuted；possible → unconfirmed；present → confirmed	Condition.verificationStatus
temporality: historical → inactive；current → active	Condition.clinicalStatus
temporality: hypothetical	没有原生字段——省略，或使用 RiskAssessment 资源
value + 术语检查结果	Condition.code，作为 CodeableConcept（{text: value, coding: [{system, code, display}]}）
span + location	Condition.note 或来源扩展

这是对经过验证的记录进行的确定性转换——无需调用模型。用户指定 FHIR 为目标时提供此选项；否则默认使用扁平记录。

先决条件

为架构中指定的所有 check.via 值配置连接器。缺少连接器不会阻止提取——这些字段会保持未验证状态，报告中也会列出它们。