From 565e66d30ed6ad5c0227cf214651452a6b536b9a Mon Sep 17 00:00:00 2001 From: Menghuan1918 Date: Mon, 17 Aug 2026 00:26:48 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=89=E8=A3=85/=E6=9B=B4=E6=96=B0?= =?UTF-8?q?=E8=AF=B4=E6=98=8E=E5=8F=AA=E7=95=99=20dsh=20plugin=20add=20?= =?UTF-8?q?=E5=91=BD=E4=BB=A4=EF=BC=8C=E7=A7=BB=E9=99=A4=E4=B8=80=E9=94=AE?= =?UTF-8?q?=E8=84=9A=E6=9C=AC=E5=BC=95=E7=94=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 95 ++++------------------------------------------------ README_EN.md | 95 ++++------------------------------------------------ 2 files changed, 12 insertions(+), 178 deletions(-) diff --git a/README.md b/README.md index 2f11ec1..1f1918a 100644 --- a/README.md +++ b/README.md @@ -57,95 +57,12 @@ **前置**：已装好 DSH（`dsh web` 能正常运行），Node.js ≥ 20、pnpm ≥ 10。 -**直接安装**（npm 发布安全期已过，无需指定版本；装有 DSH CLI 的环境一条命令搞定）： - ```sh dsh plugin --profile web add dsh-better-sidebar ``` -**或一键脚本**（macOS / Linux，Windows 装了 Git Bash 或 WSL 也可）： - -```sh -curl -fsSL https://raw.githubusercontent.com/omdsh-dev/DSH-better-sidebar/main/scripts/install.sh | bash -``` - -**Windows（PowerShell 5.1+ / pwsh）**： - -```powershell -irm https://raw.githubusercontent.com/omdsh-dev/DSH-better-sidebar/main/scripts/install.ps1 | iex -``` - 装完**硬刷新浏览器**（Cmd/Ctrl+Shift+R）即可看到侧边栏（DSH 对 client 改动热加载，无需重启；仅 host 半更新时需要重启）。 -
-指定版本 / 装完自动重启（可选） - -```sh -# macOS / Linux -curl -fsSL https://raw.githubusercontent.com/omdsh-dev/DSH-better-sidebar/main/scripts/install.sh | bash -s 0.12.3 --restart - -# Windows PowerShell -& ([scriptblock]::Create((irm 'https://raw.githubusercontent.com/omdsh-dev/DSH-better-sidebar/main/scripts/install.ps1'))) -Version 0.12.3 -Restart -``` - -不确定的话，可先加 `--dry-run`（PowerShell 用 `-DryRun`）预览步骤再执行。 - -
- -
-手动安装（逐步命令，想看清每一步） - -与一键脚本等价。**第 ③ 步可重复执行；①② 只需做一次。** - -**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.12.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 -``` - -
- -
-脚本内部做了什么（技术细节） - -一键脚本自动完成 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.12.3` 发布，通过 `dsh.bundle.patch`（随包的 `cordis.patch.yml`）由官方 CLI 自动挂载，**不修改 DSH 源码**。 - -
-
更新 @@ -153,7 +70,7 @@ npx -y --package @deepseek-ai/dsh dsh plugin --profile web add dsh-better-sideba dsh plugin --profile web add dsh-better-sidebar ``` -或重跑一次一键脚本；也可把 `~/.dsh/profiles/web/package.json` 里的版本号改高后 `pnpm install`。改完**硬刷新浏览器**（Cmd/Ctrl+Shift+R）即可（client 改动无需重启 DSH）。 +也可把 `~/.dsh/profiles/web/package.json` 里的版本号改高后 `pnpm install`。改完**硬刷新浏览器**（Cmd/Ctrl+Shift+R）即可（client 改动无需重启 DSH）。
@@ -162,13 +79,13 @@ dsh plugin --profile web add dsh-better-sidebar | 现象 | 原因与解决 | |---|---| -| 报 `Ignored build scripts` | pnpm 11 拦截构建脚本。跑 `pnpm approve-builds --all`（一键脚本已自动处理）。 | -| 报 `minimum release age` / 版本不足 24h | 装的版本发布不足 24 小时。等 24h 或重跑一次（pnpm 会自动补 `minimumReleaseAgeExclude`）；一键脚本已自动处理。 | +| 报 `Ignored build scripts` | pnpm 11 拦截构建脚本。在 profile 目录（`~/.dsh/profiles/web`）跑 `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 ...`（一键脚本会自动清）。 | +| 页面出现**两个侧边栏** | 双挂载：`~/.dsh/profiles/web/cordis.patch.yml` 还留着旧的手动挂载行，删掉那段 `- insert: ... better-sidebar ...`。 | | Windows 下终端无法使用 | `node-pty` 依赖预编译二进制；若当前 Node 版本没有对应产物，需装编译工具链（VS Build Tools）。主流 Node 版本一般已有预编译。 | -| 终端提示「node-pty 加载失败」 | `node-pty` 安装缺失/损坏（如 pnpm 拦截了构建脚本）。终端横幅会给出修复命令：复制到 DSH 所在环境的终端/cmd 执行（POSIX 为 `bash "<插件路径>/scripts/install.sh" --repair`，Windows 为对应 `install.ps1 -Repair`；或直接重跑一键安装脚本），完成后重启 DSH 并点重试。插件与 DSH 核心使用同一 `node-pty@^1.1.0`，修复后两者同步恢复。 | -| Windows 没有 bash / curl | 直接用 PowerShell 一键命令；或安装 Git Bash / WSL 再跑 bash 命令。 | +| 终端提示「node-pty 加载失败」 | `node-pty` 安装缺失/损坏（如 pnpm 拦截了构建脚本）。终端横幅会给出修复命令：复制到 DSH 所在环境的终端/cmd 执行（在 `~/.dsh/profiles/web` 下 `pnpm approve-builds --all && pnpm rebuild node-pty`），完成后重启 DSH 并点重试。插件与 DSH 核心使用同一 `node-pty@^1.1.0`，修复后两者同步恢复。 | +| 提示 `dsh: command not found` | 先安装 DSH；或直接用 `npx -y --package @deepseek-ai/dsh dsh plugin --profile web add dsh-better-sidebar`。 | diff --git a/README_EN.md b/README_EN.md index 151cc19..f8d2522 100644 --- a/README_EN.md +++ b/README_EN.md @@ -57,95 +57,12 @@ **Prerequisites**: DSH installed (`dsh web` boots), Node.js ≥ 20, pnpm ≥ 10. -**Direct install** (the npm publish safety window has passed — no version pin needed; one command on machines with the DSH CLI): - ```sh dsh plugin --profile web add dsh-better-sidebar ``` -**Or one-click script** (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 -``` - -**Windows (PowerShell 5.1+ / pwsh)**: - -```powershell -irm https://raw.githubusercontent.com/omdsh-dev/DSH-better-sidebar/main/scripts/install.ps1 | iex -``` - Then **hard-refresh the browser** (Cmd/Ctrl+Shift+R) to see the sidebar (DSH hot-reloads client changes; only host-half updates need a restart). -
-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.12.3 --restart - -# Windows PowerShell -& ([scriptblock]::Create((irm 'https://raw.githubusercontent.com/omdsh-dev/DSH-better-sidebar/main/scripts/install.ps1'))) -Version 0.12.3 -Restart -``` - -Not sure? Add `--dry-run` (`-DryRun` in PowerShell) to preview before running. - -
- -
-Manual install (step by step) - -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.12.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 -``` - -
- -
-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.12.3` and mounts via `dsh.bundle.patch` (the shipped `cordis.patch.yml`), so the DSH source is never modified. - -
-
Updating @@ -153,7 +70,7 @@ The one-click script does four things, all idempotent (safe to re-run): 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.12.3"`) and run `pnpm install`. Then hard-refresh the browser (Cmd/Ctrl+Shift+R) — client changes do not need a DSH restart. +or bump the version in `~/.dsh/profiles/web/package.json` (e.g. `"^0.12.3"`) and run `pnpm install`. Then hard-refresh the browser (Cmd/Ctrl+Shift+R) — client changes do not need a DSH restart.
@@ -162,13 +79,13 @@ or re-run the one-click script; or bump the version in `~/.dsh/profiles/web/pack | 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. | +| `Ignored build scripts` | pnpm 11 blocked build scripts. Run `pnpm approve-builds --all` in the profile directory (`~/.dsh/profiles/web`). | +| `minimum release age` / version `< 24h` | The release is younger than 24 hours. Wait, or re-run once (pnpm auto-adds `minimumReleaseAgeExclude`). | | "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). | +| 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. | | 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. | -| Terminal shows "node-pty failed to load" | The `node-pty` install is missing or broken (e.g. pnpm skipped its build script). The terminal banner shows a repair command — copy it into a terminal/cmd on the DSH machine and run it (POSIX: `bash "/scripts/install.sh" --repair`; Windows: the matching `install.ps1 -Repair`; or re-run the one-click installer), then restart DSH and click Retry. The plugin and DSH core share the same `node-pty@^1.1.0`, so the repair restores both. | -| No bash / curl on Windows | Use the PowerShell one-click command, or install Git Bash / WSL and run the bash commands. | +| Terminal shows "node-pty failed to load" | The `node-pty` install is missing or broken (e.g. pnpm skipped its build script). The terminal banner shows a repair command — copy it into a terminal/cmd on the DSH machine and run it (in `~/.dsh/profiles/web`: `pnpm approve-builds --all && pnpm rebuild node-pty`), then restart DSH and click Retry. The plugin and DSH core share the same `node-pty@^1.1.0`, so the repair restores both. | +| `dsh: command not found` | Install DSH first, or run `npx -y --package @deepseek-ai/dsh dsh plugin --profile web add dsh-better-sidebar`. |