xrkh-better-sidebar 0.17.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 xrkseek
+Copyright (c) 2026 dsh-external
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# xrkh-better-sidebar
+
+> **读者**：XRK-Harness 终端用户 · 集成者
+
+XRK-Harness（`xrkh`）标准侧边栏插件：资源管理器 · 编辑器 · 终端 · Git · 浏览器等工作台，按会话隔离。  
+Host 侧 `/sidebar/*` 由产品内置兼容器接线；本包提供 **client 半包**（及可选进程清单）。
+
+## 安装
+
+前置：`xrkh web` 或 `npx @xrkseek/harness-cli web`，Node ≥ 26。
+
+```bash
+xrkh plugin add xrkh-better-sidebar@latest
+xrkh restart
+```
+
+从源码（SSH）：
+
+```bash
+git clone git@github.com:xrkseek/xrkh-better-sidebar.git
+xrkh plugin add ./xrkh-better-sidebar
+xrkh restart
+```
+
+装完硬刷新浏览器（Ctrl+Shift+R）。
+
+## 契约
+
+| 项 | 说明 |
+|----|------|
+| npm | `xrkh-better-sidebar` |
+| 仓库 | `xrkseek/xrkh-better-sidebar` |
+| 清单 | `xrk.client`（`package.json`）· `xrk.plugin.json` |
+| 注入 | `@xrkseek/client-runtime` · `client-locale` · `client-ui-slots` · `client-ui-conversation` · `client-modules` |
+| Host | 产品 `dsh-compat` 提供 `/sidebar/api` · `/sidebar/bundle` · PTY 等 |
+
+## 开发
+
+```bash
+pnpm install
+pnpm bundle
+```

package/README_EN.md

@@ -0,0 +1,42 @@
+# xrkh-better-sidebar
+
+> **Audience**: XRK-Harness end users · integrators
+
+Standard sidebar plugin for XRK-Harness (`xrkh`): explorer · editor · terminal · git · browser, isolated per session.  
+Host serves `/sidebar/*` via the product adapter; this package ships the **client** half (and optional process manifest).
+
+## Install
+
+Requires `xrkh web` or `npx @xrkseek/harness-cli web`, Node ≥ 26.
+
+```bash
+xrkh plugin add xrkh-better-sidebar@latest
+xrkh restart
+```
+
+From source (SSH):
+
+```bash
+git clone git@github.com:xrkseek/xrkh-better-sidebar.git
+xrkh plugin add ./xrkh-better-sidebar
+xrkh restart
+```
+
+Hard-refresh the browser after install (Ctrl+Shift+R).
+
+## Contract
+
+| Item | Notes |
+|------|--------|
+| npm | `xrkh-better-sidebar` |
+| Repo | `xrkseek/xrkh-better-sidebar` |
+| Manifest | `xrk.client` · `xrk.plugin.json` |
+| Inject | `@xrkseek/client-*` (runtime, locale, slots, conversation, modules) |
+| Host | Product adapter: `/sidebar/api` · `/sidebar/bundle` · PTY |
+
+## Develop
+
+```bash
+pnpm install
+pnpm bundle
+```

package/cordis.patch.yml

@@ -0,0 +1,49 @@
+# dsh-better-sidebar bundle patch
+#
+# This file is the `dsh.bundle.patch` layer of the published npm package: when
+# the plugin is installed through the official CLI —
+#
+#   dsh plugin --profile <name> add dsh-better-sidebar@<version>
+#
+# — the command reconciles `dsh.profile.bundles` against installed packages
+# and, seeing this declaration, appends `dsh-better-sidebar` to the bundle
+# stack. The profile boot then merges THIS patch (a single `insert` of the
+# plugin row) exactly like the manual cordis.patch.yml mount line used
+# before. No profile file edits needed — one command installs and mounts.
+#
+# If the profile still carries the old manual mount line in its own
+# cordis.patch.yml, remove it before switching to the bundle channel to
+# avoid double-mounting (two Node halves, two sidebars).
+#
+# To choose the terminal shell, add `config.shell` to the inserted plugin
+# row (or to the profile's manual cordis.patch.yml mount line). When omitted,
+# the host keeps resolving $SHELL / the login shell / powershell.exe.
+# `config.shellArgs` optionally supplies explicit startup arguments; when
+# non-empty they replace the automatic POSIX `-l` login flag:
+#
+#   - insert:
+#       - id: better-sidebar
+#         name: 'dsh-better-sidebar'
+#         config:
+#           shell: /bin/zsh
+#           shellArgs:
+#             - --noprofile
+#             - --no-rc
+#
+# Aggregate double-mount guard: aggregate bundles (e.g. @linxin666/dsh-web-ui-all)
+# may already mount this package under their own entry id (e.g.
+# `web-ui-better-sidebar`). Two mounts register /sidebar/api twice and fail the
+# whole plugin tree at boot ("duplicate prefix route"). The `!!js` disabled
+# expression backs THIS row off when another *enabled* entry already mounts
+# `dsh-better-sidebar`; the aggregate instance then owns the sidebar. The
+# loader evaluates it when this row is processed (entry-list order, only rows
+# before this one are visible), so the aggregate bundle must precede this one
+# in `dsh.profile.bundles` — the standard install order, since `dsh plugin add`
+# appends new bundles last. The reverse order (this bundle before the
+# aggregate) is a known limitation: the guard cannot see rows that come after
+# it, and no runtime singleton guard is added. Same-id manual duplicates still
+# fail loudly at the loader as before.
+- insert:
+    - id: better-sidebar
+      name: 'dsh-better-sidebar'
+      disabled: !!js "[...ctx.loader.entries()].some((e) => e.options.name === 'dsh-better-sidebar' && e.options.id !== 'better-sidebar' && !e.disabled)"

package/package.json

@@ -0,0 +1,182 @@
+{
+  "name": "xrkh-better-sidebar",
+  "version": "0.17.1",
+  "description": "XRK-Harness (xrkh) standard sidebar plugin: explorer, editor, terminal, git, browser.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/xrkseek/xrkh-better-sidebar.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./client/service": {
+      "types": "./lib/types/client/service.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./client/api": {
+      "types": "./lib/types/client/service.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=26"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/client-registry.js",
+    "lib/client-terminal.js",
+    "lib/client-editor.js",
+    "lib/client-mermaid.js",
+    "lib/types/**/*.d.ts",
+    "src",
+    "scripts/install.sh",
+    "scripts/install.ps1",
+    "cordis.patch.yml",
+    "README.md",
+    "README_EN.md",
+    "LICENSE",
+    "scripts/install-xrkh.ps1",
+    "scripts/install-xrkh.sh",
+    "xrk.plugin.json"
+  ],
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('lib',{recursive:true,force:true})\" && tsc -p tsconfig.build.json && tsdown",
+    "typecheck": "tsc --noEmit",
+    "bundle": "tsdown",
+    "watch": "tsdown --watch",
+    "test": "vitest run",
+    "test:mount": "bash scripts/e2e-mount.sh",
+    "check:consumer-types": "bash scripts/check-consumer-types.sh"
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@xrkseek/cordis": "*",
+    "@xrkseek/client-locale": "*",
+    "@xrkseek/client-ui-conversation": "*",
+    "@xrkseek/client-ui-primitives": "*",
+    "@xrkseek/client-ui-settings": "^0.1.2-alpha.3",
+    "@xrkseek/client-ui-slots": "*",
+    "@xrkseek/xrk-invariants": "*",
+    "@huanlin/dsh-plugin-better-locale": "^0.1.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@huanlin/dsh-plugin-better-locale": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@codemirror/commands": "^6.10.4",
+    "@codemirror/lang-cpp": "^6.0.3",
+    "@codemirror/lang-css": "^6.3.1",
+    "@codemirror/lang-go": "^6.0.1",
+    "@codemirror/lang-html": "^6.4.12",
+    "@codemirror/lang-java": "^6.0.2",
+    "@codemirror/lang-javascript": "^6.2.5",
+    "@codemirror/lang-json": "^6.0.2",
+    "@codemirror/lang-markdown": "^6.5.2",
+    "@codemirror/lang-php": "^6.0.2",
+    "@codemirror/lang-python": "^6.2.1",
+    "@codemirror/lang-rust": "^6.0.2",
+    "@codemirror/lang-sql": "^6.10.0",
+    "@codemirror/lang-vue": "^0.1.3",
+    "@codemirror/lang-xml": "^6.1.0",
+    "@codemirror/lang-yaml": "^6.1.3",
+    "@codemirror/language": "^6.12.4",
+    "@codemirror/legacy-modes": "^6.5.3",
+    "@codemirror/search": "^6.7.1",
+    "@codemirror/state": "^6.7.1",
+    "@codemirror/view": "^6.43.8",
+    "@lezer/highlight": "^1.2.3",
+    "clsx": "^2.1.1",
+    "dompurify": "^3.4.14",
+    "mermaid": "^11.16.1",
+    "node-pty": "^1.1.0",
+    "react-icons": "5.7.0",
+    "rxjs": "^7.8.2",
+    "schemastery": "^3.18.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@cordisjs/plugin-loader": "^1.0.0-rc.5",
+    "@deepseek-ai/dsh-attachment": "0.1.2-alpha.3",
+    "@xrkseek/client-locale": "0.1.2-alpha.3",
+    "@xrkseek/client-ui-conversation": "0.1.2-alpha.3",
+    "@xrkseek/client-ui-primitives": "0.1.2-alpha.3",
+    "@xrkseek/client-ui-settings": "0.1.2-alpha.3",
+    "@xrkseek/client-ui-slots": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-code-runtime": "0.1.2-alpha.3",
+    "@xrkseek/xrk-invariants": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-scope": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-session-projection": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-system-prompt": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-user-approval": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-util-time": "0.1.2-alpha.3",
+    "@huanlin/dsh-plugin-better-locale": "^0.1.0",
+    "@playwright/test": "^1.62.1",
+    "@types/node": "^24.0.0",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.1",
+    "@types/ws": "^8.5.10",
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/xterm": "^5.5.0",
+    "cordis": "^4.0.0-rc.8",
+    "jsdom": "^29.1.1",
+    "lightningcss": "^1.32.0",
+    "react": "^18.2.0",
+    "react-dom": "18.2.0",
+    "tsdown": "^0.22.2",
+    "typescript": "^5.6.0",
+    "unrun": "^0.2.39",
+    "vitest": "^4.1.8"
+  },
+  "xrk": {
+    "client": {
+      "inject": [
+        "@xrkseek/client-runtime",
+        "@xrkseek/client-locale",
+        "@xrkseek/client-ui-slots",
+        "@xrkseek/client-ui-conversation",
+        "@xrkseek/client-modules"
+      ],
+      "platform": "web"
+    }
+  },
+  "dsh": {
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-modules"
+      ],
+      "platform": "web"
+    }
+  },
+  "bugs": {
+    "url": "https://github.com/xrkseek/xrkh-better-sidebar/issues"
+  },
+  "homepage": "https://github.com/xrkseek/xrkh-better-sidebar#readme"
+}

package/scripts/install-xrkh.ps1

@@ -0,0 +1,15 @@
+# One-shot install for XRK-Harness (Windows).
+param(
+  [string]$Version = "latest",
+  [switch]$Restart
+)
+$ErrorActionPreference = "Stop"
+$pkg = if ($Version -and $Version -ne "latest") { "xrkh-better-sidebar@$Version" } else { "xrkh-better-sidebar@latest" }
+if (Get-Command xrkh -ErrorAction SilentlyContinue) {
+  & xrkh plugin add $pkg
+  if ($Restart) { & xrkh restart }
+} else {
+  & npx -y @xrkseek/harness-cli plugin add $pkg
+  if ($Restart) { & npx -y @xrkseek/harness-cli restart }
+}
+Write-Host "Done. Hard-refresh the browser (Ctrl+Shift+R)."

package/scripts/install-xrkh.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -euo pipefail
+VERSION="${1:-latest}"
+PKG="xrkh-better-sidebar@${VERSION}"
+if command -v xrkh >/dev/null 2>&1; then
+  xrkh plugin add "$PKG"
+  xrkh restart
+else
+  npx -y @xrkseek/harness-cli plugin add "$PKG"
+  npx -y @xrkseek/harness-cli restart
+fi
+echo "Done. Hard-refresh the browser."

package/scripts/install.ps1

@@ -0,0 +1,306 @@
+## =============================================================================
+# dsh-better-sidebar 一键安装脚本（官方 CLI 方式，Windows PowerShell 5.1+ / pwsh）
+#
+# 通过 DSH 官方插件命令安装 npm 包并自动挂载：
+#   dsh plugin --profile web add dsh-better-sidebar@<version>
+#
+# 包内声明了 dsh.bundle.patch（cordis.patch.yml）：CLI 的 bundle 协调会把它
+# 自动加进 profile 的 dsh.profile.bundles，下次启动即挂载——无需手动写
+# cordis.patch.yml 挂载行。符合仓库硬约束：不修改 DSH 源码，插件永远作为
+# 独立包被 profile 引用。
+#
+# 用法（任选其一）：
+#   # 默认最新版
+#   $script = (irm 'https://raw.githubusercontent.com/omdsh-dev/DSH-better-sidebar/main/scripts/install.ps1').TrimStart([char]0xFEFF)
+#   & ([scriptblock]::Create($script))
+#   # 指定版本 / 装完重启
+#   $script = (irm 'https://raw.githubusercontent.com/omdsh-dev/DSH-better-sidebar/main/scripts/install.ps1').TrimStart([char]0xFEFF)
+#   & ([scriptblock]::Create($script)) -Version 0.10.2 -Restart
+#   # 本地保存后运行
+#   powershell -ExecutionPolicy Bypass -File install.ps1 -Version 0.10.2 -DryRun
+#   # 修复 node-pty 依赖（终端提示「node-pty 加载失败」时用，见 issue #140）
+#   powershell -ExecutionPolicy Bypass -File install.ps1 -Repair
+#
+# 参数：
+#   -Version    npm 版本号/范围，缺省 latest（自动解析为最新）。
+#   -Repair     修复模式：不重装插件，只确保 profile 的 pnpm-workspace.yaml
+#               放行 node-pty 构建脚本，然后重跑 pnpm install + pnpm rebuild
+#               node-pty。
+#   -Profile    目标 profile 名（缺省 web）；安装与修复模式均适用。
+#   -Restart    装完后尝试 `pm2 restart dsh-web`（无 pm2 时仅提示）。会断开当前页面会话。
+#   -DryRun     只打印将要执行的操作，不写任何文件。
+#
+# 环境变量（均可省略）：
+#   DSH_HOME    默认 %USERPROFILE%\.dsh
+#   REGISTRY    默认 https://registry.npmjs.org
+#   DSH_CMD     默认优先 PATH 上的 dsh，缺省回退 npx -y --package @deepseek-ai/dsh
+#
+# 说明：
+# - pnpm 11 的 strict-dep-builds 会拦截 node-pty/protobufjs 的构建脚本并使
+#   `dsh plugin add` 非零退出。脚本会先把这两个构建许可写进 profile 的
+#   pnpm-workspace.yaml（幂等），保证 CLI 一步成功。
+# - pnpm 11 的 minimumReleaseAge 会拒绝发布 <24h 的新版本。脚本会预写
+#   minimumReleaseAgeExclude（幂等），放行本插件，避免"重跑一次才成功"。
+# - 老版本（<0.10.2）用手动挂载行，bundle 通道激活后需移除，否则双挂载。
+#   脚本会幂等移除 better-sidebar 挂载行。
+# =============================================================================
+param(
+  [string]$Version = '',
+  [switch]$Restart,
+  [switch]$DryRun,
+  [switch]$Repair,
+  [string]$Profile = 'web'
+)
+
+$PKG = 'dsh-better-sidebar'
+$REGISTRY = if ($env:REGISTRY) { $env:REGISTRY } else { 'https://registry.npmjs.org' }
+
+# DSH_HOME：DSH_HOME 环境变量 > %USERPROFILE% > $HOME
+if ($env:DSH_HOME) {
+  $DSH_HOME = $env:DSH_HOME
+} elseif ($env:USERPROFILE) {
+  $DSH_HOME = Join-Path $env:USERPROFILE '.dsh'
+} else {
+  $DSH_HOME = Join-Path $HOME '.dsh'
+}
+$PROFILE_DIR = Join-Path $DSH_HOME "profiles\$Profile"
+$WS_YML = Join-Path $PROFILE_DIR 'pnpm-workspace.yaml'
+$PATCH_YML = Join-Path $PROFILE_DIR 'cordis.patch.yml'
+
+function Say([string]$m)  { Write-Host "[install] $m" -ForegroundColor Green }
+function Warn([string]$m) { Write-Host "[warn] $m" -ForegroundColor Yellow }
+function Die([string]$m)  { Write-Host "[error] $m" -ForegroundColor Red; exit 1 }
+
+# 解析版本 -> npm spec（"x.y.z" / "^x.y.z" / latest）
+function Resolve-Spec {
+  param([string]$Given)
+  if ([string]::IsNullOrWhiteSpace($Given) -or $Given -eq 'latest') {
+    $v = $null
+    foreach ($tool in @('npm', 'pnpm')) {
+      if (Get-Command $tool -ErrorAction SilentlyContinue) {
+        $v = (& $tool view $PKG version "--registry=$REGISTRY" 2>$null | Select-Object -Last 1)
+        if ($v) { break }
+      }
+    }
+    if ($v) { return ([string]$v).Trim() }
+    Warn '无法联网解析最新版本（npm/pnpm 查询失败），回退为 latest，由 pnpm 直接解析。'
+    Warn '若已知版本号，可显式传入：-Version 0.10.2'
+    return 'latest'
+  }
+  return $Given
+}
+
+# 组装 dsh CLI：优先 PATH 上的 dsh，缺省 npx 拉官方包
+function Get-DshCli {
+  if ($env:DSH_CMD) { return $env:DSH_CMD }
+  if (Get-Command dsh -ErrorAction SilentlyContinue) { return 'dsh' }
+  if (Get-Command npx -ErrorAction SilentlyContinue) { return 'npx' }
+  return $null
+}
+
+# 步骤 1（安装与修复共用）：预写 workspace 设置（幂等），保证 pnpm 不拦截
+# node-pty/protobufjs 构建脚本、放行本插件新版本
+function Ensure-WorkspaceSettings {
+  $wsScript = @'
+const fs = require("fs");
+const p = process.argv[2];
+let t = fs.readFileSync(p, "utf8");
+const before = t;
+t = t.replace(/^(\s*)(node-pty|protobufjs):.*$/gm, "$1$2: true");
+if (!/^\s*allowBuilds:\s*$/m.test(t)) {
+  t += "\nallowBuilds:\n  node-pty: true\n  protobufjs: true\n";
+} else {
+  for (const k of ["node-pty", "protobufjs"]) {
+    if (!new RegExp("^\\s*" + k + ":\\s*true\\s*$", "m").test(t)) {
+      t = t.replace(/^(\s*allowBuilds:\s*)$/m, "$1\n  " + k + ": true");
+    }
+  }
+}
+if (!/^\s*-\s+dsh-better-sidebar\s*$/m.test(t)) {
+  if (/^\s*minimumReleaseAgeExclude:\s*$/m.test(t)) {
+    t = t.replace(/^(\s*minimumReleaseAgeExclude:\s*)$/m, "$1\n  - dsh-better-sidebar");
+  } else {
+    t += "\nminimumReleaseAgeExclude:\n  - dsh-better-sidebar\n";
+  }
+}
+if (t !== before) fs.writeFileSync(p, t);
+console.log(t === before ? "unchanged" : "updated");
+'@
+  # PowerShell 5.1 把含内嵌双引号的多行 JS 作为参数传给 `node -e` 时，引号会被
+  # Windows 命令行解析吞掉，导致 JS 语法错误（Expected ',', got ':'）。
+  # 改用临时文件方式，兼容 PS 5.1 与 pwsh 7。
+  $wsJs = Join-Path $env:TEMP ("dshbs-ws-" + [guid]::NewGuid().ToString("N") + ".js")
+  Set-Content -LiteralPath $wsJs -Value $wsScript -Encoding UTF8
+  $wsOut = node $wsJs "$WS_YML" 2>&1
+  $wsCode = $LASTEXITCODE
+  Remove-Item -LiteralPath $wsJs -Force -ErrorAction SilentlyContinue
+  $wsResult = (($wsOut | Out-String)).Trim()
+  if ($wsCode -ne 0) { Die "处理 $WS_YML 失败（node 退出码 $wsCode）：$wsResult" }
+  if ($wsResult -eq 'updated') {
+    Say "已确保 $WS_YML：allowBuilds（node-pty/protobufjs: true）+ minimumReleaseAgeExclude（$PKG）"
+  } else {
+    Say 'workspace 设置已就绪，跳过'
+  }
+}
+
+# 前置校验
+if (-not (Get-Command node -ErrorAction SilentlyContinue)) {
+  Die '未找到 node（DSH 运行需要 Node.js >= 20），请先安装 Node.js 并加入 PATH。'
+}
+if (-not (Get-Command pnpm -ErrorAction SilentlyContinue)) {
+  Die '未找到 pnpm；安装脚本需要 pnpm >= 10。请先安装或升级 pnpm 并加入 PATH。'
+}
+$pnpmVersion = (& pnpm --version 2>$null | Select-Object -Last 1)
+if ($LASTEXITCODE -ne 0 -or -not $pnpmVersion) {
+  Die '无法读取 pnpm 版本；安装脚本需要 pnpm >= 10。'
+}
+$pnpmVersionText = ([string]$pnpmVersion).Trim()
+$pnpmMajor = 0
+if (-not [int]::TryParse(($pnpmVersionText -split '\.')[0], [ref]$pnpmMajor)) {
+  Die "无法解析 pnpm 版本（输出：$pnpmVersionText）；安装脚本需要 pnpm >= 10。"
+}
+if ($pnpmMajor -lt 10) {
+  Die "安装脚本需要 pnpm >= 10；当前版本为 $pnpmVersionText。请升级 pnpm 后重试。"
+}
+if (-not (Test-Path $PROFILE_DIR)) {
+  Die "找不到 profile 目录：$PROFILE_DIR（请先安装并运行过一次 dsh web）"
+}
+if (-not (Test-Path $WS_YML)) {
+  Die "找不到 $WS_YML（请先初始化 $Profile profile）"
+}
+
+# ── 修复模式（issue #140）：不重装插件，只修复 node-pty 依赖 ────────────
+# 终端提示「node-pty 加载失败」时运行：确保 allowBuilds 后重跑
+# pnpm install + pnpm rebuild node-pty（重放被 pnpm 11 拦截的构建脚本）。
+if ($Repair) {
+  if ($DryRun) {
+    Say "[dry-run] 修复：确保 $WS_YML 含 allowBuilds（node-pty: true）"
+    Say "[dry-run] 修复：cd $PROFILE_DIR; pnpm install; pnpm rebuild node-pty"
+    exit 0
+  }
+  Say "修复模式：重装 node-pty（profile: $Profile，$PROFILE_DIR）..."
+  Ensure-WorkspaceSettings
+  Push-Location $PROFILE_DIR
+  try {
+    pnpm install
+    if ($LASTEXITCODE -ne 0) { Die "pnpm install 失败（退出码 $LASTEXITCODE）。请确认 pnpm 在 PATH 上、网络可用，然后重试。" }
+    pnpm rebuild node-pty
+    if ($LASTEXITCODE -ne 0) { Die "pnpm rebuild node-pty 失败（退出码 $LASTEXITCODE）。请确认 pnpm 在 PATH 上，然后重试。" }
+  } finally {
+    Pop-Location
+  }
+  Say '修复完成：node-pty 已重装（与 DSH 核心保持同一版本）。请重启 DSH 后重试终端。'
+  exit 0
+}
+
+$SPEC = Resolve-Spec $Version
+$CLI = Get-DshCli
+if (-not $CLI) {
+  Die '未找到 dsh 或 npx。请先安装 DSH（并确保 Node/npm 可用），或用 DSH_CMD 指定。'
+}
+Say "目标：$CLI plugin --profile $Profile add $PKG@$SPEC（profile: $PROFILE_DIR）"
+
+if ($DryRun) {
+  Say "[dry-run] 步骤 1：确保 $WS_YML 含 allowBuilds（node-pty/protobufjs: true）与 minimumReleaseAgeExclude（$PKG）"
+  Say "[dry-run] 步骤 2：执行 $CLI plugin --profile $Profile add $PKG@$SPEC（安装 + bundle 自动注册）"
+  Say "[dry-run] 步骤 3：校验 dsh.profile.bundles 含 $PKG"
+  Say "[dry-run] 步骤 4：幂等移除 $PATCH_YML 里旧的 better-sidebar 手动挂载行（避免双挂载）"
+  if ($Restart) { Say '[dry-run] 步骤 5：pm2 restart dsh-web' } else { Say '[dry-run] 步骤 5：提示用户手动重启 DSH' }
+  exit 0
+}
+
+# 步骤 1：预写 workspace 设置（幂等），保证 pnpm 不拦截构建、放行本插件新版本
+Ensure-WorkspaceSettings
+
+# 步骤 2：官方 CLI 安装 + bundle 自动注册（含挂载）
+if ($CLI -eq 'dsh') {
+  $cliArgs = @('plugin', '--profile', $Profile, 'add', "$PKG@$SPEC")
+} else {
+  $cliArgs = @('-y', '--package', '@deepseek-ai/dsh', 'dsh', 'plugin', '--profile', $Profile, 'add', "$PKG@$SPEC")
+}
+Say "执行 $CLI plugin --profile $Profile add $PKG@$SPEC ..."
+$addOut = & $CLI @cliArgs 2>&1
+$addCode = $LASTEXITCODE
+$addOut | ForEach-Object { $_ }
+if ($addCode -ne 0) {
+  Warn 'dsh plugin add 失败。已预写 allowBuilds 与 minimumReleaseAgeExclude，仍失败的可能原因：'
+  Warn '  - 网络/登录问题：npm registry 不可达或需要登录。'
+  Warn "  - 依赖安装冲突：可手动重试 cd $PROFILE_DIR; pnpm install。"
+  exit 1
+}
+
+# 步骤 3：校验 bundle 已注册（挂载生效的判据）
+$pkgJson = Get-Content -Raw (Join-Path $PROFILE_DIR 'package.json') | ConvertFrom-Json
+$bundles = $pkgJson.dsh.profile.bundles
+if ($bundles -notcontains $PKG) {
+  Warn 'dsh-better-sidebar 未出现在 dsh.profile.bundles 中——挂载未注册。'
+  Warn "若上面的 pnpm 输出提示 ignored build scripts，请确认 $WS_YML 的 allowBuilds 后重跑本脚本。"
+  exit 1
+}
+Say "bundle 已注册：dsh.profile.bundles 包含 $PKG（下次启动自动挂载）"
+
+# 步骤 4：幂等移除旧的 manual 挂载行（避免与 bundle 双挂载）
+$mountScript = @'
+const fs = require("fs");
+const p = process.argv[2];
+const lines = fs.readFileSync(p, "utf8").split("\n");
+const out = [];
+let i = 0;
+let removed = false;
+while (i < lines.length) {
+  const line = lines[i];
+  if (/^[ \t]*- insert:\s*$/.test(line)) {
+    const block = [line];
+    let j = i + 1;
+    while (j < lines.length && lines[j].trim() !== "" && !/^-\s/.test(lines[j])) {
+      block.push(lines[j]);
+      j++;
+    }
+    if (block.some((l) => /id:\s*better-sidebar\b/.test(l))) {
+      while (out.length && /^[ \t]*#/.test(out[out.length - 1])) out.pop();
+      i = j;
+      removed = true;
+      continue;
+    }
+  }
+  out.push(line);
+  i++;
+}
+if (!removed) {
+  console.log("none");
+} else {
+  const t = out.join("\n").replace(/\n{3,}/g, "\n\n");
+  fs.writeFileSync(p, t);
+  console.log("removed");
+}
+'@
+$mountJs = Join-Path $env:TEMP ("dshbs-mount-" + [guid]::NewGuid().ToString("N") + ".js")
+Set-Content -LiteralPath $mountJs -Value $mountScript -Encoding UTF8
+$mountOut = node $mountJs "$PATCH_YML" 2>&1
+$mountCode = $LASTEXITCODE
+Remove-Item -LiteralPath $mountJs -Force -ErrorAction SilentlyContinue
+$mountResult = (($mountOut | Out-String)).Trim()
+if ($mountCode -ne 0) { Die "处理 $PATCH_YML 失败（node 退出码 $mountCode）：$mountResult" }
+if ($mountResult -eq 'removed') {
+  Say "已从 $PATCH_YML 移除旧的 better-sidebar 手动挂载行（bundle 通道接管挂载）"
+} else {
+  Say '无旧手动挂载行，跳过'
+}
+
+Say "安装完成：$PKG@$SPEC"
+
+# 步骤 5：重启提示
+if ($Restart) {
+  if (Get-Command pm2 -ErrorAction SilentlyContinue) {
+    Say '重启 dsh-web（pm2）...'
+    pm2 restart dsh-web
+    if ($LASTEXITCODE -ne 0) { Warn 'pm2 restart 失败，请手动重启 DSH' }
+  } else {
+    Warn '未找到 pm2，请手动重启 DSH（如：pm2 restart dsh-web 或 dsh web）'
+  }
+} else {
+  Say '下一步：重启 DSH 并硬刷新（Ctrl+Shift+R / Cmd+Shift+R）使新副本生效。'
+  if (Get-Command pm2 -ErrorAction SilentlyContinue) {
+    Say '本机可用：pm2 restart dsh-web（会短暂断开当前页面会话）'
+  }
+}