桌面编码代理 ShuaixinHuang/deepseek-harness-desktop

DeepSeek-Harness-Desktop

本地优先、桌面优先的 coding-agent harness，默认使用 DeepSeek。

English · MIT License ·产品对比

DeepSeek-Harness-Desktop 是一套桌面优先的 agent harness，定位为 DeepSeek Harness（dsh）的原生桌面版对位产品。DeepSeek Harness 于 2026 年 8 月以 v0.1 开发者预览版亮相：通过 npx @deepseek-ai/dsh web 启动的 Web UI、一切皆插件的架构，并明确预告了破坏性变更。DeepSeek-Harness-Desktop 保留同样的 DeepSeek 优先、本地优先理念，但以真正的桌面形态交付——原生 Electron 应用加终端客户端，无需浏览器标签页、无需插件商店、也不被不断变化的底层框架绑架。

它默认使用经济的 DeepSeek V4 Flash，并内置支持 Codex、OpenAI、Anthropic、OpenRouter、Z.AI、Kimi、MiniMax、xAI 和 OpenCode Zen Go。会话以本地树形 JSONL 保存，可随时恢复、分叉和回放。命令默认在 OS sandbox 中运行并禁止联网，每次成功 patch 都会生成持久且带冲突保护的 checkpoint。

桌面客户端

终端客户端

可从 DeepSeek-Harness-Desktop v0.1.0 的项目发布页下载（macOS 提供 DMG，Windows 提供安装程序 EXE，Linux 提供 DEB/RPM）。

为什么选择 DeepSeek-Harness-Desktop

DeepSeek Harness 证明了 DeepSeek 原生 agent harness 的需求。DeepSeek-Harness-Desktop 只保留其中真正重要的部分，并把它交付成"装好即用"的产品，而不是需要自己拼装的 dev-preview 技术栈：

| 维度 | DeepSeek-Harness-Desktop | DeepSeek Harness（dsh） |
| 形态 | 原生 Electron 桌面应用 + 终端 TUI | Web UI（npx @deepseek-ai/dsh web），在浏览器标签页中打开 |
| 安装 | macOS / Windows / Linux 签名安装包 | Node.js + npm 启动器；v0.1 开发者预览 |
| 默认模型 | DeepSeek V4 Flash + minimal harness | 模型适配器通过插件组合 |
| 会话 | 本地树形 JSONL；可恢复 / 分叉 / 回放 | append-only session log + Trajectory 回放 |
| 安全 | OS sandbox、默认禁网、checkpoint | sandbox、权限和存储均通过插件组合 |
| Runtime | 本地、可检查、MIT 许可 | Cordis 插件内核，MIT 许可，预期有破坏性变更 |

- 桌面优先，而非 Web UI 优先。 会话视图、diff review 和设置都在你启动的应用里，另有完整终端客户端用于无头与脚本化工作。
- DeepSeek 优先，但不限于 DeepSeek。 DeepSeek V4 Flash 仍是默认模型，继续使用专用 Responses adapter、原生 freeform apply_patch 和服务端 Web Search；也可以在不改变工具与会话的情况下切换到 Codex、OpenAI、 Anthropic、OpenRouter、Z.AI、Kimi、MiniMax、Grok 或 OpenCode Zen Go。
- 极简 harness 是主路径。 默认 runtime 暴露的正是 DeepSeek 官方评测 V4 Flash 时使用的极简工具面（exec_command + apply_patch），让模型不再纠结于语义重叠的工具选择；需要显式文件读取、文件搜索和语言诊断时，一个 --harness safe 即可切换。
- 运行全程可追溯。 每条消息、reasoning item 和工具结果都写入本地 JSONL。恢复、分叉、压缩与回放都基于同一份 transcript。
- 模型支持时可识图。 可在 TUI 粘贴图片或通过 @file 传入；GPT-5.6 等模型能检查截图，会收到真正的图片 attachment，text-only DeepSeek 模型则会给出明确限制。
- 围绕成本设计。 Runtime 直接利用 DeepSeek 的 1M context 和硬盘前缀缓存；/status 会显示 context、缓存命中、token、reasoning 和预估费用。最新价格以 DeepSeek 官方价格页为准。
- 并行但不失控。 内置 explorer、implementer、reviewer、tester 四种角色，最多四路并行；implementer 在独立 Git worktree 中修改，主 agent 负责集成和最终验证。
- 本地控制。 会话以树形 JSONL 保存在本地；命令默认在 OS sandbox 中运行并禁止联网；API key 不传给子进程；每次成功 patch 都生成持久且带冲突保护的 checkpoint。
- 无需重学工作流。 支持 AGENTS.md、CLAUDE.md、Agent Skills、MCP、hooks、项目 trust、后台任务、 JSONL/CI、RPC 和 VS Code 入口。

与 DeepSeek Harness 以及更成熟的 Claude Code、Codex 的事实对比见产品对比。我们不认为功能清单能够证明 DeepSeek-Harness-Desktop 全面更好；项目应在真实仓库任务上按成功率、耗时、成本、安全和人工接管率进行评测。

快速开始

要求 Node.js 22.19+ 和 Git。DeepSeek-Harness-Desktop 运行时也使用 rg；安装器会准备 pnpm，并在 macOS 可用时通过 Homebrew 安装 ripgrep。

从 npm 安装：

npm install -g deepseek-harness-desktop

也可以安装最新源码版本：

curl -fsSL /scripts/install.sh | sh

确认 ~/.local/bin 已加入 PATH，然后启动 DeepSeek-Harness-Desktop：

deepseek-harness-desktop -C /path/to/project

全新安装进入 TUI 后输入 /login 选择供应商。认证成功后 DeepSeek-Harness-Desktop 会选择该 provider 的默认模型；非交互命令和未显式指定 provider 的配置仍默认使用 DeepSeek。

| 供应商 | ID | 认证方式 |
| DeepSeek | deepseek | API key |
| OpenAI Codex | openai-codex | 符合条件的 ChatGPT 套餐 |
| OpenAI | openai | API key |
| Anthropic | anthropic | Claude 账号或 API key |
| OpenRouter | openrouter | OpenRouter 账号或 API key |
| Z.AI Coding Plan | zai | API key |
| Kimi For Coding | kimi-coding | Kimi Code 账号或 API key |
| MiniMax | minimax | API key |
| xAI / Grok | xai | Grok/X 账号或 API key |
| OpenCode Zen Go | opencode-go | API key |

/login 和 --provider 也接受 kimi、grok 这两个易记别名。

配置 DeepSeek 时，DeepSeek-Harness-Desktop 会遮罩 API key，然后提供可选的 API base URL；直接回车使用 https://api.deepseek.com，也可以填写兼容 DeepSeek/OpenAI 的第三方网关。默认优先把凭证保存到操作系统钥匙串；无 UI 进程或钥匙串不可用时回退到权限为 0600 的 ~/.deepseek-harness-desktop/auth.json。
endpoint 保存到权限为 0600 的 ~/.deepseek-harness-desktop/config.json。
优先级为 --base-url、DEEPSEEK_BASE_URL、本地保存值、DeepSeek 官方地址。如果不希望保存密钥：

export DEEPSEEK_API_KEY="sk-..."
export DEEPSEEK_BASE_URL="https://api.deepseek.com"
deepseek-harness-desktop -C /path/to/project

也可以在进入 TUI 前完成认证：

deepseek-harness-desktop login deepseek # DeepSeek API key
deepseek-harness-desktop login openai-codex # 浏览器 OAuth，使用 ChatGPT 套餐限额 deepseek-harness-desktop login openai # 安全输入 OpenAI API key deepseek-harness-desktop login anthropic # Claude 账号或 Anthropic API key deepseek-harness-desktop login openrouter # OpenRouter 账号或 API key deepseek-harness-desktop login opencode-go # OpenCode Zen Go API key

选择的 provider 和模型会保存供后续启动使用，也可以随时覆盖：

deepseek-harness-desktop --provider openai-codex --model gpt-5.6-sol -C /path/to/project
deepseek-harness-desktop --provider deepseek --model deepseek-v4-flash -C /path/to/project

DeepSeek-Harness-Desktop 的全局数据统一保存在 ~/.deepseek-harness-desktop：

~/.deepseek-harness-desktop/settings.json TUI 与运行时偏好 ~/.deepseek-harness-desktop/config.json 存储策略与 DeepSeek endpoint ~/.deepseek-harness-desktop/auth.json 仅当前用户可读的凭证回退 ~/.deepseek-harness-desktop/credential-metadata.json 不含密钥的钥匙串索引 ~/.deepseek-harness-desktop/state.sqlite 会话元数据与桌面运行状态 ~/.deepseek-harness-desktop/skills/ 全局 skills ~/.deepseek-harness-desktop/extensions/ 全局 extensions ~/.deepseek-harness-desktop/mcp.json 全局 MCP servers ~/.deepseek-harness-desktop/hooks.json 全局 hooks ~/.deepseek-harness-desktop/sessions/YYYY/MM/DD/ JSONL 会话正文 ~/.deepseek-harness-desktop/archived_sessions/ 已归档会话

顶层的 sessions/.jsonl 是为当前终端运行时保留的硬链接兼容入口，与日期目录中的正文指向同一个 inode，不会重复占用空间。JSONL 是会话正文的唯一事实来源；SQLite 只保存可搜索的会话元数据、置顶/归档状态和文件指纹。

可以在 ~/.deepseek-harness-desktop/config.json 中配置凭证与历史记录策略：

{
"cli_auth_credentials_store": "auto",
"history": { "persistence": "save-all" }
}

凭证模式支持 auto、keyring、file。把历史策略设为 none 后，新会话不会写入正文。
DEEPSEEK_HARNESS_DESKTOP_SQLITE_HOME 可单独迁移 SQLite 状态目录。

可用 DEEPSEEK_HARNESS_DESKTOP_HOME 修改整个目录，用 DEEPSEEK_HARNESS_DESKTOP_SESSIONS_DIR 单独修改会话目录。DeepSeek-Harness-Desktop 不再继承 PI_CODING_AGENT_DIR。首次启动会把旧的 ~/.deepseek-harness-desktop/agent 内容无损复制到新目录，不删除、不覆盖已有文件。项目 skills 建议使用可移植的 .agents/skills/ 约定。

默认配置

全新安装使用：

model deepseek-v4-flash
transport responses
thinking max
harness minimal
permission auto
sandbox workspace-write
network blocked

默认 minimal harness 只暴露少量高杠杆工具：沙箱命令、后台进程交互、freeform patch 和并行 delegation。--harness safe 会额外提供显式文件读取、文件搜索和自动语言诊断。

常用启动方式

新会话 deepseek-harness-desktop -C ./my-project

继续或选择历史会话 deepseek-harness-desktop -C ./my-project --continue deepseek-harness-desktop -C ./my-project --resume

一次性输出、JSONL 自动化或 IDE RPC deepseek-harness-desktop -C ./my-project -p "解释认证流程" deepseek-harness-desktop -C ./my-project --mode json -p "修复 lint 并运行测试" deepseek-harness-desktop -C ./my-project --mode rpc

使用支持视觉的模型检查截图 deepseek-harness-desktop --provider openai-codex @screenshot.png "解释这个错误"

在 TUI 中粘贴 PNG、JPEG、GIF 或 WebP 图片并输入问题即可。DeepSeek-Harness-Desktop 会立即把终端插入的本地路径
替换为 [Image #N]，并把图片数据作为 attachment 随消息发送；每轮最多支持 8 张图片，每张最大
20 MB。

TUI 常用命令：

| 命令 | 作用 |
| /plan | 进入或退出结构化只读规划 |
| /permissions | 查看或切换 plan、ask、auto、full 权限 |
| /status | 查看模型、context、缓存命中、token、费用和会话信息 |
| /diff | 查看当前 patch transcript |
| /checkpoints / /undo | 查看或恢复持久 checkpoint |
| /new / /clear | 清除当前 context 并开始一个新会话（两者等价） |
| /resume / /fork / /tree | 导航树形本地会话 |
| /compact | 压缩旧 context，同时保留当前工作状态 |
| /jobs | 查看可重连的后台命令 |
| /mcp / /agents / /doctor | 查看集成、agent 和运行状态 |
| /login [provider] | 选择并认证支持的模型供应商 |
| /model | 选择已配置的模型，并保存选择 |
| /effort ... | 调整当前模型的 reasoning effort |

输入 / 查看全部命令，输入 /hotkeys 查看快捷键。

安全模型

权限决定 DeepSeek-Harness-Desktop 什么时候询问；sandbox 决定命令实际上能访问什么。

| 模式 | 行为 |
| plan | 只读调查；隐藏写入、delegate 和 MCP 工具 |
| ask | 命令、写入、delegate 和 MCP 都需要批准 |
| auto | 普通工作区操作自动执行；破坏性命令、联网、宿主机访问和外部 MCP 仍受控 |
| full | 可信模式，命令拥有不受限的宿主机文件系统和网络访问 |

默认命令边界是 workspace-write 且禁止联网。命令需要联网或宿主机访问时，TUI 会提供仅本次允许 / 本次会话始终允许这条命令 / 拒绝，然后用最小必要权限自动重试。--network 可以为本次运行预授权网络；--permission full 只应用于完全可信的工作区。deepseek-harness-desktop -y 是明确的 YOLO 快捷方式：本次运行直接信任项目资源、跳过工具审批、关闭 sandbox 并开放网络。

macOS 使用 Seatbelt；Linux 和 Windows 使用配置好的 Docker sandbox：

export DEEPSEEK_HARNESS_DESKTOP_SANDBOX_IMAGE="your-reviewed-image:tag"
deepseek-harness-desktop -C ./project --sandbox workspace-write

没有可用 sandbox 后端时，DeepSeek-Harness-Desktop 会 fail closed，不会悄悄在宿主机运行。

DeepSeek 专用适配

- Responses API 无状态；DeepSeek-Harness-Desktop 从本地会话树回放消息、reasoning item 和工具结果。
- Adapter 会删除 DeepSeek 不支持的 OpenAI store、cache retention 和 include 字段。
- Thinking 模式会删除 DeepSeek 忽略的采样参数，并支持 low、high、max effort。
- apply_patch 使用原生 freeform custom tool，避免大 diff 的 JSON 转义。
- Prompt 和工具顺序保持稳定，为 DeepSeek 自动前缀缓存保留可复用前缀。
- --web 加入 DeepSeek 服务端 Web Search，不代替本地仓库搜索。

这些转换只在当前 provider 为 deepseek 时执行；其他供应商使用运行时内置的原生实现。
Provider API key 不会传给命令、hooks 或 stdio MCP server。

扩展与自动化

- 分层读取 AGENTS.md 和 CLAUDE.md
- 用户级和项目级 Agent Skills
- 可信项目 hooks 与 MCP server
- 可重连后台命令
- 面向 CI 的 JSONL，以及完整 stdin/stdout RPC 模式
- 可复用的 deepseek-harness-desktop-core 包及其内置 headless RPC worker
- apps/desktop 中的原生 Electron 桌面客户端
- editors/vscode 中的 VS Code 扩展
- safe harness 自动发现 TypeScript、Pyright、Rust、Go 和 Swift diagnostics

图形客户端和 IDE 集成可以直接安装 deepseek-harness-desktop-core，不要求用户全局安装 CLI。Core 提供凭证、设置 API 和类型化 RPC client，使用与终端版完全相同的 Agent、工具、权限和本地会话格式：

import { createDeepSeekHarnessDesktopRpcClient } from "deepseek-harness-desktop-core/rpc";

const client = createDeepSeekHarnessDesktopRpcClient({ cwd: "/path/to/project" });
await client.start();
client.onEvent((event) => render(event));
await client.prompt("检查这个仓库");

普通 deepseek-harness-desktop tarball 会内嵌相同版本的 Core 构建，因此现有 CLI 安装不会新增运行时 registry 依赖，也不会改变命令、配置或会话行为。
桌面端通过 monorepo 的 workspace: 直接依赖 Core，并把对应 Core 构建内置到安装包中，避免开发期间源码版本与 npm 版本发生漂移；用户无需另外安装 Core 或系统 Node.js。
经过签名与 Apple 公证的 macOS 安装包，以及 Windows、Linux 安装包，可从项目发布页下载。

从源码构建

git clone
cd deepseek-harness-desktop
corepack enable
pnpm install
pnpm check
pnpm dev -C /path/to/project

常用验证命令：

pnpm check # 类型检查、测试和生产构建
pnpm desktop:check # 桌面端类型检查、测试和生产构建
pnpm smoke:live # 使用真实 DeepSeek API 的修改与测试 smoke flow
pnpm acceptance:live # 完整真实 API 功能验收

日常开发提交到 dev；带新版本号的提交合并到 main 并通过 CI 后，会自动创建对应的 GitHub Release 并发布 npm 包。详细流程见 Releasing DeepSeek-Harness-Desktop。

当前边界

- DeepSeek V4 Flash 仍只接受文本输入；截图等图片任务需要切换到支持视觉的模型。
- ChatGPT 套餐登录受账号可用模型、用量限制和 workspace 权限约束；OpenAI API key 的用量由 API 平台单独计费。
- VS Code 扩展是本地集成，尚未发布到 Marketplace。
- Linux 和 Windows 的隔离能力取决于配置的 Docker 镜像。
- DeepSeek Harness 本身仍处于快速迭代的 v0.1 开发者预览；DeepSeek-Harness-Desktop 不跟踪它的插件 API，而是构建自己的本地 runtime。
- DeepSeek-Harness-Desktop 仍是早期项目；Claude Code 和 Codex 当前拥有更广泛的 IDE、云端、多模态和生态支持。

我们不认为功能清单能够证明 DeepSeek-Harness-Desktop 全面更好。项目应在真实仓库任务上按成功率、耗时、成本、安全和人工接管率进行评测。

License

MIT