How cmdragon/dratk works
先说明:从仓库内容能/不能推断什么
从你提供的 <file_tree> 来看,这个仓库几乎只有:
• .github/*(issue 模板、funding)
• README.md
• docs/images(可能是截图/说明图)
没有 src/, package.json, Cargo.toml, pubspec.yaml, go.mod 等源码与构建配置,因此无法从文件树确定技术栈(Electron/Tauri/Flutter/.NET 等)和真实模块边界。
但 README 描述非常清晰:DraTK 是一个跨平台桌面应用,有模块化/插件化工具集合、主题/多语言、自动更新、认证、通知/窗口状态等“应用级基础设施”。
因此系统设计图应围绕“桌面应用壳 + 核心平台能力 + 工具插件 + 外部依赖(文件系统、更新服务、认证服务等)”来画。
项目类型与目的(在图里要体现)
类型:跨平台桌面端工具集(Toolbox Desktop App),强调插件化扩展。
目的:对本地文件系统做批量整理/清理/结构变换,并提供现代 UI、可撤销、可预览、报告/统计、自动更新、登录认证等能力。
在架构图中,你要让读者一眼看到:
建议采用的画图方法:C4 + 关键流程图(最准确、最不容易过度脑补)
对 Principal 级别最有效的是组合:
2~4 张关键 Sequence/Activity 图:预览整理、执行、撤销、更新等关键链路
> 在缺少源码的情况下,不要假设具体语言/框架;但可以把“UI 渲染层”和“本地能力层(文件系统/更新/存储)”作为抽象容器画出来。
你需要在图中拆出来的“尽可能多”的组件(按层次)
下面给出一个推荐拆分(你可以直接照此画容器/组件图)。
外部参与者 & 外部系统(Context 图)
• User(用户)
• OS 文件系统(Windows/Linux/macOS FS)
• 更新分发端(GitHub Releases / Update Manifest/CDN)
• 认证服务(Auth Provider):README 提到登录/登出,但未说明是本地还是远端;图上可先画为外部服务(可替换)
• (可选)崩溃/日志上报服务:README 未提,可不画;除非你们产品确实有
箭头示例:
• User → DraTK:配置工具参数/执行/撤销/查看报告
• DraTK ↔ OS FS:扫描目录、移动/重命名/删除、读取元数据
• DraTK ↔ Update Service:检查版本、下载、校验、安装、回滚
• DraTK ↔ Auth Provider:登录、token/会话校验、登出
“容器级”内部结构(Container 图)
把桌面应用画成 2~4 个大容器(不要纠结具体技术实现):
Desktop UI Shell(桌面 UI 壳)
• 导航(侧边栏/多标签)
• 设置页面(语言/主题/通知/更新)
• 任务页(各工具 UI)
• 进度与结果展示(统计、详细列表、报告视图)
Core Application Runtime(核心运行时/平台层)
• 插件/工具加载器(动态加载工具模块)
• 任务编排与并发(异步执行、避免 UI 卡顿)
• 统一权限/安全策略(避免误删、根目录保留等策略)
• 日志与审计(为撤销/报告提供事件来源)
Local Services(本地服务层)
• File System Service:扫描、过滤、移动、重命名、删除、冲突处理、特殊字符处理
• History & Undo Service:操作记录、撤销/回滚(工具 3/4 明确需要)
• Report Service:生成整理报告/清理统计
• Settings Store:语言、主题、通知开关、更新渠道、窗口状态
• Window State Manager:保存/恢复窗口大小位置
• Notification Service:toast/系统通知/重要提醒
Update & Security(更新与安全子系统)
• Update Checker(启动时/手动检查)
• Downloader(断点/重试可选)
• Integrity Verifier(SHA256 校验)
• Backup Manager(更新前备份)
• Installer/Applier(替换文件、重启)
• Rollback Manager(失败回滚)
• Channel Manager(稳定/测试)
(可选)Auth Module(认证模块)
• Login UI
• Credential Storage(系统 keychain/加密存储,具体未知可抽象)
• Session Manager(token 刷新、登出)
> 这些“容器/子系统”之间的箭头要明确:UI 只发起命令与订阅状态;真正的文件变更只在本地服务层执行。
“工具插件层”的组件拆分(Component 图里重点表达模块化)
根据 README 的四个工具,把它们统一成一个接口/抽象:
• Tool Plugin Interface(工具插件接口)
• configure() / validate()
• preview()(有预览的工具)
• execute()(执行)
• emitProgress()(进度事件)
• result()(结构化结果:成功/跳过/错误)
• undo()(可撤销工具必须实现)
• Tool: 文件整理专家
• Rule Engine(类型/时间/大小/自定义规则)
• Preview Planner(预览输出:目标路径、冲突、统计)
• Executor(批量移动/归档)
• Tool: 空目录清理
• Directory Scanner(空目录判定)
• Tree Model Builder(树形展示数据)
• Delete Executor(保留根目录策略)
• Tool: 文件夹解散
• Depth Controller(处理深度 1-10)
• Filter(扩展名过滤)
• Flatten Executor(移动/重命名冲突处理)
• Undo Adapter(写入历史)
• Tool: 文件套文件夹
• Folderizer(创建同名目录并移动文件)
• Sanitizer(特殊字符处理)
• Undo Adapter(写入历史)
重要:工具不要直接操作 UI 和存储
图里用依赖箭头表达:Tool Plugin → File System Service / History Service / Report Service;UI 通过 Core Runtime 调度工具。
关键交互关系(你必须画出来的“箭头”和数据流)
为了“最准确”,建议在容器图/组件图上至少标出这些主路径:
用户操作 → UI → Core Runtime → Tool Plugin → Local Services → OS FS
• UI 只负责收集参数/展示状态
• Runtime 负责任务生命周期(开始/取消/并发/错误)
• Tool 负责业务规则
• Local Services 才落盘
执行前预览链路(文件整理专家最关键)
• Tool.preview() → File System Service(扫描/元数据) → Preview Planner → UI(展示预览 + 统计)
• 预览结果应可序列化:供“开始整理”复用/对比(可在图上标注)
撤销链路(工具 3/4 明确要求)
• Execute 时:每一步文件变更 → History Service 记录“反向操作”
• Undo:History Service 重放反向操作 → File System Service → OS FS
• UI:展示撤销进度/结果
自动更新链路(README 描述很完整,值得单独画一张序列图)
• App Start → Update Checker → 拉取 manifest/最新版本 → UI 通知
• 用户确认 → Downloader → Integrity Verifier(SHA256)
• 通过 → Backup Manager → Installer → 重启
• 失败 → Rollback Manager → 恢复旧版本 → 通知
设置/个性化链路
• Settings UI → Settings Store(持久化)
• i18n/Theme Engine 订阅设置变化 → UI 立即刷新(README 提到实时更新)
按“桌面工具集 + 插件化”的特点,图要特别强调的架构原则
• 横切能力平台化:i18n、主题、通知、设置、更新、认证、撤销/历史、报告 都是“平台能力”,工具只是消费它们
• 文件操作的安全边界:所有 destructive 操作(删除/移动)集中在 File System Service,并有统一的策略(根目录保留、冲突命名、权限错误处理)
• 异步任务与 UI 解耦:用“任务队列/worker/后台执行”的概念画出来,解释“避免界面卡顿”的来源
• 插件加载边界:Runtime 通过注册表/manifest 动态加载工具(README 明确提到动态加载插件)
画图规范(让图可读、可审阅、可落地)
• 每个框:名称 + 职责一句话 + 关键数据/接口(例如 History Service: store reversible operations)
• 箭头:写清楚协议/方式(如 “in-process call / event bus / filesystem API / HTTPS”——如果未知就写 “API call”)
• 数据:用小标签标出核心数据结构
• 预览计划(Preview Plan)
• 操作历史(Operation Log)
• 设置(Settings)
• 更新清单(Manifest)/安装包(Package)
颜色/形状建议(强制区分类型)
• 蓝色:UI 层
• 绿色:核心运行时/编排层
• 橙色:本地服务(FS/设置/历史/报告)
• 紫色:工具插件
• 灰色:外部系统(OS、更新服务、认证服务)
Component 图(1~2 张):
• 平台层组件(FS/History/Report/Settings/i18n/Theme/Notification/WindowState/TaskManager)
• 插件层组件(四个工具 + Tool Plugin Interface)
Sequence 图(至少 2 张):
• 文件整理专家:预览→执行→报告
• 自动更新:检查→下载→校验→备份→安装→回滚
(可选再加:撤销流程、空目录清理删除策略)
你现在缺的关键信息(为了把图从“合理”变成“精确”)
如果你能从源码/构建文件补充以下内容,图的准确度会显著提升:
• 技术栈:Electron/Tauri/Flutter/.NET/Qt?是否多进程(UI/后台)?
• 插件机制:动态加载是通过脚本、动态库、还是编译期模块注册?
• 设置与历史的存储:本地文件(JSON/SQLite)还是系统注册表/Keychain?
• 自动更新实现:自研 updater 还是框架自带(如 Squirrel、Sparkle、Tauri updater)?
• 认证:纯本地还是远程账号体系?token 生命周期与存储方式?
如果你把真实源码目录结构(例如 src/, app/, packages/)补上,我可以把上面的“抽象容器/组件”进一步落到具体模块名、入口文件、依赖方向,并给出更贴近实现的 C4 Component 图拆分建议。