docs(dsh): 记录 profile overrides 必须与宿主同批抬版本的坑（0.2.0 升级实测）

升级 3080 后出现「加载提供商目录失败: settings service is absent」，根因是 profile 的
pnpm-workspace.yaml 里上一轮留下的 overrides '@deepseek-ai/dsh-settings': 0.1.7-rc.2——
它让 profile 顶层留住 0.1.7-rc.2 的 dsh-settings，后者用精确版本拉来 dsh-config-editor
0.1.7-rc.2 并遮蔽 bundle 自带的 0.2.0-rc.1，于是 0.2.0 的启动预检禁用 config-editor 行，
settings 行永远 pending (waiting for service: configEditor)。

已修：override 抬到 0.2.0-rc.1（profile 顶层全部收敛到 0.2.0-rc.1，.pnpm 里 0.1.7 副本归零）。
文档：适配记录新增 §5.1（含原始日志证据），AGENTS §3.0 增加「用户 profile 自己的 pin 也要
同批抬」一条。

AGENTS.md

@@ -38,6 +38,7 @@
 - **宿主 web profile 组成**：新增 desktop-only `product-analytics` / `desktop-product-telemetry`（web 上 `disabled`）；`time-context` / `schedule` / `ui-schedule`（本就 `disabled`）移入可选 `dsh-experimental-schedule-bundle`。挂载 lane 的「宿主 tab 恰好 1 条（terminal）、browser 缺席」断言不受影响。插件**不依赖**宿主 schedule 服务。
 - **生态连带**：可选集成 `@huanlin/dsh-plugin-better-locale` 的 peer 钉 `^0.1.x`（最新 0.4.3 也钉 `^0.1.5-rc.2`），在 0.2.0 上必被预检禁用 → `pnpm peers check` 会报它的 5 条 unmet peer，属上游未适配，与本插件自身 14 条 peer 无关。
 - **本机 dev 树**：先 `pnpm install --registry https://registry.npmjs.org`（npmmirror 对新预发布滞后，直接 `pnpm install` 会 `ERR_PNPM_NO_MATCHING_VERSION`）。
+- **用户 profile 自己的 pin 也要同批抬**（2026-09-28 实测踩到）：profile 的 `pnpm-workspace.yaml` 里若有 `overrides: '@deepseek-ai/dsh-*'`（例如历史上为修「旧宿主包遮蔽 bundle」而加的 `dsh-settings` pin），**升级宿主时必须与宿主版本同批更新**。忘了抬的后果：profile 顶层留住旧版 `dsh-settings`，它用精确版本拉来旧版 `dsh-config-editor` 并遮蔽 bundle 自带的 0.2.0 版本 → 预检禁用 `config-editor` 行 → `settings` 行永远 `pending (waiting for service: configEditor)` → 界面报「加载提供商目录失败: settings service is absent」。症状与原因隔着好几层，先看宿主日志里的 `disabling profile plugin row` 与 `pending (waiting for service: …)` 两行。
 
 ### 3.1~3.4 历史：DSH 0.1.7 适配要点（0.1.7-rc.1+ 基线，v0.21.1–v0.23.0）
 

docs/plans/2026-09-28-dsh-0.2.0-rc.1-adaptation.md

@@ -67,4 +67,21 @@
 | `@deepseek-ai/dsh-experimental-agent-team-profile` | 无 DSH peer | 升级到 0.2.0-rc.1 |
 | `@deepseek-ai/dsh-experimental-agent-team-web-profile@0.1.6-alpha.2` | 无 DSH peer | 保持旧版（无 0.2.0 发布），运行时未验证 |
 
+### 5.1 实测踩到的坑：profile 自己的 `pnpm-workspace.yaml` overrides 必须与宿主同步
+
+升级后 3080 出现「加载提供商目录失败: settings service is absent: mount @deepseek-ai/dsh-settings with @deepseek-ai/dsh-config-editor in the profile composition」。宿主日志给出了根因链路：
+
+```
+dsh: disabling profile plugin row "config-editor": Plugin @deepseek-ai/dsh-config-editor@0.1.7-rc.2
+     is incompatible with dsh 0.2.0-rc.1: peerDependencies {"@deepseek-ai/dsh-hmr":"0.1.7-rc.2",
+     "@deepseek-ai/dsh-app-boot":"0.1.7-rc.2"}
+settings (@deepseek-ai/dsh-settings): pending (waiting for service: configEditor)
+```
+
+profile 的 `pnpm-workspace.yaml` 里有一条上一轮升级留下的 `overrides: '@deepseek-ai/dsh-settings': 0.1.7-rc.2`（它自己的注释就写着「Keep this in lockstep with the host version」）。这条 pin 让 profile 树里的 `dsh-settings` 停在 0.1.7-rc.2，而 `dsh-settings` 用**精确版本**声明 `dsh-config-editor` / `dsh-util-values` → profile 顶层出现 0.1.7-rc.2 的 `dsh-config-editor`，它**遮蔽**了宿主 bundle 自带的 0.2.0-rc.1，于是 0.2.0 的启动预检把 `config-editor` 整行禁用，`settings` 行永远等不到 `configEditor`，设置/模型页的 provider 目录随之失败。
+
+修法：把该 override 与注释一起抬到 `0.2.0-rc.1` → `pnpm install`（profile 内）→ 重启。修复后 profile 顶层全部收敛到 0.2.0-rc.1（`dsh-atomic-write` / `dsh-brand` / `dsh-config-editor` / `dsh-util-values` / agent-team 三包），`.pnpm` 里 0.1.7-rc.2 的副本归零。
+
+**教训（对宿主版本升级通用）**：升级 DSH 时，除了 launcher 的 npx 钉版与 profile 依赖，**profile 自己的 `overrides` / `pnpm-workspace.yaml` 里任何 `@deepseek-ai/dsh-*` pin 都必须同批抬版本**；否则 profile 树里会出现旧宿主包并遮蔽 bundle 自带的那一份，而预检只报「某行被禁用」，症状（设置服务缺失）与原因（一条 override）隔着好几层。
+
 升级步骤（含回滚）见最终交付说明：备份 `~/.dsh/dsh-web.sh` 与 `profiles/web/package.json` → launcher 的 npx 钉版 → `0.2.0-rc.1` → 升 agent-team profile → 装 v0.24.0 tarball → `pm2 restart dsh-web` → 核对路由与 `pm2 logs` 的 `disabling profile plugin` 行。