记录BUG开发violet_agents过程中出现Python的循环导入问题复现在测试violet_agents包时我们输入以下代码测试fromviolet_agentsimportSimpleAgentfromviolet_agentsimportVioletAgentsLLMfromdotenvimportload_dotenv load_dotenv()agentSimpleAgent(namehelloAgent,llmVioletAgentsLLM(providerdeepseek),system_prompt你是一个简单的助手直接回答用户的问题不进行复杂的思考和计划。)responseagent.run(你好1 1 等于多少)print(response.content)运行该文件后会报错报错如下Traceback (most recent call last): File d:\programming\Python\test_violet_agent\main.py, line 1, in module from violet_agents import SimpleAgent File D:\programming\Python\test_violet_agent\.venv\lib\site-packages\violet_agents\__init__.py, line 4, in module from .agents.react_agent import ReactAgent, REACT_PROMPT File D:\programming\Python\test_violet_agent\.venv\lib\site-packages\violet_agents\agents\__init__.py, line 2, in module from .simple_agent import SimpleAgent File D:\programming\Python\test_violet_agent\.venv\lib\site-packages\violet_agents\agents\simple_agent.py, line 4, in module from ..core.config import Config File D:\programming\Python\test_violet_agent\.venv\lib\site-packages\violet_agents\core\__init__.py, line 2, in module from .agent import Agent File D:\programming\Python\test_violet_agent\.venv\lib\site-packages\violet_agents\core\agent.py, line 10, in module from ..tools.registry import ToolRegistry File D:\programming\Python\test_violet_agent\.venv\lib\site-packages\violet_agents\tools\__init__.py, line 3, in module from .builtin import WeatherTool, SkillsTool, SearchToolsTool, TerminalTool File D:\programming\Python\test_violet_agent\.venv\lib\site-packages\violet_agents\tools\builtin\__init__.py, line 4, in module from .search_tools_tool import SearchToolsTool File D:\programming\Python\test_violet_agent\.venv\lib\site-packages\violet_agents\tools\builtin\search_tools_tool.py, line 7, in module from ...core.agent import Agent, SubAgent ImportError: cannot import name Agent from partially initialized module violet_agents.core.agent (most likely due to a circular import) (D:\programming\Python\test_violet_agent\.venv\lib\site-packages\violet_agents\core\agent.py)遇到报错不着急顺藤摸瓜。追踪报错先看报错最后一行明确错误类型和原因ImportError: cannot import name Agent from partially initialized module violet_agents.core.agent (most likely due to a circular import) (D:\programming\Python\test_violet_agent\.venv\lib\site-packages\violet_agents\core\agent.py)错误类型ImportError– 导入失败。具体原因无法从violet_agents.core.agent中导入Agent而且模块处于“部分初始化”状态很可能是因为循环导入circular import。从下往上读定位循环链条Traceback 是从最底层错误发生点向上调用入口排列的最后一行是错误本身而上面每一行都显示了导入过程中的一环。File ...\search_tools_tool.py, line 7, in module from ...core.agent import Agent, SubAgent这里试图从core.agent导入Agent是直接触发错误的地方。再往上看是谁导入了search_tools_tool.pyFile ...\tools\builtin\__init__.py, line 4, in module from .search_tools_tool import SearchToolsToolbuiltin/__init__.py导入了search_tools_tool。继续File ...\tools\__init__.py, line 3, in module from .builtin import WeatherTool, SkillsTool, SearchToolsTool, TerminalTooltools/__init__.py导入了builtin包。再往上File ...\core\agent.py, line 10, in module from ..tools.registry import ToolRegistry我们发现core/agent.py里导入了tools.registry而tools包又导入了builtin包进而导入了search_tools_tool而它又反过来导入core.agent——这就形成了循环。这种情况是间接循环导入由这几个__init__.py把路铺成了闭环简单说就是search_tools_tool.py在执行from ...core.agent import Agent, SubAgent时回头找还没定义完的core/agent.py。解决方法core/agent.py将from ..tools.registry import ToolRegistry从顶层导入移入TYPE_CHECKING块__init__中改用懒加载from ..tools.registry import ToolRegistry as _ToolRegistry消除了core.agent↔tools.builtin.search_tools_tool之间的潜在循环导入修改如下检查/防止循环导入的方法方法一pip install pylint使用命令进行检查pip install pylint pylint src/violet_agents pylint src/violet_agents --disableall --enablecyclic-import方法二pip install import-linter/violet_agentspylint src/violet_agents --disableall --enablecyclic-import### 方法二pip install import-linter 这是大型 Python 项目经常使用的工具。此处不做过多介绍