docs(cli): finalize installation guide for stage-two delivery

areyoubugcoder · areyoubugcoder · commit bd54fa37683e · 2026-05-14T13:46:01.000+08:00
阶段二代码就绪后改写 CLI 安装文档与命令参考：

- install.md 从「阶段一仅本地构建」改写为四种正式方式：
  install.sh / npm 包装 / 直接下载 / 源码构建。每节附环境变量
  覆盖示例（INSTALL_DIR / VERSION / NO_VERIFY / MP2RSS_VERSION /
  MP2RSS_NO_VERIFY）与卸载指引；总览说明资产命名约定与
  checksums.txt 校验。
- faq.md 新增「如何更新到最新版本」：mp2rss update（推荐）+
  pnpm up -g @mp2rss/cli + 重跑 install.sh + 源码 git pull 四条
  路径；卸载条目按四种安装方式补全。
- commands.md `mp2rss update` 节从占位说明改写为完整行为描述：
  GitHub Releases 拉 + checksums.txt SHA-256 校验 + 原子替换 +
  macOS quarantine 处理；tip 提示包管理器装的用户优先用包管理器
  升级。
- index.md 安装速览改为四种方式简写 + 链接到 install.md。

所有 release 资源链接统一指向 /releases/latest，避免硬编码版本号。
diff --git a/docs/cli/commands.md b/docs/cli/commands.md
@@ -236,16 +236,23 @@ mp2rss mp articles 2234567 -o json | jq '.items[].title'
 
 ## `mp2rss update`
 
-自更新命令。
+自更新到 GitHub Releases 的最新版本。
 
 ```bash
 mp2rss update                # 检查并执行更新
 mp2rss update --check        # 只检查不更新
-mp2rss update --force        # 跳过版本对比强制更新
+mp2rss update --force        # 即使版本相同也强制重装
 ```
 
-::: warning 当前阶段为占位实现
-当前版本执行该命令仅会提示「自更新功能将在 v1.x 版本启用」。完整功能（拉取最新 release 并原子替换）将在 v1.x 上线时启用。
+行为：
+
+1. 查询 `https://api.github.com/.../releases/latest`，按语义版本与本地比对（预发布版本视为更老）。
+2. 下载对应平台归档 + `checksums.txt`，校验 SHA-256。
+3. 暂存为 `<selfpath>.new` 后 `os.Rename` **原子替换**；Windows 下若旧二进制被占用，会先改名 `.old` 再换入。
+4. macOS 自动 `xattr -d com.apple.quarantine` 去掉 Gatekeeper 隔离属性。
+
+::: tip 通过 npm / 包管理器装的怎么升级？
+仍可用 `mp2rss update`，但**推荐改用对应包管理器**（如 `pnpm up -g @mp2rss/cli`），避免下次包管理器升级时哈希校验冲突。详见 [FAQ](./faq#如何更新到最新版本)。
 :::
 
 ## 配置与环境变量
diff --git a/docs/cli/faq.md b/docs/cli/faq.md
@@ -84,6 +84,58 @@ mp2rss mp list -o json
 
 CLI 在写入时会强制设置上述权限。如果权限被外部修改成更宽松的值，下次写入会自动恢复。
 
+## 如何更新到最新版本？
+
+按安装方式选择对应的更新路径：
+
+### 推荐：`mp2rss update`（任何安装方式通用）
+
+```bash
+mp2rss update              # 检查并升级到最新 release
+mp2rss update --check      # 只检查，不下载
+mp2rss update --force      # 即使版本相同也强制重装
+```
+
+行为细节：
+
+- 查询 `https://api.github.com/.../releases/latest`，与本地版本比对（语义版本，预发布版本视为更老）。
+- 下载平台归档 + `checksums.txt`，校验 SHA-256。
+- 暂存为 `<selfpath>.new` 后 `os.Rename` 原子替换；Windows 会先把旧二进制改名 `.old` 再换入，避免「文件正在使用」。
+- macOS 会自动 `xattr -d com.apple.quarantine` 去掉 Gatekeeper 隔离属性。
+
+::: tip 通过包管理器装的，仍可用 `mp2rss update` 吗？
+可以，但**推荐改用对应包管理器**，避免覆盖被包管理器接管的文件——下次包管理器升级时可能出现哈希校验冲突。
+:::
+
+### npm / pnpm 安装的场景
+
+```bash
+pnpm up -g @mp2rss/cli
+# 或
+npm update -g @mp2rss/cli
+```
+
+`postinstall` 会重新拉对应版本的二进制并校验 SHA-256。
+
+### install.sh 安装的场景
+
+直接重跑安装命令即可：
+
+```bash
+curl -fsSL https://mp2rss.com/install.sh | sh
+```
+
+脚本会发现已存在的二进制并覆盖到同一位置。可用 `VERSION=v0.2.0` 锁定具体版本。
+
+### 源码构建的场景
+
+```bash
+cd /path/to/mp2rss-cli
+git pull
+make build
+sudo install -m 0755 mp2rss /usr/local/bin/mp2rss
+```
+
 ## 怎么完全卸载并清理本地痕迹？
 
 ```bash
@@ -93,8 +145,10 @@ mp2rss auth logout
 # 2. 删除配置目录
 rm -rf ~/.mp2rss
 
-# 3. 从 PATH 中删掉二进制
-sudo rm /usr/local/bin/mp2rss   # 或你自己放置的位置
+# 3. 从 PATH 中删掉二进制（按你的安装方式选一种）
+sudo rm /usr/local/bin/mp2rss          # install.sh / 源码构建 / 直接下载
+rm "$HOME/.local/bin/mp2rss"           # install.sh 默认目录
+pnpm rm -g @mp2rss/cli                 # npm / pnpm / yarn 安装
 ```
 
 ## 怎么报 Bug / 提需求？
diff --git a/docs/cli/index.md b/docs/cli/index.md
@@ -31,25 +31,23 @@ mp2rss mp list
 
 ## 安装速览
 
-阶段一仅提供 **本地源码构建** 方式：
+四种方式，按场景任选其一：
 
 ```bash
-git clone https://github.com/areyoubugcoder/mp2rss-cli.git
-cd mp2rss-cli
-go build -o mp2rss .
-```
+# 一键安装（推荐 macOS / Linux）
+curl -fsSL https://mp2rss.com/install.sh | sh
 
-::: tip 上线后可用的安装方式
-首个正式版本（v1.x）发布后将开放以下安装方式，安装文档届时一并补充：
+# npm 包装（Node ≥ 18）
+pnpm add -g @mp2rss/cli
 
-- Homebrew（macOS / Linux）
-- npm 包装 `@mp2rss/cli`
-- 一键安装脚本 `https://mp2rss.com/install.sh`
-- 直接从 GitHub Releases 下载对应平台二进制
+# 直接下载
+# https://github.com/areyoubugcoder/mp2rss-cli/releases/latest
 
-:::
+# 源码构建（Go ≥ 1.21）
+git clone https://github.com/areyoubugcoder/mp2rss-cli.git && cd mp2rss-cli && make build
+```
 
-详细安装步骤见 [安装](./install)。
+详细步骤、环境变量覆盖与卸载指引见 [安装](./install)。
 
 ## 下一步
 
diff --git a/docs/cli/install.md b/docs/cli/install.md
@@ -1,79 +1,202 @@
 # 安装
 
+`mp2rss` 提供四种安装方式，可按场景任选其一。
+
 ## 系统要求
 
-- 操作系统：macOS、Linux、Windows 任一现代版本均可。
-- 架构：x86_64（amd64）或 arm64。
-- 构建工具（仅本地构建需要）：Go 1.22 或更新版本。
+- **操作系统**：macOS、Linux、Windows（amd64 / arm64）。
+- **架构**：x86_64（amd64）或 arm64。
+- **可选依赖**：
+  - `install.sh` 一键安装：`curl` 或 `wget` + `tar`；macOS / Linux。
+  - `npm` 包装：Node.js ≥ 18。
+  - 源码构建：Go ≥ 1.21。
+  - 直接下载：`tar`（unix）或解压 zip 的工具（Windows）。
+
+::: tip 哪种装法适合我？
+- 桌面 / 开发机首次安装 → **install.sh 一键安装**。
+- Node 工具链已就绪、想随 `package.json` 锁定版本 → **npm 包装**。
+- 离线分发 / 公司内部镜像 / CI 缓存 → **直接下载**。
+- 想跟踪未发布的 `main` → **源码构建**。
+:::
+
+资产命名约定（所有安装方式底层都拉这些文件）：
+
+```
+mp2rss-cli_<version>_<goos>_<goarch>.tar.gz   # darwin / linux
+mp2rss-cli_<version>_<goos>_<goarch>.zip      # windows
+checksums.txt                                 # 每个 release 配套的 SHA-256 清单
+```
 
-## 本地源码构建（当前阶段唯一方式）
+每个 release 同时附带 `checksums.txt`，建议保留校验环节，避免镜像被篡改。
 
-阶段一只提供本地源码构建。完整步骤：
+## 方式一：install.sh 一键安装（推荐 macOS / Linux）
 
 ```bash
-# 1. 克隆仓库
-git clone https://github.com/areyoubugcoder/mp2rss-cli.git
-cd mp2rss-cli
+curl -fsSL https://mp2rss.com/install.sh | sh
+```
 
-# 2. 构建二进制（产物即当前目录下的 mp2rss）
-go build -o mp2rss .
+脚本会：
 
-# 3. 验证
-./mp2rss --version
-./mp2rss --help
+1. 探测当前 OS / 架构；
+2. 通过 `api.github.com/.../releases/latest` 解析最新 tag；
+3. 选写优先级 `$HOME/.local/bin` → `$HOME/bin` → `/usr/local/bin`（前者权限不足时回退，最后一档可能需要 `sudo`）；
+4. 下载对应平台的 `tar.gz` 并对照 `checksums.txt` 校验 SHA-256；
+5. 解压、`chmod 755`，并尝试 `mp2rss --version` 自检。
+
+### 环境变量覆盖
+
+```bash
+# 指定安装目录
+curl -fsSL https://mp2rss.com/install.sh | INSTALL_DIR="$HOME/.local/bin" sh
+
+# 指定版本（默认最新）
+curl -fsSL https://mp2rss.com/install.sh | VERSION=v0.2.0 sh
+
+# 跳过 SHA-256 校验（仅在受信镜像 / 离线环境下使用）
+curl -fsSL https://mp2rss.com/install.sh | NO_VERIFY=1 sh
+
+# 组合使用
+curl -fsSL https://mp2rss.com/install.sh \
+  | INSTALL_DIR="$HOME/.local/bin" VERSION=v0.2.0 NO_VERIFY=1 sh
 ```
 
-把 `mp2rss` 放到 `PATH` 中任意目录（例如 `/usr/local/bin` 或 `~/bin`）后即可全局调用：
+### 卸载
 
 ```bash
-sudo mv mp2rss /usr/local/bin/
-mp2rss --version
+# 1. 删除二进制（脚本提示的 install_dir）
+rm "$HOME/.local/bin/mp2rss"
+
+# 2. 清理本地配置（可选）
+rm -rf ~/.mp2rss
 ```
 
-::: tip 关于体积
-默认 `go build` 出来的二进制约 12–14 MB。仓库 `Makefile` 中提供了 `make build` 目标，会附加 `-trimpath -ldflags="-s -w"` 等参数进一步压缩到 10 MB 左右。
+::: warning Windows 用户
+`install.sh` 仅覆盖 macOS / Linux。Windows 请使用 [方式二：npm 包装](#方式二-npm-包装) 或 [方式三：直接下载](#方式三-直接下载-github-releases)。
 :::
 
-## 升级
+## 方式二：npm 包装
 
-在仓库目录 `git pull` 后重新执行 `go build` 即可。`mp2rss update` 命令将在 v1.x 版本启用，届时支持一键自更新。
+适合 Node 工具链已就绪、CI 中按 `package.json` 锁定版本的场景。Node ≥ 18。
 
-## 卸载
+```bash
+# pnpm
+pnpm add -g @mp2rss/cli
 
-把 `mp2rss` 二进制从 `PATH` 中删除即可。配置目录在 `~/.mp2rss/`，如不再使用：
+# npm
+npm install -g @mp2rss/cli
+
+# yarn
+yarn global add @mp2rss/cli
+```
+
+`postinstall` 会按当前 OS / 架构从 GitHub Releases 拉对应二进制，并对照 `checksums.txt` 校验 SHA-256。可通过环境变量微调：
 
 ```bash
-rm -rf ~/.mp2rss
+# 指定版本（覆盖 package.json）
+MP2RSS_VERSION=0.2.0 pnpm add -g @mp2rss/cli
+
+# 跳过 SHA-256 校验
+MP2RSS_NO_VERIFY=1 pnpm add -g @mp2rss/cli
 ```
 
-## v1.x 起将支持
+### 卸载
 
-以下安装方式会在首个正式版本（v1.x）发布后启用，本页面届时一并补充具体命令与下载链接：
+```bash
+pnpm rm -g @mp2rss/cli     # 或 npm uninstall -g @mp2rss/cli / yarn global remove @mp2rss/cli
+rm -rf ~/.mp2rss           # 清理本地配置（可选）
+```
+
+## 方式三：直接下载（GitHub Releases）
 
-### Homebrew
+[最新 release 页面](https://github.com/areyoubugcoder/mp2rss-cli/releases/latest) 一律附带四个平台归档 + `checksums.txt`。
+
+### 自动选择最新版本（脚本片段）
 
 ```bash
-# 占位，上线后可用
-brew install areyoubugcoder/tap/mp2rss
+REPO=areyoubugcoder/mp2rss-cli
+TAG=$(curl -fsSL "https://api.github.com/repos/$REPO/releases/latest" \
+  | sed -n 's/.*"tag_name":[[:space:]]*"\(v[^"]*\)".*/\1/p' | head -n1)
+SEMVER=${TAG#v}
+# 按本机平台替换 darwin/amd64 → 你的目标
+OS=darwin ARCH=arm64
+ASSET="mp2rss-cli_${SEMVER}_${OS}_${ARCH}.tar.gz"
+
+curl -L -o "$ASSET" \
+  "https://github.com/$REPO/releases/download/$TAG/$ASSET"
+curl -L -o checksums.txt \
+  "https://github.com/$REPO/releases/download/$TAG/checksums.txt"
+
+# 校验
+shasum -a 256 -c <(grep " $ASSET\$" checksums.txt)
+
+# 解压并安装
+tar -xzf "$ASSET" mp2rss
+sudo install -m 0755 mp2rss /usr/local/bin/mp2rss
+mp2rss --version
 ```
 
-### npm 包装
+### 平台对应资产
+
+| 平台 | 资产 |
+| ---- | ---- |
+| macOS Apple Silicon | `mp2rss-cli_<version>_darwin_arm64.tar.gz` |
+| macOS Intel | `mp2rss-cli_<version>_darwin_amd64.tar.gz` |
+| Linux x86_64 | `mp2rss-cli_<version>_linux_amd64.tar.gz` |
+| Linux arm64 | `mp2rss-cli_<version>_linux_arm64.tar.gz` |
+| Windows x86_64 | `mp2rss-cli_<version>_windows_amd64.zip` |
+| Windows arm64 | `mp2rss-cli_<version>_windows_arm64.zip` |
+
+Windows 用 `tar -xf <asset>.zip mp2rss.exe`（Windows 10+ 内置 `tar` 支持 zip），或资源管理器解压。
+
+### 卸载
 
 ```bash
-# 占位，上线后可用
-npm install -g @mp2rss/cli
+# unix
+sudo rm /usr/local/bin/mp2rss
+
+# Windows（PowerShell）
+Remove-Item "$Env:USERPROFILE\bin\mp2rss.exe"
+
+# 清理本地配置（可选）
+rm -rf ~/.mp2rss
 ```
 
-### 一键安装脚本
+## 方式四：源码构建
+
+适合需要跟踪未发布 `main`、自行打包、或为新平台编译的场景。需要 Go ≥ 1.21。
 
 ```bash
-# 占位，上线后可用
-curl -fsSL https://mp2rss.com/install.sh | sh
+git clone https://github.com/areyoubugcoder/mp2rss-cli.git
+cd mp2rss-cli
+make build              # 等价于 go build -trimpath -ldflags="-s -w" -o mp2rss .
+./mp2rss --version
+```
+
+把产物放到 `PATH`：
+
+```bash
+sudo install -m 0755 mp2rss /usr/local/bin/mp2rss
+```
+
+::: tip 关于体积
+默认 `go build` 出来约 12–14 MB；`make build` 会附加 `-trimpath -ldflags="-s -w"`，压缩到 ~10 MB。
+:::
+
+### 卸载
+
+```bash
+sudo rm /usr/local/bin/mp2rss
+rm -rf ~/.mp2rss          # 清理本地配置（可选）
+# 仓库目录直接删除即可
 ```
 
-### GitHub Releases 直接下载
+## 升级
+
+参见 [FAQ → 如何更新到最新版本](./faq#如何更新到最新版本)：
 
-发行版会按平台 / 架构提供独立的归档包与 `checksums.txt`，可在 [Releases](https://github.com/areyoubugcoder/mp2rss-cli/releases) 页面下载并校验。
+- `mp2rss update` 自更新（推荐，所有安装方式通用）
+- `pnpm up -g @mp2rss/cli`（npm 安装的场景）
+- 重跑 `install.sh`（脚本安装的场景）
 
 ## 下一步
 
