# dsh-mcp-server

把 **DeepSeek Harness 的 Agent**（`dsh`，带全套工具：文件、终端、网页搜索、子代理、工作流的编码 Agent）通过 [Model Context Protocol](https://modelcontextprotocol.io) 暴露成本机可用的**模型后端**，并同时暴露"**读懂我 / 改造我**"的接口。

```
┌────────────────────────────┐        stdio / HTTP         ┌──────────────────────────────┐
│  其他 Agent / MCP 客户端     │  ────────────────────────▶  │        dsh-mcp-server         │
│  (Claude Desktop, Cursor,  │                            │  方向A：驱动我（消耗我的额度）  │
│   Claude Code, 自定义程序)   │                            │  方向B：读懂我/改造我（便宜）   │
└────────────────────────────┘                            └──────────────┬───────────────┘
                                                                         │ spawn
                                                              ┌──────────▼───────────────┐
                                                              │  dsh Agent（完整工具链）    │
                                                              │  DeepSeek 模型（默认）      │
                                                              └──────────────────────────┘
```

## 两个方向

### 方向 A：驱动我 —— 消耗 DeepSeek Harness 额度，**必须用户确认**

`dsh_ask` / `dsh_converse` / `dsh_tool` 每次调用都会拉起一个完整的 dsh Agent 进程，由它（用 DeepSeek 模型）实际干活：读写文件、跑命令、搜网页、派子代理。**这消耗的是 DeepSeek Harness 的 token 额度**，所以：

1. 调用先返回 `confirmation_required`（**此时不消耗任何额度**），并明确告知"将消耗 DeepSeek Harness 额度"；
2. 调用方必须把这个请求展示给用户（MCP 客户端通常会自动展示工具调用）；
3. 用户批准后调用 `dsh_confirm(requestId, approve=true)` 才真正执行；或 `dsh_deny(requestId)` 取消。

每个待确认请求也会在服务器 stderr 打一行醒目的警告。未确认的请求 10 分钟过期。

> ⚠️ 风险开关：`DSH_MCP_AUTO_APPROVE=1` 会跳过确认闸门（适合无人值守/完全可信环境）。单次调用也可传 `confirm: false` 跳过。

### 方向 B：读懂我 / 改造我 —— 消耗**对方**的 token，服务器侧很便宜

其他 Agent 想理解"我是什么、怎么设计的、怎么给我做插件/改配置"时，走这些接口（服务器只做本地读取/校验，**不消耗 dsh 模型额度**；对方模型把结果读进自己的上下文，消耗的是对方自己的 token）：

| 接口 | 类型 | 内容 |
|---|---|---|
| `dsh_self` | 工具 | 完整设计快照：后端模型/版本、人设模板、plan-mode 规则、挂载的 81 个插件行、工作区与配置路径、凭据键名（值打码）、可发现技能 |
| `dsh://self/persona` | 资源 | 人设与系统提示组件（模板、指令上限、plan-mode 全文） |
| `dsh://self/tools` | 资源 | 挂载的插件行清单 + 工具族可用性 |
| `dsh://self/settings` | 资源 | `$DSH_HOME/settings.yaml`（密钥打码） |
| `dsh://self/credentials` | 资源 | 已配置凭据的**键名**（值永不暴露） |
| `dsh://self/skills` | 资源 | 技能清单（内置预设 + 用户/项目技能） |
| `dsh://self/skills/{name}` | 资源模板 | 某个技能的 SKILL.md 正文 |
| `dsh_plugin_contract` | 工具 | 给"想改造我"的 Agent 看的插件/配置改造契约（profile/patch/bundle/skill 的格式与安全规则） |
| `dsh_patch_config` | 工具 | 提议修改配置：默认 dry-run 用 dsh 自己的解析器校验（不写盘）；真正写入会备份原文件 + 要求用户确认 |

典型用法：外部 Agent 先读 `dsh://self/*` 资源理解设计（花它的 token），再调用 `dsh_patch_config` 提出配置修改（比如换模型、挂新技能、停用某个插件），或依据 `dsh_plugin_contract` 给本机写一个 dsh 插件。

## 快速开始

```powershell
cd E:\DeepSeek Harness\dsh-mcp
npm install          # 安装 @modelcontextprotocol/sdk

# 冒烟测试：不经过 MCP，直接验证 dsh Agent 后端可用
node scripts/smoke.mjs

# 以 stdio 传输启动服务器（MCP 客户端的标准方式）
node src/index.js
```

服务器会自动发现本机安装的 `dsh`（扫描 npx 缓存 / npm 缓存 / 本目录），无需配置。
找不到时用环境变量指定：`DSH_MCP_DSH_BIN=C:\...\@deepseek-ai\dsh\lib\bin.js`。

### 接入 Claude Desktop

编辑 `%APPDATA%\Claude\claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "dsh": {
      "command": "node",
      "args": ["E:\\DeepSeek Harness\\dsh-mcp\\src\\index.js"]
    }
  }
}
```

### 接入 Claude Code / Cursor / VS Code

分别使用 `examples/claude-code.json`、`examples/cursor-mcp.json`、`examples/vscode.json`。

### 接入你自己的 Agent（HTTP 方式）

```powershell
node src/index.js --transport http --port 3005
# 端点：http://127.0.0.1:3005/mcp  （Streamable HTTP）
```

## 工具清单

| 工具 | 方向 | 说明 |
|---|---|---|
| `dsh_ask` | A（消耗额度） | 一次性任务交给全新 dsh Agent，返回最终回复 + 元数据。需确认。 |
| `dsh_converse` | A（消耗额度） | 多轮对话（服务端按 `sessionId` 记历史并注入）。需确认。 |
| `dsh_tool` | A（消耗额度） | 让 Agent 直接调某个具体工具并原样回报。需确认。 |
| `dsh_confirm` | — | 批准/取消一个待确认请求（`approve: true/false`）。 |
| `dsh_pending` | — | 列出当前等待确认的请求（诊断）。 |
| `dsh_new_session` | — | 生成新 `sessionId`。 |
| `dsh_reset` | — | 清空会话记忆。 |
| `dsh_status` | — | 诊断：dsh 版本、模型、工具族、待确认数等。 |
| `dsh_self` | B | 设计快照（人设/插件行/路径/技能/凭据键名）。 |
| `dsh_patch_config` | B | 校验/写入配置 patch（dry-run 默认，写盘需确认+备份）。 |
| `dsh_plugin_contract` | B | 插件与配置改造契约文档。 |

## 环境变量

| 变量 | 默认值 | 说明 |
|---|---|---|
| `DSH_MCP_DSH_BIN` | 自动发现 | `@deepseek-ai/dsh/lib/bin.js` 绝对路径 |
| `DSH_MCP_PROFILE` | `headless` | dsh 启动的 profile |
| `DSH_MCP_TIMEOUT_MS` | `300000` | 单次 Agent 调用硬超时 |
| `DSH_MCP_MAX_TASK_CHARS` | `30000` | 任务文本长度上限（Windows 命令行 ~32k） |
| `DSH_MCP_MAX_HISTORY_CHARS` | `12000` | `dsh_converse` 历史注入预算 |
| `DSH_MCP_CONCURRENCY` | `4` | 并行 dsh 进程数上限 |
| `DSH_MCP_AUTO_APPROVE` | 未设置 | `1` = 跳过确认闸门（危险，慎用） |
| `DSH_MCP_APPROVAL_TTL_MS` | `600000` | 待确认请求过期时间 |
| `DSH_PERMISSION_MODE` | `workspace-write` | 传给 dsh Agent 的权限模式 |

## 权限与安全

- dsh Agent 继承 dsh 权限体系：默认 `workspace-write`（只能写工作目录），可调 `read-only` / `danger-full-access`。
- 方向 A 的所有执行都经过确认闸门，额度披露明确。
- 方向 B 只读路径不打码任何密钥值；写路径（`dsh_patch_config`）默认 dry-run、写盘前自动备份、需要确认，并警告 home 层会影响所有 profile（含运行中的 Web UI）。
- 会话持久化在 `~/.dsh/sessions`，凭据共用 `~/.dsh/.credentials.yaml`。
- 服务器只监听本机（stdio 管道 / 127.0.0.1）。

## 换模型（方向 B 的典型用法）

默认模型来自 dsh 的 `agent-default-model`（本机 `deepseek-official / deepseek-v4-flash`）。改法：

1. **用 `dsh_patch_config`**（推荐）：提交 patch 到 `home` 层，dry-run 校验通过、用户确认后写入（自动备份）。示例 patch：
   ```yaml
   - id: agent-default-model
     config:
       provider: deepseek-official
       model: deepseek-chat
   ```
2. **改全局设置**：编辑 `~/.dsh/settings.yaml` 的 `agent-default-model` 段。
3. **换整套 profile**：`DSH_MCP_PROFILE` 指定其它 profile（不同工具集/人设）。

## 已知限制

- 方向 A 每次调用是新进程（约 2~3 秒冷启动 + 模型响应），无流式，任务文本 ≤ ~30k 字符。
- 确认闸门依赖调用方把 `confirmation_required` 展示给用户；若调用方是无人值守程序且未设 `DSH_MCP_AUTO_APPROVE`，请求会一直挂着直到过期。
- 资源/工具数量：6 个资源 + 11 个工具。

## 开发与测试

```powershell
node scripts/smoke.mjs              # 仅测 dsh 后端（无 MCP）
node scripts/demo.mjs               # 演示：确认闸门 + 读懂我 + 改配置提议
node scripts/mcp-client-test.mjs    # stdio 端到端：闸门/拒绝/多轮/自省/patch/资源
node scripts/http-client-test.mjs   # HTTP 端到端（自动批准模式）
```

## 目录结构

```
dsh-mcp/
├── src/
│   ├── index.js     # CLI 入口（stdio / HTTP 传输）
│   ├── server.js    # MCP 工具与资源注册
│   ├── dsh.js       # dsh 子进程运行器（spawn/超时/输出捕获/并发闸门）
│   ├── approvals.js # 确认闸门（额度披露、待确认队列、过期）
│   ├── self.js      # 自省：设计快照、技能发现、配置路径、插件契约
│   └── sessions.js  # 会话记忆与多轮提示组装
├── scripts/         # 冒烟 + 演示 + 端到端测试
└── examples/        # 各客户端接入配置
```