核心用法
Todoist Skill 是 Maton 平台提供的官方代理服务，将 Todoist REST API v2 封装为托管 OAuth 网关。用户无需直接处理 Todoist 的 OAuth 流程，只需在 Maton 控制面板完成授权，即可通过统一网关调用任务管理接口。
典型工作流：
1. 在 ctrl.maton.ai 创建 Todoist 连接并完成 OAuth
2. 使用 MATON_API_KEY 调用网关端点
3. 通过标准 REST 操作管理任务、项目、分区、标签和评论
关键功能覆盖：
- 任务管理：创建/更新/完成/删除任务，支持自然语言日期（"tomorrow at 5pm"）、优先级（1-4）、标签、循环任务
- 项目管理：嵌套项目、颜色标记、看板/列表视图、协作者查询
- 分区组织：项目内分组管理
- 标签系统：自定义标签体系
- 评论协作：任务和项目级别的评论线程
显著优点
- 零 OAuth 维护：Maton 托管令牌刷新，避免令牌过期导致的自动化中断
- 多连接支持：可通过
Maton-Connection头切换多个 Todoist 账户 - 自然语言日期：
due_string支持 Todoist 原生 NLP 解析（"every week", "next Monday"） - 完整 API 映射：覆盖 Todoist v2 全部核心资源，无功能阉割
- 标准化错误码：400/401/404/429 等状态码清晰可预期
潜在局限
- 网关依赖：所有请求必须经过 Maton 基础设施，存在单点依赖
- 网络要求：纯云端代理，无法离线使用
- 速率限制：受 Todoist API 和 Maton 网关双重限制，高并发场景需自行退避
- ID 类型混淆：文档强调 ID 为字符串，但历史习惯可能导致整数处理错误
适合人群
- 需要将 Todoist 集成到自动化工作流（CI/CD、定时脚本、数据处理管道）的开发者
- 使用 Maton 平台统一管理多 SaaS 连接的团队
- 希望避免 OAuth 实现复杂度的个人效率用户
常规风险
| 风险类型 | 说明 | 缓解建议 |
|---------|------|---------|
| 令牌泄露 | `MATON_API_KEY` 泄露可能导致所有托管连接被滥用 | 使用环境变量注入，避免硬编码；定期轮换密钥 |
| 连接失效 | Todoist 账户授权撤销或令牌异常 | 监控 400 错误，在 `ctrl.maton.ai` 检查连接状态 |
| 数据误删 | DELETE 操作立即生效无回收站 | 生产操作前先在测试项目验证；关键任务先备份 |
| 并发覆盖 | 多客户端同时修改同一任务 | 业务层实现乐观锁或操作串行化 |
| 网关不可用 | Maton 服务中断导致 API 访问失败 | 关键路径设计降级方案（如本地缓存 + 延迟同步）|