DeepSeek Harness 桌面端实战：安装、模式选择与避坑指南
桌面端到底解决了什么问题
DeepSeek Harness（命令名 dsh）不是又一个聊天客户端，而是让模型能在授权范围内读取文件、编辑代码、运行命令、调用工具、拆分任务并持续执行工作流的 Agent 运行环境。桌面端的核心价值，是把"准备 Agent 运行环境"变成"安装普通桌面软件"——不再需要先折腾 Node.js、pnpm、终端环境变量和端口占用。
但有个边界必须先说清："本地 Agent"不等于"模型完全离线运行"。工作区和命令执行保存在本机，但调用 DeepSeek 云端模型时，请求仍会走网络。哪些内容进入模型上下文，取决于任务、工具调用和你的授权范围。
桌面端与 DeepSeek 聊天应用是完全不同的产品。后者主打通用对话，前者可操作本地环境；两边用同一个账号，但会话数据不互通。Harness 的会话、工作区和工具执行记录属于自己的数据体系。
版本时间线：别再把 alpha 当稳定版
截至 2026 年 10 月 10 日，官方 Release 页面最新的是 v0.2.1-alpha.2，仍标记为 Pre-release。关键变化：
- v0.2.0-rc.2（9 月 29 日）：桌面端可通过菜单安装
dsh命令，无需另装 Node.js - v0.2.1-alpha.1（10 月 3 日）：桌面端改用系统动态分配端口，自动化任务并入 Web 能力
- v0.2.1-alpha.2（10 月 9 日）：新增实验性思考翻译、Git Worktrees、Claude Code/Codex Bundle 安装入口
日常用户优先用官网安装包并查看内置更新；插件开发者必须同时关注 Harness 版本和插件的 Peer Dependency 兼容范围。
安装与初始化：从下载到第一次只读体检
官方入口只有三个：产品页 deepseek.com/harness、GitHub 仓库、开发者文档。当前官网直接提供 macOS Apple Silicon 和 Windows 64 位的安装包，Linux 暂无桌面端下载按钮。
Windows 安装注意 SmartScreen 提示，先核对发布者与下载来源。桌面端常驻系统托盘，关闭主窗口是隐藏而非退出，真正退出要从托盘菜单操作。
macOS 拖入应用程序后，首次运行按需授予文件夹或麦克风权限。任务不需要的权限就不要给——只做代码审阅时不需要麦克风，只处理一个项目时不需要把整个主目录授权给工作区。
账号登录与 API Key 两条路线：
| 路线 | 优点 | 注意点 |
|---|---|---|
| DeepSeek 账号授权 | 登录直观，可显示账号与余额 | 与聊天应用历史不互通 |
| API Key | 便于明确归属、统计和自动化配置 | Key 必须妥善保存，费用计入对应开放平台账户 |
不要在聊天、截图、Git 仓库或插件配置示例中暴露完整 API Key。
工作区决定 Agent 能看到和操作哪些本地文件。建议第一次使用创建专门的实验目录，只放可恢复的测试文件。不要直接选择整个用户目录、SSH 密钥目录、公司共享盘根目录或无备份的重要数据。
第一次会话建议用这段提示词做"只读体检"：
请先只读检查当前工作区，不修改任何文件，也不要执行安装、删除或移动操作。
输出：1. 目录结构概览；2. 项目使用的技术栈与启动方式；3. 可能包含敏感信息的文件类型；4. 如果后续需要修改，请先给出计划和预计改动文件，等待我确认。这段能验证四件事：工作区是否正确、读取权限是否正常、模型是否理解项目、审批策略是否符合预期。
核心架构：Cordis 与"一切皆插件"
Agent 的简化公式：
Agent = Model + Harness + Tools + State + Policy- Model：理解任务、推理和生成下一步动作
- Harness：上下文组织、任务循环和工具调度
- Tools：文件、Shell、搜索、预览、子 Agent 等真实能力
- State：会话、工作区、任务与执行轨迹
- Policy：哪些操作允许直接执行，哪些需要审批或沙箱约束
DeepSeek Harness 由 Cordis 驱动，通过依赖注入和配置组合把能力拆成可替换模块。模型适配器、Agent Loop、文件系统、沙箱策略、子 Agent、Web 页面——这些都可以由插件提供。
三个关键名词别混：
- Profile：一套可启动的完整组合，声明启用哪些 Bundle
- Bundle：npm 包形式的配置层，通过
dsh.bundle指向 Patch - Plugin Row：Cordis 运行时中的具体插件实例
一个可安装 Bundle 的 package.json 必须声明 dsh.bundle，否则可能被装成普通依赖却不加入 Profile 配置层——这正是"插件安装成功但功能完全没出现"的典型原因。
桌面端与 CLI/Web 共享 $DSH_HOME 下的会话、设置、凭据、工作区与存储，但不共享可执行包、插件激活状态、锁文件和 node_modules。排查问题时先确认当前使用的是哪个 Profile、哪一套运行时。
四种预设模式：不是模型变聪明，是工具组合不同
切换模式不会把 Flash 变成另一个模型，改变的是插件组合、工具呈现方式和系统指令。
| 模式 | 主要工具面 | 最适合的任务 | 不建议的用法 |
|---|---|---|---|
| 标准模式 | 文件、Shell、搜索、Skills、计划、子 Agent、工作流等 | 日常开发、文档、分析、综合任务 | 为基准测试追求最小变量 |
| PTC 模式 | 模型直接调用 run_code，在代码中编排子工具 |
批量、结构化、多步骤、可并行任务 | 模型不擅长代码规划时强行使用 |
| 极简模式 | 主要保留 Shell 与文件编辑器 | 模型能力对比、最小工具面实验 | 普通用户日常办公 |
| 创造模式 | 标准能力 + Cordis 运行时检查和插件试验 | 创建插件、定制 Preset、验证新工具 | 在生产目录无审查地自我改造 |
第一次使用直接选标准模式。 它提供最完整的常用工具面，适合阅读修改工程、整理文档、搜索资料、运行测试等大多数任务。
PTC（Programmatic Tool Calling）让模型直接看到的主要入口是 run_code，文件读取、编辑、Shell 等作为子工具在代码中被组合调用。适合扫描几百个文件并按规则分类、批量读取表格提取字段、对多个目录执行相同检查。但 PTC 不保证任何任务都更快更省 Token——模型若不能稳定写出正确编排代码，调试和重试反而增加成本。
极简模式主要保留 Shell 与文件编辑器，适合测试模型在最小环境中的 Agent 能力，追求的是可比较性，不是功能完整度。
创造模式能让 Agent 检查 Cordis 环境、试验插件和编写新的 Bundle。这个能力很强，也最需要边界：插件代码可能在 Harness 进程内运行，接触文件、网络、凭据和工具接口。
简单决策法：不确定选标准；同类工具操作很多可批量编排选 PTC；想公平测试模型裸 Agent 能力选极简；要制作插件或自定义 Preset 选创造。
实战流程：从文档整理到自动化任务
文档整理任务建议把需求写成可验收格式：
请读取当前工作区 input 目录中的 Markdown、Word 和 Excel 文件，生成 output/项目周报.docx。
要求：1. 先列出将读取的文件，不要处理工作区以外的内容；2. 按"本周完成、风险问题、下周计划、待确认事项"组织；3. 所有数字必须标注来源文件；4. 不确定的信息写"待确认"，不要补写事实；5. 生成后检查文档是否能正常打开，并给出输出路径。这比"帮我写一份周报"更可靠，因为它明确了数据边界、结构、事实规则、输出格式和验收动作。
代码任务建议拆成四阶段：只读诊断 → 计划确认 → 最小修改 → 构建与差异审阅。不要把"构建成功"当作唯一验收标准，前端还要检查 base 路径、静态资源、接口代理和服务器回退规则。
PTC 批量任务要强调可程序化规则，例如"扫描 src 目录内全部 .vue 文件，统计仍使用 ::v-deep 的位置，按文件并行读取但不要修改，输出 CSV"。它有清晰的输入集合、匹配规则、并行机会、输出 Schema 与异常策略，适合由 run_code 统一编排。
插件管理页可以查看官方插件、安装第三方 Bundle、启停和卸载。安装前检查：包名与代码来源、版本与更新时间、是否声明 dsh.bundle、Peer Dependency 是否兼容、需要哪些权限。从 Git 仓库安装源码型插件时，pnpm 10+ 可能拒绝执行 prepare，这是安装期代码执行的权限边界，不是"安装器坏了"。
自动化任务可以通过自然语言创建，例如"每周五 17:00 按 Asia/Shanghai 时区整理当前项目记录，生成本周周报草稿"。支持一次性延迟、固定间隔、指定 IANA 时区的每日/每周规则、五字段 Cron 表达式。
但自动化任务不是云端托管服务。 应用完全退出、相关会话未加载或设备休眠时，任务可能无法按预期触发。重要任务应保留外部日历、CI 或服务器调度作为兜底。
轨迹视图（Trajectory）能展示每轮模型输入、工具调用、耗时、文件修改与错误。调试时重点看：模型是否读了正确文件、工具参数是否越过工作区、Shell 命令是否包含删除或网络上传、某次失败后是否发生无意义重试、最终结论是否真的来自工具结果、Token 增长是否由重复读取或超长输出导致。
API 费用：软件免费，模型按量计费
Harness 本身 MIT 协议开源，主要可变成本来自模型 Token。截至 2026 年 10 月 10 日，DeepSeek 官方 API 定价（每百万 Token，美元）：
| 计费项 | Flash 非高峰 | Flash 高峰 | V4-Pro 非高峰 | V4-Pro 高峰 |
|---|---|---|---|---|
| 输入 Cache Hit | $0.003 | $0.006 | $0.022 | $0.044 |
| 输入 Cache Miss | $0.15 | $0.30 | $0.66 | $1.32 |
| 输出 | $0.60 | $1.20 | $1.98 | $3.96 |
高峰时段为工作日 01:00-04:00 UTC 与 06:00-10:00 UTC，对应中国时间约 09:00-12:00 与 14:00-18:00。
算一笔账：80K 缓存命中输入 + 20K 未命中输入 + 20K 输出，Flash 高峰费用约 $0.03，非高峰约 $0.015；V4-Pro 高峰约 $0.11，非高峰约 $0.055。
关键结论：
- 输出 Token 通常比输入 Cache Hit 贵得多，让 Agent 反复生成超长报告会迅速抬高费用
- 缓存能明显降低输入成本，但命中取决于稳定前缀、模型路由和请求结构，不能当成必然折扣
- 真正的性价比 = API 费用 + 失败重试成本 + 人工检查时间 + 错误造成的返工风险
选型建议：日常代码阅读、文档整理、批量处理优先用 Flash；复杂架构推理先用 Flash 做方案收集，再把关键问题交给更强模型；大量可延期任务安排在非高峰；需要图片理解选支持 Vision 的 Flash。
常见踩坑与避坑指南
19387 已不是固定端口。v0.2.1-alpha.1 后桌面端默认动态分配端口，不要把抓到的一次本地端口写入防火墙或脚本。
dsh doctor 不是官方内置命令。社区存在多个 Doctor 工具，但官方仓库里仍以 Idea/Proposal 形式讨论。排查顺序：查看版本 → 检查错误弹窗与 Crash Log → 临时停用第三方插件 → 用 --dump-config 检查配置层 → 再按需安装可信社区工具。
PTC 报"unknown tool read"不一定是缺插件。PTC 只把 run_code 作为直接工具，read、edit、bash 等要在程序里调用。解决思路：明确提示模型"在 run_code 中调用子工具"，或切回标准模式。
插件安装成功但未激活的常见原因：没有声明 dsh.bundle、Bundle 已安装但被停用、Peer Dependency 不兼容、Git 源码包的 prepare 未获允许、只改了另一个 Profile、替换安装版本后需要重启。
第三方插件的权限可能高于直觉。它可能运行在 Harness 进程内，接触主机能力。尤其警惕：安装期构建脚本、自动读取环境变量、未固定提交的 Git 依赖、要求关闭版本检查或使用 --accept-risk 的插件。
自动化任务不是关机后仍运行的云服务。真正退出应用后，提醒和任务不会继续执行。涉及付款、发布、数据库备份的任务，应使用服务器 Cron 或专业调度平台兜底。
工作区路径不要写成绝对限制。