# dsh-tools-mcp

将 [deepseek-harness](https://github.com/deepseek-ai/deepseek-harness)（DeepSeek AI 开源的 agent harness）中 **极简模式（minimal）** 与 **标准模式（standard）** 的 tools 提取并包装为 **MCP（Model Context Protocol）** 服务器，通过 `--mode` 参数控制暴露哪套工具集。

> 工具 schema、描述文案、输出信封（如 `read` 的 `<path>/<type>/<content>` 格式、`str_replace_editor` 的 view/create/str_replace/insert 语义、`[exit code: N]` 标记）均忠实还原自原仓库 `apps/cli/config/agent-presets/{minimal,standard}/agent.cordis.yml` 及其对应 `packages/*/tool-*` 实现。

## 模式与工具对照

| 模式 | 参数 | 工具 |
|---|---|---|
| **极简模式** | `--mode minimal` | 持久 shell（POSIX 为 `bash`，win32 为 `pwsh`，状态跨调用保持）+ `str_replace_editor` |
| **标准模式** | `--mode standard` | `bash`/`pwsh`（单次执行）、`read`、`write`、`edit`、`read_image`、`glob`、`grep`、`job_output`/`job_list`/`job_kill`、`todo_write`、`ask_user_question`、`web_search`、`get_goal`/`create_goal`/`update_goal`、`plan_mode`/`exit_plan_mode`、`skill` |

标准模式还支持 `--with-web-fetch` 额外暴露 `web_fetch`（原版 standard 预设默认 `fetch: false`）。

## 快速开始

```bash
cd dsh-tools-mcp
npm install
npm run build          # 输出到 dist/

# 极简模式
node dist/index.js --mode minimal --cwd D:/develop/project/dsh-tools-mcp

# 标准模式
node dist/index.js --mode standard --cwd D:/develop/project/dsh-tools-mcp
```

### MCP 客户端配置

```jsonc
// mcp.json / WorkBuddy 自定义连接器
{
  "mcpServers": {
    "dsh-minimal": {
      "command": "node",
      "args": ["D:/develop/project/dsh-tools-mcp/dist/index.js", "--mode", "minimal", "--cwd", "D:/develop/project/dsh-tools-mcp"]
    },
    "dsh-standard": {
      "command": "node",
      "args": ["D:/develop/project/dsh-tools-mcp/dist/index.js", "--mode", "standard", "--cwd", "D:/develop/project/dsh-tools-mcp"]
    }
  }
}
```

两个入口可以同时注册，按需选择极简/标准工具集。

## 全部参数

```
--mode <minimal|standard>    Agent 预设模式（默认 minimal）
--cwd <path>                 工作区根目录，文件工具基于它解析相对路径（默认 process.cwd()）
--shell <auto|bash|pwsh>     shell 后端；auto = win32 用 pwsh，其余用 bash
--shell-timeout-ms <n>       持久 shell 单条命令超时（默认 300000）
--max-output-chars <n>       输出截断上限（默认 16000）
--skills-dir <path>          启用 skill 工具，扫描该目录下的 SKILL.md 子目录
--search-provider <duckduckgo|tavily|bing>   web 搜索后端（默认 duckduckgo）
--search-api-key <key>       tavily/bing 的 API key
--proxy <url>                web 工具的 HTTP(S) 代理，如 http://127.0.0.1:7897
--with-web-fetch             额外暴露 web_fetch
--allow-outside-root         允许文件工具访问 --cwd 之外的路径（默认禁止）
--tools <a,b,c>              显式指定工具/套件清单覆盖模式（见下）
--help / --version
```

### --tools 覆写

`--tools` 接受工具名或套件名，按需暴露子集：

```bash
# 只要文件相关
node dist/index.js --mode standard --tools read,write,edit,glob,grep

# 只要极简模式的编辑器 + 后台任务
node dist/index.js --mode minimal --tools str_replace_editor,job_output,job_list,job_kill
```

套件名：`shell`（持久 shell）、`one-shot`、`fs`、`search`、`jobs`、`todo`、`web`、`ask-user`、`goal`、`plan`、`skill`。

## 设计说明

- **持久 shell**：无 node-pty 依赖，用 stdio 管道驱动长驻 `bash`/`powershell` 子进程；命令以随机 UUID 标记包裹以可靠捕获完成状态与退出码；`cd`/`export` 等状态跨调用保持；超时或 shell 退出时自动重置（与原始 `tool-bash-persistent` 语义一致）。
- **路径安全**：默认文件工具仅允许访问 `--cwd` 工作区内的路径，越界报错提示加 `--allow-outside-root`。
- **web_search 默认 DuckDuckGo**（免 key）；国内网络建议 `--proxy http://127.0.0.1:7897`，或换 `--search-provider tavily --search-api-key <key>`。
- **状态均为进程内（session 级）**：todo/goal/plan/后台任务状态随服务器进程生命周期，重启即清空——与原版"会话级状态"等价。

## 与原版 dsh 的差异（明确说明）

| 项 | 原版 dsh | 本 MCP 包装 |
|---|---|---|
| 持久 shell | node-pty PTY 终端 | stdio 管道长驻进程（无交互提示符，状态保持等价） |
| `ask_user_question` | dsh UI 提问桥 | MCP stdio 下无法同步交互，返回问题文本并指示模型转述给用户 |
| `plan_mode`/`exit_plan_mode` | UI 审批流 | 服务端标志位 + 计划文本回传 |
| subagent_*/workflow/ralph | 依赖 dsh 运行时（LLM 子代理、工作流引擎） | **未包装**——需完整 dsh 运行时，详见下方 |
| grep 引擎 | 内置 ripgrep 二进制 | node 正则实现（常见语法等价，部分 ripgrep 特性不支持） |

**未包装的工具**（原版 standard preset 中的运行时耦合工具，需完整 dsh runtime）：`subagent_control`、`list_agents`、`subagent`、`subagent_fork`、`workflow`、`ralph`。如需这些能力，请直接使用 [deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) 本体。

## 测试

```bash
npm run build
npm test          # 冒烟测试：两种模式工具暴露 + 核心工具行为 + --tools 覆写
node scripts/state-test.mjs   # 持久 shell 状态保持 / 退出码 / 优雅重置（PROXY=... 可测 web_search）
node scripts/bash-test.mjs    # bash 后端验证
```

## 源码参考

提取自 `deepseek-ai/deepseek-harness`（MIT License，master 分支）：

- 模式定义：`apps/cli/config/agent-presets/minimal/agent.cordis.yml`、`.../standard/agent.cordis.yml`
- 工具实现：`packages/shell/tool-bash-persistent`、`packages/fs/tool-str-replace-editor`、`packages/fs/tool-fs`、`packages/fs/tool-fs-search`、`packages/jobs/tool-jobs`、`packages/todo/tool-todo`、`packages/web/tool-web`、`packages/interaction/tool-ask-user`、`packages/goal/tool-goal`、`packages/plan/plan-mode`、`packages/skill/tool-skill` 等