0基础深入理解DeepSeek Harness 架构【0】总览

目录DeepSeek Harness 架构详解手册架构详解手册如何使用这本书三种读法本书中的几个约定第 0 章 先建立心像三个词、一次问答0.1 三个词大模型、Agent、Harness0.2 一次问答里到底发生了什么0.3 为什么必须要有 Harness0.4 十个词先混个脸熟第 1 章 Cordis整座建筑的地基1.1 五个核心概念1.2 五种事件分发模式选错就没信号1.3 waterfall环绕中间件以及「短路」的正确姿势1.4 一个完整的插件长什么样1.5 为什么「没有特权内核」这件事很重要1.6 Cordis 官方的实践规则照做就对了1.7 两个贯穿全仓库的类型模式1.8 这一章要带走的三句话第 2 章 一架 dsh 是怎么被组装起来的2.1 先看结果启动之后你到底得到了什么2.2 两个核心名词profile 与组合包2.3 五个内置 profile同一套内核五种外壳2.4 patch按 id 覆盖而不是深度合并2.5 最有用的一个命令把装配单打印出来2.6 应用启动器为什么没有第二个可执行文件2.7 启动器背后做了什么app-boot2.8 桌面版与 Python SDK同一套架构两个方向2.9 这一章要带走的三句话第 3 章 一个轮次的一生全书最核心的一章3.1 先定义两个词轮次与步骤3.2 官方伪代码逐行翻译3.3 全局视图把八个阶段画成一张图3.4 三个事件域该用哪个是大多数改动的第一个决定3.5 Agent 句柄你用来对话的那个对象3.6 inbox两条队列不是一条3.7 状态的真相idle 与 running3.8 取消原因是要被记住的3.9 agent/created创建 agent 时要等的事3.10 这一章要带走的三句话第 4 章 会话日志整个系统唯一的真相来源4.1 一句话说清日志是唯一真源4.2 日志里都有哪些事件4.3 「模型可见即已记录」4.4 surface日志里「真正会变成消息」的那一层4.5 插件怎么合法地修改消息内容4.6 轮次为什么结束七种原因4.7 持久化日志怎么落到磁盘上4.8 fork在轮次边界切一份会话4.9 谁来检查日志的合法性4.10 这一步做什么用投影 seam4.11 这一章要带走的三句话第 5 章 系统提示词是怎么拼出来的5.1 三个贡献类型段落、上下文、工具 schema5.2 段落的字段五个就够了5.3 最容易困惑的一点系统提示词是「消息」不是「请求字段」5.4 工具 schema 是怎么进提示词的5.5 工具提供方结果里的两个字段5.6 一个完整的组装上下文5.7 实操写一个自己的提示词段落5.8 这一章要带走的三句话第 6 章 工具执行流水线把权力关进流程里6.1 先看一个最小的工具6.2 完整字段表一个工具可以说多少事6.3 流水线全貌一次调用要过几道关6.4 三道 waterfall 怎么选一张判断表6.5 守卫为什么是「单调」的6.6 决策类型你能返回什么6.7 参数与结果为什么都要「物化 冻结」6.8 并发调度独占屏障与滚动池6.9 沙箱与审批谁能拦住一次调用6.10 PTC mode让模型写代码来调工具6.11 后台任务工具跑了很久怎么办6.12 UI 卡片一层独立的渲染意图6.13 这一章要带走的三句话第 7 章 模型流式和模型之间的那根管子7.1 消息与内容块一套可扩展的词汇7.2 消息来源两个正交的维度7.3 StreamChunk模型吐回来的原始协议7.4 BlockAssembler唯一的共享装配实现7.5 紧凑 Assistant stream证据怎么存7.6 失败与重试一套统一的失败事实7.7 重试策略注册时就固化下来7.8 Token 计量四个互不重叠的数7.9 请求信封一次调用被记成什么7.10 一个具体的设计取舍为什么「路由容量」要单独记7.11 这一章要带走的三句话第 8 章 能力 seam换个零件换掉整个产品8.1 什么是 seam三个角色一个接口8.2 最漂亮的一个例子为什么搬走文件系统就等于搬走一切8.3 主要 seam 一览8.4 怎么读这张能力图8.5 一个纪律一个包可以兼任多角色但你要说清楚8.6 这一章要带走的三句话第 9 章 作用域一个进程里跑很多个互不干扰的 Agent9.1 问题的提出9.2 核心三个词9.3 带作用域的注册表层9.4 Agent 自己的作用域agent.ctx9.5 工具的作用域与限制9.6 agent preset一整棵配置树级别的差异化9.7 发起方initiator谁在发起这件事9.8 这一章要带走的三句话第 10 章 动手用架构知识开发 Agent10.1 第一步学会问「挂在哪」10.2 零基础环境搭建先把东西跑起来10.3 实操一写一个工具最完整的例子10.4 实操二写一个权限门禁钩子插件10.5 实操三写一个模型适配器10.6 实操四让界面显示实时输出10.7 实操五写一个协议驱动10.8 实操六委派给子 agent10.9 加新行为的完整清单10.10 这一章要带走的三句话第 11 章 术语表11.1 核心名词11.2 流程与状态11.3 日志与数据11.4 消息与模型11.5 工具与安全11.6 Cordis 机制11.7 应用与宿主附录 A 扩展点速查表A.1 按目标查机制A.2 按产品功能查插件机制A.3 所有事件一览按分发模式分组附录 B 核心 ctx 键速查表附录 C 新手最常见的十二个坑附录 D 资料来源与核对说明D.1 主要资料来源D.2 核对中发现并处理的四处地方D.3 范围边界D.4 一份实用的一句话总结DEEPSEEK HARNESS 架构详解手册从零开始看懂一个「一切皆插件」的智能体框架读完能自己动手写 Agent面向读者完全没有接触过 Agent 框架的开发者、产品与运维同学资料来源DeepSeek Harness 官方架构文档docs/architecture.zh.md及其引用的全部子系统、教程、实操手册与核心包文档阅读方式前 3 章建立心像第 4—9 章拆解心脏第 10 章动手第 11 章与附录随时查一个重要提醒官方明确标注项目处于「开发者预览」阶段未来会出现破坏兼容性的变更。本书描述的是文档所记录的架构契约具体字段与命令请以你手上那份代码为准如何使用这本书这不是一份「读完就忘」的 API 清单。它要解决的是一个很具体的问题当你面对一个几十个包、上百个扩展点的框架时怎么才能既不迷路又能真的动手加东西。三种读法第一种通读推荐从第 0 章一路读到第 11 章。大约需要两到三个完整的时间段。读完后你会拥有一张完整的脑内地图之后遇到任何新概念都能自己定位。第二种带着任务读直接翻到第 10 章找到你要做的事加一个工具、加一个权限门禁、换一个模型提供方……照着做。做不下去时顺着文中给的章节号回跳补课。第三种当字典用第 11 章的术语表、附录 A 的扩展点速查表、附录 B 的 ctx 键速查表就是为「查一下」准备的。不必按顺序读。本书中的几个约定视觉记号含义术语鼠标移到带虚线下划线的词上会浮出这个词的大白话解释带虚线下划线的词是术语。把鼠标移上去手机上点一下会浮出这个词的大白话解释。第 11 章有完整列表。关键这是理解后续内容必须记住的一句话。跳过它后面会读不懂。反直觉初看会觉得「这不对吧」但它恰恰是这套架构的设计要点。这类地方最容易误读。陷阱新手最常踩的坑。多数来自「用别的框架的经验」硬套过来。像这样的等宽字代码、文件名、配置键、命令。可以直接照着敲。关于「官方文档已经写得很好了为什么还要这本书」官方文档是按「子系统」组织的每篇都对但假定你已经知道 Cordis、知道 seam、知道 surface。对零基础读者来说最难的不是某一个子系统而是找不到它们之间的接缝。这本书补的就是接缝每一章都先讲「它在整个机器里负责哪一环」再讲细节。第 0 章 先建立心像三个词、一次问答在读任何架构细节之前你得先在脑子里装上一幅正确的画面。这一章不讲代码只讲三个词和一次问答的完整过程。0.1 三个词大模型、Agent、Harness先说最容易被混在一起的三样东西。大模型LLMLarge Language Model是一个函数。你给它一段文字它返回下一段文字。仅此而已。它不记得上一次对话不能打开文件不能上网也不能执行命令。它的全部能力就是「预测下一段文字」。Agent智能体是一个循环。它把大模型、一组可调用的工具、一段会话历史凑在一起反复做这件事让模型看当前局面 → 模型说要调用某个工具 → 真的去调用 → 把结果塞回历史 → 再问模型。直到模型说「我说完了」循环结束。这个循环叫 Agent LoopAgent Loop驱动 Agent 反复执行「请求模型 → 执行工具 → 回填结果」的那个程序循环。Harness本框架的名字就叫 DeepSeek Harness命令是dsh是承载这个循环的整套工程设施。它管的是循环之外的脏活会话记录怎么存、提示词怎么拼、工具调用前的权限怎么问、用户点「停止」时怎么优雅退出、插件热重载、桌面端和 Web 端怎么共用同一套内核。图 2大模型是引擎Agent 是传动系统Harness 是整台车——而且这台车允许你在行驶中换掉任何一个零件。关键在 DeepSeek Harness 里连 Agent 循环本身也只是「一个插件」。这句话是整个架构的起点。它意味着没有哪一块是神圣不可动的你不需要 fork 一份代码去改内核。0.2 一次问答里到底发生了什么你在界面上敲一句「帮我看看这个文件里有什么」按下回车。接下来发生的事可以分成两大层来看。图 3看得见的是界面看不见的是事件流。本书大部分篇幅都在讲下面这一排方框。0.3 为什么必须要有 Harness你可能会想上面那个循环二十行代码就能写出来为什么需要一个框架因为一旦上线问题会从「怎么跑通」变成下面这些真实世界里必然出现的问题Harness 给出的答案对应本书章节上下文太长模型读不下会话日志 压缩机制第 4、8 章模型要删你的文件怎么拦住工具执行流水线五道关卡第 6 章用户点了停止但工具还在跑取消语义与收敛第 3、6 章想换一家模型厂商LLM 适配器 seam第 7、8 章想让工具跑在远程沙箱一个受限的执行环境。程序在里面能做什么、能碰哪些目录都由外面的策略规定里能力 seam换一个提供方第 8 章同一个进程里要跑好多个互不干扰的 Agent作用域与 agent preset第 9 章进程崩了聊天记录不能丢仅追加日志 检查点 崩溃恢复第 4 章想加一个新功能又不想改内核插件 事件 能力 seam第 1、8、10 章0.4 十个词先混个脸熟下面十个词会在全书反复出现。现在不必背扫一眼即可读到对应章节自然就懂了。词一句话解释详细见插件框架里唯一的「零件单位」。一个函数或一个类挂上去就生效摘下来就撤销。第 1 章上下文 ctx插件共用的「接线板」。服务的插头都插在这上面按名字取用不直接互相 import。第 1 章服务一项能力在上下文里占一个固定的名字比如ctx.tools、ctx.llm。第 1 章profile「一套启动配方」。决定这次启动要装哪些零件。第 2 章轮次 / 步骤轮次 你按一次回车到模型彻底停手步骤 里面的一次模型请求加它调用的工具。第 3 章会话日志只增不改的事件流水账。它是整个系统唯一的真相来源。第 4 章surface日志里「真正会变成模型消息」的那一层压缩就是在这层做替换。第 4 章seam「可替换能力」的接口。换一个实现整个产品行为就变了。第 8 章作用域 scope「这个注册只对某个 Agent 生效」的机制。第 9 章PTC mode让模型写一段代码来批量调用工具的机制而不是一次次单独调用。第 6 章反直觉零基础读者最容易有的误解是「框架 一堆没人看得懂的抽象」。DeepSeek Harness 的抽象方向恰好相反它把几乎所有东西都压缩成同一组概念——插件、上下文、服务、事件、可逆副作用。学会这五个词你就能读懂这个仓库里 90% 的代码。第 1 章就是讲这五个词。