升级链路使用反馈：upgrade_callback 的用户层保护、patch 降级策略与插件版本漂移数据

[sanluoluo]

标题：升级链路使用反馈：upgrade_callback 的用户层保护、patch 降级策略与插件版本漂移数据

背景

我们是一台长期运行的 fnOS 生产机（fnOS 1.2.x，内核 6.18.18.c1126-trim，x86_64），通过应用中心安装并跟版升级 fn-deepseek-harness（当前 target/dsh-version = 0.2.0-rc.2）。升级链路完整走过 0.1.x → 0.2.0-rc.2 多轮，期间为排查问题对 packages/fnos-gateway、apps/fn-deepseek-harness/cmd/* 做过只读分析和少量本地救场。以下是一手使用数据，供升级链路改进参考；按贡献规范先发 Discussions 而非直接开 issue/PR，如方向认可再转 issue + PR。

反馈 1：upgrade_callback 目前不保护用户层配置

现状：cmd/upgrade_callback 重放 install_callback，但 profiles/web/ 下的用户层（我们实测是 cordis.patch.yml，被 dsh-hmr inotify 热加载，是模型/插件配置的单一事实源）在升级前后没有任何校验或备份步骤。

实际影响：升级涉及 DSH 依赖树变化时，profiles/web/node_modules 里的插件会整体换版（我们跟踪到 billion-context 0.1.179→0.183、dsh-builtin-browser 0.3.1→0.4.1、dsh-mnemon 0.5.22、dsh-memory 0.7.1 连续四轮漂移）。若用户层 patch 引用的插件能力随版本变化，配置是静默失效的——没有任何日志提示。

建议：upgrade_callback 里在重放 install_callback 之前，对 ${DSH_PROFILE_DIRECTORY} 的用户层文件做一次时间戳快照 + 升级后 diff 摘要写入升级日志，成本几行 shell，但出问题时用户能自己看出来。

反馈 2：patch 失败降级，避免整包回滚

issue #8（dsh-attachment-local 缺失导致 fail_install 回滚）我们完整跟过。结合我们自己的场景补一个数据点：gateway-proxy.mjs 在我们机器上有过一次升级重放场景——升级会留下 gateway-proxy.mjs.dsh-gateway-patch.bak，说明 patch 机制已经有备份意识。

建议方向：把「探测不到 patch 点」从 fail_install 降级为 warn + skip + 在日志中记录 patch 名，让 patch 跟不上 DSH 版本时不阻塞整包升级（安全类 patch 除外）。这能消掉 #3/#4/#5/#8/#10 里一大类「升级整包回滚」的报障。

反馈 3：published-dsh-plugins.json 的 pin 与真实升级漂移

我们机器上跟踪到的插件版本漂移显示：profiles/web 的插件版本更新频率高于 published-dsh-plugins.json 的发布节奏（四轮 diff 间隔约一天一个）。pin 太紧时用户层会停留在旧版；太松时升级回滚（issue #5）会出现新旧混装。想知道维护者对 pin 策略的规划——是否考虑版本区间而不是精确 pin？

反馈 4：repo 与实际发布版本的对应关系（疑问）

仓库 cmd/install_callback 当前 pin DSH_VERSION="0.1.7-rc.2"（repo 最后提交 9-30），但我们机器 10-1 已升级到 0.2.0-rc.2。不确定是有独立发布渠道还是 repo 滞后——如果是后者，建议在 README 标注 repo 跟进发布的滞后窗口，方便外部贡献者对齐基线，避免拿着旧版本号报 issue。

环境信息

• fnOS 版本：1.2.x（x86_64，内核 6.18.18.c1126-trim）
• fn-deepseek-harness：0.2.0-rc.2（应用中心升级）
• Node：/var/apps/nodejs_v24

以上全部来自我们自有设备的运维记录，不包含其他用户数据；文中路径已按规范脱敏。

[tnnevol]

感谢详细的一手数据，三条逐一回应：

1. 用户层配置快照：用 fnOS 自带快照，应用不重复建设

快照能力直接使用飞牛系统自带的快照备份数据，应用侧暂时不做重复的快照机制。升级前的配置快照属于系统层职责，fnOS 快照已经覆盖。

2. 升级时的备份范围：只备份自有插件配置

DSH harness 目前处于 rc 阶段。每次升级会对自有插件（@tnnevol/xx 系列）做旧配置备份；三方插件不做处理——担心配置丢失的话，请参照第 1 条，在安装前或每日使用飞牛快照兜底。

3. 插件版本固定：rc 阶段必须 pin 死

rc 阶段必须固定插件版本，这是刻意为之：三方插件若跨 harness 版本浮动，会导致同一个版本的 FPK 应用在不同用户机器上解析出不同的依赖树，出现部分用户无法正常安装的情况。也就是说，你观察到的「pin 紧」不是没规划，而是 rc 阶段的发布一致性要求；等 harness 出 rc 进入稳定版后再评估是否放宽为版本区间。

再次感谢跟进数据，特别是 billion-context / dsh-builtin-browser 等四轮漂移的记录——这佐证了第 3 条在 rc 阶段收紧 pin 的必要性。

[sanluoluo]

感谢 @tnnevol 详细且坦诚的逐条解答！

生产实机运行中非常认同这两处架构权衡：大版本更新前直接打系统快照是最干净稳健的全局兜底，省去了应用层重复建设状态机的维护包袱；同时在当前 rc 快速迭代期，严格固定版本避免了隐式版本漂移带来的不可测故障，这个一致性收紧非常必要。

另外在最近几天实机维护和升级依赖的跟进中，踩到了两个比较典型的一手工程小细节，附在下方供后续打包与脚本迭代参考，无需专门回复：

---

1. minimumReleaseAgeExclude 多版本豁免需单行 || 联合

在 pnpm-workspace.yaml 中为同一个包排除新发布包的成熟期检查（minimumReleaseAge）时：

• ⚠️ 踩坑写法（同包按行分列）：

  minimumReleaseAgeExclude:
    - dsh-builtin-browser@0.4.1
    - dsh-builtin-browser@0.4.6

  实际机制：pnpm 在规则评估时采用首项命中即返回（First-Match-Wins）机制，后续同名条目会被直接短路忽略，导致后列出的版本无法享受豁免，在非交互安装中触发 NO_MATURE_MATCHING_VERSION（未成熟版本拦截）中断安装。

• ✅ 稳健写法（单行精确版本联合）：

  minimumReleaseAgeExclude:
    - dsh-builtin-browser@0.4.1 || 0.4.6

  注意细节：此处仅接受精确版本联合（Exact Versions Union），不能写 ^ 或 ~ 等 semver 范围表达式。我们在本地运维脚本中已将同名包合并为单行 ||，供后续官方安装/更新脚本若有类似规则维护时顺带参考。

---

2. 官方核心三件套的 npm dist-tags 现状与客户端显示

在排查 Web 客户端插件列表提示时顺带查了一下公网 npm registry：

• @tnnevol/dsh-fnos、@tnnevol/dsh-codebuddy、@tnnevol/dsh-codex-auth 的 latest 标签目前仍指向历史预发布版 0.1.1-rc.2.0 / 0.1.2-rc.1.2 / 0.1.0-rc.7，而适配新内核的版本 0.2.0-rc.2.0 则发布在 next 标签上。
• 部分按 npm 默认规则检查更新的客户端工具会据此判定有“版本异常 / 可更新”，普通用户在界面点击后可能会误触发向旧版的降级尝试。后续进入稳定发布阶段时如能顺带更新 dist-tags，可以避免这一小类客户端误报。

再次感谢回复与持续维护！

[tnnevol]

@sanluoluo 两个细节都收到了，非常有用，谢谢！

1. minimumReleaseAgeExclude 的 First-Match-Wins 陷阱

这条我们已经核实并立项处理了。排查中发现本地 web profile 还残留了一条历史锚定 @tnnevol/dsh-codebuddy@0.1.7-rc.2（指向已失效版本），正是你说的这类问题。已登记为 FNOS-012-03：安装/升级链路增加自愈——检测豁免条目指向失效版本（与清单版本不一致）时，清理该 profile 的 lockfile 与 node_modules 并重新 pnpm install；字段本身保留（它仍是新发布插件绕过发布冷静期的机制），只修复「条目与实际版本不一致」的失效状态。你实测的单行 || 联合写法已记录在需求调研结论里，供后续维护同类规则时参考。

2. npm dist-tags 的 latest 滞留

确认属实，原因是发布链路只发 next（脚本固定 --tag next），从无维护 latest 的步骤，导致 latest 冻结在各插件早期版本。已登记为 FNOS-012-04，处理方式：

• latest 将校正到各插件上一代最新稳定版 0.1.7-rc.2.2（四个包一致），而不是直接指向 0.2.0-rc.2.0——rc 版进 latest 会让按默认方式安装的用户装到预发布版，与 rc 阶段的版本固定策略冲突；
• 0.2.0-rc.2.0 继续通过 next 获取；等 harness 出 rc 进入稳定版后整体切换 latest；
• 校正自动化进发布命令：pnpm run publish 完成后按代际规则自动维护 latest（新代际首版→指向上一代最新稳定版，同代际迭代→不动），不再依赖人工记忆，防止再次滞留。你观察到的客户端误报「可更新/可降级」会随 latest 校正消失。

两项均已列入 FNOS-012（目标版本 5.7.0），完成后会在此跟进。感谢持续输出一手维护数据！