[实战复盘] 深度定制 DSH Profile 升级全链路避坑与工程实践（以 0.2.1-rc.2 → 0.2.1-rc.5 为例）

[superwiboy]

[实战复盘] 深度定制 DSH Profile 升级全链路踩坑与最佳实践（以 0.2.1-rc.2 → 0.2.1-rc.5 为例）

摘要

DeepSeek Harness（DSH）采用「一切皆插件」与 Profile 架构。出厂空白 Profile 升级通常顺利，但一旦 Profile 经过深度定制（包含多个第三方插件、本地 hotfix、历史依赖 overrides 和复杂 cordis.patch.yml），升级就极易遭遇：

• 20~50 个插件集体报错 disabling profile plugin row 或 did not activate（混合树断裂）；
• 本地手工 hotfix 在 pnpm install 后被静默冲掉；
• 第三方插件被 dsh-app-boot 静默跳过（skipping profile bundle）；
• 外部守护进程（如 systemd watchdog）在依赖半写状态下抢拉服务，引发连环崩溃与 start-limit-hit 熔断。

本文基于一次生产环境从 0.2.1-rc.2 成功平滑跃迁至 0.2.1-rc.5 的实战经验，系统拆解 7 个关键陷阱，并提供一套可复现、带秒级回滚与硬闸门校验的工业级升级标准规程。

---

一、环境拓扑与背景

角色	属性
宿主系统	Linux (x86_64), Node.js v24.x
DSH 架构	全局 CLI (@deepseek-ai/dsh) + Profile 目录 (~/.dsh/profiles/<profile_name>)
升级目标	Profile 核心包与全局 CLI 由 0.2.1-rc.2 升级至 0.2.1-rc.5
特殊定制	依赖多款开源生态插件，曾为了治理 hoisting 在 pnpm-workspace.yaml 中配置了多条 @deepseek-ai/* 的版本锁定

---

二、关键陷阱与深层机理剖析

坑 1：pnpm-workspace.yaml 历史 overrides 锁死子包引发「混合树断裂」

• 现象：
  若仅在 package.json 或通过 pnpm add 升级顶层几个核心包，启动时 journal 会报 20+ 甚至 50+ 行 disabling profile plugin row，必需核心插件（如 agent-loop、webserver）彻底无法激活。
• 根因：
  此前为解决深层 npm 依赖 hoisting 冲突，在 pnpm-workspace.yaml 的 overrides: 中钉死了大量 0.2.1-rc.2。如果只升级顶层包，深层依赖仍被强制解析为 rc.2，导致整棵 node_modules 形成版本割裂的“混合树”。rc.5 的顶层服务无法在 rc.2 的深层环境下握手。
• 规程：
  必须将 pnpm-workspace.yaml 中的 overrides 版本批量同步替换为目标版本。

  注意：overrides 字段的值通常不带引号（如 "@deepseek-ai/dsh-goal": 0.2.1-rc.2），直接用带引号的 sed 替换会静默匹配 0 行，需使用精确正则匹配行首键名与行尾版本。

坑 2：旧 Lockfile 导致未覆盖子包滞留（必须清锁重装）

• 现象：
  即使修改了 overrides 并执行 pnpm add，启动后仍有个别插件报丢失服务。
• 根因：
  未在 overrides 清单中的间接传递依赖（例如 @deepseek-ai/dsh-client-ui-primitives、@deepseek-ai/dsh-client-ui-slots 等），会被旧的 pnpm-lock.yaml 自动命中并锁定在旧版。
• 规程：
  修改 overrides 后，必须彻底删除 node_modules 与 pnpm-lock.yaml，触发全树依赖基于新 overrides 重新解析解析，并在升级后执行硬校验：确保 node_modules/@deepseek-ai/* 下旧版本包残留计数严格为 0。

坑 3：CLI 与 Profile 强同源约束及命令行参数变更

• 现象 1：全局 CLI 是旧版，Profile 是新版时，启动报 startup failed: 2 required plugins did not activate。
• 现象 2：新版 CLI 启动命令若带 web 子命令，报 error: too many arguments. Expected 0 arguments but got 1: web。
• 根因：
  1. CLI 与 Profile 必须同版本：新 Profile 依赖的新核心 service 导出必须由同版本的 CLI launcher 载入；
  2. 新版 CLI 参数规范收紧：显式传入 --profile <name> 时，不应再传 web 位置参数，直接使用 dsh --profile <name> --port <port> --no-open 即可。

坑 4：pnpm install 会静默冲掉手工改动（必须资产化为 pnpm patch）

• 现象：
  生产依赖重装后，某个第三方插件突然报 SyntaxError: The requested module '@deepseek-ai/dsh-llm' does not provide an export named 'assertNever'。
• 根因：
  第三方插件跟进官方发版较慢，用户此前在 node_modules/ 下手工修改了源码适配；但 pnpm install 会无条件整包还原为 npm 上游代码，导致本地修复静默丢失。
• 规程：
  所有本地修补必须使用 pnpm patch <package> 固化到 Profile 根目录的 patches/ 目录，并在 pnpm-workspace.yaml 中配置 patchedDependencies。每次 install 后校验目标文件的 sha256。

坑 5：compatibility.json 精准追加版本豁免

• 现象：
  启动日志出现 dsh: skipping profile bundle "xxx"，插件卡片或功能消失，但没有任何报错堆栈。
• 根因：
  查阅 dsh-app-boot/lib/index.js，DSH 对第三方 bundle 有运行时版本兼容性校验。如果该插件的 package.json 中的 peerDependencies 只声明支持旧版范围，DSH 会直接跳过加载。
• 规程：
  必须在 profile 目录下的 compatibility.json 中，向对应插件追加新版本（如 "0.2.1-rc.5"），使 dsh-app-boot 放行加载。

坑 6：外部看门狗 Timer 抢拉中间态与 systemd 熔断

• 现象：
  升级过程中，服务突然在一瞬间产生 100+ 条 disabling profile plugin row 报错，随后执行 systemctl start 报 start-limit-hit 拒绝启动，自动回滚也随之失败。
• 根因：
  1. 看门狗抢拉：若系统配置了按分钟巡检的 watchdog.timer，在 profile 依赖已换新但 CLI 尚未升级的几秒真空期内，看门狗整点唤醒并拉起服务，导致反向混合树崩溃连炸；
  2. systemd 熔断：短时间连炸 5 次触发了 StartLimitIntervalSec=300 / Burst=5 保护阈值，直接锁死 service 单元。
• 规程：
  1. 停服务前必须先停看门狗定时器；
  2. 在所有 systemctl start 之前及回滚逻辑中，必须强制前置执行 systemctl --user reset-failed <service> 清除熔断标记。

坑 7：Web Token 异步输出延迟

• 现象：
  升级脚本探测到 HTTP 200 后立即 grep journal 提取登录 token，报错“找不到 token”误判失败。
• 根因：
  底层的 /api/dsh-mneme/health 在 9 秒内返回 200，但 Webserver、插件与认证机制完整就绪并向日志打印 dsh web: http://.../?token=... 通常需要 15~25 秒。
• 规程：
  采用最长 60 秒的轮询等待循环提取 token，杜绝时序差误判。

---

三、标准化生产迁移规程（脱敏脚本模板）

推荐采用「秒级硬链接快照 + 闸门前置 + 全自动回滚」的设计模式：

#!/usr/bin/env bash
set -uo pipefail

PROFILE="$HOME/.dsh/profiles/web"
BACKUP="/tmp/dsh-profile-nm-backup"
MANIFESTS="/tmp/dsh-profile-manifests-backup"
TARGET_VER="0.2.1-rc.5"
OLD_VER="0.2.1-rc.2"

say(){ printf '\n[%s] %s\n' "$(date '+%H:%M:%S')" "$*"; }
die(){ say "✗ 失败: $*"; exit 1; }

rollback(){
  say "=== 触发自动回滚（还原至 $OLD_VER）==="
  systemctl --user stop dsh-web.service 2>/dev/null || true
  rm -rf "$PROFILE/node_modules"
  cp -al "$BACKUP" "$PROFILE/node_modules"
  cp "$MANIFESTS/package.json" "$MANIFESTS/pnpm-lock.yaml" "$MANIFESTS/pnpm-workspace.yaml" "$PROFILE/"
  [ -f "$MANIFESTS/compatibility.json" ] && cp "$MANIFESTS/compatibility.json" "$PROFILE/" || true
  npm i -g "@deepseek-ai/dsh@$OLD_VER" >/dev/null 2>&1
  systemctl --user reset-failed dsh-web.service
  systemctl --user start dsh-web.service
  systemctl --user start dsh-web-watchdog.timer 2>/dev/null || true
  say "✓ 回滚完成"
}
trap 'rc=$?; if [ $rc -ne 0 ]; then rollback; exit $rc; fi' EXIT

# 1. 停机与看护暂停
say "1. 暂停看门狗与服务"
systemctl --user stop dsh-web-watchdog.timer 2>/dev/null || true
systemctl --user stop dsh-web.service

# 2. 刷新秒级回滚基线（利用硬链接避免几十秒文件拷贝）
say "2. 创建硬链接快照"
rm -rf "$BACKUP" "$MANIFESTS"
mkdir -p "$MANIFESTS"
cp -al "$PROFILE/node_modules" "$BACKUP"
cp "$PROFILE/package.json" "$PROFILE/pnpm-lock.yaml" "$PROFILE/pnpm-workspace.yaml" "$MANIFESTS/"
[ -f "$PROFILE/compatibility.json" ] && cp "$PROFILE/compatibility.json" "$MANIFESTS/" || true

# 3. 升级 Profile 与 Overrides
say "3. 替换 overrides 并清锁重装"
cd "$PROFILE"
# 精确匹配行首 key 与行尾旧版本号
sed -i "/^  \"@deepseek-ai\// s/: 0\.2\.1-rc\.2$/: $TARGET_VER/" pnpm-workspace.yaml

# 兼容性文件追加豁免
python3 - <<'PY'
import json, os
p = 'compatibility.json'
if os.path.exists(p):
    d = json.load(open(p))
    for k in d:
        if '0.2.1-rc.5' not in d[k]:
            d[k].append('0.2.1-rc.5')
    json.dump(d, open(p, 'w'), indent=2)
PY

# 清锁重解析
rm -rf node_modules pnpm-lock.yaml
pnpm add "@deepseek-ai/dsh@$TARGET_VER" "@deepseek-ai/dsh-settings@$TARGET_VER" \
  "@deepseek-ai/dsh-base@$TARGET_VER" "@deepseek-ai/dsh-web-app@$TARGET_VER" \
  "@deepseek-ai/dsh-experimental-agent-team-profile@$TARGET_VER" \
  "@deepseek-ai/dsh-experimental-plugin-market-bundle@$TARGET_VER" \
  "@deepseek-ai/dsh-ptc-runtime-node@$TARGET_VER"

# 硬闸门 A：零混合树校验
LEFT=$(node -e "const fs=require('fs');const p=fs.readdirSync('node_modules/@deepseek-ai').map(x=>require('./node_modules/@deepseek-ai/'+x+'/package.json'));console.log(p.filter(x=>x.version==='$OLD_VER').map(x=>x.name).join(','))")
[ -z "$LEFT" ] || die "闸门A未通过：仍有旧版本残留 [$LEFT]"

# 4. 同步升级全局 CLI
say "4. 升级全局 CLI"
npm i -g "@deepseek-ai/dsh@$TARGET_VER"

# 5. 启动服务与健康校验
say "5. 启动服务"
systemctl --user reset-failed dsh-web.service
systemctl --user start dsh-web.service

# 轮询健康探针
for i in $(seq 1 60); do
  curl -sf -m 2 http://127.0.0.1:3080/api/dsh-mneme/health >/dev/null && break
  sleep 1
done

# 轮询获取 Token
TOKEN=""
for i in $(seq 1 60); do
  TOKEN=$(journalctl --user -u dsh-web.service --since '-2 min' --no-pager | grep -o 'http://127.0.0.1:3080/?token=[A-Za-z0-9_-]*' | tail -1 || true)
  [ -n "$TOKEN" ] && break
  sleep 1
done
[ -n "$TOKEN" ] || die "取不到登录 token"

# 日志关键错误清零闸门
journalctl --user -u dsh-web.service --since '-2 min' --no-pager > /tmp/boot-check.log
for pat in 'disabling profile plugin row' 'did not activate' 'failed to import' 'skipping profile bundle'; do
  N=$(grep -c "$pat" /tmp/boot-check.log || true)
  [ "$N" = "0" ] || die "日志命中异常特征: $pat × $N"
done

# 恢复看门狗
systemctl --user start dsh-web-watchdog.timer 2>/dev/null || true
say "=== 迁移成功！==="
say "入口: $TOKEN"

trap - EXIT
exit 0

---

四、经验总结

1. 不要盲目信任包管理器的局部更新：复杂的插件系统本质是一个高度耦合的微内核架构，深层依赖的一致性压倒一切；
2. 本地 Hotfix 必须代码资产化：不要直接改动 node_modules，善用 pnpm patch 让每一次修复都有迹可循；
3. 运维与生命周期隔离：在自动化迁移过程中，一切外部守护/看门狗机制都是潜在的竞态干扰源，遵循“先关看守、再动筋骨、全面校验、后开看守”的铁律。

希望这份实战记录能为社区中正在遇到升级报错的开发者提供参考！