@dsh-messaging/messaging

Readme

# dsh-messaging 📨

[English](README.md) | [中文](README.zh.md)

Multi-platform messaging plugin for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).

One plugin, many IM platforms. Configure once, switch between Feishu/Telegram/Discord/WeCom with capability auto-degradation.

## Features

- 🌉 **MessagePlatform abstraction** — unified interface for all IM platforms
- 🔌 **Plugin architecture** — each platform is a drop-in adapter
- ⚡ **Capability degradation** — unsupported features get automatic user-friendly warnings
- 📝 **Markdown auto-downgrade** — platforms that don't render Markdown (Feishu!) get plain text automatically
- 🔒 **Production-hardened** — message dedup, per-chat serial processing, token auto-refresh (battle-tested in Hermes Agent 3+ months)

## Supported Platforms

| Platform | Text | Markdown | Image | Audio | Video | File | Card | Reaction | Thread | Typing | Push |
|----------|------|----------|-------|-------|-------|------|------|----------|--------|--------|------|
| Feishu   | ✅ | ❌ | 🔨 | 🔨 | 🔨 | 🔨 | ✅ | ✅ | ✅ | ❌ | ✅ |
| Telegram | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ |
| Discord  | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ |
| WeCom    | ✅ | ❌ | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ |

❌ = platform doesn't support it → auto-downgrade with user warning
🔨 = platform supports it but not yet implemented in this plugin
🚧 = planned for future releases

## Quick Start

```sh
# Install into your DSH profile
dsh plugin --profile web add github:andiven/dsh-messaging
```

```yaml
# cordis.patch.yml
- id: messaging
  name: '@dsh-messaging/messaging'
  config:
    platform: feishu
    feishu:
      appId: env:FEISHU_APP_ID
      appSecret: env:FEISHU_APP_SECRET
      mode: websocket
    autoConnect: true
```

### Prerequisites

**Feishu:** Create a self-built app at [open.feishu.cn](https://open.feishu.cn), enable `im:message` and `im:message:send_as_bot` permissions, subscribe to `im.message.receive_v1` via long connection mode, then publish.

**Telegram:** Create a bot via [@BotFather](https://t.me/BotFather), get the bot token.

**Discord:** Create an application at the [Discord Developer Portal](https://discord.com/developers/applications), add a Bot, enable the **Message Content** privileged intent, invite it to your server with the `bot` scope and `Send Messages`/`Read Message History` permissions, and grab the bot token.

**WeCom:** Create a self-built app in the [WeCom admin console](https://work.weixin.qq.com/wework_admin), note the Corp ID, the app's Secret and AgentId. Receiving messages requires registering an HTTP callback URL (Corp ID, Token, EncodingAESKey) in the console pointing at this plugin's callback server — omit `wecom.callback` to run send-only.

## How It Works

```
User sends message in Feishu/Telegram
  ↓
Adapter receives event → normalizes to InboundMessage
  ↓
DshBridge calls agent.followup(text)
  ↓
DSH Agent processes (LLM + tools)
  ↓
session/event: assistant/chunk → buffered until turn/end
  ↓
DshBridge sends complete reply via platform.sendMessage()
  ↓
Capability auto-check: Markdown → plain text for Feishu, etc.
```

## Key Features

- **CapabilitySet** — each platform declares 12 typed capabilities; the agent can query what's possible *before* acting
- **Auto-degradation** — unsupported features trigger user-friendly bilingual warnings
- **Streaming buffer** — assistant text is accumulated and sent as a complete message (not per-token)
- **Retry with backoff** — exponential backoff + jitter, honors Telegram `retry_after` / Feishu rate-limit codes
- **Per-chat serialization** — preserves message ordering within a conversation
- **Message dedup** — Feishu duplicate events filtered with TTL + cap

## Known Limitations

- Feishu media **send** (image/audio/video/file) not yet implemented (capabilities honestly set to `false`)
- Telegram/WeCom card messages degrade to formatted text; Discord cards degrade to an embed
- Discord Gateway resume is best-effort (falls back to a fresh Identify on non-resumable close codes)
- WeCom inbound requires an HTTP callback (registered in the WeCom admin console); the proprietary AI-Bot WebSocket gateway is a separate, invite-only product and isn't implemented here
- No reconnection state preservation (queued updates may be lost on restart)
- No test suite yet
- Single platform per instance (config selects one platform)

## Development

```sh
git clone https://github.com/andiven/dsh-messaging.git
cd dsh-messaging
npm install
npm run build
```

## License

MIT