清时小伴 — 你的待办统一收件箱（v0.2 通用版）

> 核心价值：邮件/微信/IMA/脑子里随时冒的事，全部汇总到一个本地清单；早提醒、周报复盘、随时记完成。
> 设计原则：One inbox / Local-first / Inbox Zero / Hooks / Mute noise（参考开源工具 MaximeGaudin/void）。
> v0.2 通用版说明：本版本是"通用版"，仅包含规则/方法/伪代码示例，不含任何个人记录（路径/姓名/实战日期/具体待办）。本地完整版（含个人实战记录）见 ~/.hermes/skills/qingshi-xiaoban/SKILL.md。

🎯 一句话定位

针对"待办散落多渠道、经常漏事、每周写周报头疼"的人：把邮件/微信/IMA/碎片想法 4 个来源的待办汇总到一个本地 RAG 知识库，每天早 8:30 推一次重点提醒、每周五 17:00 自动生成完成情况周报；随时说"完成了"自动归档。

> 一句话：你只管说"完成了"，清时管"提醒、汇总、复盘"。

> ⚠️ 路径说明：实际项目目录以用户在首次录入时指定的为准（默认建议 ~/Documents/学习笔记/），避免 ~/qingshi-data/ 隐藏目录命名。

🎬 4 个核心场景

场景 1：4 源待办统一收集（核心入口）⭐⭐⭐⭐

4 个来源：

统一格式（追加到 清时小伴/todo.md）：

# 清时小伴 — 待办清单
> 上次更新：<YYYY-MM-DD HH:MM>

## 🔴 紧急（今天到期）
- [ ] **<待办标题>** — 来源：<邮件/微信/IMA/碎片>（<YYYY-MM-DD HH:MM> 录入）
  - 截止：<YYYY-MM-DD>
  - 关联：[原始链接或上下文]

## 🟡 重要（本周）
...

## 🟢 一般
...

收口规则（借鉴 void 的 muted noise 原则）：

场景 2：每天早 8:30 推送（每天用）⭐⭐⭐

> 关键设计（参考 void 的 inbox zero loop）：只发 1 次/天，不每条都提醒。

• 默认每天早 8:30（可改）
• 今日聚焦模式——只推 3 条（不是 5 条），标"今天就做这 3 件就赢了"
• 内容 3 块：
  1. 🔴 今天到期的（最多 3 条，超出折叠）
  2. 🟡 本周即将到期的（最多 3 条）
  3. 🟢 碎片想法里还没说截止日期的（每周只推 1 次）
• 推送渠道：微信（日常最常用）+ 邮件汇总副本

推送模板：

清时小伴 早 8:30 推送：

☀️ 早上好。今天就做这 3 件就赢了：

1. 🔴 <标题>（<来源> <录入时间>）
2. 🔴 <标题>（<来源> <录入时间>）
3. 🟡 <标题>（<来源> <截止日>）

详见 → <todo.md 路径>

— 清时小伴

场景 3：每周五 17:00 自动周报（每周用）⭐⭐⭐

> 关键差异化（借鉴 void 的 Inbox Zero + 复盘扩展）

周报结构（自动生成到 reports/<YYYY-Wxx>-周报.md）：

# 本周工作周报（<YYYY-MM-DD> ~ <YYYY-MM-DD>）

## ✅ 本周已完成（来自 done.md）
- <标题>（<完成日>）
- ...
共 <N> 件，比上周 ±<M> 件

## ⏳ 跨周未完成
- <标题>（计划 <截止日>）

## 🟡 来源分布
- 邮件来源：<N> 件
- 微信来源：<N> 件
- IMA 来源：<N> 件
- 碎片想法：<N> 件

## 💡 复盘建议（基于历史）
- "碎片想法"完成率 <X>%，"邮件来源"完成率 <Y>%
- **建议**：<个性化建议>

> 复盘逻辑：自动统计来源 vs 完成率，给个性化建议。

场景 4：随时记录完成（最常用）⭐⭐⭐

> 最简交互——用户只要说"清时，X 完成了"，自动归类 + 移到 done.md。

对话示例：

> 你：清时，<某件事> 完成了
> 清时：✅ 已记录（<完成时间>，来源：<源>）— 这件从你记录到完成用了 <时长>。

完成的处理（借鉴 void 的 archive + 智能去重）：
- 自动从 todo.md 找到匹配项 → 移到 done.md（语义匹配，不靠关键词）
- 找不到匹配项（用户随口说"完成了 X"）→ 询问"这是新增完成项吗？"
- 重复完成（同一件事说了 2 遍） → 智能去重 + 提示"已记录过啦"

⚠️ 录入实战教训（强制三步走）

> 通用教训：批量录入碎片待办时，AI 容易踩 2 个真坑：脑补漏数 和 写入前未读最新文件。

强制三步走（每次录入碎片想法时）：

1. read_file(todo.md)  →  拿最新版本（防被外部覆盖）
2. cp todo.md todo.md.bak  →  写前备份
3. 录入：原文存 todo-source/fragments/ + patch 进 todo.md

脑补拦截（用户一次说多件事时）：

用户："周一到周三要约 A、B、C 三件事..."
  ↓
AI 复述："我数了一下是 N 件对吗？A=...，B=...，C=..."
用户："对" → 录入
用户："漏了 D" → 补录

🛡️ 多写入者并发保护（核心协议）

> 核心事实：todo.md 至少有 3 个写入者——
> ① AI（chat / cron）
> ② 用户本人（手机 / Termius / Working Copy 远程编辑）
> ③ 任何自动流程（cronjob / 旧 LLM 实例）
>
> 任何一个写入者直接 write_file 整个 todo.md = 数据丢失。

3 个写入者的边界

🚨 强制规则：APPEND-ONLY ZONE 写入协议

todo.md 结构必须有 APPEND-ONLY ZONE 标记：

## 🔴 紧急
<!-- ⬇️⬇️⬇️ APPEND-ONLY ZONE START ⬇️⬇️⬇️ -->
<!-- 所有写入者只能在 ZONE END 之前追加新条目 -->
<!-- 请勿修改或删除已有条目 -->
- [ ] 已有条目 A（任何写入者都不能动）
- [ ] 已有条目 B
...
<!-- ⬆️⬆️⬆️ APPEND-ONLY ZONE END ⬆️⬆️⬆️ -->

关键约束（每个写入者必须遵守）：

1. ZONE 必须包含全部 3 个优先级区（🔴 紧急 / 🟡 重要 / 🟢 一般），不能只包一部分
2. 新条目只能插入到 ZONE END 标记之前（最末尾追加）
3. 绝不修改、删除、移动 ZONE 内的已有条目
4. 优先级由 AI 在插入前判定（按截止日 + 标题智能判断 🔴/🟡/🟢），不是写入者自己标

🔧 推荐工具：scripts/merge_todo.py

v0.1.2 起：所有写入者必须用 scripts/merge_todo.py 脚本写入，禁止直接 write_file todo.md。

脚本功能：
- 冲突检测：如果 todo.md 在 5 秒内被改过，报错让人等
- 去重：相似标题（关键词重叠 ≥60%）视为重复，不录入
- 智能优先级：根据截止日自动判定 🔴/🟡/🟢
- 原子写入：用临时文件 + os.replace 原子替换，防止中途失败损坏文件
- 强制走 ZONE：只在 ZONE END 前插入

用法：

# 录入一条新待办
python3 scripts/merge_todo.py "新待办标题" --source <源> --due <YYYY-MM-DD>

# 列出所有待办（只读，安全）
python3 scripts/merge_todo.py --list
python3 scripts/merge_todo.py --list --since <YYYY-MM-DD>   # v0.1.3 新增：按日期段查

# 标记完成（v0.1.3 新增，自动移到 done.md）
python3 scripts/merge_todo.py --done "<标题>"

# 整理 ZONE（v0.1.3 新增，把 ZONE 外孤儿移回 ZONE 内）
python3 scripts/merge_todo.py --fix-zones

# 交互模式（多步录入）
python3 scripts/merge_todo.py --interactive

# 预览（不写文件）
python3 scripts/merge_todo.py "标题" --source <源> --due <YYYY-MM-DD> --dry-run

📡 4 源收口规则

关键边界：

• ❌ 清时不主动对接任何云端（不连 IMAP、不调微信 API、不爬 IMA）
• ❌ 清时不读取任何外部数据目录（除非用户明确说"读这个"）
• ✅ 清时只响应用户在 chat 里说的话 / 用户手动给的数据
• ✅ 4 源 = 4 个给数据的入口，不是 4 个 AI 自动抓的通道

> 原因：纯本地 + 零云端依赖 = 隐私优先 + 不需要维护 4 个外部接口。

🚀 触发词（Trigger Phrases）

目录结构

<用户指定的数据根目录>/
└── 清时小伴/
    ├── todo.md                  # 待办清单（4 源汇总，按优先级分组）
    ├── done.md                  # 已完成清单
    ├── sources/                 # 各源原始数据
    │   ├── emails/              # 邮件来源原始
    │   ├── wechat/              # 微信来源原始
    │   ├── ima/                 # IMA 来源原始
    │   └── fragments/           # 碎片想法原始
    ├── reports/                 # 周报/月报
    │   ├── <YYYY-Wxx>-周报.md
    │   └── <YYYY-MM>-月报.md
    └── profile.md               # 长期画像（来源偏好/完成率/拖延模式）

> 关键点：纯 Markdown + YAML frontmatter —— 不锁死清时，任何笔记软件都能读。

🔒 隐私原则

可全离线模式：用 Ollama 本地模型替代 DeepSeek → 完全离线。

🚫 不做什么（明确边界）

• ❌ 不是 GTD 全套（不替代滴答清单/Notion 这类全套任务管理）
• ❌ 不做项目协作（不接团队 todo，只服务个人）
• ❌ 不替你做决定（不判断优先级，只汇总不决策——除非你授权）
• ❌ 不爬取所有邮件/微信（只读你授权的"待办关键词"相关）
• ❌ 不无脑提醒（每天只推 1 次，长期未完成标红不催）
• ❌ 不假装很懂你（清时只基于"你授权的来源"，不脑补）

🛠 技术栈

🔧 前置依赖

1. Ollama 本地服务（必须）：ollama pull nomic-embed-text
2. DeepSeek API key（必须）：DEEPSEEK_API_KEY
3. ChromaDB（必须）：pip 装
4. email-archive-rules skill（邮件源必须）：复用其 22 关键词
5. yuanbao skill（微信源必须）：复用其消息提取
6. 数据目录：首次运行自动创建（用户指定）

📐 设计原则（参考 void + 补充）

> 5 大原则：One inbox / Local-first / Inbox Zero / Hooks / Mute noise

📦 版本规划

• v0.1（已发布）：SKILL.md 占位 + 触发词 + 产品定义
• v0.2（当前通用版）：完整 setup.md + 4 源扫描脚本 + 智能去重 + APPEND-ONLY ZONE 协议
• v0.3：早推送（微信）+ 周报自动生成
• v0.4：与 yunjian-zhiyi 跨 skill 联动（身心一体）
• v1.0：语音录入 + 全离线模式 + 团队版（多人收件箱）预留接口

> 通用版与本地版的区别：通用版仅保留规则/方法/伪代码示例。本地完整版（含个人实战记录、实战踩坑、真实待办样例）见 ~/.hermes/skills/qingshi-xiaoban/SKILL.md。