todo-list Skill — 跨会话 TODO 管理

版本：v1.5.0 | 更新：2026-06-11 | 状态：可用（WorkBuddy Automation 已整合）

详细参考文档

• 触发词完整列表：references/triggers.md
• CLI 命令参考：references/commands.md
• 错误处理 + 降级路径：references/errors.md

决策树（agent 必读）

用户说 X → 怎么办 Y：

add 类

done / delete 类

list / update 类

未知 / 边界

异常处理

核心原则

1. 自然语言优先：用户说什么都行，不强制特定格式
2. 跨会话持久化：SQLite 文件存储，重启不丢失
3. 文件即真相源：每次操作读写 todos/todos.db，不依赖内存
4. 可追溯：所有写操作写 audit_log，便于复盘
5. 优雅降级：任何模块失败都有降级路径，不卡死对话

Skill 生命周期

┌─────────────────────────────────────────────────────────────────┐
│                     Skill Invocation Lifecycle                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  [1] Trigger Detection                                          │
│      关键词匹配 → 识别 action（add/done/del/list/update）        │
│                                                                  │
│  [2] NL Parsing                                                  │
│      raw_input → NLParser.parse() → {action, content, due,     │
│                                       priority, tags}            │
│      ⚠️ 解析失败 → 返回 {action:'unknown', raw_input}           │
│                                                                  │
│  [3] Execution                                                   │
│      TodosStore 执行对应方法                                      │
│      ⚠️ DB 异常 → 降级写 /tmp/todos_fallback.json               │
│                                                                  │
│  [4] Response Formatting                                         │
│      执行结果 → 格式化钉钉消息                                    │
│      歧义 → 列出候选让用户选择                                    │
│                                                                  │
│  [5] Audit Logging                                               │
│      写入 audit_log（action + todo_id + ts + actor）             │
│                                                                  │
│  [6] Reminder Scheduling（仅 add 且 due_at 有效时）              │
│      ✅ WorkBuddy 环境：调用 get_reminder_params() 获取参数后     │
│         通过 automation_update 创建一次性提醒                      │
│      ✅ 非 WorkBuddy 环境：注册 QwenPaw cron 一次性任务（降级）    │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

触发词（trigger words）

错误处理规范

NL 解析失败

# NLParser.parse() 返回 None 或 action='unknown' 时
if parsed is None or parsed['action'] == 'unknown':
    # Agent 回复用户，请求澄清
    reply = "没太理解你的意思，可以换个说法吗？\n" \
            "比如：'提醒我明天下午3点检查止损'\n" \
            "或者直接用命令：todos add '内容' --due '时间'"

歧义处理

# 用户说"完成那个"，但有多个 pending todo
if ambiguous:
    reply = "你说的是哪个？\n" \
            "1. 检查515050止损（今天 15:00）\n" \
            "2. 复盘ETF持仓（明天 09:00）\n" \
            "请回复编号或完整名称。"

数据库异常

try:
    store.add(...)
except sqlite3.OperationalError as e:
    # 降级：写 fallback 文件 + 告警
    _write_fallback(raw_input, str(e))
    logger.error(f"DB write failed, fallback used: {e}")
    reply = "数据库暂时异常，操作已记录，稍后自动同步。"

数据库损坏

# 检测：PRAGMA integrity_check
if integrity_fail:
    # 从 .bak 恢复 + 告警
    _restore_from_backup()
    logger.critical("DB corruption detected, restored from backup")

状态机

pending ──[用户开始]──→ in_progress
   │
   │──[用户说"完成"/done]──→ completed → archive（30天后清理）
   │──[用户说"取消"/del]──→ cancelled → archive（30天后清理）
   │──[due_at 过期 + 定时检查]──→ overdue

状态转换规则

overdue 检测时机

• 定时检查（每日 00:05）：批量扫描所有 pending/in_progress，标记 overdue
• 不在查询时触发（避免每次 list 都扫描）
• QwenPaw cron 注册：5 0 * * *（每天凌晨）

数据模型

SQLite 两表 + audit_log

字段规范

Schema 版本管理

• init_todos.sql 包含版本注释：-- v1.0 2026-06-11
• 后续增量迁移：schema/V2_xxx_add_field.sql 格式命名
• 迁移脚本必须可重复执行（CREATE TABLE IF NOT EXISTS）

日志规范

日志输出：stdout（符合 12-Factor App §XI） 日志格式：[LEVEL] [module] timestamp message

WorkBuddy Automation 整合（v1.5.0 新增）🆕

通道配置（首次使用）

首次使用 todo-list 时，agent 会引导用户选择提醒通道：

# 交互式配置
python3 -m src.reminder setup

# 直接指定通道
python3 -m src.reminder setup --channel workbuddy   # 对话内提醒（推荐）
python3 -m src.reminder setup --channel dingtalk     # 钉钉推送

配置存储在 todos/config.json：

{
  "reminder_channel": "workbuddy",
  "setup_completed": true
}

自动化任务（已创建）

WorkBuddy 环境通过 automation_update 创建 3 个 recurring automation：

一次性提醒

当用户添加带截止时间的 TODO 时，agent 调用：

from src.reminder import get_reminder_params
params = get_reminder_params(todo_id, content, due_at)
# → 返回 automation_update 参数字典
# → agent 调用 automation_update(mode="create", ...) 创建一次性 task

规则：

• 提醒时间 = due_at - 60min（默认）
• 距今 > 7 天的 TODO 不创建提醒（避免无效任务）
• 过期 TODO 不创建提醒

提醒降级

• 如果一次性自动化丢失：每日 09:00 的 recurring automation 会兜底检查
• 距截止 < 2h 且未推送过 → 立即推送一次
• 钉钉通道不可用时自动降级到对话内输出

非 WorkBuddy 环境（降级）

如果需要在 QwenPaw 等环境运行，仍可用 cron：

# 每天 00:05 批量标记 overdue
5 0 * * * cd ~/workspaces/default/todos && python -m src.cli check_overdue

目录结构

todos/
├── SKILL.md                   ← 本文件：技能定义 + 最佳实践
├── README.md                  ← 用户文档
├── DESIGN.md                  ← 技术设计文档
├── schema/
│   ├── init_todos.sql         ← v1.0 schema（入 git）
│   ├── V2_xxx.sql             ← 增量迁移（命名规范）
│   └── init_database.py       ← 初始化脚本
├── todos.db                  ← SQLite（不入 git）
├── config.json               ← 提醒通道配置（v1.5.0 新增）
├── todos.db.bak              ← 每日备份（7 天滚动）
├── src/
│   ├── __init__.py
│   ├── store.py               ← TodosStore：数据层
│   ├── nl_parser.py           ← NLParser：自然语言解析
│   ├── cli.py                 ← CLI 入口
│   ├── reminder.py             ← 定时提醒调度
│   └── etf_integration.py      ← ETF 联动
└── tests/
    ├── test_store.py
    ├── test_nl_parser.py
    ├── test_integration.py
    └── test_cli.py

业界参考（按 SOUL.md 规则13）

阶段进度

当前版本：v1.5.0（WorkBuddy Automation 整合） 评估：skill-evaluator 9.00 S（卓越）

扩展点设计（可演进性）

reminder 后端可插拔

# 环境变量切换
REMINDER_BACKEND=workbuddy    # 默认：WorkBuddy Automation
REMINDER_BACKEND=dingtalk     # 备选：钉钉推送
REMINDER_BACKEND=webhook      # 备选：自定义 webhook

# 实现 Protocol
class ReminderBackend:
    def schedule(job_id: str, run_at: str, text: str) -> bool
    def cancel(job_id: str) -> bool

将来可扩展的功能

版本升级策略

Schema 版本号

-- init_todos.sql 头部注释
-- @version 1.0.0
-- @date 2026-06-11
-- @migration_track audit_log WHERE action='schema_upgrade'

升级路径

v1.0 → v1.1（添加字段）
  └── schema/V1_1_add_reminder_at.sql

v1.1 → v2.0（结构变更）
  └── schema/V2_xxx.sql + rollback 脚本

降级路径（Rollback）

每个 migration 必须包含 rollback（注释）：

-- ROLLBACK: DROP COLUMN reminder_at FROM todos;

自评（第 3 轮）