简体中文
Rivu 产品与界面设计
产品方向
Rivu 是轻量、优先面向 macOS 的 BitTorrent 客户端。菜单栏用于快速查看与控制，主窗口用于管理任务和检查详情。
原提案保留 Go 1.27.2 + MyGo v0.4.3 原生技术栈。交互原型只是设计辅助，不是应用运行时，不引入应用 Web 前端依赖。初版界面使用中文并为英语本地化留出空间，传输与持久化保持跨平台，优先完成 macOS 集成。
主要使用流程
- 打开种子、粘贴磁力或拖入文件，选择位置和文件后开始下载。
- 在列表阅读进度、速度、剩余时间及可处理错误。
- 关闭主窗口仍继续传输，通过菜单栏查看或暂停。
- 接收完成通知，在 Finder 中显示文件，按策略继续做种。
- 主动启用登录启动；后续安静启动并恢复之前应运行的任务。
- 手动或自动检查更新，在用户同意重启前保存传输状态。
范围与优先级
| 领域 | P0 初始发布 | 后续迭代 |
|---|---|---|
| 导入 | 种子、磁力、拖放、批量导入、infohash 去重 | 监视文件夹、RSS |
| 传输 | 暂停/恢复、队列、重启恢复、校验、文件选择、目录 | 调度、顺序下载 |
| 管理 | 搜索、筛选、排序、多选、批量操作、区分移除与删除 | 标签、规则、批量重定位 |
| 详情 | 概览、文件进度/优先级、Tracker 与节点 | 分片诊断、历史图表 |
| 带宽 | 全局上下行限制、临时限速、并发数 | 单任务限制、时段规则 |
| 做种 | 上传总量、分享率、按比例停止、手动恢复 | 按时间和标签策略 |
| macOS | 菜单栏、Dock、原生对话框、通知、快捷键 | 仅菜单栏模式 |
| 设置 | 外观、目录、做种、启动、通知、连接、更新 | 高级代理、诊断 |
| 更新 | 手动/自动检查、独立自动安装、说明、失败处理 | 预览通道 |
首版不包含内容搜索、媒体库、播放、账号、云同步或远程控制。示例采用开源发行版和开放许可影片。未验证全部流量路径前，不宣称匿名或完整代理路由。
信息架构与屏幕
主窗口由侧边栏、工具栏、任务列表、详情和状态栏构成。侧边栏包含全部、下载中、做种中、已完成、已暂停、需要处理。工具栏提供添加、暂停/恢复、更多、搜索、详情开关。详情分概览、文件、连接。菜单栏显示总速度、最多四个任务、注意事项及常用动作。添加流程为来源 → 元数据 → 位置 → 文件 → 开始或排队。设置分通用、下载与做种、连接、通知、更新与关于。
主窗口
提案默认 1180 × 760 pt、最小 880 × 560 pt；侧边栏 190–220 pt，可选详情约 292 pt。空间不足先隐藏详情，必要时提供详情 sheet。浏览器窄屏布局只服务评审，不表示提供移动应用。
保留原生红黄绿按钮，工具栏融入标题栏。导航可用侧边栏材质，阅读区域使用不透明表面。任务行约 86–96 pt，优先显示名称，其次已传输/选中字节、状态、细进度条、速度和 ETA。列表可截断名称，详情和提示显示全名，避免大指标卡抢占任务信息。
单击选中、双击打开详情，不执行下载文件。原生版支持 Cmd/Shift 多选、Space 暂停/恢复。已完成包含正在做种与停止做种的完整任务，因此计数可交叠；下载中不含排队或读取元数据。保持排序稳定，默认按新增时间，也支持名称、进度、状态。右键提供暂停/恢复、Finder 显示、校验、复制磁力和移除。
详情
| 标签 | 内容 |
|---|---|
| 概览 | 名称、状态、选中文件进度、速度、ETA、大小、上传、比例、添加时间、位置、做种目标 |
| 文件 | 树、选择、逐文件进度、高/普通/不下载、选中大小 |
| 连接 | Tracker 结果、下次通告、节点数量及来源 |
完成率分母排除未选中文件。元数据未到时明确显示读取中，不编造大小、文件或 ETA。Tracker 失败先作为 Tracker 级结果，只有阻碍进度且需要用户处理时才提升为任务错误。
菜单栏面板
约 18 pt 单色模板图标，由 macOS 着色，使用提示点和文字表达注意状态，避免持续动画。左键切换锚定真实图标的面板，再次点击、外部点击或 Escape 关闭，定位遵循当前屏幕可见区域。
面板约 360 pt 宽，高度随内容变化，显示总速度、最多四任务及注意事项。点击任务打开主窗口并选中。主窗口与面板订阅同一会话，不分别维护传输状态。
全部暂停记录本次暂停成员，恢复批次只恢复这些任务，不恢复原本单独暂停的任务。移除或手动恢复任务后，将其移出批次。右键为原生菜单，包含打开、添加、全部暂停、限速、设置、退出。空状态提供添加，有错误时链接到需要处理。
添加下载
Cmd+O 选择种子，Cmd+N 打开添加窗口。只在明确操作后读剪贴板，不后台监视。原提案允许磁力在元数据未就绪时排队，并明确显示文件列表/大小待获取；当前已实现的提交规则以使用指南为准。
元数据就绪后显示名称、选中/总文件数、选中大小、文件树、位置、空间和立即开始。默认位置为 ~/Downloads/Rivu，首次传输确认，允许逐任务覆盖。按身份而非名称去重；相同 infohash 定位已有任务，不同种子的同名冲突应通过目录策略处理。
来源、选择、目录与空间通过校验后才能提交。目录暂不可用时，只有明确解释才可建立暂停任务；至少选择一个文件。批量预览逐项报错，不因一个坏种子阻止全部；成功后关闭 sheet 并选中新任务。
设置与默认值
| 分类 | 提议默认值与控件 |
|---|---|
| 通用 | 跟随系统外观、菜单栏开启、登录启动关闭；启用后默认后台启动 |
| 下载 | ~/Downloads/Rivu、三个并发、恢复原运行任务、完成通知开启 |
| 做种 | 默认继续并在分享率 2.0 停止，支持不限或立即停止，导入和详情可调整 |
| 带宽 | 普通不限速，临时下载 2 MB/s、上传 512 KB/s，原生版可编辑 |
| 连接 | 监听端口、遵守私有规则的 DHT/PEX、诊断、高级选项 |
| 通知 | 完成及可处理失败开启，系统授权单独显示 |
| 更新 | 先征求自动检查同意，同意后每日检查，自动安装关闭，支持手动检查 |
原型为可重复评审默认浅色，产品默认跟随系统。登录项必须显示真实注册结果，本地勾选不代表系统会启动。禁用菜单栏仍保留 Dock。关闭主窗口继续传输，Cmd+Q 退出，可确认中断并记住选择。
更新体验
状态为不可用 → 检查中 → 最新/有更新/检查失败；有更新 → 下载并安装 → 需要重启/安装失败。未配置源、开发构建或不可写位置属于不可用，不能显示已经最新。
同意后后台最多每 24 小时检查一次，加入抖动和失败退避；手动检查绕过定时，分别记录成功与尝试时间。MyGo Update.Install 合并下载、校验、替换，按钮应称下载并安装更新。
自动安装单独启用，等待无下载、校验或做种活动，也允许明确选择立即安装。做种属于活动，应解释等待原因。重启前保存位置、选择、队列、意图和暂停原因，停止调度、刷盘、关闭引擎；保存失败取消重启，仅恢复原本应运行任务。
区分签名错误、架构错误、空间不足、下载中断和安装失败；坏更新不能替换可运行应用。正式发布需可信 HTTPS 源、密钥、公钥、签名及公证。
任务状态模型
期望运行状态与引擎观测分离，避免重连或重启恢复手动暂停。
| 状态 | 展示与主要操作 |
|---|---|
| 读取元数据 | 文件列表读取中、大小未知；暂停、移除 |
| 排队 | 名额和队列位置；立即开始、暂停 |
| 校验 | 校验百分比；暂停、移除 |
| 下载 | 进度、速度、剩余时间；暂停、文件选择 |
| 等待节点 | 等待可用节点，无 ETA；检查连接、重试 |
| 暂停 | 解释手动、策略或退出原因；恢复、移除 |
| 做种 | 已完整、上传速度与分享率；停止、显示文件 |
| 完成 | 已达到目标或停止；恢复做种、显示文件 |
| 需要处理 | 空间、权限或磁盘错误；更改位置、重试、移除 |
网络离线是可恢复环境状态，避免重复警报。唤醒/重连只恢复期望运行的任务。统一十进制 MB/GB 和每秒速率，进度统计已验证的选中字节，平滑速率后估算 ETA，无意义时显示横线。
移除默认保留数据，独立且默认未勾选的选项才移到废纸篓。校验共享目录归属，安全移动失败应报错，不回退永久删除。
视觉系统
使用熟悉的 macOS 模式、克制的装饰与清晰层级，任务信息优先。
| 语义 | 浅色 | 深色 |
|---|---|---|
| 内容 | #FFFFFF | #202226 |
| 侧边栏 | #EFF0F3 | #27292E |
| 主文本 | #20232A | #F1F2F5 |
| 次文本 | #626975 | #A8AEB9 |
| 强调 | #0868DB | #5AA2FF |
| 分隔线 | #E3E5E9 | #3B3E45 |
完成/做种用绿，注意用橙，错误用红，同时提供文字或图标。系统字体 SF Pro，中文可回退 PingFang SC；正文约 13 pt，次级 11–12 pt，标题 17–20 pt，速率和字节使用等宽数字。4 pt 网格，8/12/16/24 pt 间距，控件圆角约 6 pt、选中区域约 8 pt。popover 外壳由系统绘制，尊重减少透明度和动态效果。提供焦点、图标可访问名称、无需悬停的核心操作和 VoiceOver 摘要，不每秒播报变化速度。
现有技术栈的实施映射
当时依据 MyGo v0.4.3 源码与示例：窗口/主题/菜单复用；菜单栏使用 NewTray、NewFlyout，设置 Tray、Popover: true、Focusable: true，右键临时附加菜单以免吞左键；登录使用 SetOpenAtLogin、OpenAtLogin、WasOpenedAtLogin；更新使用 Updater.Enabled/Check、Update.Install、App.Relaunch。引擎候选为 anacrolix/torrent，先验证协议、恢复与许可再固定版本。
应用持有会话、桌面服务、更新器与窗口。会话持有意图、队列、命令、快照、引擎和版本化存储。保持小模块，避免通用事件总线。窗口任务取消模型仅适合短操作，不能承载长期传输。引擎后台工作，发布不可变快照，主窗口约 2–4 Hz、面板 1–2 Hz。UI 通过 Window.Update 更新，关闭后拒绝过时回调。
持久记录包括稳定身份、元数据、位置、选择、优先级、期望状态、暂停原因、队列、上传和错误，不序列化节点对象。应用数据位于 ~/Library/Application Support/Rivu。保留损坏设置并提供恢复。路径防穿越与越界，处理符号链接、已有文件、共享路径、空间变化和断开的卷，遵守私有发现规则并隐藏日志凭据。
交付与验收
依次交付原生展示、真实传输闭环、桌面集成和发布准备。必须验证关闭窗口不停止会话、重开不重复任务、退出结束会话；登录注册启用/撤销与后台不抢焦点；手动/批次暂停和睡眠重启保持意图；空间/权限/磁盘/重复/无节点/坏种子有恢复路径；部分选择进度和空间正确；更新不强制中断，检查失败不伪装最新，错误签名保留当前应用。
原生实现运行 make check、make race、go tool mygo vet 和 make snapshots，并独立验收打包后的菜单栏、登录、关联、通知和更新。交叉编译不证明桌面集成正确。
参考资料
- Apple MenuBarExtra、Toolbars、SMAppService。
- MyGo v0.4.3 面板示例、登录 API、更新 API。
- anacrolix/torrent。这些引用保留历史语境，实际接口以当前固定版本源码为准。