AlistConsoleClient

C# .NET 10 客户端，用于与 Alist / Openlist 存储管理系统 API 交互。

Note

以下说明文档由AI辅助生成、人工校验修改，可能存在AI幻觉偏差和猜测语句。请参考实际程序内的help指令和实际交互输出。

功能

• Linux 风格提示符：user@host:path$，带颜色
• 彩色输出：信息灰、成功绿、错误红、警告黄、高亮青
• ls 以对齐表格展示目录内容（目录优先排序）
• cd 支持 ..、绝对路径、相对路径，校验目标是否存在
• cp 自动判断下载方向（本机→服务器暂不支持上传），支持文件夹递归
• 下载进度条：百分比、已传输/总量、实时速度 (B/s ~ MB/s)
• 键盘控制：P 暂停、R 恢复、C 取消，不阻塞控制台输入
• 暂停/取消后保留 .alistdownloading，下次自动续传
• connect 自动检测 Guest 访问权限并提示登录
• setcdnhdr / rmcdnhdr 管理 CDN 专用 HTTP 头

快速开始

╔══════════════════════════════════════╗
║       Alist / Openlist Console       ║
║          Client  v1.0                ║
╚══════════════════════════════════════╝
Type 'help' for available commands.

(not connected)> connect https://myserver.com
Connected to: My Alist Site
  Version : v3.42.0
  Guest access OK — 12 items in root.

guest@myserver:/$ login admin ******
Logged in as 'admin'
  Role      : Admin
  Permissions: CanSeeHidden, CanAccessWithoutPassword, CanMkdirAndUpload,
               CanRename, CanMove, CanCopy, CanRemove, CanWebDavRead,
               CanWebDavWrite, CanFtpRead, CanFtpWrite, CanReadArchives,
               CanDecompressArchives, CanShare

admin@myserver:/$ ls
     Name          Size     Type   Modified            HashInfo
─────────────────────────────────────────────────────────────────────
📁   documents     -        DIR    2026-01-15 08:30    -
📁   images        -        DIR    2026-06-01 12:00    -
📄   README.md     1.2 KB   FILE   2026-01-15 08:30    sha256:abc123...

 2 dir(s), 1 file(s)  [path: /]

admin@myserver:/$ cd documents
→ /documents

admin@myserver:/documents$ cp report.pdf /home/me/Downloads
Downloading 1 file(s), 15.2 MB
  → /home/me/Downloads/report.pdf
  Controls: [P]ause  [R]esume  [C]ancel
[████████████████████████████████████████] 100.0%  15.2 MB / 15.2 MB  8.7 MB/s
  ✓ report.pdf  (15.2 MB)
All 1 file(s) downloaded. (15.2 MB)

admin@myserver:/documents$ cp backups /home/me/
Downloading 47 file(s), 128.5 MB
  → /home/me/backups
  Controls: [P]ause  [R]esume  [C]ancel
[████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░]  23.1%  29.7 MB / 128.5 MB  12.3 MB/s
  ✓ db_dump.sql.gz  (22.3 MB)
  ✓ config.json  (1.8 KB)
  ...

控制台命令参考

命令	参数	说明
connect	<url>	连接服务器，显示设置与 Guest 权限状态
login	<user> <pass>	用户名密码登录，打印用户权限
logout	—	登出当前用户，保留服务器连接
disconnect	—	登出并断开，清空全部缓存状态
ls	—	列出当前目录条目（目录优先，对齐表格）
cd	<dir>	进入目录；.. 返回上级；支持绝对路径和双引号包裹
cp	<src> <dst>	下载文件或文件夹至本机；目标存在时询问续传/删除重下/跳过
setpwd	<password>	设置目录访问密码
sethdr	<key> <value>	添加 API 请求头
rmhdr	<key>	删除 API 请求头
setcdnhdr	<key> <value>	添加 CDN 下载请求头
rmcdnhdr	<key>	删除 CDN 下载请求头
help	—	显示帮助
exit / quit	—	退出程序

下载控制键：

按键	功能
P	暂停当前传输（进度文件保留，可续传）
R	恢复暂停的传输
C	取消传输（已下载部分与进度文件保留，可续传）

断点续传机制

• 每次下载在目标路径同目录创建 <filename>.alistdownloading JSON 文件，记录 downloaded_bytes、total_size、url
• 下次启动同一 cp 命令时自动读取该文件，从已下载字节位置发起 HTTP Range 请求
• 若服务器不支持 Range（返回 200 OK 而非 206 Partial Content），自动回退从头下载
• 下载完成后自动删除进度文件；暂停或取消后予以保留
• 控制台冲突检测询问 Y(续传) / D(删除重下) / N(跳过)

错误处理

• 所有 API 错误通过 AlistException 抛出，包含 int Code 和 string Message
• /api/fs/list 返回非 200 时异常消息反映原始错误码与描述（如 [403] Refresh without permission）
• 网络超时、JSON 解析失败等均有对应处理
• 下载过程中网络中断时进度文件保留，下次自动续传

架构设计

• API 客户端：单例 HttpClient 负责所有 API 请求；自定义请求头存于线程安全字典，每次请求时快照注入，避免 DefaultRequestHeaders 竞争
• 下载客户端：静态共享 HttpClient（SocketsHttpHandler 连接池，5 分钟生命周期），可选通过 IHttpClientFactory 注入
• 流管理：DelegatingDisposeStream 包装下载流，Dispose 时连带释放 HttpResponseMessage，避免资源泄漏
• JSON：System.Text.Json，全局 AllowReadingFromString 兼容 Openlist 字符串数值字段
• 分页：GetCurrentEntries() 内部循环拉取所有页数据，per_page 参数可自定义