Ghost Downloader 3 领域模型与术语规范从任务生命周期到更新分发的架构词典【免费下载链接】Ghost-Downloader-3The only downloader you need. 下载器的集大成者。项目地址: https://gitcode.com/GitHub_Trending/gh/Ghost-Downloader-3导读本文以 Ghost Downloader 3基于 PySide6 的多协议下载器仓库根目录的 CONTEXT.md 为骨架系统梳理该项目从任务建模到应用更新的领域术语与核心架构。Ghost Downloader 3 的桌面端Windows、macOS、Linux与 Android 共享同一套业务引擎浏览器扩展负责捕获资源并发送到桌面应用理解本文的术语体系是阅读源码、参与贡献或二次开发的前提。读完本文你将掌握 Task / Task Run / Task Step / FeaturePack / Browser Service / Update Service 等核心概念的准确定义、命名禁忌与底层实现位置能够精准定位 app/models/task.py、app/services/task_service.py 等关键模块。项目总体架构Ghost Downloader 3 的核心设计理念是跨端共享业务引擎、按 Pack 垂直切片扩展能力共享业务引擎桌面端与 Android 复用同一套任务、解析、下载、更新逻辑仅在平台层app/platform做差异适配如 android.py、windows.py。浏览器扩展桥接扩展捕获页面资源Resource经 browser_service.py 转换为任务创建请求送入桌面应用。FeaturePack 插件体系每个协议HTTP、FTP、m3u8、yt-dlp、BT、ed2k 等都是一个自包含的垂直切片位于 features 目录通过 loader.py 动态加载。下文术语按原文档的分组逐一展开并补充源码级佐证。任务模型Task 领域核心Task任务定义用户可见的下载项。拥有Name成品文件的基本名和Output Folder下载目标目录。路径规则单文件任务最终路径为Output Folder / Name多文件任务最终路径为包含各文件的目录。五个状态WAITING排队等待、RUNNING正在下载、PAUSED用户暂停、COMPLETED已完成、FAILED失败。源码中的定义见 app/models/task.pyclass TaskStatus(IntEnum): WAITING auto() RUNNING auto() PAUSED auto() COMPLETED auto() FAILED auto()持久化Task 序列化为 Task Record应用启动时从上次运行加载的 Task Record 称为 Saved Tasks。TaskStore将任务以 JSON Lines 格式写入APP_DATA_DIR / tasks.jsonl写入时先落.tmp临时文件再原子替换见 app/services/task_service.pyresumeSaved在启动时恢复 Saved Tasks 并重新调度见 app/services/task_service.py。命名禁忌不使用 download、jobName 不叫 title 或 filenameOutput Folder 不叫 directory。Task Files任务文件一个 Task 产生的下载文件和分片临时文件。在Task.deleteFiles()中除了逐 Step 调用step.deleteFiles()删除输出文件还会清理同名.ghd后缀的进度文件分片临时文件见 app/models/task.py。注意与 Selectable File可勾选单元严格区分。Pausable可暂停性Task 的可暂停性是派生属性取决于当前运行 Step 是否能从断点恢复。对传输类 Step取决于服务器是否支持 byte-range。源码层面TaskStep类变量canPause默认TrueTask.canPause属性取当前 RUNNING Step 的canPause值见 app/models/task.py 与 app/models/task.py。Task Error任务错误任务执行过程中已知的失败——服务器错误、磁盘空间不足、运行时未安装等。它携带用户可见的消息模板同时作为 i18n key和格式化参数class TaskError(Exception): def __init__(self, message: str, **params): super().__init__(message) self.message message self.params params见 app/models/task.py。Task 有单一错误边界Task.run()在任意 Step 抛错时将异常转换为TaskError并记到当前 Step 上见 app/models/task.py。失败后 Step 上记录 Step Errormessage params仅运行时存在不持久化。文件选择多文件任务的交互模型Selectable File可选文件多文件 Task 内的一个可勾选下载单元——可以是仓库文件、播放列表视频、多分 P 页面或种子文件。关键规则通过稳定索引标识索引不随选择变化改变选择不创建或销毁 Step任何 Task 状态下都允许取消选择的文件保留部分进度。对应实现为TaskFile含index、relativePath、selected、downloadedBytes等字段见 app/models/task.py与Task.setSelection(selectedIndexes)见 app/models/task.py。任务执行与状态汇总时通过_isStepSelected只统计被选中文件对应的 Step见 app/models/task.py。Revive复活已完成的 Task 因新选中的文件有待下载工作而回到下载状态清除完成时间戳并自动启动 Task仅对COMPLETED状态的 Task 生效。对应逻辑在TaskService.updateSelection中当原任务已完成、且新选择中存在未完成的文件时task.completedAt 0并重新调度见 app/services/task_service.py。任务创建Task CreationTask Options任务选项用于解析、创建或编辑 Task 的应用层选项。四种来源浏览器 Resource页面媒体Page Media合并请求Merge如音视频分离资源合并二进制安装如 FeaturePack 的 runtime 安装任务。源码中有三种具体子类型见 app/models/task.pydataclass(frozenTrue) class ResourceTaskOptions(TaskOptions): # name、size、canUseRangeRequests dataclass(frozenTrue) class PageTaskOptions(TaskOptions): # pageUrl、pageTitle dataclass(frozenTrue) class MergeTaskOptions(TaskOptions): # video audio命名禁忌不使用 payloadpayload 仅在原始传输 seam 使用。浏览器端消息通过toTaskOptions(source, payload)按来源转换成对应 Options见 app/services/browser_service.py。Task Parser任务解析器FeaturePack 提供的能力将 Task Options 转为 Task。声明优先级和匹配规则高优先级的 Parser 先检查。抽象基类见 app/models/pack.pyclass TaskParser: priority: int 100 def match(self, options: TaskOptions) - bool: ... def matchPassive(self, options: TaskOptions) - bool: ... async def parse(self, options: TaskOptions) - Task: ...FeatureService注册时对全部 Parser 按priority升序排序优先级数值越小越先检查见 app/services/feature_service.py。Task Draft任务草稿用户确认前的未确认任务状态。内含一个或多个 Draft Item每个 Draft Item 跟踪一条 URL处于三个状态之一Parsing解析中Resolved解析成功持有 TaskFailed解析失败。延迟确认用户确认时尚在解析的 item 会在后台等待解析完成后自动提交confirmedOptions记录确认时的选项见 app/services/task_draft.py 与_onParsed的回调逻辑。Task Service 不理解 draft 状态——草稿由 app/services/task_draft.py 的TaskDraft独立管理。命名禁忌不叫 pending task、unconfirmed task。Resource资源浏览器扩展捕获的可下载物。由 Browser Service 接收后转换为 Task Options 进入任务创建流程toResourceTaskOptions见 app/services/browser_service.py。注意与泛义资源区分——在代码与文档中 Resource 特指扩展侧产物。任务执行Task ExecutionTask Run任务运行Task 在下载循环中的当前执行。一个 Task 同时只有零或一个活跃的 Task Run。Task Run 按待完成 Step 的顺序迭代 Task Step。实现上Task.run()遍历pendingSteps()依次 await 每个 Step见 app/models/task.py 与 app/models/task.py。命名禁忌不叫 execution、session。Task Step任务步骤Task 内的一个可执行步骤一个 Task 可能有一个或多个 Step。TaskStep是注册式基类子类通过__init_subclass__以模块名.类名注册到_registry从而支持按类名反序列化见 app/models/task.py。Step 持有status、progress、receivedBytes、speed等运行态并负责自身的文件删除与移动deleteFiles、moveFiles。命名禁忌不叫 stage、phase、action。Subworker分片子任务HTTP 或 FTP Step 内的一个分片传输单元负责一个 byte-range 区间。命名禁忌不叫 worker、thread、chunk。分片数量由TaskOptions.subworkerCount决定浏览器端也可通过preBlockNum字段覆盖见 app/services/browser_service.py。应用角色Application RolesTask Service任务服务拥有用户可见任务工作流的唯一公共入口公开动词包括add、start、pause、delete、redownload、edit、setCategory、applySelection源码中为updateSelection、resumeSaved、stop见 app/services/task_service.py。命名禁忌不允许外部直接操作 Task 的状态转换——所有状态变更都应经由 Task Service。实现细节可验证的源码事实TaskQueue维护等待队列与运行映射_pump()在并发数低于cfg.maxTaskNum时持续派发见 app/services/task_service.pyadd时若开启分类先由CategoryService计算分类并解析目标目录再做输出路径去重自动追加(1)、(2)后缀并检查磁盘空间见 app/services/task_service.pyredownload停止 Task Run、删除 Task Files、重置同一个 Task、启动新的 Task Run见 app/services/task_service.py。Feature Service功能服务拥有 pack 发现、parser 优先级路由和 pack 生命周期。将 Task Options 路由到匹配的 Parser若无 parser match失败——此失败发生在 Task 创建之前不属于 Task Error。对应实现parse()依次调用parser.match(options)全部不匹配则抛出ValueError(No parser matched: ...)见 app/services/feature_service.py。此外解析前会根据 URL host 匹配身份预设TLS 指纹/UA见 app/services/feature_service.py。FeaturePack功能包全栈垂直切片——从 parser 到 card 自包含。可提供task parser、card、file type、binary runtime、page 或 setting group。抽象类见 app/models/pack.py每个 Pack 由 features 下以manifest.toml声明的目录承载例如 features/http_pack/manifest.toml[pack] entry pack.py class HttpPack dependencies [] version 1.0.1 gdMinVersion 4.3.8依赖方向规则Pack 内部 cardsView可 import task/config/session反过来不行engine 代码不知道 View 存在。用户可见文本的 i18n 归 View 层——model 存机器可读 keyView 映射到翻译文本error_catalog是给 lupdate 的声明文件不参与运行时。命名禁忌不叫 module、extension。Pack 加载经过依赖拓扑排序orderedByDependency检测循环依赖与缺失依赖并校验gdMinVersion与当前应用版本见 app/loader.py。Binary Runtime二进制运行时FeaturePack 可探测或提供安装任务的外部可执行文件家族。抽象类见 app/models/pack.py通过probeVersion()异步执行--version探测版本createInstallTask()生成安装任务delete()清理安装目录。例如 yt-dlp、ffmpeg 等运行时都以这种方式托管。Browser Service浏览器服务浏览器扩展的协议适配器接收扩展消息翻译为 Task Service 动词返回结果。它是一个绑定127.0.0.1的 WebSocket 服务器端口由cfg.browserExtensionPort配置完整消息协议见 app/services/browser_service.py握手PAIR_REQUEST弹窗确认配对→HELLO校验 token 与协议版本→HELLO_ACK回传应用版本与能力清单任务创建CREATE_TASK结果可为created/drafted/rejected三态任务控制TASK_ACTION动作含toggle_pause、cancel、remove、redownload、open_file、open_folder状态推送订阅后每秒广播TASK_SNAPSHOT含进度、速度、文件大小等摘要见 app/services/browser_service.py。协议版本号PROTOCOL_VERSION 2不匹配时返回protocol_mismatch并断开。Clipboard Listener剪贴板监听器监控剪贴板变化过滤出 URL 后发出通知。位于 app/view/shell/clipboard_listener.py。Category分类下载分类和目标目录规则将文件扩展名匹配到分类并解析下载目录。默认预置 8 个分类视频、音频、图片、字幕、文档、压缩包、程序、其他见 app/services/category_service.py。匹配算法支持复合后缀如tar.gz优先匹配tar.gz再退化为gz目录模板支持{default}占位符替换为默认下载目录见 app/services/category_service.py。命名禁忌不叫 group、tag、type。Coroutine Runner协程运行器运行异步工作并桥接回 UI 线程的应用 actor对 Task 一无所知。Task Service、Feature Service、Browser Service 全部通过它提交协程、取消任务、在 UI 线程回调。Speed Meter速度计全局下载速度监视器下载引擎喂入字节数据addSpeed聚合后每秒发出速度变更通知_tickLoop每 1 秒结算一次currentSpeed。同时提供全局限速门控waitForSpeedLimit在isSpeedLimitEnabled开启时若本周期字节数超过cfg.speedLimitation则休眠等待见 app/services/speed_meter.py。Task 的每个 Step 在run()中通过reportSpeed/waitForSpeedLimit两个回调接入见 app/services/task_service.py。Signal Bus信号总线进程级事件总线只承载跨模块的应用级事件不承载任务或业务信号——那些在各自的 Service 上如TaskService.taskAdded等 Signal见 app/services/task_service.py。Client客户端带可选 TLS 指纹模拟的 HTTP 客户端位于 app/client.py。FeatureService.parse会根据 host 匹配身份预设注入clientProfile指纹与userAgent。Plan计划所有任务完成后做 X 的意图关机、重启、休眠或打开文件。枚举PlanActionSHUTDOWN/RESTART/SLEEP/OPEN_FILE见 app/services/plan.pytrigger()在tasksAllCompleted信号触发且确认全部完成后执行对应平台动作见 app/services/plan.py。Settings设置应用级用户配置。命名禁忌不叫 options——options 是每个 Task 的输入不是应用配置。配置定义集中在 app/config/cfg.py持久化为config.json见 app/view/windows/config/config.json。应用更新App UpdateApp Dir应用目录正在使用的安装目录。命名禁忌不叫 install dir、program folder。Portable Folder便携目录App Dir 内名为GhostDownloader的目录。Portable 模式下 Settings、Task Record、Staging 住在这里。命名禁忌单独说 GhostDownloader 文件夹会与用户模式的%LOCALAPPDATA%\GhostDownloader、App Dir 本身混淆。Seed Features种子功能App Dir 内features/目录。只读的出厂默认 Pack 集合签名覆盖运行时不修改。命名禁忌不叫 factory packs、bundled packs。Features Dir功能目录APP_DATA_DIR内features/目录。可变的 Pack 运行时目录加载、更新、暂存都在这里。注意与 Seed Features 严格区分。Seed播种启动时按版本号将 Seed Features 同步到 Features Dir。版本低于种子的 Pack 被覆盖高于或等于种子的保留。实现见 app/loader.py 的seedPacks逐一比较userManifest.version与seedManifest.versionparseVersion语义比较仅当用户版本更低时才覆盖。命名禁忌不叫 copy、sync、migrate。Uninstaller卸载程序Inno Setup 写在 App Dir 里的卸载程序与日志通常是unins00.exe与unins00.dat安装脚本见 scripts/Ghost-Downloader-3.iss。命名禁忌不叫 setup、installer。Patch补丁一份目录级增量文件。命名禁忌不叫 delta、diff。Staging暂存区更新下载物的落地目录。全量更新时先在 Staging 内构建新树Updater 再搬到 App Dir 旁。实现中为APP_DATA_DIR / update_staging见 app/services/update_service.py。New Dir新目录App Dir 旁已经打好的新树Staging 内的app_new。命名禁忌不叫 dest、out。Backup Dir备份目录App Dir 改名让出后的旧树。命名禁忌不叫 old、prev。Updater更新器进程外的更新程序等应用退出后做 Patch 与 Install。对应源码为 tools/updater/updater.c。应用侧通过subprocess.Popen以分离进程启动Windows 使用DETACHED_PROCESS参数为[updater, pid, appDir, python路径, patch|newDir]见 app/services/update_service.py。命名禁忌不叫 helper、installer。Apply应用退出时把已就绪的更新交出去Pack 暂存到 Features DirpackId_pending目录下次启动经installPendingPacks落地应用则启动 Updater见 app/services/update_service.py 与 app/services/update_service.py。命名禁忌不叫 install、commit。Install安装Updater 把 New Dir 换成 App Dir。命名禁忌不叫 swap、rename、deploy。Restructure重排macOS 上 Install 后Updater 为Contents/Resources/的每个条目在Contents/MacOS/创建 symlink。目的满足 Apple 签名要求MacOS/不放非代码真实文件同时保持运行时路径透明。对应脚本见 scripts/restructure_macos_bundle.py。命名禁忌不叫 relocate、move。更新分发Update DistributionOrigin权威源应用更新与附属二进制的权威托管方构建、打 tag、发布资产以 Origin 为准。当前是 GitHubapp/update.py中的APP_REPO。命名禁忌source of truth 不单独当术语不叫 primary / 主镜像。Source拉取源客户端竞速拉取更新元数据和资产的一个托管端点。当前集合是 github 与 gitcode。相关证据ADR 0009-gitcode-raw-via-cnb.md 讨论了通过 CNBCloud Native Buildpacks代理 gitcode raw 资源命名禁忌不叫 Mirror、CDN、channelCNB 不是 Source。典型对话场景Example Dialogue原文档以问答形式澄清了两个高频误用场景这里补充其背后的实现依据Dev:用户按暂停时我们删除 Task 吗Domain expert:不。Pause 停止 Task Run。Task Record 和 Task Files 保留。对应实现TaskService.pause只做_cancelRun(task)取消协程运行与task.setStatus(TaskStatus.PAUSED)随后持久化Step 的进度字段receivedBytes、progress原样保留见 app/services/task_service.py 与 app/models/task.py。Dev:用户按重新下载时我们创建新 Task 吗Domain expert:不。Redownload 停止 Task Run、删除 Task Files、重置同一个 Task、启动新的 Task Run。对应实现TaskService.redownload先停止运行回调中依次执行task.deleteFiles()删除输出与.ghd进度文件、task.reset()清空进度与completedAt、全部 Step 回到 WAITING、_schedule(task)重新入队派发见 app/services/task_service.py 与 app/models/task.py。术语使用速查术语含义易混词避免Task用户可见下载项download、jobTask Files任务产物与分片临时文件Selectable FileSelectable File可勾选下载单元Task FilesTask Options解析/创建/编辑任务的输入payloadTask Run任务当前执行execution、sessionTask Step可执行步骤stage、phase、actionSubworker分片传输单元worker、thread、chunkTask Draft确认前的草稿pending taskFeaturePack垂直切片功能包module、extensionCategory分类与目录规则group、tag、typePlan全部完成后执行动作无App Dir / Features Dir安装目录 / 可变 Pack 目录与 Seed Features 混淆Seed / Patch / Staging播种同步 / 增量 / 暂存copy、delta、cacheOrigin / Source权威托管方 / 竞速拉取端点Mirror、CDN、channel小结CONTEXT.md 本质上是 Ghost Downloader 3 的领域语言词典——它通过精确的术语定义与命名禁忌把任务生命周期Task → Task Run → Task Step → Subworker、文件选择Selectable File → Revive、任务创建Task Options → Task Parser → Task Draft、应用角色Task Service、Feature Service、FeaturePack、Browser Service 等与更新体系Seed Features → Staging → Updater → Install串成一张完整的地图。结合上述源码路径你可以从术语直接定位实现任务状态机看 app/models/task.py任务编排看 app/services/task_service.pyPack 体系看 app/models/pack.py 与 app/loader.py扩展桥接看 app/services/browser_service.py更新链路看 app/services/update_service.py。在阅读或贡献代码时遵守这套术语就能与项目既有设计保持一致避免语义污染。【免费下载链接】Ghost-Downloader-3The only downloader you need. 下载器的集大成者。项目地址: https://gitcode.com/GitHub_Trending/gh/Ghost-Downloader-3创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考