AutoGPT Platform 中的 Todoist 项目管理：六个 Projects 块的结构、输入输出与源码剖析

2026-09-07 13:10:03作者：齐添朝

AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.

项目地址：https://gitcode.com/GitHub_Trending/au/AutoGPT

AutoGPT Platform 提供了一组用于"创建、查询、更新、删除 Todoist 项目"的视觉化积木式 Blocks（即"块"）。本篇以官方文档 Todoist Projects 为骨架，结合项目块实现源码展开讲解：你将完整掌握六个块各自的作用、全部输入输出字段与类型、默认值与取值约束，并理解它们背后"如何通过 Todoist API 干活"的实现原理，从而在 AutoGPT 画布中搭建真实可用的 Todoist 自动化工作流。

总览：Todoist Projects 块组能做什么

Todoist Projects 文档描述的是"用于在 Todoist 中创建与管理项目的块"，共包含六个独立块。它们都归属于 PRODUCTIVITY（生产力）类别，统一通过 Python 的 todoist_api_python 客户端包调用 Todoist 官方 API（涉及 REST /projects 与 Sync API），定义文件为 autogpt_platform/backend/backend/blocks/todoist/projects.py。

块名（Block 类）	文档中的功能定位	内部注册 ID（class id）	底层调用的 API
Todoist List Projects（`TodoistListProjectsBlock`）	获取当前用户的全部项目	`5f3e1d5b-6bc5-40e3-97ee-1318b3f38813`	`TodoistAPI.get_projects()`
Todoist Create Project（`TodoistCreateProjectBlock`）	新建一个项目	`ade60136-de14-11ef-b5e5-32d3674e8b7e`	`TodoistAPI.add_project()`
Todoist Get Project（`TodoistGetProjectBlock`）	按 ID 读取单个项目详情	`b435b5ea-de14-11ef-8b51-32d3674e8b7e`	`TodoistAPI.get_project()`
Todoist Update Project（`TodoistUpdateProjectBlock`）	修改现有项目	`ba41a20a-de14-11ef-91d7-32d3674e8b7e`	`TodoistAPI.update_project()`
Todoist Delete Project（`TodoistDeleteProjectBlock`）	删除项目及其全部内容	`c2893acc-de14-11ef-a113-32d3674e8b7e`	`TodoistAPI.delete_project()`
Todoist List Collaborators（`TodoistListCollaboratorsBlock`）	列出某项目的协作者	`c99c804e-de14-11ef-9f47-32d3674e8b7e`	`TodoistAPI.get_collaborators()`

可见六块覆盖了项目对象上的 增 / 查 / 改 / 删 / 列表 / 协作成员 六种基本操作，两两互补：Create 与 List/Get 配合可完成"建后即查"，List Collaborators 则补足项目在团队协作维度上的信息。

块内结构的通用范式

在 AutoGPT Platform 中，每个块在源码里都是一个 Block 子类，内部固定包含三类声明（见 projects.py）：

class Input(BlockSchemaInput) —— 输入 Schema，声明每个输入字段、类型、是否必填、默认值与是否属于高级选项（advanced=True 的字段在画布编辑器中通常默认折叠，作为高级参数展示）。
class Output(BlockSchemaOutput) —— 输出 Schema，声明块的输出端口。
async def run(...) —— 运行时主逻辑，负责用凭证连接 Todoist、调用官方 SDK、并把结果通过 yield "输出名", 值 的形式逐个流出。

此外每个块都通过 test_input / test_output / test_mock 声明了测试样例（这些样例同时也充当块的注册数据）。下文将以这六块为单位，逐块给出完整输入输出与源码行为说明。

前置条件：先连接 Todoist 账号（OAuth2 凭证）

所有六个块都包含一个类型为 Credentials 的公共输入，这正是本组块与 Todoist 账号通信的钥匙。凭证机制在 backend/blocks/todoist/_auth.py 中定义：

凭证类型是 OAuth2Credentials，输入类型约束为 ProviderName.TODOIST + "oauth2"，即必须通过 Todoist OAuth2 授权获得；
每个块都会声明其 required_scopes（所需授权范围），由 TodoistCredentialsField(scopes) 组装而成；
实际授权范围在 backend/integrations/oauth/todoist.py 中定义，默认共五个 scope：task:add、data:read、data:read_write、data:delete、project:delete。

平台后端是否启用 Todoist 集成由环境变量 TODOIST_CLIENT_ID 与 TODOIST_CLIENT_SECRET 决定：源码中 TODOIST_OAUTH_IS_CONFIGURED = bool(secrets.todoist_client_id and secrets.todoist_client_secret)（_auth.py），而每个块的构造函数里都写着 disabled=not TODOIST_OAUTH_IS_CONFIGURED——也就是说，只有当你在运行后端的环境里正确配置了 Todoist OAuth2 应用凭据，这组块才会在块库中真正启用。

OAuth 授权的整体流程由 TodoistOAuthHandler 负责：引导用户访问 https://todoist.com/oauth/authorize，用授权码换取访问令牌，随后调用 Sync API /sync 拉取用户邮箱作为 username。值得注意的实现细节：源码注释明确指出 Todoist 不支持令牌刷新（_refresh_tokens 直接原样返回），令牌的过期与吊销接口也都被实现为"不操作"——这符合 Todoist 自身"访问令牌长期有效"的模型。

Todoist List Projects：拉取账号下的全部项目

功能定位

获取当前 Todoist 账号的全部项目及其详细信息，常用于"全量盘点"或作为后续操作的输入源。

输入

输入	说明	类型	必填
Credentials	Todoist OAuth2 凭证	Credentials	是

该块是六块中唯一 没有项目级业务参数 的"列表型"块：对 Todoist 用户而言，项目列表是账号维度的资源，因此它只要求凭证，无需 project_id。

输出

输出	说明	类型
names_list	全部项目名组成的列表	List[str]
ids_list	全部项目 ID 组成的列表	List[str]
url_list	全部项目 URL 组成的列表	List[str]
complete_data	含全部字段的完整项目数据	List[Dict[str, Any]]
error	操作失败时的错误消息	str

说明：完整的 Todoist 项目对象字段较多，块把其中三个常用字段 name / id / url 拆成独立输出端口（names_list/ids_list/url_list），同时通过 complete_data 保留"含全部字段"的原始对象（project.__dict__），供下游需要原始字段时使用。

源码行为与调用链

在 TodoistListProjectsBlock 中：

用 credentials.access_token.get_secret_value() 实例化 TodoistAPI；
调用 api.get_projects() 得到项目对象列表；
遍历项目，分别把 project.name、project.id、project.url 收进三个列表，并把 project.__dict__ 收进 complete_data；
run() 只在列表非空时才 yield 对应输出，即空账号不会产生空数组输出；任何异常都会被捕获并 yield "error"。

块内置的注册测试样例（test_input/test_output）展示了典型的返回形状：例如一个名为 Inbox、ID 为 220474322、URL 为 https://todoist.com/showProject?id=220474322 的测试项目，会被同步输出到四个端口。

典型使用场景

把全部项目名渲染到 LLM 的上下文中，让 Agent 先"看清手上有哪些项目"再决策；
遍历 ids_list 逐个项目执行后续的更新/归档逻辑；
判断某项目是否已存在，避免重复建库。

Todoist Create Project：创建一个新项目

功能定位

接收项目详情参数，通过 Todoist API 新建一个项目。

输入

输入	说明	类型	必填
Credentials	Todoist OAuth2 凭证	Credentials	是
name	项目名称	str	是
parent_id	父项目 ID（用于创建子项目）	str	否
color	项目图标颜色	枚举（20 种颜色值，见下文"颜色取值"）	否
is_favorite	是否标记为收藏项目	bool	否
view_style	展示样式（`list` 列表或 `board` 看板）	str	否

输出

输出	说明	类型
success	创建是否成功	bool
error	创建失败时的错误消息	str

源码细节与默认值

从 TodoistCreateProjectBlock 的 SchemaField 声明可看到几个重要默认值与"高级项"划分：

name 是唯一必填的业务字段，且 advanced=False，在画布上作为常规参数展示；
parent_id 默认为 None——传入时即可创建子项目（Todoist 支持项目嵌套）；
color 默认值为 Colors.charcoal，即不手动指定时新项目为炭灰色图标；
is_favorite 默认 False；
view_style 默认 None，可选值为 list（列表）或 board（看板）；
后四个字段均标记 advanced=True，属于高级参数。

实现上的核心逻辑在 create_project() 静态方法：params = {"name": name, "is_favorite": is_favorite}，然后仅当可选参数非 None 时才把它们加入请求体（颜色以枚举成员 .value 的形式传入），最后调用 api.add_project(**params)；SDK 调用成功即返回 True 并 yield "success"，抛出异常则 yield "error"。

典型使用场景

程序化地批量创建项目，用于工作流自动化的"建仓"环节；
配合 parent_id 自动搭建带层级的项目树（如按"季度 → 团队"两级结构建项目）；
根据用户在某表单中的输入，动态生成个性化项目。

Todoist Get Project：查询单个项目详情

功能定位

传入一个项目 ID，返回该项目在 Todoist 中的完整详情，供下游校验或编辑使用。

输入

输入	说明	类型	必填
Credentials	Todoist OAuth2 凭证	Credentials	是
project_id	要查询详情的项目 ID	str	是

输出

输出	说明	类型
project_id	项目 ID	str
project_name	项目名称	str
project_url	项目 URL	str
complete_data	含全部字段的完整项目数据	Dict[str, Any]
error	查询失败时的错误消息	str

源码细节

在 TodoistGetProjectBlock 中，get_project() 调用 api.get_project(project_id=project_id) 后一次性返回四元组 (project.id, project.name, project.url, project.__dict__)，run() 再分别写到四个输出端口。

与 List Projects 不同，Get Project 的 complete_data 是单个字典而非列表，下游可用它拿到 id、name、url 之外更多字段（如 color、is_favorite、view_style、parent_id 等）。内置测试样例使用的项目为 ID 2203306141、名 Shopping List 的测试数据，便于在联调阶段快速验证块行为。

典型使用场景

Agent 在改名/改色前先 Get Project，确认目标项目的当前状态（查重、防误改）；
把查到的 project_url 作为后续通知/消息中的链接附件；
与"画布上人工指定 project_id"搭配，构成一个可复用的项目详情查询节点。

Todoist Update Project：更新一个已有项目

功能定位

接收项目 ID 与需要更新的字段，对 Todoist 中的现有项目进行原地修改。

输入

输入	说明	类型	必填
Credentials	Todoist OAuth2 凭证	Credentials	是
project_id	要更新的项目 ID	str	是
name	项目新名称	str	否
color	项目图标新颜色	枚举（20 种颜色值，见下文）	否
is_favorite	是否设为收藏	bool	否
view_style	新的展示样式（`list` / `board`）	str	否

输出

输出	说明	类型
success	更新是否成功	bool
error	更新失败时的错误消息	str

源码细节与"只更新非空字段"语义

TodoistUpdateProjectBlock 与 Create 分支最大的不同在于：所有业务字段都可选（默认为 None），只有 project_id 是必填的普通参数，name 属于非高级参数，color/is_favorite/view_style 为高级参数。

update_project() 的实现刻意保持"增量更新"语义：初始化空字典 params = {}，对每个字段单独判断 if name is not None、if color is not None…… 只有用户显式传入的字段才进入 api.update_project(project_id=project_id, **params) 请求体。这意味着省略任何字段都不会把它重置为空/默认值——比如只想改项目名称，就无需关心它当前的颜色与收藏状态，因为它们根本不会出现在请求里，也不会被误改。

典型使用场景

批量把过期项目从看板改回列表视图、或统一改名；
把"完成了的项目"一键标记为收藏，配合个人工作流做优先级归类；
作为 Agent 决策的结果输出动作：LLM 决定改名 → Update Project 落地。

Todoist Delete Project：删除项目及其全部内容

功能定位

按项目 ID 删除 Todoist 项目，连同其内部的 sections（区块）与 tasks（任务）一并删除（这正是官方文档强调 "and all its contents" 的语义）。

输入

输入	说明	类型	必填
Credentials	Todoist OAuth2 凭证	Credentials	是
project_id	要删除的项目 ID	str	是

输出

输出	说明	类型
success	删除是否成功	bool
error	删除失败时的错误消息	str

源码细节

TodoistDeleteProjectBlock 的实现最精简：delete_project() 直接调用 api.delete_project(project_id=project_id) 并把 SDK 返回的布尔值 success 原样透出。删除属于不可逆的高危操作，使用时应特别留意：块声明文档与类 docstring 都明确指出该操作会连带删除项目下所有 sections 和 tasks，因此建议在删除节点前，先用 Todoist Get Project/Todoist List Projects 校验目标 ID。

典型使用场景

清理已完结或废弃的项目（官方文档所述的核心场景）；
在"试用期/演示项目"生命周期结束后的自动回收流程中执行清理；
与 Create Project 配对，实现"临时项目建了用、用完即删"的沙箱式自动化。

Todoist List Collaborators：列出项目的协作者

功能定位

输入项目 ID，返回该项目的全部协作者（共享成员）信息，是六块中唯一处理"人"的块。

输入

输入	说明	类型	必填
Credentials	Todoist OAuth2 凭证	Credentials	是
project_id	要查询协作者的项目 ID	str	是

输出

输出	说明	类型
collaborator_ids	协作者 ID 列表	List[str]
collaborator_names	协作者姓名列表	List[str]
collaborator_emails	协作者邮箱列表	List[str]
complete_data	含全部字段的完整协作者数据	List[Dict[str, Any]]
error	查询失败时的错误消息	str

源码细节

TodoistListCollaboratorsBlock 采用与 List Projects 完全一致的"三列表 + 完整数据"输出结构：get_collaborators() 调用 api.get_collaborators(project_id=project_id)，遍历每个协作者对象，取出 .id、.name、.email 分别聚合，同时把 collaborator.__dict__ 放入 complete_data。块内测试样例演示了两个协作者（Alice、Bob）的输出形态，方便理解四个输出端口的对应关系。

注意：Todoist 中协作者是"受邀共享项目"的对象，因此块只负责读取名单，不含邀请/移除动作；若需管理共享关系，可在画布中串联其他协作类操作。

典型使用场景

Agent 在把某人加入/移出项目前，先确认其是否已是协作者（查重防误发）；
生成"项目成员清单"作为汇报/审计材料；
结合邮箱自动给协作者发送提醒——例如检测到某项目无人更新时提醒所有 collaborator_emails。

关键参考：20 种项目颜色与 view_style 取值

Create 与 Update 两个块的 color 字段使用同一份枚举，其在 backend/blocks/todoist/_types.py 中通过 class Colors(Enum) 定义，枚举名与取值完全一致。可填写的全部 20 个值（与官方文档列出的约束完全相同）为：

berry_red、red、orange、yellow、olive_green、lime_green、green、mint_green、teal、sky_blue、light_blue、blue、grape、violet、lavender、magenta、salmon、charcoal、grey、taupe

小贴士：Create 块的默认色是 charcoal；传入时块会取枚举成员的 .value（字符串）提交给 API，因此画布上以"枚举下拉"形式出现，填错值会被 Schema 校验拦截。

view_style 是自由字符串，文档与源码注释明确其合法取值为两类：list（列表视图）或 board（看板视图），不在二者范围内可能导致 Todoist API 返回参数错误。

组合实战：用 Projects 块组搭建一条"项目整理"工作流

在 AutoGPT 画布中，可以按以下思路把这些块串成自动化流程（块的连线对应"上一块的输出端口 → 下一块的输入端口"）：

盘点：以 Todoist List Projects 开头，读取 ids_list/names_list，喂给 LLM 块做分析（如判断哪些项目已完结、哪些名字不合规范）。
核对与决策：LLM 输出待处理的项目 ID；对需要细查的单个项目接 Todoist Get Project，读取 complete_data 中的当前颜色、收藏状态等。
改造：把决策结果接到 Todoist Update Project，仅传入需要变更的字段（利用其"增量更新"特性）。
清理：对确认废弃的项目接 Todoist Delete Project 执行删除；删除前可再用 Todoist Get Project 做最后核对。
协作视图：对需要汇报的项目接 Todoist List Collaborators，把 collaborator_emails 交给通知类块做收尾提醒。

整个过程不需要手写任何 Todoist 集成代码，全部由这几个块与平台其余节点完成。若需要更深度的 Todoist 自动化，可在同一工作区内继续接入本仓库提供的其他 Todoist 块文档：

它们与 Projects 块共享同一套 Credentials 凭证与颜色/枚举体系，可无缝互连。

错误处理与运行期行为要点

综合六个块的 run() 实现（projects.py），使用时有几点值得注意：

统一 error 端口：所有块都提供 error: str 输出。任何来自 Todoist SDK 的异常（网络错误、凭证无效、项目不存在、参数非法等）都会被 try/except 捕获，并以字符串消息形式从 error 端口流出，而非让整个图执行崩溃——这便于在下游接一个"失败分支"。
写操作用布尔、读操作用明细：Create/Update/Delete 输出 success: bool；List/Get 输出具体字段列表或字典。设计上把"动作是否成功"与"查询到的数据"严格分开。
空数据不输出空数组：三个"列表型"输出（List Projects、List Collaborators）在数据为空时不会产出空列表端口值，下游节点应容忍"未收到该输出"的情况。
删除的破坏性：Delete Project 连带删除项目全部内容，且 Todoist 侧该操作不可恢复，请在图中谨慎编排。