dsh-macos-signfix · macOS 代码签名修复插件
修复 DSH 内置 Python 在 macOS Hardened Runtime 下拒绝加载原生扩展（onnxruntime / cv2 / pypdfium2）的问题。agent 工具 doc_ocr_sign_fix 提供 diagnose / sign / verify / auto 四种模式。
一、根因（一句话）
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 因此拒绝加载。
不是 Gatekeeper / quarantine 问题，xattr -cr 不解决。
实际报错（dsh-ocr/test/macos-sign-report.txt 有完整记录）：
ImportError: dlopen(.../onnxruntime/capi/onnxruntime_pybind11_state.so, 0x0002):
... not valid for use in process:
mapping process and mapped file (non-platform) have different Team IDs
二、修复（方案 A）
对解释器注入 com.apple.security.cs.disable-library-validation entitlement 并 ad-hoc 重签：
codesign --force --options runtime \
--entitlements sign/disable-library-validation.entitlements \
--sign - ~/.dsh/dsh-runtimes/dsh-primary-runtime/dependencies/python/bin/python3
--options runtime 保留 Hardened Runtime（不破坏运行时语义），通过 entitlement 关闭 Library Validation；- 原二进制与
codesign -dvvv 输出备份到 sign/backup/<timestamp>/；
- 幂等：已修复且 import 正常时
sign/auto 为 no-op；
- 不碰 Electron 外层 App（绝不
--deep 签 .app）。
三、工具：doc_ocr_sign_fix
| 参数 | 说明 |
|---|
pythonPath | 要修复的解释器；默认 DSH 内置 primary-runtime/bin/python3 |
mode | diagnose / sign / verify / auto（默认） |
force | 已修复也强制重签（默认 false，幂等） |
deep | verify 时额外实例化 RapidOCR 跑一次最小推理 |
resignExtensions | 额外对 onnxruntime/cv2/pypdfium2 的 .so/.dylib 做 ad-hoc 重签（通常不需要，解释器 entitlement 已足够） |
diagnose → { signed, adhoc, runtime, teamIdentifier, entitlements, imports.ok, imports.errors, needsFix, verdict }sign → 前后签名状态 + backupDir + changedverify → shallow（import + 版本）/ deep（RapidOCR 推理）auto → diagnose → 需要则 sign → verify
四、安装与自检
dsh plugin --profile desktop add link:<plugin-dir>/dsh-macos-signfix
自检（复用内置 python，跑诊断→签名幂等→import→doc_ocr 回归）：
DSH_PY=~/.dsh/dsh-runtimes/dsh-primary-runtime/dependencies/python/bin/python3
"$DSH_PY" <plugin-dir>/dsh-macos-signfix/test/run_tests.py
五、验收命令
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
六、红线
- 不对
/Applications/DeepSeek Harness.app 本身 codesign --deep --force --sign -（破坏 Electron 外层签名 → App 崩溃）；
- 不依赖
DYLD_LIBRARY_PATH（Hardened Runtime 下 Python 会忽略）；
- Anaconda 只作为
auto 失败时的降级，不是最终方案；doc_ocr 会标注 fallback_used。
七、升级后注意事项
每次 DSH Desktop 升级/重装运行时，内置 python 可能恢复原签名 → 重跑一次 doc_ocr_sign_fix(mode="auto") 即可；doc_ocr 的 runner.js 在修复失效时会自动降级到 Anaconda，不阻塞 OCR。
