智能下载调度器设计文档包

本目录是智能下载调度器的实现级设计包，目标交付形态为 Go CLI。设计重点不是重写现有下载器，而是围绕本机已有 CLI 形成一套可解释、可回退、可持久化学习的调度系统。

文档导航

• docs/architecture/architecture.md
  • 整体架构、模块职责、主流程、失败回退、持久化写回。
• docs/architecture/technical-design.md
  • Go 技术栈、项目结构、SQLite ORM、迁移、桥接与测试方案。
• docs/architecture/strategy-matrix.md
  • URL 特征、信号抽取、候选策略评分、回退模板。
• docs/contracts/cli-spec.md
  • Go CLI 的子命令、参数、JSON 输出、错误码。
• docs/contracts/external-cli-contracts.md
  • 外部下载器和探测器的命令合同、成功判定、错误归一化与 feature gate 约定。
• docs/contracts/browser-probe-payload.md
  • Browser Probe 标准载荷、字段约束、TTL 规则与 cat-catch 映射示例。
• docs/data/sqlite-ddl.sql
  • SQLite 建表语句、索引、更新时间触发器、枚举约束。
• docs/testing/test-fixtures.md
  • 探测、规划、下载与浏览器嗅探的测试夹具清单与预期结果。
• docs/testing/test-scenarios.md
  • 验收清单与回归场景。
• docs/diagrams/dispatch-flow.puml
  • 主调度活动图。
• docs/diagrams/browser-probe-flow.puml
  • 浏览器嗅探结果导入与本地桥接流程图。
• docs/diagrams/site-sync-flow.puml
  • 每月站点能力同步活动图。

OpenSpec

• OpenSpec 工件现在位于 openspec/。
• 当前 active changes 位于 openspec/changes/，已归档变更位于 openspec/changes/archive/。
• 后续执行 openspec status、openspec validate、/opsx:apply 时，应以当前项目根目录作为工作目录。

UML 渲染

• 当前 docs/diagrams/ 下的流程图已改为中文版本。
• 可使用本机 D:\Java\CLI\plantuml-1.2026.2.jar 渲染 svg/png。
• 建议输出到 docs/diagrams/rendered/，把渲染产物当作预览文件，不作为设计源文件。

术语表

• Resolver
  • 对输入 URL 做规范化、跳转跟随、Host 提取与哈希计算。
• Detector
  • 做轻量探测，抽取 content_type、m3u8/mpd、Range、高置信 DRM/EME 技术标记等信号，并尽量保留可直接执行的媒体 URL；没有浏览器捕获但已经抽出媒体目标时，默认补浏览器化 User-Agent 与页面来源 Referer / Origin；对瞬时 header timeout 会做有界重试与短退避。
• Browser Probe
  • 由浏览器扩展、自动化脚本或受控浏览器会话提供的页面侧嗅探结果；download 现在可按需先后台启动 Edge 捕获真实媒体请求与请求头，必要时再切到可见窗口；即使页面播放器本身因 CORS 或前端脚本失败没能成功消费 manifest 响应，也会尽量复用已经发出的真实媒体请求。
• Browser Probe 标准化器
  • 把 cat-catch、CDP 自动捕获、BROWSER_BRIDGE 或其它来源的原始导出格式归一化为 smartdl 可消费的标准捕获记录。
• Planner
  • 根据规则、站点目录和探测信号计算候选策略与回退链。
• Executor
  • 统一封装对 yt-dlp、N_m3u8DL-RE、gopeed、ffmpeg、gallery-dl 的调用。
• Validator
  • 用 ffprobe 对下载结果做容器级校验。
• Store
  • 负责 SQLite 的目录同步、缓存、观测记录和任务历史。
• Site Capability
  • 从站点目录同步得到的候选能力记录，不代表绝对可用。
• Probe Cache
  • 某个 URL 的最近探测结果缓存，用于避免重复探测。
• Browser Capture
  • 浏览器侧导入的探测结果，通常带有更高置信度的媒体地址、请求头和 Cookie。
• Fallback Chain
  • 规划阶段预先生成的候选策略链，某一策略失败时按顺序切换。

V1 范围

• 提供本地单用户 CLI：probe、plan、download、sync-sites、ingest-sniff、bridge、db migrate、db status、db rollback。
• 使用 SQLite 持久化规则、缓存、观测记录、任务历史和同步结果。
• 使用本机现有 CLI 执行真实下载，不在 v1 重写下载协议栈。
• 允许按月同步 yt-dlp 官方站点列表到本地 site_capability。
• 允许未知站点通过运行时探测进入 host_observation 与 probe_cache。
• 允许浏览器侧嗅探结果通过 ingest-sniff 或 bridge 进入 browser_capture，作为 Detector 的可选高置信度信号源。
• 允许 download 在需要时默认先后台启动受控 Edge 会话，捕获真实媒体请求并回灌到 browser_capture -> plan -> download 链路；只有后台阶段未命中时才切到可见 Edge。
• 仍允许 ingest-sniff 或 bridge 作为高级兼容入口导入外部浏览器捕获。

V1 非目标

• 不实现公开服务端 API、Web UI 或桌面 GUI；bridge 只作为本地回环辅助接收器存在。
• 不在本轮文档中定义自动创建 Windows 计划任务或 Codex automation。
• 不处理 DRM 绕过；检测到高置信 DRM/EME 技术标记时直接阻断并进入 BLOCKED_DRM。
• 不把 supportedsites.md 当作真值库；它只是候选站点目录来源之一。

设计原则

• 先探测、后选择，不绑死单一下载器。
• 优先复用成熟 CLI，把 Go 代码集中在调度、回退、持久化和验证。
• 默认走稳妥策略，manifest 类资源优先交给 N_m3u8DL-RE，直链文件再考虑 gopeed。
• 所有关键判断都要求能落地到结构化输出或结构化表记录。
• 未知站点要能沉淀运行时经验，避免每次从零开始。
• 浏览器扩展只是可选信号源，不是硬依赖；只要能导出标准化 JSON，就能接入 smartdl。

约定

• 文档正文使用中文，命令名、表名、字段名、枚举值使用英文。
• 目录内只保存 .puml 源文件，不提交渲染图片。
• CLI 程序名固定为 smartdl。
• 默认数据库文件路径为当前用户目录下的 .smartdl/smartdl.db；无法识别用户目录时回退到 ./data/smartdl.db。
• 运行时配置文件固定为当前用户目录下 .smartdl/smartdl.yml；无法识别用户目录时回退到 ./data/smartdl.yml。
• 异步文件日志固定为当前用户目录下 .smartdl/log/smartdl.log；无法识别用户目录时回退到 ./data/log/smartdl.log。
• 默认下载目录为当前用户 Downloads。
• browser_capture 默认 TTL 为 1800 秒。
• bridge 仅监听 127.0.0.1，默认地址为 127.0.0.1:16781。
• bridge 与 ingest-sniff 共用同一套标准化载荷，当前都支持单对象和对象数组输入。
• GOPEED_DIRECT 用于支持 Range 的直链下载目标，包括真直链媒体文件与常见普通文件直链；HLS/DASH 主路径固定为 NM3U8DLRE，必要时回退 FFMPEG_DIRECT。
• 普通文件直链若命中 GOPEED_DIRECT 且下载成功，校验阶段直接返回 SKIPPED，不调用 ffprobe。
• 推荐的主工作流是：直接执行 smartdl <url> 或 smartdl download <url>；默认输出目录为当前用户 Downloads，download 还会自动完成默认数据库创建与 migration。
• download 会在首次规划前检查当前用户目录下 .smartdl/smartdl.yml 中的 sync.last_sync_at；若当月尚未同步站点目录，则先自动执行一次 sync-sites，失败只记 warning 不阻断本次下载。
• 当普通探测或首次下载失败不足以拿到高置信请求上下文时，程序会先在后台启动 headless Edge 自动尝试播放，只有后台阶段未命中时才切到可见 Edge 等待用户接管。
• 对于页面里真实发出的 .m3u8 / .mpd 请求，自动捕获会同时关注请求、响应和浏览器侧 loadingFailed；因此页面播放器自己因 CORS 或前端错误播放失败时，仍可能成功把请求回灌到下载链。
• bridge / ingest-sniff 仍保留为高级兼容路径，适用于已存在的外部扩展、脚本或调试代理导出结果。
• sync-sites 默认使用 yt-dlp 官方 raw supportedsites.md；若同时传入 --source-file 和 --source-url，以前者为准。
• sync-sites 与 download 自动同步都会把最近一次成功同步的来源与时间写回当前用户目录下 .smartdl/smartdl.yml。
• cat-catch 作为首个已知适配源接入，但内部设计不绑定其私有导出格式。

参考来源

• yt-dlp 站点目录
  • https://github.com/yt-dlp/yt-dlp/master/supportedsites.md
• yt-dlp 主仓库与结构化输出说明
  • https://github.com/yt-dlp/yt-dlp