dsh-macos-signfix：DSH 内置 Python 的 macOS 签名修复

前言¶

DeepSeek Harness（DSH）Desktop 的内置 Python 在 macOS 上运行时，由于 Hardened Runtime 的限制，无法加载某些原生扩展（如 onnxruntime、cv2、pypdfium2）。这会导致文档 OCR 等功能报错，ImportError: dlopen(...): mapping process and mapped file (non-platform) have different Team IDs。

这类问题通常不是 Gatekeeper 或 quarantine 导致的，xattr -cr 也不起作用。插件 dsh-macos-signfix 提供的诊断与修复工具，通过注入 entitlement 并重新签名，让内置 Python 能正常加载原生扩展。

插件定位¶

名称：dsh-macos-signfix
维护者：zirscard
分类：admin-security
核心价值：诊断并修复 DSH 内置 Python 在 macOS Hardened Runtime 下的签名问题，使 onnxruntime、cv2、pypdfium2 等原生扩展可正常导入。

根因与修复思路¶

DSH Desktop 的内置 Python 使用 Developer ID 签名（Team NAN929V4UM），并启用 Hardened Runtime（flags=0x10000(runtime)）。
Hardened Runtime 启用 Library Validation，只接受与进程同 Team ID 的动态库。
pip wheel 安装的 .so/.dylib 是 ad-hoc 签名（无 Team ID），dyld 因此拒绝加载。

修复思路：

对解释器注入 com.apple.security.cs.disable-library-validation entitlement；
使用 ad-hoc 签名（--sign -）重签解释器，保留 Hardened Runtime（--options runtime）；
不对 Electron 外层 App 做深层签名（--deep），避免破坏 App 结构。

工具：doc_ocr_sign_fix¶

工具提供四种模式：

diagnose：诊断签名状态，返回 signed、adhoc、runtime、teamIdentifier、entitlements、imports.ok、imports.errors、needsFix、verdict；
sign：执行签名修复，返回前后签名状态、backupDir、changed；
verify：验证签名与导入，可选 shallow（import + 版本）或 deep（实例化 RapidOCR 跑一次推理）；
auto：diagnose → 需要则 sign → verify。

参数：

pythonPath：要修复的解释器，默认 ~/.dsh/dsh-runtimes/dsh-primary-runtime/dependencies/python/bin/python3；
mode：diagnose / sign / verify / auto（默认）；
force：已修复也强制重签，默认 false（幂等）；
deep：verify 时额外实例化 RapidOCR 跑一次最小推理；
resignExtensions：额外对 onnxruntime/cv2/pypdfium2 的 .so/.dylib 做 ad-hoc 重签（通常不需要，解释器 entitlement 已足够）。

安装与启用¶

使用插件目录的链接安装：

dsh plugin --profile desktop add link:<plugin-dir>/dsh-macos-signfix

安装后，doc_ocr_sign_fix 工具会自动可用。

典型用法¶

1. 诊断当前状态¶

DSH_PY=~/.dsh/dsh-runtimes/dsh-primary-runtime/dependencies/python/bin/python3
"$DSH_PY" <plugin-dir>/dsh-macos-signfix/test/run_tests.py --mode diagnose

查看诊断输出，确认 needsFix 和 imports.errors。

2. 执行修复¶

"$DSH_PY" <plugin-dir>/dsh-macos-signfix/test/run_tests.py --mode sign

3. 验证修复¶

"$DSH_PY" <plugin-dir>/dsh-macos-signfix/test/run_tests.py --mode verify

4. 自动诊断 + 修复 + 验证¶

"$DSH_PY" <plugin-dir>/dsh-macos-signfix/test/run_tests.py --mode auto

验证命令¶

DSH_PY=~/.dsh/dsh-runtimes/dsh-primary-runtime/dependencies/python/bin/python3
codesign -dvvv --entitlements - "$DSH_PY" | grep disable-library   # 有 → OK
"$DSH_PY" -c "import onnxruntime, cv2, pypdfium2; print('OK')"       # 退出码 0

适用场景与注意¶

适合在 macOS 上使用 DSH Desktop，遇到 onnxruntime、cv2、pypdfium2 导入报错的场景；
插件以当前 dsh 进程权限运行，安装前建议检查源码与许可证（MIT）；
每次 DSH Desktop 升级或重装运行时，内置 Python 可能恢复原签名，需重新运行 doc_ocr_sign_fix(mode="auto")；
doc_ocr 的 runner.js 在修复失效时会自动降级到 Anaconda，不阻塞 OCR；
Anaconda 仅作为降级方案，不是最终修复路径；
不依赖 DYLD_LIBRARY_PATH，Hardened Runtime 下 Python 会忽略该环境变量。

总结¶

dsh-macos-signfix 解决了 DSH 内置 Python 在 macOS Hardened Runtime 下的签名问题，通过 entitlement 注入与 ad-hoc 重签，让原生扩展能正常加载。工具提供 diagnose、sign、verify、auto 四种模式，支持幂等修复与验证，不影响 Electron 外层 App 的签名。

目录页：https://www.skillhub.cn/plugins/zirscard/dsh-macos-signfix
GitHub：https://github.com/zirscard/dsh-macos-signfix