feat: download shared links

CONTRIBUTING.md

@@ -1,19 +1,28 @@
 # 参与贡献
 
-欢迎提交 Issue 和 Pull Request。开始修改前，请先搜索已有 Issue；较大的协议或行为变更建议
-先开 Issue 说明使用场景和安全影响。
+欢迎提交 Issue 和 Pull Request。协议、认证、数据写入或命令行为的较大变更，建议先在 Issue
+中说明使用场景、兼容性和安全影响。
 
-开发环境需要 Go 1.22、GNU Make 和可用于 race detector 的 C 编译工具链。提交前运行：
+## 开发与检查
+
+开发环境需要 Go 1.22、GNU Make 和支持 race detector 的 C 编译工具链。提交前运行：
 
 ```bash
 make test
 CGO_ENABLED=0 go test ./...
 git diff --check
 ```
 
-贡献应包含与行为变化对应的测试，并保持错误输出不泄露秘密。测试 fixture 必须使用虚构的
-账户、对象 ID、token、URL、证书和路径；不要提交真实凭据、浏览器数据、OAuth 回调、签名
-对象 URL或个人文件名。Release 中的系统 SPKI pin 是经过独立核验后公开分发的信任锚；普通
-测试 fixture 不应复制生产证书或 pin。
+行为变更应配套单元或协议测试，并同步更新 README 或 `docs/`。提交只包含本次修改需要的
+文件，保持 commit 信息清晰。
+
+## 测试数据与秘密
+
+测试 fixture 使用虚构的账户、对象 ID、token、共享链接、证书和路径。请勿提交真实凭据、
+浏览器数据、OAuth 回调 URL、Cookie、link token、签名对象 URL 或个人文件名。错误信息与
+测试日志也不能包含这些内容。
+
+Release 中的系统 SPKI pin 是通过独立渠道核验后分发的公开信任锚；普通测试 fixture 使用
+本地测试证书和测试 pin。
 
 提交即表示贡献内容按本仓库的 [MIT License](LICENSE) 授权。

Makefile

@@ -1,7 +1,7 @@
 SHELL := /bin/sh
 
 ifeq ($(origin VERSION),undefined)
-override VERSION := 0.2.0
+override VERSION := 0.3.0
 else
 override VERSION := $(value VERSION)
 endif

README.md

@@ -1,35 +1,35 @@
 # 北大网盘轻量 CLI
 
-`pku-drive` 是一个面向 Linux 服务器和 SSH 终端的非官方北大网盘命令行工具，支持浏览器
-登录、列目录、创建目录、上传、下载、删除和注销。发布包是 Linux amd64 静态单文件；每个
-服务器用户使用各自的北大账号和凭据。
+`pku-drive` 是面向 Linux 服务器和 SSH 终端的北大网盘命令行工具。它支持浏览器登录、
+目录浏览、文件上传与下载、创建目录、删除，以及直接下载他人分享的文件。发布包是 Linux
+amd64 静态单文件；系统中的每位用户使用自己的北大账号和凭据。
 
 ## 安装
 
-Debian / Ubuntu 推荐安装 `.deb`：
+### Debian / Ubuntu
 
 ```bash
-curl -LO https://github.com/Findddx/pku-drive-cli/releases/download/v0.2.0/pku-drive-cli_0.2.0-1_amd64.deb
-curl -LO https://github.com/Findddx/pku-drive-cli/releases/download/v0.2.0/SHA256SUMS
-grep '  pku-drive-cli_0.2.0-1_amd64.deb$' SHA256SUMS | sha256sum -c -
-sudo apt install ./pku-drive-cli_0.2.0-1_amd64.deb
+curl -LO https://github.com/Findddx/pku-drive-cli/releases/download/v0.3.0/pku-drive-cli_0.3.0-1_amd64.deb
+curl -LO https://github.com/Findddx/pku-drive-cli/releases/download/v0.3.0/SHA256SUMS
+grep '  pku-drive-cli_0.3.0-1_amd64.deb$' SHA256SUMS | sha256sum -c -
+sudo apt install ./pku-drive-cli_0.3.0-1_amd64.deb
 pku-drive version
 ```
 
-其他 Linux amd64 发行版可安装 tar 包：
+### 其他 Linux amd64 发行版
 
 ```bash
-curl -LO https://github.com/Findddx/pku-drive-cli/releases/download/v0.2.0/pku-drive-cli-0.2.0-linux-amd64.tar.gz
-curl -LO https://github.com/Findddx/pku-drive-cli/releases/download/v0.2.0/SHA256SUMS
-grep '  pku-drive-cli-0.2.0-linux-amd64.tar.gz$' SHA256SUMS | sha256sum -c -
-sudo tar -xzf pku-drive-cli-0.2.0-linux-amd64.tar.gz --strip-components=1 -C /
+curl -LO https://github.com/Findddx/pku-drive-cli/releases/download/v0.3.0/pku-drive-cli-0.3.0-linux-amd64.tar.gz
+curl -LO https://github.com/Findddx/pku-drive-cli/releases/download/v0.3.0/SHA256SUMS
+grep '  pku-drive-cli-0.3.0-linux-amd64.tar.gz$' SHA256SUMS | sha256sum -c -
+sudo tar -xzf pku-drive-cli-0.3.0-linux-amd64.tar.gz --strip-components=1 -C /
 /usr/local/bin/pku-drive version
 ```
 
-不要同时安装两种包。系统安装后所有 Linux 用户都能运行程序，但每个用户必须以自己的
-普通账号分别登录；日常网盘命令不要加 `sudo`。
+同一台机器选择一种系统安装方式即可。安装后所有用户都能运行 `pku-drive`，每位用户以
+自己的普通 Linux 账号登录；日常命令无需 `sudo`。
 
-从源码构建：
+### 从源码构建
 
 ```bash
 git clone https://github.com/Findddx/pku-drive-cli.git
@@ -41,112 +41,160 @@ make build
 
 ## 登录
 
-浏览器运行在服务器、VNC 或 X11 环境时：
+服务器有桌面、VNC 或 X11 浏览器时：
 
 ```bash
 pku-drive login
 pku-drive status
 ```
 
-浏览器运行在 SSH 客户端电脑上时：
+通过 SSH 登录服务器、浏览器运行在本地电脑时：
 
 ```bash
 pku-drive login --paste-callback
 ```
 
-打开终端打印的授权链接并完成统一身份认证。浏览器最后跳到
-`http://127.0.0.1:PORT/callback?...` 时，即使页面显示无法连接，也复制地址栏中的**完整
-URL**，粘贴到 SSH 终端的隐藏输入提示并回车。该 URL 含一次性认证信息，不要分享或保存。
+在本地浏览器打开终端显示的授权链接并完成统一身份认证。浏览器最后跳转到
+`http://127.0.0.1:PORT/callback?...` 后，复制地址栏中的**完整 URL**，粘贴回 SSH 终端并
+回车。页面显示无法连接不影响粘贴认证。回调 URL 含一次性认证信息，请勿分享、记录或写入
+命令历史。
+
+## 路径规则
+
+- 网盘路径是以 `/` 开头的绝对路径，例如 `'/个人文档/课题/data.csv'`。
+- 本地路径与普通 shell 命令相同，可以是相对路径或绝对路径。
+- 路径含空格、中文或 shell 特殊字符时，用单引号包围。
+- 分享链接内的路径相对于分享根目录，不以 `/` 开头，例如 `'数据/样本.csv'`。
+
+## 命令速查
+
+| 操作 | 命令 |
+|---|---|
+| 登录 | `pku-drive login [--paste-callback]` |
+| 查看登录状态 | `pku-drive status` |
+| 列出网盘目录 | `pku-drive ls [网盘目录]` |
+| 创建目录 | `pku-drive mkdir '网盘目录' [--parents]` |
+| 上传文件 | `pku-drive put 本地文件 '网盘文件或目录'` |
+| 下载文件 | `pku-drive get '网盘文件' 本地文件或目录` |
+| 浏览分享链接 | `pku-drive ls --share 分享链接 [分享内目录]` |
+| 下载分享文件 | `pku-drive get --share 分享链接 本地目录 [分享内文件...]` |
+| 删除 | `pku-drive rm '网盘文件或目录' [--recursive]` |
+| 注销 | `pku-drive logout` |
+| 查看版本 | `pku-drive version` |
 
 ## 常用操作
 
-远端路径使用以 `/` 开头的绝对路径；含空格或中文时用单引号包围。
-
-### 查看状态和目录
+### 查看目录
 
 ```bash
-pku-drive status
 pku-drive ls /
-pku-drive ls '/个人文档/项目'
+pku-drive ls '/个人文档/课题'
 ```
 
-### 创建文件夹
+### 上传文件
+
+参数顺序是 `put 本地文件 '网盘文件或目录'`：
 
 ```bash
-# 父目录必须存在
-pku-drive mkdir '/个人文档/项目/数据'
+# 上传并指定网盘文件名
+pku-drive put ./report.csv '/个人文档/课题/report.csv'
+
+# 上传到已有网盘目录，保留文件名 report.csv
+pku-drive put ./report.csv '/个人文档/课题/'
+
+# 覆盖网盘中的同名文件
+pku-drive put ./report.csv '/个人文档/课题/report.csv' --overwrite
 
-# 同时创建缺少的各级父目录
-pku-drive mkdir '/个人文档/项目/数据/2026' --parents
+# 大文件上传；中断后重复同一命令可继续已校验的分片
+pku-drive put ./dataset.tar '/个人文档/课题/dataset.tar' --quiet
 ```
 
-### 上传
+### 下载自己的网盘文件
 
-参数顺序是：`put 本地文件 '网盘文件或目录'`。
+参数顺序是 `get '网盘文件' 本地文件或目录`：
 
 ```bash
-# 指定网盘文件名
-pku-drive put ./report.csv '/个人文档/项目/report.csv'
+# 下载并指定本地文件名
+pku-drive get '/个人文档/课题/report.csv' ./report.csv
 
-# 上传到已有网盘目录，保留本地文件名 report.csv
-pku-drive put ./report.csv '/个人文档/项目/'
+# 下载到已有目录，保留文件名 report.csv
+pku-drive get '/个人文档/课题/report.csv' ./downloads/
 
-# 覆盖已有同名文件
-pku-drive put ./report.csv '/个人文档/项目/report.csv' --overwrite
-
-# 不显示传输进度；上传中断后重复同一条命令即可续传
-pku-drive put ./large.bin '/个人文档/项目/large.bin' --quiet
+# 覆盖本地同名文件
+pku-drive get '/个人文档/课题/report.csv' ./report.csv --overwrite
 ```
 
-默认不覆盖已有文件；只有显式使用 `--overwrite` 才会覆盖。
-
-### 下载
-
-参数顺序是：`get '网盘文件' 本地文件或已有目录`。
+### 创建与删除目录
 
 ```bash
-# 指定本地文件名
-pku-drive get '/个人文档/项目/report.csv' ./report.csv
+# 父目录已经存在
+pku-drive mkdir '/个人文档/课题/数据'
 
-# 下载到已有本地目录，保留网盘文件名 report.csv
-pku-drive get '/个人文档/项目/report.csv' ./downloads/
+# 同时创建缺少的父目录
+pku-drive mkdir '/个人文档/课题/数据/2026' --parents
 
-# 覆盖已有本地文件
-pku-drive get '/个人文档/项目/report.csv' ./report.csv --overwrite
+# 删除文件，通常移入网盘回收站
+pku-drive rm '/个人文档/课题/report.csv'
 
-# 不显示传输进度
-pku-drive get '/个人文档/项目/large.bin' ./large.bin --quiet
+# 删除目录及其中内容
+pku-drive rm '/个人文档/课题/旧数据' --recursive
 ```
 
-下载先写入同目录临时文件，完整性核验成功后再原子放到目标位置；默认不覆盖本地文件。
+## 下载分享链接
+
+公开分享（anonymous）可直接浏览和下载。组织范围分享（realname）先运行 `pku-drive login`
+或 `pku-drive login --paste-callback`，工具会使用当前用户身份检查访问权限。
 
-### 删除
+交互式选择：
 
 ```bash
-# 删除文件：移入网盘回收站
-pku-drive rm '/个人文档/项目/report.csv'
+mkdir -p ./downloads
+pku-drive get --share 'https://disk.pku.edu.cn/link/...' ./downloads/
+```
+
+本地目标必须是已存在的目录。单文件分享会直接下载；文件夹分享每次显示当前目录的一层
+内容，进入目录时再加载下一层，因此大型分享也能快速浏览。选择会在切换目录后保留，下载
+时维持分享中的相对目录结构。批量下载按文件逐个校验和落盘；若中途失败，终端会报告已完成
+数量，已完成文件保留在目标目录。重试时可只选择未完成文件，或确认覆盖后加入 `--overwrite`。
+
+| 按键 | 操作 |
+|---|---|
+| `↑` / `↓` 或 `k` / `j` | 移动光标 |
+| `→` 或 `l` | 进入目录 |
+| `←`、`h` 或 `Backspace` | 返回上级目录 |
+| `Space` | 选中或取消当前文件 |
+| `Enter` | 确认并开始下载 |
+| `q` 或 `Esc` | 取消 |
+
+脚本和无交互终端先用 JSON 列目录，再按相对路径下载一个或多个文件：
 
-# 删除目录及其全部内容：必须显式加 --recursive
-pku-drive rm '/个人文档/项目/旧数据' --recursive
+```bash
+pku-drive ls --share 'https://disk.pku.edu.cn/link/...' --json
+pku-drive ls --share 'https://disk.pku.edu.cn/link/...' '数据' --json
+pku-drive get --share 'https://disk.pku.edu.cn/link/...' ./downloads/ \
+  'README.pdf' '数据/样本.csv' --json
 ```
 
-删除通常会移入网盘回收站；若服务器启用了删除审核，命令会显示已提交审核。`/` 和顶级
-文档库不能删除。
+当前版本处理无需提取码和手机验证的分享链接。相关错误处理见
+[故障排查](docs/troubleshooting.md#分享链接)。
+
+## JSON 输出
 
-### JSON、注销和版本
+在命令末尾加入 `--json` 可获得结构化结果：
 
 ```bash
-pku-drive ls '/个人文档/项目' --json
 pku-drive status --json
-pku-drive logout
-pku-drive version
+pku-drive ls '/个人文档/课题' --json
+pku-drive put ./report.csv '/个人文档/课题/report.csv' --json
 ```
 
-## 更多文档
+脚本应同时检查进程退出码和 JSON 中的 `ok` 字段。诊断信息与登录授权链接输出到 stderr。
+
+## 文档
 
-- [完整参考与故障排查](docs/troubleshooting.md)
+- [故障排查与高级说明](docs/troubleshooting.md)
 - [API 与兼容性说明](docs/api-notes.md)
 - [安全策略](SECURITY.md)
 - [参与贡献](CONTRIBUTING.md)
 
-本项目不是北京大学或爱数官方软件。
+本项目是社区维护的非官方工具，与北京大学及爱数无隶属关系。