🐳 DeepSeek Harness 技术架构原理
照着《DeepSeek Harness 技术入门与架构原理》做的自学笔记 —— 前面那门 Agent+RPA实战 讲的是【把 AI 接进真实工作流】，这一课往下钻一层，讲Agent 软件本身应该怎么组织。全书 导读 + 8 章 + 2 附录 共 95 篇：为什么现在需要 Harness、Harness 不只是另一个 Coding Agent、从零开始运行 DSH、一切皆插件意味着什么、从 Skill / Tool 到 Hook、Cordis 让插件能够动态组合、Agent 一轮工作的全过程、从 Tool Call 到 Agent Runtime、设计自己的 Harness，最后是术语与快速演进两个附录——把 DSH 那句等式 Model + Harness = Agent 拆开，讲中间那一层的每一块怎么做成可自由装卸的插件。这是混合课：概念篇的 Demo 是沙箱里真跑过的 Python 小脚本，动手实验篇（第 2、4、5、7、8 章）则真的把 DSH 装起来跑（npx @deepseek-ai/dsh，实测 0.2.0-rc.2），复现只需一台装了 Node.js 的电脑，不需要服务器。DSH 处于 developer preview（主版本号 0），凡与教材写法不同处，各篇都用【⚠️ 2026 现状】单列。大白话、不跳步骤、必带生活比喻、常见误区、可折叠自测题。
前置课程：Agent+RPA实战（把 AI 接进工作流）、编程原理（程序怎么组织）、云计算（基础设施怎么被抽象成服务）。
内容来自我的 Obsidian 自学笔记 · 全 10 个部分 95 篇完结 ✅
导读 为什么现在需要Harness
Model 只会生成 Token，但 Agent 要完成任务
模型的本事只有【预测下一个 Token】…
为什么 DSH 值得单独写一本书
DSH 开源的是运行时不是模型（MIT／…
本书的学习路径
全书三段：先跑起来（第 2 章）→ 再拆…
第一章 Harness不只是另一个Coding Agent
先把【产品】和【Runtime】区分开
产品是看得见的外壳、Runtime 是底…
【一切皆插件】
模型适配／工具注册表／会话存储／沙箱／调…
为什么这不只是【多加几个 Tool】
加 Tool 是往核心塞功能、皆插件是做…
这是否意味着 DSH 会成为行业标准？
开放与封闭两条路线各有取舍（换可替换 v…
Developer Preview
版本号 0 开头＝接口不承诺兼容；预览期…
第二章 从零开始运行DSH
环境准备
前置条件只有一条（Node ^20.19…
Workspace 是 Agent 的【现实世界】
工作区一次决定四件事（能看／能改／命令在…
配置模型
只有两个词要分清：Provider（连哪…
对照 4 套 Preset
四套真身：standard(19)／pt…
观察 composition 的【差分】
做差集：PTC ＝ Standard ＋…
比较同一任务的执行轨迹
同一任务四套的走法（往返 1~4 次）…
为什么官方 Benchmark 会选 Minimal
Minimal 只有 persisten…
本章小结
六步复盘＋本章真实数据（插件数 19/2…
第三章 一切皆插件意味着什么
DSH 的 4 套 Preset 不是 4 个独立 Agent
四套预设的 name 全是 @deeps…
Scope Context：会话级能力从哪里来
宿主平面进程一份、会话平面每会话一份；能…
作用域的意义：动态组合必须有边界
判断标准只有一条：它该活多久；挂错平面的…
Standard：能力基线
19 件按活儿分七类，连插件管理器都是插…
PTC：同一批能力，不同的呈现方式
差分只多 tool-presentati…
Minimal：把 Harness 压到非常薄
只留 persistent-shell…
Creative：让 Runtime 本身也成为可操作对象
差分只多 tool-cordis：查询／…
4 套 Preset 如何体现【一切皆插件】
三条证据：同一 preset 插件／差分…
【一切皆插件】不等于没有内核
内核只管加载卸载、依赖解析、作用域管理三…
本章小结
八节复盘＋三个判断（一套 Runtime…
第四章 从Skill、Tool到Hook
Skill 路径与默认启用方式
Skill 是 4 件包（本体／来源／呈…
动手实验：删除 Skill，观察能力是否还在
补丁停掉 4 件 → 1260 行配置树…
注册也有生命周期
profile ＝ 四层补丁栈（bund…
不要把 Tool 看成一个函数
一个包挂多个入口（包名／/tools／/…
第三层：用 Hook 改变执行规则
配置树与 schema 搜 hook 均…
Tool Execution Pipeline：一次工具调用究竟要经历哪些阶段
六道关：挂载（disabled 条件 5…
为什么 Guard 要【单调】
权限是三档枚举（read-only／wo…
Approval 与 Sandbox 为什么必须放在不同层
两个独立插件两套配置：审批回答【这次要不…
PTC 与 Pipeline：为什么不能绕开这条管线
PTC 侧挂着三件包（presentat…
动手实验：同一 Tool，不同执行规则
补丁改沙箱与审批 → diff 只有 6…
本章小结
八节复盘＋三层扩展收口（Skill 不写…
第五章 Cordis让插件能够动态组合
Temporal Composability：生命周期结束时，变化也必须被撤下
时间维度硬规矩：装上、在场、撤下三段都要…
Effect 的边界
Effect＝【我会改变什么】；只改声明…
Spatial Composability：当能力环境变化时，插件还能不能运行
空间维度：环境变化是常态；实测 isol…
插件被发现，不等于已经具备运行条件
上岗三步：发现（包在不在）→装载（依赖齐…
Fiber：记录插件实例的一段生命周期
Fiber＝实例的生命周期账本：来源／依…
逆序清理不等于逆序完成
撤下按依赖逆序发起（C→B→A），但不必…
Cordis 的 HMR 建立在生命周期之上
实测两件 HMR 包（宿主侧 dsh-h…
Effect 与 Coeffect：插件增加什么，又需要什么
一对反向声明：Effect（交电费）／C…
动手实验：让依赖出现，消失，再回来
三轮补丁真跑：出现（insert +3…
为什么 Cordis 特别适合 Agent Runtime
四特点对四机制（会话生灭→生命周期／能力…
本章小结
九节复盘＋三条规矩一本账（可撤下／有边界…
第六章 Agent一轮工作的全过程
Agent Loop 不是黑盒
从消息进来到回复出去，中间的每个站位都点…
Turn 与 Step：一轮工作可以包含多次模型推进
Turn 是用户消息到最终回复的一整轮…
Tool Call 要经过统一执行管线
一轮里模型可能调多次工具，每次都从同一道…
Session 不是简单的消息数组
实测 session 系列包有 14 件…
模型看见的内容应当可追溯
会话流水至少记四类事件（用户消息／ass…
持久会话事件与实时 Agent 能力事件：记录事实和支持干预
同一轮工作，事件分两路：持久会话事件（落…
为什么还要保留 assistant／chunk
chunk 是流式输出的一小段；逐段保留…
Projection：同一组事实可以生成不同视图
事实只有一份（JSONL 流水），视图随…
上下文压缩也必须保持可解释
实测 compaction 分组三件包…
稳定的请求前缀与 KV Cache
模型推理有前缀缓存：请求开头完全一样就命…
重建一次模型请求，至少需要哪些材料
六样材料：系统提示、人格指令、事件流水…
能回放，不等于结果一定能复现
回放＝同样的输入重放；复现＝得到同样的输…
用 Session 调试 Agent：先找证据，再判断是不是模型问题
三步：SQL 查流水找证据 → 视图定位…
本章小结
一轮工作 ＝ N 次模型推进 ＋ 每次都…
第七章 从Tool Call到Agent Runtime
PTC：让模型用程序编排已有工具
模型不再【调一次看一眼】，而是写一段程序…
PTC 不能绕过安全治理
程序里写的每一次工具调用，照样从统一管线…
代码执行能力与具体实现分离
实测 ptc-runtime 的实现包叫…
PTC 压缩的是确定性控制流，不是依赖语义理解的决策
PTC 把确定性控制流（顺序、循环、条件…
PTC 中的工具调用为什么还要经过统一执行管线
程序里的调用依然要过统一管线——因为管线…
动手实验：用同一任务比较 Native Tool Calling 与 PTC 的效果
两次补丁真跑：实验 A 证明顶层补丁下不…
PTC 什么时候反而不划算
PTC 省的是往返，不是判断——步骤很少…
同一种 Subagent 能力，可以有不同的实现
实测配置里 4 个 provider 用…
委派子任务的 3 个问题
派活之前先回答三问：谁来做（provid…
委派还要明确任务和返回结果
委派指令必须写清任务与范围，还要写死返回…
Sandbox：决定能力在哪个受控环境中执行
实测沙箱是三处接缝＋一条策略：bash-…
持续任务机制：让工作跨越多个 Turn
普通对话一轮就结束；目标＋跨轮驱动＋后台…
Extensions：让 Agent 可以观察和修改当前 Runtime
tool-cordis 让模型能列出插件…
Creative 为什么属于高信任能力
Creative 只比 Standard…
Runtime 到底多做了什么
把本章的大件横过来看：模型只负责产生下一…
本章小结
十章复盘收成一句：Runtime 的每个…
第八章 设计自己的Harness
从需求出发，而不是从插件列表出发
造 Harness 的第一个动作不是【翻…
设计一种新能力时，需要先确定什么
设计一种新能力，先定四件事：能力 id…
把可替换点放在正确的层
接缝放错层的后果不是报错，而是静默无效…
最终项目：设计一套 Preset
最终项目是设计一套自己的预设——目标一句…
第一步：先列任务与权限清单，再写 YAML
写 YAML 之前先写清单——清单是给人…
第二步：把 Host 的共享能力与 Reviewer 的会话级组合分开
同一份清单，要按【该活多久】分两堆：跨会…
第三步：只向模型暴露审查真正需要的工具
Standard 的 19 件里，审查预…
第四步：规定审查结果的输出格式
不写格式，模型每次给的报告都长得不一样…
第五步：用失败路径验证 Preset，而不只测试正常情况
正常情况只能证明【能跑】，失败路径才证明…
不要把 Preset 当成权限系统
预设能决定装哪些件，决定不了能踩多大范围…
插件生态越强，边界越重要
件越多，越需要一套【谁能在哪一层动什么】…
模型表现与 Agent 整体表现必须分开
一个分数是模型与 Harness 一起跑…
DSH 最值得学习的不是某个 API
DSH 是主版本 0 的预览软件，接口明…
Harness Lab 的最终架构
把全书拼成一张图：模型在上，宿主与会话两…
本章小结
十章收成一句：造一套自己的 Harnes…