阅读 OpenHands 开源 coding agent 实现的学习笔记。
这个仓库放的是笔记。代码本身通过 git submodule 指向 OpenHands 官方仓库，不复制、不修改， 所有权和版权归原作者（MIT）。
| 子模块 | 内容 | commit 数 |
|---|---|---|
upstream/software-agent-sdk |
agent 循环、事件流、上下文管理、工具层、agent-server | 2408 |
upstream/extensions |
skills、automations、MCP 集成 | 359 |
upstream/automation |
调度、webhook、运行历史与派发 | 254 |
upstream/OpenHands-CLI |
基于 SDK 构建的命令行前端 | 354 |
选这四个的理由：它们覆盖了从单次 agent 决策到长期自动化调度的完整链路，且全部是 MIT。
OpenHands 组织下星数最高的 OpenHands 仓库（89k★）现在只是 React 前端控制台，
agent 架构已全部迁出到 software-agent-sdk。
精读顺序即阅读顺序，每篇自带"可迁移结论"小节。
先读这个：notes/00-principles-index.md 把 22 篇里反复出现的设计原则归并成 43 条索引，每条标注它出现在哪几节。
| 笔记 | 主题 |
|---|---|
| 01-sdk-architecture | 整体架构拆解 + 精读路线 |
| 02-event-model | 事件模型：不可变账本、事件树、并行工具调用的还原 |
| 03-view-and-properties | 上下文视图：可操作位置与四条结构规则 |
| 04-agent-step | 单步决策：四道门、四种错误恢复、并行执行与资源锁 |
| 05-run-loop | 外层循环：预算、暂停、卡死检测、并发消息不丢 |
| 06-condenser | 压缩器：硬压软压、砍到一半、四级降级 |
| 07-security | 安全体系：五层检测、shell 语法解析、失败关闭 |
| 08-critic | 评审员：可验证的预测、失败模式图谱、迭代精修 |
| 09-context-engineering | 提示装配与技能：前缀缓存、渐进式披露、路径规则 |
| 10-llm-seam | 模型接缝：能力表、非原生函数调用、三层降级 |
| 11-tool-layer | 工具层：三种来源一个接口、唯一出口脱敏 |
| 12-workspace-and-server | 执行环境与服务端：五方法抽象、认证分组、日志纪律 |
| 13-tool-implementations | 具体工具：tmux 保状态、原子写入、子 agent 委派 |
| 14-hooks | 钩子系统：退出码协议、提示注入隔离、异步进程管理 |
| 15-routing | 模型路由：确定性路由器 vs 元配置分类路由、账外开销 |
| 16-skills-loading | 技能加载：三层优先级、按可变性分层缓存、符号链接逃逸防护 |
| 17-acp-agent | ACP 适配层：驱动外部 agent、空闲超时 vs 硬超时、厂商差异表 |
| 18-browser-and-patch | 浏览器与补丁工具：fuzz 分数量化不确定性、注入 JS、分级错误策略 |
| 19-secrets-and-git | 密钥与 git：引用而非持有、流式脱敏算法、两种 diff 基准 |
| 20-observability-and-orchestration | 可观测性与编排：零成本追踪、显式上下文传递、AI 写编排代码 |
| 21-task-manager | 任务管理器：生命周期与驱逐、累计值陷阱、委派结果的可信度 |
| 22-subagent-registry-and-consultants | 子 agent 注册表与顾问工具：Markdown 定义 agent、三种求助渠道对照 |
| 23-agent-server | 服务层：租约与围栏令牌、双签名缓存失效、WebSocket 重连补发 |
| 24-plugins-profiles-settings | 插件与配置档：格式策略模式、软外键生命周期、允许清单 vs 禁用清单 |
| 25-remaining-tools | 剩下的工具：三级后端回退、三套编辑格式按模型选、子 agent 提示范本 |
| 26-verification-run | 实跑验证：11 条断言被证实、2 处修正、1 个没预料到的发现 |
git clone --recurse-submodules https://github.com/Darrenus/openhands-research.git已经 clone 过的话：
git submodule update --init --recursive更新到上游最新：
git submodule update --remotesoftware-agent-sdk 在 SWE-bench Verified 上的成绩是 77.6，技术报告见 arXiv:2511.03690。
本仓库的笔记采用 MIT。upstream/ 下的各子模块遵循其各自仓库的许可证。
子模块锁定版本记录于 git 索引；当前 SDK 指向 e21d77673。