BoxPlayer v5.0.5 发布解析：AI 工作台与媒体获取落地、多网盘能力边界与生产构建校验-开发者社区

桌面应用
AI 应用
音视频

【免费下载链接】boxplayer

BoxPlayer - 聚合网盘管理+影视聚合支持 Windows Linux iOS macOS tvOS Android

项目地址：https://gitcode.com/gh_mirrors/aliyunpa/boxplayer

本文以 docs/releases/v5.0.5.md 发布文档为主体，结合仓库源码（electron/main/agent、electron/main/mediaAcquisition、src/services/mediaAcquisition、src/services/agent）解读 v5.0.5 的核心变化：AI 工作台与受控媒体获取链路如何落地、各网盘能力边界如何声明与收敛、目录选择与认证稳定性如何修复，以及发布工作流如何完成生产构建校验。读者读完后，将能理解该版本的完整功能面、底层调用链与可复现的验证命令。

版本主题：把资源检索、媒体获取、追更与任务审计收拢到 AI 工作台

v5.0.5 的发布主题是「AI 工作台与媒体获取正式落地，完善多网盘能力、播放下载体验与生产构建校验」。发布摘要明确了该版本最核心的设计转变：

资源检索、媒体获取、追更和任务审计统一收拢到AI 工作台，用户可以从搜索结果直接选择目标网盘和保存目录；
由Agent在明确的能力边界内执行「检索候选 → 导入资源 → 核验落盘 → 整理媒体库」的完整链路；
涉及导入、移动、删除等写入操作均会先生成可确认的计划，避免 Agent 越权执行破坏性动作；
版本同时扩展了多网盘的能力声明与交互边界，增强了夸克、115、123、PikPak、光鸭等网盘的目录、离线、分享和播放链路。

从源码结构看，这一设计在主进程侧由electron/main/agent（Agent 控制与执行）与electron/main/mediaAcquisition（媒体获取服务与 SQLite 持久化）两条主链承载，渲染进程侧由src/services/mediaAcquisition提供候选、导入、整理、追更等纯策略模块，src/services/agent/providerCapabilities.ts统一汇聚各网盘的能力声明。

重点新增功能拆解

AI 工作台：对话、计划确认与受控文件操作

v5.0.5 新增统一的 AI 工作台界面，聚合了对话、计划确认、工具活动、执行上下文与异步通知。主进程侧对应的实现包括：

AgentControlService.ts：Agent 控制服务，负责会话与工具活动的调度；
AgentCliExecutor.ts 与 AgentCliExecutionScheduler.ts：CLI 执行的调度与执行器；
AgentCliPreflight.ts：执行前的预检，与服务端能力边界配合限制可执行操作；
CloudDriveCliGateway.ts 与 CloudDriveCliAdapter.ts：将网盘操作适配为 CLI 网关调用；
AgentLedgerDb.ts：任务台账的 SQLite 持久化；
AgentV1FeatureFlags.ts：特性开关，控制 Agent 各阶段能力是否启用。

「写入操作需先确认计划」这一约束在src/services/agent侧同样有支撑：boxplayerCapabilities.ts、agentToolCapabilities.ts定义 Agent 可用工具边界，providerCapabilities.ts按网盘声明操作能力（详见后文「网盘能力边界」小节），未声明能力的网盘只会执行明确可用的只读操作。

Agent 媒体获取（Pro）：从搜索结果到目标网盘落盘

媒体搜索结果可直接创建获取任务，流程为：选择目标网盘及保存目录 → 按标题、年份、季集、画质、字幕和目标网盘能力筛选候选 → 执行导入。

在src/services/mediaAcquisition中，该链路被拆解为职责清晰的模块：

模块	职责
workflowRunner.ts	获取任务的整体流程编排
candidatePolicy.ts	候选资源的筛选策略（标题、年份、季集、画质、字幕匹配）
searchGuard.ts、searchEvidence.ts	搜索护栏与证据收集，避免无关结果进入候选
shareExecutor.ts、magnetExecutor.ts、externalUrlExecutor.ts	分别执行分享导入、磁力离线、HTTP/HTTPS 离线三种导入方式
staging.ts、organizer.ts、organizerPolicy.ts	落盘暂存、媒体库整理与整理策略
snapshotDiff.ts、targetSnapshot.ts	目标目录快照与差异比对，用于核验落盘结果
duplicatePolicy.ts、duplicateCleanup.ts	重复资源策略与清理
subtitleExecutor.ts、subtitleNaming.ts	字幕获取与命名规范化
notificationReporter.ts	任务结果的通知上报
historicalLibraryScanner.ts、historicalPolicy.ts	历史媒体库扫描与补全策略（默认关闭，需显式开启）

主进程侧 MediaAcquisitionService.ts 提供对应的服务入口，例如createMediaAcquisitionRun、beginMediaAcquisitionSearch、finishMediaAcquisitionSearchWithoutCandidates、addMediaAcquisitionCandidate（候选必须包含title、locator，且kind仅允许share/magnet/http三种）、retryMediaAcquisitionSearch（搜索失败自动重试，默认最大 3 次）以及cancelMediaAcquisitionRun/forceCancelMediaAcquisitionRun两种取消路径。运行状态通过MediaAcquisitionV1Bridge.ts镜像到前端视图，保证界面与服务端状态一致。

任务核验与追更：缺集巡检、季订阅与历史补全

获取任务会完整记录候选、导入、落盘核验、整理和失败原因，形成可审计的任务链。追更体系则面向电视剧、动画提供：

缺集巡检：比对已获取集数与最新播出集数，计算缺集清单；
季订阅：按季维度订阅更新，新增季自动纳入巡检；
追更任务：按调度周期自动生成待执行任务。

持久化实现位于 MediaAcquisitionDb.ts，数据库文件为media-acquisition.db（存放在 ElectronuserData目录），其中的追更记录包含nextCheckAt（下次巡检时间）。服务层的upsertMediaAcquisitionTracking负责合并目标、季号、总集数、最新播出集数、已获取集数、缺集与状态。

两个默认行为需要特别注意：

追更巡检默认时间为北京时间06:00与21:00，由 MediaAcquisitionWakeScheduler.ts 负责调度；
历史媒体自动补全默认关闭，需要在设置中显式开启后，历史媒体库才会进入补全流程。

文档能力：文档解析服务与文档 AI 入口

v5.0.5 新增文档解析服务与文档 AI 入口，阅读器与书库同步补充了对应的元数据、回收站及检索行为。渲染进程侧的支撑包括 DocumentAIModal.vue 组件与src/services/documents目录下的解析服务，读者可通过阅读器与书库的检索入口调用文档级 AI 能力。

多网盘与传输改进

夸克网盘：Cookie 归一化与显式认证

夸克网盘是本版本重点修复的对象：

Cookie 归一化与登录态校验：统一夸克 Cookie 的解析格式并校验登录态；
目录列表请求改到主进程：目录列表在 Electron 主进程通过显式 Cookie发起请求，避免渲染进程跨域请求丢失认证信息（此前已登录用户可能收到require login [guest]错误）；
分享、下载、视频预览和目录错误信息同步补强。

对应的src/quark/下auth.ts、dirfilelist.ts实现均有配套测试（见文末「验证」一节的测试命令），保证 Cookie 处理与目录列举逻辑可回归验证。

第三方网盘按单根目录模型浏览，目录懒加载和选择状态更稳定；
阿里云盘目标目录固定使用资源盘根目录。

这一约束在 capabilities.ts 的normalizeMediaAcquisitionRootFolder中有明确实现：115、PikPak、夸克、光鸭、123 网盘分别归一化为drive115_root、pikpak_root、quark_root、guangya_root、cloud_root，未传目录或传入 root 类占位值时都会落到对应网盘的根目录，从而避免选择状态漂移。

网盘能力边界：面向 Agent 与离线任务的操作声明

v5.0.5 为阿里、115、123、百度、夸克、PikPak、139、189、Dropbox、OneDrive、Box、光鸭等网盘建立能力声明，菜单、Agent 和离线任务将据此限制到已支持的操作。

仓库中的统一注册表在 providerCapabilities.ts：

export const PROVIDER_CAPABILITIES: Record<string, ProviderCapabilityManifest> = { aliyun, cloud123, '115': cloud115, cloud139, cloud189, baidu, guangya, pikpak, quark, dropbox, onedrive, box, google, webdav }

各网盘的能力清单由其适配器目录下的capabilities.ts声明（如src/quark/capabilities.ts、src/pikpak/capabilities.ts、src/cloud123/capabilities.ts等），getProviderCapabilities通过normalizeProviderPlatform做平台别名归一化（如drive115 → 115、123 → cloud123、alist → webdav）。未注册能力清单的网盘，Agent 只会执行明确可用的只读操作。

在此基础上，媒体获取判定哪些网盘可用，取决于三类操作能力（见 capabilities.ts）：

share.import：分享导入；
offline.magnet：磁力离线；
offline.http：HTTP 外链离线。

只要具备三者之一即视为支持媒体获取（supportsMediaAcquisition），并在界面中格式化为「分享导入、磁力离线、HTTP 外链离线」的说明文案。这与「升级说明」中「AI 媒体获取依赖目标网盘已开放的分享导入、磁力离线或 HTTP/HTTPS 离线能力」的表述一一对应。

分享与离线任务：115、123、PikPak、光鸭链路完善

分享与离线任务在本版本继续完善：

115、123、PikPak、光鸭的离线/分享处理补强；
新增123 付费分享提示；
改善BT 目标目录、任务状态和 aria2 参数处理。

底层相关实现分布在src/cloud115/offline.ts、src/cloud123/offline.ts、src/pikpak/offline.ts、src/guangya/offline.ts、src/guangya/miaochuan.ts以及 aria2 相关模块（src/utils/aria2Rpc.ts、src/utils/aria2c.ts、src/utils/aria2EnginePolicy.ts），分享导入路径则与媒体获取的shareExecutor.ts相互衔接。

下载与本地播放：任务详情、BT 文件选择与 MPV 启停

下载记录、任务详情、BT 文件选择及本地视频播放策略继续完善；媒体播放链路补齐了MPV 启停与代理请求处理。相关实现参考 TorrentFileSelector.vue、TaskDetailDrawer.vue，播放侧可关注src/utils/mpvPlayerPolicy.ts、src/utils/proxyMediaRewrite.ts、src/utils/proxyhelper.ts以及electron/main/mpv目录，它们共同支撑本地视频播放的启停与代理请求。

构建与运行时变化

发布工作流新增 Linux MPV 校验：在跨平台打包前验证原生播放运行时，相关校验脚本见scripts/check-embedded-mpv-bundles.mjs（check:mpv-bundles），防止打包产物缺失 MPV 运行时；
生产构建启用原生依赖重建，并将better-sqlite3作为运行时依赖（package.jsondependencies中含"better-sqlite3": "^12.11.1"），提升桌面包内 SQLite 运行可靠性；rebuild:electron脚本通过electron-rebuild -f -w better-sqlite3完成原生模块重建；
新增 Agent 运行时依赖与相关测试覆盖，继续使用 SQLite 保存检索、任务和追更状态（AgentLedgerDb.ts与MediaAcquisitionDb.ts均基于 SQLite）。

升级说明与注意事项

升级到 v5.0.5 时需要留意以下三点：

AI 媒体获取的依赖前提：AI 媒体获取依赖目标网盘已开放的分享导入、磁力离线或 HTTP/HTTPS 离线能力；资源可用性、账户状态和网盘限制会影响最终结果。也就是说，即使界面可创建获取任务，目标网盘若不具备上述能力或账号受限，任务仍可能失败。
夸克重新登录：已登录的夸克用户如仍收到require login [guest]，请重新登录夸克以刷新 Cookie；桌面端更新后需完整退出并重启应用，确保主进程与 preload 更新生效（目录列表请求经由主进程显式 Cookie 发起）。
追更默认行为：追更巡检默认时间为北京时间06:00,21:00；历史媒体自动补全需在设置中显式开启，默认关闭。

验证：发布前的回归测试与构建命令

发布前将执行以下命令（来自 docs/releases/v5.0.5.md「验证」一节）：

pnpm run test pnpm exec vitest run electron/main/core/__tests__/mediaAcquisitionDb.test.ts src/utils/__tests__/mediaAcquisitionPolicy.test.ts src/utils/__tests__/mediaAcquisitionSearchEvidence.test.ts src/quark/__tests__/auth.test.ts src/quark/__tests__/dirfilelist.test.ts pnpm run build

测试命令覆盖了本次发布的核心风险面：

mediaAcquisitionDb.test.ts：媒体获取任务/追更的 SQLite 持久化行为；
mediaAcquisitionPolicy.test.ts：候选筛选与获取策略；
mediaAcquisitionSearchEvidence.test.ts：搜索证据与护栏；
quark/auth.test.ts与quark/dirfilelist.test.ts：夸克 Cookie 归一化、登录态校验与目录列表逻辑，对应本次夸克链路修复。

执行pnpm run build（内部依次执行node version.mjs、vue-tsc --noEmit类型检查与vite build）完成生产构建校验，发布工作流还会在跨平台打包前执行 Linux MPV 校验，确保原生播放运行时就绪。

小结

v5.0.5 是 BoxPlayer 在「AI 驱动网盘操作」方向上的关键一版：AI 工作台把检索、媒体获取、追更与审计统一收口，Agent 在网盘能力边界内以「先确认计划、后执行写入」的方式完成导入与整理；夸克认证、目录选择器与多网盘能力声明补齐了稳定性与交互边界；生产构建引入原生依赖重建、better-sqlite3运行时依赖与 Linux MPV 校验，保证桌面端交付质量。若要在本地复现验证，直接执行上文「验证」一节的测试命令即可。

进一步阅读：