OpenHands 源码学习
20 天 · 每天 30 分钟 · 逐层读懂开源的"自主 AI 软件工程师"——它能自己读代码、敲命令、改文件、跑测试，替你完成软件工程任务
开篇 · 这是个什么项目
OpenHands（原名 OpenDevin）是一个开源的 自主 AI 软件工程师平台。你给它一个任务（"帮我修这个 bug""给这个项目加个功能"），它就像一个真人程序员那样：读代码、在终端敲命令、编辑文件、跑测试、浏览网页查资料，一步步把任务做完。
🎯 一句话：OpenHands = 大模型的"大脑" + 一个安全的"沙箱电脑"（终端/文件/浏览器）。大脑决定"下一步干什么"（Action），沙箱执行后把结果（Observation）返回给大脑，如此循环，直到任务完成。
会用终端
在隔离沙箱里执行 shell 命令，像人一样操作。
会改代码
读取、创建、编辑文件，完成真实的代码修改。
会上网
浏览网页、查文档、看报错解决方案。
会自我纠错
看命令/测试结果，判断对错，调整下一步。
openhands-sdk / openhands-agent-server / openhands-tools）。本仓库主要是"编排/服务层"（openhands/app_server：管理会话、沙箱、事件流）+ 前端 + 企业版。所以这份教程会：① 从本仓真实存在的 app_server 和前端类型逐行讲编排/事件/沙箱；② 对已拆到外部包的 Agent SDK，讲清它的设计与概念。全程标注代码来源，诚实说明哪些在本仓、哪些在外部包。架构全景（动起来看）
下图那颗发光小球是"你的一个任务从前端落到底层沙箱执行"的过程。从上到下：用户界面 → 服务编排层（本仓核心）→ Agent 大脑（外部 SDK）→ 沙箱执行环境。
OpenHands 的核心心智模型是一个简单而强大的循环——Agent 感知-决策-行动循环：
（已发生什么）→ 2. 决策问大模型
下一步做什么→ 3. Action产出一个动作
（跑命令/改文件…）→ 4. 执行沙箱运行
得到 Observation↺ 回到 1直到完成
rm -rf？）。OpenHands 把所有执行放进隔离的沙箱（通常是 Docker 容器）——AI 在里面折腾，炸了也不影响你的真实系统。安全是这个项目的头等大事。怎么用这份教程
每天 30 分钟
一天一个独立页面，跟着"今日小结 + 动手"收尾。
零基础友好
不假设你懂 Agent/Docker/FastAPI，术语首次出现都有大白话解释。
精确到行号
关键代码标 文件:行号，可在真源码里跳转对照。
项目全景与 V1 架构
OpenHands 是什么、能干什么、V1 拆包后的架构、本仓的定位。
核心概念：Action / Observation
Agent 的动作与执行结果，一切都是事件对。
事件流 Event Stream
会话 = Action/Observation 交替成的一条事件流。
运行一个 OpenHands
Docker/CLI 启动、配置 config.toml、接大模型。
一次任务的完整旅程
把前 4 天串起来：从下任务到完成的全过程。
app_server 架构总览
顶层模块地图：conversation/event/sandbox/config。
会话生命周期
app_conversation：会话怎么创建、启动、管理。
Event 系统源码
事件怎么建模、存储、通过 SSE/WS 推给前端。
Sandbox 沙箱管理
执行环境怎么供给、隔离、回收。
server 服务装配
FastAPI app、路由、中间件怎么把一切连起来。
Agent SDK 概念
openhands-sdk：Agent 抽象、感知-决策循环。
工具体系 openhands-tools
bash / 文件编辑 / 浏览器工具怎么定义和调用。
Runtime 运行时
Action 怎么被送进沙箱执行、Observation 怎么回来。
LLM 抽象与提示词
多模型接入、系统提示、函数调用怎么组织。
CodeAct 范式精读
OpenHands 的招牌：用"写代码"作为统一动作空间。
前端如何实时展示 Agent
WebSocket/事件订阅、把事件流渲染成 UI。
安全与权限
沙箱隔离、confirmation mode 人工确认、危险动作拦截。
微代理 microagents
用知识片段/触发词定制 Agent 行为。
enterprise 企业版扩展
多租户、鉴权、集成，本仓 enterprise 目录一览。
构建测试与收官串讲
全项目回顾、设计哲学、学习路线。
✅ 全部 20 天已就绪。建议按顺序学。准备好了就从 Day 01 · 项目全景 开始。