From 97e52b650e8444fdfbf7049216f416693318a09a Mon Sep 17 00:00:00 2001 From: Menghuan1918 Date: Fri, 14 Aug 2026 00:59:02 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=89=E8=A3=85=E7=AB=A0=E8=8A=82?= =?UTF-8?q?=E6=8A=98=E5=8F=A0=E6=8A=80=E6=9C=AF=E7=BB=86=E8=8A=82=E4=B8=BA?= =?UTF-8?q?=E5=8F=AF=E6=8A=98=E5=8F=A0=E5=9D=97=EF=BC=8C=E7=89=88=E6=9C=AC?= =?UTF-8?q?=E5=BC=95=E7=94=A8=E6=9B=B4=E6=96=B0=E4=B8=BA=200.10.3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 66 ++++++++++++++++++++++++++++++---------------------- README_EN.md | 66 ++++++++++++++++++++++++++++++---------------------- 2 files changed, 76 insertions(+), 56 deletions(-) diff --git a/README.md b/README.md index 83186d0..2ab6547 100644 --- a/README.md +++ b/README.md @@ -35,18 +35,9 @@ https://github.com/user-attachments/assets/23187822-047e-45cc-b480-fe997bd55b86 ## 🚀 安装 -装好只需三步：**① 满足前置 → ② 跑一条对应平台的一键命令 → ③ 重启 DSH 并硬刷新**。 +**前置**：已装好 DSH（`dsh web` 能正常运行），Node.js ≥ 20、pnpm ≥ 10。 -### 前置要求 - -- 已安装 **DSH**，且 `dsh web` 能正常启动（首次运行会初始化 `~/.dsh/profiles/web` 这个 profile）。 -- **Node.js ≥ 20**（DSH 运行本身就需要）。 -- **pnpm ≥ 10**（装依赖用；pnpm 11 也可，脚本会自动处理它的新策略）。 -- 插件已发布到 npm：**`dsh-better-sidebar@0.10.2`**。包内声明了 `dsh.bundle.patch`（随包发布的 `cordis.patch.yml`），官方 CLI 装完即自动挂载，**不修改 DSH 源码**。 - -### 一键安装（推荐） - -**macOS / Linux**（Windows 装了 Git Bash 或 WSL 也可用）： +**macOS / Linux**（Windows 装了 Git Bash 或 WSL 也可）： ```sh curl -fsSL https://raw.githubusercontent.com/omdsh-dev/DSH-better-sidebar/main/scripts/install.sh | bash @@ -58,28 +49,27 @@ curl -fsSL https://raw.githubusercontent.com/omdsh-dev/DSH-better-sidebar/main/s irm https://raw.githubusercontent.com/omdsh-dev/DSH-better-sidebar/main/scripts/install.ps1 | iex ``` -**指定版本 / 装完自动重启**（两平台参数一致）： +装完**重启 DSH 并硬刷新**（Cmd/Ctrl+Shift+R）即可看到侧边栏。 + +
+指定版本 / 装完自动重启（可选） ```sh # macOS / Linux -curl -fsSL https://raw.githubusercontent.com/omdsh-dev/DSH-better-sidebar/main/scripts/install.sh | bash -s 0.10.2 --restart +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.2 -Restart +& ([scriptblock]::Create((irm 'https://raw.githubusercontent.com/omdsh-dev/DSH-better-sidebar/main/scripts/install.ps1'))) -Version 0.10.3 -Restart ``` -脚本会自动完成 4 件事（全部幂等，可安全重复执行）： +不确定的话，可先加 `--dry-run`（PowerShell 用 `-DryRun`）预览步骤再执行。 -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. 清理旧版残留的手动挂载行，避免「双挂载」（页面出现两个侧边栏）。 +
-不确定的话，可先加 `--dry-run`（PowerShell 用 `-DryRun`）预览步骤再真正执行。`curl | bash` / `irm | iex` 会执行远程代码——脚本已随仓库开源（`scripts/install.sh` / `scripts/install.ps1`），可先下载审阅。 +
+手动安装（逐步命令，想看清每一步） -### 手动安装（逐步命令） - -适合想看清每一步的用户，与一键脚本等价。**第 ③ 步可重复执行；①② 只需做一次。** +与一键脚本等价。**第 ③ 步可重复执行；①② 只需做一次。** **macOS / Linux（bash）**： @@ -95,7 +85,7 @@ minimumReleaseAgeExclude: - dsh-better-sidebar EOF -# ③ 安装并自动挂载（不带 @版本 = npm 的 latest；固定版本写 dsh-better-sidebar@0.10.2） +# ③ 安装并自动挂载（不带 @版本 = npm 的 latest；固定版本写 dsh-better-sidebar@0.10.3） npx -y --package @deepseek-ai/dsh dsh plugin --profile web add dsh-better-sidebar ``` @@ -114,9 +104,24 @@ Add-Content -Path pnpm-workspace.yaml -Value "`nminimumReleaseAgeExclude:`n - d npx -y --package @deepseek-ai/dsh dsh plugin --profile web add dsh-better-sidebar ``` -`dsh plugin add` 会：`pnpm add` 登记依赖 → 识别包内 `dsh.bundle.patch` → 自动注册到 `dsh.profile.bundles` → 下次启动自动挂载（**无需手写 `cordis.patch.yml`**）。 +
-### 更新 +
+脚本内部做了什么（技术细节） + +一键脚本自动完成 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 源码**。 + +
+ +
+更新 ```sh dsh plugin --profile web add dsh-better-sidebar @@ -124,7 +129,10 @@ dsh plugin --profile web add dsh-better-sidebar 或重跑一次一键脚本；也可把 `~/.dsh/profiles/web/package.json` 里的版本号改高后 `pnpm install`。改完**重启 DSH 并硬刷新**（Cmd/Ctrl+Shift+R）。 -### 常见问题 +
+ +
+常见问题 | 现象 | 原因与解决 | |---|---| @@ -135,6 +143,8 @@ dsh plugin --profile web add dsh-better-sidebar | Windows 下终端无法使用 | `node-pty` 依赖预编译二进制；若当前 Node 版本没有对应产物，需装编译工具链（VS Build Tools）。主流 Node 版本一般已有预编译。 | | Windows 没有 bash / curl | 直接用 PowerShell 一键命令；或安装 Git Bash / WSL 再跑 bash 命令。 | +
+
从源码安装 / 开发（可选，替代 npm 方式） @@ -152,7 +162,7 @@ dsh plugin --profile web add dsh-better-sidebar 5. 重启 DSH 并硬刷新 ``` -更新：`git pull && pnpm install && pnpm build` → 重启 DSH（仅 client 改动可硬刷新）。切回 npm 通道时，把依赖改回 `"dsh-better-sidebar": "^0.10.2"` 再 `pnpm install`。 +更新：`git pull && pnpm install && pnpm build` → 重启 DSH（仅 client 改动可硬刷新）。切回 npm 通道时，把依赖改回 `"dsh-better-sidebar": "^0.10.3"` 再 `pnpm install`。
diff --git a/README_EN.md b/README_EN.md index 1f29e5a..5f43479 100644 --- a/README_EN.md +++ b/README_EN.md @@ -35,16 +35,7 @@ https://github.com/user-attachments/assets/23187822-047e-45cc-b480-fe997bd55b86 ## 🚀 Installation -Installation is three steps: **① meet the prerequisites → ② run one command for your OS → ③ restart DSH and hard-refresh**. - -### Prerequisites - -- **DSH** installed and `dsh web` boots (the first run initializes the `~/.dsh/profiles/web` profile). -- **Node.js ≥ 20** (DSH itself requires it). -- **pnpm ≥ 10** (pnpm 11 also works — the installer handles its new policies automatically). -- The plugin is published to npm as **`dsh-better-sidebar@0.10.2`**. It declares `dsh.bundle.patch` (the shipped `cordis.patch.yml`), so the official CLI mounts it after install — the DSH source is never modified. - -### One-click install (recommended) +**Prerequisites**: DSH installed (`dsh web` boots), Node.js ≥ 20, pnpm ≥ 10. **macOS / Linux** (also works in Git Bash / WSL on Windows): @@ -58,28 +49,27 @@ curl -fsSL https://raw.githubusercontent.com/omdsh-dev/DSH-better-sidebar/main/s irm https://raw.githubusercontent.com/omdsh-dev/DSH-better-sidebar/main/scripts/install.ps1 | iex ``` -**Pin a version / auto-restart after install** (same options on both platforms): +Then **restart DSH and hard-refresh** (Cmd/Ctrl+Shift+R) to see the sidebar. + +
+Pin a version / auto-restart (optional) ```sh # macOS / Linux -curl -fsSL https://raw.githubusercontent.com/omdsh-dev/DSH-better-sidebar/main/scripts/install.sh | bash -s 0.10.2 --restart +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.2 -Restart +& ([scriptblock]::Create((irm 'https://raw.githubusercontent.com/omdsh-dev/DSH-better-sidebar/main/scripts/install.ps1'))) -Version 0.10.3 -Restart ``` -The script does four things, all idempotent (safe to re-run): +Not sure? Add `--dry-run` (`-DryRun` in PowerShell) to preview before running. -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). +
-Not sure? Add `--dry-run` (`-DryRun` in PowerShell) to preview before committing. `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. +
+Manual install (step by step) -### Manual install (step by step) - -For users who want to see every step; equivalent to the one-click script. **Step ③ is repeatable; ①② only need to run once.** +Equivalent to the one-click script. **Step ③ is repeatable; ①② only need to run once.** **macOS / Linux (bash)**: @@ -95,7 +85,7 @@ minimumReleaseAgeExclude: - dsh-better-sidebar EOF -# ③ Install and auto-mount (no @version = npm's latest; pin with dsh-better-sidebar@0.10.2) +# ③ 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 ``` @@ -114,17 +104,35 @@ Add-Content -Path pnpm-workspace.yaml -Value "`nminimumReleaseAgeExclude:`n - d npx -y --package @deepseek-ai/dsh dsh plugin --profile web add dsh-better-sidebar ``` -`dsh plugin add` runs `pnpm add` to register the dependency, detects `dsh.bundle.patch`, auto-appends the plugin to `dsh.profile.bundles`, and the next boot mounts it — **no hand-written `cordis.patch.yml` mount line**. +
-### Updating +
+What the script does (technical details) + +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. + +
+ +
+Updating ```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.2"`) and run `pnpm install`. Then restart DSH and hard-refresh (Cmd/Ctrl+Shift+R). +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). -### Troubleshooting +
+ +
+Troubleshooting | Symptom | Cause & fix | |---|---| @@ -135,6 +143,8 @@ or re-run the one-click script; or bump the version in `~/.dsh/profiles/web/pack | 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. | +
+
Install from source / develop (optional — alternative to the npm flow) @@ -152,7 +162,7 @@ To debug local changes or track the dev branch, point the dependency at a local 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.2"` 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`.