AutoGPT Platform Todoist Sections 区块全解析：在 Agent 工作流中读取与清理项目分区

本文围绕 AutoGPT 平台内置的 Todoist Sections 系列区块展开，系统讲解如何在一个可编排的 Agent 流程中按 ID 查询、枚举与删除 Todoist 项目内的分区（Section）。读完本文，你将掌握三个区块（List / Get / Delete Section）的输入输出契约、底层 Todoist API 调用方式、OAuth2 凭据前置条件，并能结合源码把它们拼接进真实的"任务分区整理"自动化场景。

什么是 Todoist Sections 区块

在 AutoGPT 平台中，Block（区块）是构建工作流的最小可执行单元，开发者可以像搭积木一样把不同功能的区块串成 Agent。每个区块定义明确的输入 schema、输出 schema，并由平台运行时驱动其 run() 方法执行。

Todoist 集成属于平台 Productivity（生产力）分类，负责"Tasks and projects"这类任务管理能力（见 provider 注册配置）。官方区块文档目录 docs/integrations/block-integrations/todoist/ 下按资源拆分：projects.md、sections.md、tasks.md、comments.md、labels.md。本文聚焦 sections.md 描述的三个"分区管理"区块。

Todoist 中的 Section 是项目（Project）内部用于分组的横向层级，例如一个"生活管理"项目下可以有 Groceries、Work 等多个 Section。这三个区块共同覆盖了分区的**查询（读）与清理（写）**两类操作：

区块（Block）	能力	源码类
Todoist List Sections	获取某项目下的全部分区	TodoistListSectionsBlock
Todoist Get Section	按 ID 获取单个分区的详情	TodoistGetSectionBlock
Todoist Delete Section	删除一个分区及其下全部任务	TodoistDeleteSectionBlock

它们的实现都集中在 sections.py，内部直接复用第三方 SDK todoist_api_python 提供的 TodoistAPI。

前置条件：Todoist OAuth2 凭据接入

三个分区区块都属于凭据型区块，每个区块的 Input 中都带有一个隐藏的 credentials 字段。从源码看（sections.py），其定义如下：

credentials: TodoistCredentialsInput = TodoistCredentialsField([])

TodoistCredentialsField（定义于 _auth.py）会把该区块要求的授权范围合并进 TodoistOAuthHandler.DEFAULT_SCOPES，并声明"该 Todoist 集成要求 OAuth2 认证"。平台侧完整的 OAuth 处理器在 oauth/todoist.py，其默认授权范围为：

task:add, data:read, data:read_write, data:delete, project:delete

需要特别注意的是 OAuth 处理流程中的两个平台级事实：

• Todoist 不支持令牌刷新（_refresh_tokens 直接原样返回），因此接入时以用户授权的 access token 为准；
• 区块是否可用取决于部署环境是否配置了 OAuth 客户端：源码在构造区块时设置 disabled=not TODOIST_OAUTH_IS_CONFIGURED，而该开关要求环境中存在 todoist_client_id 与 todoist_client_secret 两个密钥（见 _auth.py）。也就是说，如果平台没有正确配置 Todoist OAuth 应用，这三个区块会在工作流编辑器中处于不可用状态。

在 Todoist API 语境下，Section 数据对象主要包含四个字段：id（分区 ID）、project_id（所属项目 ID）、order（在项目内的排序号）、name（分区名），下文所有区块的输出都围绕这套结构展开。

Todoist List Sections：列出项目下的全部分区

文档将其功能概括为"Gets all sections and their details from Todoist"，适合在工作流启动时先探明项目当前的分区布局。

输入参数

参数	类型	必填	说明
project_id	str	否	可选的项目 ID，用于过滤某个项目下的分区

注意：虽然文档表格里把该参数标记为 Yes，但源码（sections.py）中它是 Optional[str]，类型标注为可选，因此运行时允许留空以列出账号可见的分区。此外每个分区区块都带隐式的 OAuth2 credentials 输入。

输出数据

输出	类型	说明
names_list	List[str]	全部分区名称组成的列表
ids_list	List[str]	全部分区 ID 组成的列表
complete_data	List[Dict[str, Any]]	完整分区数据（含全部字段）
error	str	操作失败时的错误信息

该区块一次给出三路并列输出，非常适合下游做"按名称定位"或"按 ID 批量操作"两种分支。从源码实现看（sections.py），其执行逻辑是：

1. 用凭据中的 access_token 实例化 TodoistAPI；
2. 调用 SDK 的 api.get_sections(project_id=project_id) 拉取分区对象；
3. 遍历结果，把每个分区对象的 name、id 与 __dict__ 全量字段分别追加到三份列表；
4. run() 中仅在列表非空时才产出对应输出；任何异常都会统一产出 error 字符串而不是中断整个工作流。

参考返回值示例

源码的测试夹具（test_output）给出了真实形状的可预期结果：

test_output=[
    ("names_list", ["Groceries"]),
    ("ids_list", ["7025"]),
    ("complete_data", [{
        "id": "7025",
        "project_id": "2203306141",
        "order": 1,
        "name": "Groceries",
    }]),
]

可见一个名为 Groceries、排序为 order=1 的分区会出现在 complete_data 中，且 id / project_id 均为字符串类型，order 为整型。

Todoist Get Section：按 ID 读取单个分区详情

文档将其功能概括为"Gets a single section by ID from Todoist"，适合在已经持有分区 ID 的场景下精准回读某个分区的当前状态（例如核对它所属项目是否仍然正确）。

输入参数

参数	类型	必填	说明
section_id	str	是	要获取的分区 ID

输出数据

输出	类型	说明
id	str	分区 ID
project_id	str	分区所属的项目 ID
order	int	分区在项目内的排序序号
name	str	分区名称
error	str	操作失败时的错误信息

从实现看（sections.py），区块调用 api.get_section(section_id=section_id) 取回单个对象后，将其 __dict__ 展开，再按四个键分别产出 id、project_id、order、name。该区块在 IDE 中最自然的连接方式是：把上游 List Sections 的 ids_list 交给"Step Through Items / 列表循环"类逻辑逐项取出，或直接由外层流程注入一个已知的 section_id。

Todoist Delete Section：删除分区及其全部任务

文档将其功能概括为"Deletes a section and all its tasks from Todoist"，并特别提示了破坏性语义：删除分区会连同其中所有任务一并删除。

输入参数

参数	类型	必填	说明
section_id	str	是	要删除的分区 ID

输出数据

输出	类型	说明
success	bool	分区是否删除成功
error	str	操作失败时的错误信息

实现上（sections.py）直接透传 SDK 的 api.delete_section(section_id=section_id) 返回值到 success；一旦 SDK 抛错，则产出 error。正因为该操作不可逆，把它接入工作流时建议遵守两条安全准则：

• 先读后删：上游用 Get Section 或 List Sections 确认目标分区身份，再连到 Delete；
• 配合条件分支：在删除前用文本匹配/条件判断对分区名（如 archive_* 前缀）做白名单校验，避免误删任务。

一个重要的设计边界：当前没有"创建分区"区块

如果你仔细翻看 sections.py，会发现源文件中注释掉了一个 TodoistCreateSectionBlock（Create Section），其注释明确写道：官方 todoist SDK 存在报错，计划改用 sync API 再补回该区块。也就是说：

• 当前平台实际注册并展示的 Todoist Section 区块只有 List / Get / Delete 三个；
• 官方区块总览 README.md 中列出的 Todoist 分区能力也仅包含 Delete / Get / List；
• 若你的工作流需要"新建分区"，现阶段需要借助 Todoist REST API（经 Send Web Request 等通用 HTTP 区块）自行实现，或者等待该区块后续开放。

这一点直接决定了你在设计"自动整理"类 Agent 时的落点：Todoist Sections 系列负责读取现状与清理冗余，而创建动作要绕行通用请求区块。

底层调用链：从区块输入到 Todoist API

把三个区块的源码串起来，可以归纳出它们共享的一套执行骨架：

工作流输入 → Input schema 校验 → run(input_data, credentials)
    → TodoistAPI(access_token) 实例化
    → 调用 SDK 方法（get_sections / get_section / delete_section）
    → 解析返回对象（__dict__）或直接透传
    → yield 输出 or yield "error"

其中值得注意的两个工程细节：

1. 错误不中断：三个区块的 run() 都包在 try/except 里，任何异常都会以 error 输出端子的形式暴露给工作流，供下游做重试或人工介入，而不是让整个 Agent 崩溃；
2. 输出为空则不发：List 区块只在对应列表非空时才产出 names_list / ids_list / complete_data，这意味着空项目不会"推送空列表"给下游。

同时，每个区块的构造参数里都带上了固定 UUID（d6a116d8-...、ea5580e2-...、f0e52eee-...）以及 categories={BlockCategory.PRODUCTIVITY}，这解释了为什么它们会出现在编辑器生产力分类中，也便于对图（graph）持久化时稳定引用这些内置区块。

区块级测试：可验证的行为契约

这三个区块在源码内都内嵌了单元测试契约（见各区块构造中的 test_input / test_output / test_mock），平台可用 mock 凭据对它们做离线验证。例如 Get Section 的测试约定是：

test_input={"credentials": TEST_CREDENTIALS_INPUT, "section_id": "7025"},
test_output=[
    ("id", "7025"),
    ("project_id", "2203306141"),
    ("order", 1),
    ("name", "Groceries"),
],

而 mock 层直接把 api.get_section(...) 替换为返回上述字段的字典，TEST_CREDENTIALS（定义于 _auth.py）则模拟了一个 scope 覆盖 data:read、data:read_write、data:delete、project:delete、task:add 的 OAuth2 凭据对象。如果你要给这些区块写集成测试，这套结构就是现成的参照模板。

实战编排建议：把三个区块串成"分区治理"工作流

综合文档与源码，一个典型的高价值编排是周期性分区巡检与清理 Agent：

1. Todoist List Sections 以目标 project_id 枚举当前分区，得到 names_list / ids_list；
2. 用列表处理逻辑遍历分区，对每个 name 做规则判断（例如是否属于废弃前缀）；
3. 命中规则的 section_id 交给 Todoist Get Section 复核（确认项目归属、排序），再连入 Todoist Delete Section 删除，success=false 时走 error 端子告警。

此外也可以把读类区块与文档目录中同级的 Todoist Get Tasks 组合，在删除分区前先统计其任务数，形成"空分区清理"或"归档迁移"类流程。需要注意：整个分区体系面向的是 Todoist 的读与删，若流程闭环依赖"新建分区/任务归位"，需搭配通用 HTTP 区块直连 Todoist API，直到官方补齐 Create Section 区块。