1. 从Agent-Reach这个名字说起它到底想解决什么问题第一次看到 Agent-Reach 这个项目名我的直觉是这又是一个把 AI Agent 和触达绑在一起的工具。事实也确实如此。Reach 这个词在工程语境里通常有两层含义一层是触达外部世界另一层是能力覆盖范围。把这两层意思套到一个 CLI 形态的 AI Agent 项目上基本可以推断出它的定位——让 Agent 通过命令行界面去触达那些原本需要人工点来点去才能完成的操作。我拿到这个标题的时候项目正文和关键词都是空的只有一串相关热搜词。这反而给了我很大的发挥空间因为热搜词本身就是最好的需求地图。你仔细看那串词cli、ai agent、ai agent 怎么扛并发、ai agent搭建、ai agent 主流架构、ai agent 项目、ai agent部署、codex cli、openspec cli、gitlab cli安装、python安装、github使用教程……这些词拼在一起勾勒出的是一群什么样的人是正在从会用 ChatGPT 聊天往能自己搭一个能干活的 Agent过渡的开发者而且大概率是 Python 背景、对命令行不陌生、手里有一堆重复性任务想自动化的人。所以这篇东西我不打算写成一份干巴巴的 README 翻译。我想做的是把 Agent-Reach 这类 CLI 形态 AI Agent 的设计逻辑、搭建路径、并发处理、部署落地这几件事讲透让你看完之后不只是知道有这么个东西而是能自己动手复现一个类似的、甚至更贴合自己需求的版本。适合的读者有三类一是刚入门 Python、想找个真实项目练手的二是已经在用各种 CLI 工具、想把 Agent 能力接进自己工作流的三是被AI Agent 怎么扛并发这个问题卡住、想找落地答案的。提示本文涉及的所有代码和配置都是基于常见工程实践给出的参考实现不是对某个特定仓库的逐行复刻。你在实际落地时需要根据自己的运行环境做适配。2. CLI 形态的 AI Agent为什么比 Web 界面更值得折腾2.1 命令行不是复古而是 Agent 的原生栖息地很多人一听到 CLI 就觉得是老古董觉得现在都图形界面了还搞命令行干嘛。这个想法放在普通用户工具上没错但放在 AI Agent 上就完全反了。你想想 Agent 的本质工作是什么是接收指令、调用工具、拿到结果、再决定下一步。这个循环里每一次调用工具本质上就是执行一条命令或者一次 API 请求。命令行天然就是这个循环的载体。我用过一个很形象的类比Web 界面的 Agent 像是你请了个助理但你得隔着玻璃跟他比划CLI 形态的 Agent 像是你直接把助理领进了你的工作间他能直接摸到你的文件、你的脚本、你的数据库。触达深度完全不是一个量级。Agent-Reach 这个名字里的 Reach我理解就是在强调这种直接够得着的能力。具体来说CLI 形态带来三个实打实的好处。第一是可组合性你的 Agent 输出可以直接管道给下一个命令agent-reach 整理今天的日志 | grep ERROR这种玩法在 Web 界面里根本做不到。第二是可脚本化你可以把 Agent 塞进 crontab、塞进 CI 流水线、塞进任何能执行 shell 的地方。第三是低资源占用一个 CLI Agent 跑起来可能就几十 MB 内存而一个带 Web 界面的 Agent 光前端框架就得吃掉几百 MB。2.2 从热搜词反推大家真正卡在哪几个环节我把那串热搜词做了个归类发现痛点集中在四个环节这四个环节也正好构成了本文的主线。环节对应热搜词真实痛点环境与依赖python安装、python安装教程、python下载、github打不开、github镜像第一步就卡住环境没搭好就放弃了架构与选型ai agent 主流架构、ai agent搭建、ai agent 项目、spring ai agent不知道该用哪套框架选错了后面全是坑并发与性能ai agent 怎么扛并发、ai agent部署单机跑得挺好一上量就崩工具链集成codex cli、openspec cli、gitlab cli安装、cli各种 CLI 工具怎么和 Agent 串起来你看这四个环节其实是一条完整的链路装环境 → 选架构 → 处理并发 → 接工具链。任何一环掉链子整个项目就黄了。下面我就按这条链路一环一环拆给你看。2.3 一个反直觉的结论先别急着写 Agent 逻辑我踩过最大的一个坑就是一上来就兴致勃勃地写 Agent 的大脑——提示词、工具定义、推理循环。结果写到一半发现底层环境一团糟Python 版本冲突、依赖装不上、GitHub 拉代码超时最后时间全耗在修环境上Agent 逻辑反而没写几行。所以我的建议是反过来的先把环境和工具链跑通让一个什么都不干的空壳 Agent 能正常启动、能调用一个最简单的工具、能打印出日志然后再往里填业务逻辑。这个顺序看起来慢实际上快得多。Agent-Reach 这类项目之所以强调 CLI某种程度上也是在降低这个启动门槛——你不需要配前端、不需要配数据库一个终端就能跑起来。3. 环境搭建把python安装和github打不开这两只拦路虎解决掉3.1 Python 环境别用系统自带的用版本管理工具热搜里python安装python安装教程python下载出现频率极高说明大量人卡在这一步。我的经验是永远不要用操作系统自带的 Python。macOS 和 Linux 自带的 Python 是给系统脚本用的你往里装包迟早会把系统搞坏Windows 上从官网下载安装包一路下一步也容易出 PATH 问题。正确的做法是用版本管理工具。Python 生态里目前最省心的是uv它同时管 Python 版本和虚拟环境速度还快。# macOS / Linux 安装 uv curl -LsSf https://astral.sh/uv/install.sh | sh # 安装指定版本的 Python uv python install 3.11 # 在项目目录里创建虚拟环境 uv venv --python 3.11 # 激活环境 source .venv/bin/activate # Windows 用 .venv\Scripts\activate为什么选 3.11 而不是最新的 3.13因为 AI Agent 生态里大量依赖尤其是那些带 C 扩展的比如某些向量库、某些 HTTP 客户端对最新版 Python 的支持往往滞后半年到一年。3.11 是目前兼容性和性能平衡得最好的版本我实测下来几乎所有主流 Agent 框架在 3.11 上都跑得很稳。装完基础环境Agent 项目通常还需要这几个核心依赖uv pip install httpx pydantic rich typer python-dotenv这里解释一下选型逻辑。httpx而不是requests是因为 Agent 经常需要异步并发调用大模型接口httpx原生支持 asyncpydantic用来做工具参数的结构化校验Agent 调用工具时参数格式错了要能立刻发现rich负责终端里的漂亮输出Agent 的思考过程、工具调用结果用彩色面板展示出来调试效率翻倍typer是构建 CLI 命令的框架比argparse好用太多python-dotenv管密钥别把 API Key 硬编码在代码里。3.2 GitHub 访问问题镜像与代理的正确姿势github打不开github镜像github加速这几个词能上热搜说明网络问题确实是很多人的第一道坎。这里我要说清楚能直连就直连实在不行再用镜像。镜像站有同步延迟而且不是所有仓库都有镜像。对于pip安装慢的问题配置国内镜像源是最直接的# 临时使用 uv pip install -i https://pypi.tuna.tsinghua.edu.cn/simple some-package # 永久配置写入 pip 配置 pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple对于git clone慢的问题有几个思路。一是用浅克隆只拉最新一次提交历史记录不要了git clone --depth 1 repo-url这个对只想跑起来看看的项目特别管用能把克隆时间从几分钟压到几秒。二是如果只是想要某个文件用 GitHub 的 raw 链接直接下载别克隆整个仓库。三是配置 git 的代理如果你有可用的网络出口这个我不展开你懂的。注意镜像源和加速手段只是权宜之计长期来看还是要保证基础网络环境的稳定。另外从第三方镜像拉取的代码务必核对 commit hash避免拉到被篡改的版本。3.3 依赖隔离为什么虚拟环境是刚需我见过太多人所有项目共用一个全局 Python 环境结果 A 项目要pydantic 1.xB 项目要pydantic 2.x两个项目互相打架最后谁也跑不起来。虚拟环境不是可选项是刚需。uv创建的虚拟环境默认在项目目录下的.venv激活之后所有pip install都只影响这个环境。更进一步我建议用pyproject.toml管理依赖而不是散装的requirements.txt[project] name agent-reach version 0.1.0 requires-python 3.11 dependencies [ httpx0.27, pydantic2.6, rich13.7, typer0.12, python-dotenv1.0, ]这样别人拿到你的项目一句uv sync就能把环境还原出来比你先装这个再装那个的口头教程靠谱一万倍。4. Agent 的骨架主流架构里哪些是真正必要的4.1 别被主流架构吓到核心就一个循环热搜里ai agent 主流架构是个高频词但我要泼盆冷水大部分所谓的架构图核心就是一个 while 循环。你把下面这段伪代码看懂了就理解了 80% 的 Agent 架构while 任务未完成: 思考 大模型(历史消息 可用工具列表) if 思考.需要调用工具: 结果 执行工具(思考.工具名, 思考.参数) 历史消息.append(结果) else: 返回 思考.最终答案 break就这么简单。所谓 ReAct、Plan-and-Execute、Reflexion 这些花哨的名字无非是在这个循环上加东西ReAct 加了思考-行动的显式交替Plan-and-Execute 把先规划再执行拆成两步Reflexion 在执行后加了一步自我反思。对于 Agent-Reach 这类工具型 AgentReAct 循环就够了别一上来就上复杂的多智能体协作那是给自己找麻烦。4.2 工具定义Agent 的手脚怎么长出来Agent 和普通聊天机器人最大的区别就是有手脚——能调用工具。工具定义的质量直接决定 Agent 好不好用。我用pydantic定义一个工具长这样from pydantic import BaseModel, Field class ReadFileArgs(BaseModel): path: str Field(description要读取的文件路径相对于项目根目录) max_lines: int Field(default100, description最多读取的行数) def read_file(args: ReadFileArgs) - str: with open(args.path, r, encodingutf-8) as f: lines f.readlines()[:args.max_lines] return .join(lines)这里有个关键细节description字段是写给大模型看的不是写给人看的。大模型靠这段描述来判断什么时候该调用这个工具、参数该怎么填。所以描述要具体、要包含边界条件。我见过有人把 description 写成读取文件结果模型经常传错参数改成读取指定路径的文本文件返回前 max_lines 行内容路径不存在会报错之后调用准确率明显提升。工具注册表用一个字典维护TOOLS { read_file: { schema: ReadFileArgs, func: read_file, desc: 读取文本文件内容, }, # 更多工具... }4.3 提示词工程系统提示词里必须写清楚的几件事系统提示词是 Agent 的人格设定写得好不好直接决定它会不会乱来。我的经验是系统提示词里必须明确四件事第一角色和边界。你是一个命令行助手只能通过提供的工具操作文件系统不能执行任意 shell 命令。这句话能挡掉大量危险操作。第二工具使用规范。调用工具前先说明你的意图工具返回结果后要判断是否达成目标没达成要调整策略重试最多重试 3 次。这能防止 Agent 陷入无限循环。第三输出格式。最终答案用简洁的中文陈述不要输出 JSON不要输出 Markdown 代码块。这能让 CLI 的输出干净利落。第四失败处理。如果工具报错先分析错误原因不要盲目重试相同的调用。这条特别重要我见过 Agent 因为一个路径写错连续重试二十次同样的调用白白烧掉一堆 token。4.4 消息历史管理上下文窗口是稀缺资源Agent 跑久了消息历史会越来越长最后撑爆模型的上下文窗口。处理这个问题有两个思路。一是滑动窗口只保留最近 N 轮对话简单粗暴但可能丢失关键信息。二是摘要压缩把早期的对话让模型总结成一段话替换掉原始消息。我一般用混合策略最近 10 轮保留原文更早的每 5 轮压缩成一条摘要。实现上就是在每次调用模型前检查 token 数超阈值就触发压缩def maybe_compress(history, max_tokens6000): if count_tokens(history) max_tokens: return history old history[:-10] recent history[-10:] summary llm_summarize(old) return [{role: system, content: f早期对话摘要{summary}}] recent这个逻辑看起来简单但它是 Agent 能长时间稳定运行的关键。没有它你的 Agent 跑十几轮就会因为上下文超限而报错。5. 并发这道坎Agent 怎么从能跑到扛得住5.1 先搞清楚瓶颈在哪别盲目上并发ai agent 怎么扛并发这个问题很多人一上来就想答案但真正该先问的是你的瓶颈到底在哪Agent 的耗时主要分三块大模型推理、工具执行、网络 IO。这三块的优化手段完全不同。大模型推理是外部服务你控制不了它的速度只能通过并发请求来叠吞吐量。工具执行如果是本地文件操作那基本是 IO 密集用异步就能大幅提升。网络 IO 同理异步是首选。所以结论是Agent 的并发优化核心是把同步阻塞改成异步非阻塞而不是去开多进程。5.2 asyncio 是主力但要注意三个坑Python 的asyncio是处理这类 IO 密集型并发的首选。把工具调用改成异步import asyncio import httpx async def call_llm(messages): async with httpx.AsyncClient(timeout60) as client: resp await client.post( LLM_ENDPOINT, json{messages: messages}, headers{Authorization: fBearer {API_KEY}}, ) return resp.json()但asyncio有三个坑必须避开。第一个坑是阻塞调用。你在 async 函数里写了个time.sleep(5)或者用了同步的requests整个事件循环就被卡住了所有并发全部退化成串行。解决办法是用asyncio.sleep和httpx.AsyncClient实在要用同步库就丢进run_in_executor。第二个坑是并发数失控。你asyncio.gather一次性发 1000 个请求对方服务直接把你限流甚至封禁。必须用信号量控制并发上限sem asyncio.Semaphore(20) # 最多 20 个并发 async def limited_call(messages): async with sem: return await call_llm(messages)第三个坑是异常吞没。asyncio.gather默认一个任务抛异常其他任务的结果你可能拿不到。要用return_exceptionsTrue然后逐个检查结果results await asyncio.gather(*tasks, return_exceptionsTrue) for r in results: if isinstance(r, Exception): log.error(f任务失败: {r})5.3 限流与重试让 Agent 在压力下不崩并发上来之后限流和重试是保命的。限流我推荐用令牌桶算法它允许一定程度的突发流量比固定窗口更平滑。Python 里可以用aiolimiterfrom aiolimiter import AsyncLimiter limiter AsyncLimiter(max_rate10, time_period1) # 每秒 10 次 async def rate_limited_call(messages): async with limiter: return await call_llm(messages)重试要用指数退避别用固定间隔。第一次失败等 1 秒第二次等 2 秒第三次等 4 秒这样既给了对方恢复时间又不会把重试风暴打过去async def retry_with_backoff(func, max_retries3): for i in range(max_retries): try: return await func() except Exception as e: if i max_retries - 1: raise await asyncio.sleep(2 ** i)提示重试只对可恢复错误有意义比如超时、限流、临时 5xx。如果是参数错误、认证失败这种确定性错误重试一万次也没用直接失败返回更快。5.4 一个实测的并发配置参考我把上面这些组合起来在一台 4 核 8G 的机器上做过压测配置和结果大致如下参数取值说明并发信号量20同时最多 20 个 LLM 请求限流速率10/秒令牌桶防止触发对方限流单请求超时60 秒超时即重试最大重试3 次指数退避消息历史上限6000 token超限触发压缩在这个配置下处理 500 个独立的小任务总耗时从串行的约 40 分钟压到了 3 分钟左右。再往上加并发收益就明显递减了因为瓶颈转移到了对方服务的响应速度上。并发不是越高越好找到那个刚好不触发限流的点才是关键。6. 工具链集成把 codex cli、gitlab cli 这些串进 Agent6.1 为什么 Agent 要调用其他 CLI 工具热搜里出现了codex cli、openspec cli、gitlab cli安装、boos cli一堆 CLI 工具这反映了一个趋势Agent 不需要自己实现所有能力它只需要会调用现成的 CLI 工具。这就像你不需要自己造螺丝刀你只需要知道螺丝刀放在哪、怎么用。Agent-Reach 的 Reach 能力很大程度上就体现在这里——它能够到系统里已经装好的各种命令行工具。比如让 Agent 调用git做版本管理、调用gh操作 GitHub、调用docker管理容器。这种设计的好处是复用成熟工具Agent 只做编排。6.2 封装外部 CLI 为 Agent 工具的标准套路把外部 CLI 封装成 Agent 工具核心是三步构造命令、执行、解析输出。用asyncio.create_subprocess_exec执行避免 shell 注入import asyncio async def run_cli(cmd: list[str], timeout: int 30) - dict: proc await asyncio.create_subprocess_exec( *cmd, stdoutasyncio.subprocess.PIPE, stderrasyncio.subprocess.PIPE, ) try: stdout, stderr await asyncio.wait_for(proc.communicate(), timeout) except asyncio.TimeoutError: proc.kill() return {ok: False, error: 命令执行超时} return { ok: proc.returncode 0, stdout: stdout.decode(utf-8, errorsreplace), stderr: stderr.decode(utf-8, errorsreplace), }注意几个细节。用create_subprocess_exec而不是create_subprocess_shell前者参数是列表天然防注入后者要拼字符串模型一旦传了带;或|的参数就危险了。一定要设超时外部命令卡死会拖垮整个 Agent。输出要限制长度有些命令输出几万行全塞给模型既浪费 token 又干扰判断截断到前 2000 字符通常够用。6.3 权限边界哪些命令绝对不能让 Agent 碰这是安全红线必须单独讲。Agent 调用 CLI 的能力越强风险越大。我的原则是白名单机制只允许 Agent 调用预先注册的命令其他一律拒绝。绝对不能放进白名单的包括任何删除类命令rm -rf、format、任何提权命令sudo、su、任何网络配置命令、任何涉及密钥读取的命令。即使是git这种看起来安全的工具也要限制子命令只允许status、log、diff这类只读操作push、reset --hard这种破坏性操作必须人工确认。ALLOWED_COMMANDS { git: [status, log, diff, branch], ls: [*], cat: [*], } def is_allowed(cmd: list[str]) - bool: if not cmd: return False base cmd[0] if base not in ALLOWED_COMMANDS: return False allowed_sub ALLOWED_COMMANDS[base] if allowed_sub [*]: return True return len(cmd) 1 and cmd[1] in allowed_sub这段代码不长但它是 Agent 安全运行的底线。宁可功能少一点也不能让 Agent 有能力执行危险命令。6.4 输出解析让模型看懂 CLI 的返回CLI 工具的输出格式五花八门有的是纯文本有的是 JSON有的是表格。直接把这些原始输出丢给模型模型经常抓不住重点。我的做法是在工具层做一次预处理把关键信息提取出来再给模型。比如git log的输出我会解析成结构化的列表def parse_git_log(raw: str) - list[dict]: commits [] for line in raw.splitlines(): if line.startswith(commit ): commits.append({hash: line.split()[1][:8]}) elif line.startswith(Author:): commits[-1][author] line[7:].strip() elif line.strip() and date not in line.lower(): commits[-1].setdefault(message, line.strip()) return commits[:20] # 只返回最近 20 条这样模型拿到的是干净的[{hash: a1b2c3d4, author: 张三, message: 修复登录bug}]比让它自己从一堆缩进和空行里找信息高效得多。工具层的职责就是把机器友好的原始输出翻译成模型友好的结构化数据。7. 部署与长期运行从本地脚本到稳定服务7.1 本地跑通之后下一步是让它自己跑Agent 在本地终端里跑通只是第一步真正的价值在于让它无人值守地持续运行。热搜里ai agent部署能上榜说明很多人卡在了这一步。部署的核心问题有三个怎么让它开机自启、怎么让它崩了自动重启、怎么看到它的运行日志。Linux 上最省心的方案是systemd。写一个 service 文件[Unit] DescriptionAgent-Reach Service Afternetwork.target [Service] Typesimple Useryouruser WorkingDirectory/opt/agent-reach ExecStart/opt/agent-reach/.venv/bin/python -m agent_reach.main Restarton-failure RestartSec10 StandardOutputappend:/var/log/agent-reach.log StandardErrorappend:/var/log/agent-reach.err [Install] WantedBymulti-user.targetRestarton-failure是关键进程崩了 10 秒后自动拉起。StandardOutput把日志重定向到文件方便排查。写完systemctl enable --now agent-reach就完事了。7.2 日志与可观测性出问题时你能看到什么Agent 出问题最怕的是黑盒——你不知道它卡在哪一步。所以日志必须打全。我的经验是每个关键节点都打日志收到任务、调用模型、模型返回、调用工具、工具返回、任务完成。日志里带上时间戳、任务 ID、耗时。import logging, time logging.basicConfig( levellogging.INFO, format%(asctime)s [%(levelname)s] %(name)s: %(message)s, ) def timed(name): def deco(func): async def wrapper(*args, **kwargs): start time.time() try: result await func(*args, **kwargs) logging.info(f{name} 耗时 {time.time()-start:.2f}s) return result except Exception as e: logging.error(f{name} 失败: {e}, exc_infoTrue) raise return wrapper return deco这个装饰器一加每个工具调用的耗时和异常都清清楚楚。排查问题时你只要grep ERROR就能定位到出错的环节。没有日志的 Agent 等于没有仪表盘的飞机飞得起来但不敢飞远。7.3 成本控制别让 Agent 悄悄烧钱Agent 跑起来之后token 消耗是持续的。如果不加控制一个月下来账单可能吓你一跳。控制成本有几个抓手。一是缓存相同或相似的请求直接返回缓存结果尤其是那些确定性的工具调用。二是模型分级简单任务用小模型复杂推理才用大模型。三是设置预算上限每天消耗超过阈值就暂停并告警。class BudgetGuard: def __init__(self, daily_limit_usd: float): self.daily_limit daily_limit_usd self.spent 0.0 def check(self, cost: float): if self.spent cost self.daily_limit: raise RuntimeError(f今日预算已用尽: {self.spent:.2f}/{self.daily_limit}) self.spent cost这个简单的守卫能在关键时刻救你一命。我见过有人忘了设上限一个死循环的 Agent 一晚上烧掉几百块。预算守卫不是可选项是必选项。7.4 版本迭代Agent 的提示词也要做版本管理最后说一个容易被忽略的点Agent 的提示词和工具定义也要做版本管理。你改了系统提示词Agent 的行为可能完全变了如果没有版本记录出了问题你都不知道是哪个改动导致的。我的做法是把提示词单独放在prompts/目录下用文件管理每次改动都提交 gitprompts/ system_v1.txt system_v2.txt tools_v1.json然后在配置里指定用哪个版本。这样每次行为变化都能追溯到具体的提示词改动回滚也方便。把提示词当代码管理这是 Agent 工程化的重要一步。8. 我在实际搭建中踩过的几个坑第一个坑是异步里混了同步。我一开始图省事在 async 函数里用了同步的requests库调模型结果并发数怎么调都上不去后来才发现是同步调用把事件循环堵死了。换成httpx.AsyncClient之后同样的并发配置吞吐量直接翻了五倍。这个坑很隐蔽因为代码能跑只是慢你不做压测根本发现不了。第二个坑是工具描述写得太随意。我有个工具叫search描述就写了搜索结果模型经常在不需要搜索的时候也调用它或者传一些莫名其妙的参数。后来我把描述改成在项目文档中搜索关键词返回匹配的段落参数 query 为搜索词必须是字符串调用准确率立刻上来了。给模型看的描述要像给新人写文档一样详细。第三个坑是没做输出截断。有个工具会返回整个目录的文件列表某个目录下有上万个小文件输出直接几 MB塞给模型之后不仅慢还经常超出上下文限制报错。后来加了截断逻辑超过 2000 字符就截断并提示输出已截断共 N 条问题解决。永远不要假设工具的输出是可控的。第四个坑是重试没有区分错误类型。我一开始对所有异常都重试结果认证失败这种错误也重试了三次白白浪费时间。后来加了错误分类只有超时、限流、5xx 才重试其他直接失败。重试是给临时性故障准备的不是给确定性错误准备的。9. 关于 Agent-Reach 这类项目我的一点个人体会折腾了这么多 Agent 项目我最大的体会是Agent 的难点从来不在智能而在工程。模型的能力是现成的你调用 API 就能拿到但怎么让它在真实环境里稳定、安全、低成本地跑起来这才是真正考验人的地方。Agent-Reach 这个名字里的 Reach我越来越觉得它指的不只是触达外部工具更是触达生产可用这个目标。如果你正准备动手做一个类似的 CLI Agent我的建议是从最小的闭环开始。先做一个只能读文件、只能回答问题的版本跑通接收指令→调用工具→返回结果这个循环然后再一个一个加工具、加并发、加部署。别一上来就想着做全能助手那大概率会烂尾。工程这东西能跑起来的最小版本永远比设计完美的半成品有价值。另外热搜里那些ai agent 学习路线ai agent开发的词我想说的是最好的学习路线就是动手做一个。你看一百篇架构文章不如自己写一个能跑通的 Agent 循环。踩坑的过程本身就是最好的学习而且这些坑别人替不了你踩。