Skip to content

architecture-deep-dive.md

Latest commit

 

History

History
639 lines (492 loc) · 30.4 KB

architecture-deep-dive.md

File metadata and controls

639 lines (492 loc) · 30.4 KB
Raw

2. Code Agent 架构深度对比（源码级分析）

基于 9 个开源项目 + 1 个闭源项目（Claude Code）本地源码的深入分析，对比 AI 编程代理的核心架构设计

通用代理循环架构图

graph TD
    U[用户输入] --> SP[系统提示组装]
    SP --> |"系统提示 + 工具定义 + 上下文"| API[LLM API 调用]
    API --> R{响应类型?}
    R --> |文本| OUT[输出给用户]
    R --> |工具调用| TC[工具执行]
    TC --> |权限检查| PERM{允许?}
    PERM --> |允许| EXEC[执行工具]
    PERM --> |拒绝| DENY[用户确认/拒绝]
    DENY --> |用户允许| EXEC
    DENY --> |用户拒绝| FEEDBACK[反馈给 LLM]
    EXEC --> RESULT[工具结果]
    RESULT --> |追加到上下文| CTX{上下文满?}
    CTX --> |否| API
    CTX --> |是| COMPACT[上下文压缩]
    COMPACT --> API
    R --> |停止| STOP{完成?}
    STOP --> |是| END[结束]
    STOP --> |反射/重试| API

    style U fill:#e1f5fe
    style API fill:#fff3e0
    style EXEC fill:#e8f5e9
    style COMPACT fill:#fce4ec
    style END fill:#f3e5f5
Loading

各工具架构差异

graph LR
    subgraph "Claude Code (Rust)"
        CC_IN[输入] --> CC_SYS["8模块系统提示<br/>bo1/mo1/Uo1/xo1"]
        CC_SYS --> CC_API["Anthropic API<br/>cache_control: ephemeral"]
        CC_API --> CC_SEC["安全监控<br/>28 BLOCK 规则<br/>双阶段分类器"]
        CC_SEC --> CC_TOOL["20+ 工具<br/>+ MCP + Skill"]
    end

    subgraph "Aider (Python)"
        AI_IN[输入] --> AI_MAP["RepoMap<br/>PageRank + Tree-sitter"]
        AI_MAP --> AI_API["LiteLLM<br/>100+ 模型"]
        AI_API --> AI_EDIT["14种编辑格式<br/>diff/whole/patch/udiff"]
        AI_EDIT --> AI_REF["反射循环<br/>lint→test→retry×3"]
    end

    subgraph "Codex CLI (Rust)"
        CX_IN[输入] --> CX_API["OpenAI API<br/>GPT-5 系列"]
        CX_API --> CX_GUARD["Guardian<br/>审批系统"]
        CX_GUARD --> CX_SAND["3平台沙箱<br/>Seatbelt/Bwrap/WinToken"]
        CX_SAND --> CX_TOOL["apply_patch<br/>+ Shell"]
    end
Loading

上下文管理对比

graph TD
    subgraph "压缩触发阈值"
        G["Gemini CLI<br/>50% ← 最早触发"] --> K["Kimi CLI<br/>80%/85%"]
        K --> C["Claude Code<br/>~95% ← 最晚触发"]
    end

    subgraph "压缩算法复杂度"
        A_SIMPLE["Aider<br/>递归分割×3<br/>后台线程"] --> K_STRUCT["Kimi CLI<br/>结构化XML<br/>自定义焦点"]
        K_STRUCT --> C_THREE["Claude Code<br/>三层压缩<br/>微+自动+手动"]
        C_THREE --> G_FOUR["Gemini CLI<br/>四阶段+验证<br/>最复杂"]
    end
Loading

分析范围

项目 语言 代码量 本地路径
Aider Python ~30k 行 /root/git/aider
Goose Rust ~55k 行 /root/git/goose
Gemini CLI TypeScript ~191k 行 /root/git/gemini-cli
Qwen Code TypeScript ~191k 行（分叉） /root/git/qwen-code
OpenCode TypeScript（Bun） ~50k 行 /root/git/opencode
Cline TypeScript ~40k 行 /root/git/cline
SWE-agent Python ~20k 行 /root/git/swe-agent
OpenHands Python ~60k 行 /root/git/openhands
Kimi CLI Python ~20k 行 /root/git/kimi-cli
Claude Code Rust 专有 /root/git/claude-code

1. 代理循环模式

所有工具的核心都是一个代理循环，但实现方式差异显著：

工具调用循环（主流）

消息 → LLM → function calling → 工具执行 → 结果 → 重复

使用者：Claude Code、Gemini CLI、Qwen Code、Codex CLI、OpenCode、Cline、Goose、Copilot CLI、Kimi CLI

  • Claude Code 使用 Anthropic tool_use API，20+ 内置工具
  • Gemini CLI/Qwen Code 使用 @google/genai function calling，CoreToolScheduler（1790 行）调度工具
  • Codex CLI 使用 OpenAI function calling + apply_patch
  • OpenCode 使用 Vercel AI SDK v5 统一接口，18 工具（14 无条件 + 4 有条件）
  • Cline 在 VS Code 内执行，24+ 工具，每步自动 Git Checkpoint
  • Goose 通过 MCP 协议统一工具接口（所有工具走 MCP）
  • Copilot CLI 使用 YAML 定义的代理，tool_choice 列出现在模型配置矩阵
  • Kimi CLI "工具调用解析" + ToolCall/ToolResult Wire 事件，多提供商

注 1：许多交互式 coding agent 都可以理解为 ReAct-like 循环（reasoning → acting → observation → repeat）。差异主要在于动作表达/编排机制：function calling、文本解析、编辑格式、事件流等。

注 2：Cursor、Warp、Continue、Qoder CLI 等闭源/IDE 嵌入式 Agent 具有工具系统能力（多支持 MCP），但本仓库现有证据不足以确认其使用原生 API function calling，暂不列入。Oh My OpenAgent 基于 OpenCode Harness 层，继承工具调用架构但不直接调用 LLM API。

混合 ReAct 循环

思考 → 动作 → 解析 → 执行 → 观察 → 重复

使用者：SWE-agent

  • SWE-agent 的 DefaultAgent.step() 支持多种解析器，FunctionCallingParser（原生 function calling，默认）和纯文本 ThoughtActionParser、ActionOnlyParser
  • 文本动作解析是兼容路径，适用于不支持 function calling 的模型，也是其鲜明特征之一
  • 与"工具调用"流派的区别：SWE-agent 同时支持两种动作表达方式，而非仅依赖原生 function calling

编辑-提交循环

发送 → 解析编辑 → 应用修改 → Git 提交 → Lint/测试 → 反思

使用者：Aider

  • 独特的编辑格式系统（14 种），模型输出直接包含代码修改
  • 反思循环：lint/测试失败自动重试（最多 3 次）
  • 每次修改自动 Git 提交，天然版本控制

事件驱动循环

Action → EventStream → Runtime → Observation → 订阅者通知

使用者：OpenHands

  • 最复杂的架构：EventStream 发布/订阅总线
  • Action 和 Observation 完全解耦
  • 支持多代理委托和异步执行

2. LLM 接入策略

策略对比

策略 实现方式 支持提供商 使用者
LiteLLM 统一 Python 包装 100+ 模型 100+ Aider, SWE-agent, OpenHands
Vercel AI SDK TS SDK 统一 streamText() + models.dev 动态加载 100+ OpenCode（TUI 层）
独立 Generator 每个提供商独立实现 1（Gemini CLI）/ 6+（Qwen Code） Gemini CLI, Qwen Code
Provider trait Rust trait 抽象 58+ Goose
Handler 工厂 每个提供商一个 Handler 48+ Cline
单提供商 直连特定 API 1 Claude Code

模型选择与路由

Agent 模型路由 弱模型 回退
Aider model-settings.yml 预配置 ✓（历史摘要用便宜模型） 手动切换
Gemini CLI ModelRouterService（Fallback/Override/Classifier） ✓ 自动回退链
Goose 模型注册表 ✓（轻量操作） 手动切换
SWE-agent 配置驱动 + 多 Key 负载均衡 ✓ LiteLLM fallbacks
其他 单模型或手动选择

3. 工具系统设计

工具数量与类型

Agent 内置工具数 文件操作 Bash 搜索 Web 浏览器 MCP
Aider ~15 命令 ✓ ✓ ✓ ✓
Goose MCP 驱动 ✓ ✓ ✓ ✓（截图） ✓ 原生
Gemini CLI 23（17 核心 + 6 任务追踪） ✓ ✓ ✓ ✓ ✓
Qwen Code 16 ✓ ✓ ✓ ✓ ✓
OpenCode 18（14 无条件 + 4 有条件） ✓ ✓ ✓ ✓ ✓
Cline 24+ ✓ ✓ ✓ ✓ ✓（Headless） ✓
SWE-agent Bundle 驱动 ✓ ✓ ✓ ✓
OpenHands 8 核心 ✓ ✓ ✓ ✓（Playwright） ✓

工具定义模式

模式 定义方式 校验 使用者
声明式类 TypeScript 抽象类 Zod / FunctionDeclaration Gemini CLI, Qwen Code, OpenCode
Rust trait rmcp::Tool JSON Schema Goose
Python dataclass @dataclass Action Pydantic OpenHands, SWE-agent
YAML Bundle 配置文件定义 参数类型校验 SWE-agent
无正式注册 命令行解析 configargparse Aider

编辑策略

Agent 编辑方式 特色
Aider 14 种编辑格式（whole/diff/udiff/patch/architect...） 按模型能力自动选择
Claude Code 原生编辑工具 差异预览
OpenCode edit + apply_patch（GPT 专用） 按模型切换
Cline replace_in_file (search/replace) + write_to_file Checkpoint 回滚
Gemini CLI edit 工具（声明式） 策略审批
SWE-agent str_replace_editor (Bundle) 支持 undo_edit
OpenHands StrReplaceEditorTool + LLMBasedFileEditTool 双编辑模式

4. 权限与安全

安全模型对比

Agent 权限模型 策略格式 特殊能力
Claude Code 精细工具权限 配置文件 沙箱网络控制
OpenCode 分层规则 (allow/deny/ask) JSON Tree-sitter bash AST 分析
Gemini CLI PolicyEngine TOML 外挂安全检查器进程
Qwen Code deny > ask > allow > default JSON Hook 拦截权限请求
Cline 命令权限控制器 正则 + 设置 重定向/子 shell 检测
Goose 四模式 (Auto/Approve/Smart/Chat) YAML 环境变量白名单（31 项）
SWE-agent Docker 沙箱隔离 配置 命令超时 + 成本上限
OpenHands 三层安全分析 配置 + 外部 LLM 风险 + Invariant + GraySwan
Aider 信任模式 无 用户确认 shell 命令

创新安全特性

特性 工具 说明
Tree-sitter Bash 分析 OpenCode AST 级解析命令，自动提取目录和操作
TOML 策略引擎 Gemini CLI 通配符 + 正则 + 四种审批模式
Doom Loop 保护 OpenCode 3 次连续拒绝自动中断
Loop 检测 Qwen Code Levenshtein 距离检测重复调用
三层安全分析 OpenHands LLM 风险评估 + 策略检查 + 外部监控
环境变量白名单 Goose 31 个危险变量禁止注入
Git Checkpoint Cline 每步操作 Git 快照，一键回滚
重定向检测 Cline 检测 >, >>,

5. 上下文管理

上下文窗口策略

Agent 最大上下文 压缩策略 特殊优化
Claude Code 100 万 token 自动压缩 最大上下文窗口
Aider 按模型 ChatChunks 分块 + 弱模型摘要 Prompt 缓存保活 ping
Gemini CLI ~100 万 ChatCompressionService 思维链不回传
Qwen Code ~100 万 ChatCompressionService（继承） Token 阈值触发
OpenCode 按模型 会话压缩 工具输出 32K 截断
Cline 按模型 Hook 压缩 扩展思维预算控制
SWE-agent 按模型 HistoryProcessor（LastN/CacheControl） 成本上限 $3/实例
OpenHands 按模型 递归对话压缩 Condenser 深度可配置

Aider 的 RepoMap——最独特的上下文方案

Tree-sitter AST 解析（30+ 语言）
  → 提取函数/类定义标签
  → SQLite 磁盘缓存
  → 按提及标识符排名
  → 树形结构输出
  → Token 预算截断

其他工具依赖 LLM 工具调用来探索代码库，Aider 主动构建代码地图，大幅减少 LLM 需要的探索轮次。

6. 存储架构

Agent 存储方式 查询能力 持久化
OpenCode SQLite（Drizzle ORM） SQL 查询 完整关系存储
OpenHands EventStream + FileStore (PostgreSQL V1) 事件过滤 + SQL 事件持久化
Aider diskcache (SQLite) + 内存 缓存查询 标签缓存
Gemini CLI .gemini/sessions/ 文件 文件遍历 JSON 会话
Qwen Code .qwen/tmp/ JSONL 文件 分页读取 JSONL 追加
Cline ~/.cline/data/ 文件 文件读取 JSON
SWE-agent trajectory JSON 无查询 轨迹文件
Goose JSON 文件 + keyring 文件读取 会话 + 密钥链
Hermes Agent SQLite + FTS5 虚拟表（hermes_state.py） FTS5 BM25 全文搜索 + LLM 摘要 Markdown（MEMORY.md/USER.md/SKILL.md）+ SQLite（会话 + 索引）

7. 扩展/插件生态

MCP 支持程度

Agent MCP 客户端 MCP 服务器 传输方式
Goose ✓（原生） ✓（内置） Stdio, HTTP, Builtin
Hermes Agent ✓（tools/mcp_tool.py） ✓（mcp_serve.py，9 OpenClaw 工具 + channels_list） Stdio, HTTP/StreamableHTTP
Claude Code ✓ Stdio, SSE, Streamable-HTTP
OpenCode ✓ HTTP, SSE, Stdio, WebSocket
Gemini CLI ✓ Stdio, SSE, HTTP
Qwen Code ✓ Stdio, SSE, HTTP
Cline ✓ Stdio, SSE, HTTP
OpenHands ✓ FastMCP
Kimi CLI ✓ Stdio, HTTP
Aider 不支持
SWE-agent 不支持

扩展系统

Agent 扩展类型 加载方式
OpenCode npm 插件 + Hook 配置文件引用
Qwen Code 扩展 + Claude/Gemini 格式转换 Git clone / Release
Cline Skills + Workflows + Hook Markdown 文件
Goose MCP 扩展 + Recipe YAML 配置
Gemini CLI Skills + MCP Markdown + 配置
OpenHands 插件 + Microagent Python + Markdown

8. TUI/UI 框架

Agent 框架 特点
Aider prompt_toolkit + Rich Python 终端，最轻量
Hermes Agent prompt_toolkit + Rich Python 终端 + 14 个消息渠道 Web/Bot UI
Goose Rust CLI + Electron 桌面 Rust 原生性能
Gemini CLI Ink 6 + React 19 终端 React 组件
Qwen Code Ink 6 + React 19（继承） + Vim 模式
OpenCode OpenTUI + Solid.js 信号驱动响应式
Cline VS Code WebView + React IDE 原生
SWE-agent Textual + Rich Python TUI
OpenHands FastAPI + React Web UI

9. 多代理设计

Agent 代理类型 并行能力 委托
OpenCode build, plan, general, explore + 自定义 ✓（子代理） @ 引用
Qwen Code 主代理 + 子代理 + Arena ✓（Tmux/iTerm2） agent 工具
OpenHands CodeAct, Browsing, Visual, ReadOnly ✓ AgentDelegate
Cline 主代理 + 子代理 Skill 调用
Claude Code 主代理 + 子代理 ✓（worktree） Agent 工具
Aider Architect 两阶段 内部委托
SWE-agent DefaultAgent + RetryAgent 审查循环
Goose 单代理 + 调度 Recipe
Hermes Agent 主代理 + 后台 Review 子代理（memory/skill 学习闭环） ✓（线程异步） delegate_tool + mixture_of_agents_tool + 后台 spawn

10. 技术栈总览

Agent 语言 运行时 包管理 构建
Aider Python CPython pip/pipx setuptools
SWE-agent Python CPython pip setuptools
OpenHands Python CPython Poetry Poetry
Goose Rust 原生 Cargo Cargo
Claude Code Rust 原生 npm(发布) Cargo
Gemini CLI TypeScript Node.js npm esbuild
Qwen Code TypeScript Node.js npm esbuild
OpenCode TypeScript Bun Bun Turbo
Cline TypeScript Node.js npm esbuild
Hermes Agent Python（369K 行，822 文件） CPython 3.11+ pip / setuptools setuptools

关键洞察

1. 四大架构流派

  • 编辑优先（Aider）：LLM 直接输出代码修改，需文本解析，工具是辅助
  • 工具调用（Claude Code、Gemini CLI、Qwen Code、Codex CLI、OpenCode、Cline、Goose、Copilot CLI、Kimi CLI）：LLM 通过结构化 function calling 操作环境，是主流模式
  • 混合 ReAct（SWE-agent、mini-swe-agent）：兼容 function calling（默认）与文本动作解析，文本解析是其鲜明特征
  • 事件驱动（OpenHands）：完全解耦的事件总线，最灵活但最复杂

关键认知：许多交互式 coding agent 都可以理解为 ReAct-like 循环（reasoning → acting → observation → repeat）。本文为了可操作地分类，主要按动作表达/编排机制区分：function calling、文本解析、编辑格式、事件流等。ReAct 原论文的核心是 reasoning + acting + observation 的交错交互模式，不强制要求动作用纯文本表达。

未列入的 Agent：Cursor、Warp、Continue、Qoder CLI 等闭源/IDE 嵌入式 Agent 暂因证据不足未列入「工具调用」流派。Oh My OpenAgent 基于 OpenCode Harness 层，继承工具调用架构但不直接调用 LLM API，视为「工具调用」的间接成员。

2. Gemini CLI 是事实上的"开源 Claude Code 模板"

Gemini CLI 的架构被 Qwen Code 直接分叉，其设计模式（声明式工具 + 事件调度器 + 策略引擎）影响了多个后续项目。

3. Rust vs TypeScript vs Python

  • Rust（Goose, Claude Code）：性能最佳，内存最低，但插件生态门槛高
  • TypeScript（Gemini CLI, Qwen Code, Cline）/ TypeScript(Bun)（OpenCode）：生态最丰富，Ink/React 终端 UI 成熟
  • Python（Aider, SWE-agent, OpenHands）：LiteLLM 生态强大，学术研究首选

4. 安全是差异化关键

  • 权限系统从"无"（Aider 信任模式）到"三层分析"（OpenHands）差异巨大
  • 创新方向：Tree-sitter 命令分析（OpenCode）、TOML 策略引擎（Gemini CLI）、环境变量白名单（Goose）

5. MCP 正在成为标准

8/10 个工具支持 MCP（仅 Aider 和 SWE-agent 不支持），Goose 甚至将所有工具都通过 MCP 提供。未来 MCP 将是代理工具扩展的统一协议。Hermes Agent 实现 MCP 双向集成：既是 MCP Client（连接外部 server）也是 MCP Server（暴露跨平台对话为 9 个 OpenClaw 工具 + channels_list），让 Claude Code / Cursor / Codex 等可以通过 MCP 操控 Hermes 的消息渠道。

6. 闭环学习系统：新的差异化方向

Hermes Agent 引入了原生的闭环学习系统（Closed Learning Loop），包含 4 个子系统：

  1. 冻结快照 Memory（保护 prompt cache）
  2. 自主 Skill 创建 + patch 自修补
  3. SQLite FTS5 跨会话搜索 + Gemini Flash 摘要
  4. 双计数器 Nudge 触发后台 review 子代理

这是 19 款 Code Agent 中唯一完整实现该范式的产品。Claude Code Auto-Memory 和 Qwen Code PR #3087（开发中）在部分功能上有对标。详见 闭环学习系统深度对比。

分析基于本地源码仓库，截至 2026 年 3 月。

附录 A：源码级精确参数（GitHub API 验证）

以下数据全部通过 gh api 直接从各项目 GitHub 仓库提取，附带源码位置。

A.1 Aider — 编辑格式（14 种）

编辑格式名称 源码文件 说明
diff editblock_coder.py 搜索/替换代码块（默认）
diff-fenced editblock_fenced_coder.py 围栏搜索/替换块
whole wholefile_coder.py 输出整个文件
udiff udiff_coder.py 统一 diff 格式
udiff-simple udiff_simple.py 简化统一 diff
patch patch_coder.py Git patch 格式
architect architect_coder.py 架构师→编辑器两阶段
ask ask_coder.py 仅问答，不编辑
context context_coder.py 上下文选择
help help_coder.py 帮助系统
editor-diff editor_editblock_coder.py 编辑器模式搜索/替换
editor-whole editor_whole_coder.py 编辑器模式整文件
editor-diff-fenced editor_diff_fenced_coder.py 编辑器模式围栏 diff
（函数调用） wholefile_func_coder.py, editblock_func_coder.py, single_wholefile_func_coder.py 基于 function calling 的变体

A.2 Aider — 代理循环与 API 参数

循环结构 (base_coder.py):

run() → run_one() → while message: send_message() → 检查 reflected_message → 重复
参数 值 源码位置
max_reflections 3 base_coder.py:101 — lint/测试失败后自动反思次数上限
temperature 0（默认） models.py:988 — use_temperature=True 时默认 0
use_temperature False 用于推理模型 models.py — DeepSeek R1、o1/o3/o4、GPT-5 关闭温度
request_timeout 600 秒 models.py — API 请求超时
RETRY_TIMEOUT 60 秒 models.py — 重试退避上限（初始 0.125s，指数增长）
streaming True（默认） models.py — 默认流式输出
LLM 调用方式 litellm.completion(**kwargs) models.py:1020 — 通过 LiteLLM 统一调用

重试策略: 指数退避（0.125s → 0.25s → 0.5s → ... → 最大 60s），仅重试 LiteLLM 标记为可重试的错误。

A.3 Gemini CLI — 代理循环与 API 参数

循环结构 (client.ts):

generateContent() → processTurn() → handleToolCalls() → 重复（最多 MAX_TURNS 轮）
参数 值 源码位置
MAX_TURNS 100 client.ts:81 — 单次对话最大轮次
DEFAULT_TOKEN_LIMIT 1,048,576 (1M) tokenLimits.ts:20 — 所有 Gemini 模型
DEFAULT_MAX_ATTEMPTS（重试） 10 retry.ts:20 — API 调用最大重试次数
initialDelayMs（重试） 5000 retry.ts:44 — 重试初始延迟 5 秒
maxDelayMs（重试） 30000 retry.ts:45 — 重试最大延迟 30 秒
重试条件 429 + 5xx retry.ts:150 — 仅重试速率限制和服务器错误

生成配置 (defaultModelConfigs.ts):

配置别名 temperature topP topK thinkingConfig
base 0 1 — —
chat-base 1 0.95 64 includeThoughts: true
chat-base-2.5 继承 chat-base 继承 继承 thinkingBudget: DEFAULT_THINKING_MODE
chat-base-3 继承 chat-base 继承 继承 thinkingLevel: HIGH
classifier 继承 base (0) 继承 (1) — thinkingBudget: 512, maxOutputTokens: 1024
prompt-completion 0.3 继承 — thinkingBudget: 0, maxOutputTokens: 16000
fast-ack-helper 0.2 继承 — thinkingBudget: 0, maxOutputTokens: 120

A.4 Kimi CLI — 代理循环与 API 参数

循环结构 (kimisoul.py):

run() → while True: step_no++ → 检查 max_steps → auto_compact → _step() → 检查 stop_reason
参数 值 源码位置
max_steps_per_turn 100 config.py:71-72 — 单轮最大步数
max_retries_per_step 3 config.py:77 — 单步最大重试次数
max_ralph_iterations 0（默认），-1 无限 config.py:79 — Ralph 模式额外迭代
reserved_context_size 50,000 tokens config.py:81 — LLM 响应预留空间
compaction_trigger_ratio 0.85 (85%) config.py:85 — 上下文使用率触发压缩阈值
default_max_tokens 50,000（Anthropic provider） llm.py:171
重试策略 tenacity 指数抖动退避 kimisoul.py:687-691 — initial=0.3, max=5, jitter=0.5
环境变量覆盖 KIMI_MODEL_TEMPERATURE, KIMI_MODEL_TOP_P, KIMI_MODEL_MAX_TOKENS, KIMI_MODEL_MAX_CONTEXT_SIZE llm.py:139-144, 75-77

上下文压缩: 双触发条件 — context_tokens >= max_context_size * 0.85 或 context_tokens + 50000 >= max_context_size。压缩时用 LLM 生成摘要，保留最近消息，字符级 token 估算（~4 字符/token）。

A.5 Goose — 代理循环与 API 参数

循环结构 (agent.rs):

reply() → loop { provider.complete() → handle tool_calls → execute → append results → 重复 }
参数 值 源码位置
temperature None（默认），可通过 GOOSE_TEMPERATURE 环境变量设置 model.rs:157-158
max_tokens None（默认），可通过 GOOSE_MAX_TOKENS 设置 model.rs:178-179
GOOSE_AUTO_COMPACT_THRESHOLD 0.8 (80%) 环境变量（官方文档）— 上下文压缩触发阈值
DEFAULT_RETRY_TIMEOUT_SECONDS 300（5 分钟） types.rs:16 — Recipe 重试超时
DEFAULT_ON_FAILURE_TIMEOUT_SECONDS 600（10 分钟） types.rs:19 — 失败后操作超时
RetryConfig.max_retries 用户配置，必须 > 0 types.rs:25 — Recipe 执行重试上限
工具输出批量摘要 10 个工具调用/批次 context_mgmt/mod.rs:21 — TOOLCALL_SUMMARIZATION_BATCH_SIZE

ModelConfig 结构 (model.rs:48):

pub struct ModelConfig {
    pub model_name: String,
    pub context_limit: Option<usize>,
    pub temperature: Option<f32>,
    pub max_tokens: Option<i32>,
    pub toolshim: bool,           // 为不支持工具调用的模型启用 shim
    pub toolshim_model: Option<String>,
    pub request_params: Option<HashMap<String, Value>>,
    pub reasoning: Option<bool>,
}

A.6 跨项目参数对比总览

维度 Aider Gemini CLI Kimi CLI Goose
循环上限 3 次反思 100 轮 100 步/轮 无固定上限
默认温度 0 0（base）/ 1（chat） 环境变量控制 环境变量控制
重试次数 指数退避到 60s 10 次 3 次/步 用户配置
重试延迟 0.125s → 60s 5s → 30s 0.3s → 5s（+抖动） 300s 超时
压缩阈值 ChatChunks 分块 50% 容量 85% 上下文 80% 上下文
预留空间 无 无 50K tokens 无
LLM 调用 LiteLLM @google/genai SDK kosong (自研) + tenacity Provider trait
流式输出 默认开启 默认流式 流式 Provider 决定

代理循环工程洞察

Codex CLI 代理循环内部（来源：OpenAI Engineering Blog，2026-01-24）

"The agent loop is the core logic in Codex CLI that is responsible for orchestrating the interaction between the user, the model, and the tools the model invokes."

二次方成本问题：每次工具调用迭代都追加到 prompt，导致"A single turn can involve many iterations between model inference and tool execution"，发送到 Responses API 的 JSON 量呈二次方增长。

解决方案——Prompt 缓存使采样变为线性：通过保持请求间的精确前缀匹配实现缓存命中，"With cache hits, sampling becomes linear rather than quadratic."

无状态架构（隐私优先）：Codex CLI 故意不使用 previous_response_id，"every request is stateless, which is essential for ZDR customers who have opted out of data storage."

三类工具的信任边界：

工具来源 沙箱 信任级别
Codex 内置工具 OS 级沙箱 最高
API 提供的工具 无沙箱 中等
MCP 服务器工具 无沙箱，需自行保障 最低

"Other tools from MCP servers are not sandboxed by Codex and must enforce their own guardrails."

Agent 反馈循环设计原则（来源：Claude Agent SDK，2025-09-29）

"The key design principle behind Claude Code is that Claude needs the same tools that programmers use every day."

"Agents often operate in a specific feedback loop: gather context -> take action -> verify work -> repeat."

三层验证模式：

层 类型 示例
规则反馈 确定性 代码 lint、类型检查、测试
视觉反馈 半确定性 截图/渲染比较
LLM-as-Judge 概率性 另一个模型评估输出质量

Agent 协议全景（来源：Google Developers Blog，2026-03-18）

6 大标准化协议构成分层架构：

协议 层 解决的问题
MCP 数据层 Agent ↔ 系统/数据库
A2A Agent 层 Agent ↔ Agent 互操作
UCP 商业层 标准化交易
AP2 授权层 支付护栏
A2UI UI 层 18 个组件原语的声明式 JSON
AG-UI 流式层 Agent → 前端的标准化 SSE 事件流

A2A 是 MCP 的补充而非替代——"MCP provides helpful tools and context to agents; A2A lets agents talk to each other as opaque peers."

Harness Engineering：代理循环之上的环境设计（来源：OpenAI Blog，2026-02-11）

代理循环是 Agent 的内核，而 Harness 是包裹内核的外壳——决定了 Agent 在什么约束下、使用什么文档、通过什么反馈循环来工作。

"Humans steer. Agents execute."

"Give Codex a map, not a 1,000-page instruction manual."——AGENTS.md 作为导航地图指向 docs/ 结构化文档，而非把所有信息塞进一个文件。

Harness vs 代理循环的关系：

Harness（环境设计）
  ├── 文档系统（AGENTS.md → docs/ 结构化文档）
  ├── 架构约束（分层依赖规则、linter 检查）
  ├── 反馈循环（测试失败 → Agent 自修复）
  └── 熵管理（定期清理 Agent）
      │
      └── 代理循环（Agent 内核）
            ├── 系统提示组装
            ├── LLM API 调用
            ├── 工具执行 + 权限检查
            └── 上下文压缩

关键实证：LangChain coding agent 仅修改 Harness（不改模型），Terminal Bench 2.0 分数从 52.8% 提升到 66.5%——表明 Harness 优化可以在不更换模型的情况下带来显著性能提升。详见构建自己的 AI 编程 Agent中的「Harness Engineering」章节。

实践案例：Oh My OpenAgent（45k Stars）在 OpenCode 之上构建了 710 个 Discipline Agent 编排 + 分类模型路由 + Hash-Anchored Edit，是目前最成功的开源 Harness 层实践。