Tork 是一款在终端中运行的、高度集成的 BitTorrent 搜索与下载客户端。它不仅能搜索主流公共种子索引站，还能智能合并重复结果、整合多源Tracker，并通过一个TUI（终端用户界面）提供流畅的操作体验。

本教程将指导你完成 Tork 的安装、配置和日常使用。

📦 第一步：安装 Tork

Tork 支持多种安装方式，请根据你的操作系统选择最合适的一种。

1.1 官方推荐方式

  • macOS (Homebrew)：

    1
    brew tap melqtx/tap && brew install tork

  • Arch Linux (AUR)：

    1
    2
    yay -S tork
    # 或使用其他AUR助手

  • Nix：

    1
    nix run github:melqtx/tork

  • Go 环境 (Go 1.26+)：

    1
    go install github.com/melqtx/tork/cmd/tork@latest

    macOS 注意事项：如果 Go 使用了 Nix 的编译器，请使用以下命令强制使用 Apple Clang：

    1
    CC=/usr/bin/clang CXX=/usr/bin/clang++ go install github.com/melqtx/tork/cmd/tork@latest

1.2 从源码构建

  1. 克隆仓库：

    1
    2
    git clone https://github.com/melqtx/tork.git
    cd tork

  2. 构建二进制文件：

    1
    go build -o ./bin/tork ./cmd/tork

    构建完成后，可执行文件 tork 会位于 ./bin/ 目录下。你也可以直接运行而不构建：

    1
    go run ./cmd/tork

⚙️ 第二步：配置与初始设置

Tork 采用约定优于配置的理念，大部分设置开箱即用。

2.1 默认目录与配置

  • 配置目录：~/.tork/
  • 默认下载目录：~/Downloads/tork （可通过 tork -d <你的目录> 启动时修改）
  • 主配置文件：~/.tork/config.yaml（首次运行后自动生成）

2.2 基础配置项（可选）

你可以编辑 ~/.tork/config.yaml 来调整缓存、客户端行为等。以下是一些常用设置示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 元数据缓存设置
metadata_cache:
  enabled: true
  max_mb: 256       # 最大缓存大小（MB）
  max_entries: 512  # 最大缓存条目数

# 高级BT客户端调优（保留0或注释掉以使用默认值）
torrent_tuning:
  half_open_conns_per_torrent: 25
  total_half_open_conns: 100
  download_rate_limit: 0  # 0 表示无限制，单位：字节/秒
  upload_rate_limit: 0

# 健康检查（每日自动检查）
health:
  enabled: true
  interval_hours: 24

🚀 第三步：启动与核心功能

在终端中输入 tork 并回车，即可进入主界面。

3.1 主界面导航

Tork 的核心交互围绕以下几个主要视图，你可以通过标签页或快捷键切换：

  • Home (搜索框)：输入关键词，选择搜索源（如 Knaben、YTS、Nyaa 或 ISO 镜像），按 Enter 搜索。
  • Results (结果列表)：显示搜索结果，相同种子被智能折叠。按键操作：
    • Enter：预览/获取该种子。
    • D：直接下载。
    • Y：复制磁力链接。
    • /：打开智能过滤器。
    • v：查看详细信息和来源。
  • Preview (文件预览)：下载前查看种子内文件列表。
    • Space：切换选择/取消选择单个文件或文件夹。
    • a / n：全选/取消全选。
    • Enter：下载选中的文件。
  • Downloads (下载管理)：查看和管理所有下载任务。
    • Enter：打开下载完成的文件。
    • p：暂停/恢复。
    • s：开始做种。
    • v：重新校验文件完整性。
    • m：移动下载位置。
    • x：移除任务（不删文件）。
    • d：删除任务及文件。

快捷键提示：在任何界面按下 ? 键，可以查看当前视图的所有可用快捷键。

3.2 快速开始：一个完整的示例

  1. 搜索：在搜索框输入 Ubuntu 22.04，选择 ISOs 作为来源，按 Enter。
  2. 选择：在结果列表中找到官方镜像，按 Enter 预览。
  3. 筛选（可选）：在预览界面，如果种子包含多个文件，用 Space 取消选择不需要的文件（如 .nfo 或 sample 文件）。
  4. 下载：按 Enter 确认下载。Tork 会提示开始下载，并自动跳转（或你可以手动切换到）下载管理视图查看进度。

3.3 高级功能：使用 Autopilot (WIP)

Autopilot 功能允许你用自然语言描述需求，让 Tork 自动规划和选择下载。

1
2
3
4
# 描述你想要的内容
tork autopilot "所有绝命毒师 1080p 版本，总大小不超过 40GB"
tork autopilot --dry-run --min-seeders 20 "沙丘 2024 2160p"  # 仅预览计划
tork autopilot --headless --yes "最新的 Ubuntu LTS 版本"    # 非交互模式，自动确认

🔌 第四步：高级配置（SOCKS5 代理）

Tork 原生支持 SOCKS5 代理，可配合 Tor 或其它代理使用，以增强隐私。

  1. 快速使用 Tor (本地默认)：

    1
    2
    tork proxy tor          # 设置代理为 socks5://127.0.0.1:9050 并开启严格模式
    tork doctor --proxy-check # 验证代理是否生效

  2. 使用自定义 SOCKS5 代理：

    1
    2
    3
    4
    5
    # 设置无认证代理
    tork proxy set socks5://127.0.0.1:1080
    # 安全设置带认证代理（避免密码出现在历史记录）
    tork proxy set
    # 然后根据提示输入：socks5://用户名:密码@127.0.0.1:9050

  3. 手动编辑配置文件 (~/.tork/config.yaml)：

    1
    2
    proxy:
      socks5: "socks5://user:password@127.0.0.1:9050"

    安全提醒：包含认证信息的配置文件必须为 0600 权限。Tork 启动时会自动检查并收紧权限。

🩺 第五步：运维与排障

5.1 健康检查 (doctor 命令)

用于诊断配置、磁盘、网络和提供商状态。

1
2
3
4
tork doctor                 # 只读检查
tork doctor --engine        # 包含服务端监听检查
tork doctor --record        # 将结果保存到 ~/.tork/health.json
tork doctor --proxy-check   # 通过代理访问Tor检查服务，验证出口IP

5.2 性能监控

Tork 界面的顶部标题栏会实时显示当前的传输数量和速度。在下载视图中，你可以关注每个种子的连接数和进度。

5.3 常见问题处理

  • 无法连接到搜索源：运行 tork doctor 检查提供商连通性。确保网络允许访问这些索引站。
  • 下载速度慢：检查 ~/.tork/config.yaml 中的 torrent_tuning 部分，适当提高 total_half_open_conns 和 peer_high_water 的值。同时确保你的防火墙没有阻止BT端口。
  • 代理模式下载异常：确认代理服务器工作正常。Tork 在代理严格模式下会禁用DHT、uTP和UDP Tracker，这可能导致找到的peer减少，是正常现象。

⚖️ 重要声明与法律合规

Tork 本身不托管任何文件，也不运营任何Tracker或搜索索引。它是一个工具，通过搜索第三方公共索引站来帮助用户查找和下载内容。

你全权负责确保你下载和分享的内容是你拥有合法权利的文件（如Linux ISO、公共领域媒体、开源软件等）。 使用Tork请遵守你所在地的法律法规以及所使用搜索源的服务条款。

至此，你已经完成了 Tork 的部署、配置和使用入门。开始享受这个轻快、强大的终端下载管理器吧！