[dsh-settings] settingsNamespace export removed in 0.1.2-alpha.x without migration cue — misleading 'does not provide an export' crash

[GiantAxeint]

现象（真实事故，2026-09-06）

@deepseek-ai/dsh-settings 的 settingsNamespace 导出在 0.1.2-alpha.3 被移除（改为 SettingsProvider 等）。旧 API 消费者（如 @morlay/session-rdb@0.0.11，peer 声明 ^0.1.1-rc.2）在解析到新版时启动即崩：

failed to import loader entry xxx: ... does not provide an export named 'settingsNamespace' (imported by .../@morlay/session-rdb/lib/index.mjs)

为什么特别难排查

• 报错像「缺包/装错包」，实为版本漂移：profile 本地实体缺失后，Node 沿目录向上爬升命中全局 CLI 内置的 dsh-settings@0.1.2-alpha.3（而非声明兼容的 0.1.1-rc.2）；
• 版本号看似满足 peer 区间（同大版本段内 prerelease 被 npm 区间规则排除前，肉眼无法分辨），破坏性变更没有任何迁移提示。

建议

1. 破坏性移除导出时，至少保留一个 stub re-export（deprecated 包装 + console.warn 迁移提示），而不是直接消失；
2. 或在 peer/exports 层面阻断旧区间（把移除旧 API 的版本发布为需要 peer ^0.1.2-rc.1 的新段），让区间解析直接失败而非静默漂移；
3. pre-1.0 破坏性变更发布规范：CHANGELOG + BREAKING-MIGRATION 说明配套，供依赖方参考。

环境

• DSH（deepseek-harness）@deepseek-ai/dsh-settings：0.1.1-rc.2（含导出）→ 0.1.2-alpha.3（移除导出）

[rootkiller6788]

0.1.3-alpha.1（当前 master）上确认：settingsNamespace 的值导出没了，同名只剩类型 SettingsNamespace，也没有任何 deprecated 别名——所以这是真实的 API 断崖，不是缺包。它的位置现在是 ctx.settings 这个 Service：namespace 从「一个导出标识符」变成你注册/读取时传进去的普通字符串（index.ts 里用 ^[a-z][a-z0-9-]*$ 校验）。@morlay/session-rdb 要么把 import 迁到新模型，要么先钉回还带该导出的 0.1.1-rc.2。

想确认到底跑的是哪份，在插件目录执行一句即可：

node -e "console.log(import.meta.resolve('@deepseek-ai/dsh-settings'))"

打印出的绝对路径会立刻说明是不是沿目录爬上了 CLI 内置那份。你的「本地实体缺失后向上爬」判断在 DSH 插件模型里基本是常态：插件跑在宿主进程内，import 走的是宿主的模块图，不服从插件自己 package.json 写的区间。还有个细节佐证这确实是漂移而非正常解析——^0.1.1-rc.2 在严格 semver 下其实不匹配 0.1.2-alpha.3（0.x caret 只收同一 [major,minor,patch] 行上的 prerelease），它既然还是被跑到了，说明那份副本根本不是经这个区间进来的。所以建议 2 只对「解析器真按区间放依赖」的场景有效，拦不住宿主内置副本这种运行时命中；要更快让旧区间失效，得靠 pinned overrides 或发一个显式不满足旧区间的版本。

三个建议我基本都认，只是排序不同：stub re-export + console.warn 是最便宜的止血，有真实消费者时尤其该做——把「启动即崩」降级成一条带替换指引的 warn，最好连替换一并给出（这次其实就是换成 ctx.settings 的注册），下游当场能改完；而真正能提前拦住这种断崖的是导出面快照——一条断言 public exports 的用例或 API extractor 结果入库，CI 在移除那一刻就红，而不是等用户某天启动才红。CHANGELOG/BREAKING（建议 3）当然该写，但对 import 期报错救不了急，导出面测试才是兜底。

需要的话我可以把 0.1.1-rc.2 → 0.1.2-alpha.3 之间 dsh-settings 的导出差异整理成一份迁移清单。