# DeepSeek Local Harness

一个开源的 Windows DeepSeek 本地 Agent Harness。它把 **DeepSeek Web 适配器 + Agent Loop + 本地 PowerShell 执行核心 + Electron 桌面 UI** 封装在一起。

普通用户可以直接从 **GitHub Releases** 下载 `DeepSeek-Harness-Setup-*-x64.exe`，双击安装后使用；开发者也可以直接阅读、修改和自行构建全部源码。

![DeepSeek Harness 主界面](docs/images/harness-using.png)

> **非官方项目。** DeepSeek Web 适配层使用逆向的网页协议，可能随着 DeepSeek 网页更新而失效。请使用自己的账号，并自行确认使用方式符合适用条款与法律。

## 核心思路

这个项目不要求模型原生支持 MCP / Function Calling。模型只需要输出一个非常小的文本协议：

```text
<<<PS>>>
Get-ChildItem
<<<END_PS>>>
```

本地 Agent 会严格解析完整响应，交给受监督的 PowerShell runner 执行，再把真实执行结果送回同一个 DeepSeek Web conversation。模型因此可以在**没有原生 MCP tool calling** 的情况下进入本地工具循环。

```text
DeepSeek Web
    ^
    |  Lean Web <-> OpenAI adapter (:8891)
    v
Agent Loop (:8890)
    |
    | <<<PS>>> / PS_RESULT
    v
Local PowerShell Bridge (:8880)
    |
    v
Windows files / commands / npm / Python / Git / long-running processes
```

## 功能

- 单窗口 Electron 桌面 UI
- 两种登录：
  - 当前 Harness 窗口内直接显示 DeepSeek 官方登录页
  - 手动输入 DeepSeek `userToken`
- 登录成功后凭据通过 Electron `safeStorage` 在本机加密保存，并在下次启动时直接复用
- 登录页使用独立 Electron session，与聊天 renderer 隔离
- 官方网页登录检测到 `userToken` 后立即切回 Harness，不再额外等待一次远程验证
- 本地 Lean 2API，只监听 `127.0.0.1`
- 只暴露两个模型：
  - `deepseek-v4-flash` -> `deepseek-r1-search`
  - `deepseek-v4-pro` -> `deepseek-expert-r1-search`
- DeepSeek `conversation_id` 持久复用，不需要每轮重放完整历史
- reasoning / content 分离展示
- FIFO 消息排队、编辑、删除、立即打断
- PowerShell 本地文件和命令操作
- 长进程 `session_id`：read / write / kill
- 禁止 `Start-Process`、后台 `&`、`.NET Process.Start` 等脱离监督的启动方式
- 不执行不完整的模型流

## 登录

首次启动可以直接在当前 Harness 窗口进入 DeepSeek 官方登录页，也可以手动输入 DeepSeek Token。

![DeepSeek Harness 登录页](docs/images/harness-login.png)

网页登录完成后，Harness 会在本机安全保存需要的凭据并进入聊天界面。正常关闭再打开时会复用本地登录态，不要求重复登录。

## 直接安装（推荐）

前往仓库的 **Releases**，下载最新版本：

```text
DeepSeek-Harness-Setup-1.0.0-x64.exe
```

安装完成后直接启动 **DeepSeek Harness**，登录自己的 DeepSeek 账号即可。

安装包已经包含 Electron 和 Python runtime；Windows 10/11 使用系统自带 PowerShell 作为 fallback，因此普通用户不需要另外安装 Python、Node.js 或 PowerShell 7。

> 当前公开构建未购买代码签名证书，Windows SmartScreen 可能在第一次运行时显示未知发布者提示。Release 页面会提供 SHA256。

## 从源码运行

开发环境需要：

- Windows 10/11
- Python 3.11+
- Node.js 20+
- npm

```powershell
powershell -ExecutionPolicy Bypass -File .\setup.ps1
```

然后：

```text
start.vbs
```

## 可选：标准 MCP STDIO 入口

安装包运行并不需要完整 MCP SDK；模型通过轻量文本协议进入同一个 PowerShell runner。开发者如果需要把 runner 直接暴露给标准 MCP Client，可以额外安装：

```powershell
.\.venv\Scripts\python.exe -m pip install -r requirements-mcp.txt
cd mcp
..\.venv\Scripts\python.exe -m src.mcp_server
```

该入口仍然只暴露一个 `powershell` tool。

## 自己构建 Windows 安装包

```powershell
powershell -ExecutionPolicy Bypass -File .\build-release.ps1
```

输出：

```text
release\DeepSeek-Harness-Setup-<version>-x64.exe
```

构建流程会：

1. 构建 Lean DeepSeek Web adapter；
2. 用 PyInstaller 把 Agent backend + MCP bridge 合并为一个 runtime exe；
3. 用 electron-builder + NSIS 构建 Windows 安装器。

发布版 Electron 仅保留 `zh-CN` 与 `en-US` 语言资源；不会裁剪 Prompt、Agent、MCP 或 DeepSeek adapter 逻辑。

构建后如需释放本地磁盘空间，可以先预览清理计划：

```powershell
.\clean-build.ps1
```

确认后执行普通清理：

```powershell
.\clean-build.ps1 -Apply
```

若还要删除可由 `npm ci` 恢复的构建依赖：

```powershell
.\clean-build.ps1 -Apply -Deep
```

脚本始终保留当前版本安装包，并且不会清理聊天数据、登录凭据或源码。

## 本地端口

| Port | Purpose |
| --- | --- |
| `127.0.0.1:8880` | supervised PowerShell bridge |
| `127.0.0.1:8890` | Harness backend + UI |
| `127.0.0.1:8891` | Lean DeepSeek Web adapter（仅登录后启动） |

## 代码结构

```text
app/
  backend/             Agent loop / DeepSeek client / store / prompt
  desktop-electron/    Electron main / auth / service manager
  web/                 Harness renderer
mcp/
  src/runner.py        supervised PowerShell execution core
  src/protocol.py      <<<PS>>> / <<<FINAL>>> parser
  src/http_service.py  local bridge
vendor/deepseek-free-api/
  src/                 reduced DeepSeek Web reverse adapter source
packaging/
  runtime_entry.py     packaged Python runtime entry
```

## 上游与许可证

Lean DeepSeek Web adapter 基于：

- `Fu-Jie/deepseek-free-api`
- Upstream commit: `68b2fc60180b11fe78118daaaef4426c9fbb8df1`
- Upstream license: GPL-3.0

本仓库保留上游来源和 GPL-3.0 许可证。详见 `vendor/deepseek-free-api/UPSTREAM.md` 和根目录 `LICENSE`。

## 安全说明

- 不要把 DeepSeek Token、GitHub Token、聊天数据或本地日志提交到仓库。
- 登录 Token 不会展示在聊天 UI，也不会作为命令行参数传给 2API；它只通过子进程环境变量传递。
- 不完整/断开的 DeepSeek 响应不会触发 PowerShell 执行。
- 本地服务仅绑定 loopback。

## Disclaimer

This project is not affiliated with or endorsed by DeepSeek. The reverse-engineered web protocol is inherently unstable and may stop working when the upstream website changes.