littleuqu

小小优趣 Python CLI：短信登录、电影/动画/熏听分类查询、目录展开与下载。

直接交给 AI 使用

复制下面的提示词给支持终端操作的 AI，即可让它自动安装 CLI 并继续完成查询或下载：

请在当前电脑上安装并使用“小小优趣”CLI 完成我的需求。先检查 uv 是否可用；如果没有，按照 uv 官方安装文档完成安装。然后执行 uv tool install littleuqu；如果已经安装，则执行 uv tool upgrade littleuqu。运行 littleuqu version 和 littleuqu --help 验证安装。

安装成功后，根据我的需求使用 littleuqu categories、list、show、download 或 fetch。需要登录时执行 littleuqu login，再向我询问手机号和短信验证码；不要把手机号、验证码或登录凭据写入命令历史、日志或项目文件。下载前确认保存目录并通过 --output 指定。需要合并 HLS 或提取音轨时先检查 ffmpeg，缺失时完成安装。参数不确定时先查看对应命令的 --help，不要猜测。完成后告诉我执行结果、文件保存路径，以及失败或未完成的项目。

安装

uv tool install littleuqu
littleuqu --help

升级到最新版：uv tool upgrade littleuqu。

HLS 合并与音轨提取需要 ffmpeg（macOS：brew install ffmpeg）。 从源码开发：uv sync --group dev，随后 uv run littleuqu --help。

登录

littleuqu login
littleuqu auth status
littleuqu auth logout

login 输入手机号后会发送短信。已有验证码可用 login --mobile PHONE --code CODE， 但交互输入更适合避免 shell 历史保存验证码。会话保存在 platformdirs 用户配置目录，权限 0600。 可用 LITTLEUQU_CONFIG_DIR 指定目录。 客户端优先使用 Python 运行时的系统 CA bundle，兼容安装了本机代理证书的环境；也可用 LITTLEUQU_CA_BUNDLE=/path/to/ca.pem 显式指定，TLS 校验不会被关闭。 登录返回 refreshToken，但刷新接口尚未实现，目前过期后需要重新登录。 儿童档案查询接口尚未实现，可 auth set-child ID --age-days N 设置。

查询

littleuqu categories
littleuqu categories 电影
littleuqu categories 动画 --json
littleuqu list 电影 --filter type=2 --all-pages
littleuqu list 动画 --filter 主题=儿歌 --filter 语言=英文 --all-pages
littleuqu list 熏听 --filter type=3 --json
littleuqu show 动画 44
littleuqu show 电影 116
littleuqu show 熏听 382

类别别名：movie / animation / audio。筛选项来自接口，支持名称和数字值，0 表示全部。 list 默认第 1 页、每页 16 条，--all-pages 遍历全部页。按类别和资源类型/ID 去重。 当前将 page.offset 按页码递增，检测重复页时会报错而非静默截断。

下载

# 查看计划，不请求播放、不创建下载文件
littleuqu download 动画 44 --season 169 --dry-run
# 下载一集视频（不请求 PDF 附件）
littleuqu download 动画 44 --episode 5294 --media video
# 视频、字幕、封面和元数据
littleuqu download 动画 44 --season 169 --media video,files
# 显式从视频提取音轨（保留中间视频）
littleuqu download 动画 44 --episode 5294 --media video,audio --extract-audio
# 按分类批量下载，最多 5 集
littleuqu download 动画 --filter subjectType=1001 --all --limit 5 --media video
# 下载电影视频、字幕、中英文 PDF、封面和元数据
littleuqu download 电影 116
# 下载熏听专辑的一条音轨并提取为 M4A
littleuqu download 熏听 382 --episode 11281 --media audio
# 下载整个熏听专辑；auto 对熏听等同于 audio,files
littleuqu download 熏听 382
# 已有音频、PDF、ZIP、MP4 或 M3U8 直链
littleuqu fetch 'https://example.com/audio.mp3' -o audio.mp3
littleuqu fetch 'https://example.com/playlist.m3u8' -o video.mp4

--output 指定目录；--jobs 控制 HLS 分片并发（默认 4）；--overwrite 强制重下。 --quality 默认对动画/电影使用 SD，对熏听使用 FD；--lang 默认对电影使用 2， 对动画/熏听使用 -1。其他值需服务端支持。

文件按 动画/作品_ID/季_ID/序号_集名_ID 组织。完成标记记录文件长度，重复运行跳过已完成文件。 已完成的音视频直接本地校验，不再逐集请求播放接口；包含 files 时复用原有元数据检查附件， 附件缺失、长度变化或元数据不可用时才重新获取播放信息。目录仍会从服务端读取，以发现新增集数。 音频已完成时无需保留中间视频。使用 --overwrite 可强制重新获取播放信息和下载文件。 直链使用 .part、ETag/Last-Modified 与 Range 续传；无验证器或服务器忽略 Range 时重新下载。 HLS 支持普通点播 TS、主列表选择、AES-128 正确 IV/密钥、分片缓存、签名刷新和 CDN 切换。 目前 byte-range/fMP4、独立音轨主列表和非 AES-128 加密会明确报错。 媒体请求不发送账户 token；API 请求保留 TLS 校验。

下载报告 download-report.json 包含每项 complete/partial/failed 状态。 批量处理中报告按约一秒间隔保存进度，结束时写入最终结果，避免跳过大量已完成课程时逐集重写整份报告。 退出码：0 成功（或 dry-run 成功生成计划）；1 参数/接口/环境错误；2 批量结果存在未完成项。 使用 --media files 时，已知 SRT、封面和元数据可以保存；若服务端显示存在 PDF， 报告会明确标记 partial，避免误认为附件齐全。报告不会保存临时签名播放地址。

当前接口覆盖

熏听当前覆盖 LISTEN_AD、LISTEN_VD 和 LISTEN_FILM。遇到其他 rssType 会明确报错。 download --all 会遍历三类。 fetch 可下载手头已有的音视频/附件直链。

待补充：熏听除 LISTEN_AD/LISTEN_VD/LISTEN_FILM 外的资源类型、动画和熏听的 PDF 地址、 动画整季 ZIP、儿童档案与 token 刷新接口。

验证

uv run pytest
uv run ruff check src tests
uv build

测试使用脱敏合成响应和本地 HTTP 服务，不发送短信、不访问真实内容服务。

本次验证结果

• 34 项测试通过（含 19 项重复下载回归测试）；Ruff 检查通过。
• 真实下载 Baby Shark（动画 44 / 集 5294），MP4 约 41 MB、178.926 秒，包含 H.264 视频与 AAC 音轨。
• 真实下载熏听专辑 382 的音轨 11281，并提取为 AAC/M4A，约 2.4 MB、310.1 秒。
• 真实下载 LISTEN_AD 专辑 65 的歌曲 918，保存原始 320 kbps MP3、LRC 和封面。
• 电影 116 的详情和播放接口实测通过，返回完整 SD M3U8、字幕和中英文 PDF 地址。
• 电影 116 的 SRT、中英文 PDF 和封面已实际下载并校验文件格式。
• 本机代理环境使用系统 CA 完成严格 TLS 校验；未关闭证书验证。
• wheel 与源码包构建通过，打包内容不含下载文件。