1. 从命令行到智能体：Agent-Reach 到底在解决什么问题

第一次看到 Agent-Reach 这个名字，我脑子里蹦出来的画面是“让 AI Agent 伸手够到真实世界”。事实也确实如此。过去一年我折腾过不少 AI Agent 项目，从基于 Rust 的高性能运行时，到 Spring AI 那套 Java 生态的编排框架，再到扣子这类低代码智能体平台，绕了一大圈之后发现一个共性痛点：Agent 的“大脑”越来越聪明，但“手脚”始终不够利索。模型能推理、能规划、能写代码，可一旦要它去操作一个真实的命令行工具、跑一条构建指令、拉一次 Git 仓库、调一个本地脚本，整个链路就开始掉链子。

Agent-Reach 就是冲着这个断层来的。它本质上是一个CLI 形态的 AI Agent 执行层，把自然语言指令翻译成可落地的命令行操作，再通过一套受控的执行沙箱把结果回传给模型，形成“思考—执行—观察—再思考”的闭环。你可以把它理解成给大模型装了一双能敲键盘的手，而且这双手知道什么该碰、什么不该碰。

为什么我特别关注这个方向？因为现在市面上讲 AI Agent 的文章，十篇里有八篇在讲架构图、讲 ReAct、讲 Plan-and-Execute，但真正落到“Agent 怎么安全地执行一条 shell 命令”这种脏活累活的，少之又少。而恰恰是这些脏活，决定了你的 Agent 是能上生产还是只能待在 demo 里。Agent-Reach 瞄准的就是这个位置——它不跟你抢模型，也不跟你抢编排框架，它专注做执行触达层。

这篇文章适合三类人看：一是正在搭建 AI Agent 项目、卡在“怎么让 Agent 真正干活”这一步的开发者；二是对 CLI 工具链感兴趣、想了解 codex cli、zcode cli 这类工具背后执行逻辑的技术人；三是想搞清楚 AI Agent 并发、token 消耗、部署这些实际问题怎么处理的工程实践者。我会从设计思路、核心机制、实操搭建、问题排查几个维度，把 Agent-Reach 这类 CLI Agent 执行层拆开揉碎讲清楚，尽量让你看完就能动手复现。

2. 核心设计思路：为什么是 CLI，为什么是 Reach

2.1 CLI 作为 Agent 执行层的天然优势

很多人第一反应是：都 2025 年了，为什么还要用命令行这么“原始”的交互方式？做个图形界面或者 API 调用不好吗？我一开始也这么想，直到踩了几次坑才明白，CLI 恰恰是当前 AI Agent 执行层最务实的载体。

原因有三层。第一层是通用性。命令行是操作系统最底层的通用接口，git、npm、docker、python、curl，几乎所有开发工具都提供 CLI。Agent 只要掌握了命令行的调用方式，就等于掌握了整个工具生态，不需要为每个工具单独写适配器。这比一个个对接 API 要高效得多。第二层是可组合性。命令行天然支持管道、重定向、环境变量，一条命令可以串联起复杂的操作流。Agent 生成的指令可以直接复用这些能力，不用自己造轮子。第三层是可观测性。命令行的输入输出都是纯文本，对模型来说极其友好——stdout 就是观察结果，stderr 就是错误信号，退出码就是成功与否的判断依据。这种结构化的反馈，比解析复杂的 JSON 响应要简单直接。

Agent-Reach 选择 CLI 作为核心交互形态，本质上是在赌一个判断：未来的 AI Agent 执行层，会像今天的 DevOps 一样，以命令行为中心构建。这个判断我认为是站得住的。你看 codex cli、zcode cli 这些工具的火爆，本质上都是同一个逻辑——让 AI 通过命令行这个“万能接口”去触达真实系统。

2.2 “Reach”的三层含义拆解

Agent-Reach 里的 Reach 这个词，我理解它至少包含三层设计意图，这也是它区别于普通 CLI 封装工具的关键。

第一层是触达能力。Agent 要能“够到”本地的文件系统、进程、网络、环境变量。这听起来简单，但实际做起来要考虑跨平台差异——Windows 的 PowerShell 和 Linux 的 bash 语法不同，路径分隔符不同，权限模型也不同。Agent-Reach 需要在抽象层抹平这些差异，让上层 Agent 不用关心底层是哪个系统。

第二层是触达边界。这是最容易被忽视但最致命的部分。一个没有边界控制的 Agent 执行层，等于把 root 权限交给了一个可能产生幻觉的模型。Agent-Reach 必须定义清楚：哪些命令允许执行、哪些目录允许访问、单次执行超时多久、输出截断多少字符、并发上限是多少。这些边界不是限制能力，而是保证 Agent 不会因为一次幻觉就把系统搞崩。

第三层是触达反馈。执行完命令之后，结果怎么回传给模型？是原样返回 stdout，还是做结构化处理？错误信息怎么归类？长输出怎么摘要？这些反馈质量直接决定了 Agent 下一轮推理的准确性。我见过太多项目在这一步偷懒，直接把几百行日志塞回给模型，结果 token 爆炸不说，模型还被无关信息干扰得找不着北。

2.3 与主流 Agent 架构的定位差异

现在主流的 AI Agent 架构大致分几派：以 LangChain、LangGraph 为代表的编排派，以扣子为代表的平台派，以 Spring AI 为代表的企业集成派。Agent-Reach 跟它们不是竞争关系，而是互补关系。

编排派解决的是“Agent 怎么思考、怎么规划、怎么记忆”的问题，它们擅长把多个步骤串起来，但具体到“怎么执行一条命令”，往往就是简单包一个 subprocess 调用，缺乏安全控制和反馈优化。平台派解决的是“让不懂代码的人也能搭 Agent”的问题，但它的执行能力受限于平台提供的插件，触达范围有限。企业集成派解决的是“Agent 怎么接入现有系统”的问题，但往往绑定特定技术栈。

Agent-Reach 的定位很清晰：做编排框架和真实系统之间的那层执行中间件。你可以用 LangGraph 做规划，用 Agent-Reach 做执行；也可以用扣子做交互，用 Agent-Reach 做落地。它不挑上游，只专注把“触达”这件事做扎实。这个定位让我想起当年 Docker 的崛起——它不跟虚拟机抢编排，也不跟物理机抢硬件，它专注做“应用打包和隔离”这一层，结果成了整个云原生生态的基石。

3. 核心机制拆解：Agent-Reach 内部是怎么运转的

3.1 指令解析与安全校验流水线

Agent-Reach 收到模型生成的指令后，不会直接丢给系统执行，而是先过一条安全校验流水线。这条流水线我拆成四个环节来讲。

第一个环节是语法解析。把自然语言或半结构化的指令，解析成标准的命令调用结构，包括可执行文件名、参数列表、工作目录、环境变量、超时设置。这一步要处理模型输出的各种不规范情况——有时候模型会带 markdown 代码块标记，有时候会加解释性文字，有时候参数顺序乱七八糟。解析器需要足够健壮，能从噪声中提取出真正的命令。

第二个环节是白名单匹配。Agent-Reach 维护一份可执行命令的白名单，只有名单内的命令才允许执行。白名单不是简单列几个命令名，而是要精确到子命令和参数模式。比如git允许status、log、diff，但不允许push --force；rm默认禁止，除非显式配置了允许的路径范围。这个设计思路跟防火墙的规则引擎很像，核心是默认拒绝，显式允许。

第三个环节是路径与资源校验。检查命令涉及的文件路径是否在允许的工作区内，防止 Agent 通过../之类的路径穿越访问敏感目录。同时校验资源使用，比如单条命令的 CPU 时间、内存上限、输出大小上限。这一步是防止 Agent 因为幻觉执行find /这种全盘扫描的关键。

第四个环节是风险分级。把命令分成只读、写入、危险三个等级。只读命令可以直接执行，写入命令需要记录审计日志，危险命令需要人工确认或直接拒绝。这个分级机制在实际使用中非常有用，因为大部分 Agent 的日常操作都是只读的，只有少数场景需要写入权限。

提示：白名单配置是 Agent-Reach 安全性的核心，建议初期把白名单收得很紧，只开放最必要的命令，随着使用场景明确再逐步放宽。我见过有人图省事直接开放全部命令，结果 Agent 在一次调试中执行了清理缓存的命令，把整个项目的依赖目录删了。

3.2 执行沙箱与资源隔离

命令通过校验后，进入执行沙箱。沙箱的设计目标是在保证执行能力的同时，把影响范围控制在最小。Agent-Reach 的沙箱机制我总结为三个隔离维度。

进程隔离是最基础的。每条命令在独立的子进程中执行，父进程负责监控超时和资源使用。一旦命令执行超过预设时间，直接 kill 掉，避免僵尸进程堆积。这个超时设置很讲究——太短了正常命令跑不完，太长了卡死的命令会拖垮整个 Agent。我的经验是默认设 30 秒，对于构建、安装这类耗时操作单独配置更长的超时。

文件系统隔离是进阶能力。Agent-Reach 可以为每条命令指定一个工作目录，命令只能在这个目录及其子目录内读写。实现方式可以是简单的路径校验，也可以是更彻底的容器化隔离。路径校验轻量但不够严密，容器化隔离彻底但部署复杂。实际选型要看场景——本地开发用路径校验就够了，生产环境建议上容器。

环境变量隔离容易被忽略但很重要。Agent 执行命令时继承的环境变量需要过滤，不能把宿主机上所有敏感变量都暴露出去。Agent-Reach 应该只传递白名单内的环境变量，比如 PATH、HOME 这些必要的，而像 API Key、数据库密码这类敏感信息，要么不传，要么通过安全的注入机制单独提供。

3.3 输出处理与反馈压缩策略

命令执行完，输出怎么处理是决定 Agent 智能程度的关键。我见过太多项目在这里偷懒，直接把原始输出丢回给模型，结果就是 token 消耗爆炸、模型注意力被稀释、推理质量下降。Agent-Reach 在输出处理上做了几层优化，值得借鉴。

第一层是截断。对超长输出做头部和尾部保留，中间部分用省略标记替代。因为大部分命令的关键信息要么在开头（比如错误信息），要么在结尾（比如执行结果汇总），中间往往是重复的日志。截断策略要可配置，不同命令用不同的截断阈值。

第二层是结构化。把非结构化的文本输出，尽量转成结构化数据。比如git status的输出可以解析成文件列表和状态码，npm install的输出可以提取出成功安装的包数量和耗时。结构化之后，模型理解起来更准确，也更容易做后续处理。

第三层是摘要。对于确实无法结构化的长输出，用一个小模型或者规则引擎做摘要，提取关键信息。这一步要谨慎，因为摘要可能丢失细节。我的做法是保留原始输出到日志文件，只把摘要回传给模型，需要细节时再让 Agent 主动去读日志。

第四层是错误归类。命令执行失败时，把 stderr 和退出码映射成标准错误类型——是权限问题、路径问题、依赖缺失还是语法错误。归类之后，模型能更快定位问题，而不是对着一堆报错信息瞎猜。

3.4 并发模型与 token 消耗控制

“AI Agent 怎么扛并发”是最近被问得最多的问题之一，Agent-Reach 在这块的设计思路值得单独讲讲。

并发控制的核心矛盾是：Agent 的推理是串行的，但执行可以是并行的。一个 Agent 在思考下一步做什么的时候，之前触发的命令可能还在跑。如果傻等，效率极低；如果无脑并发，资源会爆。Agent-Reach 的做法是引入一个执行队列 + 并发池的模型。

执行队列负责接收 Agent 提交的命令任务，按优先级排序。并发池控制同时执行的命令数量，默认设一个保守值比如 4，根据机器配置调整。当 Agent 提交的命令超过并发上限时，进入队列等待，而不是直接拒绝。这样既保证了资源可控，又不会让 Agent 因为一次拒绝就卡住。

token 消耗控制是另一个关键点。Agent 的每一轮推理都要把历史上下文塞给模型，如果执行输出不做压缩，几轮下来 token 就爆了。Agent-Reach 的策略是只保留最近 N 轮的完整输出，更早的输出只保留摘要。N 的取值要看模型上下文窗口大小，一般 3 到 5 轮比较合适。同时，对于重复出现的输出模式，做去重处理，避免同样的信息反复占用 token。

提示：并发数不是越大越好。我实测下来，对于大多数开发场景，并发 4 到 8 是甜点区。再往上，收益递减不说，还容易触发系统资源竞争，反而拖慢整体速度。而且并发太高会让日志交错，排查问题变得困难。

4. 从零搭建一个 CLI Agent 执行层：实操全流程

4.1 环境准备与技术栈选型

动手之前先把环境理清楚。Agent-Reach 这类执行层，技术栈选择主要看你的上游 Agent 用什么。如果上游是 Python 生态的 LangChain、LangGraph，那执行层用 Python 写最顺；如果追求性能和部署简单，Rust 或 Go 是更好的选择；如果团队是 Java 背景，Spring AI 那套也能用。

我这次演示用 Python 来写，原因是生态成熟、上手快，而且大部分 AI Agent 项目本身就是 Python 的，集成成本最低。核心依赖就几个：subprocess做进程管理，asyncio做并发控制，pydantic做配置校验，shlex做命令解析。不需要引入重型框架，保持轻量。

环境准备清单：

• Python 3.10 以上，低版本对 asyncio 的支持不够完善
• 一个独立的虚拟环境，避免污染系统 Python
• 一个专门的工作目录，作为 Agent 的文件操作沙箱
• 如果要做容器隔离，需要本地有 Docker 环境

python -m venv agent-reach-env source agent-reach-env/bin/activate pip install pydantic asyncio

工作目录建议单独建，比如~/agent-workspace，所有 Agent 的文件操作都限制在这个目录内。这样即使 Agent 出问题，影响范围也可控。

4.2 命令白名单与权限配置

白名单配置是整个执行层的地基，配得好后面省心，配得差后面全是坑。我建议用 YAML 或 JSON 来管理配置，结构清晰，改起来方便。

commands: git: allowed_subcommands: [status, log, diff, branch, show] denied_patterns: ["push --force", "reset --hard"] timeout: 30 ls: allowed: true timeout: 10 cat: allowed: true allowed_paths: ["~/agent-workspace"] timeout: 10 npm: allowed_subcommands: [install, run, test] timeout: 300 rm: allowed: false

这份配置的设计逻辑是：按命令名分组，每个命令单独配置允许的子命令、禁止的参数模式、超时时间、路径限制。git允许查看类操作但禁止强推和硬重置，npm允许安装和运行但给足超时，rm直接禁用。

配置加载后要做校验，确保格式正确、路径存在、超时值是合理范围。校验失败要给出明确的错误提示，而不是等到执行时才报错。

注意：白名单里的路径要用绝对路径，不要用相对路径或~这种依赖当前用户环境的写法。因为 Agent 执行命令时的工作目录可能跟你预期的不一样，相对路径会出问题。

4.3 执行引擎的核心代码实现

执行引擎的核心逻辑我拆成几个函数来讲，这样结构清晰，也方便你按需修改。

首先是命令解析函数，负责把模型输出的字符串解析成结构化命令：

import shlex from dataclasses import dataclass @dataclass class ParsedCommand: executable: str args: list[str] raw: str def parse_command(raw: str) -> ParsedCommand: # 去掉 markdown 代码块标记 cleaned = raw.strip().strip('`').strip() if cleaned.startswith('bash'): cleaned = cleaned[4:].strip() # 用 shlex 做安全分词，避免 shell 注入 parts = shlex.split(cleaned) if not parts: raise ValueError("空命令") return ParsedCommand( executable=parts[0], args=parts[1:], raw=cleaned )

这里用shlex.split而不是简单的split()，是因为 shlex 能正确处理引号和转义，避免参数被错误切分。同时它不做 shell 展开，天然防止了$(...)这类注入。

然后是白名单校验函数：

def validate_command(cmd: ParsedCommand, config: dict) -> bool: rule = config['commands'].get(cmd.executable) if not rule or not rule.get('allowed', True): raise PermissionError(f"命令 {cmd.executable} 不在白名单") allowed_subs = rule.get('allowed_subcommands') if allowed_subs and cmd.args: if cmd.args[0] not in allowed_subs: raise PermissionError(f"子命令 {cmd.args[0]} 不被允许") denied = rule.get('denied_patterns', []) full = ' '.join(cmd.args) for pattern in denied: if pattern in full: raise PermissionError(f"命中禁止模式: {pattern}") return True

校验逻辑分三层：命令名是否在白名单、子命令是否允许、参数是否命中禁止模式。任何一层不通过就拒绝执行。

执行函数用 asyncio 做异步，配合超时控制：

import asyncio async def execute_command(cmd: ParsedCommand, workdir: str, timeout: int): proc = await asyncio.create_subprocess_exec( cmd.executable, *cmd.args, cwd=workdir, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE, env=get_safe_env() ) try: stdout, stderr = await asyncio.wait_for( proc.communicate(), timeout=timeout ) except asyncio.TimeoutError: proc.kill() await proc.wait() return {"status": "timeout", "output": ""} return { "status": "success" if proc.returncode == 0 else "error", "exit_code": proc.returncode, "stdout": stdout.decode('utf-8', errors='replace'), "stderr": stderr.decode('utf-8', errors='replace') }

注意create_subprocess_exec和create_subprocess_shell的区别。前者直接执行可执行文件，不经过 shell，天然防止注入；后者会启动一个 shell，虽然方便但风险高。Agent-Reach 这类场景必须用前者。

4.4 输出压缩与反馈格式化

输出处理是提升 Agent 智能程度的关键，我写一个压缩函数来演示核心思路：

def compress_output(text: str, max_lines: int = 50, max_chars: int = 4000) -> str: if not text: return "" lines = text.splitlines() if len(lines) > max_lines: head = lines[:max_lines // 2] tail = lines[-(max_lines // 2):] omitted = len(lines) - max_lines lines = head + [f"... 省略 {omitted} 行 ..."] + tail result = '\n'.join(lines) if len(result) > max_chars: result = result[:max_chars] + "\n... 输出已截断 ..." return result

这个函数做两件事：行数超限时保留头尾、中间省略；字符数超限时直接截断。头尾保留是因为错误信息通常在开头，结果汇总通常在结尾。

反馈格式化则是把执行结果组织成模型友好的结构：

def format_feedback(result: dict) -> str: if result['status'] == 'timeout': return "[执行超时] 命令在限定时间内未完成，请检查命令是否合理或调整超时设置。" if result['status'] == 'error': err = compress_output(result.get('stderr', '')) return f"[执行失败] 退出码 {result['exit_code']}\n错误信息:\n{err}" out = compress_output(result.get('stdout', '')) return f"[执行成功]\n{out}"

格式化的核心是给模型明确的信号——成功还是失败、失败原因是什么、关键输出在哪里。这样模型下一轮推理时能快速定位，不用在噪声里找信息。

4.5 并发调度与队列管理

并发调度用 asyncio 的信号量来控制：

class ExecutionPool: def __init__(self, max_concurrent: int = 4): self.semaphore = asyncio.Semaphore(max_concurrent) self.queue = asyncio.Queue() async def submit(self, cmd, workdir, timeout): async with self.semaphore: return await execute_command(cmd, workdir, timeout) async def submit_batch(self, tasks): return await asyncio.gather(*[ self.submit(**t) for t in tasks ])

信号量控制同时执行的任务数，超出的任务自动等待。submit_batch用于批量提交，适合 Agent 一次性规划出多个独立操作的场景。

队列管理要处理优先级。比如 Agent 的“查看状态”类命令应该优先于“安装依赖”类命令，因为前者快且是后续决策的依据。可以用asyncio.PriorityQueue实现，给不同命令类型分配不同优先级。

提示：并发池的大小要根据实际机器配置调整。CPU 密集型命令（比如编译）并发数不要超过 CPU 核心数；IO 密集型命令（比如网络请求）可以适当放大。我一般设成 CPU 核心数的 1 到 2 倍。

5. 常见问题与排查技巧实录

5.1 命令执行超时怎么排查

超时是最高频的问题。排查思路分三步走。

第一步，确认是命令本身慢还是环境问题。手动在终端跑一遍同样的命令，看耗时。如果手动跑很快，Agent 跑很慢，那大概率是环境变量或工作目录不对。Agent 执行时的 PATH 可能跟你的交互式 shell 不一样，导致找不到某些工具或者用了不同版本。

第二步，检查超时设置是否合理。安装依赖、构建项目这类操作，30 秒肯定不够。我的经验值是：查看类命令 10 秒，普通操作 30 秒，安装构建 300 秒，特殊场景单独配置。超时设置要跟命令类型匹配，一刀切必然出问题。

第三步，看是不是死锁或等待输入。有些命令会等待用户输入，比如npm init不带参数时会交互式提问。Agent 执行时没有输入源，就会一直卡着直到超时。解决办法是给这类命令加上非交互参数，比如npm init -y。

5.2 输出乱码与编码问题处理

编码问题在跨平台场景下特别常见。Windows 默认用 GBK，Linux 用 UTF-8，Agent 执行命令时如果编码不匹配，输出就是乱码。

处理办法是在解码时指定errors='replace'，把无法解码的字符替换掉，至少保证不崩溃。更彻底的做法是强制命令用 UTF-8 输出，比如设置环境变量PYTHONIOENCODING=utf-8、LANG=en_US.UTF-8。

还有一种情况是命令输出包含 ANSI 颜色码，这些转义字符会污染模型的输入。处理办法是用正则把 ANSI 码过滤掉：

import re ansi_pattern = re.compile(r'\x1b\[[0-9;]*m') clean = ansi_pattern.sub('', text)

5.3 权限拒绝与路径穿越拦截

权限问题通常有两类。一类是命令本身不在白名单，这个好办，改配置就行。另一类是路径穿越，Agent 试图访问工作目录之外的路径。

路径穿越的典型模式是../或者绝对路径。校验逻辑要把命令中的路径参数提取出来，解析成绝对路径，然后检查是否在工作目录内：

from pathlib import Path def check_path(path_str: str, workspace: str) -> bool: workspace = Path(workspace).resolve() target = (workspace / path_str).resolve() return workspace in target.parents or target == workspace

注意要用resolve()解析符号链接，否则 Agent 可以通过软链接绕过检查。

5.4 常见问题速查表

5.5 几个我踩过的坑

坑一：环境变量继承导致的安全问题。早期版本我直接让子进程继承父进程的全部环境变量，结果 Agent 执行env命令时把宿主机上所有敏感变量都打印出来了。后来改成白名单传递，只传 PATH、HOME、LANG 这几个必要的。

坑二：输出截断把关键信息截掉了。有次 Agent 执行git log想看最近提交，结果截断策略只保留了前 25 行，而关键信息在第 30 行。后来改成头尾都保留，中间省略，问题解决。

坑三：并发执行导致日志交错。多个命令同时执行，日志混在一起，排查问题时根本分不清哪条输出属于哪个命令。解决办法是给每个执行任务分配唯一 ID，日志里带上 ID 前缀。

坑四：超时 kill 后子进程没清理干净。proc.kill()只杀主进程，如果命令自己 fork 了子进程，这些子进程会变成孤儿进程继续跑。彻底的做法是用进程组，kill 整个组。

6. 进阶方向：从执行层到智能执行层

6.1 执行历史学习与命令推荐

基础版 Agent-Reach 是被动执行——Agent 给什么命令就执行什么。进阶版可以做成主动推荐——根据历史执行记录，预测 Agent 下一步可能需要什么命令，提前准备好或者直接建议。

实现思路是记录每次执行的命令、上下文、结果，形成一个执行日志。然后用简单的统计或者轻量模型，找出高频命令模式和常见错误。当 Agent 遇到类似场景时，主动提示“上次遇到这种情况，执行了 X 命令，效果不错”。

这个能力对降低 token 消耗很有帮助，因为很多操作是重复的，Agent 不用每次都从头推理。

6.2 多 Agent 协作下的执行协调

当多个 Agent 共享一个执行层时，协调就变得重要。比如 Agent A 在执行构建，Agent B 想执行测试，两者可能冲突。解决办法是引入资源锁机制，对特定资源（比如工作目录、构建产物）加锁，同一时间只允许一个 Agent 操作。

更复杂的场景是任务依赖。Agent A 的输出是 Agent B 的输入，执行层需要感知这种依赖，确保顺序执行。这可以用有向无环图来建模，执行层按拓扑序调度。

6.3 执行结果缓存与幂等性保证

很多命令是幂等的，比如git status、ls，短时间内重复执行结果一样。执行层可以加一层缓存，相同命令在缓存有效期内直接返回上次结果，省去重复执行的开销。

缓存的关键是缓存键的设计——命令、参数、工作目录、环境变量都要纳入，任何一个不同都不能命中缓存。同时要设置合理的过期时间，太长了结果过时，太短了没效果。

幂等性保证则是另一个维度。对于写操作，执行层要能识别重复提交，避免同一个操作执行两次。可以用命令指纹加执行状态来实现，执行前先查是否已执行过。

6.4 可观测性建设：日志、指标与追踪

生产环境用 Agent-Reach，可观测性是刚需。至少要建设三块。

日志要结构化，每条执行记录包含时间戳、命令、参数、工作目录、执行时长、退出码、输出摘要。日志要能按 Agent ID、命令类型、时间范围检索。

指标要覆盖关键维度：执行总数、成功率、平均耗时、超时率、并发峰值、token 消耗。这些指标能帮你发现性能瓶颈和异常模式。

追踪要能串起一次完整的 Agent 任务。从 Agent 发起请求，到命令执行，到结果回传，每个环节都要有 trace ID，方便端到端排查。

提示：可观测性建设不要一步到位，先上日志，再上指标，最后上追踪。日志是基础，没有日志其他都是空中楼阁。我见过团队一上来就搞全套 APM，结果日志都没打全，出了问题还是抓瞎。

7. 一些实操心得

Agent-Reach 这类执行层，技术难度其实不算高，难的是边界感的把握。放得太松，Agent 能干活但风险大；收得太紧，Agent 处处受限发挥不出价值。我的经验是从最紧开始，按需放宽。先只开放只读命令，跑一段时间确认稳定，再逐步开放写入命令。每次放宽都要有明确的场景驱动，而不是图方便。

另一个心得是反馈质量比执行速度更重要。很多人优化 Agent 性能时盯着执行耗时，其实真正影响体验的是反馈质量。一条命令执行快 100 毫秒，用户感知不到；但反馈信息准确清晰，Agent 少走两轮弯路，省下的时间是以秒计的。所以在输出处理、错误归类、结构化反馈上多花功夫，回报率远高于抠执行性能。

最后说个关于 token 的体会。Agent 的 token 消耗大头往往不在模型推理，而在上下文传递。执行输出如果不做压缩，几轮下来上下文就爆了。我实测过一个场景，不做输出压缩时，10 轮对话消耗 8 万 token；做了压缩和摘要后，同样 10 轮只消耗 2 万 token。这个差距在规模化使用时就是真金白银的成本差异。所以别小看输出处理这几行代码，它可能是整个执行层里性价比最高的优化点。