OpenMed CLI 帮助面漂移检测：基于值无关签名的离线 CI 一致性保障

OpenMed CLI 帮助面漂移检测：基于值无关签名的离线 CI 一致性保障

【免费下载链接】openmedLocal-first healthcare AI: clinical NER & HIPAA PII de-identification that runs 100% on-device. 2,200+ medical models, 21 languages, Apple MLX + Python, no cloud, no patient data leaving your network. Apache-2.0项目地址: https://gitcode.com/GitHub_Trending/ope/openmed

openmed.cli.help_drift是 OpenMed（local-first 医疗 AI，核心覆盖临床 NER 与 HIPAA PII 脱敏）中一个专为离线 CI 设计的确定性检测器：它通过比较「合成命令帮助记录」（synthetic command-help records），在不执行命令、不发起任何网络请求的前提下，持续保证 CLI 生成的帮助信息与文档、脚本、机器契约保持一致。读完本文，你将掌握该检查器的完整输入格式、值无关签名的规范化原理、六类漂移语义与退出码约定，并能在自己的发布流水线中直接落地这套可复现的 CLI 帮助面基线校验。

为什么需要 CLI 帮助面漂移检测

OpenMed 的 CLI 在 openmed/cli/main.py 中构建了一个包含analyze、deid、pii、risk、models、release等大量子命令的 argparse 命令树。随着命令不断演进，帮助文本、选项别名、参数元数据很容易与文档、shell 补全脚本和自动化脚本产生静默漂移。传统做法是直接调用--help抓取输出做快照比对，但这种方式存在三个问题：

1. 执行副作用：运行命令可能触发模型加载、目录扫描或配置读取；
2. 环境依赖：输出受终端宽度、locale、模型缓存状态影响，难以确定性复现；
3. 隐私风险：帮助输出中可能混入路径、默认值等不应进入 CI 日志的信息。

openmed.cli.help_drift的解法是「值无关（value-free）」：它只消费合成记录（描述命令路径与选项形状的 JSON），规范化后仅保留"形状"，丢弃所有值，再对基线（baseline）与候选（candidate）做确定性比对。模块 docstring 明确写道：默认值、帮助文本、choices、metavars 等选项值在生成签名或报告之前就被刻意丢弃（见 openmed/cli/help_drift.py）。

输入记录：如何描述一条命令的帮助面

检查器接受三种形式的输入：一个命令记录列表、一个包含commands或records列表的对象、或单条命令记录。每条命令记录由command（命令路径）与options（选项列表）组成，示例：

[ { "command": ["reports", "inspect"], "options": [ {"flags": ["--input", "-i"], "required": true}, {"flags": ["--json"], "action": "store_true"} ] } ]

命令路径的两种写法

command可以是数组，也可以是空白分隔的字符串（源码_normalize_command_path对二者都做规范化，见 openmed/cli/help_drift.py）：

{"command": "reports inspect", "options": []}

为了兼容不同的调用方，命令路径字段还接受command_path、path、name作为别名（源码_normalize_command按command→command_path→path→name顺序取值）。路径中的每个名称必须非空且不含空白字符，否则抛出HelpDriftError。

选项记录的完整字段

选项记录支持多组字段别名：

flags中的每个标志会被strip()并按=截断（即--format=json被规范化为--format），且必须满足：长度不小于 2、以-开头、不是--、不含空白或控制字符。选项也可以简写成纯字符串形式：

{"command": "models list", "options": ["--remote", "--json"]}

甚至可以把options写成一个映射，映射的键即标志：

{ "command": "models list", "options": { "--remote": {"action": "store_true"}, "--format": {"nargs": "?"} } }

nargs 与 arity 的规范化

nargs支持整数、字符串与特殊符号，最终统一收敛到六种规范 arity（源码_normalize_arity/_canonical_arity，见 openmed/cli/help_drift.py）：

当nargs缺省时，依据action与takes_value推断：store_true、store_false、count或takes_value: false归为none，其余默认one。repeatable缺省时也会从action推断：append、extend、count视为可重复。显式布尔字段required、repeatable若非布尔类型会直接报错。

值无关签名（HelpSurfaceSignature）

normalize_help_records()是核心入口，返回不可变的HelpSurfaceSignature。它的规范表示（canonical representation）只包含排序后的命令路径与选项形状：

• 选项标志与别名（排序后）；
• 选项是否必填（required）；
• 值的 arity（none、one、optional、zero_or_more、one_or_more、fixed:N）；
• 选项是否可重复（repeatable）。

默认值、choices、帮助文本、metavars、destinations 以及所有运行时值都被丢弃。这一设计由三层冻结数据类承载（openmed/cli/help_drift.py）：

• OptionSignature：flags、required、arity、repeatable；identifier属性返回稳定比较键（优先第一个--长标志，否则第一个短标志）；
• CommandSignature：命令路径 + 排序后的选项集合；__post_init__会检测重复选项别名并报错；
• HelpSurfaceSignature：命令集合 + 固定的schema_version（"openmed.cli.help_drift.v1"），命令按路径排序，重复命令记录直接拒绝。

规范化对输入顺序不敏感：test_normalization_is_order_independent_and_value_free用反转的 options、字符串形式的 command 与不同的 description 构造第二份输入，断言两份签名相等且 SHA-256 digest 一致（见 tests/unit/cli/test_help_drift.py）。digest 由to_json的紧凑形式（sort_keys=True、无多余空白）计算 SHA-256 得到，因此同一帮助面在任何机器上产生同一摘要。

from openmed.cli.help_drift import normalize_help_records, surface_digest records = [ {"command": ["reports", "inspect"], "options": [ {"flags": ["--input", "-i"], "required": True, "default": "secret-default"}, {"flags": ["--json"], "action": "store_true"}, ]} ] signature = normalize_help_records(records) # -> HelpSurfaceSignature print(signature.to_json()) # 仅含形状字段，无任何值 print(signature.digest) # 确定性 SHA-256 print(surface_digest(records)) # 便捷别名，结果相同

签名 JSON 中绝不会出现输入值：测试断言"discarded-value"与"discarded-choice"不在to_json()输出中。无效输入统一抛出HelpDriftError（ValueError子类），且异常消息只包含结构上下文，绝不回显输入值——test_invalid_shape_does_not_echo_input_values明确验证了默认值synthetic-sensitive-placeholder不会泄漏进异常文本（tests/unit/cli/test_help_drift.py）。这与 OpenMed 全项目"错误消息不回显输入/路径/异常"的隐私纪律一脉相承，可参见 docs/cli/machine-contract.md 中的机器契约约定。

漂移分类与退出码

compare_help_surfaces(baseline, candidate)返回HelpDriftReport，其中包含排序后的added、removed、changed三组OptionChange，以及空命令的新增/删除（added_commands/removed_commands）——后者无法用选项变化表示，因此单独记录。

选项身份（identity）优先取长标志：为已有选项添加或删除别名，被视为同一个选项的形状变化（changed）；重命名标志则是一次新增加一次删除。测试test_alias_addition_is_one_changed_option验证了：基线--format -f变成候选--encoding --format -f时，只产生一个changed，且标识为--format。

分类逻辑（_classify）先统计三个布尔位，再合并：

注意退出码 0–4 覆盖漂移语义，退出码 5 独立表示输入无效，与漂移无关（常量定义见 openmed/cli/help_drift.py）。HelpDriftReport还提供了便捷属性：is_clean（无漂移）、has_drift（存在任意漂移）、exit_category（与category等价），以及added_options/removed_options/changed_options三个显式别名。

报告 JSON 的内容

report.to_json()只包含规范化后的标志、命令路径、形状元数据、类别计数与表面摘要，绝不包含被丢弃的值：

{ "schema_version": "openmed.cli.help_drift.v1", "category": "added", "exit_category": "added", "exit_code": 1, "baseline_digest": "<sha256>", "candidate_digest": "<sha256>", "added_commands": [], "removed_commands": [], "added": [ { "command": ["reports", "inspect"], "option": "--json", "category": "added", "before": null, "after": {"flags": ["--json"], "required": false, "arity": "none", "repeatable": false} } ], "removed": [], "changed": [] }

OptionChange的before/after字段在新增时为null、在删除时为null，由此category属性可确定性推导类别（见 openmed/cli/help_drift.py）。

选项匹配算法

对同时存在于两侧的命令，源码用共享标志建立一对一双向匹配（baseline_links/candidate_links）：仅当某个基线选项与某个候选选项通过共享标志唯一互配时才视为同一选项；未匹配的候选记为added、未匹配的基线记为removed、匹配但形状不等（before != after）记为changed（见 openmed/cli/help_drift.py）。全部输出集合按命令路径与选项键排序，保证报告字节级可复现。

本地 JSON CLI：离线比较两个文件

模块自带一个不依赖任何远程服务的命令行入口，参数由build_argument_parser()定义（baseline、candidate两个位置参数 +--format {json,text}，默认json）：

# 默认输出确定性 JSON 报告，退出码即漂移类别 python -m openmed.cli.help_drift baseline.json candidate.json # 输出人类可读的文本报告 python -m openmed.cli.help_drift baseline.json candidate.json --format text

文本格式包含类别、退出码、三类计数，以及逐条的命令与选项变更：

category: added exit_code: 1 added: 1 removed: 0 changed: 0 added command: reports inspect added option: reports inspect --json

执行流程（main()，见 openmed/cli/help_drift.py）：

1. 分别用_load_json读取两个 JSON 文件（读取失败统一转为HelpDriftError）；
2. 调用compare_help_surfaces生成报告；
3. 捕获HelpDriftError时向 stderr 打印help surface input is invalid并返回退出码 5；
4. 按--format输出 JSON 或文本报告，返回report.exit_code。

整个过程不涉及凭据、远程服务或强制网络调用。把进程退出码接入 CI 门禁即可：例如exit_code != 0视为帮助面漂移告警、exit_code == 5视为输入格式错误。测试test_json_cli_is_local_and_returns_category_code验证了 CLI 返回EXIT_ADDED且报告中的added[0].option == "--json"、输出中不含被丢弃的值；test_json_cli_reports_invalid_input_without_raw_error验证了无效输入走退出码 5 且 stdout 为空（tests/unit/cli/test_help_drift.py）。

源码级纵深：模块设计与可编程 API

整个模块只有标准库依赖（argparse、hashlib、json、dataclasses、enum等），与 OpenMed"离线、可复现、零副作用"的 CLI 哲学完全一致。除了模块级函数，源码还暴露了便于 CI 集成与脚本调用的完整 API：

几个值得注意的实现细节：

• 确定性排序：标志按(casefold, 原值)稳定排序（_stable_text），命令按路径排序、选项按(identifier, flags)排序，因此输入书写顺序不影响任何输出；
• 重复检测：命令路径重复、同一命令内选项标识重复、选项别名跨选项重复都会被拒绝（duplicate command record/duplicate option in command record/duplicate option alias in command record），从源头消除歧义比对；
• schema 版本门禁：HelpSurfaceSignature构造时校验schema_version，未来格式演进不会静默破坏既有基线；
• 宽容的容器形态：_record_sequence允许顶层是列表、含commands/records键的对象、或单条记录对象，字符串/字节输入会被明确拒绝（"must be a sequence"）。

可编程用法示例：

from openmed.cli.help_drift import compare_help_surfaces, DriftCategory baseline = [ {"command": "reports inspect", "options": [ {"flags": ["--input", "-i"], "required": True}, {"flags": ["--json"], "action": "store_true"}, ]} ] candidate = [ {"command": "reports inspect", "options": [ {"flags": ["--input", "-i", "--in"], "required": True}, # 别名变更 ]} ] report = compare_help_surfaces(baseline, candidate) print(report.category.value) # changed print(report.exit_code) # 3 print(report.is_clean) # False print(report.changed[0].option) # --input（长标志优先）

用测试验证行为契约

tests/unit/cli/test_help_drift.py是行为契约的权威证据，覆盖了前面提到的全部关键路径：顺序无关且值无关的规范化、四类确定性退出码、混合漂移的排序输出、干净表面的零退出码、别名变更的合并语义、重复别名拒绝、显式单值 arity 与默认一致、异常不回显输入值、CLI 本地执行与无效输入处理。可以在任意离线环境中运行：

python -m pytest tests/unit/cli/test_help_drift.py -q

此外，docs/cli/machine-contract.md 展示了 OpenMed CLI 更广义的机器可读契约（--json输出、稳定错误码、退出码 0/1/2 语义），帮助面漂移检测与这套契约是互补关系：前者保证"命令长什么样"不漂移，后者保证"命令行为与错误语义"不漂移。该模块在 mkdocs.yml 中被编排为 "CLI Help-Surface Drift" 文档，在 CHANGELOG.md 中记录为"确定性 CLI 帮助面漂移检查器，带规范命令/选项签名"，并被 docs/brand/system/publication.yml 纳入发布物料清单——这些配置本身即可作为 CI 编排的落点。

边界情况与常见误区

• nargs: 1与缺省等价：_fixed_arity(1)返回one，因此--format与--format+nargs: 1的签名完全相同（测试test_explicit_single_arity_matches_the_default）；
• store_true是nonearity：布尔开关不取值，写nargs反而会改变形状；
• 别名的归属：添加/删除别名是changed而非added+removed；只有换长标志名才是新增加删除；
• 空 options 合法："options": []是合法记录，它表示"该命令没有选项"，删除全部选项会触发removed类别（注意同一命令下被移除的每个选项都会各记一条）；
• 纯装饰字段无影响：description、help、default、choices、metavar、dest等字段在规范化时被完全忽略——这正是"值无关"的含义，也意味着你不必为比对结果清洗这些字段；
• 无效输入 ≠ 漂移：输入解析失败（坏 JSON、非法标志语法、非法 arity、重复记录）统一走退出码 5，与漂移类别 0–4 严格分离。

结语

OpenMed 的openmed.cli.help_drift为 CLI 帮助面提供了一套轻量、确定性、隐私安全的离线检查方案：合成记录 + 值无关签名 + SHA-256 摘要 + 六档退出码。它既可作为python -m openmed.cli.help_drift baseline.json candidate.json直接用于发布门禁，也可通过normalize_help_records、compare_help_surfaces等 API 嵌入自定义工具链。对任何以"文档、脚本与命令行为长期一致"为目标的 CLI 项目，这套"只比对形状、绝不触碰值"的设计都是可直接借鉴的工程范式。

【免费下载链接】openmedLocal-first healthcare AI: clinical NER & HIPAA PII de-identification that runs 100% on-device. 2,200+ medical models, 21 languages, Apple MLX + Python, no cloud, no patient data leaving your network. Apache-2.0项目地址: https://gitcode.com/GitHub_Trending/ope/openmed