@nonamelego/dsh-catppuccin 0.5.9 → 0.5.10-beta.0

package/README.en.md

@@ -125,22 +125,29 @@ dsh plugin --profile web add @nonamelego/dsh-catppuccin
 Restart `dsh web` after installing — `dsh plugin` adds it to the profile's bundles.
 Use the profile name of your choice in place of `web` (e.g. `headless`).
 
-**Desktop**: the desktop build's active profile is named `desktop`
-(`$DSH_HOME/profiles/desktop`), so run:
+**Desktop**: the official desktop shell and the community desktop shell both read the **same profile**
+`$DSH_HOME/profiles/desktop`, but **they install/upgrade plugins in completely different, non-interchangeable
+ways** — pick the column that matches your shell:
 
-```sh
-dsh plugin --profile desktop add @nonamelego/dsh-catppuccin
-```
+| | Official desktop shell ([DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) app) | Community shell ([DSH Desktop](https://github.com/anywhere-labs/dsh-desktop)) |
+|---|---|---|
+| **Install** | Its **plugin UI** → add plugin → enter the package name `@nonamelego/dsh-catppuccin` (Git URLs / tarballs / local paths are accepted too) | In the app's own **DSH terminal**:<br>`dsh plugin --profile desktop add @nonamelego/dsh-catppuccin` |
+| **Upgrade** | **Remove the plugin in the plugin UI, then enter the same package name again to reinstall it** (v0.2.0 has no upgrade entry point and no version picker) | The same `update` command as web:<br>`dsh plugin --profile desktop update @nonamelego/dsh-catppuccin` |
+| Runs pnpm | The app's bundled pnpm | The app's bundled pnpm |
+
+Either way, **restart the desktop app** to load the new version.
 
-Run it in the DSH terminal of the desktop app (`dsh plugin` defaults to the active profile),
-then restart the app.
-Installing from the repo works the same way: `dsh plugin --profile desktop add https://github.com/NoNameLeGo/dsh-catppuccin-theme`.
+> ⚠️ **Do not mix the columns**: the official shell's plugin UI does not run commands, and the community
+> shell's `update` command does not apply to the official shell. Also, **the plain `dsh` on your system PATH
+> cannot manage `desktop` in either shell** — upstream reserves that profile name and rejects it with
+> `error: profile "desktop" is managed exclusively by the Electron application`. To use the CLI, use another
+> profile name (`web`, `headless`, `dsh-tui`).
 
 > **Two desktop shells, one profile**: the official
 > [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) monorepo ships
-> `apps/desktop` / `apps/desktop-host` (Electron, still in development), and the community
-> [DSH Desktop](https://github.com/anywhere-labs/deepseek-harness-desktop) does the same — both boot
-> `$DSH_HOME/profiles/desktop`, so the command above works for either. This plugin's desktop support
+> `apps/desktop` / `apps/desktop-host` (Electron), and the community
+> [DSH Desktop](https://github.com/anywhere-labs/dsh-desktop) does the same — both boot
+> `$DSH_HOME/profiles/desktop`, so a plugin installed once works in either. This plugin's desktop support
 > targets the **official web + desktop** builds; the community shell's `desktopProfiles` service probe
 > is kept. The official shell's profile process carries **no** dedicated env marker (its
 > `DSH_DESKTOP_NODE_EXECUTABLE` is injected only into its package-install children), so the plugin
@@ -157,6 +164,10 @@ dsh plugin --profile web add https://github.com/NoNameLeGo/dsh-catppuccin-theme
 When installing from git, pnpm may ask you to allow build scripts — follow pnpm's prompt
 and add the package to the profile's `pnpm-workspace.yaml` `allowBuilds`, then run it again.
 
+On desktop, follow the table above instead: the **official shell** takes the Git URL directly in its
+plugin UI, while the **community shell** runs the same command with
+`dsh plugin --profile desktop add …`.
+
 ### dsh-TUI (terminal) themes
 
 The same package covers the TUI. Install it into the dsh-tui profile:
@@ -246,6 +257,12 @@ In **Settings → General**, right below the **Glass** row:
 - Channel policy: stable builds follow the `latest` tag; prereleases follow both `latest`
   and `beta` (the upgrade command automatically carries `@beta`). Offline or network
   failures show the reason and offer a retry.
+- The upgrade path follows the **host**: the **official desktop build** (DeepSeek Harness
+  client) gets no command line — it has no reachable terminal — so this row shows the
+  **`package@channel`** spec and tells you to delete the plugin on the **Plugins** page and
+  reinstall it (the same path as the desktop section above). The **community desktop shell**
+  and **web** keep the copyable `dsh plugin …` command. The host classifies itself
+  (`web` / `community-desktop` / `official-desktop`); you do not pick.
 
 ## Glassmorphism
 
@@ -269,7 +286,7 @@ What this plugin does:
 - **One-click toggle**: off restores the stock UI exactly; uninstalling the plugin leaves
   nothing behind.
 
-### What Compatibility mode matches
+### When Compatibility mode matches the wrong surface
 
 Compatibility mode frosts host and third-party floating surfaces through **class substrings and
 semantic attributes**, needing no cooperation from other plugins — the price is that a substring
@@ -278,54 +295,19 @@ matches are exactly these:
 
 | Family | Anchor |
 |---|---|
-| Composer card | `[data-composer-card]` (the host's own attribute) |
+| Composer card | `[data-composer-card]` (the material is painted on its `::before`, see issue #19) |
 | Menus | `[role='menu']` |
 | Popovers | `[class*='popover']` / `[class*='dropdown']` (still substrings) |
 | Modal dialogs | `[role='dialog'][aria-modal='true']` |
 | Host right sidebar (open state only) | `[data-sidebar-right-panel][data-sidebar-right-open]` |
 
-`0.5.8` narrowed the three widest families out of the sheet on evidence (the `card` substring, the
-`panel` substring and row-level tooltips — see issue #17), but a **new class name in a third-party
-plugin can still be misread**. Defaults only change with evidence, so when you hit one:
-
-**1. Collect evidence** (read-only — paste into the browser console). Lists every element the glass
-rules match, the matched rule text and its computed values:
-
-```js
-(() => {
-  const rules = []
-  for (const ss of document.styleSheets) {
-    let rs; try { rs = ss.cssRules } catch { continue }
-    for (const r of rs) if (r.selectorText && r.selectorText.includes('dsh-glass')) rules.push(r)
-  }
-  const out = []
-  for (const el of document.querySelectorAll('[class*="card"],[class*="panel"],[role="tooltip"]')) {
-    const hit = rules.filter(r => { try { return el.matches(r.selectorText) } catch { return false } })
-    if (!hit.length) continue
-    const cs = getComputedStyle(el), b = el.getBoundingClientRect()
-    if (b.width < 8 || b.height < 8) continue
-    out.push({ cls: String(el.className).slice(0, 48), w: Math.round(b.width), h: Math.round(b.height),
-               bf: cs.backdropFilter, bg: cs.backgroundColor,
-               rule: hit.map(x => x.style.cssText).join(' | ').slice(0, 60) })
-  }
-  console.table(out.slice(0, 40))
-})()
-```
-
-**2. Stop the bleeding locally.** The plugin has **no** "custom CSS" option (DSH's profile patch
-layer can only write plugin `config` — there is no generic style entry point), so this needs an
-external injector: a browser extension (Stylus / Violentmonkey) or DevTools Overrides with an
-`!important` rule, e.g.
-
-```css
-[class*='yourRow'] { backdrop-filter: none !important; background: none !important; outline: none !important; }
-```
-
-**3. Report it.** Paste step 1's output plus your DSH and plugin versions into
-[issues](https://github.com/NoNameLeGo/dsh-catppuccin-theme/issues). That is how `0.5.8` was built:
-the reporter supplied per-element computed values and we narrowed the **defaults** — which is also
-why there is no "custom CSS" option: the default should be right first, an escape hatch is only a
-supplement.
+**A new class name in a third-party plugin can still be misread.** When you hit one, work through three
+steps: **① collect evidence** (a probe snippet you paste into the console, listing every matched element
+and rule) → **② temporary relief** (inject an `!important` override from outside; this plugin
+deliberately ships **no** "custom CSS" option) → **③ report** (attach the evidence plus your DSH and
+plugin versions to [issues](https://github.com/NoNameLeGo/dsh-catppuccin-theme/issues)).
+The full write-up, the probe snippet and the history (#16 / #17 / #19) live in
+[docs/glass-mis-hits.md](docs/glass-mis-hits.md).
 
 ### Environment limit: glass needs a see-through base from the host
 
@@ -393,53 +375,18 @@ The machine-readable form of the above is `dsh.compatibility` (`dsh` / `dshRelea
 ## Development
 
 ```sh
-pnpm install
-pnpm typecheck       # tsc --noEmit: type check for src
-pnpm typecheck:tests # tsc --noEmit: type check for the specs (vitest transpiles, it never type checks)
-pnpm test            # vitest palette-coverage tests
-pnpm build           # tsdown build -> lib/index.js (host) + lib/client.js (browser)
-```
-
-Palettes are produced by a generator script — after editing
-`scripts/generate-palettes.mjs`, rerun:
-
-```sh
-node scripts/generate-palettes.mjs
-```
-
-The changelog draft is generated from your conventional commits (bilingual `EN:` support
-in commit bodies):
-
-```sh
-pnpm changelog:gen            # print the draft since the last tag
-pnpm changelog:gen -- --write # write it into the [Unreleased] section
-```
-
-TypeDoc docs for the public API (`./client`, `./tui-themes` subpath exports) are generated
-locally on demand into `docs/api/` (that directory is **not** committed — it's in
-`.gitignore`; wire up CI Pages publishing later if an online copy is ever wanted):
-
-```sh
-pnpm docs:api
-```
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution guide and
-[docs/state-migrations.md](docs/state-migrations.md) for the state versioning contract.
-
-### Local link debugging
-
-Clone the repo, link it into a profile and add it to the bundles (use your own paths;
-`$DSH_HOME` defaults to `~/.dsh`):
-
-```sh
-pnpm --dir ~/.dsh/profiles/web add link:/path/to/dsh-catppuccin
-# Windows example:
-# pnpm --dir C:\Users\<you>\.dsh\profiles\web add link:D:\dev\dsh-catppuccin
+pnpm install          # install dependencies
+pnpm typecheck        # tsc --noEmit for src
+pnpm typecheck:tests  # tsc --noEmit for tests
+pnpm test             # vitest
+pnpm build            # tsdown -> lib/index.js (host) + lib/client.js (browser)
 ```
 
-Then add `@nonamelego/dsh-catppuccin` to the profile's `package.json`
-`dsh.profile.bundles` and restart `dsh web`. For DSH Desktop use
-`~/.dsh/profiles/desktop` instead.
+The palette table is generated by `scripts/generate-palettes.mjs` — **never hand-edit**
+`src/client/palettes.ts`; CHANGELOG drafts come from `pnpm changelog:gen`.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full command list, the generators, typedoc and local
+link debugging; state-contract migration rules are in
+[docs/state-migrations.md](docs/state-migrations.md).
 
 ## 🙋 FAQ
 
@@ -459,8 +406,12 @@ Then add `@nonamelego/dsh-catppuccin` to the profile's `package.json`
   A: Settings → General → **Check Catppuccin plugin updates** compares against npm in one
   click and gives a copyable upgrade command; or run
   `dsh plugin --profile web update @nonamelego/dsh-catppuccin` manually (re-`add` the
-  latest version works too). In [DSH Desktop](https://github.com/anywhere-labs/deepseek-harness-desktop),
-  use `desktop` as the profile name, or just run `dsh plugin update` in the app's DSH terminal.
+  latest version works too). **Desktop depends on which shell you use**: the community
+  [DSH Desktop](https://github.com/anywhere-labs/dsh-desktop) runs that same command in the app's own
+  DSH terminal (with `desktop` as the profile name), while the **official shell has no upgrade entry
+  point** — **remove the plugin in its plugin UI, then enter the package name
+  `@nonamelego/dsh-catppuccin` again to reinstall**, and restart the app. The two routes are not
+  interchangeable; see the table under Install → Desktop.
 
 ## 💝 Credits
 

package/README.md

@@ -117,25 +117,27 @@ dsh plugin --profile web add @nonamelego/dsh-catppuccin
 装完重启 `dsh web` 即可，`dsh plugin` 会自动把它加进 profile 的 bundles。
 其他 profile 把命令里的 `web` 换成对应名字即可（如 `headless`）。
 
-**桌面版**：桌面端默认激活的 profile 就叫 `desktop`（`$DSH_HOME/profiles/desktop`），
-把命令里的 `web` 换成 `desktop` 即可：
+**桌面版**：官方桌面壳与社区桌面壳都读**同一个 profile** `$DSH_HOME/profiles/desktop`，但
+**两者装/升插件的方式完全不同、也不通用**——按你用的壳选一列：
 
-```sh
-dsh plugin --profile desktop add @nonamelego/dsh-catppuccin
-```
+| | 官方桌面壳（[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 客户端） | 社区桌面壳（[DSH Desktop](https://github.com/anywhere-labs/dsh-desktop)） |
+|---|---|---|
+| **安装** | 应用内的**插件界面** → 添加插件 → 填包名 `@nonamelego/dsh-catppuccin`（也接受 Git 地址 / 压缩包 / 本地路径） | 在打开的 **终端**里执行命令：<br>`dsh plugin --profile desktop add @nonamelego/dsh-catppuccin` |
+| **升级** | **先在插件界面里把插件删除，再重新填一遍同一个包名安装**（v0.2.0 没有升级入口，也没有版本选择器） | 与 web 类似的更新命令：<br>`dsh plugin --profile desktop update @nonamelego/dsh-catppuccin` |
+| 谁执行 pnpm | 应用自带的 pnpm | 应用自带的 pnpm |
 
-在桌面的 **DSH 终端**里运行即可（`dsh plugin` 默认作用于当前激活的 profile，
-若在托盘里选了别的 profile 就换成那个名字），装完**重启桌面应用**生效。
-从仓库安装的方式同理：`dsh plugin --profile desktop add https://github.com/NoNameLeGo/dsh-catppuccin-theme`。
+两种方式改完都要**重启桌面应用**才会加载新版本。
 
-> **两个桌面壳，同一个 profile**：官方 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
-> 仓库里的 `apps/desktop` / `apps/desktop-host`（Electron，仍在开发中）与社区的
-> [DSH Desktop](https://github.com/anywhere-labs/deepseek-harness-desktop) 都启动
-> `$DSH_HOME/profiles/desktop`，所以**上面的命令对两者都成立**。本插件的桌面支持以
+> ⚠️ **两列别混用**：官方壳的插件界面不执行命令；社区壳那条 `update` 命令对官方壳也不适用。
+> 另外，**系统 PATH 上那个普通 `dsh` 两个壳都管不了 `desktop`**——上游把 `desktop` 当自己保留的
+> profile，会直接报 `error: profile "desktop" is managed exclusively by the Electron application`。
+> 想用 CLI 管就用别的 profile 名（`web`、`headless`、`dsh-tui`）。
+
+> 本插件的桌面支持以
 > **官方 web + 官方 desktop** 为维护核心；社区壳的 `desktopProfiles` 服务探测也保留。
 > 但官方壳的 profile 进程**没有**专用的环境标记（它的 `DSH_DESKTOP_NODE_EXECUTABLE` 只注入给
 > 包安装子进程），所以本插件改为识别 **Electron-as-node 运行时**（`process.versions.electron`）
-> 来判定官方桌面版——升级提示里的 profile 名与文案因此是对的；设置的读写不受影响。
+> 来判定官方桌面版；设置的读写不受影响。
 
 ### 方式二：从仓库安装
 
@@ -146,6 +148,9 @@ dsh plugin --profile web add https://github.com/NoNameLeGo/dsh-catppuccin-theme
 从 git 安装时 pnpm 可能要求允许构建脚本——按 pnpm 的提示把对应包加进 profile
 `pnpm-workspace.yaml` 的 `allowBuilds` 后重跑一次即可。
 
+桌面版同理，但按上面的表走：**官方壳**在插件界面里直接填 Git 地址；**社区壳**把这条命令的
+`dsh plugin --profile web add …` 换成 `dsh plugin --profile desktop add …`。
+
 ### dsh-TUI（终端版）主题
 
 与 Web GUI 插件同一个包。用标准的插件安装命令装进 dsh-tui profile：
@@ -175,7 +180,7 @@ dsh plugin --profile dsh-tui add https://github.com/NoNameLeGo/dsh-catppuccin-th
 
 ## 使用
 
-1. 打开 Web GUI（默认 `http://127.0.0.1:3080`）；在 [DSH Desktop](https://github.com/anywhere-labs/deepseek-harness-desktop) 中则直接打开桌面应用即可。
+1. 打开 Web GUI（默认 `http://127.0.0.1:3080`）；在 [DSH Desktop](https://github.com/anywhere-labs/dsh-desktop) 中则直接打开桌面应用即可。
 2. 进入 **设置 → 常规**。
 3. 在 **外观** 区域下方找到 **Catppuccin** 行，选择主题：
    **Latte**（浅色）、**Frappé**、**Macchiato** 或 **Mocha**（深色）。
@@ -224,6 +229,11 @@ dsh plugin --profile dsh-tui add https://github.com/NoNameLeGo/dsh-catppuccin-th
   命令，会提示改用 `git pull` 或重新构建。
 - 通道策略：正式版只跟随 `latest` 标签；预发布版同时跟随 `beta`（升级命令
   自动带 `@beta`）。离线或网络失败时显示原因并可重试。
+- 升级路径按**宿主**分流：**官方桌面版**（DeepSeek Harness 客户端）不给命令行——
+  它没有可达的终端入口，所以这一行改为给出 **`包名@渠道`** 并提示在
+  **插件界面**里先删除、再重新安装（与上面「桌面版」段的升级路径一致）；
+  **社区桌面壳**与 **web** 仍照常给出可复制的 `dsh plugin …` 命令。
+  判定由宿主完成（`web` / `community-desktop` / `official-desktop`），无需你选。
 
 ## 玻璃拟态（Glassmorphism）
 
@@ -244,65 +254,24 @@ dsh plugin --profile dsh-tui add https://github.com/NoNameLeGo/dsh-catppuccin-th
   变色；页面底色取当前主题纯色，背景亮度旋钮直接往纯色里调和白/黑；
 - **一键开关**：关闭即完全还原原生界面，插件卸载不留任何残留。
 
-### 兼容模式会命中哪些面
+### 兼容模式误命中了别的面？
 
-兼容模式靠**类名子串与语义属性**给宿主与第三方插件的悬浮面加玻璃，不需要任何插件配合——
+兼容模式靠**类名子串与语义属性**给宿主与第三方插件的悬浮面加玻璃，不需要插件配合——
 代价是子串匹配**无法区分「面」与「面里的行级容器」**。自 `0.5.8` 起，明确会被命中的族只剩这些：
 
 | 族 | 锚点 |
 |---|---|
-| 输入框卡片 | `[data-composer-card]`（宿主自己的属性；材质画在它的 `::before` 上，见 issue #19） |
+| 输入框卡片 | `[data-composer-card]`（材质画在它的 `::before` 上，见 issue #19） |
 | 菜单 | `[role='menu']` |
-| 弹出层 | `[class*='popover']` / `[class*='dropdown']`（这两个仍是子串） |
+| 弹出层 | `[class*='popover']` / `[class*='dropdown']`（仍是子串） |
 | 模态框 | `[role='dialog'][aria-modal='true']` |
 | 宿主右侧栏（仅展开态） | `[data-sidebar-right-panel][data-sidebar-right-open]` |
 
-`0.5.8` 按证据把最宽的三族收窄掉了（宽泛的 `card` 子串、`panel` 子串、行级 tooltip，详见
-issue #17），但**第三方插件里新出现的类名仍可能被误命中**。默认收窄要讲证据，遇到时走下面三步。
-
-#### 1. 取证（只读，粘进浏览器控制台）
-
-列出当前所有被玻璃规则命中的元素、命中的规则原文与 computed 值：
-
-```js
-(() => {
-  const rules = []
-  for (const ss of document.styleSheets) {
-    let rs; try { rs = ss.cssRules } catch { continue }
-    for (const r of rs) if (r.selectorText && r.selectorText.includes('dsh-glass')) rules.push(r)
-  }
-  const out = []
-  for (const el of document.querySelectorAll('[class*="card"],[class*="panel"],[role="tooltip"]')) {
-    const hit = rules.filter(r => { try { return el.matches(r.selectorText) } catch { return false } })
-    if (!hit.length) continue
-    const cs = getComputedStyle(el), b = el.getBoundingClientRect()
-    if (b.width < 8 || b.height < 8) continue
-    out.push({ cls: String(el.className).slice(0, 48), w: Math.round(b.width), h: Math.round(b.height),
-               bf: cs.backdropFilter, bg: cs.backgroundColor,
-               rule: hit.map(x => x.style.cssText).join(' | ').slice(0, 60) })
-  }
-  console.table(out.slice(0, 40))
-})()
-```
-
-#### 2. 临时止血
-
-本插件**没有**「自定义 CSS」配置项（DSH 的 profile patch 层只能给插件写 `config`，没有通用样式入口；
-但**个别第三方插件自带样式入口**，例如 `dsh-better-sidebar@0.21.1` 的 `customCss`——它 gate 在自身的
-`titleBarScheme: 'custom'` 上、以 `data-dsh-custom-css` 注入，装了这类插件时也可以直接写在它的 `config` 里），
-所以这一步要用外部注入——浏览器扩展（Stylus / 暴力猴）或 DevTools 的 Overrides——加一条
-`!important` 规则把该族还原，例如：
-
-```css
-[class*='yourRow'] { backdrop-filter: none !important; background: none !important; outline: none !important; }
-```
-
-#### 3. 反馈
-
-把第 1 步的表格输出连同 DSH 与插件版本贴到
-[issues](https://github.com/NoNameLeGo/dsh-catppuccin-theme/issues)。`0.5.8` 就是这么修出来的：
-报告人给了逐元素的 computed 对照，我们据此收窄**默认**规则——这也是为什么没有「自定义 CSS」
-配置项：默认行为应该先是对的，配置项只能当补充。
+**第三方插件里新出现的类名仍可能被误命中**。遇到时走三步：**① 只读取证**（一段粘进控制台的探针脚本，
+列出命中的元素与规则）→ **② 临时止血**（外部注入一条 `!important` 还原；本插件**不**提供
+「自定义 CSS」配置项）→ **③ 反馈**（把取证输出连同 DSH 与插件版本提到
+[issues](https://github.com/NoNameLeGo/dsh-catppuccin-theme/issues)）。
+三步的完整说明、探针脚本与历史（#16 / #17 / #19）见 [docs/glass-mis-hits.md](docs/glass-mis-hits.md)。
 
 ### 环境限制：玻璃需要宿主提供可透出的底色
 
@@ -364,51 +333,17 @@ alias 101 / specific 11 / 非三族 1）全覆盖，含 0.2.0 新增的 17 个 a
 ## 开发
 
 ```sh
-pnpm install
-pnpm typecheck       # tsc --noEmit：src 的类型检查
-pnpm typecheck:tests # tsc --noEmit：tests 的类型检查（vitest 跑 esbuild，不做类型检查）
-pnpm test            # vitest 跑配色表 / 契约 / e2e 覆盖测试
-pnpm build           # tsdown 构建 -> lib/index.js（服务端）+ lib/client.js（浏览器）
-```
-
-配色表由生成器脚本产出——修改 `scripts/generate-palettes.mjs` 后重跑
-（`--pin <sha>` 可把上游 commit SHA 写进 `palettes.ts` 头部，见
-`docs/plugin-improvements.md` 的 L 项）：
-
-```sh
-node scripts/generate-palettes.mjs [--pin <upstream-sha>]
-```
-
-CHANGELOG 草稿由 conventional 提交生成（提交正文里的 `EN:` 行会被渲染成英文摘要）：
-
-```sh
-pnpm changelog:gen            # 打印上一 tag 之后的草稿
-pnpm changelog:gen -- --write # 直接写入 [Unreleased] 节
-```
-
-对外 API（`./client`、`./tui-themes` 子路径导出）的 typedoc 文档**按需本地生成**到
-`docs/api/`（该目录不入库、已进 `.gitignore`；哪天真需要在线版本再接 CI 发布）：
-
-```sh
-pnpm docs:api
-```
-
-贡献指南见 [CONTRIBUTING.md](CONTRIBUTING.md)；状态契约的版本迁移约定见
-[docs/state-migrations.md](docs/state-migrations.md)。
-
-### 本地链接调试
-
-克隆到本地后，把包链接进 profile（把路径换成你自己的；`$DSH_HOME` 默认是 `~/.dsh`）：
-
-```sh
-pnpm --dir ~/.dsh/profiles/web add link:/path/to/dsh-catppuccin
-# Windows 例：
-# pnpm --dir C:\Users\<you>\.dsh\profiles\web add link:D:\dev\dsh-catppuccin
+pnpm install          # 装依赖
+pnpm typecheck        # tsc --noEmit：src 的类型检查
+pnpm typecheck:tests  # tsc --noEmit：tests 的类型检查
+pnpm test             # vitest
+pnpm build            # tsdown -> lib/index.js（服务端）+ lib/client.js（浏览器）
 ```
 
-再把 `@nonamelego/dsh-catppuccin` 加进 profile `package.json` 的
-`dsh.profile.bundles`，重启 `dsh web`。DSH Desktop 用
-`~/.dsh/profiles/desktop` 对应路径。
+配色表由 `scripts/generate-palettes.mjs` 生成，**不要手改** `src/client/palettes.ts`；
+CHANGELOG 草稿由 `pnpm changelog:gen` 从 conventional 提交里产出。
+完整命令清单、生成器与 typedoc、本地 link 调试见 [CONTRIBUTING.md](CONTRIBUTING.md)；
+状态契约的版本迁移约定见 [docs/state-migrations.md](docs/state-migrations.md)。
 
 ## 🙋 常见问题
 
@@ -436,9 +371,11 @@ pnpm --dir ~/.dsh/profiles/web add link:/path/to/dsh-catppuccin
   A: 设置 → 常规 → **检查 Catppuccin 插件更新** 一键检测本插件在 npm 上的最新版本，
   发现新版会给出可复制的升级命令；也可以随时手动执行
   `dsh plugin --profile web update @nonamelego/dsh-catppuccin`
-  （或重新 `add` 最新版）。在 [DSH Desktop](https://github.com/anywhere-labs/deepseek-harness-desktop) 中，把 `web` 换成 `desktop`
-  （`dsh plugin --profile desktop update @nonamelego/dsh-catppuccin`），
-  或者直接在 DSH 终端里运行 `dsh plugin update`（默认作用于当前 profile）。
+  （或重新 `add` 最新版）。
+  **桌面版要分壳**：社区壳 [DSH Desktop](https://github.com/anywhere-labs/dsh-desktop) 在应用内的
+  DSH 终端里用同一条命令（把 `web` 换成 `desktop`）；**官方壳没有升级入口**——要在插件界面里
+  **先删掉本插件，再重新填一遍包名 `@nonamelego/dsh-catppuccin` 安装**，然后重启应用。
+  两种方式不通用，详见上面「安装 → 桌面版」的对照表。
 
 ## 💝 致谢
 

package/lib/client.js

@@ -547,9 +547,11 @@ window.__ModuleLoader__.load({
 			"update.commandHint": "在终端运行以下命令升级（把 web 换成你的 profile 名）：",
 			"update.commandHintDetected": "已自动探测到 profile「{profile}」，在终端运行以下命令升级：",
 			"update.commandHintDesktop": "已检测到你在使用 DSH Desktop，目标 profile「{profile}」，请在 DSH 终端中运行以下命令升级：",
+			"update.commandHintOfficialDesktop": "已检测到官方桌面版（DeepSeek Harness 客户端）：它没有命令行升级入口——请在**插件界面**里先删除本插件，再把下面的包名粘进「添加插件」重新安装。",
 			"update.restartHint": "升级完成后重启 dsh web 生效。",
 			"update.restartHintDesktop": "升级完成后重启 DSH Desktop 生效。",
 			"update.copy": "复制命令",
+			"update.copySpec": "复制包名",
 			"update.copied": "已复制 ✓",
 			"update.failed": "检查失败，请稍后重试。",
 			"update.retry": "重试",
@@ -622,9 +624,11 @@ window.__ModuleLoader__.load({
 			"update.commandHint": "Run this in a terminal to upgrade (replace web with your profile name):",
 			"update.commandHintDetected": "Profile \"{profile}\" detected — run this in a terminal to upgrade:",
 			"update.commandHintDesktop": "DSH Desktop detected — target profile \"{profile}\", run this in the DSH terminal to upgrade:",
+			"update.commandHintOfficialDesktop": "Official desktop build detected (DeepSeek Harness client) — it has no CLI upgrade path: delete this plugin on the **Plugins** page, then paste the package name below into \"Add plugin\" to reinstall.",
 			"update.restartHint": "Restart dsh web after the upgrade.",
 			"update.restartHintDesktop": "Restart DSH Desktop after the upgrade.",
 			"update.copy": "Copy command",
+			"update.copySpec": "Copy package name",
 			"update.copied": "Copied ✓",
 			"update.failed": "Check failed — try again later.",
 			"update.retry": "Retry",
@@ -697,9 +701,11 @@ window.__ModuleLoader__.load({
 			"update.commandHint": "ターミナルで以下を実行してアップグレード（web をあなたの profile 名に変更）:",
 			"update.commandHintDetected": "profile「{profile}」を検出。ターミナルで以下を実行してアップグレード:",
 			"update.commandHintDesktop": "DSH Desktop を検出。target profile「{profile}」、DSH ターミナルで以下を実行:",
+			"update.commandHintOfficialDesktop": "公式デスクトップ版（DeepSeek Harness クライアント）を検出: CLI からのアップグレード経路はありません——**プラグイン画面**で本プラグインを先に削除し、下のパッケージ名を「プラグインを追加」に貼り付けて再インストールしてください。",
 			"update.restartHint": "アップグレード後、dsh web を再起動してください。",
 			"update.restartHintDesktop": "アップグレード後、DSH Desktop を再起動してください。",
 			"update.copy": "コマンドをコピー",
+			"update.copySpec": "パッケージ名をコピー",
 			"update.copied": "コピーしました ✓",
 			"update.failed": "確認に失敗しました。後で再試行してください。",
 			"update.retry": "再試行",
@@ -772,9 +778,11 @@ window.__ModuleLoader__.load({
 			"update.commandHint": "터미널에서 다음을 실행해 업그레이드하세요 (web을 당신의 profile 이름으로 교체):",
 			"update.commandHintDetected": "profile「{profile}」을 감지했습니다. 터미널에서 다음을 실행하세요:",
 			"update.commandHintDesktop": "DSH Desktop 감지. 대상 profile「{profile}」, DSH 터미널에서 다음을 실행하세요:",
+			"update.commandHintOfficialDesktop": "공식 데스크톱 버전(DeepSeek Harness 클라이언트)을 감지했습니다: CLI 업그레이드 경로가 없습니다——**플러그인 화면**에서 이 플러그인을 먼저 삭제한 뒤 아래 패키지 이름을 「플러그인 추가」에 붙여 다시 설치하세요.",
 			"update.restartHint": "업그레이드 후 dsh web을 재시작하세요.",
 			"update.restartHintDesktop": "업그레이드 후 DSH Desktop을 재시작하세요.",
 			"update.copy": "명령 복사",
+			"update.copySpec": "패키지 이름 복사",
 			"update.copied": "복사됨 ✓",
 			"update.failed": "확인 실패. 잠시 후 다시 시도하세요.",
 			"update.retry": "다시 시도",
@@ -847,9 +855,11 @@ window.__ModuleLoader__.load({
 			"update.commandHint": "Ejecuta esto en una terminal para actualizar (sustituye web por el nombre de tu profile):",
 			"update.commandHintDetected": "Profile \"{profile}\" detectado: ejecuta esto en una terminal para actualizar:",
 			"update.commandHintDesktop": "DSH Desktop detectado: profile objetivo \"{profile}\", ejecuta esto en la terminal de DSH:",
+			"update.commandHintOfficialDesktop": "Se detectó la versión oficial de escritorio (cliente DeepSeek Harness): no tiene ruta de actualización por CLI; elimina este plugin en la página **Plugins** y pega el nombre del paquete de abajo en «Añadir plugin» para reinstalarlo.",
 			"update.restartHint": "Reinicia dsh web tras la actualización.",
 			"update.restartHintDesktop": "Reinicia DSH Desktop tras la actualización.",
 			"update.copy": "Copiar comando",
+			"update.copySpec": "Copiar nombre del paquete",
 			"update.copied": "Copiado ✓",
 			"update.failed": "Error al comprobar; inténtalo de nuevo más tarde.",
 			"update.retry": "Reintentar",
@@ -922,9 +932,11 @@ window.__ModuleLoader__.load({
 			"update.commandHint": "Exécutez ceci dans un terminal pour mettre à jour (remplacez web par le nom de votre profile) :",
 			"update.commandHintDetected": "Profile « {profile} » détecté — exécutez ceci dans un terminal :",
 			"update.commandHintDesktop": "DSH Desktop détecté — profile cible « {profile} », exécutez ceci dans le terminal DSH :",
+			"update.commandHintOfficialDesktop": "Version bureau officielle détectée (client DeepSeek Harness) : aucune mise à jour en ligne de commande — supprimez ce plugin dans la page **Plugins**, puis collez le nom du paquet ci-dessous dans « Ajouter un plugin » pour le réinstaller.",
 			"update.restartHint": "Redémarrez dsh web après la mise à jour.",
 			"update.restartHintDesktop": "Redémarrez DSH Desktop après la mise à jour.",
 			"update.copy": "Copier la commande",
+			"update.copySpec": "Copier le nom du paquet",
 			"update.copied": "Copié ✓",
 			"update.failed": "Échec de la vérification — réessayez plus tard.",
 			"update.retry": "Réessayer",
@@ -997,9 +1009,11 @@ window.__ModuleLoader__.load({
 			"update.commandHint": "Führen Sie dies in einem Terminal aus (ersetzen Sie web durch Ihren Profile-Namen):",
 			"update.commandHintDetected": "Profile „{profile}“ erkannt – führen Sie dies in einem Terminal aus:",
 			"update.commandHintDesktop": "DSH Desktop erkannt – Ziel-Profile „{profile}“, führen Sie dies im DSH-Terminal aus:",
+			"update.commandHintOfficialDesktop": "Offizielle Desktop-Version erkannt (DeepSeek Harness-Client): Es gibt keinen CLI-Upgradepfad – löschen Sie dieses Plugin auf der Seite **Plugins** und fügen Sie den Paketnamen unten in „Plugin hinzufügen“ ein, um es neu zu installieren.",
 			"update.restartHint": "Starten Sie dsh web nach dem Update neu.",
 			"update.restartHintDesktop": "Starten Sie DSH Desktop nach dem Update neu.",
 			"update.copy": "Befehl kopieren",
+			"update.copySpec": "Paketnamen kopieren",
 			"update.copied": "Kopiert ✓",
 			"update.failed": "Prüfung fehlgeschlagen – versuchen Sie es später erneut.",
 			"update.retry": "Erneut versuchen",
@@ -3027,6 +3041,8 @@ window.__ModuleLoader__.load({
 			const autoResult = lastAutoResult();
 			const localInstall = payload?.ok === true && payload.installSource !== void 0 && payload.installSource !== "registry";
 			const isDesktop = payload?.ok === true && payload.env === "desktop";
+			const officialDesktop = payload?.ok === true && payload.shell === "official-desktop";
+			const upgradeValue = payload?.ok === true ? officialDesktop ? payload.updateSpec : payload.updateCommand : void 0;
 			const showConflict = conflicts > dismissedConflicts;
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 				style: {
@@ -3273,14 +3289,14 @@ window.__ModuleLoader__.load({
 									" ",
 									/* @__PURE__ */ (0, react_jsx_runtime.jsx)("strong", { children: payload.latest })
 								]
-							}), payload.updateCommand !== void 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [
+							}), upgradeValue !== void 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [
 								/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 									style: {
 										color: "var(--dsw-alias-label-tertiary)",
 										fontSize: 12,
 										lineHeight: "18px"
 									},
-									children: isDesktop ? t("update.commandHintDesktop").replace("{profile}", payload.profile ?? "") : payload.profileDetected === true && payload.profile !== void 0 ? t("update.commandHintDetected").replace("{profile}", payload.profile) : t("update.commandHint")
+									children: officialDesktop ? t("update.commandHintOfficialDesktop") : isDesktop ? t("update.commandHintDesktop").replace("{profile}", payload.profile ?? "") : payload.profileDetected === true && payload.profile !== void 0 ? t("update.commandHintDetected").replace("{profile}", payload.profile) : t("update.commandHint")
 								}),
 								/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 									style: {
@@ -3304,17 +3320,17 @@ window.__ModuleLoader__.load({
 											textOverflow: "ellipsis",
 											fontFamily: "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace"
 										},
-										children: payload.updateCommand
+										children: upgradeValue
 									}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
 										type: "button",
 										onClick: () => {
-											copyCommand(payload.updateCommand ?? "").then(setCopied);
+											copyCommand(upgradeValue).then(setCopied);
 										},
 										style: {
 											...buttonStyle,
 											cursor: "pointer"
 										},
-										children: copied ? t("update.copied") : t("update.copy")
+										children: copied ? t("update.copied") : t(officialDesktop ? "update.copySpec" : "update.copy")
 									})]
 								}),
 								localInstall && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {