@lansenger-pm/openclaw-lansenger-channel 2.7.2 → 2.8.2

package/README.fr.md

@@ -47,23 +47,53 @@ Connecte OpenClaw à Lansenger — une plateforme de messagerie d'entreprise —
 | `lansenger_revoke_message` | Révoquer un message précédemment envoyé |
 | `lansenger_query_groups` | Interroger les groupes disponibles |
 
-## Installation rapide
+## Installation et Configuration
 
-### Via OpenClaw CLI (recommandé)
+### Flux recommandé en 4 étapes
 
 ```bash
-# 1. Install the plugin
+# 1. Installer le plugin
 openclaw plugins install @lansenger-pm/openclaw-lansenger-channel
 
-# 2. Copy to extensions directory (required due to OpenClaw CLI discovery bug)
-mkdir -p ~/.openclaw/extensions/lansenger
-cp -r ~/.openclaw/npm/node_modules/@lansenger-pm/openclaw-lansenger-channel/* \
-     ~/.openclaw/extensions/lansenger/
+# 2. Activer le plugin (si non auto-activé)
+openclaw config set plugins.entries.Lansenger.enabled true
 
-# 3. Restart gateway
+# 3. Configurer le canal (assistant interactif)
+openclaw channels add --channel Lansenger
+#   OU non-interactif :
+openclaw channels add --channel Lansenger --token "appId:appSecret"
+
+# 4. Redémarrer la passerelle
 openclaw gateway restart
 ```
 
+Les métadonnées `openclaw.install` dans `package.json` (`npmSpec`, `localPath`, `defaultChoice`) permettent l'**installation à la demande** : si un utilisateur exécute `openclaw channels add --channel Lansenger` avant que le plugin soit installé, OpenClaw peut l'installer automatiquement.
+
+> **Passerelle personnalisée** : pour les déploiements entreprise (ex. 奇安信), configurez `apiGatewayUrl` dans `openclaw.json` ou via les variables d'environnement après la configuration — voir [Configuration optionnelle](#configuration-optionnelle).
+
+### Installation de développement (lien local)
+
+```bash
+cd /path/to/openclaw-lansenger-channel
+npm install
+openclaw plugins install --link
+openclaw gateway restart
+```
+
+### Obtenir les identifiants
+
+**Lansenger Desktop** → **Contacts** → **Bots** → **Personal Bots** → cliquer sur l'icône **ℹ️**
+
+> ⚠️ **Le client mobile ne permet PAS de voir les identifiants.** Utilisez uniquement le client desktop.
+
+### Premier message
+
+Après le redémarrage, le bot se connecte automatiquement via WebSocket. Envoyez un DM au bot — vous recevrez un code de pairage. Approuvez-le :
+
+```bash
+openclaw pairing approve Lansenger <code>
+```
+
 > ⚠️ Step 2 is required because `openclaw channels add` only discovers plugins in the `extensions/` directory, not from npm-installed packages. This is an [OpenClaw upstream bug](https://docs.openclaw.ai), not a plugin issue.
 
 ### Via npm
@@ -112,7 +142,7 @@ Obtenir les identifiants : **Lansenger Desktop** → **Contacts** → **Bots**
 Après le redémarrage, le bot se connecte automatiquement via WebSocket. Envoyez un DM au bot — vous recevrez un code de pairage. Approuvez-le :
 
 ```bash
-openclaw pairing approve lansenger <code>
+openclaw pairing approve Lansenger <code>
 ```
 
 ## Configuration
@@ -138,11 +168,11 @@ Ajoutez ces variables à `~/.openclaw/.env` ou à votre environnement :
 ```json
 {
   "channels": {
-    "lansenger": {
+    "Lansenger": {
       "appId": "your-appid",
       "appSecret": "your-secret",
       "apiGatewayUrl": "https://open.e.lanxin.cn/open/apigw",
-      "homeChannel": "lansenger",
+      "homeChannel": "Lansenger",
       "enabled": true,
       "allowFrom": ["your-appid"],
       "dmSecurity": "paired",
@@ -150,7 +180,6 @@ Ajoutez ces variables à `~/.openclaw/.env` ou à votre environnement :
         "your-appid": {
           "appId": "your-appid",
           "appSecret": "...",
-          "agentId": "main",
           "apiGatewayUrl": "https://open.e.lanxin.cn/open/apigw"
         }
       }
@@ -169,22 +198,19 @@ Ajoutez ces variables à `~/.openclaw/.env` ou à votre environnement :
 | `allowFrom` | IDs d'utilisateurs autorisés en DM | `[]` |
 | `dmSecurity` | Politique DM : `paired`, `allowlist`, `open` | `paired` |
 | `accounts` | Configuration multi-bot | — |
+| `groupPolicy` | Politique de groupe : `open` (tous les groupes), `allowlist` (groupes autorisés uniquement), `disabled` (messages de groupe désactivés) | `allowlist` |
+| `groupAllowFrom` | IDs de groupes autorisés à déclencher le bot | `[]` |
+| `groups` | Configuration par groupe (requireMention, enabled, allowFrom) | — |
 
 ### Configuration multi-bot
 
-> ⚠️ `openclaw channels add` ne supporte qu'un seul compte et **remplace** le précédent à chaque exécution. Pour ajouter plusieurs bots, utilisez `openclaw config set` avec la structure `accounts`.
-
-Après avoir ajouté le premier compte via `channels add`, ajoutez des bots supplémentaires avec `openclaw config set` :
+Pour ajouter plusieurs bots, utilisez `openclaw config set` avec la structure `accounts` :
 
 ```bash
 # Ajouter un deuxième bot (remplacez appid/appsecret/gateway par vos valeurs)
-openclaw config set channels.lansenger.accounts.your-appid-2.appId "your-appid-2"
-openclaw config set channels.lansenger.accounts.your-appid-2.appSecret "your-appsecret"
-openclaw config set channels.lansenger.accounts.your-appid-2.apiGatewayUrl "https://apigw.lx.qianxin.com"
-
-# Lier chaque bot à un agent différent
-openclaw config set channels.lansenger.accounts.your-appid-2.agentId "main"
-openclaw config set channels.lansenger.accounts.your-appid-1.agentId "test"
+openclaw config set channels.Lansenger.accounts.your-appid-2.appId "your-appid-2"
+openclaw config set channels.Lansenger.accounts.your-appid-2.appSecret "your-appsecret"
+openclaw config set channels.Lansenger.accounts.your-appid-2.apiGatewayUrl "https://apigw.lx.qianxin.com"
 
 # Redémarrer pour appliquer
 openclaw gateway restart
@@ -195,7 +221,7 @@ Structure de configuration résultante :
 ```json
 {
   "channels": {
-    "lansenger": {
+    "Lansenger": {
       "appId": "your-appid-2",
       "appSecret": "...",
       "dmSecurity": "paired",
@@ -203,19 +229,18 @@ Structure de configuration résultante :
         "your-appid-2": {
           "appId": "your-appid-2",
           "appSecret": "...",
-          "agentId": "main",
           "apiGatewayUrl": "https://apigw.lx.qianxin.com"
         },
         "your-appid-1": {
           "appId": "your-appid-1",
           "appSecret": "...",
-          "agentId": "test",
           "apiGatewayUrl": "https://apigw.lx.qianxin.com"
         }
       }
     }
   }
 }
+```
 
 ## Utilisation
 
@@ -241,21 +266,45 @@ openclaw channels status
 openclaw gateway call lansenger.status
 ```
 
-### Lier un bot à un agent (configuration)
+### Routage multi-agent
 
-La liaison bot-agent utilise `agentId` dans la configuration du compte ou OpenClaw `bindings[]` :
-
-```bash
-# agentId par compte (recommandé)
-openclaw config set channels.lansenger.accounts.your-appid.agentId "main"
+Utilisez `bindings` pour router les DM Lansenger ou les conversations de groupe vers différents agents (même principe que Feishu/WhatsApp/etc.) :
 
-# Ou via OpenClaw bindings[]
-openclaw config set bindings '[{"agentId":"main","match":{"channel":"lansenger","peer":{"kind":"direct","id":"your-userid"}}}]'
+```json5
+{
+  agents: {
+    list: [
+      { id: "main" },
+      { id: "agent-a", workspace: "/home/user/agent-a" },
+    ],
+  },
+  bindings: [
+    {
+      agentId: "agent-a",
+      match: {
+        channel: "Lansenger",
+        peer: { kind: "direct", id: "2285568-xxx" },
+      },
+    },
+    {
+      agentId: "agent-a",
+      match: {
+        channel: "Lansenger",
+        peer: { kind: "group", id: "group-chat-id" },
+      },
+    },
+  ],
+}
 ```
 
-> Voir [Configuration multi-bot](#configuration-multi-bot) pour le routage multi-agent.
+Champs de routage :
+* `match.channel`: `"Lansenger"`
+* `match.peer.kind`: `"direct"` (DM) ou `"group"` (chat de groupe)
+* `match.peer.id`: ID utilisateur (`2285568-xxx`) ou ID de chat de groupe
+
+En mode mono-agent, tous les messages routent vers l'agent par défaut (`main`) automatiquement — pas de bindings nécessaires.
 
-## Types de messages supportés
+### Politique de groupe
 
 | Type | Description | Méthode API | Direction |
 |------|-------------|-------------|-----------|
@@ -333,8 +382,7 @@ openclaw-lansenger-channel/
 │   ├── client.ts       # Client API Lansenger (WS, HTTP, médias)
 │   ├── channel.ts      # Plugin de canal OpenClaw
 │   ├── channel.test.ts # Tests du plugin de canal
-│   ├── runtime.ts      # Runtime passerelle (méthodes, handler entrant)
-│   └── bindings.ts     # Gestionnaire de liaisons multi-bot
+│   └── runtime.ts      # Runtime passerelle (méthodes, handler entrant)
 ├── skills/
 │   └── lansenger-messaging/
 │       └── SKILL.md    # Stratégie de messagerie de l'agent
@@ -354,7 +402,7 @@ Utilisez uniquement le **client Lansenger (desktop)**. L'application mobile n'af
 
 ### "No binding for botId"
 
-Configurez `agentId` dans la configuration du compte, ou utilisez OpenClaw `bindings[]` pour le routage multi-agent.
+Le routage des agents est géré par la configuration `bindings[]` d'OpenClaw — voir [Routage multi-agent](#routage-multi-agent). En mode mono-agent, aucun binding est nécessaire ; les messages routent automatiquement vers l'agent par défaut.
 
 ### Déconnexions WebSocket
 
@@ -373,6 +421,8 @@ Les mises à jour de statut d'approbation utilisent le format DynamicMsg appCard
 
 ## Journal des modifications
 
+- **v2.8.1** — Correction README : flux d'installation en 4 étapes (installer → activer → configurer → redémarrer), suppression du hack de copie manuelle ; correction SKILL.md frontmatter (conformité AgentSkills : suppression version/category/trigger, ajout metadata.openclaw gating) ; identifiant de canal renommé en Lansenger
+- **v2.8.0** — Routage multi-agent via OpenClaw `bindings[]` (remplace `agentId` par compte) ; ajout groupPolicy/groupAllowFrom/groups pour contrôle d'accès groupe ; utilisation de `resolveAgentRoute` SDK pour routage inbound
 - **v2.7.2** — Ajout fichier VERSION ; complétion changelog dans 5 READMEs ; régénération package-lock.json
 - **v2.7.0** — Enregistrement des outils comme objets simples (pas fonctions factory) ; utilisation de l'état runtime pour client/target — correction de l'enregistrement des outils de plugin externe
 - **v2.6.0** — Enregistrement inconditionnel des outils (résolution du compte à l'exécution) ; suppression du ghost delete_message

package/README.md

@@ -31,7 +31,7 @@ Lansenger (蓝信) channel plugin for OpenClaw — WebSocket inbound, HTTP API o
 
 **Default strategy**: Use `formatText` first for Markdown replies. Fall back to `text` for attachments. Both `formatText` and `text` support @mention via `reminder` param — include "@姓名" in text content when mentioning.
 
-## Agent Tools (v2.5.1)
+## Agent Tools
 
 | Tool | Description |
 |------|-------------|
@@ -45,32 +45,29 @@ Lansenger (蓝信) channel plugin for OpenClaw — WebSocket inbound, HTTP API o
 | `lansenger_revoke_message` | Revoke a previously sent message |
 | `lansenger_query_groups` | Query available groups |
 
-## Quick Install
+## Installation & Configuration
 
-### Via OpenClaw CLI (recommended)
+### Recommended 4-step flow
 
 ```bash
 # 1. Install the plugin
 openclaw plugins install @lansenger-pm/openclaw-lansenger-channel
 
-# 2. Copy to extensions directory (required due to OpenClaw CLI discovery bug)
-mkdir -p ~/.openclaw/extensions/lansenger
-cp -r ~/.openclaw/npm/node_modules/@lansenger-pm/openclaw-lansenger-channel/* \
-     ~/.openclaw/extensions/lansenger/
+# 2. Enable the plugin (if not auto-enabled)
+openclaw config set plugins.entries.Lansenger.enabled true
 
-# 3. Restart gateway
+# 3. Configure the channel (interactive wizard)
+openclaw channels add --channel Lansenger
+#   OR non-interactive:
+openclaw channels add --channel Lansenger --token "appId:appSecret"
+
+# 4. Restart the gateway
 openclaw gateway restart
 ```
 
-> ⚠️ Step 2 is required because `openclaw channels add` only discovers plugins in the `extensions/` directory, not from npm-installed packages. This is an [OpenClaw upstream bug](https://docs.openclaw.ai), not a plugin issue.
-
-### Via npm
+The `openclaw.install` metadata in `package.json` (`npmSpec`, `localPath`, `defaultChoice`) enables **install-on-demand**: if a user runs `openclaw channels add --channel Lansenger` before the plugin is installed, OpenClaw can automatically install it using this metadata.
 
-```bash
-# First install the npm package manually, then configure via CLI
-npm install -g @lansenger-pm/openclaw-lansenger-channel
-openclaw channels add --channel lansenger
-```
+> **Custom gateway**: For enterprise deployments (e.g. 奇安信), set `apiGatewayUrl` in `openclaw.json` or environment after configuration — see [Optional Configuration](#optional-configuration).
 
 ### Development install (linked)
 
@@ -81,36 +78,18 @@ openclaw plugins install --link
 openclaw gateway restart
 ```
 
-## Quick Start
-
-After installing, configure credentials:
-
-> **Single account**: `channels add` creates one account. For multiple bots, see [Multi-Bot Configuration](#multi-bot-configuration) below.
+### Get Credentials
 
-```bash
-# Standard (uses default gateway https://open.e.lanxin.cn/open/apigw)
-openclaw channels add --channel Lansenger \
-  --app-token "your-appid" \
-  --secret "your-appsecret"
-
-# Enterprise deployment (custom gateway URL)
-openclaw channels add --channel Lansenger \
-  --app-token "your-appid" \
-  --secret "your-appsecret" \
-  --base-url "https://apigw.lx.qianxin.com"
-```
+**Lansenger Desktop** → **Contacts** → **Bots** → **Personal Bots** → click **ℹ️** icon
 
-Then restart:
-```bash
-openclaw gateway restart
-```
+> ⚠️ **Mobile client does NOT support viewing credentials.** Use the desktop client only.
 
-Get credentials from **Lansenger Desktop** → **Contacts** → **Bots** → **Personal Bots** → click **ℹ️** icon (mobile client cannot view credentials).
+### First message
 
-The bot will auto-connect via WebSocket on gateway restart. Send a DM to the bot — you'll receive a pairing code. Approve it:
+The bot auto-connects via WebSocket on gateway restart. Send a DM to the bot — you'll receive a pairing code. Approve it:
 
 ```bash
-openclaw pairing approve lansenger <code>
+openclaw pairing approve Lansenger <code>
 ```
 
 ## Configuration
@@ -136,11 +115,11 @@ Add these to `~/.openclaw/.env` or your environment:
 ```json
 {
   "channels": {
-    "lansenger": {
+    "Lansenger": {
       "appId": "your-appid",
       "appSecret": "your-secret",
       "apiGatewayUrl": "https://open.e.lanxin.cn/open/apigw",
-      "homeChannel": "lansenger",
+      "homeChannel": "Lansenger",
       "enabled": true,
       "allowFrom": ["your-appid"],
       "dmSecurity": "paired",
@@ -148,7 +127,6 @@ Add these to `~/.openclaw/.env` or your environment:
         "your-appid": {
           "appId": "your-appid",
           "appSecret": "...",
-          "agentId": "main",
           "apiGatewayUrl": "https://open.e.lanxin.cn/open/apigw"
         }
       }
@@ -167,22 +145,19 @@ Add these to `~/.openclaw/.env` or your environment:
 | `allowFrom` | User IDs allowed to DM the bot | `[]` |
 | `dmSecurity` | DM policy: `paired`, `allowlist`, `open` | `paired` |
 | `accounts` | Multi-bot configuration | — |
+| `groupPolicy` | Group policy: `open`, `allowlist`, `disabled` | `allowlist` |
+| `groupAllowFrom` | Group IDs allowed to trigger the bot | `[]` |
+| `groups` | Per-group configuration (requireMention, enabled, allowFrom) | — |
 
 ### Multi-Bot Configuration
 
-> ⚠️ `openclaw channels add` only supports a single account and **overwrites** the previous one each time. For multiple bots, use `openclaw config set` with the `accounts` structure below.
-
-After adding the first account via `channels add`, add additional bots using `openclaw config set`:
+For multiple bots, add additional accounts using `openclaw config set`:
 
 ```bash
 # Add a second bot (replace appid/appsecret/gateway with your values)
-openclaw config set channels.lansenger.accounts.your-appid-2.appId "your-appid-2"
-openclaw config set channels.lansenger.accounts.your-appid-2.appSecret "your-appsecret"
-openclaw config set channels.lansenger.accounts.your-appid-2.apiGatewayUrl "https://apigw.lx.qianxin.com"
-
-# Bind each bot to a different agent
-openclaw config set channels.lansenger.accounts.your-appid-2.agentId "main"
-openclaw config set channels.lansenger.accounts.your-appid-1.agentId "test"
+openclaw config set channels.Lansenger.accounts.your-appid-2.appId "your-appid-2"
+openclaw config set channels.Lansenger.accounts.your-appid-2.appSecret "your-appsecret"
+openclaw config set channels.Lansenger.accounts.your-appid-2.apiGatewayUrl "https://apigw.lx.qianxin.com"
 
 # Restart to apply
 openclaw gateway restart
@@ -193,7 +168,7 @@ The resulting config structure:
 ```json
 {
   "channels": {
-    "lansenger": {
+    "Lansenger": {
       "appId": "your-appid-2",
       "appSecret": "...",
       "dmSecurity": "paired",
@@ -201,13 +176,11 @@ The resulting config structure:
         "your-appid-2": {
           "appId": "your-appid-2",
           "appSecret": "...",
-          "agentId": "main",
           "apiGatewayUrl": "https://apigw.lx.qianxin.com"
         },
         "your-appid-1": {
           "appId": "your-appid-1",
           "appSecret": "...",
-          "agentId": "test",
           "apiGatewayUrl": "https://apigw.lx.qianxin.com"
         }
       }
@@ -240,21 +213,45 @@ openclaw channels status
 openclaw gateway call lansenger.status
 ```
 
-### Bind a bot to an agent (config-based)
+### Multi-agent routing
 
-Bot-to-agent binding uses `agentId` in the account config or OpenClaw `bindings[]`:
+Use `bindings` to route Lansenger DMs or groups to different agents (same pattern as Feishu/WhatsApp/etc.):
 
-```bash
-# Per-account agentId (recommended)
-openclaw config set channels.lansenger.accounts.your-appid.agentId "main"
-
-# Or via OpenClaw bindings[]
-openclaw config set bindings '[{"agentId":"main","match":{"channel":"lansenger","peer":{"kind":"direct","id":"your-userid"}}}]'
+```json5
+{
+  agents: {
+    list: [
+      { id: "main" },
+      { id: "agent-a", workspace: "/home/user/agent-a" },
+    ],
+  },
+  bindings: [
+    {
+      agentId: "agent-a",
+      match: {
+        channel: "Lansenger",
+        peer: { kind: "direct", id: "2285568-xxx" },
+      },
+    },
+    {
+      agentId: "agent-a",
+      match: {
+        channel: "Lansenger",
+        peer: { kind: "group", id: "group-chat-id" },
+      },
+    },
+  ],
+}
 ```
 
-> See [Multi-Bot Configuration](#multi-bot-configuration) for multi-agent routing.
+Routing fields:
+* `match.channel`: `"Lansenger"`
+* `match.peer.kind`: `"direct"` (DM) or `"group"` (group chat)
+* `match.peer.id`: user ID (`2285568-xxx`) or group chat ID
+
+In single-agent mode, all messages route to the default agent (`main`) automatically — no bindings needed.
 
-## Supported Message Types
+### Group policy
 
 | Type | Description | API Method | Direction |
 |------|-------------|------------|-----------|
@@ -332,8 +329,7 @@ openclaw-lansenger-channel/
 │   ├── client.ts       # Lansenger API client (WS, HTTP, media)
 │   ├── channel.ts      # OpenClaw channel plugin
 │   ├── channel.test.ts # Channel plugin tests
-│   ├── runtime.ts      # Gateway runtime (methods, inbound handler)
-│   └── bindings.ts     # Multi-bot binding manager
+│   └── runtime.ts      # Gateway runtime (methods, inbound handler)
 ├── skills/
 │   └── lansenger-messaging/
 │       └── SKILL.md    # Agent messaging strategy
@@ -353,7 +349,7 @@ Use the **Lansenger Desktop** client only. The mobile app does not display bot c
 
 ### "No binding for botId"
 
-Configure `agentId` in the account config, or use OpenClaw `bindings[]` for multi-agent routing.
+Agent routing is handled by OpenClaw's `bindings[]` config — see [Multi-agent routing](#multi-agent-routing). In single-agent mode, no binding is needed; messages route to the default agent automatically.
 
 ### WebSocket disconnects
 
@@ -372,6 +368,8 @@ Approval status updates use the DynamicMsg appCard format. The `updateCardStatus
 
 ## Changelog
 
+- **v2.8.1** — Fix README: proper 4-step install flow (install → enable → configure → restart), remove manual-copy hack; fix SKILL.md frontmatter (AgentSkills spec compliance: remove version/category/trigger, add metadata.openclaw gating); rename channel identifier to Lansenger
+- **v2.8.0** — Use OpenClaw `bindings[]` for multi-agent routing (replaces per-account `agentId`); add groupPolicy/groupAllowFrom/groups for group chat access control; use `resolveAgentRoute` SDK for inbound routing
 - **v2.7.2** — Add VERSION file; complete changelog in all 5 READMEs; regenerate package-lock.json
 - **v2.7.0** — Register tools as plain objects (not factory functions); use runtime state for client/target — fixes external plugin tool registration
 - **v2.6.0** — Register tools unconditionally (resolve account at execute time); removed phantom delete_message tool registration