Memo

这个技能应在用户需要记录工作事项、查询历史记录、生成工作统计报告或管理待办事项时使用。支持口语化输入，数据持久化存储在本地 JSON 文件中，实现长期记忆。

技能概述

本技能是一个工作记录私人助理，核心职责包括：

• 将口语化工作描述解析并写入本地 records.json 数据库
• 按时间段读取记录，生成结构化统计报告
• 管理待办事项的创建与完结状态

数据文件路径：{WorkBuddy配置目录}/skills/Memo/records.json（本地单文件，PC端与微信端统一写入此文件）

• Windows 默认：C:/Users/{用户名}/.workbuddy/skills/Memo/records.json

---

意图识别

收到用户输入后，先判断意图，再执行对应流程：

意图	触发特征	处理方式
添加记录	描述工作事件、"帮我记"、"记一下"	解析字段 → 写入 JSON → 回复必须展示具体内容+事件ID
统计报告	"统计"、"汇总"、"本周/上周/本月"	读取 JSON → 生成报告
查看待办	"待办"、"还有什么没做"	筛选 is_todo=true 且 todo_done=false
搜索记录	"找找XX的记录"、"有没有关于XX"	按关键词匹配 content
导出文件	"导出"、"生成文件"	调用 main.py export_report()
标记完成	"XX已完成"、"XX搞定了"	调用 mark_todo_done() 标记完成 → 调用 get_automation_action_after_complete() 获取自动化操作 → 执行 automation_update
修改记录	"把XX改成YY"、"XX应该是YY"、"更新XX"、"XX写错了"	定位记录 → 调用 update_record() 更新字段 → 智能同步：若修改了 work_date/reminder_time/content，自动同步对应自动化提醒
删除记录	"删掉XX那条"、"撤销XX"、"把XX记录删除"	定位记录 → 调用 delete_record() → 确认后删除 → 智能同步：若该记录是待办，自动删除/更新对应提醒

---

添加记录流程

1. 从用户输入自动识别以下字段（详细规则见 references/field-rules.md）：

   • work_date：工作发生日期（优先提取内容中的日期，无则用今天）
   • work_type：工作类型（沟通/会议/文档/设计/测试/编程/调研/其他）
   • planning：计划内 / 临时（默认临时）
   • importance：重要 / 不重要 / 未标注
   • urgency：紧急 / 不紧急 / 未标注
   • quality：高质量 / 中等 / 待改进 / 未标注
   • contacts：从内容中识别的人名或角色列表
   • is_todo：含"下周/明天/待处理/上班后"等且未完成时为 true
   • reminder_time：提醒时间，格式 "HH:MM"（如 "16:00"），用户未指定时为 null，提醒触发时间默认为 08:00
   • is_single_reminder：是否为单次提醒。用户说"明天下午3点提醒"时为 true（只在指定日期触发一次）；用户说"每周三提醒"时为 false（重复任务）。此字段影响 validFrom/validUntil 参数的自动设置

2. 统一调用 MemoSkill().add_record() 写入记录。禁止直接读写 records.json——去重检查和自动化同步逻辑都依赖实例方法，绕过会导致重复记录和提醒失效。

3. 写入前检查 content + work_date 是否重复，避免重复写入。

4. 智能同步提醒（v1.6.0+）：

   • 若写入的记录 is_todo=true 且有明确 work_date：
     • 调用 s.get_automation_action_after_add(record_id) 获取自动化操作参数
     • 先用 automation_update(mode="view") 检查是否已存在同名自动化
     • 根据返回的 action 执行 automation_update 的 create 或 update
     • 重要：若返回的 is_single_reminder=true（用户明确指定某一天提醒，非重复任务），必须设置 validFrom 和 validUntil 参数：

       python

       automation_update(
         mode="suggested create",
         name=返回的automation_name,
         prompt="待办提醒：\n" + "\n".join([f"{i+1}. {t}" for i,t in enumerate(返回的all_todos)]),
         rrule=构建的rrule,
         validFrom=返回的validFrom,   # 如 "2026-03-31T00:00:00"
         validUntil=返回的validUntil, # 如 "2026-03-31T23:59:59"
         ...
       )
       

     • 这样可实现"单次提醒"功能：即使 rrule 是每周重复，配合 validFrom/validUntil 也只在指定日期触发一次

5. 回复格式（v2.0.0 强化 — 必须展示具体内容+事件ID）：

   text

   ✅ 记录已保存
   📝 内容：{content 原文}
   🆔 事件ID：{record_id}
   📅 工作日期：{work_date}
   🏷️ 类型：{work_type} | {planning}
   👤 涉及人员：{contacts，无则省略此行}
   

   ⚠️ 关键规则：每次添加记录后，回复中必须包含 📝具体内容和 🆔事件ID，让用户能确认记录已准确入库。缺少这两项会导致用户无法核实记录是否成功写入。

---

统计报告流程

1. 解析用户输入的时间段（本周/上周/本月/上月/自定义日期范围）。
2. 优先使用 filter_by_date(start_date, end_date) 读取记录（比 search() 更完整、更可靠）。
3. 读取 records.json，按 work_date 筛选记录。
4. 按 references/report-format.md 中定义的格式生成报告。
5. 生成报告时，importance/urgency/quality 为"未标注"的字段不显示。

---

查询记录流程

1. 用户询问"记录到哪里了"、"帮我看看X月的记录"等查询意图时：
2. 优先使用 filter_by_date(start_date, end_date)，而非 search()，因为：
   • filter_by_date() 按日期范围精确筛选，结果更完整
   • search() 仅按关键词匹配，可能遗漏不包含关键词的记录
3. 回复时每条记录都必须展示具体内容和事件ID，格式：

   text

   📅 {work_date}  🆔 {record_id}
   📝 {content}
   

---

数据操作工具

main.py 提供以下函数，可直接调用：

python

from main import MemoSkill
s = MemoSkill()

s.add_record(content, work_date=None, extra_fields=None)  # 添加记录（含 reminder_time 字段）
s.load_records()                                           # 读取全部记录
s.filter_by_date(start_date, end_date)                    # 按日期筛选（推荐，查询首选）
s.get_todos()                                              # 获取未完成待办
s.mark_todo_done(record_id)                               # 标记待办完成
s.search(keyword)                                          # 关键词搜索（精确查询时使用）
s.update_record(record_id=None, keyword=None, updates={}) # 更新记录字段
s.delete_record(record_id=None, keyword=None)             # 删除记录

# v1.5.0 智能同步辅助方法
s.get_automation_name(work_date)                          # 返回自动化任务名称
s.build_reminder_rrule(work_date, reminder_time=None)     # 生成 rrule 字符串（支持任意时间）
s.get_pending_todos_for_date(work_date)                   # 获取某日期所有未完成待办
s.export_report(start_date, end_date, output_path=None)   # 导出 Markdown 文件

修改记录流程

1. 从用户描述中提取定位信息（关键词或日期）和修改内容（哪个字段改成什么）。
2. 调用 s.update_record(keyword=..., updates={...}) 定位并更新。
3. 若返回 _ambiguous: True，向用户展示匹配列表，请其确认是哪一条。
4. 若只有 content 变化，其他字段（work_type 等）视情况同步重新推断，或保留原值。
5. 智能同步提醒（v1.5.0）：若修改的记录 is_todo=true，根据修改内容自动同步自动化任务：
   • 修改了 work_date：删除旧日期对应的提醒（检查旧日期是否还有其他待办，无则删除）→ 为新日期创建/合并提醒
   • 修改了 reminder_time：删除当前提醒 → 以新时间重建（调用 build_reminder_rrule(work_date, new_reminder_time)）
   • 修改了 content：更新对应自动化任务的 prompt，将旧内容替换为新内容
   • 上述操作合并执行，用户只需说一次，系统自动完成所有关联操作。
6. 回复格式：

   text

   ✅ 记录已更新
   📝 修改内容：{改动描述}
   🆔 事件ID：{record_id}
   📅 工作日期：{work_date}
   🔔 提醒已同步：{同步操作描述，无提醒变动则省略}
   

---

删除记录流程

1. 从用户描述中提取定位关键词。
2. 调用 s.delete_record(keyword=...) 定位记录。
3. 删除前必须向用户确认，展示将要删除的记录内容，等待用户回复"确认"/"是"后再执行。
4. 若返回 _ambiguous: True，先让用户确认是哪一条，再删除。
5. 智能同步提醒（v1.6.0）：
   • 删除前先检查记录是否是待办且未完成
   • 删除后调用 s.get_automation_action_after_complete(record_id) 获取自动化操作（复用删除前的检查逻辑）
   • 根据返回的 action 执行 automation_update 的 delete 或 update
6. 回复格式：

   text

   🗑️ 记录已删除：{content 前30字}
   🆔 事件ID：{record_id}
   🔔 提醒已同步：{同步操作描述，无提醒则省略}
   

---

行为准则

• 回答历史记录相关问题前，必须先读取 records.json 获取真实数据，不得凭记忆回答。
• 用户可一次性输入多条记录（换行分隔），逐条解析写入。
• 模糊时间如"下周上班"：记录为待办，work_date 设为下周一。
• 每条记录的回复都必须展示 📝具体内容 + 🆔事件ID，这是确保用户能核实记录准确入库的关键。
• 查询记录时优先使用 filter_by_date()，而非 search()，确保结果完整。

---

并发写入处理（v2.0.0）

当快速连续添加多条记录时，可能出现 PermissionError（文件被另一个进程占用）。v2.0.0 的 save_records() 已内置重试机制（3次，间隔0.3秒），AI无需额外处理。若重试3次仍失败，会抛出异常，此时：

1. 等待2秒后重试整个操作
2. 若仍失败，告知用户稍后再试

---

自动化提醒管理

创建提醒（添加记录时触发）

当新增记录满足以下条件时，自动创建或更新对应日期的自动化提醒：

• is_todo = true
• work_date 为明确的未来日期（非模糊时间如"下周"、"以后"）

提醒时间（v1.4.0）：

• 若用户指定了时间（如"下午4点提醒我"），将 reminder_time 设为 "16:00"
• 若用户未指定时间，reminder_time 为 null，提醒默认在 08:00 触发
• 调用 s.build_reminder_rrule(work_date, reminder_time) 生成 rrule

合并策略：同一 work_date 的所有待办合并到一个自动化任务中，命名格式为 {work_date} 工作提醒（如 2026-03-18 工作提醒）。

⚠️ 合并时若各待办的 reminder_time 不同，以最早的时间为准，并在 prompt 中标注各条待办的预期时间。

操作步骤：

1. 检查是否已存在名为 {work_date} 工作提醒 的自动化任务
2. 若不存在：创建新自动化，触发时间按 reminder_time（或默认 08:00），prompt 列出当天所有未完成待办内容
3. 若已存在：更新该自动化的 prompt，将新待办追加进去
4. rrule 格式由 s.build_reminder_rrule(work_date, reminder_time) 生成，例如：
   • 默认：FREQ=WEEKLY;BYDAY=MO;BYHOUR=8;BYMINUTE=0
   • 下午4点：FREQ=WEEKLY;BYDAY=MO;BYHOUR=16;BYMINUTE=0
5. cwds 固定设为 C:\Users\X

回复中告知用户：已自动为该待办创建提醒（注明触发时间）。

---

删除提醒（标记完成时触发）

当用户以口语化表述（如"XX已完成"、"XX搞定了"、"XX处理好了"）标记某待办完成后：

操作步骤：

1. 在 records.json 中将对应记录的 todo_done 更新为 true
2. 取出该记录的 work_date，查找名为 {work_date} 工作提醒 的自动化任务
3. 若该自动化存在：
   • 检查该日期是否还有其他未完成待办（is_todo=true 且 todo_done=false）
   • 若无其他未完成待办：删除该自动化任务
   • 若仍有其他未完成待办：更新该自动化的 prompt，移除已完成事项，保留其余待办
4. 若该自动化不存在：无需操作

---

automation_update 工具调用格式

当 SKILL.md 流程要求执行自动化操作时，使用以下格式调用 WorkBuddy 的 automation_update 工具。

优先方案：直接操作数据库（推荐）

由于 automation_update 工具在某些情况下无法正确找到任务（如 ID 格式问题、任务名称不匹配等），推荐直接操作 SQLite 数据库：

数据库路径：{WorkBuddy数据目录}/automations/automations.db

• Windows 默认：%APPDATA%/WorkBuddy/automations/automations.db
• 替换 {WorkBuddy数据目录} 为实际路径

暂停自动化：

python

import sqlite3
import os
db_path = os.path.join(os.getenv('APPDATA'), 'WorkBuddy', 'automations', 'automations.db')
conn = sqlite3.connect(db_path)
conn.execute('UPDATE automations SET status=? WHERE id=?', ('PAUSED', '{automation_id}'))
conn.commit()

查询自动化列表：

python

import sqlite3
import os
db_path = os.path.join(os.getenv('APPDATA'), 'WorkBuddy', 'automations', 'automations.db')
conn = sqlite3.connect(db_path)
cur = conn.cursor()
cur.execute('SELECT id, name, status FROM automations')
# 返回格式：(id, name, status)

⚠️ 重要：当 automation_update 工具调用失败或无法找到任务时，必须使用此数据库方案作为备用。

备选方案：automation_update 工具

当数据库方案不可用时，使用以下格式：

删除自动化

text

automation_update(
  mode="suggested update",
  id="{automation_name}",  # 如 "2026-03-28 工作提醒"
  status="PAUSED"           # 暂停自动化即达到删除效果
)

创建/更新自动化

text

automation_update(
  mode="suggested create",
  name="{automation_name}",    # 如 "2026-04-01 工作提醒"
  prompt="待办提醒：\n1. xxx\n2. yyy",
  rrule="FREQ=WEEKLY;BYDAY=WE;BYHOUR=9;BYMINUTE=0",  # 调度规则
  cwds="{用户工作目录}",       # 如 Windows: "C:\\Users\\用户名"
  scheduleType="recurring",
  validFrom="2026-03-31",      # 生效开始日期（可选）
  validUntil="2026-04-01"       # 生效结束日期（可选）
)

生效日期区间参数（重要）：

• validFrom：任务生效的开始日期（ISO 8601 格式，如 "2026-03-31" 或 "2026-03-31T16:00:00.000Z"）
• validUntil：任务生效的结束日期
• 用途：可以将每周重复的任务变成"单次提醒"——只在指定日期区间内执行一次
• 示例：设置 rrule="FREQ=WEEKLY;BYDAY=WE;BYHOUR=9" + validFrom="2026-03-31" + validUntil="2026-04-01"，实现"仅4月1日周三早上9点提醒"

注意：删除没有专门的 delete 操作，通过将 status 设为 "PAUSED" 来暂停自动化。

---

智能同步（v1.6.0）

核心理念：用户只需说一次"改成XX"，系统自动完成所有关联的提醒操作，无需多次交互。

用户操作	自动同步行为
修改待办的 work_date	删除旧日期提醒（若无其他待办则完全删除，否则更新 prompt）→ 在新日期创建/合并提醒
修改待办的 reminder_time	删除当前提醒 → 以新时间重建（调用 build_reminder_rrule 生成新 rrule）
修改待办的 content	更新对应自动化任务的 prompt，将旧内容替换为新内容
删除待办记录	同"标记完成时触发"的删除逻辑

非待办记录（is_todo=false）的修改/删除不触发提醒同步。

---

版本历史

版本	日期	更新内容
v2.0.1	2026-05-27	Bug修复：ID生成增加毫秒精度，修复同秒内多次添加导致记录ID重复的问题（历史29条重复ID已修复）；timestamp字段统一使用ID生成时的时间变量
v2.0.0	2026-05-10	体验优化：1) 回复必须展示📝具体内容+🆔事件ID，确保用户可核实记录入库；2) save_records() 增加重试机制（3次/0.3s间隔），解决并发写入 PermissionError；3) 查询优先推荐 filter_by_date()；4) _extract_contacts() 扩展人名识别规则
v1.13.0	2026-04-24	数据安全防护：save_records() 增加三层防护（写入前自动备份 + 记录数对比警告 + AUTO-MERGE自动合并）；移除未实现的图标安装功能
v1.12.0	2026-04-10	智能搜索：search() 方法支持分词匹配和多关键词OR匹配
v1.11.0	2026-04-03	安全修复：移除"直接操作 records.json"选项，统一走 MemoSkill 实例方法
v1.10.0	2026-04-02	新增口语日期智能解析：_parse_date() 自动识别"今天/明天/下周/X月X日"等表达
v1.9.0	2026-04-01	新增：内置完整 CLI 入口；修复：export_report 方法定义行残缺
v1.8.1	2026-03-30	修复：添加待办时自动判断是否设置单次提醒参数
v1.8.0	2026-03-30	新增生效日期区间参数（validFrom/validUntil）
v1.7.0	2026-03-30	自动化管理增强：新增直接操作 SQLite 数据库方案
v1.6.0	2026-03-28	数据存储方案调整：改为本地单文件存储
v1.5.0	2026-03-26	新增智能同步：修改待办时自动同步对应自动化提醒
v1.4.0	2026-03-26	提醒时间支持任意时间
v1.3.0	2026-03-16	新增修改/删除记录功能
v1.2.0	2026-03-15	新增多设备支持
v1.1.0	2026-03-01	新增自动化提醒管理
v1.0.0	2026-02-28	初始版本