Day 01 / 共 20 天 · 第 1 周 核心概念
项目全景与 V1 架构
第一天先建立全局认知：OpenHands 是什么、和聊天机器人的本质区别、V1 拆包后的架构、本仓库的定位。不写一行难代码，只建直觉。这条"能行动+能观察"的闭环会贯穿全部 20 天——今天先把地图刻进脑子。
📍 第 1 周 核心概念 · 你在这里（这条链每天开头都会点亮你所在的格子）
Day1 全景→
Day2 Action/Obs→
Day3 事件流→
Day4 运行→
Day5 完整旅程
L01
它到底是什么
🤔 痛点：让 AI 帮你写代码，为什么"给段代码"还不够？
你让 ChatGPT 写个功能，它给你一段代码——但你还得自己复制、自己跑、报错了再回来贴给它、它再改……你成了 AI 的"手脚"，来回搬运几十趟才能真正把活干完。要是它能自己跑、自己看报错、自己改，多好？
💡 本质：把"只会说"的 AI 装上"手和眼"
OpenHands 的本质，就是给大模型接上一双手（能敲终端、改文件）和一双眼（能看到命令输出），让它自己跑"做→看结果→再做"的循环，直到任务完成。OpenHands 就像生活中你雇的一位"AI 实习生程序员"：你只说需求，TA 自己动手、边干边汇报——这套"实习生"类比会贯穿今天全篇。这就是 Agent（智能体）和聊天机器人的分水岭。
OpenHands（原名 OpenDevin）是一个开源的 自主 AI 软件工程师平台，口号是 "Code Less, Make More"。你给它一个自然语言任务，它能像真人程序员一样自主地把任务完成。
用最白的话说
想象你雇了个远程程序员：你在聊天框里说"帮我把这个项目的登录 bug 修了"，然后 TA 自己去看代码、在终端跑命令、改文件、跑测试、查文档，边做边跟你汇报进度，最后告诉你"修好了，是这里的空指针"。OpenHands 就是把这个"远程程序员"换成了 AI。它不只是聊天——它真的能动手操作一台（沙箱里的）电脑。
为什么它很重要：普通的 AI 助手只能"告诉你怎么做"，OpenHands 能"替你做"。它在 SWE-bench（衡量 AI 解决真实 GitHub issue 能力的权威榜单）上一直是开源方案的领先者。学它，你能理解"AI Agent 如何真正地在真实环境里干活"——这是当下最前沿的方向之一。
L02
和 ChatGPT 那种聊天机器人有啥本质不同
| 对比 | 普通聊天 AI | OpenHands |
|---|---|---|
| 能做什么 | 生成文字/代码给你看 | 真的去执行：跑命令、改文件 |
| 交互方式 | 一问一答 | 自主多步循环，直到任务完成 |
| 能否看到结果 | 看不到，只能靠你反馈 | 能看到命令输出，自我纠错 |
| 运行环境 | 无 | 隔离沙箱（终端+文件+浏览器） |
核心差异一句话
聊天 AI 是"嘴"——只会说；OpenHands 是"嘴 + 手 + 眼"——会说、会操作、还能看到操作结果再调整。这个"能行动 + 能观察反馈"的闭环，就是"Agent（智能体）"区别于"聊天机器人"的本质。
L03
一个真实任务示例（脑补一遍流程）
你说："给这个 Python 项目加一个 /health 健康检查接口。" OpenHands 内部大致这样跑：
# 第1步 Agent 想：先看看项目结构 → 产出一个"跑命令"动作
$ ls && cat app.py # ← Action：执行命令
# 沙箱返回文件内容 # ← Observation：结果回给 Agent
# 第2步 Agent 想：这是个 Flask 应用，我在 app.py 加个路由 → 产出"编辑文件"动作
edit app.py: 加上 @app.route('/health')... # ← Action：改文件
# 沙箱返回"编辑成功" # ← Observation
# 第3步 Agent 想：验证一下 → 产出"跑命令"动作
$ python -m pytest # ← Action
# 测试通过 # ← Observation
# 第4步 Agent 想：完成了 → 产出"finish"动作，告诉你搞定了
把上面的过程做成一张单步走查表（像调试器单步执行一样跟一遍）：
| 步骤 | 实习生（Agent）在想 | 产出的 Action | 拿到的 Observation |
|---|---|---|---|
| 1 | 先摸清项目结构 | ls && cat app.py | 文件内容（发现是 Flask） |
| 2 | 在 app.py 加路由 | 编辑 app.py | "编辑成功" + 改动 diff |
| 3 | 验证没改坏 | python -m pytest | exit_code=0，测试通过 |
| 4 | 活干完了，交差 | finish（附总结） | ——（任务结束） |
📝 举个例子：一步"跑命令"在系统里长什么样
Agent 决定 →
沙箱执行完 →
Agent 读到"failed" → 产出下一个
Action: ExecuteBash(command="pytest")（想做的事）沙箱执行完 →
Observation: 输出 "1 failed"、exit_code=1（真实结果）Agent 读到"failed" → 产出下一个
Action 去改 bug。输入是意图、输出是事实，中间隔着一个真实沙箱。读法：每一步都是"Agent 产出一个动作（Action）→ 沙箱执行 → 返回结果（Observation）→ Agent 看结果决定下一步"。这个循环就是 OpenHands 的心脏，明天（Day 02）我们正式拆解 Action 和 Observation。
注意"自我纠错"：如果第 3 步测试失败，Agent 会看到失败的 Observation，然后产出新的 Action 去改 bug、再测——不用你插手。这种"看到结果再调整"的能力，正是它能完成复杂任务的关键。
L04
V1 拆包架构（重要，先说清楚）
🤔 对话体 Q&A：拆包是怎么回事？
👶 小白：我打开本仓库想找"Agent 思考循环"的代码，怎么翻遍了也找不到？
👨🏫 老师：因为 V1 重构把"大脑"拆出去了——本仓只是"公司前台+调度室"，大脑在外部包
👶 小白：那我学本仓还有意义吗？
👨🏫 老师：非常有！"怎么管理会话、沙箱、事件流"这套编排层工程恰恰是生产系统最值钱的部分，而且概念（Action/Observation）在本仓前端类型里有完整镜像。
👨🏫 老师：因为 V1 重构把"大脑"拆出去了——本仓只是"公司前台+调度室"，大脑在外部包
openhands-sdk 里。👶 小白：那我学本仓还有意义吗？
👨🏫 老师：非常有！"怎么管理会话、沙箱、事件流"这套编排层工程恰恰是生产系统最值钱的部分，而且概念（Action/Observation）在本仓前端类型里有完整镜像。
OpenHands 发展到 V1 版本时做了一次重要重构：把"Agent 的大脑逻辑"从主仓库拆成了几个独立的 Python 包。看 pyproject.toml 就能证实：
# pyproject.toml —— 本仓（openhands-ai）依赖这几个外部包
dependencies = [
"openhands-agent-server==1.34.0", # Agent 运行服务
"openhands-sdk==1.34.0", # Agent 核心 SDK（大脑）
"openhands-tools==1.34.0", # 工具集（bash/文件/浏览）
# ...
]openhands-sdk
Agent 大脑感知-决策循环、LLM 抽象、Action/Observation 定义。
openhands-tools
工具集bash 执行、文件编辑、浏览器等工具的实现。
openhands-agent-server
Agent 服务把 Agent 跑成一个可调用的服务。
openhands-ai（本仓）
编排/服务层管理会话、沙箱、事件流、Web 服务、企业版。
为什么要拆？对我们学习有什么影响？
拆包是为了让"Agent 核心"能被别的项目复用（比如你想只用 SDK 自己搭 Agent），也让各部分独立发版。对我们的影响：本仓库里看不到 Agent 循环的源码（它在
openhands-sdk 那个包里）。所以这份教程会：第 2 周深读本仓真实存在的编排层代码（会话/事件/沙箱）；第 3 周讲 SDK 的设计与概念（结合公开设计和本仓的调用方式）。我们全程会标注"这段在本仓 / 这段在外部包"，绝不含糊。L05
本仓库目录导览
OpenHands/
├── openhands/
│ ├── app_server/ # ★ 本仓核心：会话/事件/沙箱编排层（第2周主战场）
│ │ ├── app_conversation/ # 会话生命周期
│ │ ├── event/ # 事件系统
│ │ ├── sandbox/ # 沙箱管理
│ │ └── config_api/ # 配置接口
│ ├── server/ # FastAPI Web 服务入口（app.py/listen.py）
│ ├── db/ # 数据库
│ └── analytics/ # 埋点
├── frontend/ # React 前端（第4周看事件如何渲染成 UI）
│ └── src/types/v1/core/events/ # ★ V1 事件类型定义（第1周读它理解概念）
├── enterprise/ # 企业版：多租户/鉴权/集成（第4周）
├── config.template.toml # 配置模板（第1周 Day04）
└── pyproject.toml # 依赖（能看到拆出去的外部包）读法：记住两个重点目录——
openhands/app_server/（后端编排层，第2周逐行读）和 frontend/src/types/v1/core/events/（前端里的事件类型定义，第1周用它来理解 Action/Observation 长什么样）。Agent 大脑不在这，在外部包。L06
四层架构（心智模型）
把整个系统从上到下分四层理解：
四层心智模型：前端下任务→编排层(本仓)驱动Agent大脑→大脑产Action→沙箱执行得Observation→存下来推回前端。数据的"通用货币"是 Action/Observation。
- L4 前端界面（frontend/）：你下任务、实时看 Agent 每一步在干嘛。
- L2 服务编排层（openhands/app_server/，本仓核心）：管理"一次会话"的生命周期——建沙箱、驱动 Agent、把事件存下来并推给前端。
- L3 Agent 大脑（openhands-sdk，外部包）：决定"下一步做什么"，产出 Action。
- L1 事件对 Action/Observation：贯穿所有层的核心数据——Agent 的动作和执行结果。
数据怎么流：你在前端(L4)下任务 → 编排层(L2)创建会话和沙箱 → 驱动 Agent 大脑(L3) → 大脑产出 Action(L1) → 编排层把 Action 送进沙箱执行 → 得到 Observation(L1) → 存下来并推回前端(L4)显示，同时喂回大脑决定下一步。这条链路就是这 20 天的主线，今天先记住"分四层、核心是 Action/Observation 循环"即可。
L07
为什么反复强调"安全沙箱"
OpenHands 让 AI 真的执行命令——这既是它的威力，也是最大风险。想象 AI 理解错了任务，执行了 rm -rf /，或者把你的密钥上传到某处。所以 OpenHands 的所有执行都在隔离沙箱（通常是 Docker 容器）里进行。
沙箱 = 给 AI 的"隔离实验室"
沙箱是一个和你真实系统隔离的环境（独立容器）：AI 在里面能自由敲命令、改文件，但碰不到你宿主机的真实文件和系统。就算它在里面把环境搞崩了，删掉容器重建一个就行，你的电脑毫发无伤。这就是为什么第 2 周有一整天（Day 09）专门讲沙箱管理——对"能自主行动的 AI"来说，隔离就是安全的地基。
⚠️ 常见误解：小白常误以为"OpenHands 直接在我电脑上跑命令，太危险了"。其实恰恰相反——它的一切命令默认都在隔离的 Docker 容器里执行，实习生只能在"实验室"里折腾，碰不到你家的东西。
除了沙箱隔离，OpenHands 还有 confirmation mode（人工确认模式）：危险动作执行前暂停、等你点头（Day 17 细讲）。沙箱隔离 + 人工确认 = 双重安全带。
一句话复述今天所学
OpenHands = 一位关在"隔离实验室"里的 AI 实习生程序员：你派活（前端），调度室（本仓 app_server）给 TA 开工位（沙箱）、记工作日志（事件流），TA 的大脑（openhands-sdk）不断"想一步→动手（Action）→看结果（Observation）→再想"，直到交差。
L08
今日小结 + 动手
🧠 今天你应该能回答
- OpenHands 是什么？和聊天 AI 的本质区别？（能行动+能观察反馈的闭环）
- 一个任务大致怎么被自主完成？（Action→执行→Observation→再决策 的循环）
- V1 拆成了哪几个包？本仓库的定位是什么？（编排/服务层）
- 本仓两个重点目录是？（app_server / frontend 的 events 类型）
- 为什么必须用沙箱？
✋ 动手：确认架构现状
# 1. 看依赖，确认拆出去的外部包
grep -A6 'dependencies = \[' pyproject.toml | head
# 2. 看本仓核心目录
ls openhands/app_server/
# 3. 看前端里的 V1 事件类型（第1周会精读）
ls frontend/src/types/v1/core/events/明天预告 · Day 02：正式拆解 OpenHands 的两个核心概念——Action（Agent 想做的事） 和 Observation（执行后的结果）。我们对着
frontend/src/types/v1/core/events/ 里的真实类型定义，看它们长什么样、有哪些种类。