openakita%2fskills%40todoist-task（openakita%2fskills%40todoist 任务）

Todoist Task — Todoist 任务管理

When to Use

• 用户需要创建、查看、更新或删除 Todoist 任务
• 需要管理 Todoist 项目和分区
• 需要设置任务优先级、截止日期、重复规则
• 需要用标签分类任务
• 需要查询和过滤任务
• 需要将对话中讨论的待办事项同步到 Todoist
• 需要批量管理任务（导入/导出/整理）

Prerequisites

必需配置

获取 Token：

1. 登录 Todoist → 设置 → 集成 → 开发者
2. 或访问：https://app.todoist.com/app/settings/integrations/developer
3. 复制 API Token

在 .env 中配置：

TODOIST_API_TOKEN=your_todoist_api_token_here

工具依赖

验证配置

curl -s "https://api.todoist.com/rest/v2/projects" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" | jq '.[0].name'

Instructions

Todoist API v2 基础

所有请求发送到 https://api.todoist.com/rest/v2/，携带 Bearer Token：

curl -s "https://api.todoist.com/rest/v2/{endpoint}" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" \
  -H "Content-Type: application/json"

核心概念

优先级映射

注意 API 的优先级数字与 Todoist UI 显示是相反的：

Workflows

Workflow 1: 任务 CRUD

创建任务

基本创建

curl -s -X POST "https://api.todoist.com/rest/v2/tasks" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "完成项目方案",
    "description": "包含技术选型和时间线",
    "due_string": "明天下午3点",
    "due_lang": "zh",
    "priority": 4,
    "project_id": "PROJECT_ID"
  }' | jq '.'

带标签和分区的创建

curl -s -X POST "https://api.todoist.com/rest/v2/tasks" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Review PR #42",
    "description": "Check error handling and test coverage",
    "due_date": "2025-03-05",
    "priority": 3,
    "project_id": "PROJECT_ID",
    "section_id": "SECTION_ID",
    "labels": ["code-review", "urgent"]
  }' | jq '.'

创建子任务

curl -s -X POST "https://api.todoist.com/rest/v2/tasks" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "编写单元测试",
    "parent_id": "PARENT_TASK_ID",
    "priority": 2
  }' | jq '.'

查看任务

获取所有活跃任务

curl -s "https://api.todoist.com/rest/v2/tasks" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" | jq '.'

按项目筛选

curl -s "https://api.todoist.com/rest/v2/tasks?project_id=PROJECT_ID" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" | jq '.'

按标签筛选

curl -s "https://api.todoist.com/rest/v2/tasks?label=urgent" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" | jq '.'

使用过滤器查询

curl -s "https://api.todoist.com/rest/v2/tasks?filter=today%20%7C%20overdue" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" | jq '.'

获取单个任务

curl -s "https://api.todoist.com/rest/v2/tasks/TASK_ID" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" | jq '.'

更新任务

curl -s -X POST "https://api.todoist.com/rest/v2/tasks/TASK_ID" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "更新后的任务标题",
    "due_string": "下周一",
    "due_lang": "zh",
    "priority": 3
  }' | jq '.'

完成任务

curl -s -X POST "https://api.todoist.com/rest/v2/tasks/TASK_ID/close" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN"

重新打开任务

curl -s -X POST "https://api.todoist.com/rest/v2/tasks/TASK_ID/reopen" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN"

删除任务

curl -s -X DELETE "https://api.todoist.com/rest/v2/tasks/TASK_ID" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN"

Workflow 2: 项目管理

列出所有项目

curl -s "https://api.todoist.com/rest/v2/projects" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" | jq '.[] | {id, name, color, is_favorite}'

创建项目

curl -s -X POST "https://api.todoist.com/rest/v2/projects" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q2 产品开发",
    "color": "blue",
    "is_favorite": true,
    "view_style": "board"
  }' | jq '.'

view_style 可选：

• list：列表视图（默认）
• board：看板视图

更新项目

curl -s -X POST "https://api.todoist.com/rest/v2/projects/PROJECT_ID" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q2 产品开发（已完成）",
    "color": "grey"
  }' | jq '.'

删除项目

curl -s -X DELETE "https://api.todoist.com/rest/v2/projects/PROJECT_ID" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN"

Workflow 3: 分区管理

分区（Section）用于在项目内组织任务，类似看板的列。

列出分区

curl -s "https://api.todoist.com/rest/v2/sections?project_id=PROJECT_ID" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" | jq '.'

创建分区

curl -s -X POST "https://api.todoist.com/rest/v2/sections" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "PROJECT_ID",
    "name": "进行中"
  }' | jq '.'

常见分区模板

看板式

for section in "待处理" "进行中" "待审核" "已完成"; do
  curl -s -X POST "https://api.todoist.com/rest/v2/sections" \
    -H "Authorization: Bearer $TODOIST_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"project_id\": \"PROJECT_ID\", \"name\": \"$section\"}"
done

GTD 式

for section in "收集箱" "下一步行动" "等待中" "将来/也许" "参考资料"; do
  curl -s -X POST "https://api.todoist.com/rest/v2/sections" \
    -H "Authorization: Bearer $TODOIST_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"project_id\": \"PROJECT_ID\", \"name\": \"$section\"}"
done

Workflow 4: 标签管理

列出所有标签

curl -s "https://api.todoist.com/rest/v2/labels" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" | jq '.[] | {id, name, color, is_favorite}'

创建标签

curl -s -X POST "https://api.todoist.com/rest/v2/labels" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "high-energy",
    "color": "red"
  }' | jq '.'

推荐标签体系

Workflow 5: 截止日期与重复任务

自然语言日期（推荐）

Todoist 支持多语言自然语言日期：

{
  "due_string": "明天下午3点",
  "due_lang": "zh"
}

ISO 日期格式

{
  "due_date": "2025-03-15"
}

或带时间：

{
  "due_datetime": "2025-03-15T15:00:00Z"
}

重复任务

{
  "due_string": "every weekday at 9am",
  "due_lang": "en"
}

常见重复规则：

Workflow 6: 高级过滤查询

过滤器语法

查询示例

今日待办

curl -s "https://api.todoist.com/rest/v2/tasks?filter=today%20%7C%20overdue" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" | \
  jq '.[] | {content, due: .due.string, priority}'

本周紧急任务

curl -s "https://api.todoist.com/rest/v2/tasks?filter=7%20days%20%26%20(p1%20%7C%20p2)" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" | \
  jq '.[] | {content, due: .due.string, priority}'

Workflow 7: 批量操作

从对话生成任务

当用户在对话中提到多个待办事项时，批量创建：

tasks='[
  {"content": "准备周会PPT", "due_string": "明天", "priority": 3},
  {"content": "回复客户邮件", "due_string": "今天", "priority": 4},
  {"content": "代码审查 PR #55", "due_string": "后天", "priority": 2}
]'

echo "$tasks" | jq -c '.[]' | while read task; do
  curl -s -X POST "https://api.todoist.com/rest/v2/tasks" \
    -H "Authorization: Bearer $TODOIST_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d "$task" | jq '{id, content, url}'
  sleep 0.3
done

批量完成任务

task_ids=("TASK_ID_1" "TASK_ID_2" "TASK_ID_3")

for id in "${task_ids[@]}"; do
  curl -s -X POST "https://api.todoist.com/rest/v2/tasks/$id/close" \
    -H "Authorization: Bearer $TODOIST_API_TOKEN"
  sleep 0.3
done

任务导出

curl -s "https://api.todoist.com/rest/v2/tasks" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" | \
  jq -r '["内容","项目ID","优先级","截止日期","标签"], (.[] | [.content, .project_id, .priority, (.due.date // "无"), (.labels | join(","))]) | @csv' \
  > tasks_export.csv

Output Format

任务列表输出

📋 今日待办 (5 项)

🔴 [P1] 回复客户紧急邮件
   📅 今天 14:00 | 🏷️ work, urgent
   📁 客户项目

🟠 [P2] Review PR #42
   📅 今天 | 🏷️ code-review
   📁 开发任务

⚪ [P4] 整理会议纪要
   📅 今天 | 🏷️ admin
   📁 日常事务

✅ 已完成: 3 项 | ⏰ 逾期: 1 项

创建确认

✅ 任务已创建
- 内容: 完成项目方案
- 项目: Q2 产品开发
- 截止: 明天 15:00
- 优先级: P1 (紧急)
- 标签: deep-work
- 链接: https://todoist.com/app/task/12345

Common Pitfalls

1. API Token 无效

症状：所有请求返回 401 解决：确认 TODOIST_API_TOKEN 正确设置，到 Todoist 设置页面重新获取

2. 优先级数字混淆

API 的 priority: 4 对应 UI 的 P1（紧急），这是反直觉的。牢记映射关系或在代码中使用常量：

P1_URGENT=4
P2_HIGH=3
P3_MEDIUM=2
P4_NORMAL=1

3. 中文日期解析失败

使用中文自然语言日期时必须指定 due_lang: "zh"，否则会解析失败或解析为错误日期。

4. 过滤器 URL 编码

通过 curl 传递过滤器时需要 URL 编码：

• | → %7C
• & → %26
• # → %23
• 空格 → %20

5. 项目/任务 ID 是字符串

Todoist REST API v2 返回的 ID 是字符串类型，不是数字。使用 jq 处理时注意类型。

6. 批量操作超频

Todoist API 的限制是每分钟约 450 次请求。批量操作时添加 sleep：

sleep 0.3  # 每次请求间隔 300ms

7. 重复任务的 close vs delete

• close（完成）：对重复任务，会自动创建下一次任务
• delete：永久删除，不会创建下次任务

确保对重复任务使用 close 而非 delete。

8. 时区问题

带时间的截止日期使用 UTC 格式。如果用户在东八区（CST），需注意时差：

{
  "due_datetime": "2025-03-15T07:00:00Z"
}

上述表示北京时间 15:00。

进阶用法

每日回顾脚本

echo "=== 📋 每日回顾 $(date +%Y-%m-%d) ==="
echo ""
echo "--- 🔴 逾期任务 ---"
curl -s "https://api.todoist.com/rest/v2/tasks?filter=overdue" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" | \
  jq -r '.[] | "  ❗ \(.content) (原定: \(.due.date))"'
echo ""
echo "--- 📅 今日任务 ---"
curl -s "https://api.todoist.com/rest/v2/tasks?filter=today" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" | \
  jq -r '.[] | "  • [\(if .priority == 4 then "P1" elif .priority == 3 then "P2" elif .priority == 2 then "P3" else "P4" end)] \(.content)"'
echo ""
echo "--- 📆 明日预览 ---"
curl -s "https://api.todoist.com/rest/v2/tasks?filter=tomorrow" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" | \
  jq -r '.[] | "  ○ \(.content)"'

项目进度统计

PROJECT_ID="your_project_id"
total=$(curl -s "https://api.todoist.com/rest/v2/tasks?project_id=$PROJECT_ID" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" | jq 'length')
echo "📊 项目进度: 剩余 $total 个活跃任务"

EXTEND.md 扩展

用户可在技能同目录下创建 EXTEND.md 添加：

• 默认项目 ID 和名称映射
• 自定义标签体系
• 任务模板（如每周例行任务）
• 与其他工具的集成配置
• 团队成员 ID 映射