@coremail/lunkr-openclaw 1.0.0

package/docs/USAGE.md

@@ -0,0 +1,337 @@
+# Lunkr Channel Plugin - Usage Guide
+
+This document provides detailed information on using the Lunkr channel plugin for OpenClaw.
+
+## Bot Simulation
+
+The Lunkr plugin simulates a bot by using the authenticated user's account to send and receive messages. This approach is called "Bot Simulation" because:
+
+1. **The bot is you**: The AI responds using your Lunkr account
+2. **Bot replies are marked**: Bot messages are prefixed with `[@!BotName]` to distinguish them from your regular messages
+3. **Self-triggering**: In normal chats, you trigger the bot by sending a message that starts with the command prefix
+
+### How Bot Simulation Works
+
+```
+User (You)                    Lunkr Server                   OpenClaw
+   |                              |                              |
+   |-- "Hello" ----------------->|                              |
+   |                              |                              |
+   |                              |-- "Hello" ------------------>|
+   |                              |                              |
+   |                              |    (Bot triggers AI)         |
+   |                              |                              |
+   |                              |<-- "[@!Bot] Hi there!" ------|
+   |                              |                              |
+   |<-- "[@!Bot] Hi there!" ------|                              |
+```
+
+## Trigger Rules
+
+The bot triggers based on where the message is sent and who sends it.
+
+### Bot Discussions (Recommended)
+
+Bot Discussions are dedicated discussion groups where **all messages** trigger the AI agent.
+
+```
++---------------------------+
+|  Bot Discussion Group     |
+|                           |
+|  Alice: How do I reset?   | --> Triggers AI
+|  Bob: Check settings      | --> Triggers AI
+|  Bot: [@!Bot] To reset... | --> Does NOT trigger (bot reply)
++---------------------------+
+```
+
+**Setup:**
+```yaml
+channels:
+  lunkr:
+    botDiscussions:
+      "group-id-abc123":
+        name: "AI Assistant"
+        creatorUid: "admin-uid"
+        createdAt: "2024-01-01T00:00:00Z"
+```
+
+### Normal Groups and DMs
+
+In regular groups and direct messages, only **you** can trigger the bot by prefixing your message with the command prefix (default: `/bot`).
+
+```
++---------------------------+
+|  Regular Group Chat       |
+|                           |
+|  Alice: Hello everyone    | --> No trigger
+|  Bob: /bot What is AI?    | --> Triggers AI (if Bob is you)
+|  You: /bot Explain X      | --> Triggers AI
+|  Bot: [@!Bot] X is...     | --> Does NOT trigger (bot reply)
++---------------------------+
+```
+
+### Trigger Summary Table
+
+| Scenario | Message From | Message Content | Triggers AI? |
+|----------|-------------|-----------------|--------------|
+| Bot Discussion | Anyone | Anything | Yes |
+| Bot Discussion | You (Bot reply) | `[@!BotName] ...` | No |
+| Normal Group/DM | You | `/bot help` | Yes |
+| Normal Group/DM | You | `Hello` | No |
+| Normal Group/DM | Others | `/bot help` | No |
+| Normal Group/DM | Others | `Hello` | No |
+
+## Configuration Reference
+
+### Complete Configuration Schema
+
+```yaml
+channels:
+  lunkr:
+    # Enable this channel
+    enabled: true
+
+    # Bot display name (appears in bot replies)
+    botName: "AI Assistant"
+
+    # Command prefix for normal chats
+    commandPrefix: "/bot"
+
+    # Bot discussion groups (all messages trigger AI)
+    botDiscussions:
+      "discussion-id-1":
+        name: "Support Channel"
+        agentId: "support-agent"    # Optional: route to specific agent
+        creatorUid: "user-123"
+        createdAt: "2024-01-15T10:30:00Z"
+
+    # Direct message policy
+    dmPolicy: "allow"              # allow | deny | whitelist
+    allowFrom:                     # Whitelisted users (for dmPolicy: whitelist)
+      - "user-id-1"
+      - "user-id-2"
+
+    # Group message policy
+    groupPolicy: "allow"           # allow | deny | whitelist
+    groups:                        # Whitelisted groups (for groupPolicy: whitelist)
+      - "group-id-1"
+      - "group-id-2"
+```
+
+### Policy Values
+
+#### `dmPolicy`
+
+| Value | Description |
+|-------|-------------|
+| `allow` | Accept DMs from all users (default) |
+| `deny` | Reject all DMs to the bot |
+| `whitelist` | Only accept DMs from users in `allowFrom` list |
+
+#### `groupPolicy`
+
+| Value | Description |
+|-------|-------------|
+| `allow` | Respond in all groups when triggered (default) |
+| `deny` | Never respond in groups |
+| `whitelist` | Only respond in groups in `groups` list |
+
+### Bot Discussion Configuration
+
+Each bot discussion entry requires:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Display name for this discussion |
+| `agentId` | string | No | Agent ID to route messages to |
+| `creatorUid` | string | Yes | User ID of the creator |
+| `createdAt` | string/number | Yes | Creation timestamp (ISO or epoch ms) |
+
+## Multi-Agent Routing
+
+You can route different Bot Discussions to different AI agents:
+
+```yaml
+# In your OpenClaw config
+agents:
+  sales-agent:
+    # Sales-specific agent configuration
+  support-agent:
+    # Support-specific agent configuration
+
+channels:
+  lunkr:
+    botDiscussions:
+      "sales-group-id":
+        name: "Sales Bot"
+        agentId: "sales-agent"
+        creatorUid: "admin"
+        createdAt: "2024-01-01"
+      "support-group-id":
+        name: "Support Bot"
+        agentId: "support-agent"
+        creatorUid: "admin"
+        createdAt: "2024-01-01"
+```
+
+When a message arrives in a Bot Discussion with an `agentId` configured, it is automatically routed to that specific agent.
+
+## Message Handling
+
+### Inbound Messages
+
+Messages from Lunkr are processed as follows:
+
+1. **Receive**: Message arrives via Socket.IO real-time connection
+2. **Analyze**: Determine if message should trigger the bot
+3. **Convert**: Transform Lunkr format to OpenClaw format
+4. **Route**: Send to appropriate agent for processing
+
+### Outbound Messages
+
+Bot replies are formatted with the `[@!BotName]` prefix:
+
+```
+[@!AI Assistant] Here is my response to your question...
+```
+
+This prefix helps distinguish bot messages from your regular messages.
+
+### Message Types Supported
+
+| Type | Support |
+|------|---------|
+| Text | Full support |
+| Images | Supported |
+| Files | Supported |
+| Reactions | Supported |
+| Edits | Supported |
+| Replies | Supported |
+
+## Security Considerations
+
+### Bot Reply Detection
+
+The plugin identifies bot replies by checking if:
+- The message is from the authenticated user (self)
+- The content starts with `[@!<botName>]`
+
+These messages are never re-processed by the bot to prevent loops.
+
+### Self-Message Triggering
+
+In normal chats, only messages from the authenticated user that start with the command prefix trigger the bot. This prevents:
+- Accidental triggers from other users
+- Message loops from bot replies
+
+### Whitelist Security
+
+When using whitelist policies:
+
+```yaml
+dmPolicy: whitelist
+allowFrom:
+  - "trusted-user-1"
+  - "trusted-user-2"
+```
+
+Only messages from whitelisted users will be processed.
+
+### Pairing Flow
+
+Users can request to be whitelisted via pairing:
+
+1. User sends a pairing request
+2. Admin approves with: `openclaw pairing approve lunkr <code>`
+3. User's ID is added to `allowFrom`
+
+## Examples
+
+### Example 1: Simple Bot Discussion
+
+```yaml
+channels:
+  lunkr:
+    enabled: true
+    botName: "Helper"
+    botDiscussions:
+      "abc123":
+        name: "Help Channel"
+        creatorUid: "admin"
+        createdAt: "2024-01-01"
+```
+
+Any message in group `abc123` triggers the bot.
+
+### Example 2: Restricted DM Access
+
+```yaml
+channels:
+  lunkr:
+    enabled: true
+    dmPolicy: whitelist
+    allowFrom:
+      - "user-001"
+      - "user-002"
+    groupPolicy: deny
+```
+
+Only `user-001` and `user-002` can DM the bot. No group messages are processed.
+
+### Example 3: Multi-Agent Setup
+
+```yaml
+agents:
+  code-reviewer:
+    model: "claude-3"
+    systemPrompt: "You are a code reviewer..."
+
+  translator:
+    model: "gpt-4"
+    systemPrompt: "You are a translator..."
+
+channels:
+  lunkr:
+    botDiscussions:
+      "code-review-group":
+        name: "Code Reviews"
+        agentId: "code-reviewer"
+        creatorUid: "dev-team"
+        createdAt: 1704067200000
+      "translation-group":
+        name: "Translations"
+        agentId: "translator"
+        creatorUid: "intl-team"
+        createdAt: 1704067200000
+```
+
+### Example 4: Custom Command Prefix
+
+```yaml
+channels:
+  lunkr:
+    enabled: true
+    commandPrefix: "!"
+```
+
+Now use `! help` instead of `/bot help` to trigger the bot in normal chats.
+
+## Troubleshooting
+
+### Bot Not Responding in Bot Discussion
+
+1. Verify the discussion ID matches your configuration
+2. Check that the message is not a bot reply (starts with `[@!...]`)
+3. Review gateway logs for errors
+
+### Wrong Agent Receiving Messages
+
+1. Check the `agentId` in the bot discussion configuration
+2. Verify the agent ID exists in your agents configuration
+3. Check for typos in the discussion ID mapping
+
+### DM Whitelist Not Working
+
+1. Ensure `dmPolicy` is set to `whitelist` (not `allow`)
+2. Verify user IDs in `allowFrom` are correct
+3. Remember to restart the gateway after config changes

package/openclaw.plugin.json

@@ -0,0 +1,61 @@
+{
+  "id": "lunkr",
+  "channels": ["lunkr"],
+  "skills": ["skills/lunkr"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enabled": {
+        "type": "boolean",
+        "default": true
+      },
+      "botName": {
+        "type": "string",
+        "default": "Bot"
+      },
+      "commandPrefix": {
+        "type": "string",
+        "default": "/bot"
+      },
+      "dmPolicy": {
+        "type": "string",
+        "enum": ["pairing", "allowlist", "any"],
+        "default": "pairing"
+      },
+      "allowFrom": {
+        "type": "array",
+        "items": { "type": "string" },
+        "default": []
+      },
+      "groupPolicy": {
+        "type": "string",
+        "enum": ["allowlist", "any"],
+        "default": "any"
+      },
+      "groups": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "object",
+          "properties": {
+            "requireMention": { "type": "boolean", "default": true },
+            "enabled": { "type": "boolean", "default": true }
+          }
+        }
+      },
+      "botDiscussions": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "object",
+          "properties": {
+            "name": { "type": "string" },
+            "agentId": { "type": "string" },
+            "creatorUid": { "type": "string" },
+            "createdAt": { "type": "number" }
+          },
+          "required": ["name", "creatorUid", "createdAt"]
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "@coremail/lunkr-openclaw",
+  "version": "1.0.0",
+  "description": "OpenClaw Lunkr/Coremail channel plugin",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.ts"
+    }
+  },
+  "bin": {
+    "lunkr-cli": "./dist/bin/lunkr-cli.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "openclaw.plugin.json",
+    "skills/**",
+    "docs/**",
+    "README.md"
+  ],
+  "scripts": {
+    "help": "node scripts/help.mjs",
+
+    "dev": "tsx watch src/index.ts",
+    "dev:cli": "tsx src/bin/lunkr-cli.ts",
+
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/",
+
+    "clean": "rm -rf dist/",
+    "build": "tsc && tsc-alias",
+    "build:release": "node scripts/build-release.js",
+
+    "deploy:local": "node scripts/deploy-local.mjs",
+    "deploy:local:full": "npm run clean && npm test && npm run build && npm run deploy:local",
+
+    "pack": "npm run clean && npm test && npm run build && npm pack",
+    "prepublishOnly": "npm run build:release"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "0.34.48",
+    "commander": "^12.0.0",
+    "fast-xml-parser": "^5.0.0",
+    "https-proxy-agent": "^7.0.6",
+    "qrcode-terminal": "^0.12.0",
+    "uuid": "^11.0.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/mime-types": "^3.0.1",
+    "@types/node": "^25.4.0",
+    "@types/qrcode-terminal": "^0.12.2",
+    "@types/ws": "^8.18.1",
+    "esbuild": "^0.25.0",
+    "mime-types": "^3.0.2",
+    "tsc-alias": "^1.8.16",
+    "tsx": "^4.19.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.0.0"
+  },
+  "keywords": [
+    "openclaw",
+    "lunkr",
+    "coremail",
+    "channel",
+    "plugin"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "channel": {
+      "id": "lunkr",
+      "label": "Lunkr",
+      "selectionLabel": "Lunkr/Coremail (论客)",
+      "docsPath": "/channels/lunkr",
+      "docsLabel": "lunkr",
+      "blurb": "Lunkr/Coremail enterprise messaging with rich API support.",
+      "aliases": [
+        "coremail"
+      ],
+      "order": 40
+    },
+    "install": {
+      "npmSpec": "@coremail/lunkr-openclaw"
+    }
+  }
+}

package/skills/lunkr/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: lunkr
+description: Send messages and interact with Lunkr (论客) messaging platform
+user-invocable: true
+command-dispatch: tool
+command-tool: lunkr_command
+---
+
+# Lunkr/论客 Skill
+
+Send messages and interact with Lunkr (论客) messaging platform.
+
+## Usage
+
+```
+/lunkr <subcommand> [args]
+```
+
+> **Note**: The `/lunkr` command works when typed directly but does not appear in the TUI slash command autocomplete list. This is a limitation of OpenClaw core's `getSlashCommands()` function, which doesn't include skill commands in autocomplete suggestions. Just type `/lunkr` and it will work.
+
+## Subcommands
+
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `send <to> <message>` | `s` | Send message to user or group |
+| `search-groups <keyword> [limit]` | `sg` | Search for groups (default: 10) |
+| `search-contacts <keyword> [limit]` | `sc` | Search for contacts (default: 10) |
+| `list-chats [limit]` | `lc` | List recent chats (default: 20) |
+| `help` | | Show usage help |
+
+## Examples
+
+Send a message to a user by email:
+```
+/lunkr send user@example.com Hello, this is a test message
+```
+
+Send a message to a group by ID:
+```
+/lunkr s #26783249#T Meeting reminder: standup at 10am
+```
+
+Search for groups:
+```
+/lunkr search-groups project-alpha
+```
+
+List recent chats:
+```
+/lunkr list-chats 10
+```
+
+## Agent Usage
+
+**IMPORTANT: Always use `lunkr_send_message` tool for sending messages to Lunkr, NOT the generic "message" tool.**
+
+The `lunkr_send_message` tool automatically resolves recipient names to UIDs:
+- Pass group name directly: `测试Bot` → tool will search and find the UID
+- Pass user name directly: `张三` → tool will search and find the UID
+- Of course you can also use: `#xxx#U`, `#xxx#T`, `email@example.com`
+
+Other available tools:
+
+- `lunkr_search_groups` - Search for discussion groups
+- `lunkr_search_contacts` - Search for contacts
+- `lunkr_get_group_info` - Get group details
+- `lunkr_get_user_info` - Get user details
+- `lunkr_list_recent_chats` - List recent conversations
+- `lunkr_download_file` - Download files from messages
+- `lunkr_get_message` - Get specific message details
+
+## Recipient Formats
+
+The `to` parameter in `/lunkr-send` accepts:
+
+- User ID: `#835#U`
+- Group ID: `#26783249#T`
+- User email: `user@example.com`
+- Group email: `t..xxx@coremail.cn`
+- Group name (will search): `Project Alpha Team`