npm package: @riseai/sheetsx
Description: Channel plugin for DingTalk Sheet - Automate workflows via SheetsX WebSocket
Author: RiseAI-Labs
Latest version: 2.0.0

# SheetsX - OpenClaw Channel Plugin

Channel plugin for OpenClaw - Automate your DingTalk Sheet workflows via SheetsX.

## Overview

SheetsX is a channel plugin for OpenClaw that seamlessly integrates with DingTalk Sheet (钉钉表格). It enables automation for your spreadsheet workflows, allowing users to submit tasks through DingTalk Sheet shortcuts and receive intelligent responses from OpenClaw AI Gateway.

**Key capabilities:**
- 🤖 AI-driven task processing and response generation
- 🔄 Real-time bidirectional communication via WebSocket
- 📊 Seamless integration with DingTalk Sheet workflows
- ⚡ Streaming responses for long-running AI tasks
- 🔐 Secure authentication with HMAC signatures

## Architecture

```mermaid
flowchart LR
    subgraph DingTalk["钉钉表格"]
        A1["指令列<br/>(任务输入)"]
        A2["结果列<br/>(结果输出)"]
    end

    subgraph Backend["SheetsX Backend"]
        B1["API Server"]
        B2["Nchan Pub/Sub"]
    end

    subgraph Plugin["OpenClaw Plugin<br/>(This Package)"]
        C1["SheetsXClient<br/>(WebSocket Connection)"]
        C2["Channel Handler"]
    end

    subgraph AI["OpenClaw AI"]
        D1["Agent Router"]
        D2["AI Models"]
    end

    A1 --"提交任务"--> B1
    B1 --"Publish"--> B2
    B2 --"WebSocket"--> C1
    C1 --"Dispatch"--> C2
    C2 --> D1
    D1 --> D2
    D2 --"Response"--> C2
    C2 --"Send Result"--> B2
    B2 --"Return"--> B1
    B1 --"返回结果"--> A2
```

## Installation

### Prerequisites

Install OpenClaw CLI first (see [OpenClaw Getting Started](https://docs.openclaw.ai/start/getting-started)):

```bash
pnpm add -g openclaw@latest
```

### Install Plugin

```bash
openclaw plugins install @riseai/sheetsx@latest
```

Expected output:
```
🦞 OpenClaw 2026.1.29 (a5b4d22) — We ship features faster than Apple ships calculator updates.

Downloading @riseai/sheetsx@latest…
Extracting /var/folders/.../riseai-sheetsx-2.0.0.tgz…
Installing to /Users/.../.openclaw/extensions/@riseai/sheetsx…
Installing plugin dependencies…
Installed plugin: @riseai/sheetsx
Restart the gateway to load plugins.
```

## Configuration

Run the channel configuration wizard:

```bash
openclaw channels add
```

Follow these steps:
1. Select **Yes** to enter configuration
2. Select **SheetsX** from the channel list
3. Configure the following:
   - **Nchan server URL**: `https://sheetsx.cn`
   - **Bot App ID**: Your bot's app ID (create via SheetsX web interface)
   - **Bot App Secret**: Your bot's app secret
4. Select **Finish** to save

### Bot Registration

Before configuring, create a Bot through the SheetsX web interface:
1. Log in to your SheetsX account
2. Navigate to OpenClaw settings
3. Click "Create Bot" to generate your `app_id` and `app_secret`

## Plugin Structure

```
src/
├── index.ts      # Plugin entry point & registration
├── channel.ts    # Channel plugin definition & configuration
├── client.ts     # Nchan WebSocket client with HMAC auth
├── gateway.ts    # Message gateway with auto-reconnection
├── bot.ts        # AI message handler & streaming support
├── types.ts      # TypeScript type definitions
├── runtime.ts    # Runtime API management
├── logger.ts     # Structured logging utilities
└── monitor.ts    # Provider monitor (legacy)
```

**Key Components:**
- **SheetsXClient**: Manages WebSocket connections with automatic reconnection and HMAC authentication
- **Gateway**: Handles message routing and ensures reliable delivery
- **Bot Handler**: Processes AI requests with streaming support for real-time responses

## Message Types

### Task Message (from SheetsX)

```typescript
{
  type: 'task',
  channel: 'sheetsx',
  timestamp: '2024-01-01T00:00:00Z',
  data: {
    task_id: 'unique-task-id',
    task: 'Analyze this data...',
    timestamp: '2024-01-01T00:00:00Z',
    bot_app_id: 'bot-xxxxxxxxxx'
  }
}
```

### Result Message (to SheetsX)

```typescript
{
  type: 'result',
  channel: 'sheetsx',
  timestamp: '2024-01-01T00:00:00Z',
  data: {
    task_id: 'unique-task-id',
    result: 'AI response text',
    timestamp: '2024-01-01T00:00:00Z',
    finished: true
  }
}
```

## Development

```bash
# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode
npm run dev

# Run tests
npm test
```

## License

MIT