StreamPath

StreamPath 是面向 Windows 的便携 WebDAV 媒体浏览器。它负责浏览目录、解析 STRM、匹配外挂字幕、启动 MPV 等外部播放器，并将播放进度、缓存策略和会话状态 保存在程序目录下的 stream_path_data/。

当前版本按功能能力支持 OpenList/AList：已核验的 OpenList v4.0.0、v4.1.4、v4.2.5 支持增强索引与存储恢复；AList v3.0.1、v3.6.0、v3.7.1、v3.63.0 按端点矩阵分级， 未知版本不会被乐观宣称为完整兼容。MPV 已实测 0.34.0 与多个 0.41+ 构建。详细架构、 协议与维护约束见 PROJECT.md。

主要功能

• 使用 WebDAV PROPFIND 浏览目录，支持中文长路径、自然排序和目录缓存。
• WebDAV 密码可以为空；每次登录都强制访问服务器验证当前输入，不使用旧账号缓存冒充 登录结果，失败时保留登录页并显示原因。
• 支持保存多个服务器档案；每个档案包含名称、WebDAV 地址、账号、默认目录和独立的 OpenList/AList 恢复配置，登录页可以直接选择并切换。
• 每个档案使用不会随地址或账号编辑而变化的 profileId，目录缓存、访问型索引、收藏、 最近记录和视频/音频播放进度均按档案隔离。
• 播放视频、音频和同源 STRM；视频自动切集，音频自动生成带曲名的 M3U8。
• 音频支持 MP3、FLAC、WAV、M4A/M4B、AAC、OGG/Opus、WMA、APE、 ALAC、AIFF、MKA、AC3/EAC3、DTS、DSF/DFF、WV、TAK、TTA、AAX 等 常见格式，实际解码能力由当前 MPV 构建决定。
• 音频自动注入同目录同名 LRC；封面优先使用音频内嵌图片，外挂封面按 同名图片优先，其次匹配 cover、folder、front、album 等标准名称。
• 按同目录、同文件名规则匹配字幕；“自动注入”和“自动选择”可分别关闭。
• 使用 SQLite、MPV watch_later 和逐媒体 JSONL 日志同步续播进度。
• 最多同时管理两个独立播放会话；状态文件、命令文件、IPC 和临时脚本互不共用。
• 音频另有独立下边栏、历史、SQLite、watch_later、状态/命令/进度文件和 MPV 进程服务；音频模块故障不会占用或修改视频会话资源。
• 根据媒体大小、时长、内存、网络和历史样本生成 MPV 缓存参数，并在播放中安全降级。
• 音频播放完全绕过上述缓存控制与动态优化，并移除播放器模板中的 MPV 缓存覆盖参数， 只使用 MPV 自身默认缓存机制。
• 可选的 OpenList/AList 自动恢复：仅在 MPV 明确报告 end-file reason=error 时尝试 重新登录、刷新存储并重新拉起播放；默认关闭。
• 浏览页以名称、大小和修改时间展示目录内容，文件夹的大小单元格显示短杠；窄窗口会把普通 文件的大小与时间收进条目副标题。页面支持时间、体积、名称排序和鼠标滚轮，显示排序 不改变稳定播放列表顺序。
• 浏览页支持当前目录搜索，可收藏目录、视频、STRM 和音频；搜索、隐藏后缀和临时排序 只改变屏幕上的条目，不改变播放列表、字幕、LRC 或封面候选。
• 右上角“媒体中心”按视频和音频分栏展示收藏、继续播放、最近播放、收藏目录与最近目录。 顶部全局搜索只查询当前账号已经访问并仍保留在目录缓存中的内容，不会联网递归扫描服务器； 未访问过的目录或已清理、已过期的目录快照不会出现在结果中。
• 设置页按服务器、播放、媒体中心、缓存、诊断、界面和基础设置分页；再次进入时会在本次软件运行期间保留上次 打开的分页；鼠标位于表单或空白区域时均可使用滚轮滚动当前分页。
• 界面页可在默认样式与 Windows 系统材质之间切换，可选择自动、Acrylic 或 Mica 并调整 界面背景密度。Acrylic 是带背景模糊和透视的半透明磨砂材质；Mica 是从桌面背景取色的 低透视材质，不属于同一种磨砂玻璃效果。自动模式在 Windows 11 优先 Mica、Windows 10 使用 Acrylic；显式 Mica 不可用时回退 Acrylic。系统材质整体不可用时软件会继续使用 不透明界面。系统材质模式 内部按背景、结构栏、 内容、浮起表面和临时弹窗分级，文件列表不逐项叠加模糊以保持大目录滚动性能。界面页还会 显示 Windows 版本、透明效果、高对比度与窗口实际材质；系统限制只影响当前显示，不会清除 已保存的材质选择。确认弹窗会按实际生效材质分别使用 Acrylic 或 Mica 外观，背景暗化、 模糊和弹窗本体使用连续入场曲线，避免完整模糊在首帧突然出现。
• 使用自绘标题栏替换 Windows 系统标题栏：显示应用标识并提供最小化、最大化/还原与 关闭按钮，拖动与双击最大化行为与系统一致；标题栏与页面顶部信息栏共用同一背景色， 默认样式与磨砂玻璃样式下均自然衔接。
• 缓存页可分别配置目录刷新、目录快照、页面滚动位置、续播记录和媒体元数据的过期时间； 长时间未访问的数据自动淘汰，缓存学习数据始终只允许主动清理。
• 缓存页可在确认后清理目录缓存、播放进度、继续播放记录和 MPV 临时文件；缓存学习 数据由独立按钮清理。两种操作都保留全部配置和媒体中心个人资产，播放器运行期间不会执行。
• 基础设置可单独启用或关闭隐藏后缀过滤；关闭后仍保留后缀列表，输入格式统一为 .ass, .mkv，并强制使用英文逗号分隔。
• 基础设置可选择简体中文、繁体中文、日文或英文；保存全部配置后立即切换，并在下次启动时 从 stream_path_config.json 的 language 字段恢复。也可在应用关闭时直接把该字段设置为 zh-CN、zh-TW、ja 或 en。
• 基础设置底部提供低误触的“重置全部设置”入口，确认后恢复服务器、播放、缓存策略、界面 和基础设置的默认值；目录缓存、续播记录、学习数据及当前连接和播放会话均保持不变。

运行要求

• Windows 10 或 Windows 11 x64。
• 一个可访问的 WebDAV 地址和用户名（推荐为Openlist）；服务器未设置密码时密码框留空。
• MPV 或其他接受 URL 参数的外部播放器。推荐使用已实测的 MPV 版本。
• 额外注意事项：播放 Strm 文件时建议在 Openlist 的 Strm 存储设置中开启 启用签名 选项。建议在 MPV 配置文件中完全注释或删除 IPC 的配置代码，保证软件的 IPC 功能能够正常运行（如 input-ipc-server= 字样）。

快速使用

1. 启动 streampath.exe。
2. 选择已有服务器档案，或填写档案名称、WebDAV 地址和用户名新建档案；密码按服务器实际配置填写或留空。
3. 连接成功后进入目录，单击视频、音频或有效 STRM 播放。
4. 首次使用前在设置页确认播放器可执行文件路径和参数模板。
5. 使用浏览页右上角搜索当前目录，或打开“媒体中心”查看收藏、继续播放与长期历史。
6. 右上角退出仅断开当前连接并返回登录页，已保存配置不会被清空。

服务器档案与凭据

“设置 → 服务器”可以新建、编辑和删除服务器档案，并为每个档案设置登录后的默认目录。 正在连接的档案必须先退出登录才能删除；删除档案只移除档案与凭据，不会删除该档案现有的 缓存、收藏、索引和播放进度。登录页或设置页切换到其他档案时都会发起真实 WebDAV 根目录 认证请求；只有验证成功才保存为当前活动档案并同步登录页，失败时恢复原活动档案且不保存 候选修改。登录页选择已有档案时，设置页也会在本次软件运行期间同步显示该档案，但不会因此 提前改变已保存的活动档案。

密码与 OpenList/AList Token 默认保存在当前 Windows 用户的凭据管理器中， stream_path_config.json 只保存非敏感档案字段。需要完整复制便携数据时，可以明确选择 “便携明文”；此模式会把密码和 Token 直接写入配置 JSON，必须自行保护数据目录。旧单账号 配置首次升级时会生成“默认服务器”，沿用原有匿名来源 ID，使收藏、访问索引和进度继续可见。

配置格式使用 schemaVersion。每次跨版本迁移前都会在配置目录生成 stream_path_config.json.migration-v<旧版本>-<时间>.bak，并把结果追加到 stream_path_config.json.migrations.jsonl。迁移备份用于关闭应用后的人工回退；旧配置或 便携明文配置的迁移备份可能含明文凭据，应与配置目录采用相同的访问保护。 当前版本为 schemaVersion = 4；版本 3 升级时会补入默认语言 zh-CN。

诊断中心

“设置 → 诊断”可以分别检查 WebDAV、播放器路径、MPV IPC、OpenList/AList 公开 API、 数据目录写入、视频/音频 SQLite、Hive 目录缓存以及配置迁移状态。检查结果彼此独立，某一项 失败不会掩盖其他检查。

“导出脱敏诊断包”会在 stream_path_data/diagnostics/ 生成一个 JSON 文件。服务器 URL 只保留来源和路径 SHA-256 摘要；档案 ID、默认目录同样只导出摘要，不导出档案名称、用户名、 密码、Token、URL userinfo、查询或签名参数。发送文件前仍建议按普通隐私文件自行复核。

“非破坏性维护数据库”仅在播放器全部关闭时可用。它先运行 PRAGMA quick_check，通过后为 视频和音频数据库分别生成一致性备份，再执行 REINDEX 与 ANALYZE；不会删除播放进度。 若完整性检查已经报告损坏，软件会停止自动维护，避免扩大损失。

默认 MPV 参数模板可使用以下占位符：

• {url}：媒体 URL。
• {subfile}：单集字幕 URL；多集字幕由 Lua 按播放列表位置注入。
• {start}：单集续播秒数；多集续播使用 watch_later。

搜索与媒体中心

当前目录搜索按文件名执行不区分大小写的包含匹配，中文可直接输入；“返回上级”始终保留。 关闭搜索后会恢复原目录的列表和滚动位置，进入其他目录时会自动退出搜索。搜索输入框与 登录、设置页使用同一套 Windows 剪贴板历史兼容处理，可使用 Win+V 或右键剪贴板历史。

搜索框右侧的范围菜单可切换到“OpenList 全部索引”。默认仍为“当前目录”；索引搜索要求至少 输入 2 个字符，只查询 OpenList/AList 已建立的本地索引，不会边输入边递归访问网盘。点击 索引结果时，StreamPath 会进入真实 WebDAV 目录重新核对文件；已删除或移动的旧条目会提示 更新索引，而不会直接播放失效路径。

OpenList 索引结果不提供文件修改时间，因此文件名下方继续显示完整父路径，宽窗口右侧的 “所在文件夹”列只显示直接父文件夹名称；软件不会为了补齐时间对每个结果额外请求挂载源。 普通当前目录列表仍显示 WebDAV 返回的真实修改时间。

“设置 → 服务器 → OpenList/AList 索引”可以手动立即更新，或开启定时更新。定时更新默认 关闭，开启后最短间隔为 5 分钟、最长为 7 天，并且先等待一个完整间隔再执行。若 OpenList/ AList 已在更新索引，本次请求会跳过；手动和定时请求不会重叠。搜索使用普通 WebDAV 用户 权限，更新才使用管理员 Token 或管理员账号密码。索引更新可能访问挂载源，请根据网盘风控 选择足够长的间隔；即使手改配置，低于 5 分钟也会按 5 分钟执行。 使用前需先在 OpenList/AList 中启用数据库索引和增量自动更新能力；StreamPath 不会替用户 清空、重建或切换服务端索引类型。

索引卡下方显示当前状态、已处理条目数、上次更新时间和服务端错误。运行中使用动态进度条， 因为 OpenList 不返回可计算百分比的总条目数。页面仅在索引运行且服务器设置页可见时每 2 秒 刷新状态；任务完成、离开分页或关闭设置后停止，也可以使用右侧按钮手动刷新。

目录、视频、STRM 和音频条目右侧可以切换收藏。成功进入非根目录后会更新最近目录；外部 播放器成功启动后才会写入最近播放，启动失败不会产生记录。播放列表实际切集或切歌时， 同一批播放列表会原位更新原有的一条记录，不会为每一集新增位置；关闭播放器后重新启动会 创建新的播放记录，即使目录和文件相同也不会覆盖旧批次。删除媒体中心的最近播放只删除界面历史，不删除 SQLite、 MPV watch_later 或续播点。

媒体中心保持打开时会监听个人资产和播放进度的成功写入，无需退出页面即可更新最近播放、 继续播放及已播放时间。运行中的视频和音频在首次有效状态、暂停或恢复、自动切集或切歌时 立即更新，连续播放期间最多每 10 秒更新一次；播放器结束后仍以现有 JSONL 与 watch_later 退出同步结果为最终进度。

媒体中心顶部全局搜索匹配名称和完整目录路径，最多显示 200 项。它只使用当前来源的 Hive 目录快照，因此首次使用时需要先正常浏览相关目录；普通缓存清理会清除这些搜索快照，但 stream_path_data/library/media_library.json 中的收藏、最近目录和长期播放历史会保留。 “重置全部设置”同样不会删除这些个人资产。远端条目暂时不可用时只会提示，不会自动移除 收藏或历史。若媒体库 JSON 已损坏，首次修改前会先生成逐字节一致的唯一 .corrupt-*.bak 备份；无法读取或版本高于当前程序时会拒绝覆盖，避免把原数据静默改写为空库。

“设置 → 媒体中心”可以调整收藏、继续播放、最近播放和最近目录的数量限制。配置与界面同步 写入 stream_path_data/config/stream_path_config.json 的 mediaLibrary 节点；即使手动填写 超大数值，软件也会收敛到系统硬上限。收藏和最近目录按当前来源计算，继续播放和最近播放按 视频、音频分栏分别计算；降低保存上限后会立即淘汰最旧记录。

同一页面提供收藏、继续播放、最近播放和最近目录的一键清理。清空继续播放只隐藏媒体中心中 现有的续播入口，不删除 SQLite、MPV watch_later、正式或临时续播点，也不清除最近播放； 清空最近播放会同时移除由这些历史派生的媒体中心继续播放入口，但同样保留底层进度。所有操作 只作用于当前连接或当前已保存的服务器来源，并在执行前要求确认。

音频播放

单击音频后，StreamPath 使用当前目录的稳定自然顺序创建 UTF-8 M3U8，点击项作为 播放起点，每个条目使用服务器文件名作为自定义曲名。临时排序、隐藏后缀和搜索结果 不会改变播放列表顺序。

音频伴随文件规则：

• 歌词只接受音频同目录、主文件名完全相同且扩展名为 .lrc 的文件，大小写不敏感； LRC 服从现有“自动注入”和“自动选择”开关，关闭自动选择时仅加入轨道并保留原选择； 远程 LRC 会按原始字节保存为本次 MPV 会话资源，以兼容不支持 Range 的 WebDAV 响应；整批准备最多等待 10 秒，读取失败或超时只跳过相应歌词，不会阻断音频播放；
• 内嵌封面由 MPV 原生识别，并保持最高优先级；
• 外挂封面先匹配同目录同名图片，再匹配 cover、folder、front、album、 albumart、thumb 等标准名称；
• LRC 和外挂封面按当前 M3U8 的 playlist-pos 逐曲目注入，切歌时不会串到其他曲目。

音频下边栏支持显示当前曲名、暂停、继续、关闭与应用重启后的“继续播放”；现有“自动 续播”开关同时控制视频与音频。播放位置 通过音频专用 SQLite、MPV 音频 watch_later 和逐曲目 JSONL 合并：自然播放完会清除旧 进度，明确回到 0 秒会覆盖旧正数进度，普通退出使用 MPV 的精确最终位置。

音频模块不调用缓存策略、媒体探测、动态监控或 OpenList 恢复。启动时还会过滤模板中 的 cache、cache-secs、demuxer-max-bytes、demuxer-seekable-cache、 stream-buffer-size 等参数，确保音频只采用 MPV 默认缓存。音频的 LRC、封面、M3U8 和下边栏功能要求播放器配置为 MPV。LRC 会话文件只保存歌词、不保存音频数据，播放 会话结束后删除，不属于可复用缓存；音频媒体流和封面仍由 MPV 直接读取。

MPV 兼容性

2026-08-23 使用 C:\Users\YX\Documents\StreamPathProject\cross_version_testing\打包版本 中的四个 打包版本，以及 D:\MPV_Player\mpv_config-2026.04.14\mpv.exe 完成自动化实测。 每个版本都实际加载媒体并验证 Lua、暂停/恢复命令、命名管道、十三行状态文件、 逐媒体进度日志、TS、字幕、watch_later、file_error、动态缓存属性，以及不支持 Range 的远程 LRC 与远程外挂封面同时存在时的两首音频列表自然推进。

测试程序	mpv --version	结果
mpv-0.34.0-x86_64	mpv 0.34.0	通过
mpv-v0.41.0-x86_64-pc-windows-msvc	v0.41.0-dev-g41f6a6450	通过
mpv-lazy-20260510-noVS	v0.41.0-615-g7b057f66f	通过
mpv-x86_64-20260610-git-304426c	v0.41.0-744-g304426c39	通过
mpv-v0.41.0-460-g2f6561947(MPV Config 版本)	v0.41.0-460-g2f6561947	通过

普通测试默认跳过实体 MPV 测试。需要复测时执行：

$env:STREAMPATH_MPV_TEST_ROOT = 'C:\Users\YX\Documents\StreamPathProject\cross_version_testing\打包版本'
$env:STREAMPATH_PATH_MPV = 'D:\MPV_Player\mpv_config-2026.04.14\mpv.exe'
flutter test --no-pub test/mpv_version_compatibility_test.dart -r expanded

测试会自动把系统 PATH 中的 mpv.exe 作为第五个版本；也可以通过 STREAMPATH_PATH_MPV 指定该版本的完整路径。

OpenList/AList 能力矩阵

基础 WebDAV 连接与增强 API 分开判断。设置页会显示后台版本及“可用、不可用、尚不可证明” 状态；缺少端点时只关闭对应功能，不会把增量更新降级为破坏性的全量构建。

后端版本	搜索	索引进度	增量更新	存储恢复
AList v3.0.1	不可用	不可用	不可用	不可用
AList v3.6.0	可用	可用	不可用	不可用
AList v3.7.1	可用	可用	可用	可用
AList v3.63.0	可用	可用	可用	可用
OpenList v4.0.0、v4.1.4、v4.2.5	可用	可用	可用	可用
未知版本	按实际端点响应	按实际端点响应	按实际端点响应	按实际端点响应

OpenList/AList 自动恢复

设置页可填写后台地址和管理员 Token，或填写管理员账号、密码。推荐使用 Token；启用 2FA 的账号必须使用 Token。管理员 Authorization 值直接使用 Token，不添加 Bearer。管理请求同时要求 HTTP 2xx 和 JSON code=200；每个逻辑请求共享总截止时间， 每次连接、发送、接收和同源重定向只能使用剩余预算；能力探测 transport timeout 时会 立即失败关闭，不会用微小剩余预算继续请求其他管理端点。

恢复流程只在以下条件全部满足时运行：

1. 功能已启用且配置完整；
2. MPV 明确报告当前媒体读取错误；
3. 原媒体地址的 Range 探测仍不可用。

系统优先调用 /api/auth/login，仅当端点不存在时回退 /api/auth/login/hash，随后调用 /api/admin/storage/load_all 并等待存储列表和 媒体地址恢复。失败只显示提示，不会中断播放器退出监听或反复无限重试。 如果 MPV 第二次报告读取错误，但 Range 探测确认媒体仍可读取，系统会将其判定为 非链接失效并停止本次自动恢复，不会进入第三次本机重启。只有前两次都返回可重试失败时， 第三次才仅支持本机、身份已确认且以 server --force-bin-dir 标准方式运行的 openlist.exe / alist.exe：软件发送 Ctrl+C 让服务自行保存并退出，确认旧 PID 消失后再重新启动，不会使用 taskkill /F。远程后台、 反向代理、Docker、Windows 服务、包含无关进程的共享控制台或非标准启动方式会安全拒绝自动重启。

播放会话会保存启动时的播放器、服务器、恢复配置、档案和凭据快照；播放期间切换档案不会 改变该会话后续恢复的目标。关闭 MPV 前还会同时核对 PID、可执行文件绝对路径、创建时间和 named pipe 所属进程；任一证据缺失或不一致时保留会话并拒绝终止。

视频起播后的前 5 秒不记录瞬时缓冲；之后 MPV 每次进入 paused-for-cache 都会写入独立 临时播放点。连续健康播放 5 秒、自然完成或到达 99% 后自动清除。临时播放点和普通续播 进度位于 SQLite 的不同表，普通退出或异常写入 0 秒不会覆盖临时点；下次打开同一视频时 临时点优先。

数据目录

便携版数据位于程序同级 stream_path_data/：

stream_path_data/
├─ config/
│  ├─ stream_path_config.json
│  ├─ stream_path_config.json.bak
│  ├─ stream_path_config.json.migrations.jsonl
│  ├─ stream_path_config.json.migration-v*-*.bak
│  ├─ stream_path_config.json.migration-legacy-files-*.bak/
│  ├─ cache_policy.json
│  ├─ cache_intelligence.json
│  └─ cache_expiration.json
├─ diagnostics/
│  └─ streampath-diagnostics-*.json
└─ cache/
   ├─ directory_cache/
   ├─ streampath.db
   ├─ playback_history.json
   ├─ audio_streampath.db
   ├─ audio_playback_history.json
   ├─ media_metadata.json
   ├─ cache_intelligence_learning.json
   ├─ mpv-watch-later/
   ├─ mpv-audio-watch-later/
   └─ 视频与音频 MPV 会话状态、命令、进度、脚本及 M3U/M3U8 播放列表

旧版平铺数据会在启动时迁移到上述目录。目标已存在时不会覆盖；迁移失败时原文件 保留，应用继续启动。统一配置采用临时文件原子替换，并保留最近一次有效备份；跨版本 迁移还会先生成独立备份并记录结果。启动时主配置损坏会回退最近有效备份，备份也不可用时 使用默认值并保留损坏文件。视频与音频 SQLite 使用 (profile_id, url) 复合主键，旧进度 升级时归入由旧连接信息生成的“默认服务器”档案。

缓存过期配置

“设置 → 缓存 → 缓存过期时间”可以修改以下项目：

• 目录刷新间隔：默认 10 分钟，可设置 1～1440 分钟。超过后先显示旧快照，再后台刷新；
• 目录快照保留时间：默认 30 天，可设置 1～3650 天。按最后访问时间自动清理；
• 滚动位置保留时间：默认 30 分钟，可设置 1～1440 分钟。长时间未打开的目录从顶部显示；
• 续播记录保留时间：默认 365 天，可设置 1～3650 天，同时作用于视频/音频 SQLite、 继续播放记录和 MPV watch_later；
• 媒体元数据保留时间：默认 180 天，可设置 1～3650 天，适用于文件大小、时长、码率、 ETag 和 Last-Modified 等缓存。

这些值保存在 stream_path_data/config/cache_expiration.json。软件启动时加载一次；在 设置页保存或点击右上角“从配置文件重新加载”后，后续缓存访问使用新值。直接修改文件后 也可以重启软件使其生效。非法类型回退默认值，越界数值自动收敛到允许范围，配置损坏不会 阻止浏览或播放。

缓存学习数据 cache/cache_intelligence_learning.json 不读取任何过期时间，不会被 自动清理。只有“清理学习数据”按钮会重置它；普通缓存清理仍会保留该文件。

安全边界

• WebDAV 与 OpenList 管理请求手动处理重定向，只在严格同源时携带凭据。
• MPV 不使用会跨域转发的全局 --http-header-fields=Authorization；仅给 WebDAV 同源 URL 写入 userinfo。实测的五个 MPV 版本在跨来源重定向时会移除该凭据。
• STRM 最大读取 8192 字节，只接受 HTTP/HTTPS 且与 WebDAV 根地址同源的目标。
• OpenList 管理员请求拒绝跨来源重定向；媒体探测跳到签名域名后立即移除 Basic。
• 默认模式把 WebDAV 密码与 OpenList/AList 密码、Token 保存在 Windows 凭据管理器； 明确选择“便携明文”时这些值会写入 JSON。旧配置迁移备份也可能保留旧明文，均需保护。
• 脱敏诊断包不导出密码、Token、用户名、档案名称、URL userinfo、查询或签名参数。

开发、测试与打包

flutter pub get
flutter analyze
flutter test
flutter run -d windows

当前常规测试覆盖视频与音频识别、M3U/M3U8、字幕/LRC/封面、进度、会话隔离、缓存 边界和 WebDAV；需要显式提供 MPV 目录的多版本兼容测试仍按条件跳过。项目内另有一项 使用当前实测 MPV 的音频实体测试，会实际加载 WAV、LRC、外挂封面和完成事件。

Release/AOT 构建并更新指定便携目录：

.\tools\package.ps1

脚本启动后输入打包目录；直接回车使用现有便携版目录。也可以在命令行直接传入目录：

.\tools\package.ps1 -Target 'D:\StreamPath portable'

需要细分构建参数时使用底层脚本：

.\tools\build.ps1 -Mode release `
  -Target 'C:\Users\YX\Documents\StreamPath_Release\StreamPath 20260809 V0.1 portable' `
  -Yes

构建脚本依次执行静态分析、全部常规测试和 Windows Release 构建，并校验 data/app.so 存在且没有 Debug kernel_blob.bin。覆盖目标时只替换程序构建产物， 保留 使用说明.txt 与 stream_path_data/ 用户数据。非空目标必须同时含已有 streampath.exe 和 data/app.so 标记，否则拒绝覆盖。四个脚本都从 tools 的父目录 解析并验证项目根，不依赖调用命令时的当前目录。

仅清理缓存和运行时数据、保留全部配置：

.\tools\cleanup.ps1

保留播放历史时使用 .\tools\cleanup.ps1 -KeepHistory。脚本会验证目标范围并拒绝驱动器 根目录、项目根目录、用户目录和目标路径链中的重解析点；旧版播放器与连接配置也不会 被清理。默认清理项目根的 stream_path_data，并保留缓存学习数据。

也可以在软件的“设置 → 缓存 → 缓存文件清理”中执行。确认后会清除播放进度与继续 播放记录，但保留缓存学习数据和 stream_path_data/config/。需要重置匿名码率、 存储画像和缓存习惯统计时，使用同页独立的“清理学习数据”按钮，该操作不会清除其他 缓存。开发构建和便携版都会按当前可执行文件定位各自的 stream_path_data/cache/； 两种清理操作开始前都需要先关闭仍在运行的播放器。

常见问题

• 空密码无法连接：确认服务器确实允许该用户名使用空密码；StreamPath 会发送 username: 对应的 Basic 凭据，失败会显示服务器或网络错误。
• 登录页标签闪动或重叠：当前实现首帧同步填充控制器并固定标签浮动位置；若仍出现， 请记录系统缩放比例和复现步骤。
• MPV 无法启动：在设置页使用 mpv.exe 的完整路径，先在终端执行该文件的 --version。
• STRM 不显示或不可播放：只接受非空、8192 字节以内且与 WebDAV 同源的目标； 第三方直链会被拒绝。
• OpenList 恢复失败：检查后台根地址、Token 权限和 2FA；后台反向代理必须允许 管理 API 且不能把管理员请求重定向到其他来源。