todoist-api

Todoist 工作流

日常操作请使用官方 CLI。只有在处理特定集成，或确认已安装的 CLI 帮助中存在功能缺口时，才使用公共 API。不要维护另一个完整客户端，也不要在用户不知情的情况下切换其账户或连接。

确认操作界面

1. 如果已有授权的 Todoist 连接器支持所请求的操作，请优先使用；否则检查 td --version、td --help 和 td auth status。
2. 官方软件包是 @doist/todoist-cli，可执行文件为 td。安装和身份验证会更改主机或账户状态；仅在获得授权时执行。
3. 使用操作系统凭据存储，不要在命令参数、报告或代码仓库中放置令牌。如果当前账户或权限似乎有误，检查是否设置了 TODOIST_API_TOKEN，但不要打印其值。
4. 对于只读操作，优先使用只读 OAuth。CLI 身份验证元数据不能证明外部提供的令牌具有特定范围。
5. 使用前，先阅读对应子命令的帮助。优先使用结构化输出；不要解析面向用户的表格，也不要假定不同命令都支持相同的标志。

Doist 维护了自己的 CLI 技能（td skill install universal，或相关的 Agent 目标）。如可用，请使用它了解完整命令语法；安装它是可选的，并非前提，也不代表可以修改 Agent 配置。此技能补充了以下解析、批量更改和核对工作流。

解析、执行、验证

td project list --json
td task list --project "Work" --json
td task view TASK_ID --json

应在对应的上下文中解析名称：账户/工作区、项目、分区，以及个人标签与共享标签。保留不透明的字符串 ID。遇到重名时，列出候选项；不要选择第一个匹配项。切勿将 tmp- 客户端占位符传给服务端端点。

获得授权后，可使用以下简单示例进行记录：

td add "Email Chris tomorrow at 09:00 #Work @follow-up p2"

读取创建后的任务，并验证项目、标签、解析出的日期/时间、时区和重复规则。自然语言解析结果不能证明系统保存了预期日期。API 优先级编号与面向用户的 p1 表示法不同；应验证两者的对应关系，不要在不同界面之间直接照搬数字。

编辑时，先读取当前状态，使用已安装帮助中说明的方法应用所请求的更改，然后重新读取受影响字段。如果请求的意思是完成任务，而非永久删除，请选择完成操作。完成重复任务的某次执行与结束整个重复系列是不同操作；请检查返回的下一个截止日期。

批量编辑和恢复

批量关闭、移动、评论或删除之前，请阅读 API 和批量操作。明确固定一组 ID 和拟议更改，先预览，再应用该集合，而不要重新运行可能产生变化的筛选条件。用户已有的授权可以覆盖该计划；CLI 标志或计划文件不能授予额外权限。

记录每项操作的结果，包括已确认成功、已确认失败和结果未知的情况。写入后发生超时属于结果未知，不能据此认定操作未发生。重试前先核对。恢复时，切勿重新执行整个未完成的批次，也不要重新生成去重 ID。

报告和集成工作

对于已完成工作报告，应明确时区和时间区间，并区分完成时间与截止日期。应按请求遍历所有返回的游标，否则须将结果标记为不完整。不要将页面大小误认为总数。

对于 Sync API、附件、模板、归档资源或迁移工作，只有在确认当前端点/SDK 合约后，才使用参考资料。旧版自定义 Python CLI 及其标志已移除；没有兼容层。

请返回已查找或更改的内容、稳定 ID 或服务提供方返回的链接、已执行的验证、尚未解决的结果，以及分页边界。不能仅凭命令示例就声称连接、写入或报告成功。

来源和检查

于 2026-09-13 对照 Todoist API v1 和官方 CLI进行了审核。已安装版本的帮助信息和当前端点文档仍是准确语法的权威来源。

维护者：针对 Agent 轨迹运行 evals/scenarios.json 中的场景。这些是评估用例，并不代表已进行了实时测试。