@dsh-external/dsh-gateway

Readme

# @dsh-external/dsh-gateway

将 SillyTavern Multi-Platform Gateway 的核心消息总线/适配器移植为 DeepSeek Harness
（dsh）插件，使用户可以在 QQ（OneBot v11）、Telegram、Discord、飞书、QQ 官方机器人、
钉钉等聊天软件中直接向 dsh 下达指令，并收到 dsh 的回复。

## 功能

- 六平台适配器：`qq`、`telegram`、`discord`、`feishu`、`qqofficial`、`dingtalk`
- IM 会话 ↔ dsh 会话双向桥接：
  - 入站：聊天消息作为用户消息 `followup` 到对应 dsh agent
  - 出站：dsh `assistant/message` 自动回传到原聊天
- 本地命令：`/help`、`/status`、`/reset`
- 模型工具：`gateway_send`、`gateway_status`
- HTTP API：`/api/gateway/*`（兼容旧网关主要接口）
- 设置页「网关」面板：可视化编辑各平台配置、凭据、@开关；红绿灯显示启用/运行状态；自动刷新
- 敏感凭据存 dsh credentials（`$DSH_HOME/.credentials.yaml`，0600），设置文件中只存非敏感配置
- 保存后立即生效：非敏感配置走 settings 热更新，连接参数/凭据变化自动重启对应适配器
- 消息队列、重试、分段发送、去重、入站/出站过滤器（移植自旧网关）

## 架构

```
聊天软件 (QQ/TG/Discord/飞书/QQ官方/钉钉)
        │ 适配器标准化 InboundMessage
        ▼
 GatewayService（消息总线 + 队列 + 过滤器）
        │ onMessage
        ▼
 DshBridge
   ├─ 本地命令直接回复
   └─ 映射 sessionId = gw-<platform>-<chatId>
        │ ensureAgent（resume/create dsh agent）
        ▼
 dsh agent-loop（指令解析、工具调用、执行）
        │ session/event assistant/message
        ▼
 DshBridge.sendText → GatewayService.sendMessage → 原聊天回复
```

## 安装

### 1. 克隆插件

```bash
git clone https://github.com/JOJO666888888/dsh-gateway.git
cd dsh-gateway
npm install --no-audit --no-fund
```

### 2. 将插件链接到 dsh profile

编辑你的 dsh profile 的 `package.json`，例如：

```jsonc
// <DSH_HOME>/profiles/web/package.json
"dependencies": {
  "@dsh-external/dsh-gateway": "link:/绝对路径/dsh-gateway"
}
```

Windows 示例：

```json
"@dsh-external/dsh-gateway": "link:D:/dsh-gateway"
```

### 3. 在 profile 的 `cordis.patch.yml` 追加插件行

```yaml
- insert:
    - id: gateway
      name: '@dsh-external/dsh-gateway'
      config:
        enabled: true
        sessionPrefix: 'gw'
        defaultModel: {}
        adapters:
          qq:
            enabled: false
            mode: websocket
            wsUrl: 'ws://127.0.0.1:3000'
            requireMention: true
          telegram:
            enabled: false
            requireMention: true
          discord:
            enabled: false
            requireMention: true
          feishu:
            enabled: false
            appId: ''
            domain: feishu
            requireMention: true
          qqofficial:
            enabled: false
            appId: ''
            sandbox: false
            requireMention: true
          dingtalk:
            enabled: false
            clientId: ''
            requireMention: true
```

### 4. 重启 dsh web

```bash
dsh --profile web
```

> 敏感凭据（Bot Token / AppSecret 等）不要在 `cordis.patch.yml` 中填写，请通过设置界面“网关”面板保存到 dsh credentials。

## 配置

推荐在 dsh web **设置 → 网关** 面板中编辑：

- 非敏感配置（启用状态、@开关、连接参数、默认模型等）保存到 `settings.yaml` 的 `gateway` 分节。
- 敏感凭据（Bot Token、AppSecret、AccessToken 等）保存到 dsh credentials
  （`$DSH_HOME/.credentials.yaml`），界面只显示“已配置/未配置”，不显示明文。

`cordis.patch.yml` 中的 `gateway.config` 作为组合 base 层；面板保存的用户配置覆盖 base。
默认全部 `enabled: false`。

| 平台 | 非敏感关键字段（已精简） | 敏感凭据（credentials ref） |
|------|----------------|------------------------------|
| qq | mode / wsUrl / requireMention | `GATEWAY_QQ_ACCESS_TOKEN` |
| telegram | requireMention | `GATEWAY_TELEGRAM_BOT_TOKEN` |
| discord | requireMention | `GATEWAY_DISCORD_BOT_TOKEN` |
| feishu | appId / domain / requireMention | `GATEWAY_FEISHU_APP_SECRET` |
| qqofficial | appId / sandbox / requireMention | `GATEWAY_QQOFFICIAL_SECRET` / `GATEWAY_QQOFFICIAL_TOKEN` |
| dingtalk | clientId / requireMention | `GATEWAY_DINGTALK_CLIENT_SECRET` |

`defaultModel` 可显式指定新 dsh 会话使用的 `provider`/`model`；留空时使用
`agent-default-model` 的当前选择。

## 从旧网关迁移

旧 `config/gateway.json` 中：

- 非敏感 `adapters.*` → 插件 `adapters.*`，字段名与结构不变
- 敏感字段（botToken/appSecret/accessToken 等）→ 迁移到 dsh credentials，不写入 `cordis.patch.yml`
- `server.authToken` → `GATEWAY_API_TOKEN` credential
- 旧网关的 `session.*` / `messageQueue.*` → 插件 `messageQueue.*`（可选）
- 旧网关的 `runtime.llm` / `antiBagu` / `plugin` 不迁移（dsh 使用自身模型与会话体系）

可运行迁移脚本生成非敏感配置片段与凭据写入指引：

```bash
node D:\预设\harness-plugins\dsh-gateway\scripts\migrate-gateway-config.mjs
```

## HTTP API

| 方法 | 端点 | 说明 |
|------|------|------|
| GET | /api/gateway/health | 健康检查 |
| GET | /api/gateway/status | 适配器状态 + 活动 IM 会话 |
| GET | /api/gateway/config | 脱敏配置 |
| GET | /api/gateway/settings | 读取设置（含凭据已配置状态） |
| POST | /api/gateway/settings | 保存非敏感设置（mutate ops） |
| GET | /api/gateway/credentials | 凭据状态 |
| POST | /api/gateway/credentials/set | 设置凭据 |
| POST | /api/gateway/credentials/unset | 清除凭据 |
| GET | /api/gateway/bindings | 查看会话绑定 |
| POST | /api/gateway/bindings | 新增/更新会话绑定 |
| DELETE | /api/gateway/bindings/:platform/:chatId | 删除会话绑定 |
| GET | /api/gateway/tasks | 查看任务队列 |
| POST | /api/gateway/send | 发送消息 |
| GET | /api/gateway/sessions | 会话列表 |
| GET | /api/gateway/sessions/:platform/:chatId/history | 会话历史 |
| DELETE | /api/gateway/sessions/:platform/:chatId/history | 清空会话 |
| POST | /api/gateway/adapters/:name/start\|stop\|verify | 适配器管理 |
| POST | /api/gateway/verify | 验证全部适配器 |
| GET | /api/gateway/logs | 最近日志 |
| POST | /api/gateway/sync-commands | 同步命令到平台 |

## 使用示例

重启 dsh web 后，打开「设置 → 网关」面板，可编辑各平台配置/凭据/@开关，
查看红绿灯运行状态与活动 IM 会话；保存后立即生效。

在 Telegram 中给机器人发私聊：

```
/help
你好，请列出当前工作区文件
```

dsh 会为 `telegram:<你的ID>` 创建/恢复会话 `gw-telegram-<你的ID>`，执行指令并把
回复发回 Telegram。群聊中需要按适配器配置 `requireMention`（默认 true）@机器人。

支持远程会话绑定命令：

```text
/sessions                列出可绑定 dsh 会话
/bind <sessionId>        将当前聊天绑定到指定 dsh 会话
/bind current            绑定到当前 dsh Web 会话
/unbind                  解除绑定，恢复默认映射
/tasks                   查看当前任务队列
/regex list              查看正则移除规则
/regex test <正则> [替换] [flags]  测试单条移除规则
/regex test-full <文本>   测试全部移除规则
```

正则移除规则配置位于 `gateway.regexFilter.removePatterns`，支持字段：

- `name`
- `enabled`
- `pattern` / `find_regex` / `findRegex`
- `replacement` / `replace_string` / `replaceString`
- `flags`（默认 `gs`）
- `trimStrings` / `trim_strings`

每条普通指令会先收到：

```text
✅ 已收到指令 #<requestId>，正在处理...
```

dsh 回复后收到：

```text
✅ #<requestId> 执行结果：
<dsh 回复内容>
```

dsh agent 也可以主动调用 `gateway_send` 工具，向任意已接入平台发送消息。