AutoGPT Platform 迭代块（Step Through Items）完全指南：列表与字典的逐项处理原理、工作流接入与安全限制

AutoGPT Platform 将自动化流程拆解为一个个可复用的"块（Block）"，而 Step Through Items（逐步遍历项） 正是逻辑控制类（Logic and Control Flow）中负责"把一个集合拆成一次次独立处理"的核心迭代块。本指南以其官方文档 iteration.md 与 logic.md 为主线，对照后端真实实现与安全测试，帮助你彻底掌握该块的输入输出契约、底层流式执行原理、批量处理接线方式，以及防止超大规模输入拖垮执行引擎的内置限制。

Step Through Items 是什么：一个把"批量"变"逐个"的控制流块

在 AutoGPT 的块体系中，绝大多数块一次输入、一次输出；但现实业务里你常常需要"对一组客户逐一发邮件"、"把一批任务逐条写入表格"。如果为每条数据手动复制一份下游子图，既不现实也不可维护。Step Through Items 的作用正是把一次运行拆成多次递送：它接收一个列表或字典作为输入，每命中一个元素，就产出一对 Item（当前元素）与 Key（当前下标或字典键）输出。

根据其所属目录 docs/integrations/README.md 的 "Logic and Control Flow" 分类，它与其他条件（Condition）、比较、计数、采样块并列，用于在图中表达"循环/展开"这种控制流语义。在块选择器里它的显示名为 Step Through Items，后端定义位于 autogpt_platform/backend/backend/blocks/iteration.py。

从源码看，它的类定义非常简短：

• 块名：StepThroughItemsBlock；
• 块 ID：f66a3543-28d3-4ab5-8945-9b336371e2ce（见 iteration.py）；
• 分类：BlockCategory.LOGIC；
• 官方描述："Iterates over a list or dictionary and outputs each item."

小提示：同一个块同时在 docs/integrations/block-integrations/iteration.md 与 logic.md 两处文档中登记，两处描述基本一致，本指南以仓库内实际代码为最终事实基准，并在下文指出文档与实现不一致之处。

输入与输出契约：不止一个"Items"，而是三个输入槽

官方单页文档 iteration.md 把输入简写为一个 "Items"，但在实际实现中，为了兼容来自不同上游块的多种数据类型，块面（UI）上会展示三个可选的输入槽（见 iteration.py）：

输入槽	Schema 字段	类型	默认值	说明
Items	items	list	[]（default_factory=list）	直接传入列表，例如 [1, 2, 3, 4, 5]
Items Object	items_object	dict	{}（default_factory=dict）	直接传入字典，例如 {"key1": "value1", "key2": "value2"}
Items String	items_str	str	""	传入 JSON 字符串，块会自动解析成列表或字典

三个字段均标记为 advanced=False，即默认在界面上可见可填。块在执行时会按 items → items_object → items_str 的顺序检查（见 iteration.py），任何一个槽非空就会被处理；换句话说，如果同时填了多个槽，块会依次遍历每一个非空输入，产出多组结果——一般建议每次只使用其中一个输入槽，以免输出顺序超出预期。

输出端口

输出	Schema 字段	类型	说明
Item	item	Any	当前正在处理的元素
Key	key	Any	列表场景下为元素下标（从 0 开始）；字典场景下为当前键名

关于字典 Key 输出：文档与实现的差异

原文档在 iteration.md 与 logic.md 的 "Outputs" 表格中写的是：对于字典，Key 与 Item 相同（即字典的值）。但请以当前仓库源码为准：在 iteration.py 中，字典分支实际执行的是：

for key, value in items.items():
    yield "item", value   # Item = 字典的 value
    yield "key", key      # Key = 字典的 key

源码注释甚至标注了 # Fixed: should yield key, not item，说明该行为曾经过修正——现在字典输入时，Item 输出的是值（value），Key 输出的是键（key）。读者若在官方文档中看到"字典的 Key 与值相同"的描述，应理解为旧版行为描述；对接字段时请以实际运行结果为准，在画布上把上游字典块的键接到这里时，直接使用字典本身的键名即可。

逐元素执行过程：一个流式产出的异步生成器

理解该块的关键是：它的 run() 是一个异步生成器，不是"收完一整个列表后吐一个结果"。

看核心实现 iteration.py：

async def run(self, input_data: Input, **kwargs) -> BlockOutput:
    for data in [input_data.items, input_data.items_object, input_data.items_str]:
        if not data:
            continue
        ...
        if isinstance(items, dict):
            for key, value in items.items():
                yield "item", value
                yield "key", key
        else:
            for index, item in enumerate(items):
                yield "item", item
                yield "key", index

对于列表输入，采用 enumerate，因此 Key 就是 0 开始的下标；对于字典输入，遍历 items() 的键值对，把值作为 Item、键作为 Key 逐个产出。每个元素对应两条连续的 yield（先 item 后 key）。

这与块基类的执行框架完全契合：在 autogpt_platform/backend/backend/blocks/_base.py 中，Block.execute() 用 async for output_name, output_data in self.run(...) 消费这些产出，对每个输出做 schema 校验后向上游执行器转发。也就是说：

• 输出是逐条流式到达的，下游节点无需等整批结束即可开始处理第一个元素；
• 同名输出可以出现多次，这正是"扇出（fan-out）"的基础：连接到 item 输出的下游块会对每一个元素分别执行一次。

一个可验证的输出序列示例

块的构造器里内嵌了自测用的 test_input / test_output（见 iteration.py）。输入 [1, 2, 3, {"key1": "value1", "key2": "value2"}] 时，输出序列精确为：

顺序	输出名	输出值
1	item	1
2	key	0
3	item	2
4	key	1
5	item	3
6	key	2
7	item	{"key1": "value1", "key2": "value2"}
8	key	3

注意最后一项：元素本身也可以是复合结构（这里就是字典），说明块对元素类型没有任何限制，可用来迭代"对象数组"（如一批记录、一批消息）。相应地，test_blocks_dos_vulnerability.py 中的正常路径测试也断言：输入 [1, 2, 3] 时总共产出 6 条输出（每个元素一对 item/key）。

三类输入的实战用法

1. 直接接入上游"生成列表"的块

很多数据处理块（如拆分文本、查询数据库、读取表格）直接输出 Python 列表，此时把它们的输出连到 Items 槽即可。例如读取一批客户记录后，把整张表交给本块逐行处理。

2. 用 JSON 字符串传递数据

当数据来自文本类上游（例如某块只输出字符串、或来自 HTTP 响应体），把 JSON 字符串接到 Items String 槽，块内部会先做字符串大小检查，再用 JSON 解析（见 iteration.py）还原成列表或字典：

[{"name": "Alice"}, {"name": "Bob"}, {"name": "Carol"}]

或

{"[e-mail]": "Alice", "[e-mail]": "Bob"}

如果上游产生的还不是 JSON 字符串，可以先串接一个 JSON 编码类块（相关工具块参见 data.md 的 JSON Encoder / JSON Decoder 条目）再做转换。若 items_str 不是合法 JSON，块会抛出解析异常并在执行日志中显示为可读错误。

3. 处理字典的键值语义

当输入是字典时，如果希望逐条处理"每个键名对应一个值"的数据（例如邮件地址到姓名的映射、消息 ID 到内容的映射），直接连 Items Object 即可：Item 拿值（如姓名），Key 拿键（如邮件地址）——注意前文所述的当前实现行为。

典型业务场景：批量发送个性化邮件

原文档给出的经典用例是：有一批客户姓名，需要对每个客户执行某个动作（例如发送个性化邮件）。在 AutoGPT 的图编辑器中，接线方式为：

1. 用某个数据源块（如表格读取、数据库查询、AI 列表生成）产出一批客户记录；
2. 接到本块的 Items 输入；
3. 把 Item 输出连到下游的邮件 / 通知类块的收件人或内容字段；
4. 由于 Item 会对每个元素各产出一次，下游发送块会被触发多次，从而完成"逐一发送"。

值得特别说明的是它的批量"静态"语义：本块输出的是"展开后的元素流"，且单次运行只遍历一遍输入。如果需求是"对同一个列表反复执行多轮操作直到满足条件"，属于更复杂的循环编排，超出本块能力范围——需要用其他控制流手段（例如在图上结合条件判断与多次触发）实现。

安全边界：防 DoS 的内置上限（务必了解）

迭代块天然存在被超大数据集打爆执行引擎的风险，因此源码里写明了显式的防护逻辑（见 iteration.py），这些数字是当前版本实际生效的硬性限制：

限制项	上限值	触发行为
MAX_ITEMS 单次最大迭代元素数	10,000	列表或字典元素数超过后抛 ValueError: Too many items
MAX_ITEM_SIZE 字符串输入最大长度	1,048,576 字符（1 MB）	JSON 字符串超长时抛 ValueError: Input too large，且解析前检查
迭代中的 iteration_count 兜底	10,000	即使边界判断出现偏差，循环体内也会在超过后 break 中断

对字符串输入，代码会先检查长度、再执行 JSON 解析，避免一次性载入超长文本消耗内存；对列表/字典则在开始遍历前先数长度。这些约束都有专门的回归测试覆盖，位于 test_blocks_dos_vulnerability.py 的 TestStepThroughItemsBlockSecurity 类：

• test_item_count_limits：构造 20,000 个元素的列表，断言抛出匹配 "Too many items" 的 ValueError；
• test_string_size_limits：构造超长 JSON 字符串，断言抛出匹配 "Input too large" 的异常；
• test_normal_iteration_works：输入 [1, 2, 3] 时断言恰好产生 6 条输出，防止防护逻辑误伤正常迭代。

这些测试与该文件同级的其他安全测试（如 XML、正则、文本块的同类限制）共同构成平台块级的 DoS 防护体系。因此在实际使用中，当迭代对象可能超过万级时，应先在上游做分片/采样/分批（同分类下也有 Data Sampling 等块可参考），把单次交给本块的数据量控制在安全范围内。

在代码库中自行验证与二次开发

如果你希望在本地确认或扩展它的行为，可以关注以下仓库路径：

• 块本体：autogpt_platform/backend/backend/blocks/iteration.py——包含 Schema、构造器自测数据与 run() 全逻辑；
• 执行框架：autogpt_platform/backend/backend/blocks/_base.py——execute() 如何流式消费块的多次产出；
• 安全回归测试：autogpt_platform/backend/backend/blocks/test/test_blocks_dos_vulnerability.py；
• 块总览与分类入口：docs/integrations/README.md 的 "Logic and Control Flow" 一节；
• 若想仿照它编写自己的迭代/批处理块，可参考 Block SDK 指南 中的块定义与 SchemaField 约定。

小结

Step Through Items 是 AutoGPT Platform 工作流中把"集合输入"翻译成"逐条执行流"的枢纽块：理解它的三个输入槽（列表 / 字典 / JSON 字符串）、Item+Key 的成对输出语义（特别是字典场景下 Key 输出的是键名）、基于异步生成器的流式扇出机制，以及 10,000 元素 / 1 MB 的安全硬限制，就能在批量通知、批量写入、逐条 AI 处理等场景中准确接线，并避免误用引发的大数据量执行问题。