🤖 说明：本文为个人在学习 DeepSeek Harness 架构过程中的阶段性笔记与测验实录，由 AI 助教配合共同研讨、点对点纠偏与排版整理而成。

本篇导读：本文为 DeepSeek Harness（简称 DSH）架构体系学习的第三阶段沉淀，核心聚焦于 Preset（预设）、Scope（作用域）、Host Plane（宿主层） 与 Agent Plane（Agent 会话层） 的解耦设计。深入剖析了 PTC 模式中“能力（Capability）与呈现（Presentation）彻底解耦”的工程精髓，以及 Minimal 极简模式下“面向模型的薄 Harness 与面向宿主的厚治理”的辩证统一，并附带本阶段的架构测验与深度复盘。

---

一、Preset 的本质：不是独立 Agent，而是动态能力组合

在初学 DSH 时，很容易产生一个直觉误区：把 Standard、PTC、Minimal 和 Creative 4 种预设理解为“4 个各自独立运行的 Agent 进程”。

但在 DSH 的工程架构中，它们并不是 4 个彼此独立的 Agent，而是在同一个 DSH Runtime 中，通过不同的能力组合形成的 4 种 Agent 形态。

graph TD
    subgraph Host["Host Plane (宿主基础设施常驻单例)"]
        TR["Shared Tool Registry (全局工具实现)"]
        MR["Model Route (模型调用路由)"]
        DB["Persistence (持久化存储)"]
        SB["Sandbox & Security (沙箱与执行治理)"]
    end

    subgraph Scope1["Session 1: Agent Scope (Standard)"]
        P1["标准 Prompt 切片"]
        T1["Native JSON Tools 暴露"]
    end

    subgraph Scope2["Session 2: Agent Scope (PTC)"]
        P2["PTC 系统规约"]
        T2["Code SDK (TypeScript) 呈现层"]
    end

    subgraph Scope3["Session 3: Agent Scope (Minimal)"]
        P3["极简 Prompt (无运行时注入)"]
        T3["高危剪枝 (最小工具暴露)"]
    end

    Host --> Scope1
    Host --> Scope2
    Host --> Scope3

• 全量独立进程模式（Anti-Pattern）：若每个会话都全量冷启动，会导致数据库连接、沙箱运行时、模型路由被重复创建，内存开销巨大，且全局安全与审计策略难以统一；
• 纯全局单例模式（Anti-Pattern）：若所有能力都在全局扁平化注册，会话间将毫无隔离，Session A 注入的特定工具或 Prompt 切片会直接污染 Session B；
• DSH 的折中解：Host 进程常驻持有进程单例的基础设施；当 Session 创建时，系统派生出一个独立的 ScopeContext（作用域上下文）。Preset 提供的能力只挂载在局部 Scope 中，会话结束即行销毁。

---

二、架构分层：Host Plane 与 Agent Plane

理解 DSH 组合设计的关键，在于划清两层边界：

维度	Host Plane（宿主层）	Agent Plane（Agent 会话层）
关注点	跨 Session 共享的基础设施与系统治理	当前会话的个性化形态与面向模型的呈现
典型组件	共享工具注册中心、模型路由、持久化存储、沙箱执行器、审批策略	角色人设（Persona）、Prompt 切片、工具呈现（Presentation）、会话局部状态
生命周期	进程级常驻（Process-singleton）	会话级绑定，随 Session 创建与销毁
设计哲学	底座稳定、治理集中、物理隔离	按需拼装、动态组合、安全受限

💡 架构判断黄金法则：
“模型看见什么（Presentation/View）”属于 Agent Plane；“系统怎么执行（Infrastructure/Provider）”属于 Host Plane。

• 某个 Session 要限制为只读模式：在 Agent Plane 调整工具呈现（遮蔽写工具）；
• 系统将执行环境从本地迁至 Docker 容器：在 Host Plane 替换底层 Sandbox Provider。

---

三、PTC 模式的“能力缝”：Capability ≠ Presentation

PTC（Programmatic Tool Calling，代码模式）常被误解为“只是比 Standard 多了一个运行代码的工具”。其深层的架构创新在于将能力本身（Capability）与呈现形态（Presentation）彻底解耦。

graph LR
    subgraph Capability["Capability (能力实现层 - Host)"]
        C1["文件读写 (fs)"]
        C2["网络检索 (fetch/web)"]
        C3["命令执行 (bash)"]
    end

    subgraph Presentation["Presentation (模型呈现层 - Agent)"]
        P_Standard["Standard 模式: 暴露独立的 JSON Tool Schemas"]
        P_PTC["PTC 模式: 封装为强类型的 TypeScript SDK"]
    end

    Capability --> P_Standard
    Capability --> P_PTC

1. 传统 Native 模式 vs PTC 模式

• Native 模式（单步往返）：模型每一步生成一个 JSON 工具调用，等待 Harness 执行并回传结果，再根据结果思考下一步（$ ext{LLM} \leftrightarrow ext{Tool A} \leftrightarrow ext{LLM} \leftrightarrow ext{Tool B}$），往返轮次（Round-trip）长、中间状态对 Token 消耗大。
• PTC 模式（编排聚合）：模型将工具视为 TypeScript 库，编写一段包含循环、条件判断和并行处理（Promise.all）的完整程序，一次性提交给沙箱执行，仅将最终聚合结果返回给 LLM。

2. PTC 的工程权衡（Trade-off）

• 优势：大幅压减往返延迟与上下文冗余，适合多步骤、确定性高的批量处理流程；
• 劣势与局限：
  1. 对模型代码生成准确度依赖极高，脚本语法错误会引发沙箱中断；
  2. 剥夺了单步执行过程中的实时推理反馈，在探索性未知的模糊任务中缺乏灵活性；
  3. 对于简单的单步工具调用，拉起代码运行环境会引入不必要的延迟与 Token 开销。

---

四、Minimal 模式：极简 Harness 与不可妥协的安全底线

Minimal 预设明确声明了 includeRuntimeContext: false，关闭了上下文自动压缩与引导切片。

1. 学术科研诉求（科学控制变量）：
   剥离 Harness 的强大辅助支架（Planner、压缩机制、丰富工具），以高透明度、零干扰的环境客观评估基座模型自身的推理与指令遵循能力。
2. 安全治理底线（薄引导，厚安全）：
   Minimal 暴露给模型的能力虽然极度精简，但底层的 Host Plane 执行边界和审批沙箱依然全局生效。
   “薄”指的是面向模型的人格引导与辅助逻辑（Agent Plane），而“厚”指的是面向宿主操作系统的执行物理护栏（Host Plane）。系统的安全性绝不能建立在“模型自己很乖”的假设上，必须由不可穿透的宿主底层进行强制兜底。

---

五、实战阶段测验复盘（Q&A）

点击展开：第 3 章 阶段架构测验与深度纠偏实录

【第 1 题：Preset 与独立 Agent 的本质区别】

问题背景：
初学者常常把 Standard、PTC、Minimal、Creative 理解为“4 个独立的 Agent 运行时”。但 DSH 的设计明确指出它们是在同一个 DSH Runtime 中按需动态组合的能力集合。

问题：

1. 如果每个会话（Session）都以独立的完整 Agent 实例方式冷启动，系统在资源和治理层面会面临哪些弊端？
2. DSH 采用的“Host 进程常驻 + Session 动态挂载 Preset”的中间路线是如何在共享基础设施与会话专属行为之间做权衡的？请结合 ScopeContext 简述其隔离机制。

【我的回答】：

1.1 如果每个 Session 都完整启动一个独立 Agent 实例，系统需要为每个会话重复初始化模型路由（Model Route）、持久化存储连接（Persistence）、工具注册表（Tool Registry）、沙箱执行器以及子 Agent 管理器等基础设施。这会导致内存与 CPU 资源开销极大，无法支撑高并发会话；同时各个实例各自为战，全局的安全审计策略、限流与统一治理变得非常碎片化。

1.2

• 另一种极端是所有能力扁平堆在全局，Session A 新增的特定 Tool 或临时 Prompt 会直接污染 Session B。
• DSH 的中间路线是：Host 进程常驻并持有 process-singleton（进程单例）的基础设施，不随 Session 重复创建。
• 当某个 Session 创建时，系统派生出一个独立的 ScopeContext（作用域上下文）。Preset 提供的提示词（Persona/Prompt Sections）、工具呈现与局部状态只挂载并注册在这个局部作用域中。
• 这样既复用了底层的昂贵底座，又严格保证了会话级能力“属于当前 Scope、只对当前 Scope 可见、跟随当前 Scope 销毁”，互不污染。

【导师纠偏与深度解析】：

🎯 亮点评定：

• 回答非常精准且有深度！准确抓住了“全局单例污染”与“全量冷启开销”这两个极端反模式，并透彻阐明了 DSH 中间路线的精髓。
• 对 ScopeContext 隔离三要素（生命周期归属、可见性与隔离边界、销毁释放）的表述与原书架构哲学高度契合。

💡 架构深度补充（Cordis 的上下文树机制）：

• 在底层 Cordis 微内核中，ScopeContext 实际上是一棵作用域树（Context Tree）。Host Plane 处于根节点（Root Context），持有共享的单例 Service（如 SQLite 连接池、vLLM Client 等）；
• 每个 Session 则是 Root Context 派生出的子作用域（Child Scope）。子作用域能够自顶向下“透视”并消费父级服务，但子作用域中通过 Preset 注册的组件默认只对当前子树生效，无法向上回写逆向污染父上下文。这种单向可见性保证了高并发多 Agent 的绝对隔离。

---

【第 2 题：Host Plane 与 Agent Plane 的职责分工与架构设计】

问题背景：
在 DSH 的组合设计中，能力被解耦到 Host Plane 和 Agent Plane 两层。官方强调：“不要去数 Standard 到底挂了多少个插件，而要看这项能力属于谁、谁可以使用它”。

问题：

1. 请分别列举 Host Plane 和 Agent Plane 各自的核心职责（至少各列举 3 种典型能力/组件）。
2. 请针对以下两个工程需求做出正确的架构分层决策，并说明原因：
   • 需求 A：某个 Session 想要临时禁用“写文件”权限，仅允许只读分析。应该在 Host Plane 还是 Agent Plane 调整？为什么？
   • 需求 B：出于合规要求，系统需要把所有文件读写和命令执行从本地环境迁移到受限的远端 Docker 容器或沙箱中。应该在 Host Plane 还是 Agent Plane 调整？为什么？

【我的回答】：

2.1

• Host Plane（宿主层）：负责跨 Session 共享的基础设施与系统治理。典型组件包括：
  1. Shared Tool Registry（全局工具实现与注册中心）
  2. Model Route（大模型调用路由与连接池）
  3. Persistence（持久化存储与会话历史数据库）
  4. Sandbox / Approval Provider（沙箱隔离与危险命令审批策略）
• Agent Plane（会话层）：负责当前会话的个性化组合与向模型的呈现。典型组件包括：
  1. Persona & Prompt Sections（身份人设与动态提示词切片）
  2. Tool Presentation / Contribution（决定哪些工具暴露给当前模型、以何种形式暴露）
  3. Agent-local Services（会话私有状态，如 Plan/Goal 运行态）

2.2

• 需求 A 应在 Agent Plane 调整：
  因为底层的“文件写入能力”本身并未失效，需求只是针对“当前特定会话”的模型权限进行收缩。只需在当前 Session 的 Agent Scope 中修改工具呈现（遮蔽写文件工具或将其设为只读），不应该动底层全局的文件系统 Provider，否则会波及其他需要写文件的正常会话。
• 需求 B 应在 Host Plane 调整：
  因为该需求改变的是“整个系统如何执行文件和命令操作”的底层基础设施与安全物理边界，属于共享底座的变更。需要替换 Host Plane 的 Filesystem Provider 和 Sandbox Execution Provider，将系统调用路由至 Docker 容器。各 Session 无需关心底层是在本地还是在 Docker 中运行。

【导师纠偏与深度解析】：

🎯 亮点评定：

• 满分答卷！对“需求 A”和“需求 B”的归因切中了现代软件架构的精髓：“模型看见什么（Presentation/View）”属于 Agent Plane，“系统怎么执行（Infrastructure/Provider）”属于 Host Plane。

💡 实战工程避坑警示：

• 很多初学者在做 Agent 二开时容易犯一个典型错误：为了给某个特定 Agent 禁命令，去硬编码改底层的 Bash 工具源码（污染了 Host Plane）；或者为了换 Docker 沙箱，在 System Prompt 里反复提醒模型“请注意你在容器里”（企图用 Agent Plane 解决 Host Plane 的安全隔离），这种 Prompt 级防御极易被越狱绕过。严格划清这两层是工业级 Agent 系统的基本素养。

---

【第 3 题：PTC 模式的“能力缝”（Capability Seam）与架构权衡】

问题背景：
很多人把 PTC（Programmatic Tool Calling）简单等同于“Standard 模式额外增加了一个 run_code 工具”。但在 DSH 架构中，PTC 的核心Seam（能力缝）在于 Capability（能力本身）与 Presentation（呈现方式）的彻底解耦。

问题：

1. 什么是“Capability ≠ Presentation”？底层同一个 Tool Registry，在 Native Tool Calling 和 PTC 模式下分别是如何向模型呈现并被调用的？
2. 相比传统 Native 模式的多轮交互，PTC 试图通过什么手段减少往返轮次（Round-trip）？为什么官方注释明确说明“减少 Round-trip 只是设计目标，并非无条件性能保证”？在哪些场景下 PTC 可能会表现欠佳甚至适得其反？

【我的回答】：

3.1

• Capability ≠ Presentation 是指：系统底层具备什么能力（功能实现），与模型以什么形式看见并调用该能力，是完全解耦的两个独立关注点。
• 底层 Tool Registry（文件读写、网页搜索、Bash 执行等）是完全同一套代码实现；
• Native Tool Calling 模式：以 JSON Tool Schema 的形式向模型暴露一个个独立函数。模型每次生成一个 JSON 工具调用，等待 Harness 执行并回传结果后，再做下一轮决策（LLM -> Tool A -> LLM -> Tool B）。
• PTC 模式：通过 ToolPresentation (mode: code) 将这套工具转换封装为带类型的 TypeScript SDK。模型看到的不是孤立的 JSON 描述，而是一个可编程式调用的类库。

3.2

• 减少 Round-trip 的手段：模型通过编写一段完整的 TypeScript 程序（支持循环、条件分支、Promise.all 并行操作等），把多步确定性的工具调用和中间数据过滤逻辑全部打包进脚本，一次性提交给 run_code 执行，最终只把聚合后的核心结果返回给 LLM，把原本 5~10 轮的往返交互压缩为 1 轮。
• 为什么不是无条件性能保证：
  1. 代码生成准确率受限：如果模型代码能力不强，编写的 TS 脚本存在语法错误、类型不匹配或异常处理缺失，整个程序会在沙盒中报错崩溃，反而增加了排错重试的往返轮次。
  2. 丢失单步动态推理反馈：在高度不确定性、探索性的复杂任务中，模型往往需要根据 Tool A 返回的具体内容临时调整下一步策略；如果一次性全写进脚本，模型就失去了“边看边想”的灵活性。
  3. 小任务额外开销：对于只调一次工具的简单任务，生成一段完整的 TS 代码并拉起代码沙盒执行，其 Token 消耗和执行延迟反而高于直接发一个 JSON 调用。

【导师纠偏与深度解析】：

🎯 亮点评定：

• 思考极其全面！特别是在第 2 问中指出了“丢失单步动态推理反馈”和“小任务冷启开销”，这体现了非常优秀的工程权衡（Trade-off）思维。

💡 关键机制补充（Cordis 的 PENDING 依赖状态）：

• PTC 在工程落地时还有一个极其优雅的设计：PTC 的代码执行依赖 Host 侧的 codeRuntime Service。
• 很多传统架构如果缺少某个系统依赖，往往会在模型生成代码并调用 run_code 的瞬间抛出 Unhandled Exception 导致整个对话爆掉。
• 而在 Cordis 架构中，如果检测到宿主未配置 codeRuntime，PTC 插件在初始化阶段就会主动停留在 PENDING 状态挂起，直到对应能力被注入。这种声明式依赖治理让系统的运行时弹性大大增强。

---

【第 4 题：Minimal 模式的薄 Harness 与安全治理底线】

问题背景：
Minimal 预设明确声明了 includeRuntimeContext: false，不启用上下文压缩，剔除了绝大部分辅助提示词与工具。

问题：

1. DSH 设计 Minimal 预设的核心诉求是什么？它与直接使用“未经 Harness 包装的裸模型 API”有何本质异同？
2. 既然 Minimal 暴露给模型的能力非常少，为什么底层的执行边界和沙箱策略依然必须由 Host Plane 强行保持？这体现了 Harness 架构设计的什么安全准则？

【我的回答】：

4.1

• 核心诉求：Minimal 的目标不是做一个功能残缺的弱版 Standard，而是将 Harness 支架层压到极致薄（剔除复杂的引导提示词、关闭上下文自动压缩、最小化工具集），为基准评测和学术研究提供一个极高透明度的纯粹环境，以便准确观测基座模型在缺少外力辅助时的原始推理与代码能力。
• 与裸模型 API 的异同：
  • 相同点：面向模型呈现的上下文极其纯净，没有复杂的系统预设、工作流规则干扰。
  • 本质不同：裸模型 API 是单纯的文本补全/对话接口，没有执行闭环；而 Minimal 依然运行在 DSH Runtime 中，具备完整的 Tool 执行循环、标准输入输出协议以及宿主环境的托管生命周期。

4.2

• 为什么 Host Plane 安全底线必须保持：
  • 即使 Minimal 暴露的工具极少（例如只保留了基础 Shell 或文件读写），只要模型具备与物理系统交互的能力，它就有可能因为幻觉生成毁灭性命令（如 rm -rf / 或越权读取敏感文件）。
  • “薄”指的是面向模型的人格引导与辅助逻辑（Agent Plane），而“厚”指的是面向宿主系统的执行安全边界（Host Plane）。
• 体现的安全准则：
  • 安全防御纵深（Defense in Depth）与不可妥协的底座治理：系统的安全性绝不能寄希望于“模型自己很乖”或“给模型少暴露工具”，而必须由不可穿透的宿主沙箱和审批策略（Approval/Sandbox Provider）进行强制物理级托底。Agent 可以千变万化，但 Host 的安全底线坚如磐石。

【导师纠偏与深度解析】：

🎯 亮点评定：

• “薄的是面向模型的引导 Harness，厚的是宿主层的安全控制底座”——总结得极具穿透力！精准点明了 Minimal 模式的哲学内涵。

💡 终极升华（为什么学术界 Benchmark 偏爱 Minimal，而工业界落地偏爱 Standard/PTC）：

• 学术界（评测模型智力）：必须用 Minimal 控制变量。如果使用了 Standard，模型拿了高分，你很难分清是模型本身变聪明了，还是 Standard 里的上下文压缩与 Prompt 工程起了决定性作用。
• 工业界（交付业务价值）：必须用 Standard 或 PTC。业务场景不在乎“模型裸考多少分”，而在乎如何用最少的 Token、最低的延迟、最稳健的容错机制把事情办成。这就是为什么 DSH 要在同一个 Runtime 中同时容纳这两种截然不同的预设形态。

贡献者: Withnoidea

上一页从零运行DeepSeek Harness

下一页拆解DSH的“一切皆插件”原则（下）