OpenHands SDK：三层语义与五个生产旋钮

OpenHands 最有教学价值的部分，是它把三年踩坑史直接固化成了一套可安装的 SDK (Software Development Kit, 软件开发工具包)。

为什么一个框架值得单独半讲？因为 L14 的历史线 (p.4-11) 几乎就是编码 agent (coding agent) 的进化史，而 SDK 的每一个设计决定 (p.13-20) 都能在历史线上找到对应的伤疤。

一、三年：从给建议到管部署

第一幕是代码补全 (code completion) 时代，到 2023 年为止。Copilot 与早期 Cursor 的角色是给建议，编辑、执行、检查全由人主导。

这个时代的尺子是 HumanEval，单函数加单元测试。L14 p.4-11 举的示例函数是 has_close_elements：模型补全一个函数，测试通过即得分。

2023-10 的 SWE-bench 换了考题：给真实 GitHub issue 与仓库快照，要求产出补丁并通过仓库自己的测试。早期结果很差 (Jimenez et al. 图 1)，说明会写函数离会修仓库隔着一整层系统能力。

第二幕是 2024 年的 agent 诞生期。2024-03-12，Cognition 的 Devin 以「第一个 AI 软件工程师」的演示引爆话题。

整整两周后的 2024-03-26，开源项目 OpenDevin (OpenHands 前身) 跟进，前端 + agent + Docker 沙箱 (sandbox) 三件套齐上。

随后 2024-04 的 SWE-agent 与 2024-05 的 OpenDevin CodeAct 1.0 各自卡位：前者做文件搜索、代码编辑、修复验证的界面设计，后者打通代码执行、终端命令与反馈。两者共同提出一个命题，即 agent - 计算机界面 (agent–computer interface, ACI) 本身是研究课题，正如人机交互之于图形界面。

第三幕收敛于两点。一是 2025 年的基准进展同时来自更好的模型 (推理、代码编辑、工具使用) 与更好的 agent 系统 (工具、测试环境、上下文、恢复)，归因见 SDK 报告 §5。

二是 2026 年的部署提出一串新需求：更长运行、中断、并行任务、进度可见与结果检查、可重复工作流、受控访问 (scoped access)、验证 (Neubig 富士通演讲，2026-09)。

这串需求值得逐字读一遍：考题不再是能不能解出 issue，而是能不能像同事一样被安排工作。SDK 的设计就是对这份清单的逐条作答。

支撑这条进化线的平台本体，记录在 OpenHands 平台论文 (ICLR 2025)：写代码、命令行、浏览网页统一成一个行动空间，沙箱内安全执行，支持多 agent 协同。同一平台在 SWE-Bench Lite、WebArena、GAIA 等 15 项基准上验证，188+ 贡献者，MIT 协议。

SDK 是这个平台把自身经验产品化的产物。

二、Batteries included, but flexible

SDK 的设计立场写在 p.13 一句话里：开箱即用 (batteries included)，但保持灵活 (flexible)。具体哪些配好、哪些可换，见下面的对照。

最少代码长这样 (L14 p.14)：

llm = LLM(model=..., api_key=...)  # 讲义示例默认 gpt-5.5
agent = Agent(llm, tools=[TerminalTool, FileEditorTool, TaskTrackerTool])

p.15 给出三层语义：Workspace (工作区) 管文件与执行，Conversation (会话) 管任务、动作与观察的事件流，Run (运行) 是动作 - 观察循环 (action–observation loop) 本身。用法即组装：

conversation = Conversation(agent, workspace)
conversation.send_message("3 project facts in FACTS.txt")  # 任务：写入 3 条项目事实
conversation.run()

三、五个生产旋钮

历史线第三幕的部署需求，落到 p.16-20 就是五个旋钮。

自定义工具。 三段式模式：Action 是类型化输入，Executor 是真正去跑搜索的实现，Observation 是模型可读的结果 (L14 p.16)。工具从提示词里的一段散文，变成一组带类型与描述的类定义。以讲义的 Grep 为例：

class GrepAction(Action):
    pattern: str = Field(..., description="要搜索的模式")
    path: str = Field(..., description="搜索范围")

class GrepObservation(Observation):
    matches: list  # 命中列表，回给模型

会话持久化 (persistence)。 指定 persistence_dir 与 conversation_id，事件与会话状态落盘。同一 ID、同一存储即可恢复 (L14 p.17)。

上下文管理。 长任务会撑爆上下文。LLMSummarizingCondenser 用一个 LLM 副本 (usage_id=“condenser”) 把较旧事件折成摘要，max_size=10、keep_first=2，保住最初的原始指令与近期工作 (L14 p.18)。

摘要有细节损失的风险。兜底办法是让 agent 把重要结论写进文件、用测试验证，用外部证据补内部记忆，别赌摘要一字不漏。

远程执行。 DockerWorkspace (server_image, platform) 在容器里跑 Agent Server，get_default_agent (cli_mode=True)。开发者手里的 Conversation API 不变，任务与事件都在远端 (L14 p.19)。

本机只当遥控器。执行环境锁进镜像，换一台机器也能复现同一个沙箱。

动作确认 (confirmation policy)。 set_confirmation_policy (AlwaysConfirm ()) 让每个动作执行前暂停，待定动作 (pending action) 交人决策，拒绝后 agent 修订计划 (L14 p.20)：

五个旋钮对上部署清单：

• 可重复工作流：靠持久化。
• 更长运行：靠摘要压缩。
• 受控访问：靠远程沙箱加确认策略。
• 进度可见与结果检查：靠 Conversation 的事件流 (p.15)。
• 自定义工具：决定 agent 的能力上限。

与本讲的连接

资料卡各就各位：m7-openhands-paper 是平台原典，m7-oh-sdk-report 是 SDK 报告，m7-swe-bench 是换考题的原典。

行动项：装上 SDK 跑通 “3 project facts in FACTS.txt” 这个讲义示例，再按顺序拧旋钮，先加 AlwaysConfirm 看暂停点，再配 Condenser 看摘要边界，最后把工作区挪进 Docker。

跑完回看 2024-03 那场 Devin 演示，你会分清哪些当年只是演示、哪些如今已经长成 API。三年下来的答案，还是 p.13 那句 Batteries included, but flexible。