my-skills/todo/SKILL.md

---
name: todo
description: |
  极简任务管理 skill。通过 JSON 文件本地存储任务列表，仅记录任务的有与无。
  当用户提到待办、任务管理、todo list、添加任务、查看任务、标记完成时，使用此 skill。
  支持添加、查看、完成三个操作，参数歧义时与用户确认。
---

# 极简任务管理

通过自然语言管理本地 JSON 文件中的任务列表。任务只有「存在」和「不存在」两种状态。

## 数据存储

- 文件路径：`~/.local/share/todo/tasks.json`
- 数据格式：

```json
{
  "tasks": [
    "买菜",
    "写周报",
    "锻炼30分钟"
  ]
}
```

- 任务为纯字符串数组，无 ID、无状态、无优先级、无时间戳

## 校验脚本

每次读写 JSON 前后，使用 `<skill_dir>/scripts/validate.py` 校验数据完整性。

```bash
# 校验数据文件
python3 <skill_dir>/scripts/validate.py

# 校验指定文件
python3 <skill_dir>/scripts/validate.py <文件路径>
```

校验内容：JSON 格式合法性、结构合规（tasks 数组 + 字符串元素）、任务去重（大小写不敏感）。

退出码 0 = 通过，1 = 失败。失败时 stderr 输出具体错误。

## 操作指南

### 添加任务

触发词：添加任务 / 新建待办 / 提醒我做 / 记一下 / add

流程：
1. 确认数据文件存在，不存在则创建 `{"tasks": []}`
2. 运行 `validate.py` 校验当前数据
3. 将新任务追加到 `tasks` 数组
4. 运行 `validate.py` 校验写入后的数据（去重检查）
5. 校验失败则回滚，输出错误信息

### 查看任务

触发词：我的待办 / 有什么任务 / 今天要做什么 / 列出任务 / list

流程：
1. 运行 `validate.py` 校验数据
2. 读取并展示所有任务，带序号

输出格式：

```
📋 任务列表
1. 买菜
2. 写周报
3. 锻炼30分钟
```

### 完成任务（移除）

触发词：完成 XXX / 做完了 / 搞定 / done

流程：
1. 运行 `validate.py` 校验数据
2. 按序号或模糊匹配找到目标任务
3. 从 `tasks` 数组中移除
4. 运行 `validate.py` 校验写入后的数据
5. 校验失败则回滚，输出错误信息

- 匹配多条时列出匹配项让用户确认
- 完成即移除，不做归档

## 参数歧义处理

以下情况必须与用户确认，不可自行猜测：

- **无参数调用**：`/todo` 不带任何参数 → 询问用户意图（查看 / 添加 / 完成）
- **仅操作词无目标**：`/todo done` 未指定具体任务 → 列出任务列表让用户选择
- **语义模糊**：`/todo 买菜` 不明确是「添加」还是「完成」→ 默认理解为添加，但需确认
- **模糊匹配多条**：关键词匹配到多个任务 → 列出候选项让用户确认

确认时使用简洁的提问，例如：

```
你想对「买菜」做什么？
1. 添加为新任务
2. 标记完成（移除）
```

## 交互原则

- **确认优先**：参数歧义时绝不猜测，主动询问
- **操作前校验**：每次读写前后运行 validate.py
- **失败回滚**：校验失败时恢复原数据，告知用户错误原因
- **简洁输出**：操作结果用 ✓ 前缀确认，如 `✓ 已添加任务：买菜`