企业官网建设流程全解析

GOD（Govern, Observe, Direct）是一个面向 Agent 群体（Agent Societies）的实时控制室（Control Room），其核心框架AgentSociety 2通过"环境系统（Environment Modules）+ 推理路由（Router）"两大组件，让 LLM 智能体能够感知虚拟世界、调用工具并修改环境状态。本文将从新手视角完整拆解 GOD 的环境系统架构，横向对比ReActRouter、PlanExecuteRouter、CodeGenRouter三种推理路由策略的工作原理与适用场景，帮你快速理解智能体究竟是如何"看懂"并"操作"模拟世界的。

一、GOD 的"大脑"：环境与智能体如何协作

在 GOD 的架构中，系统分为三层：

智能体从不直接触碰环境代码，而是把一条自然语言指令交给Router（路由器）；路由器负责把它翻译成对@tool函数的真实调用，再把结果喂回给智能体。这正是 GOD 环境系统的精髓所在——智能体与环境的解耦。

二、环境系统解剖：EnvBase 与 @tool 装饰器

环境模块的基类是EnvBase，其定义位于 env/base.py。开发者只需要用@tool装饰器标记普通 Python 函数，就能把它"发布"给智能体使用：

• readonly=True：只读工具，不改变环境状态（观察类）
• readonly=False：可写工具，会修改环境状态
• kind="observe"：单参数（agent_id）的观察工具，可被自动聚合调用
• kind="statistics"：无参数的聚合统计查询

工具的元信息会被统一收集进ToolsInfoDict，供路由器在生成提示词、选择函数时检索。这套设计让新增一个环境模块完全不需要改动智能体代码——模块组合即世界能力。

三、三大推理路由范式原理对比

所有路由器都继承自抽象基类 RouterBase，它统一管理 LLM 调用（含限流指数退避重试、token 统计）、仿真时钟推进和ask()统一入口。三种主流路由策略的差异，就在于**"如何把自然语言指令变成工具调用"**。

1. ReActRouter：边想边做的推理-行动循环

源码：router_react.py

ReAct（Reasoning + Acting）是最经典的范式：LLM 在"推理 → 行动"的循环中逐步选择 function calling 工具：

1. 收集所有环境模块的工具 schema
2. LLM 推理出下一步该调哪个工具并发起调用
3. 执行工具，把结果反馈给 LLM
4. 重复循环，直到 LLM 调用内置的set_status工具宣布success/fail，或达到max_steps

特点：每一步都有全局视角、能根据中间结果灵活调整；但多步任务会累积 LLM 调用次数，token 成本较高。

2. PlanExecuteRouter：先规划、后执行

源码：router_plan_execute.py

Plan-and-Execute 把过程切成两个阶段：

• 阶段一（规划）：LLM 只"看"工具清单，不执行任何调用，先产出一份完整的分步计划
• 阶段二（执行）：按计划逐步调用工具，最后汇总生成答案

特点：对目标明确的多步骤复杂任务（例如"组织一场拍卖模拟"）更稳定、可解释性强，规划过程可以在执行前人工审查。

3. CodeGenRouter：让 LLM 写代码来干活

源码：router_codegen.py

这是 GOD 的默认主力路由。它不走 function calling，而是让 LLM 直接生成一段 Python 代码来调用所有@tool接口，再在沙箱中执行：

1. 把所有工具格式化为类似.pyi存根的签名文档喂给 LLM
2. LLM 生成调用代码
3. AST 安全校验：解析语法树，黑名单拦截eval/exec/compile、危险模块（os、subprocess、socket等）与危险 AST 节点（类定义、with 语句等）
4. 受限沙箱执行：只开放math、numpy、collections等白名单模块和受限 builtins，10 秒超时
5. 根据执行结果与打印输出生成最终自然语言回复

一图看懂三种路由的差异

四、CodeGenRouter 的工程细节：三级代码获取责任链

CodeGenRouter 并非每次都要现找 LLM 要代码。它内部采用责任链模式获取代码，优先级为：

PredefinedCode → Cache → LLM

• Predefined：<observe>、<statistics>等内置指令直接命中预定义代码，零 LLM 成本
• Cache：模板指令（含{var}变量）会经向量相似度匹配（阈值template_cache_similarity_threshold=0.85）命中历史缓存条目，缓存库默认存放在codegen_router_cache目录
• LLM：未命中才调用 coder 模型生成，失败时会把执行错误反馈回 LLM 自动重试

配合 router_codegen.py 中的CacheStats，可观测缓存命中率、代码执行成功率、平均重试次数等指标。这套机制是 GOD 能支撑大规模智能体社会（几十上百个智能体高频请求）的关键优化。

五、进阶路由：TwoTier 与 SearchTool

当环境模块数量很多时，把所有工具平铺进提示词会膨胀上下文，GOD 提供了两种"降维"策略：

• TwoTierReActRouter（router_two_tier_react.py）：第一层先让 LLM 选中目标模块，第二层才在该模块内部做 ReAct 循环，支持跨模块接力
• SearchToolRouter（router_search_tool.py）：提供一个search_tool作为"工具搜索器"，LLM 先搜索候选函数再调用，天然适配海量工具场景

此外还有两层规划版 router_two_tier_plan_execute.py，完整清单可在 env/init.py 中查看。

六、如何为实验选择正确的 Router？

官方在 examples/advanced/02_multi_router.py 中用同一道"分苹果"题和"拍卖模拟"题对三种路由做了对照演示，其总结可直接作为选型参考：

• 需要迭代式推理与观察→ ReAct
• 目标清晰的多步骤任务→ Plan-Execute
• 可用代码/计算解决的问题→ CodeGen

而路由质量的量化评测由 env_benchmark.py 完成：它用工具选择 IOU、调用序列 LCS 分数、参数准确率、完全成功调用四项指标，对比各路由器在标准指令集上的表现，让路由策略的优劣可以用数据说话。

七、快速上手：三步跑通多路由演示

1. 进入包目录并安装依赖：cd agentsociety/packages/agentsociety2，用uv sync（项目提供 uv.lock）
2. 配置.env中的 LLM 密钥（coder 模型用于路由，default 模型用于摘要，见 config/）
3. 运行python examples/advanced/02_multi_router.py，即可看到三种 Router 对同一指令的不同执行轨迹

更完整的概念说明（含架构图）见官方文档 docs/concepts.rst 与 docs/env_modules.rst。

总结

GOD 的环境系统通过EnvBase+@tool实现了智能体与世界的彻底解耦，而 ReAct、Plan-Execute、CodeGen 三种推理路由则提供了从"灵活交互"到"计划驱动"再到"代码生成"的完整谱系。理解它们的原理，你既能看懂 GOD 控制室里每一次智能体动作背后的调用链路，也能在自己的智能体社会实验中为不同场景挑选最合适的"大脑"。