Day 20 / 共 20 天 · 第 4 周（结业）
构建、测试与收官串讲
昨天（Day 19）看完企业版这层"最外圈"，今天是全程终点：把开发、测试、debug 收口，再把 20 天知识连成一张地图、提炼设计哲学做总回顾。本地怎么跑起来开发、测试怎么组织、debug 技巧、从零用 OpenHands 完成任务的清单，一次讲透，为整个系列画上句号。
📍 第 4 周 前端与生态 · 全程终点，你在这里 🏁
Day16 前端展示→Day17 安全权限→Day18 微代理Skills→Day19 企业版→Day20 构建收官 🏁
L01
本地开发环境
make build # 构建前后端
make run # 同时跑前端(3001) + 后端(3000)
make start-backend # 只后端 = uvicorn openhands.app_server.app:app
make start-frontend # 只前端
# 用 OpenHands 开发 OpenHands 自己（最快的本地调试）：
export INSTALL_DOCKER=0
export RUNTIME=local # 本地运行时，不用 Docker（Day 13）
make build && make run最省事的开发姿势
RUNTIME=local（Day 13）让 Agent 直接在本地进程执行，省去 Docker 的启动开销——改代码、重启、看效果的循环最快。生产/给用户则用 RUNTIME=docker（隔离安全）。开发求快用 local，部署求稳用 docker——同一套代码，环境变量切换。💡 本质：构建/测试 = 产品出厂前的"质检流水线"把整个开发流程想成一条工厂流水线：
make build 是组装（打包前后端），make test 是质检工位（跑单测抽检），lint 是外观检查（代码风格），最后 poetry build 打包装箱出厂。RUNTIME=local 像"试制车间"（快速改料验证），RUNTIME=docker 像"正式生产线"（标准、隔离、可复现）。今天就是走一遍这条流水线，看每个工位在干嘛。💡 简化版 → 真实版：为什么构建不是一行
poetry build？如果让你写构建脚本，你大概只写一句 poetry build 打包完事。但真实 Makefile 的 build 目标先跑一串 check-dependencies（check-python/check-docker/check-tmux/check-poetry），再 install-python-dependencies + install-frontend-dependencies + install-pre-commit-hooks。多出来的每一步都在防一种"新人踩坑"：环境没装 → 提前报错而非跑一半崩；依赖没同步 → 先装齐。朴素脚本只管"能打包"，工程级脚本还管"换台机器、换个新人也能一键跑通"。L02
测试怎么组织
tests/unit/app_server/ # app_server 的单测（57 个文件，第2周内容）
tests/unit/ # 其他单测
enterprise/tests/unit/ # 企业版单测
# 跑测试（Python）
poetry run pytest tests/unit/app_server/ # 只跑 app_server 单测
poetry run pytest -k "conversation" # 跑名字含 conversation 的怎么用测试学源码？
tests/unit/app_server/ 有 57 个测试文件——它们是可运行的用法示例。想搞懂"会话怎么启动""事件怎么存"，去读对应的测试：测试里会构造输入、调用函数、断言输出，等于手把手演示这个模块怎么用。读测试常比读实现更快理解一个模块的行为契约——这和 eino 教程建议读 *_test.go 是同一招。L03
Debug 技巧
- 看事件流：一切皆事件（Day 03）——Agent 行为诡异时，去看会话的事件序列（前端展示或 app_server 存的 JSON 文件），一眼看出是哪步 Action 出了问题、Observation 返回了什么。
- 分清是哪层：问题在管家（app_server）还是工人（agent-server）？看日志来源。启动失败多半是 app_server（拉沙箱/clone 失败）；执行诡异多半是 agent-server/LLM。
- 用 local runtime 调试：
RUNTIME=local时能直接在本机断点调试 Agent 执行，不用进容器。 - 看启动状态机：卡在哪个状态（WAITING_FOR_SANDBOX / PREPARING_REPOSITORY，Day 07）就知道是哪一步慢/失败。
最强 debug 武器：事件流可回放。因为整个任务是一串持久化的结构化事件，出问题时你能完整重现 AI 当时"看到什么、想了什么、做了什么"。这是"一切皆事件"设计送的最大礼物——可观测性拉满。
L04
从零用 OpenHands 完成一个任务
- 启动：Docker 方式跑起来（Day 04），挂载你的项目目录
- 配模型：Settings 里填 LLM 和 API Key（Day 04/14）
- （可选）写 skills：项目里加
.openhands/skills/教 Agent 项目规范（Day 18） - （可选）加
.openhands/setup.sh：自动装依赖（Day 07/18） - 开安全：生产环境务必用沙箱 + 开
confirmation_mode（Day 17） - 下任务：用自然语言描述你要做什么
- 观察：实时看 Action/Observation，必要时暂停/确认/纠正（Day 16/17）
- 设上限：配
max_iterations/max_budget_per_task防失控（Day 04） - 验收：让它跑测试证明改动正确，看 diff 确认改动范围
你现在能驾驭它了
这份清单每一项都对应你学过的某一天。从"读懂源码"到"会用、会配、会调、敢放心让它干活"，你都具备了。
L05
常见坑速查
- 找不到 Agent 循环代码：它在外部包
openhands-sdk，不在本仓（Day 01/11）。本仓是编排层。 - 以为 app_server 推实时事件：不是，实时靠前端直连沙箱 WebSocket；app_server 只存不推（Day 08/16）。
- 无沙箱模式的风险：npm 直跑无隔离，AI 有宿主机权限——只在信任场景用（Day 04/17）。
- 忘了设预算：自主 Agent 会持续烧 token，务必配
max_budget_per_task（Day 04/14）。 - server 目录里改代码没生效：那是转发壳，真代码在 app_server（Day 06/10）。
- 密钥泄漏担忧：用 secrets 机制按需下发，别硬编码进镜像/配置（Day 09/17）。
L06
20 天知识地图
第1周 核心概念
- D1 全景/V1架构
- D2 Action/Observation
- D3 事件流
- D4 运行与配置
- D5 完整旅程
第2周 编排层
- D6 架构+依赖注入
- D7 会话生命周期
- D8 事件系统
- D9 沙箱管理
- D10 服务装配
第3周 Agent大脑
- D11 SDK 概念
- D12 工具体系
- D13 Runtime
- D14 LLM 抽象
- D15 CodeAct
第4周 前端/安全/生态
- D16 前端展示
- D17 安全权限
- D18 微代理/Skills
- D19 企业版
- D20 收官
图注：四周不是四个孤立主题，而是同一条链的四段——底层始终是 Action/Observation 事件这枚"通用货币"。
一条主线：Action/Observation 事件（第1周）→ app_server 编排会话/事件/沙箱（第2周）→ Agent 大脑在沙箱里跑 CodeAct 循环（第3周）→ 前端展示、安全兜底、生态扩展（第4周）。从"一个动作"到"一个能自主完成软件工程任务、可安全部署、可企业化的完整系统"，你把整条链路走通了。
L07
贯穿始终的设计哲学
① 一切皆事件：把 Agent 的每次交互建模成结构化 Action/Observation，换来可观测、可回放、可审计、可分享、易渲染。
② 安全纵深防御：沙箱隔离 + 风险评估 + 人工确认 + 密钥/用户隔离 + 熔断脱敏，多层叠加，敢把执行权交给 AI。
③ 面向接口 + 依赖注入：Runtime/Sandbox/Service 都是接口，改环境变量换实现，一套代码适配 local/docker/remote、OSS/SaaS。
④ 职责分离（双进程）：管家（编排）/ 工人（执行）/ 前端（展示）各司其职，可独立演进、独立部署、独立扩展。
⑤ CodeAct（以代码为动作）：用 LLM 最擅长的"写代码"作为通用动作空间，胜过一堆固定工具。
⑥ 成本经济学：token 全程统计、预算硬熔断、按需加载 skills、Agent 自主切模型——自主 AI 必须精算花费。
这些哲学不只属于 OpenHands。它们和你在 eino 教程里学的"统一抽象、接口与实现分离、流式一等公民、成本经济学"高度重合——因为它们是所有优秀 AI Agent 系统的通用规律。学两个框架，你就能看穿第三个。
L08
🎓 结业 + 下一步
恭喜你完成 OpenHands 20 天源码学习！
你从零基础，走到了理解"一个自主 AI 软件工程师如何构建、运行、保障安全、企业化"的水平。你读懂了它的事件模型、编排层源码、Agent 大脑设计、前端展示、安全体系——并能诚实区分"哪些在本仓、哪些在外部 SDK"。这种面对真实、演进中的大型项目仍能理清脉络的能力，比记住某个 API 珍贵得多。
🚀 下一步建议
- 动手用：照 L04 清单，用 OpenHands 帮你的项目干一件真实的活。
- 读外部 SDK：想深入 Agent 循环，去看
OpenHands/software-agent-sdk仓库（openhands-sdk 的源头）。 - 读测试：
tests/unit/app_server/是活的文档。 - 横向对比：本系列还有 CrewAI、AutoGPT、LangGraph——它们和 OpenHands 都是 Agent 框架，对比设计异同（事件模型？CodeAct vs 固定工具？）会让你理解得更透。