用 UML 拆解两个 Agent 的骨架

%% UML 包图 · mini-swe-agent vs SWE-agent 源码组织对照 %% 标本: mini 04d809c / SWE-agent 3ea751c %% ⚠️ mermaid 无原生 Package Diagram 语法，本图以 flowchart + subgraph 近似表达 flowchart TB subgraph PKG_MINI["「mini-swe-agent」源码组织 · commit 04d809c"] direction TB ID_mini_root["minisweagent/__init__
Model·Environment·Agent Protocol"] ID_mini_run["run/
CLI 入口 (typer)"] ID_mini_agents["agents/
DefaultAgent·InteractiveAgent"] ID_mini_models["models/
Litellm·OpenRouter·Portkey·Requesty"] ID_mini_envs["environments/
local·docker·singularity"] ID_mini_cfg["config/
default.yaml·mini.yaml"] ID_mini_run --> ID_mini_root ID_mini_run --> ID_mini_agents ID_mini_run --> ID_mini_models ID_mini_run --> ID_mini_envs ID_mini_agents --> ID_mini_models ID_mini_agents --> ID_mini_envs ID_mini_models --> ID_mini_root ID_mini_envs --> ID_mini_root ID_mini_cfg -.->|"渲染/装配"| ID_mini_run end subgraph PKG_SWE["「SWE-agent」源码组织 · commit 3ea751c"] direction TB ID_swe_types["types.py
StepOutput·TrajectoryStep"] ID_swe_run["run/
RunSingle·RunBatch·hooks"] ID_swe_agent["agent/
AbstractAgent·RetryAgent·DefaultAgent"] ID_swe_env["environment/
SWEEnv·repo·hooks"] ID_swe_tools["tools/
ToolHandler·parsing·commands"] ID_swe_utils["utils/
log·patch 工具"] ID_swe_run --> ID_swe_agent ID_swe_run --> ID_swe_env ID_swe_agent --> ID_swe_tools ID_swe_agent --> ID_swe_types ID_swe_tools --> ID_swe_types ID_swe_env --> ID_swe_types ID_swe_agent --> ID_swe_utils ID_swe_env --> ID_swe_utils end ID_NOTE_EXC["横切关注点（两侧共用，不入包图主干）
mini: exceptions.py（中断型异常树）
SWE: run/hooks/ · environment/hooks/（生命周期钩子）"] classDef cfg fill:#f5f7fb,stroke:#4f5dd5,stroke-width:1px classDef root fill:#eef1f8,stroke:#185fa5,stroke-width:1px classDef note fill:#fffbe6,stroke:#ba7517,stroke-width:1px,stroke-dasharray:4 3 class ID_mini_cfg,ID_swe_utils cfg class ID_mini_root,ID_swe_types root class ID_NOTE_EXC note

%% UML 类图 · mini-swe-agent vs SWE-agent 契约层对照 %% 标本: mini 04d809c / SWE-agent 3ea751c %% mermaid classDiagram 原生语法，支持 <<annotation>> 与五种关系 classDiagram %% ============ mini-swe-agent 侧 ============ class mini_Agent { <<interface>> +config +run(task) dict +save(path) dict } class mini_Model { <<interface>> +config +query(messages) dict +format_message() dict +format_observation_messages() list +get_template_vars() dict +serialize() dict } class mini_Environment { <<interface>> +config +execute(action, cwd) dict +get_template_vars() dict +serialize() dict } class mini_DefaultAgent { +messages list +cost float +n_calls int +run(task) dict +step() list +query() dict +execute_actions(message) list +add_messages() list } class mini_LitellmModel { +abort_exceptions list +query(messages) dict +_parse_actions(response) list +_calculate_cost(response) dict } class mini_LocalEnvironment { +execute(action, cwd) dict -_check_finished(output) void } class mini_AgentConfig { <<config extends BaseModel>> +step_limit int +cost_limit float +wall_time_limit_seconds int +max_consecutive_format_errors int } class mini_InterruptAgentFlow { +messages tuple } class mini_Submitted { } class mini_FormatError { } mini_Agent <|.. mini_DefaultAgent : duck-typed impl mini_Model <|.. mini_LitellmModel : duck-typed impl mini_Environment <|.. mini_LocalEnvironment : duck-typed impl mini_DefaultAgent *-- mini_LitellmModel : owns mini_DefaultAgent *-- mini_LocalEnvironment : owns mini_DefaultAgent --> mini_AgentConfig : configures mini_DefaultAgent ..> mini_InterruptAgentFlow : catches mini_InterruptAgentFlow <|-- mini_Submitted mini_InterruptAgentFlow <|-- mini_FormatError %% ============ SWE-agent 侧 ============ class swe_AbstractAgent { <<semantic abstract>> +step() StepOutput +run() AgentRunResult +from_config() Self +add_hook() None } class swe_DefaultAgent { +messages list +trajectory Trajectory +setup() None +step() StepOutput +run(env, problem) AgentRunResult +forward(history) StepOutput +forward_with_handling(history) StepOutput +handle_action(step) StepOutput } class swe_AbstractModel { <<abstract>> +query(messages) dict +stats InstanceStats } class swe_LiteLLMModel { +query(messages) dict } class swe_SWEEnv { <<no abstraction>> +config EnvironmentConfig +communicate(input) dict +step(action) dict } class swe_StepOutput { <<config>> +done bool +exit_status str +submission str +thought str +action str +output str } class swe_AbstractParseFunction { <<abstract>> +__call__(model_response) list } class swe_ToolHandler { +config ToolConfig +get_action(step) str +should_block_action() bool } class swe_XmlThoughtActionParser { <<parser impl>> +__call__(model_response) list } class swe_EnvHook { <<semantic abstract>> +on_step_start() None +on_step_done() None } class swe_RunHook { <<semantic abstract>> +on_instance_start() None +on_instance_completed() None } swe_AbstractAgent <|-- swe_DefaultAgent swe_AbstractModel <|-- swe_LiteLLMModel swe_AbstractParseFunction <|-- swe_XmlThoughtActionParser swe_DefaultAgent --> swe_AbstractModel : uses swe_DefaultAgent --> swe_SWEEnv : uses swe_DefaultAgent --> swe_ToolHandler : uses swe_DefaultAgent --> swe_StepOutput : returns swe_DefaultAgent ..> swe_RunHook : notifies swe_SWEEnv ..> swe_EnvHook : notifies swe_ToolHandler --> swe_AbstractParseFunction : delegates

%% UML 顺序图 · mini-swe-agent 主循环（标本 commit 04d809c） %% ⚠️ sequenceDiagram 不支持 subgraph，故双项目拆为两个文件并列对照 %% 证据锚点全部来自 DefaultAgent.run / step / query / execute_actions sequenceDiagram autonumber participant U as 用户 CLI participant A as DefaultAgent participant H as MessageHistory participant M as LitellmModel participant E as LocalEnvironment participant T as 轨迹文件 U->>A: run task Note over A,H: run 清空历史 L91 A->>H: 追加 system 与 instance 两条种子消息 L92-95 loop while True L96 终止条件是末条消息 role 为 exit L122 A->>A: step 等于 execute_actions 包 query L126-128 alt 预算已超限 L132 或 L140 A-->>A: 抛 LimitsExceeded 或 TimeExceeded 携带 exit 消息 else 预算正常 A->>M: query messages L149 opt API 可重试失败 M->>M: retry 循环重试直到 abort_exceptions L82 end M-->>A: 返回 message 含 actions 与 cost A->>H: add_messages message L151 Note over A: 解析失败抛 FormatError actions_toolcall.py L41 end A->>E: execute action L156 Note over E: execute 内调用 _check_finished local.py L42 alt 首行为 COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT local.py L48 E-->>A: 抛 Submitted 携带 submission local.py L50 else 正常命令输出 E-->>A: 返回 output 与 returncode 与 exception_info end A->>H: add_messages observation L157 alt 捕获 FormatError 且未连续超限 L100-114 A->>H: 追加错误消息后继续循环 else 连续超限 L104 A->>H: 追加 exit 消息 RepeatedFormatError end A->>T: save 落盘 finally L120-121 每步都写 end A-->>U: 返回末条消息的 extra 即 exit_status 与 submission

%% UML 顺序图 · SWE-agent 主循环（标本 commit 3ea751c） %% ⚠️ sequenceDiagram 不支持 subgraph，故双项目拆为两个文件并列对照 %% 证据锚点全部来自 agents.py 的 run / step / forward_with_handling / forward / handle_action sequenceDiagram autonumber participant U as RunSingle participant A as DefaultAgent participant H as messages 历史 participant P as ToolHandler 与 parser participant M as LiteLLMModel participant E as SWEEnv participant K as RunHook 钩子 U->>A: run env 与 problem_statement L1265 A->>A: setup 装工具并写入模板消息 L1279 A->>K: on_run_start L1282 loop while not step_output.done L1284 A->>K: on_step_start L1248 A->>A: step L1235 转 forward_with_handling self.messages L1252 loop 内层重查询循环 n_format_fails 小于 max_requeries L1107 A->>M: forward 调用 query L1006 P->>P: parse_actions 生成 actions A->>P: ToolHandler 判定动作是否放行 L936 alt FormatError 或 BlockedAction 或 BashSyntax L1120-1141 Note over A: requery 不退出循环，次数累加 else 触发退出类异常 L1152-1210 A-->>A: attempt_autosubmission_after_error 兜底提交 patch else 返回正常 StepOutput A->>E: handle_action 执行 L936 E-->>A: observation 含 returncode end end A->>H: add_step_to_history step_output L1253 A->>A: save_trajectory L1286 每步落盘 A->>K: on_step_done L1262 end A->>K: on_run_done L1287 A-->>U: 返回 AgentRunResult 含 info 与 trajectory

%% UML 状态机图 · mini-swe-agent（标本 commit 04d809c） %% 迁移标签统一 [event]/action 三段式；终态出边仅指向 [*] %% 证据：agents/default.py run L96-124 / query L130-152 / execute_actions L154-157；exceptions.py %% 关键事实：所有中断型异常均由同一处 except InterruptAgentFlow(L115) 收敛成 role=exit 消息 stateDiagram-v2 [*] --> Initializing : [agent.run() L88]/messages 清空 Initializing --> Thinking : [写入种子消息 L92-95]/messages += system 与 instance Thinking --> Acting : [query() 成功 L149]/n_calls++ 且 cost 累加 Thinking --> Terminating : [check_limits() L132]/raise LimitsExceeded Thinking --> Terminating : [check_wall_time() L140]/raise TimeExceeded Thinking --> FormatError : [_parse_actions 失败 actions_toolcall L41]/raise FormatError Thinking --> Failed : [未捕获异常 L117]/追加 exit 消息后 raise 逃逸 FormatError --> Thinking : [单次失败 L113-114]/cost 补记后继续循环 FormatError --> Terminating : [连续超限 L104-112]/追加 RepeatedFormatError 的 exit 消息 Acting --> Observing : [execute_actions L156-157]/messages += observation Acting --> Terminating : [_check_finished local.py L48-50]/raise Submitted Observing --> Thinking : [末条消息 role 不是 exit L122]/进入下一轮 while True Observing --> Failed : [未捕获异常 L117]/raise 逃逸 Terminating --> Submitted : [exit_status 为 Submitted L122]/break 返回 submission Terminating --> LimitsExceeded : [exit_status 为 LimitsExceeded]/break 返回空 submission Terminating --> TimeExceeded : [exit_status 为 TimeExceeded]/break 返回空 submission Terminating --> RepeatedFormatError : [exit_status 为 RepeatedFormatError]/break 返回空 submission Submitted --> [*] : [done]/正常结束 LimitsExceeded --> [*] : [done]/预算耗尽 TimeExceeded --> [*] : [done]/超时 RepeatedFormatError --> [*] : [done]/格式连续失败 Failed --> [*] : [done]/异常向上传播 note right of Terminating 收敛点：except InterruptAgentFlow L115-116 统一把异常携带的消息追加进历史， 再由 L122 单一判据检出 role == exit end note note left of Observing 落盘时机：finally 子句每步调用 save L120-121 end note

%% UML 状态机图 · SWE-agent（标本 commit 3ea751c） %% 迁移标签统一 [event]/action 三段式；终态出边仅指向 [*] %% 证据：agents.py run L1265-1294 / step L1235 / forward_with_handling L1062-1218；types.py StepOutput %% 关键事实：终止靠结构化返回对象 StepOutput.done，而非消息流；九类异常先 autosubmit 兜底 stateDiagram-v2 [*] --> Initializing : [RunSingle.from_config]/构造 RunSingle Initializing --> Setup : [agent.run() L1279]/setup 装工具并写模板消息 Setup --> Thinking : [on_run_start L1282]/进入 while not done Thinking --> Acting : [forward L1006 查询成功]/StepOutput 含 action Thinking --> Requery : [forward_with_handling L1107]/n_format_fails++ 后重试 Requery --> Thinking : [_BlockedAction L1125 或 BashSyntax L1135]/history 换错误消息后重试 Requery --> Thinking : [RetryWithOutput L1142]/追加观测后重试 Requery --> Autosubmitting : [n_format_fails 达到 max_requeries L1211]/exit_format Acting --> Observing : [handle_action L936 执行成功]/observation 写入 StepOutput Acting --> Autosubmitting : [_ExitForfeit L1154]/exit_forfeit Acting --> Autosubmitting : [CommandTimeoutError L1168]/exit_command_timeout Observing --> Thinking : [step_output.done 为 False L1284]/add_step_to_history 后下一步 Observing --> Done : [submission 已产生 L1255]/done 置为 True Thinking --> Autosubmitting : [ContextWindowExceeded L1175]/exit_context Thinking --> Autosubmitting : [CostLimitExceeded L1182]/exit_cost Thinking --> Autosubmitting : [TotalExecutionTimeExceeded L1161]/exit_total_execution_time Thinking --> Failed : [TotalCostLimitExceeded L1180]/唯一直接 raise 不兜底 Autosubmitting --> Done : [attempt_autosubmission_after_error L823]/从环境提取 patch 兜底提交 Done --> [*] : [while 条件不再成立]/返回 AgentRunResult Failed --> [*] : [done]/异常向上传播 note right of Autosubmitting 兜底提交是 SWE-agent 独有机制： 出错时仍尝试从环境导出 patch 提交， mini-swe-agent 没有对应设计 end note note left of Observing 落盘时机：save_trajectory L1286 每步调用 同时 RunHook.on_step_done L1262 触发 end note

%% UML 组件图 · mini-swe-agent vs SWE-agent 运行时装配对照 %% 标本: mini 04d809c / SWE-agent 3ea751c %% ⚠️ mermaid 无原生 Component Diagram 语法，本图以 flowchart + subgraph 近似表达 %% 与包图的分工：包图画「源码怎么组织」，组件图画「运行时怎么装配」 flowchart TB subgraph RUN_MINI["「mini-swe-agent」运行时装配"] direction TB ID_m_cli["『CLI 构件』 typer app
run/mini.py main"] ID_m_cfg["「config 构件」
YAML + Jinja2 模板"] ID_m_fac["『装配构件』 工厂三件套
get_model / get_environment / get_agent"] ID_m_agent["『控制构件』 DefaultAgent"] ID_m_model["『模型构件』 LitellmModel"] ID_m_env["『环境构件』 LocalEnvironment"] ID_m_hist["『存储构件』 messages + 轨迹 JSON"] ID_m_cfg -.->|«configures»| ID_m_cli ID_m_cli -->|"读配置, 调工厂"| ID_m_fac ID_m_cfg -.->|«configures»| ID_m_fac ID_m_fac -->|"注入"| ID_m_agent ID_m_fac -->|"构造"| ID_m_model ID_m_fac -->|"构造"| ID_m_env ID_m_agent ==>|"持有并调用"| ID_m_model ID_m_agent ==>|"持有并调用"| ID_m_env ID_m_agent -->|"每步写"| ID_m_hist end subgraph RUN_SWE["「SWE-agent」运行时装配"] direction TB ID_s_cli["『CLI 构件』 RunSingle / RunBatch"] ID_s_cfg["「config 构件」
YAML + Jinja2 模板"] ID_s_fac["『装配构件』 get_agent_from_config
显式 if-elif 分支"] ID_s_agent["『控制构件』 DefaultAgent"] ID_s_model["『模型构件』 LiteLLMModel"] ID_s_tools["『工具构件』 ToolHandler
含 parser 家族"] ID_s_env["『环境构件』 SWEEnv
含 swerex 容器会话"] ID_s_hook["『扩展构件』 RunHook / EnvHook"] ID_s_out["『存储构件』 StepOutput + Trajectory"] ID_s_cfg -.->|«configures»| ID_s_cli ID_s_cli -->|"读配置"| ID_s_fac ID_s_cfg -.->|«configures»| ID_s_fac ID_s_fac -->|"注入"| ID_s_agent ID_s_agent ==>|"调用"| ID_s_model ID_s_agent ==>|"调用"| ID_s_tools ID_s_tools -->|"解析后交给"| ID_s_env ID_s_agent ==>|"调用"| ID_s_env ID_s_agent -.->|"通知"| ID_s_hook ID_s_env -.->|"通知"| ID_s_hook ID_s_agent -->|"每步写"| ID_s_out end ID_NOTE_DIFF["装配方式差异
mini: 字符串映射表 + importlib 动态导入（数据驱动, 加一行即可扩展）
SWE: if-elif 显式分支（ agents.py L242-254, 加一种要改代码）"] classDef cfg fill:#f5f7fb,stroke:#4f5dd5,stroke-width:1px classDef store fill:#eef1f8,stroke:#185fa5,stroke-width:1px classDef note fill:#fffbe6,stroke:#ba7517,stroke-width:1px,stroke-dasharray:4 3 class ID_m_cfg,ID_s_cfg cfg class ID_m_hist,ID_s_out store class ID_NOTE_DIFF note

%% UML 泳道活动图 · mini-swe-agent vs SWE-agent 错误处理与重试行为对照 %% 标本: mini 04d809c / SWE-agent 3ea751c %% ⚠️ mermaid 无原生 Activity Diagram / swimlane，以 flowchart 上下双泳道近似 %% 三色约定：主链(灰)正常流转 │ 蓝(requery) 可恢复重试 │ 橙(autosubmit) SWE 独有兜底 │ 红(terminate) 直接终止 flowchart LR classDef requery fill:#e1ecff,stroke:#1f6fd6,stroke-width:1.5px,color:#0b3f8f classDef autosub fill:#ffe4cc,stroke:#d97b1f,stroke-width:1.5px,color:#8a4b08 classDef term fill:#ffd9d9,stroke:#d6453d,stroke-width:1.5px,color:#8a1210 classDef main fill:#f5f7fa,stroke:#5b6572,stroke-width:1px subgraph mini_sw["「mini-swe-agent」错误处理 · default.py run L96-124"] direction TB m1["run(task) L88
注入两条种子消息"] m2{{"while True L96"}} m3["step = query + execute_actions L126"] mQ{{"query() L130 查预算"}} m4["model.query L149 + add_messages"] m5{{"parse 成功?"}} mE["env.execute L156
_check_finished 判提交"] mO["format_observation 追加 L157"] mN["role == exit ? L122"] mEnd(("返回 exit_status")) mT1["LimitsExceeded L133"]:::term mT2["TimeExceeded L141"]:::term mT3["RepeatedFormatError L109"]:::term mF["FormatError 累计 L100"]:::requery mX["无 autosubmit 兜底
连续错 = 直接结束"]:::autosub m1 --> m2 m2 -->|每次| m3 m3 --> mQ mQ -->|超限| mT1 & mT2 mQ -->|正常| m4 m4 --> m5 m5 -->|成功| mE m5 -->|失败| mF mE --> mO --> mN mN -->|exit| mEnd mN -->|非 exit| m2 mF -->|单次| m2 mF -->|超3次| mT3 mX -.-> mT3 mT1 & mT2 & mT3 --> mEnd end subgraph swe_sw["「SWE-agent」错误处理 · agents.py forward_with_handling L1062-1218"] direction LR s1["run(env,problem) L1265"] s2{{"while not done L1284"}} s3["step() L1235"] s4{{"n_format_fails < max_requeries L1107"}} s5["forward→query L1006"] s6{{"parse 结果?"}} s7["ToolHandler 放行 L936"] s8["env.execute L936"] sE["add_step_to_history L1253
save_trajectory L1286"] sEnd(("返回 AgentRunResult")) sR1["requery 分支 L1120-1140"]:::requery sA1["_ExitForfeit L1154"]:::autosub sA2["TotalExecTime L1161"]:::autosub sA3["CommandTimeout L1168
ContextWindow L1175"]:::autosub sA4["CostLimit L1182
Retry/Swerex/RuntimeError L1187-1207"]:::autosub sA0{{"异常 → 统一 autosubmit L1152"}}:::autosub sA5["exit_format 兜底 L1215"]:::autosub sAS["attempt_autosubmission_after_error
导 patch 提交 L823-868"]:::autosub sT["TotalCostLimit
唯一直接 raise L1180"]:::term s1 --> s2 s2 -->|每次| s3 s3 --> s4 s4 -->|正常| s5 s5 --> s6 s6 -->|Format/Blocked/BashSyntax L1120-1140| sR1 s6 -->|正常| s7 s7 --> s8 --> sE -->|done=False| s2 sE -->|done=True| sEnd sR1 -->|未超限| s4 sR1 -->|达到上限 L1211| sA5 s6 -->|退出类异常| sA0 s8 -->|CommandTimeout L1168| sA0 sA0 --> sA1 & sA2 & sA3 & sA4 sA0 --> sAS sA1 & sA2 & sA3 & sA4 --> sA5 sAS --> sEnd s6 -->|总成本超限| sT sT --> sEnd end

%% UML Hook 织入时序图 · SWE-agent 扩展点（标本 commit 3ea751c） %% 一帧 step 内密集织入多回调；13 个回调定义见 hooks/abstract.py %% 教学落点：新增能力只需加一个 AbstractAgentHook 子类经 add_hook 注入，不改主循环 sequenceDiagram autonumber participant R as RunSingle participant A as DefaultAgent
(agents.py) participant H as CombinedAgentHook
(hooks/abstract.py) participant M as AbstractModel participant E as SWEEnv Note over R,A: === 装配 === A->>H: add_hook(hook) 注册自定义钩子 L519 A->>A: on_init L287 构造期钩子(慎用) Note over A,E: === setup 阶段(一次) === A->>H: on_tools_installation_started L592 A->>H: on_setup_attempt L594 A->>H: on_setup_done L606 Note over A,H: === run 外层 === A->>H: on_run_start L1282 loop while not step_output.done L1284 A->>H: on_step_start L1248 rect rgb(235, 245, 255) Note over A,M: requery 内层循环 while n_format_fails < max_requeries L1107 A->>H: on_query_message_added L558 (每加一条消息) A->>H: on_model_query L1029 (带完整 history 查询) A->>M: query(history) M-->>A: model response A->>H: on_actions_generated L1051 (动作已生成未执行) end A->>H: on_action_started L959 A->>E: handle_action→execute L936 E-->>A: observation A->>H: on_action_executed L992 A->>A: add_step_to_history + save_trajectory L1253/1286 A->>H: on_step_done L1262 end A->>H: on_run_done L1287 (整个 run 结束) R-->>A: 返回 AgentRunResult