不是源码翻译
先回答“为什么这样设计”，再解释事件顺序、边界和代价。
28 章 · 6 层 · upstream@47f9438
把 Agent Harness
读成一套可迁移的架构能力
从“为什么不只是一个 while 循环”开始，沿 Cordis 插件树、Turn / Step、事件事实、工具守卫、压缩投影、子代理与工作流，一直走到你能安全扩展自己的 Agent 产品。
通俗直觉真实事件流源码可复核
研究基线deepseek-harness@47f94382026-08-13 · developer preview
不是过时快照
逐条校准官方 47f9438：49 个顶层包族、324 份文档。
不是读完就忘
每章都有可点击机制图、不变量、反例、自测与下一章桥接。
ARCHITECTURE ATLAS
先看系统，再看文件
49 个包族并不等于 49 个孤岛。用六个平面把复杂度重新装进可推理的抽屉。
六平面架构地图 SOURCE ALIGNED
Profile · Bundle · Patch · Cordis
组合平面
决定哪些插件存在、如何分层以及卸载时如何回收。
bootbundlepresetextensionsGUIDED CURRICULUM
每章只跨一个台阶，但从不浅尝辄止
01
能向别人讲清模型、Agent 与 Harness 的边界
4 章建立全局直觉
先知道 Harness 解决什么问题，再学习它如何拆分复杂度。
02
能读懂一棵真实插件树为何可安装、可替换、可卸载
5 章掌握组合语法
沿着 Cordis 的上下文、effect、服务、事件、作用域与配置树读系统。
03
能逐事件解释一次完整模型请求
6 章追踪 Agent 主干
从 Agent 创建到 SessionEvent、Turn、Step、Prompt、LLM 与工具执行。
Agent 的创建、所有权与取消
谁有权销毁一个 Agent？创建失败一半时又如何回滚？
SessionEvent：唯一真源
为什么连原始 assistant/chunk 都要持久化，而不是只存最终消息？
Inbox、Turn 与 Step
为什么“用户发了一条消息”不等于“系统只会请求一次模型”？
Prompt 不是一段字符串
插件如何增加模型可见上下文，又不让所有人共同编辑一份 systemPrompt？
LLM Adapter 与流式词汇
DeepSeek、重放模型或其他 Provider 的流式事件为什么能进入同一 Agent Loop？
工具执行不是一次函数调用
为什么一个后加载插件不能把前面已经 deny 的危险调用重新放行？
04
能判断系统在拒绝、崩溃、取消和长上下文下是否仍可信
5 章理解安全与耐久性
审批、沙箱、文件系统、压缩、持久化、投影与防御性不变量。
审批、策略与权限预设
为什么“danger-full-access + never ask”仍然不等于所有工具都能执行？
Sandbox、FS、Shell 与同一个执行世界
为什么替换 subprocess provider，Bash、PTY、LSP 与外部子 Agent 会一起迁移？
Compaction、Token Meter 与 Spill
如何缩短模型上下文，同时不破坏工具 call/result 配对、不删除原始事实？
持久化、Projection 与 Query
会话列表为什么不应该为每一行加载完整 SessionEvent 日志？
取消、超时与防御性不变量
为什么一个超时不能简单地 Promise.race 后忘掉仍在运行的工作？
05
能区分状态、委派、编排与长期运行的责任边界
4 章从单 Agent 扩到协作系统
目标、计划、待办、子 Agent、后台任务、工作流、调度和能力发现。
06
能在不修改 Agent Loop 的前提下交付一项完整能力
4 章动手扩展并交付
把理解落到工具、适配器、客户端表面、Profile 与 Bundle。
FROM READER TO BUILDER
看懂一次运行，解释每个边界，最后做出自己的组合。
第一章只需要 12 分钟：先把 Harness 和 Agent Loop 的差别讲清楚。
开始深读