Skip to content

PLAN.md

Latest commit

 

History

History
399 lines (278 loc) · 45.7 KB

PLAN.md

File metadata and controls

399 lines (278 loc) · 45.7 KB
Raw

the-boxes · 开发与易用性测试计划

版本 v0.2.37 · 2026-09-20 · 本文是活文档，每个里程碑结束时回顾更新，变更见文末【变更日志】

1. 产品定义

一句话：本地优先的纯文本 todo 桌面应用——类 Things 的易用界面，数据是自己的 Markdown 文件，WebDAV / GitHub Private 备份。

核心概念

概念 定义
todo 最小单元，三种状态（见下表）
inbox 按"提出日期"组织的 todo 流：哪天想到的就落在哪天的文件里
任务 task 一组相关 todo + 一个整体目标，一任务一文件；比清单重、比项目轻

状态语义（三态；v2.0 起定，v1.x 的 [>]/[<] 已删）

状态 名称 语义 进入今日聚合的条件†
[ ] 待办 提出后未处理 所在文件为今日文件
[/] 进行中 正在做 所在文件为今日文件
[x] 完成 已完成，可附 @done:日期 不进入

† 今日聚合界面暂未实现——v2.1 起默认视图为平铺（见下节与 SPEC §2），语义保留备用。

迁移（把 todo 挪到另一天）= 拖到左侧 mini 日历的某一天：整行原样移动到该日文件，源文件删行。详见 SPEC §1。

设计原则

  1. 数据即文件：全部数据是人能直接读的 Markdown，无数据库。界面坏了数据不丢，Obsidian / VS Code / cat 都能打开。
  2. 文件记录事实，视图负责呈现：文件记录"何时提出、当前状态"；"今天该做什么"由视图聚合计算，不靠手动搬文件。
  3. 界面优先，文件为本：类 Things 的图形界面是产品本体；Markdown 文件是唯一数据源，界面只是它的视图与编辑器——外部改动，界面即刷新。CLI 降为辅助（脚本、快捷录入），不是 MVP 门槛。
  4. 自己即第一个用户：每个里程碑的产物必须能管理每天的真实 todo，用不上就不算完成。

非目标（v0.x 明确不做）

提醒/推送通知、日历视图、多人协作、AI 功能。移动端为远期愿景（Tauri 2 支持 iOS），v0.x 不做。重新评估时点：v0.1.0 发布后。

2. 总体方法：测试驱动的里程碑循环

每个里程碑都重复同一节奏：

明确本阶段范围 → 最小实现 → 真实使用一周 → 记 friction log → 周回顾
        ↑                                                     │
        └──────────  修复"致命"级摩擦后重跑一周  ←──────────────┘

四条铁律：

  1. 先人肉后代码：新概念先手工用纯文件操作验证，痛了才写代码（M0 已缩短为 48h 格式验证，语义已定）。
  2. 不达标不加功能：每个里程碑有可量化的毕业标准，未达标只修不加。
  3. 痛点只记真实发生的：friction log 只在真实使用中记录，禁止想象需求。
  4. 先日用后打磨：易用性优先于动效与美化——类 Things 的"轻快"来自交互路径短，不是动画。

3. 数据格式（摘要）

细节以 SPEC.md 为准（v2.5），要点：

~/the-boxes/                   # 数据目录（独立于代码仓库）
├── inbox/
│   └── 2026-09-19.md          # 一天一文件：当天提出的所有 todo
├── tasks/
│   └── 2026-09/
│       └── 装修.md            # 一任务一文件：目标 + todos（按提出月份嵌套，防重名）
├── archive/                   # 完结任务归档
├── trash/                     # 垃圾箱：拖进垃圾箱的 todo 整行移来（软删除，可手改找回）
├── .boxes-onboarding.json     # 上手示例标记（应用自管，空目录首开铺示例用）
└── .boxes.yml                 # 配置（M3 起：备份目标等）

# 2026-09-19

- [ ] 回复 Alice 的邮件 ^k3f9
- [/] 写 the-boxes 的 SPEC ^a02x
- [x] 晨跑 30 分钟 @done:2026-09-19 ^b7q1
- [ ] 买生日礼物 @2026-09-22 ^d4n7
- [ ] 挑瓷砖 +装修 ^e5p8          # 遗留：归属现由所在文件决定，新界面不再写 +任务

4. 里程碑

M0 · 规范冻结 + 脚手架（2–3 天）

范围：

  • 决策落定（§7 已全部完成），冻结 SPEC.md v1.0 ✅
  • 建立 docs/friction-log.md ✅
  • 初始化数据目录 ~/the-boxes/
  • 前端脚手架：Vite + React + TS，本地文件服务可跑通"读一个文件渲染列表"

可选 48h 手用：直接手写 markdown 管理真实 todo，验证格式手感（v1.x 曾验证 [>] 滚动手感，该状态已随 v2.0 移除）。

毕业标准：

  • SPEC v1.0 冻结（含今日视图聚合规则）
  • 数据目录与脚手架就绪，pnpm dev 能跑（2026-09-19 验证：API 与界面渲染通过）
  • 若做手用：无"致命"级格式问题

M1 · MVP：可日用的界面（2–3 周）

技术：React + TS（Vite）。开发期跑浏览器（本地文件服务提供 API）；毕业前用 Tauri 打包成桌面 App，同一套 API 换 Rust 实现。

范围——只做 inbox 日用流：

  • 平铺视图（默认）：全部 todo 平铺（inbox 日期倒序在前，任务按提出日倒序在后），按来源文件分组、组头显示文件名称（日期 / 任务名 + 提出月份）；回平铺走右上角 home 图标，或再按一次已选中的日期/任务卡片——取代原「今日视图」聚合（SPEC §2 语义保留）
  • 筛选：点 mini 日历某天 → 该日 todo；点任务卡片 → 任务详情（目标、状态、提出日 + 该任务 todos 的三态切换与拖拽排序，原属 M2 已提前实现）；再按一次选中项取消筛选
  • mini 日历：左上月历（周一开头），有记录的日期标圆点，点击某天右侧显示该日 todo（文件不存在也可点，drop 时才创建文件）；todo 拖到某天上即迁移（平铺视图同样可迁）
  • 添加：主区顶部输入框回车即添加；敲 @ 唤起文件下拉（列已有任务 + 日期文件，可就地「创建任务」），选中把新行路由到该文件——归属由所在文件决定，正文不再写 +任务/@日期 token
  • 状态切换：由起止时间派生（点 checkbox 展开日期条：开始/完成 +「标为完成(今天)」），不再"点一下盲切三态"；快捷键待 M5
  • 行内编辑：三入口分治——双击文字就地改名（沿用显示样式）；点 checkbox 出日期条（开始/完成 + 快捷完成，状态只读派生）；换所在文件只能拖（拖到日历某天=移那天、拖到任务卡片=移进该任务，任意来源互通，id 保留撞车换新）
  • 删除（软删）与恢复：拖动 todo 时底部浮出垃圾箱落点，拖进去 = 整行原样移进 trash/<删除日>.md（不扫描、从视图消失）；不弹确认。查看/清空：非空时左栏任务卡片最下方出现「垃圾箱」条目，点开进视图列出被删项 +「清空垃圾箱」彻底删除 trash/。恢复 = 把垃圾箱里的行拖到日历某天或任务卡片（落点即去处，不记原处）
  • 文件监听：外部改动自动刷新 ✅ 已实现（开发期 fs.watch 递归监听数据目录 + SSE /api/events，150ms 去抖广播；界面重读列表与当前视图，正在编辑某行时不打断。打包 Tauri 时换 Rust 侧原生监听，接口签名不变）
  • 上手示例：空目录首次打开自动铺一份自解释示例（今日 inbox + 示例任务，覆盖三态/起止日期/双击编辑/拖拽迁移/任务归属），顶部横幅「清空示例」一键清掉、清空后不再自动铺；已有数据的目录不受影响 ✅

明确不做：备份（M3）、主题与动效、全局快捷键（M5）；任务视图的其余部分（+任务名 归属显示、归档）仍留在 M2（今日聚合已被平铺取代，不再列入范围）。

易用性测试：

  • dogfood：连续 7 天所有 todo 只进 the-boxes
  • 计时：随机记录 10 次"唤起到回车"耗时，取中位数
  • 记忆测试：一周后不看提示使用；记不住的快捷键进 friction log
  • 破坏测试：外部手改文件、同文件多窗口编辑，观察界面表现

毕业标准：

  • 添加 todo 中位耗时 ≤ 5 秒，状态切换 ≤ 2 秒
  • 外部改动 → 界面刷新 ≤ 2 秒
  • 连续 7 天使用无中断，没有一天退回旧工具
  • 打包出可双击运行的桌面 App
  • friction log 无"致命"级未修复项

M2 · 任务（1–2 周）

范围：

  • 任务列表 + 任务详情（目标、进度）✅ 已于 M1 提前实现（读取 tasks/，卡片 + 详情，含三态切换与拖拽排序）
  • 在界面里创建任务 / 向任务添加 todo ✅ 已于 M1 提前实现（添加框 @ 路由到任务文件，无匹配「创建任务」按 SPEC §5 建骨架；归属 = 所在文件，不写行内 token）
  • 归档：完结任务移动文件至 archive/（内容不变）——尚未实现
  • 进行中任务的 todos 进入今日聚合（今日聚合界面本身尚未实现，见 §2 保留语义）

易用性测试：

  • 选 2 个真实任务全程管理：①"the-boxes 开发"本身 ②一个生活任务
  • 每周末记录：本周主动打开任务视图几次？不看文件说得出每个进行中任务的目标吗？

毕业标准：

  • 2 个真实任务，其一完整走完 立项→拆解→执行→归档
  • inbox 与任务双视图无"同一 todo 看两遍"的混乱感
  • 不看文件能说出每个进行中任务的目标

M3 · 备份（约 1 周）

范围：

  • GitHub Private：数据目录即 git 仓库，界面"同步"按钮 = add + commit + push
  • WebDAV：打包 zip 上传，保留最近 N 份
  • 冲突策略 v1：文件级"最后写入优先" + 明确警告，不做三方合并
  • 恢复功能

易用性测试（重点不是功能，是"安全感"）：

  • 灾难演练：删掉数据目录 → 恢复，计时并逐项核对
  • 双机（工作机 + 个人机）同日使用一天，观察冲突频率与体验
  • 实测至少 2 家 WebDAV 服务（如坚果云 + Nextcloud）

毕业标准：

  • 恢复演练 ≤ 5 分钟，数据零丢失
  • 连续 7 天自动备份，无一次手动干预
  • 双机冲突场景有明确可理解的处理结果（哪怕粗糙）

M4 · 属性（待排期）

范围：为每个 todo 增加属性，用于筛选与排序——先只记录，实现细节日后细化：

  • 所需时间：<2min / <1hr / 一整天
  • 所需环境：手机 / 笔记本 / 台式机 / 特定地点（如会议室）
  • 领域：自定义分类
  • # 标签显示（2026-09-19 记入）：当前界面用 @ 唤起文件路由，行内不再存 +任务 token；用户希望"类似的行内显示改用 # 标签"。归入本里程碑与属性显示一起定：任务/属性如何在行内以 # 呈现、@ 与 # 的分工、是否引入 #属性 语法——届时连同数据格式一并细化。

说明：本里程碑当前仅登记范围，测试方案、毕业标准、数据格式待排期时补齐。

M5 · 类 Things 打磨与发布 v1.0.0（持续）

范围：

  • 类 Things 体验：全局快捷键快速录入、纯键盘流、深浅色、轻量动效、菜单栏/Dock 图标
  • 只修 friction log 中排名前 5 的痛点
  • 打 tag v1.0.0（整合 M1–M4 全部能力 + 打磨），补 README 与一键安装（DMG / brew）；上线后修复走 v1.0.x
  • 邀请 3–5 位朋友使用两周

他人测试脚本（think-aloud，全程出声思考，限时 10 分钟）：

  1. 安装（计时，不提供帮助）
  2. 添加一条 todo
  3. 完成、进行中、迁移各一条
  4. 建立任务并加 2 条 todo
  5. 模拟误删文件后从备份恢复

毕业标准：

  • 5 项任务无提示完成率 ≥ 80%
  • 安装 ≤ 3 分钟，非程序员可完成
  • 收集 ≥ 3 份完整反馈，形成 v1.x backlog

5. 易用性测试工具箱

Friction Log（核心资产，贯穿全程）

位置 docs/friction-log.md，按月一节，格式：

- 2026-09-20 | 排期时忘了日期格式 | 卡了 30s | 情绪 2/5 | 希望有日期选择器

规则：只记真实发生的事；单条记录 ≤ 30 秒——记录摩擦的工具不能自己成为摩擦。

北极星指标

指标 目标 自何时测
添加一条 todo（唤起→确认） ≤ 5s M1
切换状态 ≤ 2s M1
外部编辑文件→界面刷新 ≤ 2s M1
连续使用天数 ≥ 7 天/里程碑 M1
无提示完成率（他人） ≥ 80% M5

周回顾（每周日 15 分钟，写进日历）

  1. 本周 friction 分级：致命 / 烦人 / 可忍
  2. 下周只修"致命"，其余进 backlog
  3. 对照毕业标准打勾，决定毕业或续期
  4. 更新本计划与变更日志

6. 风险清单

风险 缓解
五状态语义记不住 界面上状态即按钮/快捷键，不要求记语法；速查可呼出
手写与界面混用导致格式漂移 解析容错 + 未知行原样保留 + doctor 体检命令
Tauri/Rust 工具链拖慢 M1 M1 全程浏览器开发，打包推迟到毕业前，API 层预先隔离
多机并发编辑冲突 v1 最后写入优先 + 警告；M3 灾难演练覆盖
WebDAV 各家实现差异大 M3 至少实测 2 家
"类Things"滑向过度打磨动效 铁律 4：先日用后打磨；动效统一进 M5
计划宏大但没人用 铁律 2 不达标不加功能；每阶段强制 dogfood

7. 决策记录与开放问题

已决策（2026-09-19）

# 问题 决策
Q1 [>] [<] 语义 BuJo 式：[>] 无定期顺延（往后滚）/ [<] 排期到具体日期（v2.0 撤销：两态删除，迁移改为拖拽整行移动）
Q2 技术路线 React + TS（Vite）界面，Tauri 打包桌面 App；M1 浏览器开发
Q3 顺延/排期后行放哪 行不移动，留在提出日文件，视图聚合（v2.0 撤销：迁移 = 整行移动到目标日文件）
Q4 todo 稳定 ID 短哈希（行尾 ^a3f9）
Q5 Obsidian 兼容 读取不破坏（未知行原样保留），写入只用自有子集
Q6 任务文件形态 一任务一文件 tasks/<slug>.md

开放问题

# 问题 当前假设
Q7 昨日未处理的 [ ] 是否自动滚入今日 不自动：显式迁移（拖拽）才移动（BuJo 纪律，日回顾成为核心动作）；M1 验证，必要时加设置
Q8 界面信息架构：单栏列表 vs 三栏（导航/列表/详情） M1 第一周出线框时定，参考 Things（现状：左侧 mini 日历 + 任务卡片，右侧 todo 列表）

8. 仓库结构演进

the-boxes/                # 开源代码仓库
├── PLAN.md               # 本文档
├── SPEC.md               # 数据格式规范（已冻结）
├── docs/friction-log.md  # 摩擦日志
├── docs/style-guide.md   # 界面风格规则（配色/留白/字体/动效 token）
├── src/                  # M1 起：React + TS 界面
└── src-tauri/            # M1 末：Tauri 壳

注意：数据目录（默认 ~/the-boxes）独立于代码仓库；M3 备份到 GitHub Private 的是数据仓库，两者不混。

9. 项目版本迭代规则

the-boxes 采用语义化版本（SemVer）：主版本.次版本.补丁，当前为 v0.1.0（M1 已开线，pre-1.0）。这是整个项目的唯一正式版本号，与文档版本、里程碑编号相互独立。

版本号含义

段 含义 何时 +1 1.0 前（当前）处理
主版本 破坏性/不向后兼容 数据格式或核心命令不兼容既有数据 保持 0
次版本 新增功能，向后兼容 里程碑核心功能首次可日用（开启该里程碑的版本线） 0.1 / 0.2 / 0.3 / 0.4 依里程碑推进
补丁 修复、打磨 版本线内的缺陷修复与打磨，一个里程碑内可多次 相应递增

里程碑 ↔ 版本映射

里程碑 = 一条次版本线：核心功能可日用 → 打 vX.Y.0 开线；线内修复/打磨 → 补丁递增；毕业标准全勾 → 关线，下一里程碑开自己的线。

里程碑 产出 对应版本线
M0 规范 + 脚手架 v0.0.x（当前 0.0.1）
M1 inbox 日用界面 v0.1.x：首个日用构建打 v0.1.0，修复递增至毕业
M2 任务 v0.2.x：同上，从 v0.2.0 起
M3 备份 v0.3.x：同上
M4 属性 v0.4.x：同上
M5 打磨 + 发布 v1.0.0 整合发布（M1–M4 全部能力 + 打磨），上线后修复走 v1.0.x

M5 特殊：打磨工作在 0.4.x 线上进行，发布即 v1.0.0——不再走"0.5 线"，发布而非内测，语义干净，用户一眼看懂可用性。v1.0.x 是长期维护线，不设关闭时点：上线后的真实使用即是考验，issue 以补丁修复。若某里程碑出现回归，在当线内以补丁修复，不回退版本线。

发布流程（三个节点）

开线（里程碑核心功能首次可日用）：

  1. 更新 package.json version 为 vX.Y.0
  2. 打 git tag：git tag vX.Y.0 && git push --tags
  3. PLAN.md 变更日志追加一条

线内（修复与打磨）：

  • 每次修复/打磨递增补丁（本地开发可只在 package.json 递增，不必逐一打 tag）

关线（毕业标准全勾）：

  1. 周回顾确认该版本线毕业
  2. 开启下一里程碑（其首个日用构建再打下一个 .0）

版本与里程碑的关系（避免混淆）

  • 里程碑（M0–M5）= 规划/进度单位，回答"我在计划第几步"
  • 语义化版本（vX.Y.z）= 交付/发布单位，回答"我发出去的东西是第几版"
  • 文档版本 = SPEC/PLAN 各自的修订级，只算编辑次数，不算项目版本
  • 一次迭代 = 里程碑开线（可日用）→ 线内补丁修复 → 毕业关线；版本号跟着线走

当前状态

  • 项目版本：v0.1.0（M1 已开线：inbox 日用界面范围全部实现、可日用 → bump package.json 0.1.0 + 本地 git tag v0.1.0（未 push）。尚未毕业（未关线）：待连续 7 天 dogfood、四项北极星指标实测、friction log 无致命项、Tauri 打包成可双击桌面 App；这些修复走 0.1.1 / 0.1.2 …，毕业标准全勾才关线、M2 另开 v0.2.x）
  • package.json 中 "version": "0.1.0" 即当前项目版本号，规则以此章为准

变更日志

  • 2026-09-20 v0.2.37：M1 开线 v0.1.0。M1「inbox 日用界面」范围已全部实现且可日用（平铺/筛选/mini 日历/添加/行内编辑/日期条状态/软删+查看+拖出恢复+清空/文件监听/上手示例，build+端点 curl 全过）→ 按 §9「核心功能可日用即开线」：package.json 0.0.1→0.1.0、本地 git tag v0.1.0（不 push）、README/§9 版本行同步。毕业（关线）仍未达：待 7 天 dogfood、四项北极星指标实测、friction log 无致命、Tauri 打包桌面 App——修复走 0.1.x。§9「当前状态」相应改写。

  • 2026-09-20 v0.2.36：dogfood 前对齐审计——删死代码 + 统一 +任务 文档（不改交互/格式）。发现并清理：①死代码链：交互改版后 UI 不再调 setState/taskSetState/migrate/ensureIds/taskEnsureIds，删其 api 方法、/state·/migrate·/ensure-ids 5 条路由、store 里 setTodoStateInFile/setState/migrateTodo/ensureIds 及 vite 的 dayExistsFor（ensureIdsInFile 内部仍用、保留）；②文档漂移：SPEC §4/§2、README、PLAN §3 把 +任务 当"归属任务/任务视图聚合"（既不属实、代码也未实现聚合）→ 统一改述为"遗留 token、归属=所在文件、任务视图不聚合 inbox 的 +任务"，@start/@done 写入时机改"日期条/标为完成"。SPEC v2.4→v2.5（纯澄清）。保留端点 addTodo/addTaskTodo/editTodo/reorder/trash/onboarding 全部 curl 复测通过。另修一处顺带发现的既存隐患：reorderInFile 在 id 集合对不上时会 ensureIds 后无限递归（畸形/并发过期的 order 触发）→ 改为至多重试一次、仍不符则报错，实测畸形请求 0.02s 返回 400、正常整列表 200。

  • 2026-09-20 v0.2.35：垃圾箱入口图标与文字垂直对齐（纯视觉，配合 style-guide v0.3.31）。.task-top 的 baseline 让 SVG 图标与文字错位 → 垃圾箱行改 align-items:center。数据格式无变化。

  • 2026-09-20 v0.2.34：垃圾箱入口移到左栏任务卡片底部（配合 style-guide v0.3.30）。修改建议：入口是"进容器"的导航，与任务/日期同属左栏才顺，右上角只留 home。实施方案：入口从 header 图标按钮改为 .sidebar-trash 里一枚 .task-card.trash-entry（图标+名称+计数、is-selected 表当前视图、任务空时仍显）；header 恢复只留 home。纯布局，数据格式无变化。

  • 2026-09-20 v0.2.33：垃圾箱行拖出即恢复（配合 style-guide v0.3.29）。修改建议：恢复不必"记原处"——把垃圾箱里的行拖到日历/任务卡片即恢复到那。实施方案：TodoSourceRef 加 trash 来源、fileFor/sameSrc/updateTodo 移动分支支持从 trash 移到 day/task（写目标在前再删源，防丢）；前端 AnySource 贯通 editTodo，垃圾箱视图行 draggable（拖时不弹底部删除箱、dropToTrash 拒绝 trash 自扔）、.trash-hint 提示；M1「删除」项补「恢复=拖出」。数据格式无变化。

  • 2026-09-20 v0.2.32：垃圾箱查看/清空入口（配合 style-guide v0.3.28）。修改建议：软删除后只能开文件看 trash/，缺应用内入口。实施方案：①store.listTrash/emptyTrash + GET /api/trash/POST /api/trash/empty + api getTrash/emptyTrash；②App 新增 trash 视图（View 加一支），非空时右上角 home 左侧出垃圾桶图标按钮（计数、当前视图高亮），点开列出只读的 .todo 行（——删除于 <date>）+「清空垃圾箱」；③启动/SSE/删除后都刷新 trash 计数。恢复（放回原文件）需记来源，未实现，记为待办。数据格式无变化（trash/ 已于 v2.4 登记）。

  • 2026-09-20 v0.2.31：垃圾箱落点改圆形纯图标（去文案，配合 style-guide v0.3.27）。.trash-drop 从"图标 + '拖到此处删除…'文字"的横向浮层改为 56px 圆形图标按钮（只 TrashIcon 26px + 圈），读屏保留 aria-label；.is-over 由文字变 --accent 改图标变 --accent。纯视觉，数据格式无变化。

  • 2026-09-20 v0.2.30：垃圾箱软删除（拖入 = 移进 trash/）。修改建议：需要删 todo，但"数据即文件"下直接抹行不可恢复。实施方案：①store.trashTodo——把整行原样移入 trash/<删除日>.md（不存在则建含标题），先写 trash、再从源删行（防丢）；②POST /api/todos/trash + api trashTodo；③App 拖动中（dragging）于底部浮出垃圾箱落点（TrashIcon + 文案 + is-over 高亮），松手即删、不弹确认；④trash/ 与 archive/ 一样不被扫描 → 从各视图消失但文件仍在，可手改找回。SPEC §3 加 trash/ 目录 + §1 状态措辞改为"由起止时间决定"（顺带修「点击循环」旧述与现交互不符）→ SPEC v2.4；style-guide 新增 §5.9 垃圾箱落点（v0.3.26）；README/PLAN §3 同步。M1 范围加「删除」项。

  • 2026-09-20 v0.2.29：修双击改名时描述位移（纯视觉，配合 style-guide v0.3.25）。.todo-name-input 从 flex:1（基线/行高与块级标题不一致）改 display:block + width:100% + line-height:inherit，落点与 .todo-title 一致、进入编辑不再跳字。数据格式无变化。

  • 2026-09-20 v0.2.28：改名框去编辑态外显、日期输入去外框（纯视觉，配合 style-guide v0.3.24）。修改建议：双击改名时输入框带 surface+border-control+focus 环，与原显示行不像同一物；日期条里开始/完成外框偏重。实施方案：.todo-name-input → font/color:inherit + 透明无框无环；.edit-field input 去 border/背景/圆角、focus 仅去 outline（.date-strip 容器与 .btn 不动）。数据格式无变化。

  • 2026-09-20 v0.2.27：编辑器拆成三入口（改名双击 / 日期点 checkbox / 换文件只拖）（配合 style-guide v0.3.23）。修改建议：整行大表单太重、点 checkbox 盲切三态会凭空造今天日期。实施方案：①删 TodoEditor 大表单 + 编辑器里的所在文件字段 + 只读状态块 + cycleState/nextState/STATE_CYCLE；②改名 = 双击 .todo-title→就地 .todo-name-input（沿用显示样式，Enter/失焦提交、Esc 取消、编辑期禁拖）；③点 checkbox = 展开行下 .date-strip（开始/完成 + × +「标为完成(今天)」，状态仍由日期派生、只读反映）；④换文件 = 拖到日历格或任务卡片（moveTo→updateTodo target，任意来源互通）；⑤全走即时写盘、无保存按钮。数据格式无变化；M1「状态切换 / 行内编辑」措辞同步。

  • 2026-09-20 v0.2.26：编辑器第二/三行右对齐、所在文件框随内容宽（纯界面，配合 style-guide v0.3.22）。修改建议：开始/完成/状态与所在文件靠左、所在文件框通栏过大。实施方案：.edit-row justify-content:flex-end；.edit-loc-field 右对齐 + .edit-loc field-sizing:content（min 8ch/max 26ch、不通栏）；描述文本框仍通栏。数据格式无变化。

  • 2026-09-20 v0.2.25：编辑器占满宽度修复 + 状态改只读（纯界面，配合 style-guide v0.3.21）。修改建议：①编辑行右侧一大块留白——.todo-editing 单类被更靠后的 .todo{display:flex} 盖掉，编辑内容缩成内容宽；②状态那块不需要能点。实施方案：①.todo-editing→li.todo.todo-editing（含 ::before/:hover）抬特异度强制 block/无 hover 底色/去分隔线，编辑器随之占满；②.status-btn→静态 .edit-status（随起止时间派生的只读展示），删 cycleStatus。数据格式无变化；M1 范围「行内编辑」措辞同步。

  • 2026-09-20 v0.2.24：编辑器三行 + 状态循环按钮（纯界面，配合 style-guide v0.3.20）。修改建议：用户要 【文本框】/ 开始 完成 ✅状态 / 所在文件 三段，并能在编辑器里直接切状态。实施方案：①第二行改为 开始 + 完成 + .status-btn（盒图标+中文名，点按 待办→进行中→完成→待办 循环，底层只写开始/完成日期：进行中补今天、完成补今天保留开始、回待办清空——日期仍是唯一事实源，与只读派生不冲突）；②所在文件挪到第三行独占（.edit-loc-field，输入框 flex:1）；③操作行去掉只读盒子/提示、按钮右对齐；删 .edit-state/.edit-hint。数据格式无变化；M1 范围「行内编辑」措辞同步。

  • 2026-09-20 v0.2.23：编辑器改两行——描述多行文本框 + 所在文件/开始/完成第二行（纯界面，配合 style-guide v0.3.19）。修改建议：上一版把状态盒+描述+所在文件挤一行、时间再占一行，描述只能单行、不便改长文。实施方案：①第一行 .edit-area = <textarea>（通栏、可 resize、Enter 换行 / ⌘Ctrl+Enter 保存，换行保存时后端并成空格 → todo 仍一行）；②第二行 .edit-row：所在文件（datalist 单选，width 14em）+ 开始 + 完成 三控件并排；③派生态盒子移到操作行 .edit-state；删 .edit-main/.edit-desc/.edit-fields。数据格式无变化；M1 范围「行内编辑」措辞同步。

  • 2026-09-20 v0.2.22：日期注记换行策略——标题首行、注记次行（纯排版，配合 style-guide v0.3.18）。修改建议：——始于…🎉 注记较长，行内拼在标题后需要换行时会和标题尾巴挤一起/让出首行。实施方案：标题 .todo-title 与注记 .done-note 各 display:block（注记 nowrap 整块不拆断、去 margin-left、margin-top:1px；窄屏放开 normal）；App 里标题文字包一层 .todo-title、注记去前导空格。仍是无胶囊行内灰字，不改数据格式。

  • 2026-09-20 v0.2.21：上手示例（空目录首开自动铺，一键清空）。修改建议：新人 clone 后 pnpm dev 打开是空屏 + 空态，得照 README 手写 Markdown 才看到东西，违背"打开即用"。实施方案：①store 加 seedOnboardingIfEmpty（有 marker 或有真实数据则跳过；空则写今日 inbox + tasks/当月/示例任务.md，ensureIdsInFile 给示例行补 id 使其可点/编辑/拖），clearOnboarding/getOnboarding + 数据目录根标记 .boxes-onboarding.json（记铺过哪些文件、清空后置 files:[] 不再自动铺）；②开发服务器 configureServer 启动时 await 播种（避开前端时序竞态；Tauri 侧改由 Rust 启动做）；③GET /api/onboarding + POST /api/onboarding/clear；④App 顶部横幅「清空示例」（style-guide §5.8 v0.3.17），清空后重载列表/视图。SPEC §3 补 .boxes-onboarding.json 为工具元数据（扫描忽略）→ SPEC v2.3。数据行格式/任务格式不变；M1 范围补「上手示例」项。

  • 2026-09-19 v0.2.20：修拖拽游标的误导「+」角标（复制→移动）。修改建议：行 onDragStart/onDragOver 未声明动作，浏览器默认在游标旁画 +（复制语义），但我们做的是移动/重排——角标在骗人；日历迁移处已写 dropEffect='move' 所以是对的箭头。实施方案：行的 dragstart 设 effectAllowed='move'、dragover 在 preventDefault 后设 dropEffect='move'，与迁移手感统一。纯交互反馈，无视觉 token、数据格式无变化。

  • 2026-09-19 v0.2.19：主页平铺视图支持组内拖拽重排（修正「平铺不重排」的旧限制）。修改建议：重排只在单日/单任务视图可用，主页里拖动排序被 view.kind==='all' 直接挡回；但主页按来源分组后，同组=同一文件，组内排序完全有意义，跨组才无全序。实施方案：onDrop 改为按 sameSource 分组作用域——取该来源在当前列表里的下标子序列，只在组内做移动并提交 reorder/taskReorder，落点后 refreshView 按盘上顺序重取；跨来源落点忽略。单文件视图行为不变（整列表即一组）。纯交互，数据格式无变化。

  • 2026-09-19 v0.2.18：M1 最后一项「文件监听自动刷新」落地 + 记录版本决策。修改建议：界面只在自己发起写操作后刷新，用别的编辑器改 Markdown 得手动刷，违背设计原则 3「外部改动，界面即刷新」与北极星「外部改动→刷新 ≤2s」。实施方案：①开发期后端 boxesApi 起 fs.watch(dataDir, {recursive})，150ms 去抖后向所有 SSE 客户端广播 changed，目录不存在先 mkdir、不支持监听则静默降级（仍可手动刷新），httpServer close 时关 watcher/清连接；②GET /api/events SSE；③api subscribe(cb)（EventSource，自带重连），App 订阅一次、靠 liveRef 读最新 refreshView/编辑态，重读日历圆点 + 任务列表 + 当前视图，正在编辑某行时不刷新以免冲掉未保存编辑器。至此 M1 范围全部实现。版本决策：用户确认暂不开线——保持 package.json 0.0.1、不打 v0.1.0，攒到接近 M1 毕业（Tauri 打包 + 连续 7 天 dogfood + 北极星指标实测 + friction log 无致命项）再一次性开 v0.1.x 线；§9「当前状态」相应改写。数据格式无变化。

  • 2026-09-19 v0.2.17：编辑器收成一行（纯界面，配合 style-guide v0.3.16）。修改建议：上一版编辑器把"所在文件"做成独立的"胶囊 + @ 浮层"一行、派生态盒子又占描述左宽，割裂且占高。用户要状态在描述行开头、所在文件是描述后面的下拉单选且能输入创建。实施方案：①.edit-main 一行三段——派生态 box（开头）+ 描述 .edit-desc（通栏 flex:1）+ 所在文件 .edit-loc（<input list>+<datalist> 可输入下拉单选，尾端带 --divider 分隔）；②位置解析 resolveLocTarget：值=当前文件 token，清空→当日 / 输入未知名→当前月新建任务 / 命中 slug 名或 ISO 日期→路由该文件，保存仍走 updateTodo（同来源原地、异来源整行移动，id 保留撞车换新）；③起止时间行去掉盒子；删 .loc-bar/位置胶囊/@ 菜单。数据格式无变化；M1 范围「行内编辑」措辞同步。M1 剩余仍是文件监听自动刷新。

  • 2026-09-19 v0.2.16：编辑器布局微调（纯界面，配合 style-guide v0.3.15）。修改建议：双击编辑器的描述框被状态预览盒子挤了左宽、位置控件用静态标签且可清空，与「添加 todo」输入框不一致。实施方案：①描述改通栏全宽（复用添加框 .add-line/.add-input），派生态 box 预览移到起止时间行；②位置统一成"前置胶囊常显当前文件 + × 掉当日 + @ 选新文件替换"，保存目标恒为胶囊所指（同来源原地、异来源整行移动），删 .loc-cur/.loc-wrap/.edit-text/.edit-line。数据格式无变化；M1 范围不变，M1 剩余仍是文件监听自动刷新。

  • 2026-09-19 v0.2.15：M1 新增「双击行内编辑」。修改建议：状态只能点 box 单向推进、正文与归属只能改文件——缺一个就地改回/改错的入口。实施方案：①后端 updateTodo + PUT /api/todos/edit（{source,id,text,start,done,target}）——按 ^id 定位行，改正文与 @start/@done（null 清除、缺省不动），状态由时间派生（有 done→done、有 start→doing、皆空→todo），保留行内 legacy +任务/@日期；target 与来源不同即整行移动（先校验并写目标、再删源，宁可重复不丢行；撞 id 换新）；②App 双击行 → TodoEditor 内联表单：描述框、开始/完成 type=date + 清除、@ 位置选择器（复用添加框候选与浮层）、派生态预览、保存/取消，Esc 或失败保留编辑态不吞输入；无 id 的手写行不进入编辑。③样式 style-guide §5.7（v0.3.14），控件全走 token、主按钮 accent 描边非白底。数据格式无破坏变化（仍 SPEC §4/§5）。验证中修掉一处 bug：非法 target 原会先删源再抛错致丢行，已改为写目标在前。M1 范围补「行内编辑」项；M1 剩余仍为文件监听自动刷新。

  • 2026-09-19 v0.2.14：M1 添加框升级为 @ 文件路由，提前吃掉 M2「界面内建任务 / 向任务加 todo」。修改建议：上一版（v0.2.13）的添加只能落当天，把 todo 归进某个任务仍要手写文件；用户定调"归属只由所在文件决定，@ 是唤起/路由到文件的入口，不是往行尾贴显示标记"。实施方案：①后端 addTaskTodo + POST /api/tasks/:month/:slug/todos——往任务文件追加 - [ ] 正文 ^id（不带 +任务/@日期 token），文件缺失按 SPEC §5 建骨架（# 任务：、状态/提出/## todos），month 用当前月；②输入框 @ 弹浮层：空查询列已有任务 + 日期文件，命中 ISO 日期补「用该日期」，无同名任务末位补「创建任务 …」（需显式选中，回车不自动建）；选中记为路由目标（chip 徽章显示、可点清除），提交按 day/task/newTask 三分叉落盘，失败回填不吞输入，成功刷新日历圆点 + 任务列表 + 当前视图；③样式走 style-guide §5.5 浮层（转正）+ §5.6 重写（v0.3.13）。数据格式无破坏性变化：+任务 token 仍在 SPEC §4（存量行按 §7 容错、照常显示），只是新 UI 不再写它；M4 记一条 # 标签显示待办（连同属性一起定，本轮不做）。M1「添加」范围改写，M2「界面内建任务/加 todo」标注已提前实现。

  • 2026-09-19 v0.2.13：M1「添加 todo」界面入口落地（补齐输入框，数据格式无变化）。修改建议：北极星指标「添加一条 todo ≤ 5s」此前无法达成——界面只能读、只能改状态，添加还得开文件手写，是最刺眼的断点。实施方案：①新增 POST /api/days/:date/todos（store addTodo）：落「正在看的那天」文件末尾（平铺视图落今天），文件不存在则建（含标题），从原话里摘出行内 @日期/+任务 归入 SPEC §4 规范顺序，随机 4 位 ^id 避让已有 id，误粘的 @start/@done/^id 丢弃；②主区顶部加单行输入框（仅 all/day 视图，任务视图留待 M2 的界面内建任务）：回车提交、清空草稿，失败回填不吞输入，成功刷新日历圆点与当前视图；③空态文案从「去文件里加一行」改为「上方输入框回车」；④样式按 style-guide 输入框控件规范（v0.3.12 配套，--bg-surface + --border-control + --radius-control + 焦点环，落在 page 上）。SPEC 无变化（仅使用既有行格式）。M1「添加」范围项由「界面入口开发中」转为已实现；M1 剩余：文件监听自动刷新（外部改动 ≤2s）。

  • 2026-09-19 v0.2.12：主区标题改为右上角 home 图标，筛选支持再按一次取消。修改建议：①平铺已是默认视图，常驻标题「接下来干啥？」是它对自己的重复介绍，返回入口收到一个图标即可；②选中态已表明当前位置，再按一次选中项取消筛选是最短返回路径，不必每次把指针移到标题上。实施方案：①M1「平铺视图」条目：顶部标题点击回平铺 → 右上角 home 图标回平铺；「筛选」条目补「再按一次选中项取消筛选」（取消共三条等效路径）；②界面侧删除 .feed-title，主区无常驻顶部元素，任务视图首元素为任务详情头（style-guide v0.3.11 配套）。数据格式无变化。

  • 2026-09-19 v0.2.11：任务按提出月份嵌套 + 平铺改为分组显示（配合 SPEC v2.2）。修改建议：①任务 slug 在扁平 tasks/ 下无法重名（每月的「月度总结」类任务会撞车）——按提出月份嵌套 tasks/YYYY-MM/，重名自然分开；②行尾 @来源 标注与行自身元数据混排、视觉重复——组头直接显示来源文件名称即可，行尾不再标。实施方案：①§3 目录摘要与 M1 范围同步新结构（tasks/2026-09/装修.md）；②M1「平铺视图」条目：行尾标注 → 按来源分组、组头显示文件名称（日期 / 任务名 + 提出月份）；③任务卡片名称旁较淡显示提出月份（界面侧配套，区分跨月重名）；④§3 引用 SPEC 版本号顺手从 v2.0 更新到 v2.2（v2.1 时漏改）。

  • 2026-09-19 v0.2.10：默认视图改为平铺（配合 SPEC v2.1），去掉完成进度显示。修改建议：①「今日视图」只看今日文件，昨日未完成的事默认不可见，回顾成本高；平铺全部 todo + 筛选更直接；②「N/N 完成」进度条与卡片上的进度数字是装饰性信息，用户没要过，砍掉弱信号。实施方案：①M1 范围：「今日视图」→「平铺视图（默认）」（inbox 日期倒序 + 任务提出日倒序，行尾标注来源文件，顶部「接下来干啥？」点击回平铺），原「任务卡片」条目并入「筛选」（点日历/点卡片）；②迁移在平铺视图同样开放（拖 inbox 行到日历）；平铺视图不做行间重排（跨文件无全序意义）；③删主区进度条与卡片进度数字，卡片回到「名称 + 一句话简介」；④§1 状态表「出现在今日视图的条件」列改为「进入今日聚合的条件†」+ 脚注（语义保留、界面未实现）；⑤M1「明确不做」中今日聚合移出 M2 待办。

  • 2026-09-19 v0.2.9：日期侧栏改为 mini 日历 + 任务卡片，任务视图（M2 首项）提前实现。修改建议：纯文字日期列表只能覆盖「已有文件」的日子，「接下来 7 天」预填是为了可点而造的假数据；月历天然表达任意一天且占位更小，腾出的空间正好放任务卡片——M2 的第一项（任务列表 + 详情）顺手落地。实施方案：①M1 范围重写：「日期侧栏」（接下来 7 天 + 更早）→「mini 日历」（周一开头、圆点标记有记录日、点哪天看哪天、拖放即迁移）+「任务卡片」（名称 + 一句话简介 + 进度，点击进详情：目标、状态、提出日、todos 三态与拖拽排序），并注明后者原属 M2；②M1「明确不做」移除任务视图，其余任务能力（+任务名 归属、今日聚合、归档、界面内创建）仍留 M2；③M2 范围首项标注已提前实现，补「界面里创建任务/添加 todo」缺口；④§1 迁移说明与 Q8 现状同步改「mini 日历」表述。

  • 2026-09-19 v0.2.8：迁移方式改为拖拽，[>]/[<] 删除（配合 SPEC v2.0）。修改建议：留痕态不参与任何视图、却衍生顺延/排期两套对称语义与二选一菜单，认知成本高；改为"拖到左侧日期即迁移"后留痕失去必要性。实施方案：①状态语义表缩为三态（§1），迁移 = 整行原样移动（源文件删行、目标日文件追加，身份不变）；②§3 示例与 M0 手用注记去 [>]/[<]；③M1 范围改写：「按日期浏览」→「日期侧栏」（接下来 7 天 + 更早，倒序），「顺延/排期操作」→「拖拽迁移」；④M5 他人测试脚本与 §7 决策记录（Q1/Q3/Q7/Q8）同步标注 v2.0 撤销语义；⑤§3 引用 SPEC v2.0。

  • 2026-09-19 v0.2.7：README 行格式补齐 @start:日期（对齐 SPEC v1.2）。修改建议：README 的行格式与 token 说明停留在 SPEC v1.1，缺 @start，用户按 README 手写文件时不知道该 token 的存在与行为。实施方案：完整格式行加入 [@start:日期]；token 说明补一条（切到 [/] 自动写、完成后保留）；示例的 [/] 行附上 @start:2026-09-19 展示真实用法。

  • 2026-09-19 v0.2.6：同步 README 三处过期内容（跨文档一致性修复）。修改建议：①路线图停留在 PLAN v0.2.2 之前的状态（M4=打磨+v1.0.0），缺 M4·属性与 v0.2.5 的版本线模型；②进度描述仍写"已实现只读界面，写操作开发中"，与实际（状态切换/迁移/拖拽已实现）不符，且引用了不存在的「当前进度」小节；③"可甘用界面"笔误。实施方案：路线图补 M4·属性（v0.4.x）与 M5·打磨发布（v1.0.0），版本列统一为版本线写法；进度描述改为已支持项 + 待开发项清单；笔误改"可日用"；快速开始一节的写操作提示同步改为仅"添加 todo"缺界面入口。

  • 2026-09-19 v0.2.5：§9 版本模型修正为「里程碑 = 一条次版本线」（用户澄清既定意图）。修改建议：原映射表 M0/M4 写作区间而 M1–M3 写作单点，且 tag 绑定"毕业标准全勾"，与"里程碑从 vX.Y.0 开始、修复递增至毕业"的意图不符；M5 段落标题/范围仍留旧值 v0.1.0，与 §9 的 v1.0.0 矛盾。实施方案：①映射表统一为版本线（M1=v0.1.x … M4=v0.4.x），开线时机改为"核心功能首次可日用"；②发布流程拆为开线/线内/关线三节点；③M5 定为 v1.0.0 整合发布，打磨在 0.4.x 线上进行，上线后修复走 v1.0.x 长期维护线；④同步修正 M5 段落三处旧版本引用（标题、tag、backlog）。

  • 2026-09-19 v0.2.4：确立界面风格规则。新增 docs/style-guide.md（配色/留白/字体/易读性/动效设计 token，参考 obsidian-minimal 的设计理念，注明 MIT），并将 src/styles.css 所有硬编码颜色重构为 CSS 变量引用。更新 §8 仓库结构。

  • 2026-09-19 v0.2.3：新增里程碑 M4 · 属性（v0.4.x）——为每个 todo 增加「所需时间（<2min/<1hr/一整天）」「所需环境（手机/笔记本/台式机/特定地点如会议室）」「领域（自定义）」三类属性，用于筛选与排序。当前仅登记范围（测试方案/毕业标准/数据格式待排期补齐）；原 M4「类 Things 打磨与发布」顺延为 M5，版本映射、§5 指标、风险清单、§9 相关引用同步更新。

  • 2026-09-19 v0.2.2：新增「项目版本迭代规则」§9。明确整个项目采用语义化版本 SemVer，当前 v0.0.1；里程碑↔版本映射（M1→v0.1.0 / M2→v0.2.0 / M3→v0.3.0 / M4 直接定为 v1.0.0 正式发布）；发布流程＝毕业标准全勾 → 更新 package.json + 变更日志 → 打 git tag；并区分里程碑（规划单位）/语义化版本（交付单位）/文档版本（修订级）三者。规则落地后与已知里程碑解耦，避免"v0.x 内测"的语义含糊。

  • 2026-09-19 v0.2.1：M0 收尾。①初始化数据目录 ~/the-boxes/（inbox/tasks/archive，含 SPEC 示例数据）；②搭建脚手架：Vite 7 + React 19 + TS，开发期本地文件 API（/api/days，BOXES_DATA_DIR 可覆盖数据目录，为 Tauri 预留接口层），SPEC §4 行解析器，inbox 列表渲染（五状态 box 图标 + 元数据徽章）；③验证通过：tsc --noEmit 零错误，API 与页面渲染（浏览器实测 6 条 todo 全部正确）。

  • 2026-09-19 v0.2：依界面需求（类 Things GUI）重构。①设计原则 3 改为「界面优先，文件为本」，CLI 降为辅助；②MVP（M1）从 CLI 改为 React + TS 可日用界面，浏览器开发、毕业前打包 Tauri，新增"外部改动自动刷新"指标；③M4 聚焦类 Things 打磨（全局快捷键、纯键盘流、动效）；④决策落定 Q1–Q6（BuJo 状态语义 / Tauri 路线 / 行不移动 / 短哈希 ID / 读兼容 / 一任务一文件），新增开放问题 Q7、Q8；⑤同步产出 SPEC.md v1.0 与 friction log 模板。

  • 2026-09-19 v0.1：初版计划。含里程碑 M0–M4（各带毕业标准）、易用性测试工具箱、风险清单、开放问题 Q1–Q6。实现路径：M0 人肉验证格式 → M1 inbox CLI → M2 任务 → M3 备份 → M4 打磨发布 v0.1.0。