deepseek-harness
by xingBaGan
README.md
# DeepSeek Harness & WorkBuddy for Codex
<p align="center">
<strong>简体中文</strong> · <a href="./README.en.md">English</a>
</p>
<p align="center">
<img src="./assets/icon.png" width="128" alt="DeepSeek Harness & WorkBuddy for Codex 图标">
</p>
**DeepSeek Harness & WorkBuddy for Codex** 将 Codex 打造成本地桌面双 Agent 协同与验收中枢。通过标准 MCP(Model Context Protocol)与本地原生通信通道,Codex 能够同时操控并监督 **DeepSeek Harness** 与 **WorkBuddy** 两个桌面级执行器:由 Codex 负责需求拆解、精简派工与独立验收,两套 Agent 各展所长、在各自的原生会话与环境中执行交付。
```text
┌──────────────────────────────────────────────┐
│ Codex (CLI / Desktop) │
│ 总指挥 & 独立验收官 (Supervisor & Reviewer) │
└──────────────┬────────────────┬──────────────┘
│ │
MCP: deepseek-harness│ │ MCP: workbuddy
│ │
▼ ▼
┌──────────────────┐ ┌──────────────────┐
│ DeepSeek Harness │ │ WorkBuddy Gateway│
│ (Desktop Host) │ │ (desktop-queue) │
└─────────┬────────┘ └────────┬─────────┘
│ (Loopback RPC) │ (CDP / Channel RPC)
▼ ▼
┌──────────────────┐ ┌──────────────────┐
│ DeepSeek 真实会话 │ │ WorkBuddy 真实会话 │
│ 深度工程/重构/逆向 │ │ 业务文档/办公自动化│
└──────────────────┘ └──────────────────┘
```
---
## 核心特性与分工优势
| 角色 | 定位与适用场景 | 关键机制 |
| :--- | :--- | :--- |
| **Codex** (中枢) | **任务调度、流水线编排、差分复核与最终交付验收**。不代写执行代码,通过真实产物与测试证据客观核验。 | MCP 客户端、多 Agent 上下文汇聚、返工管理 (Rework) |
| **DeepSeek Harness** | **深度系统架构设计、算法实现、代码重构、Shell 交互与逆向工程**。在原生桌面或 Web 会话中高效运行。 | 官方 Host 插件伴随通信、增量事件流同步、同会话持续监督与接管 |
| **WorkBuddy** | **业务数据整理、文档/表格自动化、企业微信生态集成及办公工作流**。 | CDP 原生唤醒、无感目录会话绑定 (`ensure_workspace`)、持久任务队列 |
---
## 快速开始
### 1. 准备环境
- macOS 系统
- Node.js 22 或更高版本(推荐 Node 22+ LTS)
- 支持插件与 MCP 的 Codex 客户端(桌面版或 `codex` CLI)
- 已安装并已登录的桌面应用:
- [DeepSeek Harness.app](https://github.com/deepseek-ai/DeepSeek-Harness)
- [WorkBuddy.app](https://www.workbuddy.cn/)
---
### 2. 接入 DeepSeek Harness
#### 方式 A:安装 Codex 插件(推荐)
在终端中执行以下命令添加插件:
```sh
codex plugin marketplace add Seann0824/deepseek-harness-for-codex --ref main
codex plugin add deepseek-harness@deepseek-harness-for-codex
```
*macOS 备用路径:若全局 `codex` 被覆盖,可使用 `/Applications/ChatGPT.app/Contents/Resources/codex`。*
#### 方式 B:本地源码或独立 MCP
在本项目根目录构建后注册本地 MCP:
```sh
npm install
npm run check
codex mcp add deepseek-harness -- /path/to/dist/bin.mjs
```
---
### 3. 接入 WorkBuddy 网关
WorkBuddy 支持基于项目目录自动初始化与唤醒原生执行会话:
1. **构建 WorkBuddy 网关**:
```sh
cd codex-workbuddy-gateway
npm install
npm run build
```
2. **配置环境变量 (`.env`)**:
```ini
WORKBUDDY_BACKEND=desktop-queue
WORKBUDDY_NODE_BIN=/Users/你的用户名/.nvm/versions/node/v22.xx.x/bin/node
```
3. **一键注册与 Skill 安装**:
直接运行一键配置脚本:
```sh
./codex-workbuddy-gateway/setup-for-codex.sh
```
*该脚本会自动将 `workbuddy` MCP 注入 `~/.codex/config.toml`,并将 `workbuddy-executor` Skill 部署到 `~/.codex/skills/`。*
---
### 4. 验证接入状态
在终端运行以下命令,确认两端 MCP 服务均处于 `enabled` 状态:
```sh
codex mcp list
```
输出应包含:
- `deepseek-harness`:已启用(控制 DeepSeek Harness)
- `workbuddy`:已启用(控制 WorkBuddy)
---
## 双 Agent 协同使用示例
在 Codex 中启动一个新对话,使用以下模板让 Codex 同时调度两个 Agent:
```text
你现在同时具备操控 DeepSeek Harness 和 WorkBuddy 两个执行器的能力。
请帮我推进项目 /Users/username/my-project:
1. 调用 workbuddy_ensure_workspace 初始化 WorkBuddy 该项目的绑定会话;
2. 将底层的核心逻辑重构与测试编写派工给 DeepSeek Harness 执行;
3. 将项目 API 接口说明文档和测试清单梳理派工给 WorkBuddy 执行;
4. 你作为总指挥负责跟进两边的执行进度;
5. 在两边执行完成后,独立审查代码 diff 与产物文件,确认无误后完成最终验收。
```
---
## MCP 工具参考
### 1. DeepSeek Harness 工具组 (`deepseek-harness`)
| 工具 | 用途 |
| :--- | :--- |
| `start_supervised_desktop_run` | 向现有的 Harness 桌面原生会话派发任务,建立持久跟踪的轮次。 |
| `wait_desktop_run` | 轮询等待桌面端输出,单次最多 30 秒,按轮次返回增量结果。 |
| `continue_supervised_desktop_run`| 审查不合格时,向同一会话追加修改意见,进行同会话返工 (Rework)。 |
| `adopt_running_desktop_session` | 将用户在 Harness 桌面 UI 手动启动的轮次纳入 Codex 的监督状态机中。 |
| `list_desktop_sessions` | 读取本地已有的桌面会话历史与工作区绑定。 |
| `get_desktop_session_history` | 安全读取特定会话历史记录(冷读取,不激活模型)。 |
| `start_run` / `wait_run` / `get_run` | 管理由 MCP 自动拉起的 Harness Web 回环服务及临时会话。 |
| `doctor` | 检查本地 Harness 运行环境、Node、权限模式与数据目录。 |
### 2. WorkBuddy 工具组 (`workbuddy`)
| 工具 | 用途 |
| :--- | :--- |
| `workbuddy_ensure_workspace` | 根据目标绝对目录原生创建、绑定或复用 WorkBuddy 真实会话。 |
| `workbuddy_send_task` | 将任务放入本地持久队列,由后台服务通过 CDP 唤醒桌面执行。 |
| `workbuddy_wait` / `workbuddy_get_task` | 等待并读取 WorkBuddy 执行进度与当前轮次成果上报。 |
| `workbuddy_continue_task` | 保持相同会话与历史上下文,向 WorkBuddy 发送返工要求。 |
| `workbuddy_accept_task` | 经 Codex 独立核对真实产物后,记录最终验收凭证。 |
| `workbuddy_list_models` / `workspaces` | 查询 WorkBuddy 当前可用模型列表与各项目工作区绑定状态。 |
| `workbuddy_health` | 探测 WorkBuddy 桌面端连通性与监听器状态。 |
---
## 安全与隔离机制 (Hardening)
1. **严格的本地回环 RPC**:所有跨进程通信均限制在 `127.0.0.1` 本地回环网络或受保护的本地 Unix Domain Socket(`0700/0600` 权限),不开放公网端口。
2. **沙箱与目录白名单**:默认启用 `workspace-write` 保护策略,支持通过 `DSH_MCP_WORKSPACE_ROOTS` 严格限制只允许访问的项目根目录,拒绝目录穿越。
3. **敏感操作非越权**:
- 当 DeepSeek Harness 触发文件写保护、高危命令审批(Approval)或调用 `ask_user_question` 咨询时,桥接器如实上报 `waiting_input`,**绝不自动代用户越权同意**,必须由用户在桌面端 GUI 界面确认。
- WorkBuddy 的原生权限与首次登录状态同样由用户在原生客户端授权。
4. **独立验收与防伪保证**:
- 执行器报告“完成”不等于任务合格。平台与 Codex 保持严格的“内容验收与格式完成分离”契约,所有完成态必须经过外部 Codex 的实际文件 diff 比对或测试命令核验。
---
## 本地开发与测试
```sh
# 根项目(DeepSeek Harness 桥接器)
npm install
npm run check # 包含 TypeScript 类型检查、Vitest 测试与 Tsdown 构建
npm test # 运行测试用例
# WorkBuddy 网关子模块
cd codex-workbuddy-gateway
npm install
npm test # 运行 160+ 项全套自动化集成测试
npm run build
```
---
## 开源协议
本项目基于 [MIT 协议](./LICENSE) 开源。