dsh-satori

Readme

# dsh-satori

DeepSeek Harness（DSH）的 Satori 协议适配器，通过 Satori Events WebSocket 接收事件，并通过 HTTP API 回复消息

## Transport

- 连接 `${eventsUrl}/v1/events`，发送 Satori `IDENTIFY` 帧
- 处理 `READY`、`EVENT`、`PING` 和 `PONG`，服务端支持时使用最新事件序号 `sn` 恢复连接
- 通过 `POST ${apiUrl}/v1/message.create` 回复消息，并携带 Satori 平台与用户请求头

传输层接收 Satori 事件；只有 `message-created` 事件创建 Agent 交互，其余事件不创建会话或回复。WebSocket 入站负载上限为 1 MiB。

## 安装

```bash
dsh plugin --profile web add dsh-satori
```

## 配置

| 字段                | 默认值                  | 说明                                 |
| ------------------- | ----------------------- | ------------------------------------ |
| `apiUrl`            | `http://127.0.0.1:5140` | Satori HTTP API base URL             |
| `eventsUrl`         | `ws://127.0.0.1:5140`   | Satori Events WebSocket 地址         |
| `tokenRef`          | `SATORI_ACCESS_TOKEN`   | 访问令牌的 DSH credential ref        |
| `platform`          | `satori`                | Satori 平台名称                      |
| `userId`            | 空                      | Satori 账号用户 ID                   |
| `reconnectInterval` | `5000`                  | 重连间隔（毫秒）                     |
| `requestTimeout`    | `30000`                 | HTTP API 请求及图片下载超时（毫秒）  |
| `heartbeatInterval` | `30000`                 | WebSocket 心跳间隔（毫秒），`0` 禁用 |
| `commandPrefix`     | 空                      | 非空时要求此前缀，并从 prompt 移除   |
| `respondToPrivate`  | `true`                  | 响应私聊                             |
| `respondToGroup`    | `true`                  | 响应群聊                             |
| `groupMentionOnly`  | `true`                  | 群聊要求提及机器人                   |
| `userAccessMode`    | `disabled`              | `disabled`、`allowlist`、`blocklist` |
| `userIds`           | `[]`                    | 用户 ID 列表                         |
| `groupAccessMode`   | `disabled`              | `disabled`、`allowlist`、`blocklist` |
| `groupIds`          | `[]`                    | 群 ID 列表                           |

数组在设置 UI 中每行一个 ID，保存时去空白并且去重。token 存入 DSH credentials，配置只保存引用名称。

```yaml
- id: satori
  name: dsh-satori
  config:
    apiUrl: http://127.0.0.1:5140
    eventsUrl: ws://127.0.0.1:5140
    tokenRef: SATORI_ACCESS_TOKEN
    platform: satori
    userId: ''
    reconnectInterval: 5000
    requestTimeout: 30000
    heartbeatInterval: 30000
    commandPrefix: ''
    respondToPrivate: true
    respondToGroup: true
    groupMentionOnly: true
    userAccessMode: disabled
    userIds: []
    groupAccessMode: disabled
    groupIds: []
```

## 消息与回复

- 访问控制顺序为私聊/群聊开关、用户名单、群消息的群名单，最后是提及与前缀。ID 转为字符串后进行匹配；空 allowlist 拒绝全部会话，空 blocklist 允许全部会话

- 回复由会话作用域内的 `satori_reply` 提交候选；同一轮多次调用时以后一次为准，仅在 Agent 本轮进入 idle 后向当前来源发送一次文本回复。插件只开放 `message.create`，不会转发 agent loop 的中间助手文本

- `satori_reply` 支持引用入站消息。当前版本不上传出站图片；若候选包含图片则记录警告并继续发送其中的文本

- 入站图片只接受公网 `http(s)` URL 或带媒体类型的 `data:` URL，限制重定向、总下载时间和字节数后经 DSH attachments 保存 durable ref；不读取 Satori 服务端本地路径，单独 `base64://` 因缺少可信媒体类型而拒绝

- 有 session persistence 时，先以 `list()` 精确判断存在再恢复会话，否则创建一个新会话；恢复会话错误时不会回退。Satori API 无法删除 DSH 会话历史，历史需在 DSH 侧管理

## 开发

```powershell
yarn install
yarn lint
yarn build
```

许可证：MPL-2.0