Todoist 任务管理助手

技能文档

---
name: todoist-api-skill
title: Todoist 任务管理助手
description: 通过 Todoist API v1 管理任务、项目、分区、标签、评论、已完成工作报表、活动日志、ID 迁移、项目模板与同步工作流的命令行工具集，支持自然语言快速记录、名称到 ID 的安全解析、带预览的批量操作与增量同步。当用户需要记录任务、整理收件箱、批量完成或移动任务、回顾已完成工作、管理项目结构或自动化 Todoist 流程时触发。触发词：Todoist、待办事项、任务管理、收件箱整理、批量完成任务、任务同步、项目模板、快速添加任务。
category: 办公效率
---

# Todoist API

## 技能工作流

### 步骤1：判断适用性

涉及 **Todoist 数据或自动化** 时使用本技能，尤其是：

- 记录或快速添加新任务
- 查看、过滤、移动、完成、重开或删除任务
- 管理项目、分区、标签或评论
- 写入前把人类可读的名称解析为 Todoist ID
- 用预览模式执行更安全的批量编辑
- 回顾已完成工作或近期动态
- 围绕公开 API 构建 Todoist 脚本、智能体或集成

以下场景**不要**使用本技能：

- 直接操作用户本地 Todoist 应用界面
- 属于日历技能的日历类工作流
- 需要 multipart 处理的附件上传流程（除非准备好使用 `curl` 或 `raw` 逃生舱口）
- 非 Todoist 的任务系统

### 步骤2：连通性检查

确认令牌已配置并完成只读连通性验证：

```bash
export TODOIST_API_TOKEN="YOUR_TODOIST_TOKEN"
python3 scripts/smoke_test.py
python3 scripts/todoist_api.py get-projects --limit 5
```

### 步骤3：选择最小可用命令面

- **单对象单端点** → 低层 REST 封装，如 `get-task`、`update-project`、`get-comment`
- **自然语言记录** → `quick-add-task`
- **安全解析名称** → `resolve-project`、`resolve-section`、`resolve-label`
- **不存在则创建** → `ensure-project`、`ensure-section`、`ensure-label`
- **大量匹配任务** → `bulk-close-tasks`、`bulk-move-tasks`、`bulk-comment-tasks`
- **已完成工作回顾** → `report-completed` 或 `get-completed-tasks`
- **完整/增量同步或批量写入** → `sync`
- **未封装或小众端点** → `raw`

### 步骤4：执行与验证

按「解析目标 → 读取现状 → 预览写入 → 确认执行 → 复核结果」的模式操作（详见下方「推荐操作模式」），输出后向用户报告变更计数或结果摘要。

## 安全默认

- 用户意图不明确时，先以**只读**方式开始
- 任何写入前先把名称解析为 ID
- 除非用户明确要求永久删除，优先**关闭（close）**而非**删除（delete）**
- 批量或破坏性操作先跑 `--dry-run`
- 批量关闭、移动、重复评论、删除需要 `--confirm`
- 命令可能返回大载荷时设置 `--output FILE`，保持 stdout 小而可预测

## 输出契约

主脚本默认向 stdout 打印结构化输出：

- `--format json` 返回稳定的 JSON 信封，含 `action`、`ok`、`count`、`next_cursor`、`matched_count`、`changed_count`、`resolved` 等字段
- `--format summary` 返回更小的人类可读摘要
- `--output FILE` 把完整输出写入文件，stdout 只打印简短的 JSON 提示

面向智能体管线设计：stdout 保持可解析，诊断走 stderr，瞬时失败内置重试。

## 脚本

- **`scripts/todoist_api.py`** — 主非交互式 Todoist 命令行工具
- **`scripts/smoke_test.py`** — 只读连通性检查

先查看帮助：

```bash
python3 scripts/todoist_api.py --help
python3 scripts/todoist_api.py get-tasks-by-filter --help
python3 scripts/todoist_api.py bulk-move-tasks --help
python3 scripts/smoke_test.py --help
```

## 快速上手

设置令牌：

```bash
export TODOIST_API_TOKEN="YOUR_TODOIST_TOKEN"
```

只读冒烟测试：

```bash
python3 scripts/smoke_test.py
```

访问权限抽查：

```bash
python3 scripts/todoist_api.py get-projects --limit 5
python3 scripts/todoist_api.py get-labels --limit 10
```

写入前解析名称：

```bash
python3 scripts/todoist_api.py resolve-project --name "Inbox"
python3 scripts/todoist_api.py resolve-section --project-name "Client Alpha" --name "Next Actions"
python3 scripts/todoist_api.py resolve-label --name "waiting-on"
```

## 高价值工作流

### 快速添加

```bash
python3 scripts/todoist_api.py quick-add-task \
  --text "Email Chris tomorrow at 09:00 #Work @follow-up p2"
```

### 创建分区（不存在时）

```bash
python3 scripts/todoist_api.py ensure-section \
  --project-name "Client Alpha" \
  --name "Next Actions"
```

### 预览批量关闭

```bash
python3 scripts/todoist_api.py bulk-close-tasks \
  --filter "overdue & @errands" \
  --dry-run
```

### 执行同一批量关闭

```bash
python3 scripts/todoist_api.py bulk-close-tasks \
  --filter "overdue & @errands" \
  --confirm
```

### 把匹配任务移动到已解析的分区

```bash
python3 scripts/todoist_api.py bulk-move-tasks \
  --filter "#Inbox & !recurring" \
  --target-project-name "Work" \
  --target-section-name "Next Actions" \
  --dry-run
```

### 已完成工作报表

```bash
python3 scripts/todoist_api.py report-completed \
  --since "2026-03-01T00:00:00Z" \
  --until "2026-03-31T23:59:59Z" \
  --by completion \
  --output reports/march-completed.json
```

## 推荐操作模式

1. **解析或列出**目标对象
2. **读取现状**（低层 getter）
3. **预览**写入（`--dry-run`）
4. 需要时**执行**（`--confirm`）
5. **复核**：重新读取或运行报表命令

## 特性索引

- **命令目录与端点覆盖** → [references/REFERENCE.md](references/REFERENCE.md)
- **任务优先实战配方** → [references/RECIPES.md](references/RECIPES.md)
- **Todoist 特有注意事项** → [references/GOTCHAS.md](references/GOTCHAS.md)

## 逃生舱口

公开命令面尚未封装所需端点时使用 `raw`：

```bash
python3 scripts/todoist_api.py raw \
  --method GET \
  --path /projects/PROJECT_ID/full
```

需要增量同步或批量命令时使用 `sync`：

```bash
python3 scripts/todoist_api.py sync \
  --sync-token '*' \
  --resource-types '["all"]'
```

使用说明

# Todoist 任务管理助手

通过 Todoist API v1 管理任务、项目、分区、标签、评论与报表的命令行工具集。

## 能做什么

- 自然语言快速记录任务（quick-add）
- 名称安全解析为 ID（resolve-*）、不存在则创建（ensure-*）
- 带预览的批量关闭/移动/评论（dry-run → confirm）
- 已完成工作报表、活动日志、ID 迁移、项目模板导出
- 增量同步与原始端点逃生舱口（sync / raw）

## 何时使用

- 记录任务、整理收件箱、批量处理逾期任务
- 回顾已完成工作、生成周报数据
- 自动化 Todoist 工作流、搭建集成

## 快速上手

```bash
export TODOIST_API_TOKEN="YOUR_TODOIST_TOKEN"
python3 scripts/smoke_test.py                # 只读连通性检查
python3 scripts/todoist_api.py quick-add-task --text "明天 09:00 给 Chris 发邮件 #工作 p2"
python3 scripts/todoist_api.py bulk-close-tasks --filter "overdue & @errands" --dry-run
```

## 注意事项

- 批量与破坏性操作必须先 `--dry-run` 预览，再 `--confirm` 执行
- 优先关闭任务而非删除
- 详见 references/（命令参考、实战配方、注意事项）

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。