@zzedbot/yunzhijia 1.0.2

package/ALTERNATIVE_INSTALLATION.md

@@ -0,0 +1,61 @@
+# Alternative Installation Methods
+
+Since npm publishing requires 2FA or granular access tokens with bypass permissions, here are alternative ways to install and use the YunzhiJia channel plugin.
+
+## Method 1: Install from GitHub (Recommended)
+
+You can install the plugin directly from the GitHub repository:
+
+```bash
+# Install from the dev branch
+openclaw plugins install https://github.com/zzedbot/channel-yunzhijia
+
+# Or install from a specific tag/release
+openclaw plugins install https://github.com/zzedbot/channel-yunzhijia#v1.0.0
+```
+
+## Method 2: Manual Installation
+
+1. Clone the repository:
+```bash
+git clone https://github.com/zzedbot/channel-yunzhijia.git
+cd channel-yunzhijia
+```
+
+2. Copy to OpenClaw extensions directory:
+```bash
+# Create extensions directory if it doesn't exist
+mkdir -p ~/.openclaw/extensions
+
+# Copy the plugin
+cp -r . ~/.openclaw/extensions/yunzhijia
+```
+
+3. Restart OpenClaw Gateway
+
+## Method 3: Local Development Link
+
+For development purposes, you can link the local directory:
+
+```bash
+openclaw plugins install -l /path/to/your/local/channel-yunzhijia
+```
+
+## Configuration
+
+After installation using any of the above methods, configure the channel as described in DEPLOYMENT.md:
+
+```bash
+openclaw channels add --channel yunzhijia --webhook-token YOUR_WEBHOOK_TOKEN --app-secret YOUR_APP_SECRET
+```
+
+## Verification
+
+Check that the plugin is loaded correctly:
+
+```bash
+openclaw plugins list
+openclaw channels status
+```
+
+This approach bypasses the need for npm publishing while still providing full functionality.

package/DEPLOYMENT.md

@@ -0,0 +1,380 @@
+# YunzhiJia Channel Deployment Guide
+
+## Overview
+
+This document provides comprehensive deployment instructions for the YunzhiJia channel plugin, following OpenClaw's standard plugin deployment patterns. The YunzhiJia channel enables integration with Kingdee's enterprise messaging platform through webhook-based communication.
+
+## Prerequisites
+
+### 1. OpenClaw Gateway Requirements
+- **OpenClaw Gateway** version 2026.1.0 or later
+- **Public HTTPS endpoint** accessible from YunzhiJia servers
+- **Valid SSL certificate** (required by YunzhiJia)
+
+### 2. YunzhiJia Bot Configuration
+- **YunzhiJia Enterprise Account** with bot creation permissions
+- **App Secret** for request signature verification
+- **Webhook Token** for sending responses
+- **Message Receive URL** pointing to your OpenClaw instance
+
+## Installation Methods
+
+### Method 1: Plugin Installation (Recommended)
+
+The YunzhiJia channel follows OpenClaw's standard plugin architecture and can be installed using the `openclaw plugins` CLI:
+
+```bash
+# Install from local development directory
+openclaw plugins install /zed/workspace/projects/yunzhijiachannel
+
+# Or install from npm (once published)
+openclaw plugins install @openclaw/yunzhijia
+```
+
+### Method 2: Development Linking
+
+For active development, link the plugin without copying:
+
+```bash
+# Link for development (changes reflect immediately)
+openclaw plugins install -l /zed/workspace/projects/yunzhijiachannel
+```
+
+### Method 3: Manual Extension Loading
+
+Add the plugin path to your OpenClaw configuration:
+
+```json5
+{
+  plugins: {
+    load: {
+      paths: ["/zed/workspace/projects/yunzhijiachannel"]
+    }
+  }
+}
+```
+
+## Configuration
+
+### Basic Configuration
+
+After installation, configure the YunzhiJia channel in your OpenClaw config file (`~/.openclaw/openclaw.json`):
+
+```json5
+{
+  channels: {
+    yunzhijia: {
+      enabled: true,
+      webhookToken: "${YUNZHIJIA_WEBHOOK_TOKEN}",
+      appSecret: "${YUNZHIJIA_APP_SECRET}",
+      requireMention: true,
+      allowFrom: []
+    }
+  }
+}
+```
+
+### Environment Variables
+
+For security, use environment variables for sensitive credentials:
+
+```bash
+export OPENCLAW_YUNZHIJIA_WEBHOOK_TOKEN="your-webhook-token"
+export OPENCLAW_YUNZHIJIA_APP_SECRET="your-app-secret"
+```
+
+Then reference them in your config:
+
+```json5
+{
+  channels: {
+    yunzhijia: {
+      enabled: true,
+      webhookToken: "${YUNZHIJIA_WEBHOOK_TOKEN}",
+      appSecret: "${YUNZHIJIA_APP_SECRET}"
+    }
+  }
+}
+```
+
+### Multi-Account Configuration
+
+Support multiple YunzhiJia bots with different configurations:
+
+```json5
+{
+  channels: {
+    yunzhijia: {
+      accounts: {
+        "production": {
+          webhookToken: "${PROD_WEBHOOK_TOKEN}",
+          appSecret: "${PROD_APP_SECRET}",
+          enabled: true
+        },
+        "staging": {
+          webhookToken: "${STAGING_WEBHOOK_TOKEN}",
+          appSecret: "${STAGING_APP_SECRET}",
+          enabled: false
+        }
+      }
+    }
+  }
+}
+```
+
+## HTTP Endpoint Setup
+
+### Automatic Registration
+
+The YunzhiJia plugin automatically registers its HTTP endpoint at `/receive` when loaded. No manual registration is required.
+
+### Reverse Proxy Configuration
+
+Configure your reverse proxy to forward requests to the OpenClaw Gateway:
+
+#### Nginx Example
+```nginx
+server {
+    listen 443 ssl;
+    server_name your-domain.com;
+    
+    # SSL configuration
+    ssl_certificate /path/to/cert.pem;
+    ssl_certificate_key /path/to/key.pem;
+    
+    location /receive {
+        proxy_pass http://localhost:8000/receive;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header Content-Type $http_content_type;
+        
+        # Required headers for YunzhiJia
+        proxy_pass_request_headers on;
+    }
+}
+```
+
+#### Apache Example
+```apache
+<VirtualHost *:443>
+    ServerName your-domain.com
+    
+    SSLEngine on
+    SSLCertificateFile /path/to/cert.pem
+    SSLCertificateKeyFile /path/to/key.pem
+    
+    ProxyPass /receive http://localhost:8000/receive
+    ProxyPassReverse /receive http://localhost:8000/receive
+    
+    # Preserve original headers
+    ProxyPreserveHost On
+    RequestHeader set X-Forwarded-Proto "https"
+</VirtualHost>
+```
+
+## YunzhiJia Bot Setup
+
+### 1. Create Bot in YunzhiJia
+
+1. Navigate to your YunzhiJia admin panel
+2. Create a new webhook bot
+3. Set the **Message Receive URL** to: `https://your-domain.com/receive`
+4. Copy the generated **App Secret** and **Webhook Token**
+
+### 2. Configure Security Settings
+
+- **Signature Verification**: Enabled (required)
+- **Mention Requirement**: Recommended for production
+- **Allowlist**: Configure if you want to restrict access
+
+## Testing and Validation
+
+### 1. Initial Configuration Test
+
+Use the OpenClaw CLI to verify plugin installation:
+
+```bash
+# List installed plugins
+openclaw plugins list
+
+# Check channel status
+openclaw channels status --channel yunzhijia
+
+# Test configuration
+openclaw doctor
+```
+
+### 2. YunzhiJia Test Request
+
+YunzhiJia sends a test request when you save the bot configuration:
+
+**Request Headers:**
+```
+Content-Type: application/json; charset=utf-8
+sign: jy/WTAtltv5UVQVDOb0f4H4JPqw=
+sessionId: XXXXXX
+```
+
+**Request Body:**
+```json
+{
+  "type": 2,
+  "robotId": "test-robotId",
+  "robotName": "test-robotName",
+  "operatorOpenid": "test-userId",
+  "operatorName": "test-userName",
+  "time": 1599727083000,
+  "msgId": "test-msgId",
+  "content": "你好，你能做什么呢?"
+}
+```
+
+**Expected Response (within 3 seconds):**
+```json
+{
+  "success": true,
+  "data": {
+    "type": 2,
+    "content": ""
+  }
+}
+```
+
+The actual response will be sent asynchronously via webhook after OpenClaw processing completes.
+
+### 3. Manual Testing
+
+Test the integration manually using curl:
+
+```bash
+# Test signature calculation (using test-secret)
+curl -X POST \
+  -H "Content-Type: application/json; charset=utf-8" \
+  -H "sign: jy/WTAtltv5UVQVDOb0f4H4JPqw=" \
+  -H "sessionId: test-session-123" \
+  -d '{
+    "type": 2,
+    "robotId": "test-robotId",
+    "robotName": "test-robotName",
+    "operatorOpenid": "test-userId",
+    "operatorName": "test-userName",
+    "time": 1599727083000,
+    "msgId": "test-msgId",
+    "content": "测试消息"
+  }' \
+  https://your-domain.com/receive
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### 1. Signature Verification Failed
+- **Cause**: App Secret mismatch between configuration and YunzhiJia bot settings
+- **Solution**: Verify the `appSecret` in your OpenClaw config matches the YunzhiJia bot configuration
+- **Debug**: Enable verbose logging with `OPENCLAW_DEBUG=true`
+
+#### 2. Request Timeout (3 seconds exceeded)
+- **Cause**: HTTP handler not returning immediate response
+- **Solution**: Ensure the plugin is properly installed and the `/receive` endpoint is registered
+- **Verify**: Check OpenClaw logs for HTTP request processing
+
+#### 3. Webhook Delivery Failed
+- **Cause**: Invalid webhook token or network connectivity issues
+- **Solution**: Verify the `webhookToken` and ensure YunzhiJia can reach your webhook endpoint
+- **Test**: Use curl to test webhook delivery directly
+
+#### 4. No Messages Received
+- **Cause**: Bot not properly @mentioned or allowlist restrictions
+- **Solution**: Check `requireMention` setting and `allowFrom` configuration
+- **Verify**: Test with explicit @mention in YunzhiJia chat
+
+### Debugging Commands
+
+```bash
+# Enable verbose logging
+export OPENCLAW_DEBUG=true
+
+# Check channel status
+openclaw channels status --channel yunzhijia
+
+# View channel logs
+openclaw channels logs --channel yunzhijia
+
+# Run diagnostics
+openclaw doctor
+
+# Test configuration validation
+openclaw config validate
+```
+
+### Log Analysis
+
+Key log messages to watch for:
+
+- `Received YunzhiJia message from {userName} ({userId}): {content}` - Message received
+- `Invalid signature` - Signature verification failed  
+- `Processing completed, sending webhook response` - Async processing finished
+- `Failed to send webhook message` - Webhook delivery error
+
+## Security Considerations
+
+### 1. Credential Protection
+- Never commit webhook tokens or app secrets to version control
+- Use environment variables or secure secret management
+- Rotate credentials regularly
+
+### 2. Access Control
+- Enable `requireMention: true` in production to prevent spam
+- Use `allowFrom` whitelist for sensitive deployments
+- Monitor unauthorized access attempts
+
+### 3. Network Security
+- Ensure HTTPS is properly configured with valid certificates
+- Restrict inbound traffic to YunzhiJia IP ranges if possible
+- Implement rate limiting at the reverse proxy level
+
+## Maintenance and Updates
+
+### Plugin Updates
+
+Update the plugin using the standard OpenClaw plugin management:
+
+```bash
+# Update from local changes
+openclaw plugins update yunzhijia
+
+# Restart gateway to apply changes
+openclaw gateway restart
+```
+
+### Configuration Changes
+
+Apply configuration changes safely:
+
+```bash
+# Validate configuration before applying
+openclaw config validate
+
+# Apply changes with automatic restart
+openclaw gateway call config.patch --params '{
+  "raw": "{\\"channels\\": {\\"yunzhijia\\": {\\"requireMention\\": false}}}",
+  "baseHash": "<current-hash>"
+}'
+```
+
+## Compliance with OpenClaw Standards
+
+This YunzhiJia channel implementation follows OpenClaw's plugin development standards:
+
+- ✅ Uses `openclaw/plugin-sdk` for type safety and runtime integration
+- ✅ Implements complete `ChannelPlugin` interface with all required adapters
+- ✅ Supports multi-account configuration and dynamic management
+- ✅ Integrates with OpenClaw's async message processing pipeline
+- ✅ Provides proper security adapters and allowlist support
+- ✅ Includes comprehensive status monitoring and health checks
+- ✅ Follows standard deployment patterns for OpenClaw plugins
+
+The implementation is modeled after the Telegram channel reference implementation and maintains full compatibility with OpenClaw's core architecture.