架构

应用使用 Go + MyGo 原生 UI。VitePress 是独立的文档构建系统，不作为应用前端嵌入。

状态与所有权

main.go 解析 CLI 选项，将名称、版本、配置路径及从 mygo.json 嵌入的公开更新配置传给 internal/app.Run。app 包负责原生生命周期、窗口和 UI 测试。application 持有偏好设置存储和活动窗口。window 按功能组织连接、传输面板、偏好设置、已保存位置、命令面板，以及浏览器、对象、Bucket、RAM、邮件和更新状态。视图以声明式方式读取状态；commands() 同时定义菜单与命令面板操作。

原生语言和主题 API 在 UI 线程运行。偏好设置在后台写入，随后一起更新 UI 快照、语言、外观和自定义菜单。

后台工作

阻塞工作通过 window.run 执行。启动前复制用户输入，支持上下文取消，并通过 Window.Update 发布结果。

internal/tasks 使用代次检查，防止迟到的进度或完成回调更新已替换的任务或已关闭的窗口。基础层串行处理设置和浏览操作。internal/transfers.Queue 是独立调度器，使用待处理列表和运行计数，分别限制上传、下载，并提供一个对象修改任务槽，因此传输期间仍可浏览。AddBatch 先追加整批选择，再调度一次；任务完成时只检查待处理队列头。已移除但尚未完成的工作仍占用任务槽。完成或跳过的任务释放工作闭包，压缩历史时清除丢弃的指针。状态与回调由 UI 持有，工作线程接收复制的文件路径、对象及服务引用。取消传递到工作上下文；重试在工作停止后启动。断开连接会重置队列代次并释放任务闭包，旧会话回调无法影响新传输。

持久化

config.Store 校验架构版本、语言和外观。互斥锁保护快照。写入使用临时文件、同步和重命名；只有持久化成功后才更新内存。

损坏或不受支持的设置不会被自动覆盖。修复文件后使用“重新加载设置”。较旧的 schema-v1 文件若缺少语言字段，则继承 system。

国际化

internal/i18n/locales/*.json 嵌入 Go 二进制。语义化键让 UI 代码不依赖任何源语言。语言解析与回退采用和 rivu 相同的方式。参见语言与外观。

OSS 边界

internal/ossclient 封装阿里云官方 OSS Go SDK v2，负责 HTTPS Endpoint 校验、AccessKey／STS 签名、区域感知客户端、分页及脱敏错误。在 internal/app 中，connection_actions.go 协调登录和恢复；browser_state.go 持有导航历史、列表合并及排序缓存；browser_actions.go 协调导航请求。对应视图文件渲染 Design v2 界面。预览、分享、元数据和 ACL 字段与对象对话框外壳分离；对象修改有独立的队列编排。传输适配器以流方式处理文件并报告进度，提供明确的冲突策略，在可用时约束下载 ETag，并在发布本地临时文件前校验大小和 CRC64。SDK 传输管理器提供分片和检查点恢复。禁止覆盖标头受 OSS Bucket 版本控制语义约束。UI 不得直接调用 SDK 或持久化密钥。

设计参考与实现里程碑分别跟踪。生产应用发起真实 OSS 请求，固定测试数据只用于测试。账号级列举与直接 Bucket／前缀连接需要不同权限。连接配置持久化时不包含 ID、Secret 或 Token。排序只针对已加载页面，对象前缀搜索在服务端执行。

持久传输与对象操作

internal/transfers.Record 在每个 JSON 文件中保存一项不可变操作描述及其最近结果。工作开始前和结束后，以仅所有者可访问的权限原子替换文件。连接配置和 AccessKey ID 经哈希后用于隔离恢复目录；密钥和签名 URL 均不序列化。恢复时将未完成记录呈现为已停止，必须显式重试。恢复同时返回有效的未完成记录与逐文件诊断；损坏记录保留在磁盘上，不阻止其他任务恢复。SDK 检查点目录属于单个任务，并发尝试不能操作同一检查点。记录租约覆盖工作执行及最后一次日志写入。显式移除会写入删除标记，工作退出后清理日志、检查点和私有下载暂存目录。终态记录保留七天，在连接时清理；未完成或损坏记录永不过期删除。清理失败的数据留待下一轮处理。

上传、下载和递归对象规划位于 internal/transfers，独立于 MyGo。目录规划拒绝符号链接及非普通输入，准备下载目录时使用 os.Root。OSS 键会检查路径穿越、保留名称及大小写冲突。传输任务保留所选相对目录树。下载 SDK 检查点在复用前校验已保存范围。取消时保留分片数据；远端分片清理由需要确认的 Bucket 分片对话框提供。

internal/vault 封装操作系统凭据库。保存和删除都要求显式 UI 操作；保持登录授权后续读取凭据库，绝不回退到明文。测试使用内存凭据库提供者。internal/ossclient 独立于 UI 控件强制检查授权码到期时间、只读限制及根目录范围。

对象预览在解码前施加上限。编辑文本默认保存到新键。替换原对象需要显式选择，执行 ETag 预检并保留标头、元数据、ACL、标签及存储类型；预检与 PUT 不具备原子性。元数据自复制约束源 ETag，并保留 ACL 和内容标头。移动重试会记住已成功的复制；删除仍是独立、非原子的 OSS 操作。对象修改任务仅属于当前会话，重启后不重放。

版本检查通过 internal/updates 使用已配置的 MyGo 更新源／签名格式及 MyGo 安装资格判断，否则使用固定的 GitHub 仓库。自动更新只暂存并验证完整归档；显式安装会重新验证这些字节，替换失败支持回滚，之后单独执行 MyGo 重启动作。不使用增量归档。未配置的开发构建提供手动下载。更新、缩略图和对象详情任务各自使用独立取消代次。设置使用单独的分类对话框，对草稿校验和保存进行防抖。RAM／STS 使用签名 OpenAPI 请求；SMTP 强制使用 TLS。有界诊断工作线程持久化操作状态和错误类型，不记录载荷或密钥。

协议参考：OSS 上传器、PutObject、CopyObject，以及设计中链接的固定上游 OSS Browser 授权码格式。

列表与渲染开销

分页合并使用键集合在线性时间内去重。刷新与合并时替换列表切片；浏览器状态按列表标识、排序规则及搜索条件缓存排序结果。传输历史和确认列表使用 ui.List，仅构建可见行；历史行以任务标识为键，因此筛选和删除后仍关联正确操作。

版本边界

internal/buildinfo.Version 是桌面版本的来源。根入口将其传入 app.Run，tools/version 检查或同步它与 mygo.json。CI、make check 和 Release 工作流运行同一检查。私有根 npm 包的版本不代表桌面发布版本。