AutoGPT Platform 数学运算块详解：Calculator 与 Count Items 的用法与源码解析

AutoGPT Platform（本仓库 autogpt_platform）以可视化「Block（块）」为核心，让用户把 AI 能力、数据处理与程序逻辑组装成 Agent。本文聚焦其中两个最常用的逻辑数学类块——Calculator（两数计算）与 Count Items（集合计数），结合源码带你彻底掌握它们的输入输出契约、边界行为（除零、非可迭代对象等）以及如何在 Agent 流程中正确编排。读完本文，你将能直接在自己的 Agent 中使用这两个块完成百分比计算、列表计数等常见任务，并理解其底层实现与测试验证机制。

---

1. 定位：属于 LOGIC 逻辑分类的基础块

在本仓库的 Block 体系中，每个块都有一个分类标记。在 backend/blocks/_base.py 中定义了全部 BlockCategory，其中：

LOGIC = "Programming logic to control the flow of your agent"

即「用于控制 Agent 流程的程序逻辑」。Calculator 与 Count Items 两个块在源码中均以 categories={BlockCategory.LOGIC} 声明，它们不调用 AI、不访问网络，而是对流入的数据做纯计算变换，因此常被用在数据加工、结果校验、条件分支（配合 ai_condition / branching 等块）之前的数值预处理环节。

官方块索引文档 docs/integrations/README.md 将二者归类于逻辑（Logic）分组下，与 logic.md 中描述的块互为补充，而本文详细讲解的两块源码同处一个文件中：backend/blocks/maths.py。

2. Calculator：对两个数执行数学运算

2.1 功能概览

Calculator 接收两个数值与一个运算方式作为输入，执行加、减、乘、除或幂运算，并可选地把结果四舍五入为整数，最终输出一个数值结果 Result。

该块的完整定义位于 maths.py，其固定块 ID 为 b1ab9b19-67a6-406d-abf5-2dba76d00c79（该 ID 会被持久化到 Graph 的节点定义中，用于运行时定位实现）。

2.2 输入参数

输入	描述	取值 / 默认值（源码视角）
Operation	选择要执行的数学运算	Add、Subtract、Multiply、Divide、Power，对应源码中 Operation 枚举的五个成员（见 maths.py L15-L21）
A	参与计算的第一个数字	float 类型，SchemaField placeholder 示例为 10
B	参与计算的第二个数字	float 类型，placeholder 示例为 5
Round result	是否把结果取整为整数	bool 类型，默认值 False（见 maths.py L35-L38）

说明：A 与 B 在输入模式中被建模为 float，因此你填入整数或小数均可；即使填入的是字符串形式，在编排器中也会按该块的输入类型约定转换处理。

2.3 输出参数

输出	描述
Result	计算得到的数值结果

2.4 底层实现与运行语义

run() 的核心实现非常直观——它用一个字典把五个运算枚举值映射到 Python 标准库 operator 模块的函数上：

operations = {
    Operation.ADD: operator.add,
    Operation.SUBTRACT: operator.sub,
    Operation.MULTIPLY: operator.mul,
    Operation.DIVIDE: operator.truediv,
    Operation.POWER: operator.pow,
}
op_func = operations[operation]
result = op_func(a, b)
if input_data.round_result:
    result = round(result)
yield "result", result

需要特别留意的三点边界语义（这些并未写入原文档，但决定了你使用时的预期）：

1. 除法是浮点真除（truediv）：5 ÷ 2 会得到 2.5，而非整数截断；
2. 除零不抛错，而是输出无穷大：当运算为 Divide 且 B 为 0 时，显式触发 ZeroDivisionError，随后被捕获并 yield "result", float("inf")，返回 inf 表示除零；
3. 其余异常统一输出 NaN：例如两个非法数值参与计算时，会 yield "result", float("nan")。

源码实现参考 maths.py L61-L90。由于块运行是异步生成器（async def + yield），其产物是一个可被执行器逐个消费的 (字段名, 值) 序列，这也是本平台所有 Block 的统一输出约定。

2.5 典型使用场景

• 快速算术：把某个采集到的数值（例如订单金额）加上税率后再输出给下游块使用；
• 百分比换算：要计算「80 的 15%」时，可令 Operation = Multiply、A = 80、B = 0.15；若想得到整数百分比结果，则勾选 Round result；
• 幂运算：如计算面积或复利场景，选择 Power 即可。

3. Count Items：统计集合中元素数量

3.1 功能概览

Count Items 接收一个集合（collection），返回集合内元素个数。这里的集合可以是列表、字典、字符串或任何可迭代对象。

该块定义于 maths.py L93-L130，固定块 ID 为 3c9c2f42-b0c3-435f-ba35-05f7a25c772a。

3.2 输入参数

输入	描述
Collection	需要计数的集合，例如列表 [1, 2, 3]、字典 {'a': 1, 'b': 2} 或字符串 'hello'

输入字段类型被声明为 Any（见 maths.py L94-L98），placeholder 中给出了三种最常见形态的示例。

3.3 输出参数

输出	描述
Count	集合中元素的数量

3.4 底层实现与类型分支

原文档描述了「先判断类型、再用合适方法计数」的逻辑，源码将其精确实现为两条路径：

if isinstance(collection, (str, list, tuple, set, dict)):
    count = len(collection)          # 直接求长度，O(1)
elif hasattr(collection, "__iter__"):
    count = sum(1 for _ in collection)  # 逐项迭代计数
else:
    raise ValueError("Input is not a countable collection")

值得展开的细节：

• 内置容器走 len()：字符串按字符计数（'hello' → 5），列表/元组按元素计数，set 按去重后的元素计数，dict 则统计键的数量；
• 其他可迭代对象逐项累加：例如生成器、range、自定义迭代器会被 sum(1 for _ in collection) 消费一遍，因此这类对象在计数后即被耗尽，若后续还期望它提供数据则需注意；
• 错误兜底返回 -1：当输入既不是内置容器也没有 __iter__ 时，不会中断流程，而是 yield "count", -1 作为错误信号（与 Calculator 返回 NaN/inf 的容错风格一致，见 maths.py L129-L130）。

3.5 典型使用场景

当 AI 块或上游数据块返回一组名单、标签、搜索结果时，可以用本块统计数量，例如：

• 统计某个列表里共有多少客户名，用于后续批量处理或阈值判断；
• 用「搜索结果数」驱动分支逻辑：数量为 0 走「未找到」分支，否则进入详情处理。

4. 编排实战：把数学块接入 Agent 流程

在 AutoGPT Platform 的可视化编排器（Builder）中，数学块与其他块的使用方式一致：

1. 从块面板的 Logic / 逻辑 分组下拖入 Calculator 或 Count Items；
2. 通过连接线把上游块的数据输出连接到对应输入槽（如把查询返回的列表接到 Collection，或把数值接到 A、B）；
3. 配置运算参数并运行，把 Result / Count 输出继续连给下游文本生成、条件判断或输出块。

作为佐证，仓库的端到端测试数据中就有使用这两个块的示例：E2E_MARKETPLACE_AGENT_NAME = "E2E Calculator Agent"（见 test/e2e_test_data.py），该文件在构造测试 Agent 时显式创建 CalculatorBlock()，并把 CalculatorBlock 作为图中的节点参与执行（见 test/e2e_test_data.py L256-L262 及 L363 附近的节点定义逻辑），说明这两个块完全可用于端到端流程而非仅限简单演示。

5. 从源码验证行为：内置测试输入与执行器

这两个块并非「写完即弃」，它们自带 test_input / test_output，可被统一测试机制自动执行：

• CalculatorBlock 的测试样例为 ADD 下 10 + 5 = 15.0；
• CountItemsBlock 的测试样例为 [1, 2, 3, 4, 5] → 5。

平台提供了统一的 execute_block_test(block) 工具（见 backend/util/test.py L107），它会读取块的 test_input 运行 run()，并把实际输出与 test_output 逐项比对；每个块都需在仓库中被 import 一次以触发冒烟自检。甚至安装自定义代码块的 BlockInstallationBlock（见 backend/blocks/block.py）在写入新块代码后也会调用 execute_block_test 做即时校验。也就是说，你在给块添加测试样例后，跑一轮块加载即可自动确认加减乘除与计数逻辑是否按预期工作。

6. 使用注意事项小结

把上面的源码语义归纳为一张「行为速查」，便于在实际编排中避坑：

场景	行为
Calculator 除数为 0	不报错，Result = inf
Calculator 出现其他异常（非法数值等）	Result = NaN
Calculator 勾选 Round result	使用 Python 内置 round() 取整到最近的整数
Count Items 输入 list/dict/set/str/tuple	分别统计元素数、键数、去重元素数、字符数与元素数
Count Items 输入生成器等可迭代对象	逐项计数（会消费该迭代器）
Count Items 输入不可计数的对象	Count = -1，表示错误

7. 延伸阅读

• 完整文档：maths.md（本文讲解的官方入口）
• 逻辑块文档：logic.md
• 块索引总览：docs/integrations/README.md
• 核心源码：backend/blocks/maths.py
• Block 基类与分类定义：backend/blocks/_base.py
• 块测试执行器：backend/util/test.py
• 端到端测试样例：test/e2e_test_data.py

若需要在流程中基于计算结果做更复杂的条件分流，可进一步了解同属逻辑分组的 ai_condition 与 branching 块，它们与数学块配合即可搭建出「先计算、再判断、后执行」的完整 Agent 控制流。