dshx

Readme

# dshx

[English](#english) · [中文](#中文)

An extension suite for the [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH) Web GUI: an **MCP client hub** (stdio / Streamable HTTP / SSE) with a **web management console**, plus **skill**, **slash command**, **project & global memory**, and **prompt** management. Plain ESM JavaScript, no build step.

## English

- [中文](#中文) · [↑ Back to dshx](#dshx)

### Modules

| Module | Subpath | What it does |
| --- | --- | --- |
| MCP hub | `dshx/mcp` | Connects MCP servers over **stdio**, **Streamable HTTP** and **SSE**. Per-server state machine (connecting / connected / reconnecting / error), live logs (ring buffer + `$DSH_HOME/dshext/logs/mcp-<id>.log`), discovered-tool list, automatic reconnect with exponential backoff. Discovered tools are bridged to the model as native tools named `mcp__<server>__<tool>`. Model tools: `mcp_status`, `mcp_restart`. |
| Memory | `dshx/memory` | Global memory (`$DSH_HOME/dshext/memory/*.md`) and project memory (`<workspace>/.dsh/memory/*.md`), injected into the system prompt before every model step. Model tools: `memory_list`, `memory_read`, `memory_write`, `memory_delete`. Project-scope writes follow the session sandbox policy (approval + `sandbox_permissions` escalation, same as the built-in `write` tool). |
| Skills | `dshx/skills` | Creates / edits / deletes skill bundles in the roots the harness skill registry already discovers (`$DSH_HOME/skills`, `<workspace>/.dsh/skills`); changes appear in the session skill catalog immediately. Model tools: `skill_create`, `skill_edit`, `skill_delete`. |
| Commands | `dshx/commands` | User-defined slash commands as YAML files (`$DSH_HOME/dshext/commands/*.yaml`, `<workspace>/.dsh/commands/*.yaml`). Named commands are registered eagerly; a universal `/cmd <name> [args]` dispatcher resolves the calling session's project dir, so project commands work in every workspace. `{{args}}` is replaced with the typed input. Model tool: `command_define`. |
| Prompts | `dshx/prompts` | Prompt library (`$DSH_HOME/dshext/prompts/*.md`) registered as ordered system-prompt sections (`dshx:prompts/<name>`, configurable order / enable), a supplementary persona (`$DSH_HOME/dshext/persona.md`), and an assembled system-prompt inspector (rendered with a live agent scope so variables like `{{model}}` resolve). |
| Manager | `dshx/manager` | Serves the web management console at **`http://127.0.0.1:3080/dshext/`** (five tabs: MCP / Skills / Commands / Memory / Prompts, plus a JSON API under `/dshext/api/*`) and injects a floating "⚙ 扩展管理" button into the Web GUI. |

### Installation

#### Method 1 — install as a dsh bundle (persistent)

```sh
dsh plugin --profile web add github:YZz-S/dshx
```

Restart `dsh web`. The `dsh.bundle` entry in `package.json` applies
`cordis.patch.yml`, which mounts the six rows above.

> If you previously added the dshx rows manually to your profile's
> `cordis.patch.yml` (the local `./packages/dshx/...` variant), remove those
> rows first — both share the row ids `dshx-*` and mounting them twice would
> register the tools and routes twice.

#### Method 2 — manual local install (no npm / GitHub)

1. Copy `lib/*.mjs` to a directory inside your profile, e.g.
   `$DSH_HOME/profiles/web/packages/dshx/lib/`;
2. Add the rows from `cordis.patch.yml` to `$DSH_HOME/profiles/web/cordis.patch.yml`,
   replacing `name: dshx/<module>` with `name: ./packages/dshx/lib/<file>.mjs`;
3. Restart `dsh web` (or let the patch watcher hot-apply it).

Dependencies (`@deepseek-ai/*`, `@modelcontextprotocol/sdk`, `chokidar`,
`js-yaml`) all ship with every dsh installation and resolve through the
profile's `node_modules` — the plugin itself has no npm dependencies.

### Quick start

1. Open the Web GUI and click the floating **⚙ 扩展管理** button (or visit
   `http://127.0.0.1:3080/dshext/`).
2. **MCP tab** → 添加 MCP 服务器 → pick a transport:
   - **stdio**: command `npx`, args `-y @modelcontextprotocol/server-github`
     (env `GITHUB_TOKEN` as JSON);
   - **Streamable HTTP**: URL `http://localhost:3000/mcp` + optional JSON headers;
   - **SSE**: URL `http://localhost:3001/sse` + optional JSON headers.
3. The card turns green (`connected`, N 个工具) and the model can call
   `mcp__<id>__<tool>` immediately. Logs and the tool list are on the card.
4. Use the other tabs to write memory / skills / commands / prompt sections,
   or just ask the model to do it (`memory_write`, `skill_create`,
   `command_define`, …).

### MCP server configuration

Server configs live in `$DSH_HOME/dshext/mcp.json` (managed by the console or
the model tools) — example:

```json
{
  "servers": [
    { "id": "github", "name": "GitHub", "transport": "stdio",
      "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "…" } },
    { "id": "web", "name": "Web", "transport": "streamable-http",
      "url": "http://localhost:3000/mcp",
      "headers": { "Authorization": "Bearer …" } },
    { "id": "legacy", "name": "Legacy SSE", "transport": "sse",
      "url": "http://localhost:3001/sse" }
  ]
}
```

### Custom slash commands

```yaml
# $DSH_HOME/dshext/commands/review.yaml
name: review
description: Review the current changes
hint: '[path]'
prompt: |
  Review {{args}} and output an issue list ordered by severity.
```

User-level commands register as `/review`; project commands are callable via
`/cmd review` (and `/cmd` alone lists everything).

### Model-facing tools

`mcp_status` · `mcp_restart` · `memory_list` · `memory_read` · `memory_write` ·
`memory_delete` · `skill_create` · `skill_edit` · `skill_delete` ·
`command_define` — plus every discovered MCP tool as `mcp__<server>__<tool>`.

### Data files

| Feature | Location |
| --- | --- |
| MCP server config | `$DSH_HOME/dshext/mcp.json` |
| MCP logs | `$DSH_HOME/dshext/logs/mcp-<id>.log` |
| Global memory | `$DSH_HOME/dshext/memory/*.md` |
| Project memory | `<workspace>/.dsh/memory/*.md` |
| User skills | `$DSH_HOME/skills/<name>/SKILL.md` |
| Project skills | `<workspace>/.dsh/skills/<name>/SKILL.md` |
| User commands | `$DSH_HOME/dshext/commands/<name>.yaml` |
| Project commands | `<workspace>/.dsh/commands/<name>.yaml` |
| Prompt sections | `$DSH_HOME/dshext/prompts/<name>.md` |
| Supplementary persona | `$DSH_HOME/dshext/persona.md` |

### Development & tests

```sh
# syntax check every module
node --check lib/*.mjs

# 18 smoke checks (mock cordis ctx; real file round-trips; needs the dsh
# dependency tree resolvable — run from an installed copy, or give this
# package a node_modules junction to $DSH_HOME/profiles/node_modules)
node test/selfcheck.mjs

# fixture stdio MCP server used to verify the hub end to end
node test/test-mcp-server.mjs   # then add it in the console:
#   transport stdio, command <path-to-node>, args <this file>
```

### Security

See [SECURITY.md](SECURITY.md). Credentials are environment variables /
config values only — nothing is hardcoded; the console binds to the same
local-only DSH web server (127.0.0.1).

### License

[MIT](LICENSE) © 2026 DeepSeekHarnessPlugins contributors

---

## 中文

[English](#english) · [↑ 返回 dshx](#dshx)

面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）Web GUI 的扩展套件：
**MCP 客户端集线器**（stdio / Streamable HTTP / SSE 三种协议，含状态、日志、工具面板与 Web 管理台），
以及 **技能**、**斜杠命令**、**项目/全局记忆**、**提示词** 四类管理能力。纯 ESM JavaScript，无需构建。

### 模块一览

| 模块 | 子路径 | 说明 |
| --- | --- | --- |
| MCP 集线器 | `dshx/mcp` | 连接 **stdio / Streamable HTTP / SSE** 三类 MCP 服务器；状态机（连接中/已连接/重连中/错误）、实时日志、工具列表、指数退避自动重连；发现到的工具以 `mcp__<服务器>__<工具>` 注册为模型原生工具。模型工具：`mcp_status`、`mcp_restart`。 |
| 记忆 | `dshx/memory` | 全局记忆（`$DSH_HOME/dshext/memory/*.md`）与项目记忆（`<工作区>/.dsh/memory/*.md`），每次模型请求前自动注入系统提示词。模型工具：`memory_list/read/write/delete`。项目范围写入遵循会话沙箱策略（支持审批与 `sandbox_permissions` 升级）。 |
| 技能 | `dshx/skills` | 在技能注册表原生发现的目录（`$DSH_HOME/skills`、项目 `.dsh/skills`）中创建/编辑/删除技能，改动即时进入会话技能目录。模型工具：`skill_create/skill_edit/skill_delete`。 |
| 命令 | `dshx/commands` | YAML 自定义斜杠命令（用户级 `$DSH_HOME/dshext/commands/`、项目级 `.dsh/commands/`）；用户命令直接注册为 `/名称`，`/cmd <名称> [参数]` 按调用会话所在项目解析，`{{args}}` 替换输入参数。模型工具：`command_define`。 |
| 提示词 | `dshx/prompts` | 提示词片段库（注册为带顺序/开关的系统提示词 section）、人设补充（`persona.md`）、以及按活跃 Agent 作用域渲染的完整 System Prompt 组装查看。 |
| 管理台 | `dshx/manager` | 提供 **`http://127.0.0.1:3080/dshext/`** 管理台（MCP / 技能 / 命令 / 记忆 / 提示词 五个标签页 + `/dshext/api/*` JSON API），并在 Web GUI 右下角注入「⚙ 扩展管理」悬浮按钮。 |

### 安装

**方式一 · dsh bundle 安装（持久化，推荐）**

```sh
dsh plugin --profile web add github:YZz-S/dshx
```

重启 `dsh web`。`package.json` 的 `dsh.bundle` 会应用 `cordis.patch.yml` 挂载上面六行。

> 若你此前在 profile 的 `cordis.patch.yml` 里手动加过 dshx 行（`./packages/dshx/...` 本地变体），请先删除——两种方式共用 `dshx-*` 行 id，重复挂载会重复注册工具与路由。

**方式二 · 本地手动安装**

1. 把 `lib/*.mjs` 复制到 profile 内目录（如 `$DSH_HOME/profiles/web/packages/dshx/lib/`）；
2. 把 `cordis.patch.yml` 中的行写进 `$DSH_HOME/profiles/web/cordis.patch.yml`，将 `name: dshx/<模块>` 换成 `name: ./packages/dshx/lib/<文件>.mjs`；
3. 重启 `dsh web`（补丁层支持热重载，通常无需重启）。

依赖（`@deepseek-ai/*`、`@modelcontextprotocol/sdk`、`chokidar`、`js-yaml`）随 dsh 自带，经 profile 的 `node_modules` 解析，插件本身零 npm 依赖。

### 快速开始

1. 打开 Web GUI，点击右下角「⚙ 扩展管理」（或访问 `http://127.0.0.1:3080/dshext/`）；
2. **MCP** 标签 → 添加 MCP 服务器，三种协议任选：
   - stdio：命令 `npx`、参数 `-y @modelcontextprotocol/server-github`（env 填 JSON）；
   - Streamable HTTP：URL + 可选 JSON 请求头；
   - SSE：URL + 可选 JSON 请求头；
3. 卡片变绿（connected，N 个工具），模型即可直接调用 `mcp__<id>__<tool>`；
4. 其余标签页管理记忆/技能/命令/提示词，也可以直接让模型调用 `memory_write`、`skill_create`、`command_define` 等工具代办。

### 数据文件位置

| 功能 | 位置 |
| --- | --- |
| MCP 服务器配置 | `$DSH_HOME/dshext/mcp.json` |
| MCP 日志 | `$DSH_HOME/dshext/logs/mcp-<id>.log` |
| 全局记忆 | `$DSH_HOME/dshext/memory/*.md` |
| 项目记忆 | `<工作区>/.dsh/memory/*.md` |
| 用户技能 | `$DSH_HOME/skills/<名称>/SKILL.md` |
| 项目技能 | `<工作区>/.dsh/skills/<名称>/SKILL.md` |
| 用户命令 | `$DSH_HOME/dshext/commands/<名称>.yaml` |
| 项目命令 | `<工作区>/.dsh/commands/<名称>.yaml` |
| 提示词片段 | `$DSH_HOME/dshext/prompts/<名称>.md` |
| 人设补充 | `$DSH_HOME/dshext/persona.md` |

### 测试

```sh
node --check lib/*.mjs     # 全部模块语法检查
node test/selfcheck.mjs    # 18 项冒烟自检（mock cordis 上下文 + 真实文件往返）
node test/test-mcp-server.mjs  # stdio MCP 测试服务器（在管理台添加后可验证全链路）
```

### 安全与许可

见 [SECURITY.md](SECURITY.md)。凭据只通过环境变量/配置传入，无任何硬编码；管理台绑定 dsh 本地 Web 服务（127.0.0.1）。[MIT](LICENSE) © 2026 DeepSeekHarnessPlugins contributors