DeepSeek代理框架 · 讲义与学习笔记

系统拆解 DeepSeek Harness 的设计开发全貌，并完成一个类似 dsh 的 Agent 原型

整理：boyne

第 1 关 · Harness 定位、边界与整体架构

能说明 DeepSeek Harness 的项目定位与系统边界，并依据公开文档和源码解释其三层架构、插件组合方式及证据限制。

项目定位与核心命题

把模型看作负责生成下一步的「决策核心」，Harness 则是围绕模型建立的「执行驾驶舱」。模型能够理解任务、推理并提出行动，但它不会自行读取持续变化的仓库状态、真正执行命令，也不会自动把测试失败送回自己。Harness 决定模型能看到什么、允许执行什么、结果如何回流，以及任务何时继续或停止。

因此，DeepSeek Harness 的项目定位可以概括为：**它不是另一个基础模型，而是把模型组织成可运行 Agent 的编排与运行时框架。** 「Agent = Model + Harness」不是说外围环境不重要，而是说真正决定代理如何持续行动的，是模型生成能力与 Harness 编排机制的结合。

flowchart LR
    U[用户目标] --> H[Harness 组装上下文]:::focus
    H --> M[模型生成候选行动]
    M --> D[Harness 解析与决策]:::focus
    D -->|需要执行| T[工具或执行环境]
    T -->|执行结果| H
    D -->|任务完成| R[交付结果]:::result
    P[外围基础设施] -.支撑.-> H
    P -.支撑.-> T

图中的实线构成「上下文—生成—执行—反馈」闭环。Harness 的核心职责包括：维护任务状态，组装指令、历史消息与工具结果，调用模型，解析模型输出，执行获准的工具，把结果反馈给模型，并根据完成条件、错误或预算控制循环。

三类职责不能混为一谈
  1. **模型能力：决定能生成什么。**

模型的语言与代码能力、推理质量、知识水平、结构化输出和工具调用能力，主要来自训练所得的模型及其推理机制。它回答的是：在当前输入下，什么是合适的候选行动。它本身不负责保存完整会话状态，也不等于已经执行了行动。

  1. **Agent 行为：决定行动如何形成闭环。**

可观察的代理行为包括持续推进任务、调用工具、检查结果、处理失败、遵守权限、适时停止并交付结论。这些行为由模型参与决策，但具体流程由 Harness 组织。**同一个模型放进不同 Harness，可能分别表现为一次性问答助手与能自主执行、验证和纠错的编码代理。**

  1. **外围基础设施：决定行动能在哪里可靠发生。**

模型 API 接入、认证与计费、计算资源、网络、容器或沙箱宿主、持久化设施等属于运行环境。它们会影响成本、延迟和可用性，也会限制工具能做什么，但不等同于模型能力或代理编排策略。即使某个组件被整合进 Harness 工程，它的逻辑角色仍需按这一标准辨认。

一个具体例子

假设任务是「修复解析器在空输入时崩溃」。模型先根据 Harness 提供的相关文件和错误信息提出补丁；Harness 检查操作是否获准，实际应用补丁并运行测试，再把失败日志与新上下文交给模型。若测试仍失败，Harness 继续循环，并限制重试次数；全部通过后，才输出修复结果。

这里，模型的推理与代码生成属于**模型能力**；读取文件、执行补丁、运行测试、回传错误和决定停止属于 **Harness 编排**；测试进程、文件权限、网络与计算资源属于**外围基础设施**。三者缺一，实际行为都可能不同。

更完整地说，可观察的 Agent 行为可理解为：

**Agent 行为 = f（模型生成能力，Harness 编排，环境约束）**

「Agent = Model + Harness」强调的是前两项的直接组合；环境约束则决定这套组合最终能做什么。阅读项目文档和源码时，也应先问：某段代码是在生成内容、组织行动，还是仅仅提供运行条件？

**检测题：**若保持模型不变却改变代理的任务推进方式，应优先改变哪一层？

系统边界与责任划分

用「控制权」划定系统边界

DeepSeek Harness 的系统边界不能只靠目录或类名判断，而应看五种控制权分别落在哪里：**谁决定下一步、谁执行行动、谁保存状态、谁提供隔离、谁呈现交互**。模型与 API、Harness 核心、插件能力、外部工具、存储、沙箱和界面共同构成运行闭环，但它们的责任并不相同。

flowchart TD
    I[界面] <-->|交互| H[Harness 核心]:::focus
    H <-->|调度| P[插件能力]:::focus
    P <-->|调用| M[模型与 API]
    P <-->|读写| D[存储]
    P -->|请求执行| X[外部工具]
    P -->|受控执行| S[沙箱]
    S -.约束.-> X

实线表示主要调用或数据流：Harness 核心通过插件使用具体能力；虚线表示沙箱对执行过程施加约束。关键区别是，**核心负责决策与编排，插件负责实现能力，外部依赖负责真正产生副作用或提供基础设施**。

各层的责任边界

| 边界 | 负责什么 | 不负责什么 | |---|---|---| | 模型与 API | 根据上下文生成文本、推理结果或工具调用；提供供应商特定的请求格式与能力约束 | 不保存完整任务状态，不亲自执行工具，也不保证整个代理循环能够持续运行 | | Harness 核心 | 管理任务生命周期、上下文组装顺序、模型与工具调度、结果回流、错误处理、重试和停止条件 | 不亲自实现某个模型、数据库、命令执行器或界面 | | 插件能力 | 以统一能力契约接入模型、工具、会话、存储、沙箱、界面等具体实现，并完成协议转换与配置 | 不取代核心对全局流程和策略的管理 | | 外部工具 | 真正执行搜索、版本控制、文件操作或业务 API，并返回可核验的结果 | 不负责决定下一步，也不应自行决定是否继续代理循环 | | 存储 | 持久化会话、消息、任务记录、工件或检查点；提供查询、更新和保留能力 | 不负责判断哪些信息语义上最相关，也不负责规划 | | 沙箱 | 约束执行位置与权限，包括进程、文件系统、网络、时间和资源边界 | 不负责推理，也不等同于长期数据存储 | | 界面 | 接收用户输入、流式展示过程、呈现确认请求与最终结果 | 不应私自改写核心的任务策略或执行逻辑 |

由此可以得到三个容易混淆的边界：

  1. **外部工具不等于工具插件。** 插件是代理侧适配器，负责把标准工具调用翻译成实际请求；Git 服务、搜索 API 或 MCP 服务才是执行主体。
  2. **存储不等于沙箱。** 存储解决「重启后仍在」；沙箱解决「执行时不能越界」。会话可存入存储，但临时构建目录通常位于沙箱工作区。
  3. **模型能力不等于编排能力。** 模型可以建议调用某个工具，但是否允许调用、如何注入结果、何时重试或停止，仍由 Harness 核心决定。

认证、超时、重试、限流和计费通常属于模型适配器或接入基础设施。它们会影响运行效果，但不应被误算为模型本身的推理能力。

dsh 式原型的交付边界

一个可运行的 dsh 式原型应包含：

原型不必包含：基础模型权重与预训练、微调流水线、训练集群、供应商服务端的推理内部实现、外部工具自身的完整产品实现，以及与单用户代理闭环无直接关系的企业级多租户平台。它们仍可作为后续部署优化或证据研究对象单列，但不应冒充 Agent 原型的核心能力。对于未公开的内部机制，也只能建立待验证假设，不能以接口需要为由虚构实现。

判断某个功能归属时，可以依次追问：它是在**选择下一步、调用能力、执行副作用、保存状态、限制执行，还是呈现交互**？回答不同，就应落到不同边界内。

**要点：** dsh 式原型的核心不是重造模型或外部服务，而是用一个边界清晰的 Harness，把模型决策、可替换能力、受控执行、持久状态与用户交互连接成可验证的闭环。

三层架构与组合规则

DeepSeek Harness 的三层架构不是三段依次执行的流程，而是三种不同职责：**核心抽象接口负责定契约，具体能力包负责做实现，Bundle 负责选择并连接实现**。运行时只会面向接口编程，厂商实现和部署配置则被隔离在组装阶段。

第一层：核心抽象接口——声明扩展点

核心层定义 Harness 在运行过程中真正需要调用什么，而不是某个能力具体怎样实现。一个扩展点通常包含：

例如，核心只知道自己需要一个「模型接口」：接收上下文并返回模型消息或工具调用；它不直接依赖 DeepSeek API、某个 HTTP 客户端或特定 SDK。工具、会话、存储、沙箱等能力也以同样方式声明。这样，新增实现时只需遵守既有契约，而不必修改代理循环的调度代码。

因此，**接口不是能力名称的目录**。它必须把调用边界表达得足够精确，否则上层只能依赖具体实现，三层边界也会重新黏在一起。

第二层：具体能力包——实现接口

具体能力包是扩展点的实现单元。一个包可以提供模型 API 适配器、Shell 工具、文件持久化、受限进程执行等能力；不同版本或部署环境也可以为同一接口提供不同实现。

实现包主要做三类工作：

  1. 把核心契约翻译成具体协议或 SDK 调用；
  2. 转换外部数据、异常和取消信号，使结果仍符合核心类型；
  3. 声明自己的配置需求、依赖能力和初始化条件。

例如，一个模型能力包负责把统一的模型请求转换为供应商 API 的请求格式，再把供应商响应还原为统一消息；一个执行工具包负责接收标准工具参数，并把实际动作交给所绑定的执行环境。

能力包应保持可替换性：它可以实现一个接口，但不应在内部偷偷创建另一套模型客户端、存储连接或沙箱。若能力包绕过接口直接依赖某个具体兄弟实现，替换能力就会被迫修改整条链路。

第三层：Bundle——选择、绑定并验证

Bundle 是**组合根**：它把扩展点与具体实现连接起来，形成一张可执行的运行时实例图。它不是另一种插件，也不只是插件名称列表；它要回答「当前模型槽位使用哪个实现」「这个工具依赖哪个沙箱」「会话和存储是否共享同一实例」等问题。

Bundle 的组合规则可归纳为：

flowchart LR
    C[核心抽象接口]:::focus
    P[具体能力包]:::focus
    B[Bundle 组合规则]
    R[运行时实例图]:::result
    P -.实现.-> C
    P -->|提供候选实现| B
    B -->|选择并注入| R
    R -->|仅按接口调用| C

图中最关键的关系是：能力包向下实现接口，Bundle 从候选实现中选出实例并注入依赖，而运行时核心始终只认识接口。

一个组合例子

假设要组装一个本地开发代理，可以作出如下映射：模型槽位绑定 DeepSeek API 适配器；Shell 工具绑定一个具体执行实现；会话能力绑定到所选存储实现。随后，Bundle 把同一份存储实例注入会话能力，把同一个沙箱实例提供给需要受限执行的工具。

组装完成后，核心向模型接口发出请求；若模型返回工具调用，核心根据工具契约找到对应实例并传入已绑定的沙箱。工具返回的标准结果再由核心送回模型接口。整个过程中，核心既不创建 DeepSeek 客户端，也不决定 Shell 应在哪种环境中运行——这些都属于实现包和 Bundle 的职责。

判断一次扩展是否落在正确层次，可以连续问三句：核心需要的能力是否已由接口准确声明？新实现是否只依赖接口并完成适配？最终实例是否由 Bundle 明确选择、注入并验证？

**要点：** 接口定义「可以怎样接入」，能力包实现「具体怎样工作」，Bundle 决定「本次运行采用谁并如何连接」；三者分离，扩展才不会演变为对核心代码的反复修改。

三层不是顺序流程：能力包实现核心接口，Bundle 选择并连接实现；运行时只认识接口，具体厂商与部署配置被隔离。

三层不是顺序流程：能力包实现核心接口，Bundle 选择并连接实现；运行时只认识接口，具体厂商与部署配置被隔离。

插件化能力面

插件化能力面

插件化并不是把所有代码都做成可随意替换的零件，而是把 Harness 的稳定核心与可变策略分开：核心只依赖明确的能力契约，插件负责具体实现，组合时再注入实例。替换某个插件不应迫使代理循环、会话或界面跟着重写。

九类插件的职责与边界

| 插件面 | 主要职责 | 可替换边界与职责禁区 | |---|---|---| | **模型插件** | 把统一的模型请求转换为具体模型或供应商 API 的协议；处理鉴权、参数、流式事件、模型元数据，以及把供应商错误归一化 | 可以更换模型和供应商，但上下文、消息、工具调用、停止原因等核心语义必须保持兼容。模型只生成候选响应或工具调用，不负责完整的任务路线 | | **工具插件** | 暴露一项可调用的外部操作，声明参数与结果结构，校验输入，执行动作，并返回标准结果或错误 | 可以替换实现方式，但不能偷换工具的业务语义。工具负责「做什么」，不应擅自决定多步骤流程或绕过隔离策略 | | **技能插件** | 提供可复用的任务知识与工作规程，例如提示、模板、检查清单、参考资料和操作步骤；技能可指导模型组合已有工具 | 可以替换技能内容、适用范围或加载策略，但外部动作仍应经工具契约执行，不能借技能绕过权限与沙箱 | | **会话插件** | 管理一轮任务中的消息顺序、工作状态、上下文装载、暂停恢复及必要的上下文整理 | 可以从内存会话换成数据库会话，但不能因此改变会话语义。上下文何时压缩通常由循环策略决定，何时持久化则由存储能力承担 | | **沙箱插件** | 为需要执行本地命令或代码的动作提供隔离环境，约束文件系统、进程、网络和资源使用 | 可以把本地进程换成容器或远程环境，但必须保留约定的隔离边界。沙箱决定「允许怎样执行」，不决定应执行哪个工具 | | **存储插件** | 保存工作区文件、任务产物、检查点以及通用键值或对象数据，并提供读取、写入、删除和恢复能力 | 可以替换数据库、文件系统或对象存储后端，但不能自行定义会话历史或任务计划。持久化机制与业务语义应分离 | | **循环插件** | 实现代理的状态机：请求模型、接收响应、调用工具、加入观察结果、决定继续或结束，并控制步数、预算与上下文整理 | 可以从简单反应式循环替换为规划—执行—复核循环，但模型、工具和会话接口应保持稳定。循环决定代理状态层面的「下一步」 | | **调度插件** | 安排已获准的任务何时执行、以何种并发运行、如何排队、取消、重试或分配资源 | 可以替换串行、并发或队列策略，但不能替模型决定目标，也不能替工具决定业务动作。调度负责「何时、并行地做」，循环负责「接下来做什么」 | | **界面插件** | 接收用户指令，映射为 Harness 的调用；流式展示模型消息、工具事件和错误，并提供历史与控制入口 | 可以把命令行界面换成网页、IDE 或其他交互形式，但界面不应内嵌任务规划、工具执行或会话持久化逻辑 |

插件之间如何协作

下面是一条主执行链。技能插件会按需向模型和循环补充工作规程，调度插件则横向安排模型请求、工具调用或后台任务，因此没有画进固定的先后链中。

flowchart LR
  UI[界面插件] -->|输入与事件| Loop[循环插件]:::focus
  Loop -->|生成请求| Model[模型插件]
  Model -->|消息或工具调用| Loop
  Loop -->|工具请求| Tool[工具插件]:::focus
  Tool -->|结果或错误| Loop
  Loop -->|读写状态| Session[会话插件]
  Session -->|保存与恢复| Storage[存储插件]
  Tool -->|需要隔离时| Sandbox[沙箱插件]

这张图揭示了两个容易混淆的边界。第一，**模型提出行动，循环组织行动，工具真正执行行动**：模型返回工具调用并不代表命令已经运行。第二，**会话组织当前任务状态，存储保存底层数据**：换掉存储后端不应改变对话顺序，换掉会话实现也不应迫使每个插件自己读写数据库。

所有可替换边界都应至少约定五件事：输入与输出结构、流式或非流式行为、错误与取消语义、超时规则，以及是否允许副作用。只约定方法名称而遗漏这些语义，替换后很容易出现静默行为变化。

一个组合例子

假设用户要求「修复一个缺陷并运行测试」。界面插件接收指令，会话插件建立当前任务并准备上下文，技能插件按需载入该仓库的编码规范和测试流程。循环插件向模型插件发送上下文；模型插件返回读取文件、修改代码或运行测试的工具调用。

调度插件可以让互不依赖的读取操作并行；工具插件完成参数校验后，请求沙箱插件在受限环境中执行命令。测试结果作为标准观察结果返回循环，循环再决定继续修改、运行复测还是结束。期间，会话通过存储保存检查点和产物，界面则持续显示修改与测试事件。

此时可以更换兼容的模型供应商、数据库存储后端、容器沙箱或网页界面，而不重写核心循环；也可以替换测试工具的实现，但不能因此改变测试命令的业务含义。由此可见，**可替换性不是插件数量多，而是替换后各层职责仍然清晰**。

**要点：** 九类插件分别承担生成、指导、行动、隔离、记忆、控制、执行调度与交互；可替换的边界由稳定契约和不变语义共同划定，而不是简单地让所有组件互相调用。

公开证据与未公开实现边界

复刻一个类似 `dsh` 的 DeepSeek Agent Harness 时，最容易制造假进展的方式，是把架构上「说得通」的设计误写成项目「已经如此」实现。源码中的类名能证明接口存在，文档中的描述能证明公开承诺，第三方教程能帮助理解用法，但三者能支持的结论并不相同。本节的任务不是寻找唯一权威解释，而是为每条技术陈述标注证据边界。

四类陈述必须分开

| 陈述类型 | 可以依据的材料 | 允许写出的结论 | 不能直接推出的结论 | |---|---|---|---| | **可核验事实** | 官方文档、公开源码、测试、示例和已发布配置 | 「在某个版本的公开实现中，接口 `X` 接受参数 `Y`」 | 不能自动推出线上部署一定采用该默认值 | | **第三方教程解释** | 社区文章、视频、复盘和他人示例 | 「某作者将这一结构解释为……，并给出了如下配置」 | 不能仅因多篇文章重复，就升级为官方事实 | | **接口推断** | 公开接口、可复现实验、依赖关系和架构约束 | 「由于接口只暴露……，因此实现很可能……」 | 不能把合理推断写成确定实现 | | **未公开内部机制** | 私有训练平台、生产路由、隐藏提示策略等无公开材料部分 | 「目前缺少可核验证据，暂记为未知」 | 不能用常识、竞品实现或自己的设计补成事实 |

这些类别不是简单的真假排序。第三方解释可能正确，接口推断也可能最终被源码证实，但在得到新证据之前，它们仍应保留自己的证据标签。

flowchart TD
  C[待核验技术陈述] --> A[事实：文档与源码可核验]
  C --> B[解释：第三方教程]
  C --> D[推断：接口与实验]
  C --> E[未知：缺少公开证据]

因此，审查一个架构结论时，不能只问「有没有人这样写」，还要问：**这句话究竟证明哪个版本、哪个组件、哪一种行为？**

官方文档与公开源码怎样构成证据

官方文档主要说明项目定位、公开用法、配置方式和维护者承诺；公开源码则说明特定提交中的实际数据结构与执行路径。二者需要结合，但不能互相替代：文档可能描述计划中的接口，源码中也可能存在尚未启用的实验分支。更稳妥的证据链是：

  1. **固定版本**：记录仓库地址、分支或提交哈希、发布日期和运行环境。引用源码时尽量链接到固定提交，而不是会变化的默认分支。
  2. **定位公开契约**：从 README、API 文档、导出入口和配置说明确认某个能力是否属于对外接口。
  3. **追踪实现路径**：沿入口、核心抽象、具体能力包到 `Bundle` 组装过程，确认调用是否真的到达该实现，而不是只存在一个同名类型。
  4. **检查测试与示例**：测试能证明维护者覆盖过的预期行为，示例能证明一种受支持用法；二者都不能代表所有配置组合。
  5. **最小化复现**：能本地执行的接口行为应记录最小命令、输入、输出和环境。实验只能证明该环境下的观察结果，不能自动代表生产集群。
  6. **记录冲突**：文档、源码、测试和运行结果不一致时，不强行选一个消音版本，而要记录冲突及其发生条件。

例如，在源码中看到模型、工具、会话等抽象，只能证明公开代码存在这些扩展边界；要断言「`Bundle` 一定按某个顺序组合它们」，还要追踪实际构造入口和集成测试。要断言「工具默认受到完整沙箱保护」，则需要同时检查默认配置、沙箱实现、绕过路径和运行环境，不能只凭一个类名。

第三方教程与接口推断应怎样表述

第三方教程的价值主要是提供阅读线索、踩坑经验和另一种可能的解释。使用时应记录作者、链接、对应版本及教程依赖的配置。推荐写法是：「教程 `X` 认为 `Y`，但其示例使用的版本为 `Z`；公开源码目前只能直接确认……」而不是「该框架就是……」

接口推断必须显式写出前提和竞争解释。例如，公开接口若只允许调用方传入一个存储实例，可以推断「存储后端是可替换的」；但不能据此断言「官方生产环境使用某种数据库」。若运行日志显示循环在上下文超过阈值后调用压缩接口，可以确认该配置下发生了压缩，却不能把所有部署的阈值都视为固定常量。

用「假设—验证清单」管理未知项

未知项不应被隐藏，而应转化为可执行的核验任务。每项至少记录：问题、当前假设、现有证据、验证材料、最小实验、通过标准和无法验证时的结论。

| 未知问题 | 当前只能形成的假设 | 核验方法 | 证据仍不足时 | |---|---|---|---| | `Bundle` 的默认组合与覆盖顺序是什么 | 可能由默认注册表创建 | 追踪构造入口，读取默认配置并运行集成测试 | 保留为未确认，不按猜测实现复刻 | | 上下文压缩何时触发 | 可能受循环策略与配置阈值共同控制 | 检查循环及会话代码，记录输入、输出和 token 变化 | 只描述已观察到的触发条件 | | 沙箱是否覆盖全部工具路径 | 某些路径可能使用沙箱适配器 | 检查调用链并做文件、进程和网络逃逸测试 | 不宣称具备端到端隔离保证 | | 会话恢复是否具备事务一致性 | 可能只保证顺序恢复 | 阅读存储实现并注入写入失败、重启等故障 | 明确区分顺序恢复与一致性保证 | | 生产路由、扩缩容及私有推理机制是什么 | 仓库实现无法代表线上系统 | 查找官方运维说明、版本化配置或可复现实验 | 始终标记为未公开或无法确认 |

最后还要区分**公开源码存在**与**生产系统使用**。开源仓库可以完整展示某一实现，却通常不能证明私有部署环境启用了哪些模块，也不能反推出模型训练、线上调度和服务端优化细节。对后一类问题，最专业的结论往往不是猜测，而是明确写明：「截至所核验的公开版本，没有足够证据支持这一判断。」

**要点：** 先为每个结论标明证据类型，再固定版本、追踪调用路径并以最小实验核验；事实、教程解释、接口推断和未公开机制必须分别记录，未知本身也应成为可执行的验证任务。

研究相关性分层

研究相关性应按**它是否改变复刻对象**来分层，而不是按研究方向是否热门。一个 dsh 式 Agent 的复刻对象既可能包含 Harness 运行时，也可能包含自托管模型与推理服务；同一个研究主题，在不同项目边界下可能属于不同层级。

三层判定标准

采用由强到弱的顺序判断：

  1. **直接影响复刻**：研究结果会改变 Harness 的接口、控制流、状态语义、模型输出解析方式或测试标准，必须落实到代码、配置或扩展点中。
  2. **仅影响部署**：研究不改变 Agent 的运行逻辑，但会改变模型服务的吞吐、延迟、成本、容量、可用性或运维方式。
  3. **仅供背景**：研究能帮助理解问题、比较设计思路或建立评测观念，却不要求当前原型采取特定实现。
  4. **排除登记**：研究无法映射到运行行为、部署约束或复刻决策，只保留索引和排除理由，不继续展开，也不据此推测实现。
flowchart TD
  Q[研究材料] --> R{改变行为或契约?}
  R -->|是| D[直接影响复刻]:::focus
  R -->|否| S{改变部署约束?}
  S -->|是| O[仅影响部署]
  S -->|否| B{有复刻解释价值?}
  B -->|有| G[仅供背景]
  B -->|无| X[排除登记]

图中的判断顺序体现「直接性优先」：若一项研究既影响运行逻辑又影响部署，应标记为直接影响复刻，并把部署影响作为附带属性；不能因为部署部分较容易实现，就把它降为仅影响部署。

预训练与微调：先区分模型产物和研究过程

预训练研究通常改变模型的底层能力，而不是 Harness 的组织方式。若原型调用固定的托管模型 API，预训练数据、训练算法和模型内部结构最多属于背景信息；它们不能证明 Harness 实现了某种规划、记忆或工具调用机制。

微调则要继续区分两种影响：

因此，不能仅凭「使用了微调模型」就断言它是核心实现。即使微调非常重要，它对 Harness 的直接约束也必须落到可观察接口上，例如工具调用参数是否稳定、思维内容是否暴露、token 如何计数、错误如何反馈。

训练集群：通常属于部署层

数据并行、张量并行、流水线并行、检查点容错、GPU 拓扑和训练通信优化，解决的是模型生产问题。除非项目明确把「训练自有模型」纳入交付范围，否则它们不影响工具注册、循环控制、会话状态或插件组合，应归入**仅影响部署**。

若最终只复刻一个使用现有 API 的 Agent，这些研究甚至可以只登记为排除项；理由应写成「不改变当前 Harness 交付边界及运行时契约」，而不是「技术价值低」。排除的是项目相关性，不是研究质量。

推理优化：按是否跨越 API 边界拆分

推理优化也有两层：

判断关键不是算法位于模型内部还是外部，而是结果是否穿过模型 API 边界并要求 Harness 修改。若只改变服务器吞吐而 API 请求、响应和错误语义不变，就不应把实现细节写进 Harness 架构。

一般前沿研究：从概念到可执行产物

一般前沿研究只有经过「概念—机制—产物」转换，才可能升级为直接影响复刻：概念解释问题，机制给出明确算法，产物则表现为 Harness 中的模块、接口、策略或测试。缺少产物时，通常只供背景。

例如，一项关于规划器的论文若确定了具体搜索过程、状态表示和停止条件，并准备在执行循环中实现，它才进入直接影响复刻；如果它只比较多种规划观点而没有可实施约束，则保留在背景索引中。与当前 Agent 边界没有映射的通用研究，只登记排除理由和索引。

一个分类例子

假设原型准备自托管一个经过工具调用微调的模型：

建立可追溯的研究索引

每个进入项目的研究条目至少记录：标题与来源、版本或日期、相关层级、作用对象、证据、预期影响、验证方法及索引号。直接影响复刻的条目还应链接到具体模块、接口或测试；部署类条目应关联延迟、吞吐、成本或可用性指标。

对于无直接关系的材料，只记录索引号、题名、来源和排除理由即可，例如「索引 R-014：仅涉及通用算法，未改变 Harness 行为、接口或部署约束」。研究条目在项目范围或架构决策变化后可以重新分层，但应保留调整记录，避免同一文献在不同阶段被重复当成新证据。

**要点：** 研究相关性由它对复刻、部署或背景解释的实际作用决定；直接复刻项必须落到接口、代码或测试，部署项必须关联运行约束，无关研究只保留索引与排除理由。

本关小结

「项目定位与核心命题」把 DeepSeek Harness 视为连接模型与行动的 Agent 运行时；「系统边界与责任划分」借工具调用划界：模型生成意图，运行时管调度与状态，工具和外部服务提供受控能力。

「三层架构与组合规则」据此建立模型—运行时—能力层的单向依赖，运行时经插件接口装配工具、记忆与规划；「插件化能力面」说明插件可组合替换，并共用宿主循环。

「公开证据与未公开实现边界」要求定位、接口与组合关系以公开文档或源码为据，内部训练、调度和隐藏优化不得倒推；「研究相关性分层」据此划分复刻、部署、背景与排除材料。

**要点：** 本关形成由定位到证据的可追溯框架；下一关据此讨论模型接入与上下文管理。

学习笔记

DeepSeek Harness：定位、边界与整体架构

项目定位与核心命题

模型能力、Agent 行为与外围基础设施

  1. **模型能力决定「能生成什么」。**模型的语言与代码能力、推理质量、知识水平、结构化输出和工具调用能力，来自模型及其推理机制。模型不负责保存完整会话状态，也不等于已经执行行动。
  2. **Agent 行为决定「行动如何形成闭环」。**持续推进任务、调用工具、检查结果、处理失败、遵守权限、适时停止并交付结论等行为，由模型参与决策，但具体流程由 Harness 组织。同一个模型置于不同 Harness 中，可能表现为一次性问答助手，也可能表现为能自主执行、验证和纠错的编码代理。
  3. **外围基础设施决定「行动能在哪里可靠发生」。**模型 API 接入、认证与计费、计算资源、网络、容器或沙箱宿主、持久化设施等会影响成本、延迟、可用性和工具能力，但不等同于模型能力或编排策略。

例如修复解析器在空输入时崩溃：模型根据相关文件和错误信息提出补丁；Harness 检查权限、应用补丁、运行测试并回传失败日志；测试继续失败则按重试限制循环，全部通过后交付结果。模型推理与代码生成属于模型能力，读取文件、执行补丁、运行测试、回传错误和停止条件属于 Harness 编排，测试进程、文件权限、网络与计算资源属于外围基础设施。

**Agent 行为 = f（模型生成能力，Harness 编排，环境约束）**

系统边界与责任划分

系统边界应按五种控制权判断：谁决定下一步、谁执行行动、谁保存状态、谁提供隔离、谁呈现交互。

核心负责决策与编排，插件负责实现能力，外部依赖负责真正产生副作用或提供基础设施。

三组关键边界

dsh 式原型的交付边界

可运行的 dsh 式原型应包含：

三层架构与组合规则

三层架构不是依次执行的三段流程，而是三种职责：**核心抽象接口定义契约，具体能力包实现接口，Bundle 选择并连接实现**。运行时只面向接口编程，厂商实现和部署配置被隔离在组装阶段。

核心抽象接口：声明扩展点

核心层定义 Harness 运行中需要调用什么，而不规定具体实现。扩展点包括：

接口必须精确表达调用边界，而不能只是能力名称目录。新增实现只需遵守既有契约，不必修改代理循环的调度代码。

具体能力包：实现接口

能力包可以实现模型 API 适配器、Shell 工具、文件持久化、受限进程执行等扩展点，并承担三类工作：

  1. 把核心契约翻译成具体协议或 SDK 调用。
  2. 转换外部数据、异常和取消信号，使结果符合核心类型。
  3. 声明配置需求、依赖能力和初始化条件。

能力包应保持可替换性，不应在内部自行创建另一套模型客户端、存储连接或沙箱，也不应绕过接口直接依赖具体兄弟实现。

Bundle：选择、绑定并验证

Bundle 是组合根，负责把扩展点与具体实现连接成可执行的运行时实例图。它需要回答模型槽位使用哪个实现、工具依赖哪个沙箱、会话和存储是否共享实例等问题。

组合规则包括：

插件化能力面

插件化将稳定核心与可变策略分开：核心只依赖明确的能力契约，插件负责具体实现，组合时再注入实例。替换插件不应迫使代理循环、会话或界面重写。

插件协作时，界面将输入与事件交给循环，循环调用模型和工具并将结果或错误回流，同时读写会话状态；会话通过存储保存与恢复。技能插件按需向模型和循环补充工作规程，调度插件横向安排模型请求、工具调用或后台任务。

公开证据与未公开实现边界

架构上「说得通」不等于项目「已经如此」实现。源码中的类名能证明接口存在，文档中的描述能证明公开承诺，第三方教程能帮助理解用法，但这些材料支持的结论不同。