Todoist

核心用法

Todoist Skill 通过 Maton 网关提供对 Todoist REST API v2 的完整访问能力，采用托管 OAuth 认证模式，用户无需自行处理复杂的 OAuth 流程。核心功能涵盖五大资源维度：

任务管理：支持创建、更新、完成（close）、重新打开（reopen）和删除任务，提供自然语言日期解析（due_string）、优先级设定（1-4级）和标签分配。

项目管理：可创建嵌套项目、设置视图样式（list/board）、管理收藏状态和颜色标识，支持获取项目协作者信息。

结构化组织：通过 Section 实现项目内分组，支持自定义排序；通过 Label 实现跨项目标签化管理。

协作增强：为任务和项目添加评论，支持团队协作场景下的上下文沟通。

连接管理：通过 ctrl.maton.ai 集中管理多账户 OAuth 连接，支持指定特定连接进行 API 调用。

显著优点

• 零配置 OAuth：免除开发者自行搭建 OAuth 服务器的负担，通过 Maton 控制台一键完成授权
• RESTful 完整覆盖：100% 对接官方 API v2，功能无阉割，支持高级过滤语法和自然语言日期
• 多账户支持：通过 Maton-Connection 头部可在单环境中管理多个 Todoist 账户
• 多语言示例：提供 Python、JavaScript/curl 等即用代码片段，降低接入门槛

潜在局限

• 网关依赖：所有请求必须经 gateway.maton.ai 中转，存在单点故障风险和网络延迟
• 环境变量约束：MATON_API_KEY 必须在环境中预设，不支持运行时动态传入（文档示例限制）
• 错误透传：4xx/5xx 错误直接透传 Todoist 原生错误信息，可能增加调试复杂度
• 无 WebSocket 支持：仅提供 REST 轮询模式，无法实现实时任务变更推送

适合人群

• 需要快速集成 Todoist 到自动化工作流的开发者
• 使用 Python/JavaScript 构建个人效率工具的技术用户
• 管理多个 Todoist 工作区/账户的团队管理员
• 希望避免 OAuth 实现复杂性的中小项目团队

常规风险

• 密钥泄露风险：MATON_API_KEY 作为统一认证凭证，若泄露可能导致全部连接被滥用
• 数据隐私：任务内容、项目结构需经第三方网关（Maton）中转，存在中间人风险
• 供应商锁定：深度绑定 Maton 网关架构，迁移至原生 API 需重构认证层
• 速率限制：未明确说明网关层面的限流策略，高并发场景可能触发 429 错误

核心用法

Todoist Skill 是一个纯 Markdown 类型的 API 集成文档，通过 Maton 网关代理连接 Todoist REST API v2。用户需先在 maton.ai 获取 MATON_API_KEY，并在 ctrl.maton.ai 完成 OAuth 授权建立连接。

主要功能覆盖：

• 任务管理：创建、更新、完成、删除任务，支持自然语言日期（如 "tomorrow at 5pm"）、优先级标记（1-4级）、标签分类和子任务嵌套
• 项目管理：创建/更新/删除项目，支持颜色设置、收藏标记、列表/看板视图切换，以及协作者管理
• 分区管理：在项目中创建分区（如 "To Do" / "In Progress"），实现任务分组
• 标签系统：自定义标签颜色、排序和收藏状态
• 评论功能：为任务或项目添加评论，支持团队协作

多连接场景下可通过 Maton-Connection Header 指定特定连接，否则默认使用最早建立的活跃连接。

显著优点

1. OAuth 托管：Maton 平台统一管理 Todoist OAuth 令牌，用户无需处理复杂的 OAuth 流程和 token 刷新
2. 完整 API 覆盖：涵盖 Todoist REST API v2 的全部核心功能，包括高级特性如任务持续时间、循环任务调度
3. 多语言示例：提供 Python、JavaScript/cURL 等即用代码片段，降低接入门槛
4. 自然语言日期：支持 Todoist 原生的智能日期解析（"next Monday 3pm", "every week"）
5. 安全传输：所有流量强制 TLS 1.2+，API Key 通过环境变量注入，无硬编码风险

潜在缺点与局限性

1. 网关依赖：所有请求需经过 Maton 网关（gateway.maton.ai），若 Maton 服务不可用则无法访问 Todoist
2. 网络要求：必须保持网络连接，无法离线使用
3. 速率限制：受 Todoist API 和 Maton 网关双重速率限制约束
4. 功能边界：作为文档型 Skill，本身不执行代码，需用户自行实现业务逻辑
5. 地区限制：依赖海外服务，国内访问可能存在延迟或不稳定

适合人群

• 需要将 AI 助手与 Todoist 工作流集成的开发者
• 希望自动化任务管理的个人效率爱好者
• 团队协作场景下需要批量操作任务/项目的管理员
• 熟悉 REST API 且具备基础 Python/JavaScript 能力的用户

常规风险

| 风险类型 | 说明 | 缓解措施 |

|---------|------|---------|

| API Key 泄露 | `MATON_API_KEY` 若被截获可访问用户 Todoist 数据 | 使用环境变量或密钥管理服务，避免提交到版本控制 |

| OAuth 授权范围 | 用户需授权 Maton 访问 Todoist 账户 | 在 [ctrl.maton.ai](https://ctrl.maton.ai) 可随时撤销连接 |

| 数据隐私 | 任务内容经过 Maton 网关中转 | 确认 Maton 隐私政策符合个人/企业合规要求 |

| 误操作风险 | 批量删除操作（项目/任务）不可逆 | 关键操作前建议备份，生产环境先在测试项目验证 |