核心用法
Todoist Skill 提供对 Todoist REST API v2 的完整封装，通过 Maton 网关实现托管式 OAuth 认证。用户无需自行处理令牌刷新和授权流程，仅需配置 MATON_API_KEY 即可调用所有 API 功能。
主要功能模块：
- 任务管理：创建、更新、完成、删除任务，支持自然语言日期（"tomorrow at 5pm"）、优先级标记（1-4级）、标签分配和子任务层级
- 项目管理：创建/更新/删除项目，支持嵌套结构、颜色自定义和看板/列表视图切换
- 分区管理：在项目内创建逻辑分区（如"待办/进行中/已完成"）
- 标签系统：全局标签创建与管理，支持颜色分类
- 评论功能：为任务或项目添加协作评论
认证流程：通过 ctrl.maton.ai 管理 OAuth 连接，首次使用需在浏览器完成授权，后续请求自动注入令牌。支持多账户场景，通过 Maton-Connection 头部指定特定连接。
显著优点
1. 零OAuth维护成本：Maton 自动处理令牌生命周期，开发者只需关注业务逻辑
2. 完整API覆盖：支持 Todoist 官方 v2 API 的所有核心端点，包括高级过滤器语法
3. 多语言示例：提供 Python、JavaScript、bash 三种语言的完整代码示例
4. 灵活日期解析：due_string 支持自然语言输入，大幅降低日期处理复杂度
5. 多租户支持：单 API Key 可管理多个 Todoist 账户，适合团队场景
潜在缺点与局限性
- 网关依赖：所有请求必须经过 Maton 网关，存在单点故障风险；若 Maton 服务不可用则完全中断
- 网络强依赖：明确需要网络访问，无法离线使用
- 学习曲线：需同时理解 Todoist 原生API概念和 Maton 连接管理机制
- 调试复杂度：错误可能来自 Maton 网关层、OAuth 层或 Todoist API 层，排查需分层定位
- 无Webhook支持：当前仅支持REST轮询，实时同步需自行实现
适合人群
- 需要自动化任务管理的开发者/效率工具用户
- 已使用 Todoist 但希望集成到自定义工作流的技术团队
- 需要跨多个 Todoist 账户统一管理的企业管理员
- 希望避免 OAuth 实现复杂性的快速原型开发者
常规风险
| 风险类型 | 说明 | 缓解建议 |
|---------|------|---------|
| 令牌泄露 | `MATON_API_KEY` 泄露可导致账户完全控制 | 使用环境变量存储，避免硬编码；定期轮换密钥 |
| OAuth 会话过期 | 长期未使用可能导致授权失效 | 实现连接状态检查，异常时引导用户重新授权 |
| 数据误删 | DELETE 操作不可逆 | 生产环境操作前确认资源ID，考虑备份策略 |
| 速率限制 | Todoist API 有调用频率限制 | 实现指数退避重试，避免高频轮询 |
| 网关MITM风险 | 流量经过第三方网关 | 验证 TLS 证书，敏感任务考虑直接官方API |
特别注意事项：环境变量在管道命令中可能无法正确展开（如 curl ... | jq 场景），建议使用脚本文件或显式导出变量。