---

1.1 特性
登录 / 登出
列出当前目录文件（ls）
切换目录（cd）与刷新（refresh / re）
下载单文件或递归下载文件夹（download / d）
上传文件（upload）
创建文件夹（mkdir）
删除文件（rm）
创建分享链接（share）
获取文件直链（link）
回收站管理（recycle / restore）
协议切换（protocol android|web）
支持保存配置到 JSON 文件（authorization、device/os、protocol 等）
1.2 脚本环境要求
Python 3
依赖库：requests
安装：
pip install requests  
1.3 安装与运行
1.3.1 脚本运行
克隆或下载本仓库到本地。
进入项目目录。
运行脚本：
python pan123_cli.py  
启动后会提示输入用户名 / 密码，或自动读取配置文件（默认 123pan_config.json，脚本内部根据传入参数使用该文件）。
1.3.2 下载release版
根据系统下载对应的 release 版本，解压后运行 123pan.exe（Windows）或 123pan（Linux）。

1.4 配置文件（JSON）
脚本会读取并保存一个配置文件（示例 123pan_config.json），保存登录状态与偏好，格式示例：

{
  "userName": "your_username",
  "passWord": "your_password",
  "authorization": "Bearer xxxxx",
  "deviceType": "M2007J20CI",
  "osVersion": "Android_10",
  "protocol": "android"
}  
注意：保存密码或 token 到本地会有安全风险，请在可信环境下使用并妥善保护该文件。

1.5 常用命令（交互式）
在脚本交互提示符中输入命令，部分带参数：

指令	用法示例	功能说明
直接输入编号	3	若编号对应文件夹 → 进入该文件夹；若为文件 → 直接下载该文件
ls	ls	显示当前目录的文件与文件夹列表
cd [编号|..|/]	cd 3、cd ..、cd /	切换目录：进入指定编号的文件夹、返回上级、返回根目录
mkdir [名称]	mkdir test	在当前目录创建文件夹
upload [路径]	upload C:\Users\you\Desktop\file.txt	上传文件到当前目录（仅支持单个文件）
rm [编号]	rm 2	删除当前列表中指定编号的文件/文件夹（移入回收站）
share [编号 ...]	share 2 4	为指定文件创建一个或多个分享链接，可设置提取码（可为空）
link [编号]	link 3	获取指定文件的直链地址
download / d [编号]	download 5 或 d 5	下载指定编号的文件或文件夹（文件夹将递归下载）
recycle	recycle	查看回收站内容，可恢复指定编号项或输入 clear 清空回收站
refresh / re	refresh 或 re	刷新当前目录列表
reload	reload	重新加载配置文件并刷新目录
login / logout	login、logout	手动登录或登出（清除授权信息）
clearaccount	clearaccount	清除已登录账号（包括用户名和密码）
more	more	当目录分页未加载完时，继续加载更多内容
protocol [android|web]	protocol web	切换通信协议（如 android/web），并可选择保存配置
exit	exit	退出程序
交互示例：

/> cd demo  
无效命令，使用 '..' 返回上级，'/' 返回根目录，或输入文件夹编号  
/> cd 1     
当前目录为空  
/demo1> ls  
当前目录为空  
/demo1> mkdir test  
目录 'test' 创建成功  

/demo1> 1  
当前目录为空  
/demo1/test> upload 123pan.py  
上传进度: 100.0%  
上传完成，正在验证...  
文件上传成功  
------------------------------------------------------------  
编号    类型      大小          名称  
------------------------------------------------------------  
1     文件      38.66 KB    123pan.py  
============================================================  

/demo1/test> 1  
开始下载: 123pan.py  
进度: 100.0% | 38.66 KB/38.66 KB | 10.29 MB/s        
下载完成: 123pan.py  
/demo1/test>  
2、123Pan接口模块（pan123_core.py）
以下是基于代码实现的 123pan 网盘 API，按类结构分类说明：

2.1 核心类：Pan123Core
负责与 123pan 服务器的通信，管理认证状态、目录浏览、文件操作等核心逻辑。

2.1.1 属性说明
属性名	类型	描述
user_name	str	登录账号（手机号/用户名）
password	str	登录密码
authorization	str	认证 Token（登录后自动填充）
protocol	str	请求协议（"android" 或 "web"）
cwd_id	int	当前工作目录 ID（0 表示根目录）
file_list	List[dict]	当前目录文件列表
nick_name	str	当前用户昵称
uid	int	当前用户 UID
2.1.2 方法清单
2.1.2.1 （1）登录操作
方法名	参数说明	返回值类型	功能描述
login()	无	Result	使用 user_name/password 登录
logout()	无	Result	登出并清除 Token
check_login()	无	Result	检查当前 Token 是否有效
clear_account()	无	Result	清除账号信息（不保存配置）
2.1.2.2 （2）配置管理
方法名	参数说明	返回值类型	功能描述
load_config(cfg)	cfg: 包含账号信息的字典（见下方配置参数）	Result	加载配置并更新实例状态
get_current_config()	无	dict	获取当前配置（账号、Token、协议等）
set_protocol(protocol)	protocol: "android" 或 "web"	Result	切换请求协议
2.1.2.3 （3）目录操作
方法名	参数说明	返回值类型	功能描述
list_dir(parent_id=None, page=1, limit=100)	parent_id: 父目录 ID
page: 页码
limit: 单页数量	Result	获取单页文件列表
list_dir_all(parent_id=None, limit=100)	同上	Result	获取全部文件（自动翻页）
mkdir(name)	name: 目录名	Result	在当前目录创建子目录
cd(folder_index)	folder_index: file_list 中的目标文件夹下标	Result	进入目标文件夹
cd_up()	无	Result	返回上级目录
cd_root()	无	Result	返回根目录
trash(file_data, delete=True)	file_data: 文件信息字典
delete: 是否删除（True=删除，False=恢复）	Result	删除或恢复文件
list_recycle()	无	Result	获取回收站文件列表
2.1.2.4 （4）文件操作
方法名	参数说明	返回值类型	功能描述
upload_file(file_path, duplicate=0, on_progress=None)	file_path: 本地文件路径
duplicate: 冲突策略（0=报错，1=覆盖，2=保留）
on_progress: 进度回调	Result	上传文件（支持秒传和分块上传）
get_download_url(index)	index: file_list 中的目标文件下标	Result	获取文件直链（自动处理重定向）
share(file_ids, share_pwd="", expiration="2099-12-12T08:00:00+08:00")	file_ids: 文件 ID 列表
share_pwd: 提取码
expiration: 过期时间	Result	创建分享链接
2.1.2.5 （5）用户信息
方法名	参数说明	返回值类型	功能描述
get_user_info()	无	Result	获取当前用户信息（UID、昵称、空间用量等）
2.2 工具类：Pan123Tool
基于 Pan123Core 提供文件交互功能（依赖文件系统操作）。

2.2.1 属性说明
属性名	类型	描述
core	Pan123Core	关联的核心实例
config_file	str	配置文件路径（默认 "123pan_config.json"）
2.2.2 方法清单
2.2.2.1 （1）配置管理
方法名	参数说明	返回值类型	功能描述
load_config_from_file()	无	Result	从文件加载配置
save_config_to_file()	无	Result	将当前配置保存到文件
2.2.2.2 （2）文件下载
方法名	参数说明	返回值类型	功能描述
download_file(index, save_dir="download", on_progress=None, overwrite=False, skip_existing=False)	index: 文件列表下标
save_dir: 保存路径
on_progress: 进度回调
overwrite: 是否覆盖
skip_existing: 是否跳过已存在文件	Result	下载单个文件
download_directory(directory, save_dir="download", on_progress=None, overwrite=False, skip_existing=False)	directory: 目录信息字典
其他参数同上	Result	递归下载目录
2.2.2.3 （3）文件上传
方法名	参数说明	返回值类型	功能描述
upload_file(file_path, duplicate=0, on_progress=None)	同 Pan123Core.upload_file	Result	上传文件（与 Core 方法一致）
2.3 全局配置参数
2.3.1 协议相关
参数名	默认值	描述
API_BASE_URL	"https://www.123pan.com"	API 根地址
TIMEOUT_DEFAULT	15	默认请求超时时间（秒）
UPLOAD_CHUNK_SIZE	5*1024*1024	分块上传单块大小（5MB）
DOWNLOAD_CHUNK_SIZE	8192	下载流式读取单块大小（8KB）
2.3.2 设备伪装
参数名	默认值	描述
DEVICE_TYPES	见代码	可选 Android 设备型号列表
OS_VERSIONS	见代码	可选 Android 系统版本列表
2.4 错误码说明
错误码	含义	可能触发场景
0	操作成功	所有接口成功时返回
-1	网络请求失败	连接超时、SSL 错误等
5060	文件名冲突	上传时 duplicate=0 且目标文件已存在
1	本地文件冲突	下载时目标文件已存在
2.5 典型使用示例
import json

from pan123_core import Pan123Core, Pan123Tool, Pan123EventType, format_size

# 初始化核心对象（Android 协议）  
core = Pan123Core(
    user_name="13800138000",
    password="your_password",
    protocol=Pan123Core.PROTOCOL_ANDROID
)

# 登录  
result = core.login()
if result["code"] != 0:
    raise Exception("登录失败")

# 创建工具类实例  
tool = Pan123Tool(core)


# 下载文件  
def _download_progress(data) -> None:
    if data.get("type") == Pan123EventType.DOWNLOAD_PROGRESS:
        downloaded = data.get("downloaded", 0)
        total = data.get("total", 0)
        speed = data.get("speed", 0)
        if total > 0:
            pct = downloaded / total * 100
            print(
                f"\r进度: {pct:.1f}% | {format_size(downloaded)}/{format_size(total)} | {format_size(int(speed))}/s",
                end="     ",
                flush=True,
            )
    elif data.get("type") == Pan123EventType.DOWNLOAD_START_FILE:
        print(f"开始下载: {data.get('file_name', '未知文件')} ({format_size(data.get('file_size', 0))})")
    elif data.get("type") == Pan123EventType.DOWNLOAD_START_DIRECTORY:
        print(f"开始下载目录: {data.get('dir_name', '未知目录')}")
    else:
        print(json.dumps(data, indent=2))


result = tool.download_file(
    index=0,
    save_dir="downloads",
    on_progress=lambda e: print(f"下载进度: {e['percent']:.2f}%")
)

# 上传文件  
result = core.upload_file(
    file_path="local_file.txt",
    duplicate=1,  # 覆盖已有文件  
    on_progress=None  # ...  
)

# 创建分享链接  
result = core.share(
    file_ids=[12345],
    share_pwd="123456",
    expiration="2026-12-31T23:59:59+08:00"
)  
3、下载说明
下载到脚本所在目录的 download 文件夹，下载过程中使用临时后缀 .123pan，下载完成后会重命名为原文件名。
如果文件已存在，会提示覆盖 / 跳过 / 全部覆盖 / 全部跳过等选项。
4、注意事项
本工具用于学习与自用场景，请勿用于违法用途。对任何滥用造成的后果，本人概不负责。
模拟客户端协议可能存在账号或服务端策略风险，请谨慎使用。
建议不要在公用或不受信任的机器上保存明文密码或授权信息。
5、免责声明
本工具用于学习场景，请勿用于违法用途。对任何滥用造成的后果，作者概不负责。 任何未经允许的api调用都是不被官方允许的，对于因此产生的账号风险、数据损失等后果自负。