如何 100% 本地运行 DeepSeek Agent Harness

将 DeepSeek Harness 与 Ollama 结合使用，可以实现 0 美元的 API 账单、完全的数据隐私保护和完整的自主执行能力。

自主软件开发的范式转变

软件工程领域正在经历一场根本性变革，人工智能与代码库的交互方式正在被重新定义。过去多年间，机器学习模型主要扮演被动的自动补全引擎，或者是嵌入在集成开发环境（IDE）中的局部聊天助手。自主编码智能体（Agent）改变了这一切：它能检查本地文件树、执行 shell 命令、重构复杂代码库、运行多步骤的诊断循环，从而重塑开发者的工作流。

不过，早期的商业实现，最有代表性的是 Anthropic 的 Claude Code 和 OpenAI 的 Codex CLI，都把这些自主执行循环绑定在封闭的专有云端模型之上。

DeepSeek Agent Harness（DSH）提供了另一条路径：一个开源的、插件优先的框架，明确把推理引擎与操作工具链解耦。这个范式的核心可以用一个简洁的结构方程表达：

Agent = Model + Harness（智能体 = 模型 + Harness）

在这个框架中，大语言模型只是推理内核，Harness 提供周边基础设施：工具注册表、上下文管理算法、文件系统接口和执行状态循环。DeepSeek Harness 以开源的 MIT 许可证发布，把上述组件隔离为可互换的插件，统一构建在一个中央应用内核之上。

这种模块化架构让软件开发团队能够：

• 消除云端 API 订阅成本；
• 通过物理隔离（air-gapped）的本地执行保护知识产权；
• 将 Harness 与 Ollama 等本地推理引擎配对使用。

把 Qwen2.5-Coder 等开源权重模型与本地托管的 Harness 实例结合起来，开发者可以在本地硬件上完全离线部署一套功能齐全的智能体自动化系统。

DeepSeek Agent Harness 与商业智能体的对比：架构能力分析

架构能力雷达图（Architectural Capability Radar）从架构自主性、模块化、控制能力和成本这几个维度比较工具，关注的是 Harness 层的结构属性，而不是底层基础模型的原始推理能力。

下面给出技术论证和详细分解，说明为什么 DeepSeek Agent Harness（DSH）在这些维度上达到满分，而 Claude Code 和 OpenAI Codex 等封闭式 SaaS 解决方案的得分明显更低。

1. 开源与模块化

• DeepSeek Harness（100/100）：以宽松的 MIT 许可证发布，构建在模块化的 Cordis 引擎架构之上。开发者可以检查、fork、修改代码，并向执行生命周期的任何环节（提示词组装、工具 schema、沙箱、响应解析）注入自定义插件。

• Claude Code 与 Codex（15–25/100）：专有的闭源 SaaS 生态系统。开发者无法修改底层智能体 Harness，无法检查内部提示词流水线，无法自定义安全边界，也无法在自托管基础设施上运行 Harness 引擎。

2. 数据隐私与物理隔离安全

• DeepSeek Harness（100/100）：与本地 Ollama 模型引擎配对时，可以 100% 在本地运行并实现物理隔离。源代码、文件树、诊断日志和终端输出永远不会离开本地机器或内部网络，能满足严格的企业合规标准（SOC2、HIPAA、国防级知识产权约束）。

• Claude Code 与 Codex（30/100）：需要通过外部互联网连接，把完整的文件上下文、代码差异（diff）和 shell 执行输出发送到 Anthropic 或 OpenAI 的云端 API 端点。对实行无遥测政策的企业代码库来说，这是明显的合规障碍。

3. 成本效率（零 API 费用）

• DeepSeek Harness（100/100）：与本地模型（比如通过 Ollama 运行的 qwen2.5-coder 或 devstral）配对时，边际运营 API 成本为 0.00 美元，只需支付本地硬件和电费。

• Claude Code 与 Codex（20/100）：API 消耗成本高昂。自主智能体循环会在多轮交互中反复重新评估大型上下文窗口、工具输出和诊断跟踪，单次复杂的重构会话就可能消耗数十万 token，产生可观的按量计费或月度 API 账单。

4. 模型灵活性

• DeepSeek Harness（100/100）：完全模型无关（model-agnostic）。可以随时通过标准 API 配置参数切换执行后端，在本地 Ollama 端点、DeepSeek V3/R1 API、OpenAI GPT-4o 或 Anthropic Claude 模型之间自由选择。

• Claude Code 与 Codex（15–20/100）：严格的供应商锁定。Claude Code 锁定在 Anthropic 的 Claude 3.5/3.7 模型上，Codex/Copilot 工具则绑定在 OpenAI 的托管端点模型上。

5. 状态回滚与分支

• DeepSeek Harness（95/100）：采用仅追加（append-only）的状态树和事件驱动的会话持久化机制（ctx.sessions）。dsh-turn-rewind 等扩展允许开发者"时间旅行"回到任何之前的执行轮次，撤销多文件编辑，并在不丢失聊天历史的情况下对执行路径进行分支。

• Claude Code 与 Codex（35–40/100）：只提供标准的线性聊天/终端历史日志。要撤销一次错误的多文件编辑或终端诊断循环，需要手动做 Git 清理（git restore），或者从头开始一个新会话。

Harness 架构 vs. 模型智能

必须区分 Harness（智能体执行框架）和 LLM（底层大脑）：

• 雷达图衡量的是 Harness 能力：开放性、成本控制、隐私、状态分支和供应商中立性。DSH 在这些维度上占主导，因为它把 100% 的所有权交给开发者。

• 模型推理是另一回事：当 DSH 连接到高推理能力的模型（比如通过 API 连接的 DeepSeek-R1 或 Claude 3.5 Sonnet）时，它能同时获得开放的架构控制和顶级的推理性能。

深入 DeepSeek Harness：插件优先架构与 Cordis 引擎

DeepSeek Harness 与传统编码助手的本质区别在于底层编排框架。传统方案往往采用硬编码的单体式执行循环，工具调用、上下文截断和流式 API 被僵化地耦合在一起；DSH 则把运行时构建在 Cordis 框架之上。

Cordis 充当一个可扩展的服务仓库，围绕定义明确的上下文键组织，包括：

• ctx.llm：推理处理；
• ctx.tools：工具注册表管理；
• ctx.sessions：状态持久化；
• ctx.execution：沙箱操作。

插件通过显式的注入属性（inject）声明自己需要的依赖项，这保证服务只在前置条件满足时才激活。这种控制反转（IoC）设计让开发者可以在不改动静态用户界面的前提下替换模型提供商、不 fork 代码库就能更换上下文注入策略，或者附加自定义的子智能体委派驱动程序。

Cordis 内核的另一个关键技术特性是可逆插件效应。当插件在运行时被动态卸载或热插拔时，框架会自动注销关联的事件监听器、移除注入的工具 schema、拆除提示词附加内容。这种架构能有效防止长时间运行的工程会话中出现内存泄漏、残留子进程和上下文污染。

DeepSeek Agent Harness（DSH）：执行模式与配置档

DeepSeek Agent Harness（DSH）采用由 Cordis 内核驱动的配置档驱动（profile-driven）运行时系统。不同任务在速度、工具访问、自主性和安全性之间需要不同的权衡，因此 DSH 暴露了四种核心操作模式。每种模式都会动态调整 Harness 状态（ctx），启用或限制工具、系统提示词结构和上下文日志流水线。

1. 标准模式（dsh / dsh --profile standard）

架构与机制

标准模式是用于端到端软件工程的主要交互式配置档。在标准模式下初始化时，DSH 会注入一个多层级上下文窗口，其中包括：

• 持久的 bash 执行终端状态（ctx.shell）；
• 精确的文件读取和原子替换工具（str_replace_editor）；
• 分层任务规划和子智能体生成能力（ctx.agents.delegate）；
• 动态网页/文档搜索能力。

执行流程

1. 目标摄取：解析用户提示词并分解为子目标。
2. 上下文组装：把工作区文件树、当前 Git 状态和系统提示词聚合到前缀 KV 缓存中。
3. 推理循环：模型输出结构化的 JSON 工具调用（例如列出文件、读取代码、执行测试套件）。
4. 诊断反馈循环：检查终端堆栈跟踪或测试失败信息，递归地自动修正代码，直到测试通过。

适用场景

• 实现跨前端和后端的复杂多文件功能；
• 在大型代码库中调试单元/集成测试失败；
• 探索性的代码库导航和自动化架构重构。

2. 代码模式（dsh code / dsh --profile code）

架构与机制

代码模式把 DSH 从交互式终端智能体转变为程序化代码合成流水线。它剥离了冗长的智能体循环、子智能体委派和交互式用户提示，改为通过 TypeScript/Python SDK 直接输出可执行脚本。

代码模式不采取逐轮行动的方式，而是让底层模型编写单个可执行的编排脚本，一次性完成多文件编辑。

主要优势

• Token 效率：通过减少智能体上下文更替，最大限度降低往返 token 开销；
• 可预测的输出：很适合集成到现有的开发者脚本和自动化工具流水线中。

适用场景

• 一次性代码转换（例如将 JavaScript 文件批量转换为 TypeScript）；
• 需要确定性执行的 CI/CD 流水线自动化；
• 通过 CLI 脚本进行程序化代码生成。

3. 最小模式（dsh minimal / dsh --profile minimal）

架构与机制

最小模式是一种安全强化、低资源占用的执行模式，专为零信任或低算力环境设计。它大幅缩减系统提示词的大小，并把 Harness 工具注册表限制为仅两个原始工具：

• bash（持久 shell 工具）；
• str_replace_editor（确定性块替换编辑器）。

所有外部能力，包括网页搜索、子智能体委派、外部 MCP（Model Context Protocol，模型上下文协议）插件和后台守护进程生成，都在内核级别被严格禁用。

主要优势

• 低显存与上下文开销：更小的提示词足迹为本地 7B 或 14B 模型（如 qwen2.5-coder:7b）留出最大的上下文空间；
• 物理隔离合规：保证在本地容器沙箱之外零外部网络请求；
• 最高安全性：通过移除外部工具访问，减少潜在的提示词注入攻击面。

适用场景

• 在显存有限（8 GB–16 GB）的消费级笔记本电脑上运行 DSH；
• 要求完全物理隔离安全的严格企业环境；
• 受控评估和自动化基准测试。

4. 创建者模式（dsh creator / dsh --profile creator）

架构与机制

创建者（Creator）模式专为元开发者（meta-developer）、插件作者和提示工程师设计。它解锁了对底层 Cordis 框架内核服务的原始访问能力：

• ctx.llm：实时检查原始请求负载 JSON、提示前缀和补全 token；
• ctx.tools：在执行前动态热重载、注册或拦截工具调用；
• ctx.sessions：检查状态树、对话轮次历史和事件日志。

在创建者模式下，DSH 提供增强的详细输出，把原始系统提示、工具 schema、状态转换以及 KV 缓存性能指标直接记录到控制台或诊断仪表板。

本地安装完整指南

在本地工作站上部署 DeepSeek Harness 需要 Node.js 运行时环境。主包要求 Node.js 版本为 ^22.19.0 或 >=24.0.0（旧版兼容性可向下延伸至 >=20.0.0），并配合 pnpm 管理 monorepo 构建目标。

方案 A：通过 npx 一键快速启动

如果只想快速评估、不需要手动编译源码，可以直接用 npx 启动 Harness：

npx @deepseek-ai/dsh web

该命令会拉取已编译的 Web profile 包，初始化本地运行时配置，并启动一个可通过 http://127.0.0.1:3080 访问的 HTTP 服务器（视系统环境变量而定，端口也可能是 http://127.0.0.1:3018）。

方案 B：从源码构建以进行扩展开发

打算编写插件、调整安全策略或修改核心 monorepo 的开发者，直接从源码安装可以获得对代码库的完整访问权限：

# Clone the official repository
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness

# Install workspace dependencies
pnpm install# Compile TypeScript monorepo packages
pnpm run build# Launch the Web interface profile
pnpm dsh web

对于无头（headless）持续集成流水线或自动化脚本执行，可以选择 headless profile，让 DSH 在不启动图形化 Web 界面的情况下运行：

dsh –profile headless “Run project test suites, identify root causes of failures, and propose targeted code fixes.”

将 DeepSeek Harness 连接到本地 Ollama 模型

把 DeepSeek Harness 与物理隔离的本地模型集成，需要在 DSH 的模型适配服务与 Ollama 托管的 OpenAI 兼容本地推理端点之间建立桥梁。

模型选择与内存要求

自主 Agent 工作流对 LLM 的要求高于标准聊天交互。所选模型必须：

• 可靠地输出结构化的工具调用；
• 在宽广的上下文窗口中保持指令遵循能力；
• 能对执行反馈循环进行准确推理。

缺乏专门工具调用微调的模型经常输出无效的 JSON 语法、遗漏参数，或陷入重复推理循环。

要在 Ollama 中拉取并准备推荐的 140 亿参数模型，执行以下命令：

ollama pull qwen3:14b

确保 Ollama 后端服务正在运行，并监听其标准本地端口：http://127.0.0.1:11434。

在 DSH 中配置自定义 Provider 设置

可以通过 Web 界面或环境变量把 DSH 连接到本地 Ollama 实例。

界面配置

1. 在浏览器中打开 DeepSeek Harness 界面，地址为 http://127.0.0.1:3080。
2. 导航至 Settings → Models → Add Custom Provider。
3. 填写自定义 Provider 属性：
   • Provider ID：ollama-local
   • Base URL：http://127.0.0.1:11434/v1
   • Model Name：qwen3-coder:14b（与 ollama list 中的标签一致）
   • API Key：输入占位字符串，例如 ollama 或 local-key。
4. 保存配置。

注意：填写一个虚拟 API Key 很关键。虽然 Ollama 并不强制 API 认证，但 DeepSeek Harness 内部的凭据管理器在校验 Provider schema 时期望一个非空字符串，留空可能导致初始连接尝试失败。

环境变量配置

也可以通过环境变量声明连接参数，或在启动 Harness 之前直接更新 $DSH_HOME/.credentials.yaml 文件：

export DEEPSEEK_BASE_URL="http://127.0.0.1:11434/v1"
export DEEPSEEK_API_KEY="ollama-local-key"
export DEEPSEEK_MODEL="qwen2.5-coder:14b"

pnpm dsh web

对于虚拟化或容器化环境（例如 Docker 容器或 WSL2 环境），请把 127.0.0.1 替换为 host.docker.internal，以便把流量从容器化的 Harness 正确路由到宿主机的 Ollama 服务。

设置工作区安全策略

完成 Provider 设置后，选择一个隔离的工作区文件夹。DSH 强制执行严格的工作区边界，防止在指定项目文件夹之外进行意外的文件系统操作。

接下来，选择合适的权限等级来管控工具的执行方式：

• 只读等级（Read-Only Tier）：允许 Agent 检查仓库文件、查询目录结构和读取日志，但阻止文件写入和终端命令执行；
• 受防护 / 交互等级（Guarded / Interactive Tier，推荐）：在应用文件修改或运行终端脚本之前，通过交互式 diff 和审批请求提示开发者确认；
• 无限制等级（“YOLO 模式”）：自动批准所有工具调用。该模式应仅限在隔离的容器化环境中使用。

执行端到端本地工作流

为了说明 DeepSeek Harness 如何与 Ollama 协同工作，下面看一个针对 Node.js 微服务的自动化重构任务的实际开发场景。

任务目标

更新一个 Express API 路由处理器：使用 Zod schema 校验传入的负载结构，添加错误处理中间件，并通过运行项目测试套件验证更新。全部在本地完成，无需互联网访问。

分步工作流执行

首先，启动 Ollama 后端服务并启动 DeepSeek Harness 界面：

ollama run qwen2.5-coder:14b
npx @deepseek-ai/dsh web

然后打开 http://127.0.0.1:3080，选择目标仓库工作区，并提交任务提示：

“Inspect src/routes/user.ts. Refactor the POST /users endpoint to enforce payload validation using Zod schemas. Add new unit tests in tests/user.test.ts to verify invalid requests return a 400 status code, then run npm test to verify everything passes.”

（检查 src/routes/user.ts。重构 POST /users 端点，使用 Zod schema 强制执行负载校验。在 tests/user.test.ts 中添加新的单元测试，验证无效请求返回 400 状态码，然后运行 npm test 确认所有测试通过。）

执行过程中，Agent 通过结构化的工具调用循环处理该请求：

1. 仓库检查：Agent 使用文件读取工具检查 src/routes/user.ts 和 package.json。
2. 依赖管理：发现 zod 未安装后，Agent 请求用户批准通过其持久化终端工具执行 npm install zod。
3. 代码修改：获得用户批准后，DSH 调用 str_replace_editor 工具，在 src/routes/user.ts 中插入 Zod 校验逻辑并更新路由处理器。
4. 测试套件执行：Agent 在 tests/user.test.ts 中编写新的测试用例，并通过 shell 集成执行 npm test。
5. 迭代诊断：如果 Jest 报告测试失败，DSH 会读取失败的堆栈跟踪信息，调整校验 schema 或路由处理器，并重新执行测试套件，直到所有断言通过。

整个过程中，所有模型推理和工具执行都在本地进行：不消耗任何外部 API 额度，同时保证源代码完全留在本地工作站内。

不断壮大的开源 Agent 生态系统

DeepSeek Harness 的普及速度很快，预览版发布后数周内就在 GitHub 上积累了超过 19 万颗星，这证明了开发者对开放 Agent 基础设施的强烈需求。通过开源 Harness 设计，DeepSeek 催生了一个广泛的模块化扩展社区生态。

参考项目：Awesome-DeepSeek-Harness-Plugins

• 长期记忆扩展：dsh-memory-plugin 和 dsh-mneme 之类的插件添加了向量数据库和 SQLite 存储，可在长时间的开发会话中保留架构上下文；
• 工具可移植性：dsh-movein 之类的扩展允许开发者把 Model Context Protocol（MCP）服务器、自定义提示指令和权限设置，直接从现有的 Claude Code 配置导入到 DSH profile 中；
• 原生桌面界面：dsh-studio 之类的项目提供基于 SwiftUI 构建的原生 macOS 图形界面，在浏览器窗口之外展示实时执行图、工具审批管理和子 Agent 层级结构。

战略总结

DeepSeek Agent Harness 为自主软件开发提供了一个灵活的、厂商中立的基础。通过把推理模型与执行环境解耦，DSH 成为 Claude Code 和 OpenAI Codex 等封闭生态系统的有力开源替代方案。

与 Ollama 等本地推理引擎以及 Qwen2.5-Coder 或 Devstral 等开放权重的编码模型配合使用时，DSH 让软件工程团队能在本地硬件上部署完全私有、物理隔离的编码 Agent。随着围绕 Cordis 引擎的开源插件生态系统不断扩展，DeepSeek Harness 正在成为一个可定制、透明且注重隐私的 AI 开发框架。