dsh-better-sidebar 0.10.1 → 0.10.3

package/README.md

@@ -35,42 +35,116 @@ https://github.com/user-attachments/assets/23187822-047e-45cc-b480-fe997bd55b86
 
 ## 🚀 安装
 
-前置：已安装 DSH（`dsh web` 可运行），Node.js ≥ 20、pnpm ≥ 10。插件已发布到 npm：**`dsh-better-sidebar@0.10.1`**（`@deepseek-ai/*` peer 依赖对齐宿主实际版本 `^0.1.0-rc.6` / `@deepseek-ai/cordis@^4.0.1`，同版本单实例）。挂载仍走 profile + `cordis.patch.yml`，不修改 DSH 源码。
+**前置**：已装好 DSH（`dsh web` 能正常运行），Node.js ≥ 20、pnpm ≥ 10。
 
-### 一键安装（推荐）
+**macOS / Linux**（Windows 装了 Git Bash 或 WSL 也可）：
 
 ```sh
 curl -fsSL https://raw.githubusercontent.com/omdsh-dev/DSH-better-sidebar/main/scripts/install.sh | bash
-# 指定版本：         curl -fsSL <同上> | bash -s 0.10.1
-# 装完自动重启 DSH： curl -fsSL <同上> | bash -s -- --restart
 ```
 
-脚本自动完成：登记 npm 依赖到 `~/.dsh/profiles/web/package.json`、幂等追加 `cordis.patch.yml` 挂载行、执行 `pnpm install`（版本默认 latest，可传参；`--dry-run` 只预览不落盘）。
+**Windows（PowerShell 5.1+ / pwsh）**：
 
-### 手动安装（npm 包方式）
+```powershell
+irm https://raw.githubusercontent.com/omdsh-dev/DSH-better-sidebar/main/scripts/install.ps1 | iex
+```
 
-```text
-1. 在 ~/.dsh/profiles/web/package.json 的 dependencies 加 "dsh-better-sidebar": "^0.10.1"
-2. 在 ~/.dsh/profiles/web/cordis.patch.yml 追加挂载行：
-   - insert:
-       - id: better-sidebar
-         name: 'dsh-better-sidebar'
-3. 在 ~/.dsh/profiles/web 执行 pnpm install
-4. 重启 DSH 并硬刷新（Cmd/Ctrl+Shift+R）验证
+装完**重启 DSH 并硬刷新**（Cmd/Ctrl+Shift+R）即可看到侧边栏。
+
+<details>
+<summary><b>指定版本 / 装完自动重启（可选）</b></summary>
+
+```sh
+# macOS / Linux
+curl -fsSL https://raw.githubusercontent.com/omdsh-dev/DSH-better-sidebar/main/scripts/install.sh | bash -s 0.10.3 --restart
+
+# Windows PowerShell
+& ([scriptblock]::Create((irm 'https://raw.githubusercontent.com/omdsh-dev/DSH-better-sidebar/main/scripts/install.ps1'))) -Version 0.10.3 -Restart
 ```
 
-> 安装 = 依赖登记 + 一行挂载行。**DSH 以 npm 包启动（如 `npx -p @deepseek-ai/dsh@0.1.0-rc.6 dsh web`）同样可用**（v0.4.3 起实测验证）。
+不确定的话，可先加 `--dry-run`（PowerShell 用 `-DryRun`）预览步骤再执行。
 
-> 提示：若 profile 的 pnpm 因 `minimumReleaseAge`（发布 <24h 的新版本）拒绝安装，会自动向 `~/.dsh/profiles/web/pnpm-workspace.yaml` 追加 `minimumReleaseAgeExclude` 条目；也可手动补一行 `dsh-better-sidebar@<版本>`。
+</details>
 
-### 更新
+<details>
+<summary><b>手动安装（逐步命令，想看清每一步）</b></summary>
 
-```text
-1. 把 ~/.dsh/profiles/web/package.json 里版本号改到新版（如 "^0.10.1"）
-2. 在 ~/.dsh/profiles/web 执行 pnpm install
-3. 重启 DSH 并硬刷新（Cmd/Ctrl+Shift+R）
+与一键脚本等价。**第 ③ 步可重复执行；①② 只需做一次。**
+
+**macOS / Linux（bash）**：
+
+```sh
+cd ~/.dsh/profiles/web
+
+# ① 放行 node-pty / protobufjs 的构建脚本（pnpm 11 默认拦截；pnpm 10 可跳过）
+pnpm approve-builds --all
+
+# ② 放行「发布不足 24h」的新版本（装老版本可跳过；若已有该键，把下面那行并入其下即可）
+cat >> pnpm-workspace.yaml <<'EOF'
+minimumReleaseAgeExclude:
+  - dsh-better-sidebar
+EOF
+
+# ③ 安装并自动挂载（不带 @版本 = npm 的 latest；固定版本写 dsh-better-sidebar@0.10.3）
+npx -y --package @deepseek-ai/dsh dsh plugin --profile web add dsh-better-sidebar
 ```
 
+**Windows（PowerShell）**：
+
+```powershell
+cd ~\.dsh\profiles\web
+
+# ① 放行构建脚本
+pnpm approve-builds --all
+
+# ② 放行新版本（一次性；若已有该键，把 - dsh-better-sidebar 并入其下即可）
+Add-Content -Path pnpm-workspace.yaml -Value "`nminimumReleaseAgeExclude:`n  - dsh-better-sidebar"
+
+# ③ 安装并自动挂载
+npx -y --package @deepseek-ai/dsh dsh plugin --profile web add dsh-better-sidebar
+```
+
+</details>
+
+<details>
+<summary><b>脚本内部做了什么（技术细节）</b></summary>
+
+一键脚本自动完成 4 件事（全部幂等，可安全重复执行）：
+
+1. 预写 `allowBuilds`（node-pty / protobufjs），规避 pnpm 11 的构建脚本拦截；
+2. 预写 `minimumReleaseAgeExclude`，放行「发布不足 24 小时」的新版本；
+3. 执行 `dsh plugin --profile web add dsh-better-sidebar`：登记依赖 → 识别包内 `dsh.bundle.patch` → 自动注册进 `dsh.profile.bundles` 挂载；
+4. 清理旧版残留的手动挂载行，避免「双挂载」（页面出现两个侧边栏）。
+
+`curl | bash` / `irm | iex` 会执行远程代码——脚本已随仓库开源（`scripts/install.sh` / `scripts/install.ps1`），可先下载审阅。插件以 npm 包 `dsh-better-sidebar@0.10.3` 发布，通过 `dsh.bundle.patch`（随包的 `cordis.patch.yml`）由官方 CLI 自动挂载，**不修改 DSH 源码**。
+
+</details>
+
+<details>
+<summary><b>更新</b></summary>
+
+```sh
+dsh plugin --profile web add dsh-better-sidebar
+```
+
+或重跑一次一键脚本；也可把 `~/.dsh/profiles/web/package.json` 里的版本号改高后 `pnpm install`。改完**重启 DSH 并硬刷新**（Cmd/Ctrl+Shift+R）。
+
+</details>
+
+<details>
+<summary><b>常见问题</b></summary>
+
+| 现象 | 原因与解决 |
+|---|---|
+| 报 `Ignored build scripts` | pnpm 11 拦截构建脚本。跑 `pnpm approve-builds --all`（一键脚本已自动处理）。 |
+| 报 `minimum release age` / 版本不足 24h | 装的版本发布不足 24 小时。等 24h 或重跑一次（pnpm 会自动补 `minimumReleaseAgeExclude`）；一键脚本已自动处理。 |
+| 报「找不到 profile 目录」 | 先跑一次 `dsh web`，让它初始化 `~/.dsh/profiles/web`。 |
+| 页面出现**两个侧边栏** | 双挂载：`~/.dsh/profiles/web/cordis.patch.yml` 还留着旧的手动挂载行，删掉那段 `- insert: ... better-sidebar ...`（一键脚本会自动清）。 |
+| Windows 下终端无法使用 | `node-pty` 依赖预编译二进制；若当前 Node 版本没有对应产物，需装编译工具链（VS Build Tools）。主流 Node 版本一般已有预编译。 |
+| Windows 没有 bash / curl | 直接用 PowerShell 一键命令；或安装 Git Bash / WSL 再跑 bash 命令。 |
+
+</details>
+
 <details>
 <summary><b>从源码安装 / 开发（可选，替代 npm 方式）</b></summary>
 
@@ -80,12 +154,15 @@ curl -fsSL https://raw.githubusercontent.com/omdsh-dev/DSH-better-sidebar/main/s
 1. git clone https://github.com/omdsh-dev/DSH-better-sidebar.git ~/Code/DSH-better-sidebar
    cd ~/Code/DSH-better-sidebar && pnpm install && pnpm build
 2. ~/.dsh/profiles/web/package.json 的 dependencies 写 "dsh-better-sidebar": "link:<克隆目录绝对路径>"
-3. ~/.dsh/profiles/web/cordis.patch.yml 追加挂载行（同上）
+3. ~/.dsh/profiles/web/cordis.patch.yml 追加挂载行：
+   - insert:
+       - id: better-sidebar
+         name: 'dsh-better-sidebar'
 4. 在 ~/.dsh/profiles/web 执行 pnpm install
 5. 重启 DSH 并硬刷新
 ```
 
-更新：`git pull && pnpm install && pnpm build` → 重启 DSH（仅 client 改动可硬刷新）。切回 npm 通道时，把依赖改回 `"dsh-better-sidebar": "^0.10.1"` 再 `pnpm install`。
+更新：`git pull && pnpm install && pnpm build` → 重启 DSH（仅 client 改动可硬刷新）。切回 npm 通道时，把依赖改回 `"dsh-better-sidebar": "^0.10.3"` 再 `pnpm install`。
 
 </details>
 

package/README_EN.md

@@ -35,42 +35,116 @@ https://github.com/user-attachments/assets/23187822-047e-45cc-b480-fe997bd55b86
 
 ## 🚀 Installation
 
-Prerequisites: DSH installed (`dsh web` works), Node.js ≥ 20, pnpm ≥ 10. The plugin is published to npm as **`dsh-better-sidebar@0.10.1`** (`@deepseek-ai/*` peers aligned with the host's actual versions `^0.1.0-rc.6` / `@deepseek-ai/cordis@^4.0.1`, single instance). Mounting still goes through the profile + `cordis.patch.yml`; the DSH source is never modified.
+**Prerequisites**: DSH installed (`dsh web` boots), Node.js ≥ 20, pnpm ≥ 10.
 
-### One-click install (recommended)
+**macOS / Linux** (also works in Git Bash / WSL on Windows):
 
 ```sh
 curl -fsSL https://raw.githubusercontent.com/omdsh-dev/DSH-better-sidebar/main/scripts/install.sh | bash
-# Pick a version:   curl -fsSL <same URL> | bash -s 0.10.1
-# Auto-restart DSH: curl -fsSL <same URL> | bash -s -- --restart
 ```
 
-The script registers the npm dependency in `~/.dsh/profiles/web/package.json`, idempotently appends the `cordis.patch.yml` mount line, and runs `pnpm install` (version defaults to latest, pass one as an argument; `--dry-run` previews without writing anything).
+**Windows (PowerShell 5.1+ / pwsh)**:
 
-### Manual install (npm package)
+```powershell
+irm https://raw.githubusercontent.com/omdsh-dev/DSH-better-sidebar/main/scripts/install.ps1 | iex
+```
 
-```text
-1. In ~/.dsh/profiles/web/package.json dependencies add "dsh-better-sidebar": "^0.10.1"
-2. Append the mount line to ~/.dsh/profiles/web/cordis.patch.yml:
-   - insert:
-       - id: better-sidebar
-         name: 'dsh-better-sidebar'
-3. Run pnpm install in ~/.dsh/profiles/web
-4. Restart DSH and hard-refresh (Cmd/Ctrl+Shift+R) to verify
+Then **restart DSH and hard-refresh** (Cmd/Ctrl+Shift+R) to see the sidebar.
+
+<details>
+<summary><b>Pin a version / auto-restart (optional)</b></summary>
+
+```sh
+# macOS / Linux
+curl -fsSL https://raw.githubusercontent.com/omdsh-dev/DSH-better-sidebar/main/scripts/install.sh | bash -s 0.10.3 --restart
+
+# Windows PowerShell
+& ([scriptblock]::Create((irm 'https://raw.githubusercontent.com/omdsh-dev/DSH-better-sidebar/main/scripts/install.ps1'))) -Version 0.10.3 -Restart
 ```
 
-> Installation = dependency registration + one mount line. **It also works when DSH is started as an npm package (e.g. `npx -p @deepseek-ai/dsh@0.1.0-rc.6 dsh web`)** (verified since v0.4.3).
+Not sure? Add `--dry-run` (`-DryRun` in PowerShell) to preview before running.
 
-> Note: if the profile's pnpm rejects a too-fresh release via `minimumReleaseAge` (<24h old), it auto-appends a `minimumReleaseAgeExclude` entry to `~/.dsh/profiles/web/pnpm-workspace.yaml` — or add `dsh-better-sidebar@<version>` there manually.
+</details>
 
-### Updating
+<details>
+<summary><b>Manual install (step by step)</b></summary>
 
-```text
-1. Bump the version range in ~/.dsh/profiles/web/package.json (e.g. "^0.10.1")
-2. Run pnpm install in ~/.dsh/profiles/web
-3. Restart DSH and hard-refresh (Cmd/Ctrl+Shift+R)
+Equivalent to the one-click script. **Step ③ is repeatable; ①② only need to run once.**
+
+**macOS / Linux (bash)**:
+
+```sh
+cd ~/.dsh/profiles/web
+
+# ① Allow node-pty / protobufjs build scripts (pnpm 11 blocks them by default; skip on pnpm 10)
+pnpm approve-builds --all
+
+# ② Allow versions published less than 24h ago (skip for older releases; if the key already exists, merge the line under it instead)
+cat >> pnpm-workspace.yaml <<'EOF'
+minimumReleaseAgeExclude:
+  - dsh-better-sidebar
+EOF
+
+# ③ Install and auto-mount (no @version = npm's latest; pin with dsh-better-sidebar@0.10.3)
+npx -y --package @deepseek-ai/dsh dsh plugin --profile web add dsh-better-sidebar
 ```
 
+**Windows (PowerShell)**:
+
+```powershell
+cd ~\.dsh\profiles\web
+
+# ① Allow build scripts
+pnpm approve-builds --all
+
+# ② Allow fresh releases (once; if the key already exists, merge - dsh-better-sidebar under it instead)
+Add-Content -Path pnpm-workspace.yaml -Value "`nminimumReleaseAgeExclude:`n  - dsh-better-sidebar"
+
+# ③ Install and auto-mount
+npx -y --package @deepseek-ai/dsh dsh plugin --profile web add dsh-better-sidebar
+```
+
+</details>
+
+<details>
+<summary><b>What the script does (technical details)</b></summary>
+
+The one-click script does four things, all idempotent (safe to re-run):
+
+1. Pre-writes `allowBuilds` (node-pty / protobufjs) to dodge pnpm 11's build-script block;
+2. Pre-writes `minimumReleaseAgeExclude` to allow versions younger than 24 hours;
+3. Runs `dsh plugin --profile web add dsh-better-sidebar`: registers the dependency → detects `dsh.bundle.patch` → auto-appends the plugin to `dsh.profile.bundles`;
+4. Removes any leftover hand-written mount line to avoid double-mounting (two sidebars on the page).
+
+`curl | bash` / `irm | iex` executes remote code — the scripts are open source in the repo (`scripts/install.sh` / `scripts/install.ps1`); download and review them first if you prefer. The plugin ships as npm package `dsh-better-sidebar@0.10.3` and mounts via `dsh.bundle.patch` (the shipped `cordis.patch.yml`), so the DSH source is never modified.
+
+</details>
+
+<details>
+<summary><b>Updating</b></summary>
+
+```sh
+dsh plugin --profile web add dsh-better-sidebar
+```
+
+or re-run the one-click script; or bump the version in `~/.dsh/profiles/web/package.json` (e.g. `"^0.10.3"`) and run `pnpm install`. Then restart DSH and hard-refresh (Cmd/Ctrl+Shift+R).
+
+</details>
+
+<details>
+<summary><b>Troubleshooting</b></summary>
+
+| Symptom | Cause & fix |
+|---|---|
+| `Ignored build scripts` | pnpm 11 blocked build scripts. Run `pnpm approve-builds --all` (the one-click script handles it). |
+| `minimum release age` / version `< 24h` | The release is younger than 24 hours. Wait, or re-run once (pnpm auto-adds `minimumReleaseAgeExclude`); the one-click script handles it. |
+| "profile directory not found" | Run `dsh web` once so it initializes `~/.dsh/profiles/web`. |
+| Two sidebars on the page | Double-mount: `~/.dsh/profiles/web/cordis.patch.yml` still has the old hand-written `- insert: ... better-sidebar ...` line — delete it (the one-click script cleans it). |
+| Terminal fails on Windows | `node-pty` relies on prebuilt binaries; if none match your Node version, install a build toolchain (VS Build Tools). Mainstream Node versions are usually covered. |
+| No bash / curl on Windows | Use the PowerShell one-click command, or install Git Bash / WSL and run the bash commands. |
+
+</details>
+
 <details>
 <summary><b>Install from source / develop (optional — alternative to the npm flow)</b></summary>
 
@@ -80,12 +154,15 @@ To debug local changes or track the dev branch, point the dependency at a local
 1. git clone https://github.com/omdsh-dev/DSH-better-sidebar.git ~/Code/DSH-better-sidebar
    cd ~/Code/DSH-better-sidebar && pnpm install && pnpm build
 2. In ~/.dsh/profiles/web/package.json dependencies write "dsh-better-sidebar": "link:<absolute path of the clone>"
-3. Append the mount line to ~/.dsh/profiles/web/cordis.patch.yml (same as above)
+3. Append this mount line to ~/.dsh/profiles/web/cordis.patch.yml:
+   - insert:
+       - id: better-sidebar
+         name: 'dsh-better-sidebar'
 4. Run pnpm install in ~/.dsh/profiles/web
 5. Restart DSH and hard-refresh
 ```
 
-Update: `git pull && pnpm install && pnpm build` → restart DSH (client-only changes can just hard-refresh). To switch back to the npm channel, restore `"dsh-better-sidebar": "^0.10.1"` and re-run `pnpm install`.
+Update: `git pull && pnpm install && pnpm build` → restart DSH (client-only changes can just hard-refresh). To switch back to the npm channel, restore `"dsh-better-sidebar": "^0.10.3"` and re-run `pnpm install`.
 
 </details>
 

package/cordis.patch.yml

@@ -0,0 +1,19 @@
+# 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).
+- insert:
+    - id: better-sidebar
+      name: 'dsh-better-sidebar'