fhir-ig-analysis

测量 FHIR 实施指南

客观测量 FHIR IG，并报告统计内容。**严格只读：**绝不构建、修改或发布任何内容，也不进行预测。

前提条件

发现上下文；不要假设上下文，也绝不要创建上下文。

1. 工具。 必须能够运行 python3。分析器仅使用标准库，无需安装任何内容。如果没有 python3，请说明并停止；不要获取解释器。

2. 对象。 一个或多个 IG，每个都以本地路径、git URL 或软件包 .tgz 的形式提供。run 会自行解析每个对象（URL 使用浅克隆，软件包则下载）。除了工具读取的内容外，无需在仓库内发现其他内容。

   • 如果某个本地路径既没有 sushi-config.yaml，也没有 input/，则它不是 IG 项目。请报告这一点并停止。
   • git URL 需要网络访问；如果克隆失败，请报告失败情况，而不是报告空测量结果。

3. 默认采用静态分析，并了解其代价。 不进行构建时，分析为静态分析：sushi-config/软件包元数据、FSH 计数、叙述文本、指令、依赖项、语言特征、重复内容、卫生检查。构建得出的指标（qa.json：错误、警告、损坏的链接、验证结果）保持为 null，并在目录中标记为 Build。软件包 .tgz 会进一步缩减分析范围——仅分析生成的资源。

报告数字时，说明这些数字来自哪种模式。null 不等于零。

流程

生成的报告为德语；本技能的说明为英语。这是有意为之，并非由其中任一事实自然导致的——报告正文是沿用下来的，尚未翻译。请勿悄悄“修正”这一点，也不要翻译数字。

先解析脚本路径。 以下命令中，工具路径相对于本技能所在目录，而非你的工作目录（也就是你正在操作的项目）。将 SKILL_DIR 设为包含此 SKILL.md 的目录（你刚读过它，所以知道它在哪里），并在每次调用时使用它：

SKILL_DIR=<the directory containing this SKILL.md>   # e.g. .claude/skills/fhir-ig-analysis

在项目根目录直接运行 scripts/... 不只是会失败——如果项目恰好有自己的 scripts/ 目录，且其中有同名文件，它会悄悄运行那个文件。

1. 测量。 可测量一个或多个 IG，从 IG 根目录或任意位置运行：

   python3 "$SKILL_DIR/scripts/ig-stats.py" run <input…> [-o OUTDIR] [--label a,b]
   

   输入两个或更多 IG 时，会自动为每个 IG 写入一份报告，并且生成 compare-report.md。 --label 用于设置显示标签（报告标题、比较列），每个输入对应一个；输出文件名始终根据 IG id 生成。

   输入解析方式会带来两个后果，请据此正确解读数字：Git URL 会进行浅克隆，因此 Git 历史指标（bus factor、维护节奏）会报告为无法推导（git.history_complete: false，值为 null）——需要这些指标时，请测量完整的本地克隆。另一个后果是，该工具会报告已计数的成熟度组成项，但不提供汇总分数：0–100 的“就绪度”数字属于预测，本技能有意不提供此类预测。

2. 高级用户入口，需要分别运行各个阶段时使用：

   python3 "$SKILL_DIR/scripts/ig-stats.py" analyze <ig-dir> [-o stats.json]
   python3 "$SKILL_DIR/scripts/ig-stats.py" report  <stats.json>  [-o report.md]
   python3 "$SKILL_DIR/scripts/ig-stats.py" compare <stats.json…> [-o compare.md]
   

3. 仔细阅读必需页面检查结果。 工具用于检查的页面集合位于 references/report-content.json 的 mandatory_pages 下，有意设为可手动编辑。其中预置了 MII KDS 模块模板中实际使用的页面名称。

   如果测量的 IG 合理地使用了不同的页面集合，请修正列表，而不是将其页面报告为缺失——并在报告中说明使用了哪个列表。页面完整度指标的质量取决于它所比较的页面集合。

4. 同时提供两种产物。 JSON 是持久记录：它采用固定架构，因此多次运行之间可以清晰地进行差异比较，并展示模块在各版本之间的增长情况。Markdown 面向读者。

5. 仅比较标准化指标。 不同规模 IG 之间的绝对数量几乎没有意义；比较报告会汇总范围的 Σ 总计，但用于公平比较的是标准化指标列。

6. 自动验证同一模块。 当所有参与比较的输入都带有相同的 packageId 时，这些输入表示同一模块的不同状态（通常是平台源与迁移后的副本），报告会切换到同一模块验证：身份字段相等性、已发布产物集合相等性（内部 FSH 结构会单独报告——采用模板会合理地增加脚手架规则集）、规范 URL 相等性（如果两个输入都有 fsh-generated，则从中读取），以及按语言层级编写的说明（默认／翻译／保留的平台页面），并附带词数覆盖率指标。Σ 列将被移除（对单个模块没有意义）。所有判定均为计数结果，不作预测。顺序很重要：第一个输入是参照项。

预检事项（迁移 Gate 0）

从 v0.17.0 起，每项测量都会包含一个 preflight 部分，其中列出决定迁移的事项，仅根据资源树进行离线测量：

• 许可证证据，分层呈现 — 所有声明许可证的位置 （sushi-config/package.json、LICENSE 文件、叙述性版权声明）， 并将缺失和矛盾作为一等发现。
• 规范空间清查 — url 位于 IG 规范地址之外的资源，以及其中 id↔url 不匹配的资源：两者合起来就是 special_url_prediction，也就是发布者迁移时需要的 special-url 列表；example.org 规范地址会单独列出。sushi-config 与 package.json 规范地址不一致时，会报告为 config_contradiction（实测：PRO 的 package.json 中包含 modul-dok 规范地址）。
• 依赖项固定状态 — 旧式／虚拟包、THO/Extensions-Pack 是否直接固定（若缺失 → IG Publisher 会在构建时注入最新版本），以及外部父级规范地址。解析器会读取 SUSHI 的两种依赖项格式（扁平格式和嵌套的 id/version 子键）；dependency_block_unparsed: true 表示依赖项区块存在但未解析出任何条目——这是解析器发现的问题，绝不表示源中没有依赖项。
• 包布局 — 对于分发包：是否存在 .index.json（若缺失 → 基于索引的预言检查无法运行）以及嵌套资源目录（扁平 glob 会漏掉这些目录；此处的清查采用递归方式）。
• 叙述性内容来源 — 哪些树目录包含文本内容（pagecontent、intro-notes、implementation-guides/）；dual_source: true 加上各树目录的最后提交日期，可让权威副本的判定基于测量结果，而非排名默认值。
• QA 基线 — 树中是否存在已渲染的 qa.json。None 表示：获取它（构建未迁移的源，或获取其已渲染的 qa）——绝不可自行假设。

这些事项背后有三条清查诚信规则：基础规范类型的实例（ConceptMap、Measure、ObservationDefinition 等）会计入开放的 artifacts.other 类别，而不会被归入“示例”；如果 FSH 声明和生成的资源同时存在，就会交叉核对计数，并报告每一处不匹配（generated_crosscheck——页面决策以生成资源的 resourceType 清查结果为准）；如果仓库的 SUSHI 项目嵌套在根目录以下（例如 strukturdaten 的 Resources/），则会重新设置根目录并在首页发出警告，而不会在未发现问题的情况下产出空身份信息。

None 值表示此工具无法仅根据树目录测量的内容——使用者应从其他地方获取，绝不可自行假设（“null 不等于零”规则）。mii-ig-migration 技能会对未迁移的源运行此测量，作为必需的 Gate 0 预检。

验证

python3 "$SKILL_DIR/scripts/ig-stats.py" run <ig-dir> -o /tmp/igstats
python3 -c "import json;d=json.load(open('/tmp/igstats/<name>-stats.json'));print(d['mode'],d['schemaVersion'])"

• 运行以 0 退出，并为每个输入写入一个 *-stats.json 和一个 *-report.md。
• 输入不少于 2 个时，存在 compare-report.md。
• JSON 中的 mode 与你声明的模式（static / reduced）一致，并且存在 schemaVersion。
• 你引用的每项指标要么是计数值，要么是 null——绝不能是估算值。如果某个字段为 null，应报告为无法通过静态方式推导，而不是报告为零。
• 必需页面的结果与所测量的 IG 相符。全部缺失通常意味着页面集有误，而非 IG 已损坏。
• 在同模块比较中，Befund 区块会按事项说明 IDENTISCH/DIVERGIERT——只有身份信息、已发布资源集和规范 URL 均为 IDENTISCH 时，迁移才忠实；迁移技能的完成定义对此有明确要求。

范围与界定

涵盖测量与比较：IG 包含什么、内容有多整洁、与其他 IG 相比如何，以及随时间如何变化。

明确不涵盖：

• 工作量预测。 工具会报告它统计的内容，但不会估算人天、成本或就绪度评分。此技能的早期版本曾将这些数字作为迁移范围界定的依据，后来已特意缩小范围。不要重新引入这类内容：把测量结果包装成预测，是此技能可能产出的最不可信的东西。
• 迁移到 MII KDS 模块模板——参见 mii-ig-migration。根据源内容验证已迁移指南也属于该技能，具体在其 scripts/verify-migration.py 中：工件的可访问性、菜单结构、内容位置、渲染后的标题元数据和工具链来源都是通过/不通过的门槛；这些门槛会读取迁移的页面映射和运行日志——这些输入并非 IG 的属性，而且会破坏此技能“一条路径、一个 URL 或一个 .tgz”的约定。下方的同模块验证是该门槛所使用的测量，不能替代它：它只能证明工件已存在，绝不能证明有任何内容链接到它。
• 翻译——参见 fhir-ig-translation。
• 针对 MII 元维基或元数据契约的规范与命名检查。这是另一种检查，模块模板为此自带技能。
• 构建或发布任何内容。 只读是安全护栏，而非默认选项。

如果此目录和本地都提供了同名技能，则以本地版本为准。

安全护栏

• 只读。 绝不修改已分析的 IG；绝不强制构建。
• 测量，而非预测。 见上文。
• 仅通过归一化指标进行公平比较。
• 不臆造。 缺少输入时返回 null，绝不猜测。启发式指标会在目录中标明，且必须如实报告。

参考资料

• references/metrics-catalog.md——参数目录（A–N 组），列出每项指标的来源和用途。可手动扩展；这是测量内容的 SSOT。
• references/ig-stats-schema.json——ig-stats.json 的架构。
• references/report-content.json——通俗易懂的文本、术语表、指令模式、指标说明和 mandatory_pages 列表。可手动编辑。
• references/triggers.md——Gate 3 提示词集。
• scripts/ig-stats.py——分析器（run / analyze / report / compare）。

来源

衍生自 medizininformatik-initiative/mii-kds-module-template 在提交 b5beedb17a66a4397d597429668c7b6d54202c62 中的 skills/ig-analyze，后者改编自 forschungsgruppe-digital-health/mii-kds-sample-ig-inoffiziell 的 ig-analyze 技能（CC-BY-4.0）。特意记录了这段渊源的两个环节。

于 2026-07-31 为此目录重新整理。除符合目录约定外，还进行了三项实质性修改：

• 分析器现在随技能一同提供。它之前位于源代码仓库的 scripts/ 中，并通过向上遍历父目录来引用，因此技能安装到其他位置后，就无法访问所指向的文件。
• scripts/ig-stats.py 现在会根据自身路径定位 references/report-content.json。此前，它会根据计算出的仓库根目录加上硬编码的 skills/ig-analyze/references/… 来构造路径，因此在此处会因两个原因失效：无法计算仓库根目录，而且技能已重命名。
• 必需页面列表从代码中移至 references/report-content.json，并进行了修正。继承而来的列表列出了十一个页面，其中六个并不存在于用于构建这些模板模块的项目中（use-cases、data-sets、uml、context、references、 security-privacy），因此每次测量都会报告六个并不存在的缺失页面。

于 2026-08-01 在该技能首次用于真实任务后修订（针对 kerndatensatz-dokument + kerndatensatz-basis 进行试运行）。修复了四项输出缺陷，方向都是“测量，而非预测”：移除了汇总的 Reifegrad／“Freigabe-Indikator”评分（现在分别报告各组成部分，不再汇总，schemaVersion 1.4）；将“Empfehlungen”表中有关迁移范围的文字改为中性的“Befunde & Einordnung”测量说明，并删除不含指标的“Arbeitsweise”行；浅克隆的 git 历史指标（包括该工具自行创建的所有克隆）现在会报告 history_complete: false 和 null，而不是虚构的“100 % top author”；并根据真实输出重新生成了已发生偏差的 references/ig-stats-schema.json（其中声明了 mandatory_missing，却从未输出该字段）。试运行结果记录在 mii-kds-dokument-ig-inoffiziell 沙盒的 docs/reports/dry-run-2026-07-31/ 中。

原始许可：CC-BY-4.0，由两个源代码仓库分别声明。scripts/ 采用 Apache-2.0，与本仓库的代码许可一致。

于 2026-08-05 晋升至 stable：反复用于真实任务，包括对四个 KDS 模块进行测量和比较，以及对同一模块的两项已完成迁移进行验证。运行期间已使用 references/triggers.md 中的触发条件。