终端代理的架构账:为什么"能执行命令"比"能写代码"难得多

原创2026-10-25 11:11:311,622 阅读
文章标签:人工智能AI 应用AI Agent代码智能体工具调用MCP Clients交互助手CLI

终端代理的架构账:为什么"能执行命令"比"能写代码"难得多

2025 年 6 月 25 日,谷歌发布开源项目 Gemini CLI,把 Gemini 模型直接装进开发者终端,个人用户每天可发起约 1000 次免费请求、支持约 100 万 token 上下文窗口,发布后迅速在 GitHub 上收获数万 star,社区讨论一度以"硬刚 Claude Code"、"免费量大管饱"为主旋律。但热度退去后,真正有含金量的讨论集中在一个更本质的问题上:让模型写出代码,是生成问题;让模型在你真实的操作系统上执行命令,是执行问题。前者错了可以重写,后者错了会改文件、起进程、碰网络。

这篇文章以 gemini-cli 仓库源码为证据,算一算这笔"架构账":一个能执行命令的终端代理,到底要在工具调用循环里修多少层"故障安全",要在权限与审批上做多少取舍,又是如何从"单步生成"一步步演进成"多步代理"的。所有结论都落在仓库真实代码上,而不是产品宣传页。

工具调用循环里的失败恢复:四层防线

先看这个代理的"心跳"在哪里。packages/core/src/core/turn.ts 中的 Turn 类管理单轮代理循环:它从模型流式响应中拆出文本、thought 思考块、functionCalls 工具调用,把每一次工具调用封装成 ToolCallRequestInfo 推入 pendingToolCalls,再交给上层调度执行。真正决定"能不能跑下去"的,是围绕这个循环设计的四层失败恢复机制。

第一层:网络与流的中途重试

模型流式输出中断,在长任务里几乎必然发生。packages/core/src/core/geminiChat.ts 把重试拆成了"连接阶段"和"流中阶段"两种策略。连接阶段错误交给 retryWithBackoff 统一处理,而流中错误有独立的预算:

const MID_STREAM_RETRY_OPTIONS: MidStreamRetryOptions = {
  maxAttempts: 4, // 1 initial call + 3 retries mid-stream
  initialDelayMs: 1000,
  useExponentialBackoff: true,
};

注意这里有一个容易被忽略的细节:即便全局配置的 maxAttempts(例如 10)更大,流中 API 错误也最多只重试 3 次,用 Math.min(maxAttempts, maxMidStreamAttempts) 硬性封顶,并按 1s、2s、4s 指数退避。重试不是免费的——每次重试前会先向下游 yield 一个 RETRY 事件,让 UI 丢弃上一次失败尝试已经渲染出的半截内容。

packages/core/src/utils/retry.ts 则回答了"哪些错误值得重试"。它维护了一份可重试网络错误码清单(ECONNRESET、ETIMEDOUT、ERR_STREAM_PREMATURE_CLOSE 等),并专门处理了 SSL BAD_RECORD_MAC 这类在 OpenSSL 1.x 与 3.x 之间错误码后缀不一致的坑——通过正则 /^ERR_SSL_.*BAD_RECORD_MAC/i 匹配稳定后缀而非枚举所有变体,还沿着 cause 链最多向下走 5 层查找嵌套错误码。这种对底层错误形态的穷举,只有被真实生产环境反复打脸过的项目才会写。

第二层:内容级重试与"推一把"(nudge)

网络错误之外还有一类更隐蔽的失败:模型这一轮压根没产出有效内容。InvalidStreamError 在 geminiChat.ts 里区分了 NO_FINISH_REASON、NO_RESPONSE_TEXT、MALFORMED_FUNCTION_CALL、THINKING_ONLY_RESPONSE 等类型。针对"只思考不回答"和"完全空响应"两种情况,代码内置了两句系统提示,在重试时注入到上下文末尾,逼模型交出最终答案或工具调用:

export const THINKING_ONLY_NUDGE_MESSAGE =
  '[System: You previously generated thoughts but failed to provide a final user-facing response. Please ensure you provide your final answer or call a tool now.]';

更狠的是角色交替约束:Gemini API 要求 functionResponse 必须紧跟在 functionCall 之后,所以注入 nudge 时如果发现最后一轮是携带工具响应的 user turn,代码会先插入一个合成的中立 model turn再追加提示,避免破坏 API 的角色交替不变量(applyRetryNudge 函数)。这种对上游 API 契约的逐条伺候,是"能写代码的 demo"和"能跑生产的代理"之间最直观的差距。

第三层:历史修复与中断善后

长对话意味着历史会积累脏数据。extractCuratedHistory 会从完整历史中剔除无效 model 轮次(例如被安全过滤器清空的内容);而当中断发生时,geminiChat.ts 的 finally 块会把 agent 历史回滚到本次 prompt 之前的长度,同步刷新会话录制,防止一次 Ctrl+C 在历史里留下半截工具调用,导致下一次请求直接 400。仓库里甚至为这种中断定义了合成占位内容:INTERRUPTED_RESPONSE_PLACEHOLDER("[The previous response was interrupted before it completed.]")和 INTERRUPTED_TOOL_RESPONSE_ERROR("Response was lost or interrupted."),专门用来"封口"那些永远等不到真实响应的模型 functionCall。Gemini API 不允许悬空的 functionCall,历史结构一旦破损整个会话就废了——这是流式中断场景下必须偿还的"结构债"。

第四层:循环检测——"代理跑飞了怎么办"

一个能自主循环调工具的代理,最危险的死法不是报错,而是不报错地空转。packages/core/src/services/loopDetectionService.ts 给出了两套并行的检测:

  1. 启发式:TOOL_CALL_LOOP_THRESHOLD = 5(连续 5 次语义等价的工具调用)与 CONTENT_LOOP_THRESHOLD = 10(内容重复)。
  2. LLM 诊断:单条 prompt 内超过 30 轮后激活,以 10 轮为默认间隔(根据置信度在 5~15 之间动态调整)把最近 20 轮历史交给一个独立的"诊断代理",置信度 ≥ 0.9 判定为循环,甚至还有一个别名 loop-detection-double-check 用于二次复核。

诊断提示词本身就是一篇微型"循环判定法":它明确列出不该误判的情形——跨文件批处理(给 20 个文件加 license header)、同文件不同区段的渐进编辑、修改参数后的重试都是正常推进,只有"edit → build → edit → build 且每轮参数与结果实质相同"才算死循环。

检测到循环后的处置同样分两档:第一次命中(count === 1)走 _recoverFromLoop(packages/core/src/core/client.ts),向模型注入一段反馈并递归开启新一轮:

const feedbackText = `System: Potential loop detected. Details: ${loopResult.detail || 'Repetitive patterns identified'}. Please take a step back and confirm you're making forward progress. If not, take a step back, analyze your previous actions and rethink how you're approaching the problem. Avoid repeating the same tool calls or responses without new results.`;

第二次再命中(count > 1),则放弃挣扎,yield LoopDetected 事件、终止本轮循环并把控制权交回用户。boundedTurns 递减保证了这个"再试一次"本身也是有限递归。这套"先劝、再停"的两段式设计,把"代理卡死"从一个不可预期的事故变成了可观测、可恢复、有遥测(logLoopDetected)的正常状态。

权限、审批与中断:一个决策矩阵问题

如果说失败恢复解决的是"系统故障",那么权限体系解决的是"模型故障"——当模型判断失误甚至被提示注入时,谁来兜底。gemini-cli 把这个问题抽象成了一个三值决策矩阵:

// packages/core/src/policy/types.ts
export enum PolicyDecision {
  ALLOW = 'allow',
  DENY = 'deny',
  ASK_USER = 'ask_user',
}

决策不是拍脑袋给的,而是由 packages/core/src/policy/ 下的策略引擎从 TOML 规则集中推导。仓库自带了九个策略画像:read-only.toml、write.toml、plan.toml、yolo.toml、non-interactive.toml、sandbox-default.toml……其中非交互模式(headless / CI 场景)的策略写得极为干脆:

# packages/core/src/policy/policies/non-interactive.toml
# Policy for non-interactive mode.
# ASK_USER is strictly forbidden here.
[[rule]]
toolName = "ask_user"
decision = "deny"
priority = 999
interactive = false

这条规则的深意在于:headless 场景下"问用户"这个动作本身不存在,任何会走到 ASK_USER 的路径都必须被规则前置地解析成 ALLOW 或 DENY。这是 CI/CD 集成里最容易踩的坑——交互式的确认弹窗在无 TTY 环境下会把代理挂死,或者更糟,静默吞掉。

审批模式:把"信任"做成可排序的轴

policy/types.ts 定义了四级审批模式,并且显式声明了它们的许可顺序:

export const MODES_BY_PERMISSIVENESS = [
  ApprovalMode.PLAN,
  ApprovalMode.DEFAULT,
  ApprovalMode.AUTO_EDIT,
  ApprovalMode.YOLO,
];

"更宽松模式下允许的工具,必须在更严格模式下同样被检查"是这里的设计约束——宽松是严格模式的单调上界,而不是互不相关的功能开关。这样做的工程收益是:用户从 default 切到 autoEdit 时,行为变化是可以预测的;策略规则也只需要对"能力集"做单调裁剪。

调度器:工具调用的状态机

每一次工具调用在执行前要穿过一条完整的流水线。packages/core/src/scheduler/scheduler.ts 把工具调用建模为状态机,核心生命周期是 Validating → (AwaitingApproval) → Scheduled → Executing → Success/Error/Cancelled,每次调用依次经过:

  1. BeforeTool hook:用户可编程的拦截点,可以改写参数、阻断执行;
  2. 策略检查:checkPolicy 给出三值决策;
  3. 污染风险评估:hasTaintRisk 检查该工具是否涉及"被外部内容污染过的文件或构建文件"(比如 agent 读过一篇含恶意指令的网页,随后要执行构建命令);
  4. 用户确认:需要 ASK_USER 时进入 resolveConfirmation。

有两个细节最能体现"执行"比"生成"难在哪里:

其一,ALLOW 也会被打回 ASK_USER。 调度器中有一段看似多余的覆盖逻辑:

if (decision === PolicyDecision.ALLOW && hasTaintRisk) {
  decision = (this.config.isInteractive?.() ?? true)
    ? PolicyDecision.ASK_USER
    : PolicyDecision.DENY;
}

静态策略说"允许",但动态上下文说"这次调用带着污染风险",动态信号优先——而且交互式下降级为询问、非交互下直接拒绝。这正是提示注入防护落到工程上应有的样子:不是祈祷模型不被注入,而是给执行侧加一道与模型输出正交的检查。

其二,用户拒绝的"爆炸半径"。 用户选择 Cancel 后,默认 cancelAllQueued 会把整批排队的工具调用全部取消。这不是保守,而是正确语义:模型在同一轮请求里规划的多个工具调用是一个事务意图,用户否决其中一件,往往意味着否决整个方案,而不是"这一件不行、其余继续"。

确认结果本身也在编程

用户面对确认弹窗能给出的答案远不止"是/否"。packages/core/src/tools/tools.ts 中的枚举是:

export enum ToolConfirmationOutcome {
  ProceedOnce = 'proceed_once',
  ProceedAlways = 'proceed_always',
  ProceedAlwaysAndSave = 'proceed_always_and_save',
  ProceedAlwaysServer = 'proceed_always_server',
  ProceedAlwaysTool = 'proceed_always_tool',
  ModifyWithEditor = 'modify_with_editor',
  Cancel = 'cancel',
}

ProceedAlwaysAndSave 表示"以后同类操作都允许,并持久化进配置";ModifyWithEditor 允许用户在批准前用编辑器修改将要执行的命令;ProceedAlwaysServer 与 ProceedAlwaysTool 则把授权粒度细分到"仅当前 MCP server"或"仅这个工具"。调度器拿到结果后会调用 updatePolicy 把决定回写策略层——也就是说,人的每一次审批都在训练下一轮的自动化边界。审批不是摩擦成本,而是策略系统的输入源。

Shell 工具:最危险的工具最厚的一层代码

packages/core/src/tools/shell.ts 是全部工具中逻辑最重的之一,因为它是唯一能直接触碰操作系统的能力。它的 shouldConfirmExecute 里能看到的防线包括:

  • 沙箱权限外扩:命令在沙箱中因缺网络/缺写路径被拦下时,不是简单失败,而是弹出 sandbox_expansion 确认,展示"这条命令需要哪些额外权限"(逐路径核对 read/write/network 是否已授权),用户批准后才放行,且批准结果缓存为 proactivePermissionsConfirmed;
  • 后台进程 PID 捕获:后台命令会被包一层子 shell,trap 'jobs -p > "$_bgpids_file"' EXIT 在退出时把子进程 PID 落盘——代理必须知道自己在系统里留下了哪些进程,否则"中断"就只是关掉了前台;
  • 输出治理:实时输出缓冲上限 100,000 字符(LIVE_OUTPUT_MAX_BUFFER_CHARS),且裁剪时要小心别从 UTF-16 代理对中间切开(trimLiveOutputBuffer 里专门检查了 0xdc00~0xdfff 的低代理项)。命令输出是会被回灌给模型的上下文,脏输出既撑爆 token 预算也会污染推理。

而执行侧的错误处理,关键在 packages/core/src/tools/tool-error.ts 的注释里写明了设计哲学:错误分为"LLM 可以自我纠正"和"系统状态已坏"两类:

export enum ToolErrorType {
  POLICY_VIOLATION = 'policy_violation',
  INVALID_TOOL_PARAMS = 'invalid_tool_params',
  FILE_NOT_FOUND = 'file_not_found',
  PERMISSION_DENIED = 'permission_denied',
  ...
  NO_SPACE_LEFT = 'no_space_left',
  ...
}

export function isFatalToolError(errorType?: string): boolean {
  const fatalErrors = new Set<string>([ToolErrorType.NO_SPACE_LEFT]);
  return fatalErrors.has(errorType);
}

FILE_NOT_FOUND 是提示——模型换条路;NO_SPACE_LEFT 是终局——磁盘都满了,再"自我纠正"一百次也没用,进程该退出就退出。把错误分类的边界画在这里,等于把"哪些失败交给模型、哪些失败交给系统"写成了显式契约。

从单步生成到多步代理:架构是怎么"长"出来的

把前面两节的代码放在一起看,能还原出 Gemini CLI 的架构演进轨迹——它几乎是从"单步生成"向"多步代理"逐层加壳长出来的。

起点是纯生成。 最朴素的形态就是:用户输入 → 模型输出文本/代码建议,开发者自己复制粘贴执行。这个形态下唯一的可靠性问题是 API 可用性。

第一步加壳:工具循环。 模型开始输出 functionCall,本地执行 WriteFile、Edit、Shell 等工具,把结果作为 functionResponse 回灌,循环直至 finishReason 收尾。仓库里 Turn 类、tool-registry.ts、agent-loop-context.ts 都服务于这一层。此时新出现的可靠性问题是上文的全部四层防线:流会断、内容会空、历史会烂、循环会飞。

Gemini CLI 终端界面:模型创建 hello.py 并展示 WriteFile 工具调用确认,底部显示 2 个 GEMINI.md、2 个 MCP server 与 no sandbox 状态

第二步加壳:执行治理。 工具一旦能改状态,就需要策略引擎、审批模式、沙箱、hook、MCP 合规传输这一整层"执行前检查"。policy/、scheduler/、safety/、confirmation-bus/ 四个目录基本是同一时期长出来的器官。这一层的标志物是上文引用的非交互策略与污染风险覆盖——它们回答的问题已经不是"模型怎么调",而是"模型说了不算"。

第三步加壳:并发与委托。 当工具调用可以并行(isParallelizable 批量出队)、子代理可以派生(调度器参数中的 subagent、parentCallId,以及 Kind.Agent 这类工具类型),架构就必须处理批内事务性(一个 Cancel 波及整批)、跨层中断(AbortSignal 贯穿调度器、执行器、shell 进程)和历史归属(谁的工具结果进谁的上下文)。

第四层(正在发生):模型不再是单点。 client.ts 里每个 turn 之前都要过 getModelRouterService().route(...),fallback/handler.ts 则维护着模型可用性状态机:主模型失败后按策略链选择第一个可用候选,isLastResort 兜底,甚至允许"回到刚才还能用的模型"。模型从"配置项"变成了"带健康状态的资源池"——这是多步代理对上游的最后一次架构加壳:既然一个任务要跑几十轮,单模型的可用性曲线就不再是 99% 而是 99%^N,路由与降级就成了和重试同级的基础设施。

这条演进路径也解释了社区里反复出现的争论。发布初期,中文技术社区(掘金、CSDN 等)的关注点集中在免费额度、100 万 token 上下文和"硬刚 Claude Code";而真正的使用者很快把讨论拉回了信任问题——"像早期预览版,距稳定可靠还有距离"。2026 年年中,谷歌将个人版 Gemini CLI 的服务迁移到统一代理架构的 Antigravity CLI,开发者社区对闭源化与配额缩减的吐槽,本质上还是同一笔账:额度是营销能解决的,但"敢不敢让它在我机器上执行命令"是架构要回答的。开源仓库留下的这些代码——从 SSL 错误码正则到循环诊断提示词——正是这个问题的答案草稿。

结语

"能写代码"考验的是模型;"能执行命令"考验的是围绕模型的那一圈工程。gemini-cli 仓库给出了一份相当诚实的清单:指数退避与重试预算、内容 nudge 与历史回滚、循环诊断与两段式熔断、三值策略矩阵与可持久化的审批结果、污染风险对静态策略的动态否决、以及按"模型能否自愈"划线的错误分类。每一项都不性感,但缺任何一项,"终端里的 AI 搭子"就会在真实环境里露馅。对正在自研终端代理的团队来说,这份仓库价值最大的部分也许不是它做了什么功能,而是它把"执行侧故障"枚举得多具体。

登录后查看全文
gemini-cli