dingtalk-bridge

# DingTalk Bridge Skill

Bridges Claude Code with DingTalk group chat via the DingTalk Stream SDK + OpenAPI.

## Capabilities

| Feature | Description |
|---------|-------------|
| **Send Markdown** | Send rich markdown messages to a DingTalk group |
| **Send Text** | Send plain text messages |
| **Stream Bot** | 24/7 listener: receive @mentions, execute via `claude -p`, reply with results |
| **Auto Conv Discovery** | Conversation ID auto-saved on first @mention |
| **Keepalive** | 20s WebSocket ping prevents DingTalk 30-min timeout |
| **Crash Recovery** | Exponential backoff (5s to 60s) on disconnect |

## Quick Start

### 1. Install

```bash
bash "$CLAUDE_SKILL_DIR/scripts/install.sh"
```

The script will:
- Install Python dependencies (`dingtalk_stream`, `websockets`)
- Prompt for your DingTalk App Key & Secret (or read from env)
- Generate `config.json`
- Create `data/` directory for conversation state
- Optionally create a macOS LaunchAgent for 24/7 operation

### 2. Configure

Set credentials via **environment variables** (recommended):

```bash
export DINGTALK_APP_KEY="your_app_key"
export DINGTALK_APP_SECRET="your_app_secret"
export DINGTALK_WORKDIR="/path/to/your/project"  # optional
```

Or edit `config.json` in the skill directory (see `config.example.json`).

### 3. Get Conversation ID

The bot needs a conversation ID to send messages. Two ways:

**Auto (recommended):** Start the Stream bot, then @mention it in a DingTalk group. The conv ID is saved automatically.

**Manual:** If you already have the `openConversationId` and `robotCode`:
```bash
mkdir -p "$CLAUDE_SKILL_DIR/data"
echo '{"openConversationId":"YOUR_ID","robotCode":"YOUR_ROBOT_CODE"}' > "$CLAUDE_SKILL_DIR/data/conv.json"
```

## Commands

### Send a message

```bash
# Markdown (default)
python3 "$CLAUDE_SKILL_DIR/src/send.py" "**Bold** message with markdown"

# With custom title
python3 "$CLAUDE_SKILL_DIR/src/send.py" --title "Alert" "Server is down!"

# Plain text
python3 "$CLAUDE_SKILL_DIR/src/send.py" --text "Plain text message"
```

### Start the Stream Bot

```bash
python3 "$CLAUDE_SKILL_DIR/src/stream_bot.py"
```

The bot will:
1. Connect to DingTalk via Stream protocol
2. Listen for all @mentions in groups where the bot is added
3. Execute the message content via `claude -p "<message>" --continue`
4. Reply with the result as a markdown message

### Use as Python module

```python
import sys
sys.path.insert(0, "/path/to/dingtalk-bridge/src")
from send import send_markdown, send_text

send_markdown("Daily Report", "**Sent:** 50\n**Opened:** 18\n**Clicked:** 7")
send_text("Simple notification")
```

## Configuration Reference

| Config Key | Env Var | Default | Description |
|-----------|---------|---------|-------------|
| `app_key` | `DINGTALK_APP_KEY` | (required) | DingTalk App Key |
| `app_secret` | `DINGTALK_APP_SECRET` | (required) | DingTalk App Secret |
| `conv_file` | `DINGTALK_CONV_FILE` | `<skill>/data/conv.json` | Conversation metadata path |
| `workdir` | `DINGTALK_WORKDIR` | cwd | Working directory for claude CLI |
| `claude_bin` | `DINGTALK_CLAUDE_BIN` | `claude` | Path to claude binary |
| `max_reply` | `DINGTALK_MAX_REPLY` | `3000` | Max reply length (chars) |
| `keepalive` | `DINGTALK_KEEPALIVE` | `20` | WebSocket keepalive interval (seconds) |

## DingTalk App Setup (Prerequisites)

1. Go to [DingTalk Open Platform](https://open-dev.dingtalk.com/)
2. Create an **Enterprise Internal App** (企业内部应用)
3. Enable **Robot** capability (机器人)
4. Set message receive mode to **Stream** (Stream 模式)
5. Copy the App Key and App Secret
6. Add the bot to a group chat

## Running Tests

```bash
python3 "$CLAUDE_SKILL_DIR/tests/test_dingtalk.py"
```

## Architecture

```
dingtalk-bridge/
├── SKILL.md              # This file
├── config.example.json   # Example configuration
├── config.json           # Your config (gitignored)
├── data/
│   └── conv.json         # Auto-saved conversation metadata
├── src/
│   ├── __init__.py
│   ├── config.py         # Config loader (env > file > defaults)
│   ├── send.py           # Send messages (OpenAPI)
│   └── stream_bot.py     # Stream bot (receive + execute + reply)
├── scripts/
│   └── install.sh        # One-command setup
└── tests/
    └── test_dingtalk.py  # Regression tests
```