AI Dev 06 & DeepSeek Harness 桌面端实战

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */
#content_views .toc,
/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */
#content_views.markdown_views > p:empty:has(+ .toc),
#content_views.markdown_views > .toc + p:empty,
/* 富文本旧版目录标记 */
#content_views.htmledit_views #main-toc,
#content_views.htmledit_views #hr-toc,
#content_views.htmledit_views p[id*=\”-toc\”] {
display: none !important;
}
/* 目录去掉后，紧跟的首个标题不再多出一块上边距 */
#content_views.markdown_views > .toc + h1,
#content_views.markdown_views > .toc + h2,
#content_views.markdown_views > .toc + h3,
#content_views.markdown_views > .toc + h4,
#content_views.markdown_views > .toc + p:empty + h1,
#content_views.markdown_views > .toc + p:empty + h2,
#content_views.markdown_views > .toc + p:empty + h3,
#content_views.markdown_views > .toc + p:empty + h4 {
margin-top: 0 !important;
}

系列文章：上一篇 AI Develop 05｜Codex、Claude 接入 DeepSeek 模型实战 介绍了如何把外部编程助手接入 DeepSeek API。本篇换一个方向：直接使用 DeepSeek 官方开源的 Agent Harness，并重点讲清 DeepSeek Harness 桌面端的安装、模式选择、插件、自动化、费用与安全边界。

版本核验日期：2026 年 10 月 10 日。 本文以 v0.2.0-rc.2 桌面端为主要操作基线，同时补充 v0.2.1-alpha.1 / alpha.2 已发生的变化。DeepSeek Harness 仍处于快速迭代阶段，读者应以“关于 DeepSeek Harness”、官方 Release 和文档中的当前版本为准。

前言

DeepSeek Harness（命令名为 dsh）不是另一个只能聊天的桌面客户端，而是一套能让模型在授权范围内 读取文件、编辑代码、运行命令、调用工具、拆分任务、加载插件并持续执行工作流 的 Agent 运行环境。模型负责理解与推理，Harness 负责把推理转成真实操作。

桌面端真正降低的不是模型使用难度，而是 Agent 运行环境的安装门槛。过去使用 Web UI，通常要先安装 Node.js，再执行 npx @deepseek-ai/dsh web，最后在浏览器中配置模型和工作区；桌面端把运行时、Web 前端、插件管理与更新能力封装到安装包中，日常使用不再要求用户先搭建 Node.js 或 pnpm 环境。

但这里有一个必须先说清的边界：“本地 Agent”不等于“模型完全离线运行”。DeepSeek Harness 的工作区、命令执行和部分数据保存在本机；当你选择 DeepSeek 云端模型时，模型请求仍会通过网络发送到对应服务。工作区里哪些内容会进入模型上下文，取决于任务、工具调用和你的授权范围。

本文会解决这些具体问题：

• 桌面端、Web、CLI 与 DeepSeek 聊天应用到底是什么关系；
• Windows 与 macOS 如何安装，账号登录和 API Key 如何选择；
• 标准、PTC、极简、创造四种模式该怎么选；
• 插件、Bundle、Profile、Cordis 分别是什么；
• 如何完成一次 文档整理、代码修改、批量处理和定时任务；
• DeepSeek API 能力、计费规则、缓存价格和性价比如何判断；
• 哪些原稿中常见的说法已经过时，例如 固定端口 19387 和“官方内置 dsh doctor”。

图1 DeepSeek Harness 桌面端实战封面

一、先认识 DeepSeek Harness 桌面端

1.1 它解决了什么问题

CLI/Web 版的典型启动链路如下：

npx @deepseek-ai/dsh web

该命令默认启动本地 Web UI，并在浏览器打开 http://127.0.0.1:3080。这条路线适合开发者、Linux 用户、远程服务器或需要自定义 Profile 的场景，但普通用户还要处理 Node.js 版本、npm 缓存、终端环境变量、端口和进程生命周期。

桌面端把这条链路改成了：

桌面端的核心价值，是把“准备 Agent 运行环境”变成“安装普通桌面软件”。它没有改变 Agent 的基本能力模型，只是把运行时、UI、更新、插件安装与系统集成封装得更完整。

图2 CLI Web 与桌面端使用链路对比

1.2 它与 DeepSeek 聊天应用不是同一个产品

这两个产品容易被混淆：

使用同一个 DeepSeek 账号，并不代表两边历史对话自动合并。Harness 的会话、工作区和工具执行记录属于自己的数据体系，不能把聊天应用里的记录当作 Harness 历史。

1.3 版本时间线要怎么理解

原稿把“桌面端发布”和“v0.2 候选版本”写成同一个事件，容易造成误解。更准确的表达如下：

因此，本文不把某个 alpha 版本写成“稳定版”。截至 2026 年 10 月 10 日，官方 Release 页面最新的是 v0.2.1-alpha.2，它仍标记为 Pre-release。 对日常用户而言，优先使用官网安装包并查看内置更新；对插件开发者而言，必须同时关注 Harness 版本和插件的 Peer Dependency 兼容范围。

1.4 开源免费不等于使用过程零费用

DeepSeek Harness 仓库采用 MIT License，软件本身可以免费下载、审阅和扩展。但 Agent 每一次调用云模型都会产生 Token，用量由所选模型提供方计费。桌面端还可能调用网页搜索、第三方插件、远程服务或自定义 API，这些服务是否收费要分别判断。

准确说法是：Harness 软件开源免费，云端模型推理通常按量计费。不要把“免费下载安装”误解为“无限免费使用模型”。

二、下载、安装与首次初始化

2.1 只使用官方入口

官方入口为：

• 产品页：https://www.deepseek.com/harness/。
• 官方仓库：https://github.com/deepseek-ai/deepseek-harness。
• 开发者文档：https://deepseek-harness.github.io/deepseek-harness/。

当前官网首页直接提供：

• macOS（Apple 芯片）：dsh-latest-macos-arm64.dmg
• Windows（64 位）：dsh-latest-windows-x64.exe

官方仓库包含更多构建目标和开发脚本，但普通用户应以产品页公开的下载按钮为准。Linux 暂无官网桌面端下载按钮，Linux 用户更适合使用 Web/CLI 路线。

安装包体积会随内置运行时、插件和 Electron 版本变化，不建议在文章中长期写死某个 MB 数字。下载时看到体积变化，不等于文件一定异常；更重要的是核对 下载域名、数字签名和应用内版本信息。

2.2 Windows 安装

Windows 的实际流程很简单：

若 SmartScreen 给出提示，先检查发布者与下载来源，不要形成“看到提示就点仍要运行”的习惯。只有确认文件来自 download.deepseek.com 且签名正常时，才继续安装。

桌面端在 Windows 中会常驻系统托盘。关闭主窗口通常是隐藏窗口，正在运行的任务仍可继续；真正退出要从托盘菜单选择“退出 DeepSeek Harness”。退出时，如果存在运行中的 Agent 或定时任务，应用会提示可能受到的影响。

2.3 macOS 安装

macOS Apple Silicon 用户下载 DMG 后：

权限原则很简单：任务不需要的权限就不要给。例如只做代码审阅时，不需要麦克风；只处理一个项目时，不需要把整个主目录授权给工作区。

2.4 账号登录与 API Key 两条路线

桌面端可以使用 DeepSeek 账号能力，Harness 的凭据子系统还提供资料、余额与登录状态接口。Web/CLI 官方快速入门则仍以 DeepSeek API Key 为主：打开“设置 → 模型”，在 DeepSeek 卡片中保存密钥即可生效，通常不需要重启。

两条路线的区别可概括为：

不要在聊天、截图、Git 仓库或插件配置示例中暴露完整 API Key。 对项目成员共享使用时，应通过环境变量、凭据管理器或团队网关管理，而不是把 Key 写进仓库。

2.5 工作区不是普通的“打开文件夹”

工作区决定 Agent 可以看到和操作哪些本地文件。一个稳妥的目录结构可以是：

D:\\AIWork\\harness-demo
├─ input
├─ output
├─ src
└─ README.md

第一次使用建议创建一个专门的实验目录，只放可恢复的测试文件。不要直接选择：

• 整个 C:\\Users\\你的用户名；
• SSH、云厂商或证书密钥目录；
• 公司共享盘根目录；
• 包含大量生产数据的目录；
• 无备份的论文、合同或源代码唯一副本。

工作区越小，误操作影响面越小，模型需要检索的无关上下文也越少。这同时改善安全性、速度和 Token 成本。

2.6 首次会话先做一次“只读体检”

不要刚进入工作区就让 Agent 大范围修改。笔者更建议用下面这段作为第一次任务：

请先只读检查当前工作区，不修改任何文件，也不要执行安装、删除或移动操作。
输出：
1. 目录结构概览；
2. 项目使用的技术栈与启动方式；
3. 可能包含敏感信息的文件类型；
4. 如果后续需要修改，请先给出计划和预计改动文件，等待我确认。

这段提示词能验证四件事：工作区是否正确、读取权限是否正常、模型是否理解项目、审批策略是否符合预期。确认无误后再开始实际任务。

2.7 可选：安装桌面端自带的 dsh 命令

从 v0.2.0-rc.2 起，桌面端菜单提供“管理 dsh 命令…”，可安装、修复或移除命令行入口。安装完成后新开终端验证：

dsh –version

macOS 通常会创建 /usr/local/bin/dsh 入口；Windows 会把桌面端提供的命令注册到当前用户 PATH。此操作是可选的，不安装也不影响桌面 UI 的基本使用。

需要注意：桌面端拥有保留的 Desktop Profile。系统全局安装的另一个 dsh 与桌面端自带命令可能来自不同版本，插件状态也不一定相同。遇到命令冲突时，先在“管理 dsh 命令…”中查看当前指向的位置，不要盲目修改 PATH。

三、核心架构：为什么“一切皆插件”

3.1 Agent 等于模型加 Harness

在普通聊天中，模型输出文字；在 Agent 系统中，模型还要判断何时读文件、调用工具、运行命令、等待审批、继续下一轮。可以用一个简化公式理解：

Agent = Model + Harness + Tools + State + Policy

• Model：负责理解任务、推理和生成下一步动作；
• Harness：负责上下文组织、任务循环和工具调度；
• Tools：提供文件、Shell、搜索、预览、子 Agent 等真实能力；
• State：保存会话、工作区、任务与执行轨迹；
• Policy：决定哪些操作允许直接执行，哪些需要审批或沙箱约束。

这也解释了为什么同一个模型放到不同 Agent 工具里，实际表现会不同。差异不只来自提示词，还来自 工具定义、审批策略、上下文压缩、错误恢复与任务循环。

3.2 Cordis 在其中扮演什么角色

DeepSeek Harness 由 Cordis 驱动。它不是一个把所有功能写死的庞大核心，而是通过依赖注入、生命周期和配置组合，把能力拆成可替换模块。

在 Harness 中，下面这些都可以由插件提供：

• 模型适配器；
• Agent Loop；
• 文件系统和命令工具；
• 会话日志与持久化；
• 沙箱与审批策略；
• 子 Agent、Skills 与工作流；
• Web 页面、设置项和预览组件；
• 自动化任务与时间上下文。

“一切皆插件”并不代表可以无条件随时替换一切。更准确地说，能力通过可组合的插件和配置层装配。很多启停操作能在运行时生效，但替换已经安装的包版本、修改某些启动期依赖或处理不兼容插件时，仍可能需要重启。

图3 DeepSeek Harness Cordis 插件架构

3.3 Profile、Bundle 与 Plugin 不要混为一谈

这是理解 Harness 配置的关键：

一个可安装 Bundle 的 package.json 需要声明类似内容：

{
"name": "dsh-hello-plugin",
"version": "0.1.0",
"dsh": {
"bundle": {
"patch": "./cordis.patch.yml"
}
}
}

如果包里没有 dsh.bundle 声明，它可能被安装成普通依赖，却不会加入 Profile 的配置层。 这正是“插件安装成功但功能完全没出现”的典型原因之一。

3.4 桌面端与 CLI/Web 到底共享什么

官方架构文档给出的边界很清楚：桌面端和 CLI 可以共享 $DSH_HOME 下受支持的产品数据，包括 会话、设置、凭据、工作区与存储；但它们不共享可执行包、插件激活状态、锁文件和 node_modules。

因此，下面两句话只有第一句正确：

• “我在 Web 里创建的会话，桌面端可能继续看到。”——通常正确；
• “我在 Web Profile 装过的插件，桌面端一定已经启用。”——不正确。

共享数据不等于共享插件运行环境。排查问题时要先确认当前使用的是哪个 Profile、哪一套运行时和哪一个 dsh 命令。

四、四种预设模式怎么选

4.1 模式改变的是工具与规则，不是模型智力

DeepSeek Harness 的预设模式，本质上是 不同的插件组合、工具呈现方式和系统指令。切换模式不会把 DeepSeek-V4.1-Flash 变成另一个模型，也不会自动提高模型参数规模。

图4 DeepSeek Harness 四种模式选择

4.2 标准模式：大多数任务的默认答案

第一次使用直接选 标准模式。它提供最完整的常用工具面，适合：

• 阅读并修改前端、后端或 FPGA 工程；
• 整理 Word、Excel、PPT、PDF 与 Markdown；
• 搜索资料并生成带来源的结论；
• 运行测试、查看差异、修复问题；
• 把长命令转入后台并在完成后继续会话。

标准模式的代价是固定上下文和工具定义更大。工具越多，模型每轮需要理解的契约越复杂，前缀缓存也更容易因配置变化而失效。但这不意味着标准模式一定贵；真实费用仍取决于 输入长度、缓存命中、输出长度和任务轮次。

4.3 PTC 模式：让模型用程序编排工具

PTC 可以理解为 Programmatic Tool Calling。在这一模式下，模型直接看到的主要入口是 run_code，文件读取、编辑、Shell 等能力作为子工具在代码中被组合调用。

标准模式可能经历：

读文件 → 返回模型 → 决定搜索 → 返回模型 → 决定批量读取 → 返回模型 → 汇总

PTC 则可能把它压缩为：

编写 TypeScript 编排程序 → run_code 一次执行多个读取、筛选和并行操作 → 返回结果

它特别适合：

• 扫描几百个文件并按规则分类；
• 批量读取表格、提取字段、生成汇总；
• 对多个目录执行相同检查；
• 先并行检索，再统一去重和排序。

但 PTC 不保证任何任务都更快、更省 Token。模型若不能稳定写出正确编排代码，调试和重试反而增加成本。一个很典型的现象是模型提示“找不到 read 工具”——这不一定是工具丢失，而是 PTC 中 read 不是直接可调用工具，需要在 run_code 内作为子工具使用。

4.4 极简模式：用于控制变量，不是“低配标准模式”

极简模式主要保留 Shell 与文件编辑器，减少系统提示和工具数量，适合测试模型在最小环境中的 Agent 能力。

它的价值在于控制变量：同一个任务、同一个仓库、同一套最小工具，分别交给不同模型执行，结果更容易比较。因为前缀更短、更稳定，缓存条件也通常更友好。

但它不适合刚接触 Harness 的用户。缺少搜索、计划、自动化和丰富预览后，很多原本一两步能完成的工作要手动绕路。极简模式追求的是可比较性，不是功能完整度。

4.5 创造模式：让 Agent 扩展自己的 Harness

创造模式拥有标准模式能力，还能检查 Cordis 环境、试验插件和编写新的 Bundle。可以直接提出：

请为当前 Harness 创建一个“只读安全审计”预设：
1. 允许读取、搜索和生成报告；
2. 禁止写文件、删除、移动和执行有副作用的命令；
3. 输出插件结构、配置层和验证方法；
4. 安装前先让我审阅所有文件。

这个能力很强，也最需要边界。插件代码与普通对话文本不同，它可能在 Harness 进程内运行，并接触文件、网络、凭据和工具接口。Agent 能写出插件，不等于该插件已经过安全审计。

4.6 一个简单的模式决策法

可以按任务特征选择：

• 不确定选什么：标准模式；
• 同类工具操作很多、可批量编排：PTC 模式；
• 想公平测试模型裸 Agent 能力：极简模式；
• 要制作插件或自定义 Preset：创造模式。

从 v0.2.1-alpha.1 起，如果关闭“Coding Tools”，新会话列表主要保留 标准、创造和自定义模式，PTC 与极简可能不再显示；已有会话仍保留原模式。这是设置行为，不是安装损坏。

五、从会话到插件与自动化的实战流程

5.1 文档整理任务：先约束输入与输出

以“整理项目材料并生成周报”为例，建议把需求写成可验收格式：

请读取当前工作区 input 目录中的 Markdown、Word 和 Excel 文件，生成 output/项目周报.docx。

要求：
1. 先列出将读取的文件，不要处理工作区以外的内容；
2. 按“本周完成、风险问题、下周计划、待确认事项”组织；
3. 所有数字必须标注来源文件；
4. 不确定的信息写“待确认”，不要补写事实；
5. 生成后检查文档是否能正常打开，并给出输出路径。

这个提示词比“帮我写一份周报”更可靠，因为它明确了 数据边界、结构、事实规则、输出格式和验收动作。Agent 的执行过程通常包括文件检索、内容读取、数据汇总、文档生成与结果验证。

5.2 代码任务：计划、修改、测试、差异审阅

以 Vue 项目修复为例：

请定位生产环境刷新子路由 404 的原因。
先只读检查 vite.config、router 和 nginx 示例配置，给出根因与修改计划。
我确认后再改文件。修改完成后运行构建，展示改动文件、关键 diff、构建结果和仍存在的风险。

这里把任务拆成四个阶段：

不要把“构建成功”当作唯一验收标准。前端项目还要检查 base 路径、静态资源、接口代理和服务器回退规则；后端项目则要检查单元测试、数据库迁移和配置兼容性。

5.3 PTC 批量任务：让结构化操作一次完成

适合 PTC 的提示词应强调可程序化规则，例如：

扫描 src 目录内全部 .vue 文件：
1. 统计仍使用 ::v-deep、/deep/ 和 >>> 的位置；
2. 按文件并行读取，但不要修改；
3. 输出 CSV，字段为 file、line、syntax、suggestion；
4. 汇总每种旧语法数量；
5. 如果任何文件读取失败，单独列出，不要忽略。

它有清晰的输入集合、匹配规则、并行机会、输出 Schema 与异常策略，适合由 run_code 统一编排。相反，“帮我看看项目有没有问题”几乎没有结构，不会因为切到 PTC 就自动变好。

5.4 插件管理：能安装不代表值得安装

桌面端提供独立插件管理页，可以查看官方插件、安装第三方 Bundle、启停和卸载。安装前至少检查：

• 包名与代码来源；
• 当前版本与更新时间；
• 是否声明 dsh.bundle；
• 对 @deepseek-ai/dsh-* 的 Peer Dependency 是否兼容；
• 是否包含安装期 prepare 脚本；
• 需要哪些文件、网络、Shell 或凭据权限。

从 Git 仓库安装源码型插件时，pnpm 10+ 可能拒绝执行 prepare。这不是“安装器坏了”，而是安装期代码执行的权限边界。只有审阅并信任来源后，才允许确切的构建脚本；最好把 Git 依赖固定到具体提交 SHA，避免上游后续推送改变安装内容。

对 Web Profile，命令行管理形式为：

dsh plugin –profile web add <package-name>
dsh plugin –profile web remove <package-name>
dsh plugin –profile web why <package-name>

桌面端优先使用其插件页面与自带管理流程。不要用一个版本的全局 dsh 去强行修改另一个版本的 Desktop Profile。

5.5 自动化任务：把重复工作交给 Schedule

自动化任务可以通过自然语言创建。例如：

每周五 17:00，按 Asia/Shanghai 时区整理当前项目记录，生成本周周报草稿。

官方 Schedule 支持：

• 一次性延迟或绝对时间；
• 至少一分钟的固定间隔；
• 指定 IANA 时区的每日与每周规则；
• 带时区的五字段 Cron 表达式；
• schedule_create、schedule_list、schedule_update、schedule_delete。

版本差异必须注意：v0.2.0-rc.1 把自动化作为可选 Bundle；从 v0.2.1-alpha.1 起，它并入 Web 能力，并向标准、创造和 PTC 模式提供提醒工具，极简模式和子 Agent 不提供。

定时任务也不是云端托管服务。应用完全退出、相关会话未加载或设备休眠时，任务可能无法按预期触发。重要任务应保留外部日历、CI 或服务器调度作为兜底。

5.6 轨迹视图：不要只看最终答案

Harness 的 Trajectory 能展示每轮模型输入、工具调用、耗时、文件修改与错误。调试 Agent 任务时，重点看：

• 模型是否读了正确文件；
• 工具参数是否越过工作区；
• Shell 命令是否包含删除、覆盖或网络上传；
• 某次失败后是否发生无意义重试；
• 最终结论是否真的来自工具结果；
• Token 增长是否由重复读取或超长输出导致。

Agent 的可信度来自“过程可审阅 + 结果可验证”，不是来自回答语气自信。

图5 DeepSeek Harness 安全任务闭环

六、DeepSeek API 能力、费用与性价比

6.1 先区分软件成本和模型成本

Harness 本身开源，不收“桌面软件订阅费”；主要可变成本来自模型 Token。若使用第三方模型、自建网关或付费插件，还要叠加相应费用。

截至 2026-10-10，DeepSeek 官方 API 定价页列出 deepseek-flash 与 deepseek-v4-pro。两者均支持思考/非思考模式、工具调用、Responses API 与 Anthropic API；上下文长度为 1M Token，最大输出标注为 384K Token。其中 DeepSeek-V4.1-Flash 支持视觉输入，页面标注的 V4-Pro 版本不支持 Vision。

6.2 当前官方价格

以下价格均为 每 100 万 Token，单位美元：

高峰时段为工作日 01:00-04:00 UTC 与 06:00-10:00 UTC，中国标准时间对应约 09:00-12:00 与 14:00-18:00；中国法定节假日及周末全天按非高峰规则。官方可能调整价格，发布文章后仍应以价格页为准。

6.3 用一个 Agent 任务算清费用

假设一次任务包含：

• 80K Token 缓存命中输入；
• 20K Token 未命中输入；
• 20K Token 输出。

Flash 高峰费用：

0.08 × $0.006 + 0.02 × $0.30 + 0.02 × $1.20
= $0.03048

Flash 非高峰费用约 $0.01524；V4-Pro 高峰约 $0.10912；V4-Pro 非高峰约 $0.05456。

图6 DeepSeek API 费用与选型

这个例子说明两件事：

6.4 Flash 与 Pro 如何选

笔者的建议是：

• 日常代码阅读、文档整理、批量处理、常规工具调用：优先 DeepSeek-V4.1-Flash；
• 复杂架构推理、长链路决策、关键代码审查：先用 Flash 做方案与资料收集，再把少量关键问题交给更强模型；
• 大量可延期任务：安排在非高峰执行，理论价格为高峰的一半；
• 需要图片理解：当前官方价格表中优先选择支持 Vision 的 Flash；
• 需要稳定生产流程：不要只看单 Token 价格，还要统计任务成功率、重试次数和人工复核时间。

真正的性价比不是“哪一个模型单价最低”，而是：

单位有效任务成本
= API 费用
+ 失败重试成本
+ 人工检查时间
+ 错误造成的返工风险

低价模型连续失败三次，往往比高价模型一次完成更贵。对自己的典型任务做 20-50 次样本测试，比引用一张通用榜单更有价值。

6.5 Harness 为什么可能提高或降低成本

它可能降低成本，因为：

• 工具直接取得事实，减少模型凭空猜测；
• PTC 可把多次工具往返压进一次程序执行；
• 会话、文件和任务状态能够复用；
• 适当的缓存命中显著降低重复输入价格。

它也可能增加成本，因为：

• 工具列表和系统指令占据上下文；
• Agent 会经历多轮“思考—调用—观察”；
• 子 Agent、团队与后台工作会产生额外调用；
• 无约束读取大仓库或生成长报告会扩大 Token；
• 插件错误可能触发失败与重试。

最有效的控制方法不是一味切极简模式，而是 缩小工作区、限定文件范围、要求先计划、限制输出格式、复用稳定提示前缀、及时结束已完成会话。

七、注意事项与常见踩坑

7.1 它仍是开发者预览版

官方安全说明明确指出：DeepSeek Harness 是实验性的开发者预览软件，尚未完成安全审计，不能视为安全或生产就绪。它可以执行模型生成的代码与命令，加载第三方插件，并访问你授权的网络、进程、凭据和文件。

适合的环境：

• 可恢复的个人项目；
• 有 Git 或备份的代码库；
• 隔离的虚拟机、容器或测试账号；
• 不包含敏感凭据的实验目录。

不适合直接放开的环境：

• 生产服务器管理员账号；
• 未备份的合同、论文或财务数据；
• 包含云密钥、SSH 私钥和客户数据的主目录；
• 允许第三方插件不经审查自动安装的长期运行环境。

7.2 19387 已不是当前桌面端固定端口

早期桌面端资料中常见 19387。但 v0.2.1-alpha.1 已把桌面端默认行为改为由操作系统动态分配端口，原因是避免 Windows 保留端口范围导致启动失败。

因此文章中应这样区分：

• Web/CLI 默认地址：127.0.0.1:3080；
• 当前桌面端：默认动态端口；
• 旧构建或手动 Patch：可能出现 19387 或自定义端口。

不要把抓到的一次本地端口写入防火墙、脚本或监控规则当作永久值。

7.3 dsh doctor 不是官方内置命令

社区存在多个 Doctor 工具，例如 @bruc3van/dsh-doctor、dsh-plugin-doctor 等，但官方仓库里的“增加 dsh doctor”仍以 Idea/Proposal 形式讨论。直接把“遇到问题先运行 dsh doctor”写成官方标准流程，会误导没有安装社区工具的读者。

更稳妥的官方排查顺序是：

7.4 插件安装成功但未激活

常见原因包括：

• 包没有声明 dsh.bundle；
• Bundle 已安装但被停用；
• Peer Dependency 与当前 Harness 不兼容；
• Git 源码包的 prepare 未获允许；
• 插件只改了另一个 Profile；
• 替换安装版本后需要重启；
• 插件加载失败，触发桌面端恢复或禁用流程。

对 Web/CLI 可检查：

dsh –profile web –dump-config

输出中应能看到对应 Bundle 配置层。桌面端则在插件详情页核对 来源、实际安装版本、启用状态和兼容提示。

7.5 第三方插件的权限可能高于你的直觉

插件不是浏览器扩展那种天然隔离的小组件。它可能运行在 Harness 进程内，接触主机能力。尤其要警惕：

• 安装期构建脚本；
• 自动读取环境变量；
• 未固定提交的 Git 依赖；
• 复制一套不兼容的 @deepseek-ai/dsh-* 运行时依赖；
• 要求关闭版本检查或使用 –accept-risk 的插件。

允许安装脚本，等价于允许该包在本机执行代码；这不是普通的“下载文件”。

7.6 工作区路径不要写成绝对限制

“工作区路径不能包含空格或中文”不是官方通用规则。Windows 早期构建确实出现过 CJK 目录选择与路径处理问题，但这属于版本缺陷，不应写成永久产品限制。

实战中仍建议使用 短、纯英文、无特殊符号 的测试路径，例如 D:\\AIWork\\demo。这样能减少 Shell 引号、脚本编码和第三方工具兼容问题；如果中文路径在当前版本正常，就不必为了迁就过时结论迁移所有项目。

7.7 账号模型、API Key 与用量统计可能分开

桌面端账号授权与自带 API Key 可能走不同模型路由和统计口径。发现“客户端用量为 0，但开放平台余额变化”时，先确认当前模型提供方和凭据来源，不要直接判断计费异常。

建议每次做大任务前检查：

• 当前模型名称；
• 当前提供方；
• 是否为思考模式；
• 账号余额或 API Key 所属项目；
• 是否处于高峰时段；
• 是否启用了子 Agent 或自动化。

7.8 自动化任务不是关机后仍运行的云服务

桌面端隐藏窗口时，Host 仍运行，任务可以继续；真正退出应用后，提醒和任务不会继续执行。官方文档还说明，提醒只会在已加载的会话中触发，未加载会话需要重新打开后才继续。

因此，周报草稿、个人提醒可以放在 Harness；涉及付款、发布、数据库备份、生产巡检的任务，应使用服务器 Cron、CI/CD 或专业调度平台兜底。

7.9 PTC 报“unknown tool read”不一定是缺插件

PTC 只把 run_code 作为直接工具，read、edit、bash 等要在程序里调用。解决思路有两个：

• 明确提示模型“在 run_code 中调用子工具”；
• 如果当前模型持续按标准模式习惯直接调用工具，切回标准模式完成任务。

不要为这个错误反复重装文件插件。

7.10 排障速查表

7.11 一套更稳妥的使用底线

笔者建议长期坚持以下规则：

八、本文总结

DeepSeek Harness 桌面端最有价值的变化，不是“给网页套了一个窗口”，而是把 Agent 运行时、工作区、插件管理、文件预览、任务轨迹与系统集成放进一个普通用户可以直接安装的应用中。它让日常文档、数据、代码和定时任务有了统一的 Agent 工作入口。

可以带走的结论有五条：

• 第一次使用选标准模式；批量结构化任务再试 PTC，基准测试用极简，插件开发用创造；
• 桌面端和 CLI/Web 共享部分产品数据，但不共享插件激活与可执行环境；
• v0.2.1-alpha.1 后桌面端默认动态端口，19387 已不是通用固定值；
• Harness 开源免费，云模型按 Token 计费，Flash 通常适合作为默认模型；
• 它仍是未完成安全审计的预览软件，最小工作区、审批、备份和结果验证缺一不可。

如果只想体验一次，准备一个空白测试目录，用 标准模式 + DeepSeek-V4.1-Flash 完成“只读扫描—生成计划—小范围修改—验证结果”的闭环即可。等你真正理解工作区、审批和轨迹后，再启用自动化、子 Agent 与第三方插件。

DeepSeek Harness 的上限取决于模型，可靠性却取决于 Harness、权限边界与人的验收。会用工具只是起点，能把任务限制在可审阅、可回滚、可验证的范围内，才是 Agent 真正进入日常工作的标志。

九、更多操作

9.1 后续可以继续深挖的方向

• 使用 Headless 模式接入 CI/CD；
• 用 Python SDK 发起和继续 Harness 会话；
• 为团队制作只读审计、文档处理或前端开发专用 Preset；
• 研究 Claude Code Mods 实验兼容层与原生 Harness 插件的差异；
• 使用 Git Worktrees 让多个 Agent 在隔离分支并行工作；
• 统计真实项目的 Cache Hit、成功率与单位有效任务成本；
• 将 Codex、Claude Code Bundle 作为可选子 Agent 能力接入。

更多 AI 开发与工程化实战内容，可访问：AI Dev 专栏 专栏。本系列将继续整理 Codex、Claude、DeepSeek、AI Agent、前端工程化与软硬件协同开发中的可复现实战和踩坑记录。

如果本文对你有帮助，欢迎点赞、收藏和评论。若你在 Windows 沙箱、插件兼容、PTC 编排或 API 费用方面遇到不同现象，也欢迎附上 Harness 版本、操作系统、模式、Profile 和关键报错交流；这些信息比一句“不能用”更容易定位问题。

9.2 官方资料