从零运行DeepSeek Harness

约 4652 字大约 16 分钟

AIHarnessDeepSeek

2026-10-08

🤖 说明：本文为个人在学习 DeepSeek Harness 架构过程中的阶段性笔记与测验实录，由 AI 助教配合共同研讨、点对点纠偏与排版整理而成。
本篇导读：本文为 DeepSeek Harness（简称 DSH）架构体系学习的第二阶段沉淀，聚焦于从零开始运行 DSH 与建立基线。深入剖析了 Workspace 作为 Agent“物理与语境现实世界”的核心边界、解耦的 Model Provider/Adapter 接入机制、4 套预设模式（Standard / PTC / Minimal / Creative）背后的组合贡献（Composition）本质，以及评测基准中极简模式（Minimal）与 Harness 变量的深刻辩证关系。

章节主题：第 2 章从零开始运行 DSH（基线建立、Workspace 边界、Provider 接入、Preset 差分与评测哲学）
沉淀说明：系统拆解 DSH 运行基线，厘清 Agent 物理世界的边界、Cordis 微内核的作用域挂载机制、4 套 Preset 的能力面差异，以及 Benchmark 中 Harness 变量的核心考量。

一、Workspace：Agent 的“物理与语境现实世界”

1. 为什么 Workspace 是核心前提？

在进入 DSH Web UI 后，系统强制要求用户先选择或创建 Workspace，Composer 才会进入可用状态。Workspace 决定了 Agent 的以下四大边界：

可感知边界：Agent 能在哪个目录树内搜索、Glob 和读取文件。
可变更边界：Agent 的写操作（新建、覆盖、修改）发生在哪个路径树下。
Shell 工作边界：子进程/命令执行（Bash/Shell）默认以该目录作为 cwd（当前工作目录）。
语境投影边界：Session 的 Context 提取器（如代码摘要、工作树拓扑、Git Status）围绕该目录建立上下文注入。

2. 裸金属 Harness 的安全红线与隔离习惯

与日常使用的 IDE 插件（如 Cursor、Claude Code）相比，DSH 属于白盒微内核 Harness 底座：

受管产品背后内置了完善的防护链条（受控权限弹窗、Git 误删拦截、默认排除路径）。
DSH 运行时默认给予了 Agent 极高的物理级权限（持久 Bash 进程、本地文件系统直读写）。
实战铁律：在接入新模型、编写自定义插件或测试未验证的工作流时，严禁直接在重要生产仓库或宿主机根目录启动。强烈建议使用独立的空目录（如 dsh-lab/），在低价值、易重建的沙盒目录中确认 Tool 的调用行为与权限边界。

二、配置模型：解耦的 Provider 与 Adapter 架构

DSH 并不是绑定固定大模型的 Agent 产品，其底层的模型调用被高度抽象为 Provider / Adapter 契约。

graph LR
    subgraph Core["Agent Runtime"]
        Composer["Composer 编排"]
    end
    subgraph Adapter["Model Adapter 契约层"]
        OpenAI["OpenAI 兼容协议"]
        vLLM["vLLM / 本地部署"]
        Ollama["Ollama / 本地推理"]
        Cloud["DeepSeek / 官方 API"]
    end
    Composer --> OpenAI
    Composer --> vLLM
    Composer --> Ollama
    Composer --> Cloud

本地接入原则：只要服务暴露标准的 OpenAI 兼容接口（如 http://localhost:8000/v1），DSH 就可以无缝桥接本地开源权重（如 DeepSeek-R1-Distill 系列）。
模型配置的持久化：DSH 将 Model Provider 的端点、API Key、默认推理参数与 Preset 状态解耦，可以在不同会话间快速切换不同尺寸或后端的模型。

三、解构 Preset：组合贡献（Composition）而非静态提示词

在传统 Agent 工具中，Preset 往往只是一段预置的 System Prompt 或一个人设角色的替换。但在 DSH（基于 Cordis）体系下，Preset 是一个完整的贡献包（Contribution Bundle）。

1. Preset 贡献的 5 大维度

Persona & System Prompt Sections：分段式提示词片段与动态环境注入钩子。
Tools Set（工具集合）：决定当前 Agent Scope 激活并暴露哪些物理工具。
Agent-local Services：局部服务插件（如会话专属 Memory、Planner 任务规划器）。
Model-facing Presentation：工具与能力呈现给模型的形态（JSON Schema vs Code SDK）。
Runtime Policy：单会话最大循环步数、超时时限、危险命令拦截策略。

2. DSH 官方 4 套预设能力面对照

预设模式 (Preset)	核心定位	工具面 (Tools)	呈现机制 (Presentation)	典型适用场景
Standard	全功能标准助理	全量（Bash、Editor、Search、Subagent）	传统 Function Calling (JSON Schema)	日常通用开发、端到端重构
PTC	程序化工具调用	底层同 Standard	Code Mode SDK (TypeScript 脚本)	批量文件批处理、多步长链路逻辑编排
Minimal	极简极窄基线	仅保留核心最小集（如 Bash + Editor）	紧凑型 JSON Schema / Text	Benchmark 基准评测、低容积小模型验证
Creative	探索与发散型	全量工具 + 发散提示词切片	宽松策略 + 探索型 Prompt	头脑风暴、架构草案生成、原型探索

3. PTC（Programmatic Tool Calling）的降维打击

痛点：传统 Standard 模式在处理批量任务（如“遍历 20 个模块并修改导包”）时，每步都必须经历一次 LLM 生成 JSON -> Harness 执行 -> 返回结果 -> 下一次 LLM 生成，产生极其昂贵的 Round-Trip 延迟和 Token 消耗。
机制突破：PTC 将底层工具封装为代码库 SDK。模型只需在单次输出中编写一段调用该 SDK 的 TypeScript 脚本（含 for 循环、条件分支）。
收益：1 次 LLM 采样，在执行环境中一次性跑完复杂流水线，大幅削减交互延迟与 Token 开销。

四、运行时隔离机制：Host 共享设施 vs Agent Scope 局部挂载

在同一 DSH 进程中开启多个不同 Preset 的会话，系统并不会复制多套完整的 Node 进程或重载插件树，而是通过微内核的作用域派生（Fork Scope）实现高内聚隔离：

graph TD
    subgraph Host["共享 Host Runtime (全局单例)"]
        TR["Tool Registry (底层物理工具池)"]
        MP["Model Route (模型连接池与网络通道)"]
        DB["Persistence (状态持久化与历史存储)"]
        EB["Event Bus & Trace (日志总线与可观测性)"]
    end

    subgraph Scope1["Session 1: Agent Scope (Standard)"]
        P1["标准 Prompt 切片"]
        T1["全量 Tools 挂载"]
    end

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

    subgraph Scope3["Session 3: Agent Scope (Minimal)"]
        P3["极简 Prompt"]
        T3["高危剪枝 (仅 Bash/Editor)"]
    end

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

Host Runtime（厚重共享层）：单例管理物理 I/O、网络套接字、日志采集和底层数据库，避免资源重复初始化。
Agent Scope（轻量隔离层）：每个 Session 只是轻量派生的能力视口（Viewport）。增删会话零额外内存压力，单会话故障绝不污染全局。

五、评测哲学：科学控制变量与 Harness 变量

1. 为什么 Benchmark 选型 Minimal？

官方自动化评测优先采用 Minimal（极简模式），其核心目标是控制变量法：

剥离复杂的 Planner 提示词、冗余的工具集合与多轮自动纠错机制。
排除外部高级 Harness 机制对结果的干扰，观察模型在最原始的“指令遵循 + 基础工具调用”下的直接表现。

2. 评测永恒法则： $\text{Performance} = f(\text{Model}, \text{Harness})$

裸模型的高分不等于业务系统的稳定交付；
评测中 Minimal 的低分模型，在配合 PTC 编排或专属 Prompt 剪裁后，完全可能在真实场景展现极高稳定性。
生产系统落地的永远是“模型与 Harness 的组合工程体”，而非孤独的权重参数。

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

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

测验范围：第 2 章从零开始运行 DSH（环境、Workspace、配置模型、4 套 Preset 对照、Benchmark 选型权衡）
说明：包含学员作答及导师点对点纠偏、架构深度剖析。

【第 1 题：Workspace 的本质与安全边界】

问题背景：在进入 DSH Web UI 后，必须先选定 Workspace，Composer 才会进入可用状态。书中强调“Workspace 是 Agent 的现实世界”。

问题：

为什么说 Workspace 是 Agent 的“现实世界”？它在物理层面和上下文语境层面上分别决定了 Agent 的哪些边界？
为什么对于具备文件读写与命令执行特权的 Agent，首次实验强烈建议在独立的空目录中进行，而不是直接挂载已有生产项目仓库？如果无节制地暴露宿主机路径，可能引发哪些系统级风险？

【我的回答】：
1.1因为Workspace 是 Agent 可以观察、编辑、运行命令的工作目录
1.2
Agent 可以看到哪些文件
Agent 可以修改哪些文件
Shell 默认围绕什么目录工作
一些 Session / Context 如何建立工作语境
2.1因为在低价值、可随时重建的目录中进行可以先确认 Tool 的行为和权限边界。这里不太理解，claude codex这类我都是直接用的。
2.2可能扩大agent权限，导致文件误删误用；上下文增多。这里需要你帮我详细解释

【导师纠偏与深度解析】：
🎯 亮点评定：
第 1 问准确把握了书中的物理边界与语境定义，四条要点罗列非常精准。
第 2 问敏锐捕捉到了“确认 Tool 行为和权限边界”，这正是系统软件工程和安全工程的关键意识。
💡 核心疑惑深度剖析（为什么 Claude/Codex 可以直接用，而 DSH 首次必须隔离？）：
“受管沙盒产品”与“裸金属 Harness”的根本区别：
Claude Code / Codex / Cursor：你平时“直接用”时，厂商背后做了大量的隐形护栏和防御层。例如：有细粒度的权限弹窗（Ask before edit/exec）、内置的忽略列表（保护 .git、.env、密钥文件）、只允许在项目子树内运行的子进程隔离机制。
DSH 是 Harness 开发底座（原生/物理级）：DSH 是一个插件化运行时框架。在首次启动、配置未知模型或自己编写插件/Preset 时，它默认赋予了 Agent 极高的宿主机能力（如持久 Bash）。如果配置的本地小模型（如 7B/14B）产生严重幻觉，或者工具实现未加沙盒校验，它可能会直接执行跨目录甚至破坏性命令。
暴露宿主机路径的系统级风险（深度剖析）：
路径遍历与脱逸（Path Traversal）：若无边界限制，模型执行 cat ../../.ssh/id_rsa 或修改 ~/.bashrc 会直接危害系统安全。
Git 状态破坏与不可逆污染：直接挂载生产仓库时，如果 Agent 随意执行 git clean -fdx 或 git reset --hard，未提交的工作区现场将被永久抹除。
无限上下文膨胀与检索污染：若直接在根目录或杂乱仓库启动，文件扫描工具（如 Glob/Grep）会把 node_modules、大型二进制文件、虚拟环境全部纳入索引，直接让 Context Window 爆仓瘫痪。

【第 2 题：Preset 的本质——提示词还是组合贡献（Composition）？】

问题背景：很多初学者常把 Agent 的“预设（Preset）”简单理解为“替换一段 System Prompt（或者换个角色人设）”。但 DSH 的 Preset 机制从架构上看远比这深刻。

问题：

Preset 究竟向当前 Session 的 Agent Scope 贡献了哪些维度的要素？（仅仅是提示词吗？）
结合 Standard（标准模式） 与 PTC 模式 的对比，解释为什么原书强调：“能力是否存在”与“能力如何呈现给模型（model-facing presentation）”是完全不同的两件事？PTC 模式通过改变呈现方式带来了什么优势？

【我的回答】：
1.工具、提示词、能力。需要详细的介绍
2.1PTC 没有重新实现一套工具，而是在已有能力上改变了 model-facing presentation（面向模型的呈现状态）。
2.2Harness 既决定模型可以使用什么，也决定模型以什么形式看到这些能力。

【导师纠偏与深度解析】：
🎯 亮点评定：
第 2 问精确提炼出核心命题：“PTC 没有重写工具，改变的是 model-facing presentation”。这是吃透 DSH 架构的一大分水岭！
💡 维度展开：Preset 的“组合贡献”究竟包含什么？：在 DSH 架构中，Preset 决不能等同于“System Prompt 模板”。在 Cordis 体系下，Preset 是一个贡献包（Contribution Bundle），向当前 Agent Scope 注入 5 大维度的要素：
Persona & Prompt Sections：角色的系统提示词片段，以及针对特定场景的动态上下文注入规则（何时注入工作区摘要、何时注入规则约束）。
Tools（工具集合）：决定当前会话中哪些 Tool 对模型可见、哪些被隐藏。
Agent-local Services（会话局部服务）：例如会话专用的 Memory 缓存、局部计划器（Planner）、子任务分发器（Subagent Dispatcher）。
Model-facing Presentation（呈现层转换器）：工具如何包装给模型（JSON Schema 方式？还是代码 SDK 方式？）。
Runtime Policy（运行时策略）：该会话允许的最大单步执行轮次、错误重试策略、是否允许执行危险命令等。
💡 PTC 模式的核心优势（Programmatic Tool Calling）：
传统 Standard 模式（JSON Tool Call）：模型每调一个工具，必须生成一段 JSON -> Harness 解析执行 -> 回传结果给模型 -> 模型看一眼再发下一个 JSON。如果要批量修改 10 个文件，必须往返 10 个 LLM Turn，延迟高、易中断、Token 消耗极大。
PTC 模式（Code Mode SDK 呈现）：底层工具（读文件、写文件、Bash）完全没变，但向模型暴露的是一个 TypeScript SDK。模型直接写一段 TS 脚本，在代码里写 for 循环、if/else、并发请求。只消耗 1 次 LLM 调用，在沙盒运行时内一次性流水线式完成多步编排！极大地降低了调用延迟和 Token 成本。

【第 3 题：Host Runtime 共享基础设施 vs 会话级 Agent Scope 隔离】

问题背景：在同一个 DSH 实例中，我们可以同时打开 4 个 Session，分别挂载 Standard、PTC、Minimal 和 Creative 预设。

问题：

系统是否为每个 Session 都完整复制了一套全新的插件树和底层运行时？
请说明底层的 共享 Host Runtime 与各 Session 自有的 Agent Scope 各自负责什么？这种“共享底层 + 局部挂载”的分层设计带来了哪些工程和架构上的好处？

【我的回答】：
这两题都不太理解

【导师纠偏与深度解析】：
别担心，这是 Cordis / 微内核架构最精妙但也最抽象的一处设计！通过以下拆解，你会瞬间豁然开朗：
1. 答案：绝对没有复制完整的插件树！ 如果每个 Session 都要启动一个独立的 Node 进程、重复加载几十个 npm 插件包、初始化独立的数据库连接，内存和 CPU 很快就会耗尽。DSH 采用的是单 Host 进程内部的“作用域隔离（Scope Isolation）”。
2. 共享 Host Runtime vs Agent Scope 的职责分工：
┌───────────────────────────────────────────────────────────┐
│                  共享 Host Runtime (宿主全局)             │
│  - Tool Registry (底层原生工具库)                         │
│  - Model Route (LLM 提供方连接池、vLLM/OpenAI 客户端)      │
│  - Persistence (SQLite / 文件系统持久化、历史记录存储)    │
│  - Event Bus (事件总线、全局日志 Trace 监控)              │
└──────────────┬────────────────────────────┬───────────────┘
               │ 派生 (Fork Scope)          │ 派生 (Fork Scope)
               ▼                            ▼
┌─────────────────────────────┐ ┌─────────────────────────────┐
│  Session 1: Agent Scope     │ │  Session 2: Agent Scope     │
│  (挂载 Minimal Preset)      │ │  (挂载 PTC Preset)          │
│  - 仅暴露: Bash + Editor   │ │  - 暴露: Code Mode SDK      │
│  - 精简 Prompt 节          │ │  - TypeScript 编排运行时   │
│  - 独占的 Session 历史状态  │ │  - 独占的 Session 历史状态  │
└─────────────────────────────┘ └─────────────────────────────┘
底层 Host Runtime（做繁重的通用基础设施）：负责管理与大模型服务器的持久网络连接、底层文件的真实物理操作接口、日志与 Trace 的落盘、数据库连接池。这些在所有会话之间单例共享。
会话级 Agent Scope（做轻量的能力遮罩与组合）：每个 Session 只是 Host 上派生出来的一个轻量级上下文“视口”。它不重复制造工具，只决定“当前这个窗口允许谁进场”（如 Session 1 遮蔽所有工具只留 Bash，Session 2 挂载 PTC 转换器）。
3. 架构收益：
极低开销：创建新 Session 仅耗时几毫秒，内存占用几乎忽略不计。
能力复用与解耦：底层写好一个强大的 Tool，可以通过不同 Scope 随意赋权给不同 Agent，无需重写。
多任务隔离：A 会话的 Agent 崩溃或死循环，不会影响 B 会话的正常执行。

【第 4 题：Agent Benchmark 的评测哲学与 Harness 变量】

问题背景：官方 BENCHMARK.md 在做自动化评测时，选择了 Python SDK 中 jsonrpc-agent 的 Minimal（极简模式） 变体。

问题：

官方 Benchmark 为什么倾向于选择极简模式（Minimal），而不是能力更全面的 Standard 模式？其背后的科学控制变量考量是什么？
有人认为：“在 Minimal 下测出来的分数就是模型的真实能力，与其他因素无关。”请反驳这一观点。为什么说 Agent 的最终表现永远是 Model 与 Harness 的“共同作用结果”？

【我的回答】：
1.它减少了额外工具、上下文和运行时策略，让实验者更容易观察模型在相对简单条件下的任务表现。
2.只要模型运行在 Agent Runtime 中，最终结果就一定是 Model 与 Harness 共同作用的结果：
同一个模型在 Standard 下表现更好，提升可能来自更丰富的工具、规划或上下文能力；
反过来，如果复杂的 Harness 引入了多余的 Tool Call、过量的 Context 或更长的执行链，性能下降也不能简单归因于模型。

【导师纠偏与深度解析】：
🎯 亮点评定：
满分表现！第 1 问和第 2 问逻辑严密、辩证清晰，直击系统工程评测的核心痛点！
💡 进阶视角升华（工程实战启示）：
不要被“跑分神话”绑架：许多人看到某开源模型在某 Benchmark 上拿了高分，但在自己的业务 Agent 里一跑就崩；或者反过来，认为某个小模型跑分低就一无是处。
匹配度（Harness-Model Fit）：不同模型对 Prompt 的指令遵循习惯、对 Tool Schema 的冗余容忍度大相径庭。一个在极简 Minimal 下表现平庸的模型，可能在配上 PTC（代码编排）或专属 Prompt 切片的 Harness 中爆发惊人战斗力。评测与生产落地的永远是“系统”，而非裸模型。