不用怀疑，看到 hermes-agent 这个标题的第一眼，我的反应是：这名字起得漂亮。Hermes 在希腊神话里是信使之神，负责传递消息、引导旅人、穿梭于诸神与凡人之间。放在 AI Agent 这个语境里，几乎就是“智能体应该长什么样”的标准答案——一个能听、能说、能跑腿、能自己规划路径并执行任务的中枢。
我这次要聊的项目就叫 hermes-agent。它不是一个开箱即用的商业产品，而是一套我自己从头设计并实现的智能体框架，目标很朴素：让大模型不再只是“聊天框”，而是真正能调用工具、操作数据、完成多步任务的执行者。适合正在用 LangChain、AutoGPT 这类工具但总觉得“差点意思”，或者想搞懂 Agent 底层原理、准备自己写一套轻量级智能体体系的开发者参考。
整个项目做下来，最大的体会是：Agent 的难点从来不在“接一个大模型 API”，而在工程化。模型输出不稳定、工具调用格式对不上、上下文越滚越乱、任务跑到一半卡死……这些问题，网上教程基本不会告诉你。这篇文章我就按自己的实操路径，把 hermes-agent 的完整设计思路、核心代码、调试技巧和踩坑记录全部拆开讲。
1. 项目定位：为什么需要一个叫 Hermes 的智能体
1.1 名字背后的设计哲学
做这个项目之前，我花了两周时间调研市面上的 Agent 框架。LangChain 功能全，但抽象层级太多，出了 bug 你根本不知道是在哪一层挂的；AutoGPT 看起来很自动，但 token 消耗像流水，跑一个简单任务能调几十次模型；微软的 Semantic Kernel 偏重企业集成，小项目用起来反而笨重。
所以 hermes-agent 的设计哲学从一开始就很明确：不追求大而全，而是把核心流程做透明、做可控。所谓“信使”，就是让它负责三件事——理解意图、规划步骤、执行工具调用并返回结果。而这三件事，全部围绕一个主循环来转。
我在项目 README 里写的第一句话是：Hermes 不是一个框架，而是一个你可以完全读懂的 Agent 骨架。任何开发者拿到代码后，能在半小时内搞清楚“消息从哪里来、经过什么处理、到哪里去”，这就够了。
1.2 Agent 领域的核心痛点
说实话，2024 年后 Agent 这个概念被炒得有点过头了。很多人以为 Agent 就是“大模型加个 prompt”，实际上模型本身只是一个决策器，真正让 Agent“活”起来的是它周围的那套机制。
举一个我自己踩过的例子。最早我做的第一版 Agent，只做了一件事：把用户的请求拼接进 prompt，让模型直接输出答案。结果用户说“帮我查一下明天的天气然后发到群里”，模型一本正经地告诉我“明天晴转多云，适合出门”，但根本不会真的去调天气 API，更别提发消息到群里了。
这就是 Agent 与传统聊天机器人的本质区别：聊天机器人只需要“生成文字”，而 Agent 必须“生成行动”。模型需要输出结构化的指令，比如“我要调用 weather.query 这个工具，参数是北京”，然后由代码去真正执行这个工具，再把结果反馈给模型，让它决定下一步做什么。
hermes-agent 解决的就是这个闭环——从自然语言到结构化意图、从结构化意图到真实工具调用、从工具结果再回到自然语言决策。整个循环，我管它叫“感知-决策-执行-反馈”。
1.3 自己动手写的三个理由
可能有朋友会问：有现成的框架不用，为什么要自讨苦吃？我的理由有三个，每一个都是实操中真实遇到的问题。
第一，排查问题需要透明链路。用 LangChain 的时候，链式调用报错后，堆栈信息能绕三圈。自己写的框架，每一行代码都在掌控中，出问题十分钟内定位。第二，token 成本可控。商用框架为了兼容各种场景，常常会往 prompt 里塞大量模板文本，这些可都是白花花的 token。自己实现可以把系统提示词压缩到极致，跑长任务时能省不少钱。第三，后续扩展不受限制。我想加一个本地知识库检索工具、想接入公司内部的 RPA 系统、想让 Agent 学会调用数据库——自己的框架改起来跟呼吸一样自然。
这不是说商用框架不好，而是如果你像我一样，对 Agent 的每个环节都有强定制需求，从零开始其实是更高效的选择。
2. 核心模块拆解：一个能“跑起来”的 Agent 由哪些部分组成
hermes-agent 的整体架构，我把它分成了五个相互独立的模块：模型接入层、工具注册中心、上下文管理器、任务规划器、执行循环。下面逐个展开讲，每个模块我都会说明设计原因和具体实现细节。
2.1 模型接入层：为什么我不直接写死 OpenAI SDK
第一版 hermes-agent 是直接调用 OpenAI SDK 的，用了半个月我就后悔了。原因很现实：不同任务的成本要求不一样。简单问答用 GPT-4o 纯属浪费，需要推理的任务用轻量模型又经常翻车。
所以我在模型接入层做了一个统一的调用接口，底层可以自由切换不同模型服务商。核心抽象就是这个call_llm函数，它接收消息列表和可选的工具定义，返回模型的文本回复或工具调用指令。
# hermes/llm.py from abc import ABC, abstractmethod from typing import Any class LLMClient(ABC): @abstractmethod def chat(self, messages: list[dict], tools: list[dict] | None = None) -> Any: pass class OpenAICompatibleClient(LLMClient): def __init__(self, base_url: str, api_key: str, model: str, **kwargs): self.base_url = base_url self.api_key = api_key self.model = model # 这里预留额外参数，比如 temperature、max_tokens、timeout self.extra_params = kwargs def chat(self, messages, tools=None): # 统一的请求封装，兼容 OpenAI 格式的任意服务 pass这块设计有一个关键细节：tools这个参数是可选的。也就是说，模型不是每次调用都需要“携带工具”的。在不需要工具支持的纯问答环节，不传tools能减少大量 token 消耗，也让模型回复更稳定。我实测过，同样的对话，带 5 个工具定义时，prompt 会增加大约 2000 个 token；如果每轮循环都带上这 2000 个 token，跑十轮就是两万 token 的额外开销。
2.2 工具注册中心：Agent 的手脚
如果说大模型是 Agent 的大脑，那工具就是它的手脚。hermes-agent 里最核心的设计就是工具注册机制。每个工具只需要用装饰器声明一下，就能被 Agent 自动识别和调用。
# hermes/tools.py import inspect import json from typing import Callable, Any class ToolRegistry: def __init__(self): self._tools = {} def register(self, func: Callable, name: str = None, description: str = None): """注册一个函数为可被 Agent 调用的工具""" tool_name = name or func.__name__ sign = inspect.signature(func) params = {} for param_name, param in sign.parameters.items(): params[param_name] = { "type": "string", # 简易实现中全部视为 string "description": param.annotation if param.annotation != inspect.Parameter.empty else "" } self._tools[tool_name] = { "function": func, "schema": { "type": "function", "function": { "name": tool_name, "description": description or func.__doc__ or "", "parameters": { "type": "object", "properties": params, "required": list(params.keys()) } } } } return func def execute(self, name: str, args: dict) -> Any: if name not in self._tools: raise KeyError(f"工具 {name} 未注册") return self._tools[name]["function"](**args) def schemas(self) -> list[dict]: return [tool["schema"] for tool in self._tools.values()] registry = ToolRegistry()注意看这里的关键点：工具的参数描述是通过inspect.signature自动解析的。这样做的好处是，你不需要为每个工具手写一份 JSON Schema，函数的参数注释直接变成描述信息。在实操中发现，参数描述的质量直接决定模型调用工具的准确率。比如一个函数参数叫city，如果你注释里写“城市名称，如北京市”，模型几乎不会搞错；如果只写“城市”，模型有时候会传完整的地址过来。
2.3 上下文管理器：决定 Agent 聪明不聪明
很多 Agent 项目跑着跑着就“失忆”了，或者前后矛盾，核心问题都出在上下文管理上。hermes-agent 的上下文管理器，逻辑很简单：永远维护一个消息列表，保留系统提示词、最近的对话记录、以及工具调用的结果摘要。
# hermes/context.py class ContextManager: def __init__(self, system_prompt: str, max_messages: int = 30): self.system_prompt = system_prompt self.max_messages = max_messages self.messages: list[dict] = [{"role": "system", "content": system_prompt}] def add_user_message(self, content: str): self.messages.append({"role": "user", "content": content}) def add_assistant_message(self, content: str): self.messages.append({"role": "assistant", "content": content}) def add_tool_result(self, tool_call_id: str, name: str, result: str): self.messages.append({ "role": "tool", "tool_call_id": tool_call_id, "name": name, "content": result }) def trim_if_needed(self): """当消息超过阈值时，删除最古老的对话轮次（保留 system 和最近的消息）""" if len(self.messages) > self.max_messages: keep = self.messages[:1] + self.messages[-(self.max_messages - 1):] self.messages = keep def get_messages(self) -> list[dict]: return self.messagesmax_messages这个参数是我反复调出来的。设太大，长任务跑到后面 token 爆炸，一次请求可能塞爆模型上下文窗口；设太小，Agent 会丢失早期的关键信息。以 128K 上下文的模型为例，我通常设 30 条消息左右，大约对应 5 到 8 轮完整的人机交互和工具调用，既保证有足够的历史信息做决策，又不会触达上下文上限。
2.4 任务规划器与执行循环：从单轮到多步
这是整个 Agent 最核心的部分。早期版本我用的是“单轮工具调用”模式：用户问一句，模型决定调什么工具，返回结果，结束。但真实场景根本不是这样，比如“对比北京和上海明天的天气，然后推荐一个适合出差的城市”就需要先调两次天气查询，再基于结果做一次推荐。
hermes-agent 的执行循环采用了while True+ 终止条件判定的模式。每轮循环做四件事：把消息发给模型、判断模型返回的是文字还是工具调用、如果是工具调用则执行并把结果追加到上下文、如果是文字且有明确结论则退出循环。
# hermes/agent.py class HermesAgent: def __init__(self, llm_client, registry, context: ContextManager, max_iterations: int = 10): self.llm = llm_client self.registry = registry self.context = context self.max_iterations = max_iterations def run(self, user_input: str) -> str: self.context.add_user_message(user_input) iterations = 0 while iterations < self.max_iterations: response = self.llm.chat( messages=self.context.get_messages(), tools=self.registry.schemas() ) message = response["message"] tool_calls = message.get("tool_calls", []) if not tool_calls: # 没有工具调用，说明模型已经准备好给出最终答复 final_answer = message.get("content", "") self.context.add_assistant_message(final_answer) return final_answer # 先记录 assistant 消息（包含工具调用意图） self.context.messages.append(message) for tc in tool_calls: fn_name = tc["function"]["name"] fn_args = json.loads(tc["function"]["arguments"]) print(f"[调用工具] {fn_name}({fn_args})") result = self.registry.execute(fn_name, fn_args) self.context.add_tool_result( tool_call_id=tc["id"], name=fn_name, result=str(result) ) self.context.trim_if_needed() iterations += 1 raise RuntimeError(f"超过最大迭代次数 {self.max_iterations}，任务未完成")max_iterations的默认值是 10，这是个安全阀。没有它，模型一旦陷入“思考-调用-再思考”的死循环，你的账单就会一直跳。我在实际测试中见过模型因为一个 JSON 解析错误连续重试了三十多次，如果没有迭代上限，那一次任务的 token 消耗够我用一周。
3. 实操落地：基于 hermes-agent 的最小可用实现
理论讲再多，不如直接把项目跑起来。这一节我完整展示一个“能用的 hermes-agent”需要哪些文件、多少代码，以及真实运行时会发生什么。
3.1 环境准备与项目结构
先说明我的环境版本：Python 3.11，模型服务使用 OpenAI 兼容接口（本地用 Ollama 跑 qwen2.5 也可以，关键点在后面）。项目结构非常简单，一共就四个文件：
hermes-agent/ ├── hermes/ │ ├── __init__.py │ ├── agent.py # 主循环逻辑 │ ├── context.py # 上下文管理器 │ ├── llm.py # 模型接入层 │ └── tools.py # 工具注册中心 ├── tools/ │ └── business.py # 具体业务工具，按需新增 └── main.py # 启动入口依赖只需要一个openaiPython 包，因为大多数兼容接口都遵循 OpenAI 的消息协议。安装命令是pip install openai，没有其他第三方依赖。这是我故意保持的极简风格——Agent 框架的代码量本来就不应该很大，如果搞出几百个依赖文件，那一定是在过度设计。
3.2 注册几个真实可用的业务工具
为了演示效果，我在tools/business.py里注册了三个工具：查询天气、查询实时股价、发送消息到群里。这些工具本身是写死的模拟实现，但你完全可以在函数体里接入真实的天气 API、股票接口和企业微信机器人。
# tools/business.py import random from hermes.tools import registry @registry.register(description="查询指定城市的天气情况") def query_weather(city: str) -> str: """查询天气，返回 JSON 格式的天气信息""" # 这里应该替换为真实的天气 API 调用 weather_data = { "city": city, "temperature": random.randint(-5, 35), "condition": random.choice(["晴", "多云", "小雨"]), "humidity": random.randint(30, 80) } return str(weather_data) @registry.register(description="查询指定股票代码的当前价格") def query_stock_price(stock_code: str) -> str: """查询股票，返回 JSON 格式的价格信息""" # 这里应该替换为真实的股票数据源 price_data = { "code": stock_code, "price": round(random.uniform(10, 500), 2), "change_percent": round(random.uniform(-5, 5), 2) } return str(price_data) @registry.register(description="向指定群聊发送一条文本消息") def send_group_message(group_name: str, content: str) -> str: """发送群消息，返回是否成功""" # 这里应该替换为企业微信/钉钉/飞书的 webhook 调用 print(f"[模拟发送] 群:{group_name} 内容:{content}") return "发送成功"这里有个小教训：工具返回结果最好是字符串，不要返回 Python 对象。因为工具结果最终要拼进消息列表发给模型，必须是可序列化的文本格式。如果你返回一个字典对象，后面加到上下文的时候还得手动str()，很容易出错。我在第一版就吃过这个亏，各种对象的 repr 格式千奇百怪，模型经常误解。
3.3 启动 Agent 并跑一个真实任务
main.py是整个项目的入口。这里我做了两件值得注意的事：一是把系统提示词写得非常明确，告诉模型“你是一个智能助手，你有以下工具可供使用，如果合适就调用工具获取信息再回答”，二是把模型的temperature设置成 0.3，在稳定性和一定灵活性之间取了平衡值。
# main.py from hermes.agent import HermesAgent from hermes.context import ContextManager from hermes.llm import OpenAICompatibleClient from hermes.tools import registry import tools.business # 导入工具模块，触发注册 SYSTEM_PROMPT = """ 你是一个智能助手，名叫 Hermes。你拥有调用工具的能力。 在你回答用户问题之前，先判断是否需要调用工具来获取最新信息。 如果需要，请按工具定义的参数格式调用；如果工具返回结果，请依据结果进行回答。 回答要简洁清晰，不要编造数据。 """ def main(): llm = OpenAICompatibleClient( base_url="http://localhost:8000/v1", # 本地模型服务或云端服务 api_key="EMPTY", # 本地服务一般不校验 key model="qwen2.5:14b", # 按需修改 temperature=0.3, ) context = ContextManager(system_prompt=SYSTEM_PROMPT) agent = HermesAgent(llm, registry, context) user_input = "北京今天的天气怎么样？如果适合出行的话，帮我发一条消息到'工作群'" result = agent.run(user_input) print(f"最终回答: {result}") if __name__ == "__main__": main()这里有个很重要的点：我用的是本地 Ollama 服务，地址是http://localhost:8000/v1，模型是 qwen2.5:14b。为什么不用 GPT-4o？因为 Agent 在开发调试阶段需要高频调用大模型，一次流程跑下来可能调四五次，用云端 API 的话一次调试可能就要几块钱。本地模型虽然单次效果差一点，但胜在零成本和无限调用，特别适合先把流程跑通。
真正跑起来的时候，控制台输出大概是这样的：
[调用工具] query_weather({"city": "北京"}) [模拟发送] 群:工作群 内容:北京今天天气晴，气温18℃，湿度40%，非常适合出行！ [调用工具] send_group_message({"group_name": "工作群", "content": "北京今天天气晴，气温18℃，湿度40%，非常适合出行！"}) 最终回答: 北京今天天气晴，气温18℃，湿度40%，非常适合出行。我已经把这条消息发到了工作群，请注意查收。注意执行顺序：Agent 先调用了天气查询，拿到结果后没有直接结束，而是判断出“适合出行”这个结论，紧接着又调用了发消息工具，最后才输出最终回答。这就是多步工具调用的典型流程，也是 hermes-agent 的核心价值所在。
4. 常见问题与排查技巧实录
这一节全部来自我实际开发调试 hermes-agent 过程中的真实记录，每一条都是我踩过的坑。按问题类型整理成表格，后面再逐个展开讲处理思路和预防方法。
| 问题现象 | 可能原因 | 解决思路 |
|---|---|---|
| 模型不调用工具，直接编造答案 | 工具定义不清晰，或系统提示词没有强调工具优先 | 强化系统提示词，在工具描述中补充“必须调用工具获取实时数据” |
| 工具调用的参数格式错误 | 模型的 JSON 输出不稳定，或参数描述不够具体 | 给每个参数补充取值范围和示例，增加 JSON 不合法时的重试机制 |
| Agent 陷入死循环，反复调用同一工具 | 缺少迭代上限，工具返回结果未被模型正确理解 | 设置 max_iterations，检查工具返回结果是否是“干净、易解析”的文本 |
| 上下文越滚越大，最终超限报错 | 没有及时的上下文裁剪 | 启用 ContextManager 的 trim_if_needed，或把历史做摘要后压缩 |
| 工具执行报错，Agent 却声称成功了 | 工具异常被吞掉，或异常后没有反馈给模型 | 在工具执行处捕获异常，将错误信息作为工具结果返回给模型 |
4.1 模型不按预期调用工具
这个问题在小型模型上特别常见。qwen2.5:14b 这类模型，如果你不反复强调“你有工具可用”，它就默认走纯文本聊天路径，直接凭训练知识回答“北京的天气是……”。但它训练知识里哪有实时天气？于是就开始一本正经地胡编。
我的解决办法是双重强化。第一，在系统提示词中明确声明“你是工具型智能体，优先调用工具获取实时信息，禁止编造数据”；第二，把工具描述写得更有“诱惑性”，比如在 query_weather 的描述里加一句“如果你不调用此工具，你将无法获得任何天气数据，只能编造答案，这是绝对不允许的”。实测下来，这句话能让调用成功率提升至少三成。
4.2 参数格式总是对不上
工具调用的参数是模型生成的 JSON，而模型从小在互联网上训练，对 JSON 格式的偏好五花八门。有人喜欢双引号，有人喜欢把布尔值写成字符串，有人会在 JSON 后面加个逗号。一旦解析失败，整个工具调用就断了。
我在registry.execute里加了一个防御性的解析逻辑：先用json.loads解析，如果失败就尝试修正后再解析。另外就是给参数定义加示例值，比如股票代码的参数可以写“如 600519、AAPL”，模型看到示例之后几乎不会传错。这个细节看起来不起眼，但直接决定整个 Agent 的稳定性。
def _safe_loads(raw: str, tool_name: str) -> dict: try: return json.loads(raw) except json.JSONDecodeError: # 尝试提取最外层的 JSON 对象 start = raw.find("{") end = raw.rfind("}") if start >= 0 and end > start: try: return json.loads(raw[start:end+1]) except json.JSONDecodeError: pass raise ValueError(f"[{tool_name}] 无法解析工具参数: {raw}")4.3 工具返回结果太脏导致模型犯晕
工具返回给模型的内容质量，直接决定了模型的下一次决策质量。我这里说的“脏”指两种情况：一是返回的字符串太长太乱，夹杂无关信息；二是返回的结构模型看不懂。
最典型的例子是查数据库时，工具直接返回原始的 SQL 查询结果，里面全是字段名和数字，没有任何语义说明。模型看到{"price": 123.45, "change_pct": 2.3}时，它能勉强理解；但如果字段名是p,c_p，模型大概率就蒙了。
所以我在工具函数的编写上有个铁律：返回给模型的内容必须是自然语言化的结构化摘要。比如查询天气，返回的内容不是一串生僻字段，而是“北京市当前气温18℃，天气晴，湿度40%，适宜出行”。这样模型拿到的就是一个可以直接回答用户的信息块，不需要再做额外的推理。
4.4 上下文越长越笨的“失忆”问题
这个现象我印象特别深。一个 Agent 任务跑了十几轮之后，前面的关键成果被淹没在大量的工具输出和中间对话里。用户问一句“刚才说的那个方案怎么样了”，模型一脸茫然，好像前面什么都发生。
后来我查了上下文才发现，中间工具调用的输出全部堆在消息列表里，把早期的用户意图和已确认的关键结论挤得看不到了。
要解决这个问题，可以从两个方向入手。一是尽早总结：每完成一个子任务，就让模型生成一条简短的“阶段性结论”，存到上下文里。二是启动时压缩：当上下文接近上限时，把历史消息丢给一个轻量模型，让它提取成一份精炼摘要，替换掉原来的完整历史。第二种方式更优雅，但会增加一次模型调用成本，适合复杂长任务场景。
5. 规划一个更可用的 hermes-agent：扩展方向与路线图
到这一步，一个最小可用的 hermes-agent 已经能跑起来了。但如果你想让它真正用在生产环境，还有几个绕不开的扩展方向值得提前规划。
5.1 加入记忆与长期存储
当前版本的上下文管理器是纯内存的，Agent 跑完一次任务，所有记忆都清空了。这意味着下次用户问“昨天你帮我查的那只股票现在怎么样了”，Agent 完全接不上话。
我的计划是引入一个轻量的 SQLite 存储层，把重要的实体信息（用户的高频话题、偏好设置、历史结论）持久化下来。每次任务开始前，先从记忆库加载与当前任务相关的摘要；任务结束后，把新的关键信息写入记忆库。这个过程有点像人的长期记忆和短期记忆的协作，投入产出比很高。
实现方式也不复杂，你不需要引入向量数据库，一个sqlite3加上几个关键词匹配就够用了。核心逻辑是：在系统提示词之外，额外追加一段“你可能需要知道的历史背景”信息——这段信息只包含与当前问题强相关的历史记录。
5.2 增加并发任务与任务队列
现在的 Agent 是单线程的，同一时间只能处理一个任务。但在真实办公场景中，用户可能同时发起“帮我写周报”和“帮我查三个竞品的价格”两个任务，两个任务之间没有依赖关系，完全可以并行执行。
扩展方案是引入asyncio或者简单的线程池，把每一个任务放进独立的消息循环里执行。需要注意的一点是：如果多个任务共享同一个工具注册中心，工具内部如果有状态变量，必须做好线程隔离，否则会出现数据串台的问题。我的习惯是，工具函数尽量保持无状态，所有临时数据通过参数传入。
5.3 强化工具调用的反馈闭环
当前版本工具一旦抛异常，异常信息会直接塞给模型，这让模型很困惑。更好的做法是：工具内部做一层标准化的错误分类，比如“网络错误”“参数缺失”“权限不足”，然后把这些分类翻译成模型能理解和处理的指令。
举个例子，如果查询天气 API 超时，传给模型的内容不应该是长长的 traceback，而应该是“天气服务暂时不可用，建议稍后重试或改用其他城市”。模型收到这条信息后，会主动给用户一个合理的答复，而不是试图去解析一堆 Python 错误栈。这一点在对接外部系统时尤其重要。
5.4 预留多模态扩展入口
严格来说，Agent 不是只有文本一条路。用户可能会发来一张图片说“帮我看看这个截图里的数据表有什么问题”，或者发来一段音频说“把这段内容整理成会议纪要”。如果从一开始就在消息结构上兼容多模态内容，后面对接视觉模型、语音转写服务时会少走很多弯路。
我在messages结构上其实已经预留了空间，即 content 字段可以不是纯字符串，而是列表，列表里可以混合文本和图片链接。大模型服务商通常也支持这种格式，所以只需要在llm.py的请求封装里做少量适配就能支持多模态输入。
写在最后
hermes-agent 做到现在，给我的最大感受是：Agent 的门槛不在技术，而在工程设计。模型调用谁都会，难得是把“模型-工具-上下文”这三者的关系理清楚，让整个系统在无数次循环调用中保持稳定、可控、可解释。
我强烈建议每个想深入 Agent 开发的朋友，都亲手写一个最小版的框架。你不用让代码完美，关键是跑通一次完整的“自然语言到工具调用再到执行反馈回来”的循环。这个理解一旦建立，以后用任何商用 Agent 框架，你都能一眼看清它背后的原理，排查问题时也不再是瞎猜。
最后分享一个开发过程中的小技巧：调试 Agent 时一定要打印每一轮工具调用的中间状态，我在 agent 里加了[调用工具]这样的日志输出，看似不起眼，实际帮我在几小时内定位过无数个“看似玄学”的问题。永远不要让你的 Agent 循环成为一个黑盒，这是这条路上最值得记住的一句话。
