unfetch: Instructions file for Codex

unfetch — 开发指南

产品定位

unfetch 是一个专注于下载的工具，是 Unflick 生态的下载引擎层。

核心问题：Unflick 内置的视频下载能力很弱——它只是调用 yt-dlp 提取流媒体 URL 然后用 mpv 播放，并没有真正的下载管理：无断点续传、无多线程加速、无队列管理、无 BT/磁力链接支持。unfetch 填补这个缺口。

定位关系：

Unflick  →  播放（libmpv，本地文件 + 流媒体）
unfetch  →  获取（HTTP 多线程 + BT + 磁力 + ed2k + 1000+ 视频网站）

联动方式：unfetch 下载完成后，可一键调用 unflick play <file>；Unflick 中"另存为"按钮调用 unfetch add <url>。

---

架构决策

CLI/MCP First（继承自 Unflick）

每个功能必须先通过 CLI 和 MCP 可用，然后才考虑 GUI。

GUI 是可选的，daemon 是必须的。关掉 GUI 窗口不影响正在进行的下载任务。

双进程架构

Go daemon（下载引擎）  ←── REST API ──→  Rust/Tauri shell（GUI + CLI + MCP）
     ↑                                          ↑
     └── unfetch add <url>                      └── unfetch --mcp
          (CLI 直接调用 daemon API)                  (AI 工具)

• Go daemon：负责所有下载逻辑（HTTP、BT、yt-dlp 集成）。以独立进程运行，暴露本地 REST API（默认端口 19543）。Go 二进制打包进 Tauri 的 resources 目录。
• Rust/Tauri shell：负责 GUI 窗口、CLI 命令解析（clap）、MCP 服务器。所有操作都通过 REST API 转发给 Go daemon，自身不包含任何下载逻辑。

为什么用 Go 做 daemon，而不是纯 Rust？

• go-ytdlp（Go 绑定）比 Rust 的 yt-dlp 集成成熟得多
• anacrolix/torrent（Go BT 库）功能完整，是业界标准
• Go 的 goroutine 天然适合并发下载任务管理
• Unflick 已经用了 Rust，两个项目技术栈互补而不重复

---

技术栈

层	技术	说明
下载引擎	Go 1.23+	daemon 进程，REST API
BT 协议	anacrolix/torrent	支持 BT + 磁力链接
视频网站下载	go-ytdlp (go-ytdlp/go-ytdlp)	包装 yt-dlp 二进制
HTTP 下载	自研，基于 Go net/http	多线程分片 + 断点续传
ed2k 协议	go-ed2k 或调用 aMule CLI	可选，后期支持
GUI 框架	Tauri 2 + React 18 + TypeScript	与 Unflick 一致
前端状态	Zustand	与 Unflick 一致
前端样式	Tailwind CSS + Framer Motion	与 Unflick 一致
CLI 解析	clap 4（Rust）	与 Unflick 一致
MCP 服务器	Rust（JSON-RPC 2.0 over stdio）	与 Unflick 一致
配置持久化	JSON（~/.config/unfetch/config.json）
任务持久化	SQLite（Go 侧，~/.local/share/unfetch/tasks.db）
包管理（前端）	pnpm	全局约定

---

目录结构

unfetch/
├── AGENTS.md
├── README.md
├── .gitignore
│
├── core/                          # Go daemon（下载引擎）
│   ├── go.mod
│   ├── go.sum
│   ├── main.go                    # daemon 入口，启动 HTTP 服务器
│   ├── api/
│   │   ├── router.go              # REST API 路由（chi 或 gin）
│   │   ├── tasks.go               # /tasks 端点
│   │   └── config.go              # /config 端点
│   ├── downloader/
│   │   ├── http.go                # 多线程 HTTP 下载（分片 + 续传）
│   │   ├── bt.go                  # BT + 磁力链接（anacrolix/torrent）
│   │   └── ytdlp.go               # yt-dlp 集成（go-ytdlp）
│   ├── queue/
│   │   ├── manager.go             # 任务队列（并发控制、优先级）
│   │   └── store.go               # SQLite 持久化
│   └── types/
│       └── task.go                # Task、Status、Config 数据结构
│
├── src/                           # React 前端
│   ├── App.tsx
│   ├── main.tsx
│   ├── index.css
│   ├── components/
│   │   ├── TaskList/
│   │   │   ├── TaskList.tsx       # 下载任务列表
│   │   │   └── TaskItem.tsx       # 单个任务（进度条、速度、ETA）
│   │   ├── AddTask/
│   │   │   └── AddTaskDialog.tsx  # 添加任务对话框（URL 输入 + 选项）
│   │   ├── Settings/
│   │   │   └── SettingsPanel.tsx
│   │   └── TitleBar.tsx
│   ├── stores/
│   │   ├── taskStore.ts           # 下载任务状态
│   │   └── settingsStore.ts
│   └── lib/
│       └── api.ts                 # 调用 daemon REST API 的封装
│
└── src-tauri/                     # Rust/Tauri shell
    ├── Cargo.toml
    ├── tauri.conf.json
    └── src/
        ├── main.rs                # 模式检测（GUI / CLI / MCP）
        ├── lib.rs
        ├── daemon/
        │   └── mod.rs             # 启动/检测 Go daemon 进程
        ├── cli/
        │   ├── mod.rs
        │   └── commands.rs        # clap 命令定义 → 调用 daemon REST API
        ├── mcp/
        │   ├── mod.rs
        │   ├── server.rs          # JSON-RPC 2.0 over stdio
        │   └── tools.rs           # MCP 工具定义
        └── gui/
            └── commands.rs        # Tauri commands（主要是代理给 daemon）