tianemon/easymint/dev-docs

Dev Docs — 项目文档记录规范

开发期维护项目文档时按本规范执行。极简项目（单文件/无依赖）不建文档体系；有文档体系的项目按本规范执行。

文档分层

docs/需求文档.md          需求（唯一意图真相源）：项目定位、功能清单、范围边界、验收标准
.easymint/todos.json      用户待办（唯一清单源）：想法/计划，UI「待办」面板或 todo_user 工具维护
docs/开发记录.md          导航页（唯一真相源）：头部「当前进度快照」+「开发记录索引」
docs/开发记录/<日期>.md   按日期分文件的进度明细（只增不改，带提交 hash）
CHANGELOG.md              正式发布日志（Keep a Changelog，只记用户可见变更）
docs/技术架构.md          当前架构（随实现更新，保留关键决策与必要历史）

分工：需求文档管「要做什么」，用户待办管「想做还没做的」，导航页管「现在在哪」，明细管「每天发生了什么」，CHANGELOG 管「发布了什么」，技术架构管「系统怎么设计」——各载体不重复记录同一内容。

接手/恢复工作时定向核实：先读开发记录快照定位当前工作，再按任务缺口查相关需求、架构、task.json 或 git log/diff，不盲信 status。资料存在且与本次任务相关时才读；连续执行时沿用仍有效的上下文，不每轮重读整套资料。

docs/需求文档.md（需求文档）

产品需求的唯一意图真相源——「要做什么、为什么做、怎么算做完」，与进度类文档分离：

• 记录内容：
• 项目定位与目标（一句话 + 面向谁）
• 功能清单（按 P0 必需 / P1 核心 / P2 增强 标注优先级）
• 范围边界（明确不做什么，防蔓延）
• 验收标准（Evaluator 对照检查的依据，每条功能对应可验证的完成定义）
• 更新时机：需求变更时先同步需求文档，再拆任务——用户新增/修改需求 → 先更新需求文档反映最新意图 → 再拆 task.json（需求变更不更新文档直接拆任务，会导致 Builder 按过期意图开发）
• 与 task.json 分工：需求文档管「全部意图」，task.json 管「当前批次任务的执行状态」——任务完成后需求文档保留（产品全貌），task.json 是执行快照
• 简单档项目可精简（定位 + 功能清单即可），极简项目不建（见文档分层开头）

.easymint/todos.json（用户待办清单）

用户想法/计划的唯一清单源（跨会话、人机共写）——有想法、发现改进点但不立刻做时记录于此，避免靠记忆或散落对话丢失。UI 入口：输入卡片「待办」按钮面板（用户增删改查）；文件结构：

{ "updatedAt": 0, "todos": [ { "id": 1, "title": "标题（≤200 字）", "note": "补充说明（可空）", "status": "open" | "done", "createdAt": 0, "doneAt": null } ] }

Mint 侧规则（统一走 todo_user 工具，不裸写文件——结构/校验/面板广播由工具保证，本文件不再贴格式细节）：

• 新增：todo_user add——用户让「记一下/记个想法」、会话中出现「以后/之后要做 xx」的未落任务事项时记入；工具自管 id 递增，title ≤200 字符
• 完成：todo_user toggle（先 list 找到 id）——勾选完成或重新打开；面板与工具共用同一清单，随时同步
• 禁止全量替换/批量删除——清单属用户（面板可能正打开编辑）；仅用户明确点名的条目才 remove/update
• 与开发记录分工：用户待办管「想做还没做的」，开发记录管「已发生的」——新想法先落待办，动手做之后才进开发记录
• 清单为空时不建文件也行（面板/首次写入时自动创建）；不要把它当正式任务——正式任务进 task.json

docs/开发记录.md（导航页）

本文件是项目进度与交接的唯一真相源，会话交接时更新。两部分：

头部「当前进度快照」

记录当前状态，每次会话交接时更新（本区可改）：

### 当前版本
- **vX.Y.Z**（日期发布：一句话变更摘要）
 
### 最近工作
**日期 变更主题**（详见 docs/开发记录/<日期>.md）：
- 本次变更要点（2-4 条，可追溯明细）
 
### 接下来安排
1. 未完成的待办（按优先级）

• 「最近工作」保留最近 1-2 次会话即可，更早的折叠到下方时间线或由明细承接
• 更新时机：会话结束时（交接给下一次会话）、每次发版后
• 新会话开始时先读本文件头部快照，了解当前状态再开工

开发记录索引

日期 → 日志文件映射（按日期降序），每天日志独立存 docs/开发记录/<日期>.md——按需读取，避免单文件无限膨胀：

| 日期 | 记录 |
|------|------|
| 2026-08-19 | 27. 移除请求超时 & 会话卡死修复（2026-08-19，v0.10.2） |

• 每次新建当天日志时，在索引表加一行（编号递增）
• 同一天多条记录合并为一行（用分号分隔）

docs/开发记录/<日期>.md（按日期明细）

• 文件名如 2026-08-19.md，记录当天项目变动 / 用户决策 / 实现详录
• 只增不改：当天记录追加到当天文件，不覆盖历史；已写内容不修改
• 每条记录带日期 + 提交 hash 关联，方便回溯（如「2026-08-19 移除请求超时（commit c51e9e2）」）
• 记录内容：用户需求与决策、实现方案要点、踩坑与根因、发布记录
• 写入时机：每个任务完成、每个阶段切换时追加

CHANGELOG.md（正式发布日志）

条件触发：项目无对外发布需求（本地工具/个人项目）时不建不维护 CHANGELOG；用户明确要发版/发布时才创建并按其规范维护。

遵循 Keep a Changelog 规范，只记录 release 的用户可见变更：

• 日常变更先记入 `[Unreleased]` 区块，发版时整理成版本条目
• 版本条目格式：## vX.Y.Z (日期) — 变更主题，下分 ### Added / Changed / Fixed / Removed（按需）
• 只写用户能感知的变更（功能/修复/交互/性能），不写内部实现细节
• 与 docs/开发记录.md 分工：CHANGELOG 面向用户看版本变化，开发记录面向开发看过程
• 发版时按项目约定更新版本号并整理 CHANGELOG；打 tag、推送、CI Release 或其它分发步骤依实际流程与用户授权执行，不假设每个项目都有相同的发布链路

docs/技术架构.md（架构设计）

记录当前系统架构与关键决策：现状描述随实现更新，决策理由与必要历史保留，避免新旧结论并存却无法辨认当前规则。

• 记录内容：系统架构、数据模型、模块划分、关键设计决策（含为什么这么选）
• 架构级变更更新受影响的现状章节，必要时补充带版本/日期的决策记录或链接；不为每次变动复制整套架构描述
• 不记录：代码能自解释的细节、临时方案、一次性决策（这些进开发记录明细）
• 在授权范围内修正过时描述（如已删除的机制仍被引用）；有价值的旧决策保留理由并标明已替代，过程明细放开发记录
• 新会话涉及架构问题时先读本文件再动手

通用规则

• 文档用中文命名，放入 docs/ 目录
• 增量更新优先：时间线只追加；已获同一对象与范围授权的文档更新直接执行，不重复确认。不覆盖用户其他在制内容；涉及范围外删改或新的取舍时，先列内容与影响请用户决定
• 写文档时所有占位符（{{PROJECT_NAME}}、[待填写]）必须替换为实际内容，禁止留空
• 归档：定稿且不再维护的方案文档移入 docs/archive/，当前文档区只保留有效文档