升级路径的三个静默杀手：用户层文件能把 boot 和回滚一起杀掉（0.1.5-rc.1 → 0.1.7-rc.1 实测）

[dqiaok]

先说结论：这次 0.1.5-rc.1 → 0.1.7-rc.1 的升级失败，不是某一个 bug，而是升级路径缺一道"用户层兼容闸门"。构建成功、端口在听、页面能开、preset 在 roster 全绿，用户一说话就死；而且失败回滚只回代码、不回用户层，于是回滚也救不回来。同类帖子版上已经很多（#7654 / #6757 / #6167 / #7373 / #6137），我这条只补三个前面没被点名的机制，都带原始证据。先说明：fail-loud 而不是静默跳过的取向我认同，0.17 的插件兼容闸门也是好设计——问题在于这套闸门只罩住了插件，没罩住用户层。

环境：Windows 11 + Node 24.13.1 + pnpm 11.7.0；源码安装 git master；0.1.5-rc.1 → 0.1.7-rc.1（git merge --ff-only，3299 个提交）；web profile；升级动作就是 pnpm install && pnpm run clean && pnpm run build + 重启。

1. 用户层 patch 非法 = 每次 boot 当场死，且 git 回滚救不回来

~/.dsh/cordis.patch.yml（home 层）存在但不是顶层 YAML 数组时，boot 直接抛错退出，端口永远不监听，而 build 全绿：

Error: dsh: patches ~/.dsh/cordis.patch.yml must be a top-level YAML array of loader patch entries
    at parsePatchList (packages/boot/app-boot/src/index.ts:360)
    at loadOptionalPatches (.../index.ts:303)
    at composeProfile (apps/cli/src/profile-boot.ts:233)

问题不在"该不该 fail loud"，而在两点：

• 这个文件是新出现的用户层，任何占位（哪怕只有一行注释）都会把启动打死，而报错既没说是谁写的，也没说怎么修；
• 它是纯用户层文件：升级脚本失败后 git 回滚到旧版本，坏文件还在原地，而旧版本用同一条代码路径读它，于是回滚同样起不来，最后一头不落。

建议：①文件为空或只有注释时按"无这一层"处理；或 ②保留 fail loud，但报错里补一行修复指引（delete <path> or make it a top-level YAML array）。

2. 用户层覆盖了已迁移的端点 = 页面全绿，每次对话 404

0.1.7 把 llm-deepseek 换到了 Messages API：PUBLIC_BASE_URL = 'https://api.deepseek.com/anthropic'，请求打到 messagesApiRoot(baseURL) + '/messages'（messages-api.ts 会补 /v1），头为 x-api-key + anthropic-version: 2023-06-01。

我的 profile patch 里有一行 chat/completions 时代留下的 baseURL: https://api.deepseek.com。结果：每次请求 POST https://api.deepseek.com/v1/messages → 404。症状是端口在听、页面能开、preset 正常、会话在写盘，只有模型这一路死。会话日志原话：

{"type":"assistant/attempt","chunk":{"type":"finish","reason":{"kind":"error",
  "failure":{"message":"DeepSeek Messages request failed (404)","code":"HTTP_404","status":404}}}}
{"type":"turn/end","reason":{"kind":"error","failure":{"message":"DeepSeek Messages request failed (404)"}}}

正反双胞胎（同 key、同 body，只换根）：

• POST https://api.deepseek.com/anthropic/v1/messages → 200 + 完整 SSE
• POST https://api.deepseek.com/v1/messages → 404

修法是删掉那行覆盖（上游默认值已经对了），不是改它。但用户得先发一条消息才知道哪里坏了。

建议：对"用户层覆盖了本次变更过的字段/端点"给 warn + 一行迁移指引；至少对会改变请求落点的字段（如 baseURL）在 boot 或 doctor 时做一次最小连通性探测，直接报状态码。

3. preset 从目录改声明式是静默的

0.1.7 起 ~/.dsh/.agent-presets/<id>/（preset.yml + agent.cordis.yml）没有任何代码再读——不报错、不警告、不迁移。而会话日志按 preset id 记录，重启后解析不到该 id 就拒绝恢复会话，人设与工具全丢，用户侧的感受就是"升级完变砖"。迁移步骤只写在仓库自带的 skill 里（packages/preset/agent-preset/skills/editing-cordis-compositions/SKILL.md 的 "Migrate a legacy preset"），升级的用户看不到它。

建议：启动时检测到遗留 .agent-presets/ 就打印一条 warn + 迁移指引，或提供 dsh migrate 做无损转换。

共同点

三条都不是数据坏了，而是用户层被静默破坏，而所有绿色信号（build 成功、端口在听、HTTP 401/200、preset 在 roster）都在骗人。别的 agent harness 升级是一条命令或者一个按钮，失败自动回滚；这里"这次升级动了哪些用户可见的东西"整个判断被外包给了用户。

建议的最小改进（按性价比排序）

1. 官方升级入口：dsh upgrade = pull → install → clean → build → 校验产物类别计数 → 用户层快照 → 迁移/校验用户层 → 重启 → 功能自检，失败自动回滚（含用户层）。现在的"回滚"只回一半。
2. dsh doctor（[idea] One-command environment doctor for fresh installs (dsh doctor) #649 已提过）补两条现在没人有、但能一次抓住本次全部故障的检查：①构建产物按类别计数（per-package client.js 的数量），不要只查写死的文件名清单——build 报 success 也可能一个产物都没产出；②真实往返：从 catalog 取一个模型发一条最小 Messages 请求并报状态码（这条一次抓住第 2 类）。
3. 用户层兼容闸门：boot 时对用户 patch 覆盖的、本次发布变更过的字段给 warn + 迁移指引（现在只有插件有这道闸门）。
4. 破坏性变更清单进升级路径：本次 pull 动了哪些用户可见 schema（preset 位置、端点根、字段改名），升级时逐条打印一行迁移指引。
5. 若要做自升级（agent 升级自己）：幂等 + 独立看门狗 + 用户层快照。我这次就是 agent 在自己的会话里写升级链、自己重启自己，最后被自己写的用户层文件把回滚打断。

附：我这边落地的验收（欢迎直接拿走）

• 用启动打印的 token 换会话 cookie → 走 Gateway RPC 拉 agentPresets/list → 判：目标 preset 在 roster / 无激活失败 / 是默认，exit 0 才算升级成功。只看端口或 401 会把"起了但用不了"报成成功。
• 再加一条真消息端到端：上面第 2 类故障只有它能抓住（端口和 preset 两道全绿）。
• 启动脚本里放产物探针（例如 packages/client/modules/lib/client.js），让每天的启动自愈，而不是等升级那天才发现。

相关：#7654（0.1.5→0.1.7 恢复清单）、#6757（历史会话拒绝）、#6167（升级后卡死）、#7373（0.1.6-alpha 后恢复）、#649（dsh doctor 提议）、#6137（社区升级流程技能）。