figmar/apes-sidebar
1
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: 安装章节折叠技术细节为可折叠块，版本引用更新为 0.10.3

Browse Source
This commit is contained in:
Menghuan1918
2026-08-14 00:59:02 +08:00
parent 3cbf43854b
commit 97e52b650e
2 changed files with 76 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+38 -28
View File
@@ -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）即可看到侧边栏。
<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.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. 清理旧版残留的手动挂载行，避免「双挂载」（页面出现两个侧边栏）。
</details>
不确定的话，可先加 `--dry-run`（PowerShell 用 `-DryRun`）预览步骤再真正执行。`curl | bash` / `irm | iex` 会执行远程代码——脚本已随仓库开源（`scripts/install.sh` / `scripts/install.ps1`），可先下载审阅。
<details>
<summary><b>手动安装（逐步命令，想看清每一步）</b></summary>
### 手动安装（逐步命令）
适合想看清每一步的用户，与一键脚本等价。**第 ③ 步可重复执行；①② 只需做一次。**
与一键脚本等价。**第 ③ 步可重复执行；①② 只需做一次。**
**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`**）。
</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
@@ -124,7 +129,10 @@ 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>
| 现象 | 原因与解决 |
|---|---|
@@ -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 命令。 |
</details>
<details>
<summary><b>从源码安装 / 开发（可选，替代 npm 方式）</b></summary>
@@ -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`。
</details>
README_EN.md
+38 -28
View File
@@ -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.
<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.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).
</details>
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.
<details>
<summary><b>Manual install (step by step)</b></summary>
### 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**.
</details>
### Updating
<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.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
</details>
<details>
<summary><b>Troubleshooting</b></summary>
| 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. |
</details>
<details>
<summary><b>Install from source / develop (optional — alternative to the npm flow)</b></summary>
@@ -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`.
</details>