dsh-connect-trae 4.4.4 → 4.4.6

package/CHANGELOG.md

@@ -1,5 +1,188 @@
 # Changelog
 
+## 4.4.6 (2026-10-24)
+
+> **对齐宿主 DSH 0.2.1-rc.3（纯版本推进，插件代码零改动），并修掉账号链路上三处
+> 会静默丢数据的问题——其中一处可能正是 #56「被顶掉的账号若干时间后消失」的成因。**
+>
+> 宿主这一版只落地 5 个提交：三个是「导航项自定义」（面板固定/取消固定、More 菜单、埋点），
+> 一个是 DeepSeek API-key 通道改走官方 `/models` 目录，一个是版本号——**均与本插件不相干**。
+> 插件消费的 13 个宿主包里只有 `dsh-client-ui-primitives` 有代码变化，且全是新增，
+> 而本插件对它只有类型层引用，因此**不需要任何适配**。
+>
+> 真正的风险在插件自己身上：一份读不懂的副本文件会被当成「一个账号都没有」，
+> 而三条合并写路径又以它为基底——一次损坏读 + 一次刷新 = 其余账号的副本被无声抹掉。
+
+### 修复
+
+- **副本文件损坏不再清掉全部账号**（`fix(auth)`，PR #58）。
+  `parseOwn` 此前对「无法解析的文件」（半截写入、手改损坏、未知版本）一律返回空数组，而镜像 /
+  刷新 / 导入三条合并写路径都以它的结果为合并基底——一次损坏读 + 下一次刷新 = **其余全部账号的
+  副本被无声抹掉**，账号行随下一个轮询消失，且因为异常全被吞掉，日志里什么都看不到。
+  - `parseOwn` 改为三态（合法 / 合法空 / **无法解析返回 `undefined`**），新增 `readOwnForMerge`
+    收口三条写路径：遇到无法解析的文件先隔离为 `.corrupt-<时间戳>`（字节保留、可找回），
+    再从干净文件开始；**隔离失败则放弃本次写入，绝不覆盖读不懂的字节**。
+  - `deleteAccount` 对不可解析文件**拒绝**而非当空。
+  - 这可能是 #56（被顶掉的账号若干时间后消失）的一种成因——值得让报告者检查
+    `$DSH_HOME/.trae-auth.cn.json` 及其同目录的 `.corrupt-*` 隔离文件。
+- **墓碑读-改-写收进一把锁**（`fix(auth)`，PR #58）。墓碑文件被两个并发流读改写：镜像
+  （清失效墓碑）与删除（加墓碑），此前都是锁外读、锁内写，丢更新的两个方向都疼——丢一个墓碑＝
+  已删账号在下一轮镜像复活；丢一次清理＝墓碑永久残留，该账号之后永远无法再被镜像。
+  收口为锁内 `updateTombstones(mutator)`。
+- **池测量的删除不再丢并发写入**（`fix(pool)`，PR #58）。`dropTraePoolProbe` 的读取挪进锁内
+  （对齐同文件 `writeTraePoolProbes` 的范式）：此前锁外读的快照会把并发批次刚写入的测量覆盖掉。
+
+### 变更
+
+- **对齐宿主 DSH 0.2.1-rc.3**：13 个 `@deepseek-ai/dsh-*` devDependency 从 `0.2.1-rc.2`
+  推进到 `0.2.1-rc.3`。`cordis`（`4.0.5`）/ `schemastery`（`3.18.5`）/ `pi-ai`（仍 `1.1.0`）
+  均未变——宿主 `app.asar` 实测随包的 pi-ai 仍是 1.1.0，3.4.2 起的双向适配结论原样成立。
+- **peer 范围无需改动**：`0.2.1-rc.3` 对 `>=0.1.7-rc.1 <0.3.0-0` 已判通过（实测）。
+- **插件代码零改动**：rc.3 对本插件消费的 13 个宿主包里，只有 `dsh-client-ui-primitives`
+  存在代码变化，且全部是**新增**（`TooltipSide` 增加 `'left'` 并改用实测边框盒换边放置、
+  `MenuItemButton` 增加 `current`、`Menu` 增加 `minWidthFromAnchor`、新增 `IconAppsAddOutline*`）。
+  本插件对 `dsh-client-ui-primitives` 只有**类型层引用**（`import type {} from ...`），
+  运行时不消费这些组件，故无需适配。
+
+### 已核对确认无变化
+
+- 逐字节比对 npm 上 `0.2.1-rc.2` 与 `0.2.1-rc.3` 两版的全量文件树：
+  `dsh-llm`、`dsh-llm-pi-ai`、`dsh-settings`、`dsh-host-webserver`、`dsh-atomic-write`、
+  `dsh-home-paths`、`dsh-attachment`、`dsh-client-ui-renderer`、`dsh-client-ui-settings`、
+  `dsh-client-ui-settings-plugins`、`dsh-client-ui-slots`、`dsh-client-locale`
+  ——**除 package.json 的版本号与内部依赖号外逐字节相同**。
+- 本插件注册的 5 个槽位（`plugins.bundle.config`、`plugins.row.config`、`conversation.input.left`、
+  `conversation.composer.dock`、`conversation.input.model.label`）在 rc.3 中**仍然存在且契约未变**；
+  宿主新增的 `conversation.session.header.views.actions` 等槽位与本插件无交集。
+- rc.3 宿主上实测：宿主侧 Config 条目 `include:dsh-connect-trae` 在册，客户端
+  `plugins.bundle.config` / `plugins.row.config` / `conversation.input.left` 三处注册均 active。
+
+### 测试
+
+- PR #58 新增回归用例：损坏副本文件被隔离且字节保留、合法文件中坏一行只丢该行、
+  隔离失败时放弃写入且原字节不动、墓碑并发删除/写入序列化冒烟、池测量的 drop 与 write 不互相覆盖。
+- `tests/dsh-peer-range.spec.ts` 的 `MUST_ADMIT` 补入 `0.2.1-rc.3`——此前这份「必须放行的版本」
+  清单里没有当前正在使用的版本，范围若被误收窄到当前宿主之外，测试仍会全绿。
+- 全仓 **1084** 例通过（84 个测试文件），双 tsconfig 类型检查通过。
+
+### 文档
+
+- 新增 `docs/DSH_0.2.1_RC1_SYNC.md` 第十节：`0.2.1-rc.3` 复核记录（取证、依赖面、契约面、
+  槽位核对、peer 门禁）。
+- `README.md` / `README.en.md` 的宿主版本结论推进到 `0.2.1-rc.3`，并新增
+  「`0.2.1-rc.3` 同步结论」小节。
+## 4.4.5 (2026-10-23)
+
+> **模型列表不再倒出官方已下架的历史配置：按 Trae IDE 名册退役 12 行、改钉 6 行，
+> 剩下的按通道分组、固定顺序、默认只看常用通道。**
+>
+> 合并自 PR #55，修 issue #52。报告人问「为啥 trae 的模型数量这么爆炸」并提醒「拿 code 的
+> 模型请求 solo 的潜在风险」——查下来是同一个洞：插件列的是 12 个目录 function 的**并集**
+> （46 行），而 Trae 客户端**一次只渲染一个 function**（14–24 行）。本版接入第三条上游信号
+> （IDE 名册的 `is_invisible_to_user`），把「官方还展不展示」这个问题交回上游自己回答，
+> 目录 **46 → 34 行**（本机 CN 账号实测），一行都没删错、一次都没猜。
+
+### 修复
+
+- **模型列表不再把官方已下架的历史配置倒出来，并把钉错通道的行改回官方通道**（`fix(catalog)`，issue #52）。
+  报告人问「为啥 trae 的模型数量这么爆炸」，同时提醒「拿 code 的模型请求 solo」。查下来是**同一个洞**：
+  插件列的是 12 个目录 function 的**并集**（46 行），而 Trae 客户端**一次只渲染一个 function**（14–24 行）；
+  #46 为了让带日期的快照可见，给「能调但骨架没收录」的行开了提升通道，而这条通道**没有上限** ——
+  `isPromotableWireModel` 只问「能不能调、有没有真名字」，不问「官方还展不展示」。
+  - **接入了第三条上游信号**：`batch_get_detail_param`（IDE 选择器渲染的那份名册）里的
+    `is_invisible_to_user`。端点与请求体本来就为 #46 备好了（`src/model-detail.ts`），缺的只是一个
+    client 与解析器 —— 现在在 `src/official-roster.ts`。
+  - **它是逐 (config, function) 的「模式名册」，不是生命周期标记**。实测 2026-10-23：
+    `DeepSeek-V4-Pro` 在 `solo_work_remote` 下被隐藏（那个模式展示的是 `-Official` 那份），
+    但在 `chat_v3` / `solo_coder` 下是可见的；`glm-5` 在 `solo_work_remote` / `solo_agent_remote`
+    隐藏、在 `solo_work_lite` / `solo_coder` 可见。把它读成「模型下架了」会**误删 6 个在用模型**，
+    所以判定分三种：
+    - **退役**：所有 `llm_utils_chat` 接受的 function 都隐藏它（`glm-4.7` 只在
+      `code_review_summary` 可见 —— 那是代码评审的助手配置，不是对话通道）。这类共 **12 行**，
+      正是截图里「尾部整屏的老模型」。
+    - **改钉**：自己的通道隐藏、但别的对话通道展示。改用官方自己那个通道，而不是我们先前猜的
+      并集首个 —— 这正好回答「拿 code 的模型请求 solo」：`Doubao-Seed-2.0-Code` / `glm-5.1` /
+      `qwen-3.5` 落到 `solo_coder`，`glm-5` / `DeepSeek-V4-Flash` / `DeepSeek-V4-Pro` 落到
+      `solo_work_lite`（按 `TRAE_DIRECTORY_FUNCTIONS` 的优先级选，不按文档顺序，所以两次刷新结果一致）。
+      共 **6 行**。
+    - **保留**：名册没提到这个 config（实测 `kimi-k2.8-preview`、`qwen3.8-flash` 只存在于 Remote
+      目录的 `chat_v3` 分组）、只把它当工具配置、或压根没有对话通道能判 —— **沉默不是判决**。
+  - **默认开启而且是 fail-open 的**，这是敢不设开关的理由：名册读不到（受限网络、没有 `X-Ide-Token`
+    的设备身份、超时、HTTP 非 2xx、文档为空）就返回 `undefined`，一行都不动。它只是给一次**已经成功**
+    的刷新做减噪，永远不会把刷新搞失败。名册成功读一次缓存 10 分钟，失败也缓存同样时长，
+    避免每次刷新都赔一个超时。
+  - **`config_switch` 只记录不判决**：这个字段的语义没实测过，拿它删模型风险太大。
+  - **实测**（本机 CN 账号，只读探针，零额度）：名册 105 configs / 544 pairs，耗时 343 ms；
+    `46 → 34`（退役 12、改钉 6），通道分布 `solo_work_remote=20  solo_coder=7  solo_work_lite=3
+    chat_v3=2  solo_agent_remote=1  默认=1`。
+  - **测试**：`tests/official-roster.spec.ts`（23 条）覆盖解析器容错、三种判决、按通道优先级选目标、
+    `wireConfigName` 而非显示 id 取值、大小写不敏感、工具配置不算模型、fail-open、缓存窗口，
+    以及一条走真实 `mergeTraeModelSources` 的端到端；全量 `1042 条 / 82 文件` 通过。
+
+- **模型区按通道分组、可搜索、顺序固定**（`feat(client)`，issue #52 P0）。
+  上一段修的是「多出来的行」，这一段修的是「剩下的行怎么摆」。报告里那半句「一屏平铺、顺序乱」
+  有两个独立的成因：
+  - **顺序原本不是排出来的，是到达顺序**。旧卡片直接渲染合并结果的顺序，而 `src/solo-remote.ts`
+    自己写着分组顺序**每次调用都可能不同** —— 同一个账号刷新两次，同样的行可以排出两个样子。
+    现在顺序是**行的集合的纯函数**：先按区域自己的通道优先级（`solo_work_remote` →
+    `solo_work_lite` → `solo_agent_remote` → `chat_v3` → `solo_coder`），组内按显示名排序
+    （大小写不敏感，内嵌版本号按**数字**比较，所以 `GLM-5.10` 排在 `GLM-5.9` 之后），
+    同名再按 id 兜底 —— 因此结果是全序，与到达顺序无关。
+  - **「一屏」看不出这是一份并集**。现在每行归到**它会被调用的那个通道**下，表头写明是哪个模式、
+    有多少行：本机 CN 账号实测 34 行 → 6 组（`solo_work_remote` 20 / `solo_coder` 7 /
+    `solo_work_lite` 3 / `chat_v3` 2 / `solo_agent_remote` 1 / 未标注 1），
+    而不是 34 行平铺。分组用小 `<details>`，默认全开 —— 默认折叠会把用户特意来找的模型藏起来。
+  - **搜索框**匹配显示名、id 与 **config_name**（排查 `4001 config_name rejected` 的人手上拿的是
+    上游名，而它正好在 `DeepSeek-V4-Flash` 这类行上与屏幕上的名字不同）。搜索**只是视图**：
+    「测试所有模型」与批量上下文按钮仍然作用于**整个目录**，不会因为搜索框里有字而悄悄缩小范围
+    （那是要花额度的动作）。开始搜索会把折起来的组重新展开一次。
+  - **排序写在两处，各管一半**：发现流程排一次（`lastCatalog` 因此有序，DSH 自己的模型选择器
+    按目录顺序渲染，也一并变稳），卡片再排一次（升级前保存的目录同样被扶正，不必先刷新一次）。
+  - 通道优先级表从 `solo.ts` 搬到纯模块 `src/model-order.ts` 并**由 `solo.ts` 反向重新导出** ——
+    卡片要 import 它，而 `solo.ts` 带着 `node:crypto`。两份拷贝会让「线上先问哪个通道」与
+    「界面上先画哪个通道」悄悄分叉，而分叉是不可见的。
+  - **测试**：`tests/model-order.spec.ts`（21 条：通道优先级、组内排序、版本号数字比较、
+    无通道行排最后、未知通道归位、与到达顺序无关、同名兜底、不改入参、分组不丢不重、搜索三种匹配）
+    与 `tests/card-model-groups.spec.tsx`（7 条：渲染顺序、组头计数、搜索计数、按 config_name 命中、
+    无匹配提示、**搜索时「测试所有」仍覆盖全量**、折叠与搜索重新展开）。全量 `1070 条 / 84 文件` 通过。
+
+- **模型列表默认只看「常用通道」，并把藏起来的已启用模型说出来**（`feat(client)`，issue #52 P2）。
+  诊断里设想的是三档（`当前通道 / 常用通道组 / 全部`），P1 落地后重新数一遍只剩两档站得住：
+  - **「常用通道组」= 全部**。P1 已经退役了所有「任何对话通道都不展示」的 config，剩下的每一行
+    都至少有一个对话通道在展示它，这一档没有内容。
+  - **「当前通道」= 20 行，会藏掉在用的 `glm-5`**。它的真实含义是「只留第一优先的
+    `solo_work_remote`」；`glm-5` 只由 `solo_work_lite` 提供，不是 `-Official` 那份的影子。
+    为了「看起来像客户端」而把在用的模型从默认视图里拿掉，不划算。
+
+  所以是两档，默认 **24**（`solo_work_remote` + `solo_work_lite` + 未标注行），「全部」**34**
+  （再加 `solo_coder` 7 / `chat_v3` 2 / `solo_agent_remote` 1）。24 同时落在客户端「每个模式
+  展示 14–24 个」的上沿 —— 默认视图第一次和报告人拿来比较的那个列表是同一个量级，而**一行都没删**。
+  - **视图只影响绘制**：「一键测试所有」「整区切到 Max」「全部恢复默认上下文」仍作用于完整目录。
+    这些动作花额度或改设置，若因为屏幕少了 10 行就缩小范围，用户会以为「都测过了」。
+  - **被藏起来的「已启用」行必须说出来**：默认视图藏 10 行，用户之前勾选过的那些勾选框就不在
+    屏幕上了。保存路径本来就安全（写的是 state 里的 `activeEnabledIds`，不是从渲染出的 checkbox 读），
+    但不说的话，数一遍勾选框只会得出「那些模型被关了」。列表下方固定一行
+    「另有 N 个已启用的模型不在此视图内 —— 查看全部」。
+  - **搜索不撒谎**：搜索在视图内进行（全局搜索会和眼前的组头矛盾），所以空结果分两种 ——
+    「没有匹配」与「常用通道内没有，全部目录里有 N 个」+ 一键切过去。搜 `kimi` 时
+    `kimi-k2.5` 就在 `solo_coder` 组里，混成一句是搜索框最不该犯的错。
+  - **视图控件只在真有行被排除时才渲染**：一个能在两个相同列表之间切换的开关，比没有更糟。
+  - **按下态用 `bg-layer-3` 压在 `bg-layer-2` 轨道上**。第一版写的是 `bg-layer-1`，
+    `card-styles.spec.tsx` 立刻拒了 —— 那不是 DSH 定义的 token，回退值会在两个主题里同时生效，
+    正是这个测试存在的理由。
+  - **顺带**：`row.modelsChannelDefault` 字样改成「未标注模式（走 solo_work_lite）」，把这行的
+    真实调用路径写出来，而不是含糊的「默认通道」。
+  - **实测截图**（真机 34 行目录、真卡片组件、中文文案）：默认态 20+3+1 三组 24 行，
+    「另有 1 个已启用的模型不在此视图内」；切到全部后按下态与组数一同变化。
+  - **测试**：`tests/model-order.spec.ts` +5 条（`solo_work_*` 保留、未标注行按默认通道归入常用、
+    `all` 保持顺序且返回副本、按 region 判定、常用通道必须是该 region 优先级表的子集）与
+    `tests/card-model-groups.spec.tsx` +5 条（默认范围与计数、切换与 `aria-pressed`、
+    视图外命中提示与跳转、已启用行被藏时的提示与勾选状态、无可排除行时不渲染控件）；
+    原有 7 条按默认范围调整（涉及专用通道的断言先切「全部」）。全量 `1080 条 / 84 文件` 通过。
+  - **体积实测**（发版时在 main 基线上对照，更正 PR 描述里「与 4.4.4 一致」的说法）：
+    client 387.12 → **412.87 kB**、index 438.67 → **457.48 kB** —— 增长来自两个新模块与
+    分组 UI，属预期。
+
 ## 4.4.4 (2026-10-23)
 
 > **同价的会员分支不再被读成第二重折扣；顺手补上官方客户端渲染链路的取证。**
@@ -623,7 +806,6 @@
   文档时显示「正在加载账号」而不是「未登录」引导、迟到的首屏文档不会覆盖已在屏的完整文档。
 - 全仓 **902** 例通过，0 skipped。
 
-
 ## 3.10.1 (2026-10-19)
 
 > 「一键签到所有账号」下线。Trae 限制**每台设备每天只能签到一次**：本机任一账号签过之后，这个按钮
@@ -1047,7 +1229,6 @@
   上一轮的双向适配结论原样成立。
 - 线上请求体探针在真实 rc.2 栈上复跑，结果与 rc.1 一致。
 
-
 ## 3.7.0 (2026-10-17)
 
 > **对齐 DSH 0.2.1-rc.1。** 宿主把 `@earendil-works/pi-ai` 从 `^0.85.1` 抬到 `^1.1.0`，
@@ -1746,7 +1927,6 @@
 
 <img src="docs/assets/dsh-connect-trae-composer-credits.png" width="536" alt="Trae credits panel: a table of accounts with their general balance, and the composer readout below" />
 
-
 ## 2.14.0 (2026-10-07)
 
 > **积分浮层改为表格：本区域每个账号一行、只列通用积分、点行即可切换账号。**
@@ -2624,7 +2804,6 @@ Tr                        ← 我们的行只剩开头两个字母
   - **顺带修掉一处链接会在 npm 页 404 的问题**：本次新增的「未验证项」指引用户去看 `docs/WINDOWS_TOKEN_PROBE.md`，但 `package.json` 的 `files` 白名单（`RELEASING.md` 有明确记载，属有意的包体控制）只放行 `docs/assets/` 下那张截图，**所有 `docs/*.md` 都不进 npm 包**——写成相对 Markdown 链接会在 npm 页面上 404。既有引用（`docs/IMPLEMENTATION_PLAN.md` 等）用的是反引号纯文本故不受影响，本次改为指向 GitHub 的绝对链接（实测 HTTP 200）。
   - `RELEASING.md` 的打包内容清单同步更新（新增 `scripts/verify-windows.mjs`），并记下两条纪律：该脚本必须随包（否则用户无法执行验证步骤）、`docs/*.md` 不进包故 README 引用必须用绝对链接。
 
-
 ## 2.3.0 (2026-09-25)
 
 ### Breaking Changes

package/README.en.md

@@ -153,7 +153,7 @@ Restart the DSH process after install/update/uninstall.
 ## DSH version compatibility
 
 **Requires DSH 0.1.7-rc.1 and up** (since 2.3.0 the plugin no longer targets hosts older than 0.1.7; the peer dependency ranges are narrowed accordingly).
-**The peer upper bound is `<0.3.0-0`, so both the 0.1.7 and the 0.2 line are supported (including 0.2.1-rc.2, verified).**
+**The peer upper bound is `<0.3.0-0`, so both the 0.1.7 and the 0.2 line are supported (including 0.2.1-rc.3, verified).**
 
 ### Both pi-ai context generations are supported (since 3.4.2)
 
@@ -178,13 +178,26 @@ The 0.2.0 line breaks **no** contract this plugin consumes — a symbol-by-symbo
 
 ### DSH 0.2.1 line (pi-ai 1.1.0) sync
 
-The `0.2.1-rc.1` host moved `@earendil-works/pi-ai` from `^0.85.1` to **`^1.1.0`** (unchanged through `0.2.1-rc.2`) — the only change on the 0.2 line with real behavioural impact. Three conclusions:
+The `0.2.1-rc.1` host moved `@earendil-works/pi-ai` from `^0.85.1` to **`^1.1.0`** (unchanged through `0.2.1-rc.2` and `0.2.1-rc.3`) — the only change on the 0.2 line with real behavioural impact. Three conclusions:
 
 1. **The request body did not regress (measured, not inferred).** The 1.1.0 api reads the prompt **only** from a transcript system message and never touches top-level `systemPrompt` / `tools`, while `dsh-llm-pi-ai`'s `piContext()` still emits the legacy envelope. The bidirectional adapter this plugin has shipped since 3.4.2 covers exactly that: feeding the real host envelope through real `1.1.0` with a local SSE capture yields `roles: ["system","user"]`, an intact system text and `tools: 1`; **without the adapter it degenerates to `roles: ["user"]`, system `null`, `tools: 0`** — with no error. That contrast is pinned as a wire-level matrix in `tests/pi-ai-context.spec.ts`.
 2. **Types were fixed.** 1.1.0 changed `ProviderStreams`' second parameter to a **branded** `TranscriptContext` (a `unique symbol` only `normalizeContext()` can produce). The adapter casts once at that single boundary (`withContextAdaptation` in `src/adapter.ts`) and documents why the brand cannot be obtained honestly there.
-3. **The peer range needed no change.** DSH evaluates with `semver.satisfies(runtime, range, { includePrerelease: true })` and checks only the `@deepseek-ai/dsh*` namespace, so `>=0.1.7-rc.1 <0.3.0-0` already admits both `0.2.1-rc.1` and `0.2.1-rc.2` (verified). Note the prerelease cliff only exists under **default** options — it is not this plugin's situation.
+3. **The peer range needed no change.** DSH evaluates with `semver.satisfies(runtime, range, { includePrerelease: true })` and checks only the `@deepseek-ai/dsh*` namespace, so `>=0.1.7-rc.1 <0.3.0-0` already admits `0.2.1-rc.1`, `0.2.1-rc.2` and `0.2.1-rc.3` (verified). Note the prerelease cliff only exists under **default** options — it is not this plugin's situation.
 
-The dev tree pins `@earendil-works/pi-ai` at exactly **1.1.0** (the version the host actually bundles) rather than `^1.1.0`, so local typecheck and tests run against the same contract users do; the `schemastery` override moved to `3.18.5` (`dsh-llm-pi-ai@0.2.1-rc.2` declares `~3.18.5`).
+The dev tree pins `@earendil-works/pi-ai` at exactly **1.1.0** (the version the host actually bundles — still 1.1.0 on `0.2.1-rc.3`) rather than `^1.1.0`, so local typecheck and tests run against the same contract users do; the `schemastery` override moved to `3.18.5` (`dsh-llm-pi-ai@0.2.1-rc.3` declares `~3.18.5`).
+
+### `0.2.1-rc.3` sync (since 4.4.6)
+
+The host moved to `0.2.1-rc.3` (the desktop app's `CFBundleVersion` and the bundled `dsh-desktop-runtime` both report `0.2.1-rc.3`). Upstream shipped five commits: three of them are the new "navigation entry customization" UI (pin/unpin plugin launchers, a More menu, analytics), one switches the DeepSeek API-key route to the official `/models` listing, one is the version bump.
+
+For **this plugin**:
+
+- Of the 13 host packages the plugin consumes, **only `dsh-client-ui-primitives` changed code**, and every change is **additive**: `Tooltip`'s `TooltipSide` gains `'left'` and now places the bubble from measured border boxes (preferred → opposite → perpendicular side), `MenuItemButton` gains `current`, `Menu` gains `minWidthFromAnchor`, and the icon set gains `IconAppsAddOutline*`. This plugin references `dsh-client-ui-primitives` **at the type level only** (`import type {} from ...`) and never touches those components at runtime, so **no adaptation is needed**.
+- The other 12 packages (`dsh-llm`, `dsh-llm-pi-ai`, `dsh-settings`, `dsh-host-webserver`, `dsh-atomic-write`, `dsh-home-paths`, `dsh-attachment`, `dsh-client-ui-renderer`, `dsh-client-ui-settings`, `dsh-client-ui-settings-plugins`, `dsh-client-ui-slots`, `dsh-client-locale`) are **byte-for-byte unchanged**.
+- Every slot this plugin registers (`plugins.bundle.config`, `plugins.row.config`, `conversation.input.left`, `conversation.composer.dock`, `conversation.input.model.label`) **still exists with an unchanged contract** on rc.3; the host's new slots (e.g. `conversation.session.header.views.actions`) do not overlap with them.
+- The peer range **needs no change**: `0.2.1-rc.3` is admitted by `>=0.1.7-rc.1 <0.3.0-0` (verified).
+
+Details: [section 10 of `docs/DSH_0.2.1_RC1_SYNC.md`](https://github.com/dingminhua/dsh-connect-trae/blob/main/docs/DSH_0.2.1_RC1_SYNC.md).
 
 
 ### Why the upper bound is not `<0.2.0`

package/README.md

@@ -172,7 +172,7 @@ npm install dsh-connect-trae
 ## DSH 版本兼容
 
 **要求 DSH 0.1.7-rc.1 及以上**（2.3.0 起不再支持 0.1.7 之前的宿主；peer 依赖范围已按此收窄）。
-**peer 上界为 `<0.3.0-0`：0.1.7 与 0.2 两条线均受支持（含 0.2.1-rc.2，已实测）。**
+**peer 上界为 `<0.3.0-0`：0.1.7 与 0.2 两条线均受支持（含 0.2.1-rc.3，已实测）。**
 
 ### 同时支持 pi-ai 的两代上下文（3.4.2 起）
 
@@ -206,7 +206,7 @@ peer 范围不满足的 bundle 会被**整体跳过**，只往 stderr 写一行
 
 ### DSH 0.2.1 线（pi-ai 1.1.0）同步结论
 
-宿主 `0.2.1-rc.1` 把 `@earendil-works/pi-ai` 从 `^0.85.1` 抬到了 **`^1.1.0`**（`0.2.1-rc.2` 保持不变），这是 0.2 线里
+宿主 `0.2.1-rc.1` 把 `@earendil-works/pi-ai` 从 `^0.85.1` 抬到了 **`^1.1.0`**（`0.2.1-rc.2` / `0.2.1-rc.3` 均保持不变），这是 0.2 线里
 唯一有实际行为影响的变化。三项结论：
 
 1. **请求体没有丢东西（已实测）**。1.1.0 的 api **只**读 transcript 里的 system 消息，
@@ -219,13 +219,36 @@ peer 范围不满足的 bundle 会被**整体跳过**，只往 stderr 写一行
    `TranscriptContext`，只有 `normalizeContext()` 能产出。适配层在这条边界上做一次显式转型
    （`src/adapter.ts` 的 `withContextAdaptation`），并在两处调用点写明为何品牌在此处不可诚实获得。
 3. **peer 范围无需改动**。DSH 用 `semver.satisfies(runtime, range, { includePrerelease: true })`
-   求值，且只校验 `@deepseek-ai/dsh*` 命名空间，因此 `>=0.1.7-rc.1 <0.3.0-0` 对 `0.2.1-rc.1` / `0.2.1-rc.2` 均已判通过
+   求值，且只校验 `@deepseek-ai/dsh*` 命名空间，因此 `>=0.1.7-rc.1 <0.3.0-0` 对 `0.2.1-rc.1` / `0.2.1-rc.2` / `0.2.1-rc.3` 均已判通过
    （已实测）。**注意**：预发布悬崖只在**默认选项**下成立——那是 `dsh-connect-workbuddy` 侧
    调研文档所描述的困境，本插件不适用。
 
-开发树的 `@earendil-works/pi-ai` 钉在 **1.1.0**（宿主实际随包的版本）而非 `^1.1.0`，
+开发树的 `@earendil-works/pi-ai` 钉在 **1.1.0**（宿主实际随包的版本，`0.2.1-rc.3` 实测仍是 1.1.0）而非 `^1.1.0`，
 使本地 typecheck 与测试跑在与用户完全一致的契约上；`schemastery` 的 override 同步抬到
-`3.18.5`（`dsh-llm-pi-ai@0.2.1-rc.2` 声明 `~3.18.5`）。
+`3.18.5`（`dsh-llm-pi-ai@0.2.1-rc.3` 声明 `~3.18.5`）。
+
+### `0.2.1-rc.3` 同步结论（4.4.6 起）
+
+宿主推进到 `0.2.1-rc.3`（桌面版 `CFBundleVersion` 与随包 `dsh-desktop-runtime` 同为 `0.2.1-rc.3`）。
+上游这一版只落地了 5 个提交，其中 3 个是 UI 的「导航项自定义」（插件化面板的固定/取消固定、
+More 菜单、埋点），1 个是 DeepSeek API-key 通道改走官方 `/models` 目录，1 个是版本号。
+
+对**本插件**而言：
+
+- 插件消费的 13 个宿主包里，**只有 `dsh-client-ui-primitives` 有代码变化**，且**全是新增**：
+  `Tooltip` 的 `TooltipSide` 增加 `'left'` 并改用实测边框盒做「首选 → 对侧 → 垂直侧」的换边放置，
+  `MenuItemButton` 增加 `current`、`Menu` 增加 `minWidthFromAnchor`，图标新增 `IconAppsAddOutline*`。
+  本插件对 `dsh-client-ui-primitives` 只有**类型层引用**（`import type {} from ...`），
+  运行时不碰这些组件，**无需任何适配**。
+- 其余 12 个包（`dsh-llm`、`dsh-llm-pi-ai`、`dsh-settings`、`dsh-host-webserver`、`dsh-atomic-write`、
+  `dsh-home-paths`、`dsh-attachment`、`dsh-client-ui-renderer`、`dsh-client-ui-settings`、
+  `dsh-client-ui-settings-plugins`、`dsh-client-ui-slots`、`dsh-client-locale`）**逐字节未变**。
+- 插件注册的全部槽位（`plugins.bundle.config`、`plugins.row.config`、`conversation.input.left`、
+  `conversation.composer.dock`、`conversation.input.model.label`）在 rc.3 中**仍然存在且契约未变**；
+  宿主新增的 `conversation.session.header.views.actions` 等槽位与本插件无交集。
+- peer 范围**无需改动**：`0.2.1-rc.3` 对 `>=0.1.7-rc.1 <0.3.0-0` 已判通过（已实测）。
+
+细节见 [`docs/DSH_0.2.1_RC1_SYNC.md`](https://github.com/dingminhua/dsh-connect-trae/blob/main/docs/DSH_0.2.1_RC1_SYNC.md) 第十节。
 
 
 ### peer 上界为什么不写 `<0.2.0`