Skip to content

Chain 思维链

Chain 的目标是按照既定的逻辑结构来解决具体问题。它通过有穷状态机管理思考（thinking）、执行（doing）、成功（succeeded）、失败（failed）等状态，确保每次 LLM 解决任务时不会遗漏关键步骤，也不会跑偏。举例来说，像 git commit 过程：先执行 git status，再执行 diff，最后 commit。虽然目前还没有遇到「非 Chain 不可」的场景，但 Chain 的存在极大地提升了封装效率。比如在 IDELlama 项目中，Validator 的封装便是直接基于 Chain 实现，因为其工作特性不依赖于大量的工具，同时也没有必要强行封装成一个 TFRobot 工具，因此 Chain 的体量是一个比较合适的选择。

生命周期与状态流转

  1. condition_think → before_think → on_enter_thinking：校验是否达成思考条件、触发 LLM 生成内容并记录生成次数，再把最新的 LLM 输出放入中间消息列表。此阶段还会依据 max_iterations、warning_prompt 与 warning_threshold 触发预警，或在 output_schema 存在时先尝试提取合法 JSON。
  2. condition_do → before_do → on_enter_doing：判断大模型是否请求工具调用或存在迭代输出，随后优先通过神经系统 Neural 请求远程工具执行，若无返回则降级到本地 MiniDrive。执行完成后将工具返回包装成消息供下一次思考使用，并支持 tfl 脚本（tfl_scripts）即时执行。
  3. condition_succeed / condition_fail：在所有工具完成后校验 LLM 输出是否满足 output_schema 或 validate_result。若未满足，会把提示消息追加到对话上下文中以便 LLM 自我修正。成功收敛时会在 after_succeed 中缓存 JSON 结果，必要时写入 _CHAINS_INTERMEDIATE_RESULTS 供后续链路复用。
  4. Neural 协同与异步支持：每个同步方法均有 async_ 对应版本，确保在异步环境中保持一致的状态机行为；connect_to_neural/disconnect_from_neural 用于在运行期注册或注销神经系统并复用其工具目录。

Chain 配置参数介绍

Chain 的可配置参数如下：

参数 类型 说明 默认值
name ClassVar[str] Chain 的名称 Chain
description ClassVar[str] Chain 的描述 最基础的思维链封装。实现基于 LLM 与 Transitions 的循环调用与生命周期管理
llm BaseLLM 当前思维链使用的大模型封装
max_iterations int 最大迭代次数，超过后会抛出 TFProtocolError 并终止 10
max_tokens int 在单次 run 调用内允许累计消耗的最大 Token 数量，超过后抛出 TFTokenLimitError 128,000
warning_prompt Optional[dict[Literal["iterations", "token"], BasePrompt]] 靠近阈值时额外插入的预警 Prompt，与 warning_threshold 搭配使用，仅对 ChatLLM 生效 None
warning_threshold Optional[dict[Literal["iterations", "token"], int]] 触发预警 Prompt 的阈值。支持传入负数以表示「距上限多少」的提醒逻辑 None
tool_response_instructions Optional[str] 如果指定，会在工具返回消息前追加 System 说明，常用于告知 LLM 某个工具的流式/持续返回特性 有些工具会以 Iterator 迭代器的形式持续返回，如果你已经解决完问题或者已经拿到自己需要的信息，可以调用 Stop 相关工具将其关闭
response_format Optional[LLMResponseFormat] Chain 对 LLM 输出格式的硬性约束，支持 text、json_object、json_schema，会覆盖底层 LLM 的设定 None
output_schema Optional[dict \| TypeAdapter \| Type[BaseModel]] 由 response_format 推导出的 JSON Schema。如果为 json_schema/json_object 会返回实际 schema，否则为 None None
validate_result Optional[Callable[[ChainResult], tuple[bool, Optional[BaseMessage]]]] 结果验证回调，自定义二次校验逻辑。当返回 False 时会把额外提示写入上下文，并触发下一轮自我提问 None
warn_recursive_calls bool 拦截重复工具调用，防止 LLM 递归地重复执行同一工具。拦截逻辑会参考工具返回的 duplicate_call_warn 标记 True
catch_intermediate_chain_result bool 是否把成功输出写入 current_input.additional_kwargs[_CHAINS_INTERMEDIATE_RESULTS]，用于跨链共享中间产物 True
result_cache_key Optional[str] 当输出是字符串时，自定义缓存 Key，配合 catch_intermediate_chain_result 将结果封装成字典后写入上下文 None

各个配置项说明

  1. 类的静态参数：name 与 description 主要用于描述实例能力，可通过 instance_description 属性得到完整句式。
  2. llm：Chain 中使用的大语言模型对象。其 additional_kwargs_schema 会直接暴露在 Chain，同步提示链上下游准备好必要的元数据。
  3. max_iterations / max_tokens：双限位策略，避免模型长时间自问自答或在单次调用内消耗异常 Token。靠近阈值时可搭配预警 Prompt。
  4. 预警组合（warning_prompt + warning_threshold）：仅对聊天类 LLM 生效。可分别就迭代次数或 Token 消耗设置不同的提醒策略，整数表示绝对阈值，负数表示“距上限剩余多少”。
  5. tool_response_instructions：当工具返回迭代器或流式结果时，Chain 会先插入带提示的工具消息，帮助 LLM 判断是否继续等待或显式停止工具。
  6. response_format 与 output_schema：前者用来描述期望的结果结构，Chain 会在 condition_succeed 中对结果做 JSON 提取、校验，并把结构化数据同步到消息的 additional_kwargs。
  7. validate_result：适合实现业务层校验（例如字段间的联动关系）。当校验失败时可返回额外的 BaseMessage，以系统消息形式提示 LLM 如何修正上一次输出。
  8. warn_recursive_calls：block_recursive_call 会检查历史工具调用树，只对被标注 duplicate_call_warn=True 的工具返回触发警告，允许 LLM 在确认后再次调用。
  9. catch_intermediate_chain_result / result_cache_key：成功状态下对 JSON 结果或指定 Key 的字符串做缓存，写入 _CHAINS_INTERMEDIATE_RESULTS 方便后续 Chain 读取。若结果是字符串需手动提供 Key。

运行时行为细节

  1. 工具执行优先级：若已连接神经系统 (Neural)，before_do 会优先通过 signal.send/send_async 请求工具执行；否则回退到本地 MiniDrive。所有异常都会被包装成 ToolReturn 并标记 success=False。
  2. 迭代工具与生成器：Chain 支持 Iterator/AsyncIterator 作为工具返回，通过 IteratorToolReturnTuple 分批写回，避免一次性拉取大结果。
  3. TFL 脚本执行：当 LLM 在生成中返回 tfl_scripts 时，会即时编译并执行脚本，执行结果写入 console_reses，并在重复调用时提示 LLM 减少冗余。
  4. 输出与缓存：condition_succeed 会尝试将自然语言中的 JSON 片段提取成结构化数据；after_succeed 则负责把最终结果写入 _CHAINS_INTERMEDIATE_RESULTS。
  5. 异常分类：流程中可能抛出 TFProtocolError（如迭代/Token 限制、工具定义错误）、TFTokenLimitError（Token 超限）、TFChainError（输出不合法或无法进入失败状态）。

使用建议

  • 在需要多轮自问自答、跨工具协作或强格式输出的场景中优先考虑使用 Chain，能显著降低 Prompt 模板的复杂度。
  • 为长期运行的 Chain 设置 max_iterations 与 max_tokens 并搭配预警 Prompt，可提前提醒 LLM 改变策略，减少无效消耗。
  • 若需要在多个 Chain 间共享上下文或工具结果，建议开启 catch_intermediate_chain_result 并约定好 result_cache_key，让后续链路直接读取结构化数据。

Chain 运算结果缓存

Chain在运行成功时，可以将其运行结果缓存至CurrentInput.AdditionalInfo中。缓存策略如下：

前提条件：

  1. 运行成功。因为真正的缓存逻辑在 after_succeed 中执行
  2. catch_intermediate_chain_result 配置为打开状态
  3. 当前Chain运行返回结果为dict状态，或者配置了 result_cache_key

缓存结果：

  1. 在前序缓存的基础上，通过python dict update能力将当前输出缓存
  2. 需要注意的是如果输出键相同，会存在覆盖问题