OpenMed 维护者指南PR 合入流程、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/openmedOpenMed 是一个面向本地优先on-device医疗 AI 的开源项目其核心能力是临床 NER 与 HIPAA PII 去标识化。由于项目处理的每一段文本都可能包含受保护的健康信息PHI其维护与代码合入流程围绕质量门禁与隐私零泄漏两条主线设计。本文基于仓库根目录的 MAINTAINERS.md 展开结合 CONTRIBUTING.md、Makefile 与 CI 工作流源码完整讲解 OpenMed 的维护者职责分工、Pull Request 审阅与合并规则、合并前的本地检查命令以及隐私敏感路径必须通过的专项审查帮助你理解如何让一个合入请求安全、合规地进入这个医疗去标识化代码库。维护者角色与职责领域OpenMed 目前由一位维护者主导MAINTAINERS.md 中明确列出了其职责领域ownership areas维护者GitHub职责领域Maziyar Panahimaziyarpanahi项目领导隐私与去标识化模型注册表与发布工程文档、品牌与网站社区与行为准则执行从这份职责表可以看出OpenMed 的维护者职责并不只停留在合并代码层面而是横跨四个相互关联的治理面技术面隐私与去标识化对应openmed/core、openmed/risk、openmed/clinical等核心模块、模型注册表与发布工程对应根目录 models.jsonl 与gates/目录下的门禁状态文件工程基建面文档、品牌与网站对应 docs/ 目录与 mkdocs.yml社区治理面社区维护与行为准则执行对应 CODE_OF_CONDUCT.md。这种技术 基建 社区三位一体的维护结构意味着 OpenMed 的合入评审不仅是代码正确性评审还包含隐私合规、发布可追溯性与社区规范三重约束。Pull Request 审阅与合并流程MAINTAINERS.md 的 Review and merge process 一节定义了 PR 合入的五条核心规则这是所有贡献者提交代码前必须理解的行为契约1. PR 必须遵循贡献指南与模板Pull Request 需要遵循 贡献指南 与 Pull Request 模板并且应当链接一个已被接受的 issue除非维护者已直接确认了改动范围。查看 .github/PULL_REQUEST_TEMPLATE.md 可以看到模板要求提交者逐项勾选改动类型Bug 修复 / 新特性 / 破坏性变更 / 文档更新 / 重构 / 性能优化 / 测试补充、是否新增测试、是否更新了文档与CHANGELOG.md、是否运行过make format、make lint、make format-check以及 Swift 代码的make format-swift/make lint-swift。此外 CONTRIBUTING.md 还给出了分支命名规范type/issue-number-short-kebab-slug其中type可取feat、fix、docs、test、chore、refactor等例如docs/issue-280-maintainers。提交信息需使用fix:、feat:、docs:等简洁前缀并同步更新CHANGELOG.md与相关文档。2. CI 必须全部通过后才能合并合并的前提是 CI 全部绿灯包括lint、format、测试与范围门禁scoped gates。原文档给出了维护者执行这三个门禁的明确命令make lint make format-check .venv/bin/python -m pytest tests/ -q对照根目录 Makefile 可以看到这些目标的真实实现——它们全部运行在由uv sync --frozen --extra dev创建的锁定开发环境中make lint执行uv run --frozen --extra dev ruff check .即用 Ruff 对整个仓库做 lint 检查make format-check执行uv run --frozen --extra dev ruff format --check .只检查格式、不修改文件与 CI 行为完全对齐make type-check执行uv run --frozen --extra dev mypy对标注了类型的公开模块做类型检查。CONTRIBUTING.md 特别强调Ruff 是 Python lint、import 排序与格式化的唯一事实来源仓库明确禁止运行 Black、isort、flake8 等其他格式化器Swift 代码swift/OpenMedKit下则使用 Appleswift-format通过make format-swift与make lint-swift两个目标执行见 scripts/format_swift.sh 与 scripts/lint_swift.sh。3. 维护者可向贡献者分支补充提交当一个改动需要补充测试、加固或解决冲突时维护者可以向贡献者的分支添加聚焦的后续提交focused follow-up commits。PR 最终以squash-merge方式合入因此贡献者的署名author credit会被保留在压缩后的单个提交中不会因为维护者的补充提交而丢失。4. PR 保持单一主题拒绝无关格式改动每个 PR 必须聚焦于一个功能或修复无关的格式调整formatting churn不允许混入合并。这与 CONTRIBUTING.md 中避免与功能无关的格式改动的要求一致也保证了 git 历史可审查、可回滚。5. 发布由标签驱动版本发布通过打 tagvX.Y.Z触发完整流程见 docs/contributing.md 的 Release outline 章节详见本文第五节。合并前的本地检查维护者的质量门禁速查对于贡献者来说提交 PR 前需要运行完整的本地检查链。汇总 MAINTAINERS.md、CONTRIBUTING.md 与 docs/contributing.md标准流程如下# 1. 创建锁定开发环境uv 是规范环境pip 是备选回退 uv sync --frozen --extra dev # 2. 安装提交前钩子自动格式化暂存文件 Gitleaks 密钥扫描 uv run --frozen --extra dev pre-commit install # 3. 运行完整测试套件 uv run --frozen --extra dev pytest tests/ -q # 4. 格式化、lint、类型检查与格式校验CI 完全对等 make format make lint make type-check make format-check若环境没有 uvCONTRIBUTING.md 提供了标准的 pip 回退方案python3 -m venv .venv .venv/bin/python -m pip install --upgrade pip .venv/bin/python -m pip install -e .[dev] .venv/bin/pre-commit install在 .github/workflows/ci.yml 中可以看到 CI 端的完整门禁矩阵维护者评审时可以直接对照lint任务执行ruff check、ruff format --check、公开 API 向后兼容性检查scripts/release/check_public_api.py与 mypytest任务在 ubuntu/windows/macos 三平台 × Python 3.10/3.11/3.12 矩阵上运行pytest --covopenmed并在测试前先执行模型清单 schema 校验scripts.manifest.validate_manifest与 no-raw-PHI 日志守护测试此外还有securityBandit pip-audit 依赖门禁、sbom生成 CycloneDX SBOM、spaCy/YASBD 集成测试、浏览器扩展测试、CJK/Indic 国际化测试等独立 job。隐私敏感路径的专项审查OpenMed 合入评审的核心差异点与普通开源项目不同OpenMed 的合入评审对隐私敏感路径施加了额外的、强制性的审查标准。MAINTAINERS.md 原文明确列出涉及PII 提取、去标识化、日志、服务请求处理PII extraction, de-identification, logging, service request handling的改动必须对以下三项指标做重点审查直接标识符召回率direct-identifier recall直接标识符姓名、身份证号、病历号等是否全部被识别关键泄漏critical leakage是否存在被去标识化后仍然存活的关键标识符跨度完整性span integrity识别出的实体跨度是否精确、不偏移。这套审查遵循仓库的no-raw-PHI 规则。其落地细节记录在 docs/security/no-raw-phi-logging.md核心原则是日志只是运维遥测绝不能包含任何原始 PHI。具体而言允许写入日志的内容计数、时长、阈值、模型标识符、后端名、状态迁移跨度元数据标签、起始/结束偏移、置信度分桶、有效性标志已存在的预计算text_hash异常类名与高层失败类别。禁止写入日志的内容输入文档原文、清洗后的文本、截断片段、提示词、句子实体文本、原始 PII 值、脱敏前到脱敏后的映射可能包含用户输入的异常消息由患者/病历/就诊数据推导出的文件路径或条目标识符。工程上要求优先使用结构化字段而非格式化文本日志中只保留长度、计数、标签、偏移量与安全标识符。任何改动触及 PII、去标识化、文本处理或批处理路径时必须运行专项守护测试.venv/bin/python -m pytest tests/unit/test_no_raw_text_logging.py -q该测试在 .github/workflows/ci.yml 中被单独命名为 Trust-CI no-raw-PHI logging guard 并在多个 job 中重复执行是 OpenMed CI 中唯一一个信任优先的强制守卫。对应地tests/unit/ 下还存在tests/unit/security/test_redactor_leakage_bypass.py这样的泄漏绕过回归测试由 SECURITY.md 引用用于固化已缓解的泄漏滥用场景。对于安全研究人员与贡献者还需要注意任何脱敏绕过redaction bypass或 PHI/PII 泄漏都被视为安全缺陷而不是普通 bug必须通过 SECURITY.md 中的私有披露通道GitHub Private Vulnerability Reporting报告严禁公开发 issue 或 PR并且报告中只能使用合成数据如项目自带的Faker工具绝不能附带真实患者数据——在 SECURITY.md 中泄漏真实数据的报告本身会被当作一起安全事件处理。CVSS v4.0 评级中隐私影响类缺陷的评级永远不会低于 High。标签驱动的发布流程与双轨发布流MAINTAINERS.md 的最后一条指出Releases are tag-driven其完整流程在 docs/contributing.md 的 Release outline 章节 中定义通过make bump-patch或bump-minor/bump-major提升版本号这些命令会更新openmed/__about__.py运行make build用锁定的 uv 前端产出 wheel 与 sdist确认 PyPI 可信发布 配置后推送 tagvX.Y.Z触发 .github/workflows/publish.yml打 tag 前先更新CHANGELOG.md的发布说明。从 docs/release/semver-and-channels.md 可以看到 OpenMed 采用双轨发布流流 A模型制品。模型是数据单个坏 checkpoint 只影响一个模型条目可通过把 manifest 指针回拨到最后绿色last green制品来回滚。版本用仓库后缀或制品修订号 可复现性哈希标识节奏由维护者在本地转换、评估、审查后手动触发。流 B库与 SDK。openmedwheel 是代码一个坏版本会影响所有下游安装因此严格遵循 SemVerPATCH 对应注册表/清单刷新或 bug 修复MINOR 对应新增公开 APIMAJOR 对应破坏性变更。回滚采用下一补丁前向修复策略。模型发布由 .github/workflows/release-gates.yml 驱动该工作流只在显式模型候选 dispatch 或元数据回滚 dispatch 时运行没有任何 schedule也从不发布模型制品。它要求候选必须通过 golden 与 SHIELD 公开基准、中文/印度语吞吐门禁、grounding 精度门禁、公开 SHIELD 泄漏回归门禁与gates/baseline.json中的 last green 对比超出RESIDUAL_LEAKAGE_SOFT_CEILING即判定QUARANTINED、API 迁移指南完整性检查与端到端 golden 套件全部通过后才会推进gates/rollout_state.json中的 CANARY 阶段并向models.jsonl提升 manifest 指针、重写gates/baseline.json。这解释了 MAINTAINERS.md 中release process之所以被单列引用一个 OpenMed 发布不是推个版本号那么简单而是一条由评估证据链驱动的、可复现、可回滚的自动化流水线。维护者评审实操清单将以上内容收敛为维护者以及希望提高合入通过率的贡献者在评审/提交时可以直接对照的清单范围PR 是否链接已接受 issue、聚焦单一主题、无无关格式改动门禁make lint、make format-check、pytest tests/ -q是否全部通过Swift 改动是否通过make lint-swift/make format-swift隐私改动是否触及 PII / 去标识化 / 日志 / 服务路径若是是否新增了直接标识符召回率、关键泄漏、跨度完整性测试是否运行了pytest tests/unit/test_no_raw_text_logging.py文档是否更新了CHANGELOG.md、公开 API docstring对应scripts/check_public_api_docstrings.py与tests/unit/test_public_api_docstrings.py的 100% 覆盖率要求及迁移指南发布涉及模型指针canary/latest/last_green变更的库发布是否先完成了带真实 golden 与 SHIELD 证据的模型门禁遵循这套流程既是对维护者治理规则的尊重也是让一个面向医疗 PHI 的开源项目持续保持代码可合入、数据不泄漏、发布可追溯三重底线的基本前提。如需进一步深入建议继续阅读 CONTRIBUTING.md、docs/contributing.md 与 SECURITY.md。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
