157 lines
6.9 KiB
Markdown
157 lines
6.9 KiB
Markdown
# Todo List
|
||
|
||
一个简洁的桌面 Todo 应用——**Markdown 文件是真相之源，软件只是友好的外壳。**
|
||
|
||
任务存在一个普通 `.md` 文件里，任何文本编辑器都能打开、编辑、同步、diff。没有数据库，没有锁，没有私有格式。
|
||
|
||
## 为什么用它
|
||
|
||
- **零锁定** —— `todo.md` 永远可读。删掉应用也不丢任何数据。
|
||
- **极简模型** —— 任务只有四个字段：文本、勾选、⭐ 重要、▶ 当前。没有标签、优先级、截止日期、子步骤。
|
||
- **数据归属明确** —— 勾选 = 移到「已完成」；删除 = 移到「回收站」。一个任务永远只在一个地方。
|
||
- **"当前 / 重要"是视图，不是文件段** —— 任务打上 `[▶]` / `[⭐]` 行内标记后由 UI 聚合呈现，文件里不会出现重复镜像。
|
||
- **永远不让你"丢东西"** —— 没有"清空回收站"按钮，彻底删除只能手动编辑 Markdown。
|
||
|
||
## 快速开始
|
||
|
||
需要 Node.js 18+。
|
||
|
||
```bash
|
||
npm install
|
||
npm start
|
||
```
|
||
|
||
> **路径要求**：项目目录必须放在 **ASCII 路径**下（如 `C:\dev\todo-list`）。路径含中文时 Electron 会因 `require('electron')` 返回路径字符串而启动失败、看不到窗口。临时绕过：在 ASCII 位置建符号链接再启动：
|
||
>
|
||
> ```cmd
|
||
> mklink /D C:\dev\todo-list "D:\data\正在工作\Todo List"
|
||
> cd C:\dev\todo-list && npm start
|
||
> ```
|
||
|
||
数据文件位置：`~/TodoList/todo.md`（可在设置里改；仅允许用户主目录 / 文档 / 下载 / 桌面 / AppData 下的子目录）。
|
||
|
||
## 文件长什么样
|
||
|
||
```markdown
|
||
# 全部任务
|
||
|
||
## 工作
|
||
|
||
- [ ] 完成 Q3 设计文档
|
||
- [ ] [▶] 写季度汇报
|
||
- [ ] [⭐] 给客户回邮件
|
||
|
||
# 已完成任务
|
||
# 回收站
|
||
```
|
||
|
||
四个标记，零元数据：
|
||
|
||
| 写法 | 含义 |
|
||
|---|---|
|
||
| `- [ ]` | 未完成 |
|
||
| `- [✓]` | 已完成 |
|
||
| `[▶]` | 当前任务（出现在「当前任务」视图） |
|
||
| `[⭐]` | 重要任务（出现在「重要任务」视图） |
|
||
| `[原分类：xxx]` | 自动归档归属（仅在「已完成」/「回收站」里出现） |
|
||
|
||
写入器固定输出顺序：`- [✓] [▶] [⭐] [原分类：xxx] 任务文本`。完整示例见 [`data/todo.example.md`](data/todo.example.md)。
|
||
|
||
## 侧边栏
|
||
|
||
侧边栏顶部是 4 个跨子分类聚合的智能视图，下面是用户用 `## 子分类名` 自由组织的子分类（含不可删的「未分类」兜底）：
|
||
|
||
| 视图 | 说明 |
|
||
|---|---|
|
||
| **当前任务** | 所有打了 `[▶]` 的未完成任务 |
|
||
| **重要任务** | 所有打了 `[⭐]` 的未完成任务 |
|
||
| **全部任务** | 聚合显示所有子分类里的未完成任务 |
|
||
| **已完成任务** | 跨分类聚合的已完成任务 |
|
||
|
||
智能视图用 `Alt+1` / `2` / `3` / `4` 切换。
|
||
|
||
## 快捷键
|
||
|
||
| 操作 | 快捷键 |
|
||
|---|---|
|
||
| 添加任务 | `Enter`（在底部输入框） |
|
||
| 勾选 | `Space` |
|
||
| 编辑 | `F2` |
|
||
| 删除（到回收站） | `Delete` |
|
||
| 标重要 / 当前 | `Ctrl/Cmd+I` · `Ctrl/Cmd+T` |
|
||
| 搜索 | `Ctrl/Cmd+F` 或 `/` |
|
||
| 过滤菜单 | `F` |
|
||
| 命令面板 | `Ctrl/Cmd+K` |
|
||
| 新建子分类 | `Ctrl/Cmd+Shift+N` |
|
||
| 设置 | `Ctrl/Cmd+,` |
|
||
| 切换主题 | `Ctrl/Cmd+Shift+T` |
|
||
| 切换智能视图 | `Alt+1` 当前 · `Alt+2` 重要 · `Alt+3` 全部 · `Alt+4` 已完成 |
|
||
| 列表内导航 | `↑` / `↓` · `Home` / `End` · `PageUp` / `PageDown` |
|
||
| 立即重新加载 | `Ctrl/Cmd+R` |
|
||
| 开发者工具 | `F12` |
|
||
|
||
## 四个操作搞定 80% 场景
|
||
|
||
| 想做什么 | 怎么做 |
|
||
|---|---|
|
||
| 添加任务 | 底部输入框打字，回车 |
|
||
| 标"今天要做" | 任务前打 `[▶]` 或按 `Ctrl/Cmd+T` |
|
||
| 标"重要" | 任务前打 `[⭐]` 或按 `Ctrl/Cmd+I` |
|
||
| 完成 / 删除 | 勾选 → 自动到「已完成」；点 × → 自动到「回收站」 |
|
||
|
||
## 命令
|
||
|
||
```bash
|
||
npm start # 启动（推荐，自动修中文乱码）
|
||
npm run start:raw # 直接起 Electron（仅排查启动脚本时用）
|
||
TODO_DEVTOOLS=1 npm start # 启用远程调试端口 9222（外部 DevTools / Playwright 接入）
|
||
npm run check # 跑 47 项自检、约 1200 条断言
|
||
npm run build # 打包当前平台
|
||
npm run build:win # Windows（NSIS .exe）
|
||
npm run build:mac # macOS（.dmg）
|
||
npm run build:linux # Linux（.AppImage）
|
||
```
|
||
|
||
产物输出到 `dist/`。
|
||
|
||
## 功能一览
|
||
|
||
- **智能视图**：当前 / 重要 / 全部 / 已完成（按行内标记跨子分类聚合）
|
||
- **任务分类**：用 `## 子分类名` 自由组织，含「未分类」兜底
|
||
- **过滤 / 排序**：全部 / 当前 / 已完成 / 重要 · 手动 / 字母（全局偏好持久化）
|
||
- **拖拽**：子分类间、任务间、任务到侧边栏（Pointer Events，不依赖 HTML5 drag API）
|
||
- **批量操作**：选择模式多选，一键移动 / 置顶置底 / 标重要当前 / 完成 / 删除
|
||
- **导入**：粘贴大段文本按行解析成任务，支持保留 `- [✓]` 状态
|
||
- **冲突解决**：任务粒度三栏合并（用文件 / 用本地 / 保留两边 / 都不要），附 LCS 行级 diff 预览
|
||
- **搜索**：全局模糊匹配 + `Ctrl/Cmd+K` 命令面板（搜索列表 / 跳转 / 切换主题等）
|
||
- **个性化**：字体大小（小 / 标准 / 大）× 配色风格（靛蓝 / 海洋 / 森林 / 日落 / 玫瑰 / 单色，各含深浅两版）
|
||
- **主题**：深色 / 浅色 / 跟随系统；与配色风格正交
|
||
- **托盘 / 始终置顶 / 单实例锁**：关闭窗口默认隐藏到托盘；同目录同时只允许运行一个实例
|
||
- **6 个插入位置偏好**：新增 / 完成 / 取消完成 / 删除 / 恢复 / 移到分类各自选"前面 / 后面"
|
||
|
||
## 数据安全
|
||
|
||
- **实时同步** —— 每次操作立即落盘（800ms 防抖），状态栏显示「已同步 HH:MM」
|
||
- **外部修改检测** —— `fs.watch` + 250ms `statSync(mtime/size)` 轮询兜底（云盘 / 网络盘 / 非标准保存路径的编辑器也能感知）
|
||
- **冲突合并** —— 磁盘版本与本地版本不一致时弹任务粒度三栏合并对话框
|
||
- **原子写入** —— `tmp + rename` 落盘，永远不会半截
|
||
- **`.bak` 三份轮转** —— 每次保存保留最近 3 份回退点
|
||
- **带标签快照** —— 用户主动丢弃编辑、退出前 flush、reload 前等关键节点生成带时间戳的快照，永不轮转
|
||
- **`.pre-crash.bak` 兜底** —— 退出前 flush 超时（5 秒）自动备份当前内容
|
||
- **每日快照** —— `backup/todo-YYYY-MM-DD.md`，默认开启
|
||
- **数据目录沙箱** —— 所有文件 IO 必须落在数据目录内；自定义目录必须在用户已知根目录下
|
||
- **单文件上限 50 MB** —— 防止异常数据把目录撑爆
|
||
- **彻底删除只能手动编辑文件** —— 刻意的设计
|
||
|
||
## 跨设备同步
|
||
|
||
把 `todo.md` 放在云盘目录（OneDrive / Dropbox / iCloud），或在设置里改数据目录。或用 Git 管理（每个任务一行，diff 干净）。
|
||
|
||
## 开发者
|
||
|
||
关济寰 · [guanjihuan.com/about](https://www.guanjihuan.com/about)
|
||
|
||
## 许可证
|
||
|
||
MIT
|