nodmix 2026.5.25

package/docs/channels/yuanbao.md

@@ -0,0 +1,416 @@
+---
+summary: "Yuanbao bot overview, features, and configuration"
+read_when:
+  - You want to connect a Yuanbao bot
+  - You are configuring the Yuanbao channel
+title: Yuanbao
+---
+
+Tencent Yuanbao is Tencent's AI assistant platform. The Nodmix channel plugin
+connects Yuanbao bots to Nodmix over WebSocket so they can interact with users
+through direct messages and group chats.
+
+**Status:** production-ready for bot DMs + group chats. WebSocket is the only supported connection mode.
+
+---
+
+## Quick start
+
+> **Requires Nodmix 2026.4.10 or above.** Run `nodmix --version` to check. Upgrade with `nodmix update`.
+
+<Steps>
+  <Step title="Add the Yuanbao channel with your credentials">
+  ```bash
+  nodmix channels add --channel yuanbao --token "appKey:appSecret"
+  ```
+  The `--token` value uses colon-separated `appKey:appSecret` format. You can obtain these from the Yuanbao app by creating a robot in your application settings.
+  </Step>
+
+  <Step title="After setup completes, restart the gateway to apply the changes">
+  ```bash
+  nodmix gateway restart
+  ```
+  </Step>
+</Steps>
+
+### Interactive setup (alternative)
+
+You can also use the interactive wizard:
+
+```bash
+nodmix channels login --channel yuanbao
+```
+
+Follow the prompts to enter your App ID and App Secret.
+
+---
+
+## Access control
+
+### Direct messages
+
+Configure `dmPolicy` to control who can DM the bot:
+
+- `"pairing"` - unknown users receive a pairing code; approve via CLI
+- `"allowlist"` - only users listed in `allowFrom` can chat
+- `"open"` - allow all users (default)
+- `"disabled"` - disable all DMs
+
+**Approve a pairing request:**
+
+```bash
+nodmix pairing list yuanbao
+nodmix pairing approve yuanbao <CODE>
+```
+
+### Group chats
+
+**Mention requirement** (`channels.yuanbao.requireMention`):
+
+- `true` - require @mention (default)
+- `false` - respond without @mention
+
+Replying to the bot's message in a group chat is treated as an implicit mention.
+
+---
+
+## Configuration examples
+
+### Basic setup with open DM policy
+
+```json5
+{
+  channels: {
+    yuanbao: {
+      appKey: "your_app_key",
+      appSecret: "your_app_secret",
+      dm: {
+        policy: "open",
+      },
+    },
+  },
+}
+```
+
+### Restrict DMs to specific users
+
+```json5
+{
+  channels: {
+    yuanbao: {
+      appKey: "your_app_key",
+      appSecret: "your_app_secret",
+      dm: {
+        policy: "allowlist",
+        allowFrom: ["user_id_1", "user_id_2"],
+      },
+    },
+  },
+}
+```
+
+### Disable @mention requirement in groups
+
+```json5
+{
+  channels: {
+    yuanbao: {
+      requireMention: false,
+    },
+  },
+}
+```
+
+### Optimize outbound message delivery
+
+```json5
+{
+  channels: {
+    yuanbao: {
+      // Send each chunk immediately without buffering
+      outboundQueueStrategy: "immediate",
+    },
+  },
+}
+```
+
+### Tune merge-text strategy
+
+```json5
+{
+  channels: {
+    yuanbao: {
+      outboundQueueStrategy: "merge-text",
+      minChars: 2800, // buffer until this many chars
+      maxChars: 3000, // force split above this limit
+      idleMs: 5000, // auto-flush after idle timeout (ms)
+    },
+  },
+}
+```
+
+---
+
+## Common commands
+
+| Command    | Description                 |
+| ---------- | --------------------------- |
+| `/help`    | Show available commands     |
+| `/status`  | Show bot status             |
+| `/new`     | Start a new session         |
+| `/stop`    | Stop the current run        |
+| `/restart` | Restart Nodmix            |
+| `/compact` | Compact the session context |
+
+> Yuanbao supports native slash-command menus. Commands are synced to the platform automatically when the gateway starts.
+
+---
+
+## Troubleshooting
+
+### Bot does not respond in group chats
+
+1. Ensure the bot is added to the group
+2. Ensure you @mention the bot (required by default)
+3. Check logs: `nodmix logs --follow`
+
+### Bot does not receive messages
+
+1. Ensure the bot is created and approved in the Yuanbao app
+2. Ensure `appKey` and `appSecret` are correctly configured
+3. Ensure the gateway is running: `nodmix gateway status`
+4. Check logs: `nodmix logs --follow`
+
+### Bot sends empty or fallback replies
+
+1. Check if the AI model is returning valid content
+2. The default fallback reply is: "暂时无法解答，你可以换个问题问问我哦"
+3. Customize it via `channels.yuanbao.fallbackReply`
+
+### App Secret leaked
+
+1. Reset the App Secret in YuanBao APP
+2. Update the value in your config
+3. Restart the gateway: `nodmix gateway restart`
+
+---
+
+## Advanced configuration
+
+### Multiple accounts
+
+```json5
+{
+  channels: {
+    yuanbao: {
+      defaultAccount: "main",
+      accounts: {
+        main: {
+          appKey: "key_xxx",
+          appSecret: "secret_xxx",
+          name: "Primary bot",
+        },
+        backup: {
+          appKey: "key_yyy",
+          appSecret: "secret_yyy",
+          name: "Backup bot",
+          enabled: false,
+        },
+      },
+    },
+  },
+}
+```
+
+`defaultAccount` controls which account is used when outbound APIs do not specify an `accountId`.
+
+### Message limits
+
+- `maxChars` - single message max character count (default: `3000` chars)
+- `mediaMaxMb` - media upload/download limit (default: `20` MB)
+- `overflowPolicy` - behavior when message exceeds limit: `"split"` (default) or `"stop"`
+
+### Streaming
+
+Yuanbao supports block-level streaming output. When enabled, the bot sends text in chunks as it generates.
+
+```json5
+{
+  channels: {
+    yuanbao: {
+      disableBlockStreaming: false, // block streaming enabled (default)
+    },
+  },
+}
+```
+
+Set `disableBlockStreaming: true` to send the complete reply in one message.
+
+### Group chat history context
+
+Control how many historical messages are included in the AI context for group chats:
+
+```json5
+{
+  channels: {
+    yuanbao: {
+      historyLimit: 100, // default: 100, set 0 to disable
+    },
+  },
+}
+```
+
+### Reply-to mode
+
+Control how the bot quotes messages when replying in group chats:
+
+```json5
+{
+  channels: {
+    yuanbao: {
+      replyToMode: "first", // "off" | "first" | "all" (default: "first")
+    },
+  },
+}
+```
+
+| Value     | Behavior                                                 |
+| --------- | -------------------------------------------------------- |
+| `"off"`   | No quote reply                                           |
+| `"first"` | Quote only the first reply per inbound message (default) |
+| `"all"`   | Quote every reply                                        |
+
+### Markdown hint injection
+
+By default, the bot injects instructions in the system prompt to prevent the AI model from wrapping the entire reply in markdown code blocks.
+
+```json5
+{
+  channels: {
+    yuanbao: {
+      markdownHintEnabled: true, // default: true
+    },
+  },
+}
+```
+
+### Debug mode
+
+Enable unsanitized log output for specific bot IDs:
+
+```json5
+{
+  channels: {
+    yuanbao: {
+      debugBotIds: ["bot_user_id_1", "bot_user_id_2"],
+    },
+  },
+}
+```
+
+### Multi-agent routing
+
+Use `bindings` to route Yuanbao DMs or groups to different agents.
+
+```json5
+{
+  agents: {
+    list: [
+      { id: "main" },
+      { id: "agent-a", workspace: "/home/user/agent-a" },
+      { id: "agent-b", workspace: "/home/user/agent-b" },
+    ],
+  },
+  bindings: [
+    {
+      agentId: "agent-a",
+      match: {
+        channel: "yuanbao",
+        peer: { kind: "direct", id: "user_xxx" },
+      },
+    },
+    {
+      agentId: "agent-b",
+      match: {
+        channel: "yuanbao",
+        peer: { kind: "group", id: "group_zzz" },
+      },
+    },
+  ],
+}
+```
+
+Routing fields:
+
+- `match.channel`: `"yuanbao"`
+- `match.peer.kind`: `"direct"` (DM) or `"group"` (group chat)
+- `match.peer.id`: user ID or group code
+
+---
+
+## Configuration reference
+
+Full configuration: [Gateway configuration](/gateway/configuration)
+
+| Setting                                    | Description                                       | Default                                |
+| ------------------------------------------ | ------------------------------------------------- | -------------------------------------- |
+| `channels.yuanbao.enabled`                 | Enable/disable the channel                        | `true`                                 |
+| `channels.yuanbao.defaultAccount`          | Default account for outbound routing              | `default`                              |
+| `channels.yuanbao.accounts.<id>.appKey`    | App Key (used for signing and ticket generation)  | -                                      |
+| `channels.yuanbao.accounts.<id>.appSecret` | App Secret (used for signing)                     | -                                      |
+| `channels.yuanbao.accounts.<id>.token`     | Pre-signed token (skips automatic ticket signing) | -                                      |
+| `channels.yuanbao.accounts.<id>.name`      | Account display name                              | -                                      |
+| `channels.yuanbao.accounts.<id>.enabled`   | Enable/disable a specific account                 | `true`                                 |
+| `channels.yuanbao.dm.policy`               | DM policy                                         | `open`                                 |
+| `channels.yuanbao.dm.allowFrom`            | DM allowlist (user ID list)                       | -                                      |
+| `channels.yuanbao.requireMention`          | Require @mention in groups                        | `true`                                 |
+| `channels.yuanbao.overflowPolicy`          | Long message handling (`split` or `stop`)         | `split`                                |
+| `channels.yuanbao.replyToMode`             | Group reply-to strategy (`off`, `first`, `all`)   | `first`                                |
+| `channels.yuanbao.outboundQueueStrategy`   | Outbound strategy (`merge-text` or `immediate`)   | `merge-text`                           |
+| `channels.yuanbao.minChars`                | Merge-text: min chars to trigger send             | `2800`                                 |
+| `channels.yuanbao.maxChars`                | Merge-text: max chars per message                 | `3000`                                 |
+| `channels.yuanbao.idleMs`                  | Merge-text: idle timeout before auto-flush (ms)   | `5000`                                 |
+| `channels.yuanbao.mediaMaxMb`              | Media size limit (MB)                             | `20`                                   |
+| `channels.yuanbao.historyLimit`            | Group chat history context entries                | `100`                                  |
+| `channels.yuanbao.disableBlockStreaming`   | Disable block-level streaming output              | `false`                                |
+| `channels.yuanbao.fallbackReply`           | Fallback reply when AI returns no content         | `暂时无法解答，你可以换个问题问问我哦` |
+| `channels.yuanbao.markdownHintEnabled`     | Inject markdown anti-wrapping instructions        | `true`                                 |
+| `channels.yuanbao.debugBotIds`             | Debug whitelist bot IDs (unsanitized logs)        | `[]`                                   |
+
+---
+
+## Supported message types
+
+### Receive
+
+- ✅ Text
+- ✅ Images
+- ✅ Files
+- ✅ Audio / Voice
+- ✅ Video
+- ✅ Stickers / Custom emoji
+- ✅ Custom elements (link cards, etc.)
+
+### Send
+
+- ✅ Text (with markdown support)
+- ✅ Images
+- ✅ Files
+- ✅ Audio
+- ✅ Video
+- ✅ Stickers
+
+### Threads and replies
+
+- ✅ Quote replies (configurable via `replyToMode`)
+- ❌ Thread replies (not supported by platform)
+
+---
+
+## Related
+
+- [Channels Overview](/channels) - all supported channels
+- [Pairing](/channels/pairing) - DM authentication and pairing flow
+- [Groups](/channels/groups) - group chat behavior and mention gating
+- [Channel Routing](/channels/channel-routing) - session routing for messages
+- [Security](/gateway/security) - access model and hardening

package/docs/channels/zalo.md

@@ -0,0 +1,253 @@
+---
+summary: "Zalo bot support status, capabilities, and configuration"
+read_when:
+  - Working on Zalo features or webhooks
+title: "Zalo"
+---
+
+Status: experimental. DMs are supported. The [Capabilities](#capabilities) section below reflects current Marketplace-bot behavior.
+
+## Bundled plugin
+
+Zalo ships as a bundled plugin in current Nodmix releases, so normal packaged
+builds do not need a separate install.
+
+If you are on an older build or a custom install that excludes Zalo, install the
+npm package directly:
+
+- Install via CLI: `nodmix plugins install @nodmix/zalo`
+- Pinned version: `nodmix plugins install @nodmix/zalo@2026.5.2`
+- Or from a source checkout: `nodmix plugins install ./path/to/local/zalo-plugin`
+- Details: [Plugins](/tools/plugin)
+
+## Quick setup (beginner)
+
+1. Ensure the Zalo plugin is available.
+   - Current packaged Nodmix releases already bundle it.
+   - Older/custom installs can add it manually with the commands above.
+2. Set the token:
+   - Env: `ZALO_BOT_TOKEN=...`
+   - Or config: `channels.zalo.accounts.default.botToken: "..."`.
+3. Restart the gateway (or finish setup).
+4. DM access is pairing by default; approve the pairing code on first contact.
+
+Minimal config:
+
+```json5
+{
+  channels: {
+    zalo: {
+      enabled: true,
+      accounts: {
+        default: {
+          botToken: "12345689:abc-xyz",
+          dmPolicy: "pairing",
+        },
+      },
+    },
+  },
+}
+```
+
+## What it is
+
+Zalo is a Vietnam-focused messaging app; its Bot API lets the Gateway run a bot for 1:1 conversations.
+It is a good fit for support or notifications where you want deterministic routing back to Zalo.
+
+This page reflects current Nodmix behavior for **Zalo Bot Creator / Marketplace bots**.
+**Zalo Official Account (OA) bots** are a different Zalo product surface and may behave differently.
+
+- A Zalo Bot API channel owned by the Gateway.
+- Deterministic routing: replies go back to Zalo; the model never chooses channels.
+- DMs share the agent's main session.
+- The [Capabilities](#capabilities) section below shows current Marketplace-bot support.
+
+## Setup (fast path)
+
+### 1) Create a bot token (Zalo Bot Platform)
+
+1. Go to [https://bot.zaloplatforms.com](https://bot.zaloplatforms.com) and sign in.
+2. Create a new bot and configure its settings.
+3. Copy the full bot token (typically `numeric_id:secret`). For Marketplace bots, the usable runtime token may appear in the bot's welcome message after creation.
+
+### 2) Configure the token (env or config)
+
+Example:
+
+```json5
+{
+  channels: {
+    zalo: {
+      enabled: true,
+      accounts: {
+        default: {
+          botToken: "12345689:abc-xyz",
+          dmPolicy: "pairing",
+        },
+      },
+    },
+  },
+}
+```
+
+If you later move to a Zalo bot surface where groups are available, you can add group-specific config such as `groupPolicy` and `groupAllowFrom` explicitly. For current Marketplace-bot behavior, see [Capabilities](#capabilities).
+
+Env option: `ZALO_BOT_TOKEN=...` (works for the default account only).
+
+Multi-account support: use `channels.zalo.accounts` with per-account tokens and optional `name`.
+
+3. Restart the gateway. Zalo starts when a token is resolved (env or config).
+4. DM access defaults to pairing. Approve the code when the bot is first contacted.
+
+## How it works (behavior)
+
+- Inbound messages are normalized into the shared channel envelope with media placeholders.
+- Replies always route back to the same Zalo chat.
+- Long-polling by default; webhook mode available with `channels.zalo.webhookUrl`.
+
+## Limits
+
+- Outbound text is chunked to 2000 characters (Zalo API limit).
+- Media downloads/uploads are capped by `channels.zalo.mediaMaxMb` (default 5).
+- Streaming is blocked by default due to the 2000 char limit making streaming less useful.
+
+## Access control (DMs)
+
+### DM access
+
+- Default: `channels.zalo.dmPolicy = "pairing"`. Unknown senders receive a pairing code; messages are ignored until approved (codes expire after 1 hour).
+- Approve via:
+  - `nodmix pairing list zalo`
+  - `nodmix pairing approve zalo <CODE>`
+- Pairing is the default token exchange. Details: [Pairing](/channels/pairing)
+- `channels.zalo.allowFrom` accepts numeric user IDs (no username lookup available).
+
+## Access control (Groups)
+
+For **Zalo Bot Creator / Marketplace bots**, group support was not available in practice because the bot could not be added to a group at all.
+
+That means the group-related config keys below exist in the schema, but were not usable for Marketplace bots:
+
+- `channels.zalo.groupPolicy` controls group inbound handling: `open | allowlist | disabled`.
+- `channels.zalo.groupAllowFrom` restricts which sender IDs can trigger the bot in groups.
+- If `groupAllowFrom` is unset, Zalo falls back to `allowFrom` for sender checks.
+- Runtime note: if `channels.zalo` is missing entirely, runtime still falls back to `groupPolicy="allowlist"` for safety.
+
+The group policy values (when group access is available on your bot surface) are:
+
+- `groupPolicy: "disabled"` — blocks all group messages.
+- `groupPolicy: "open"` — allows any group member (mention-gated).
+- `groupPolicy: "allowlist"` — fail-closed default; only allowed senders are accepted.
+
+If you are using a different Zalo bot product surface and have verified working group behavior, document that separately rather than assuming it matches the Marketplace-bot flow.
+
+## Long-polling vs webhook
+
+- Default: long-polling (no public URL required).
+- Webhook mode: set `channels.zalo.webhookUrl` and `channels.zalo.webhookSecret`.
+  - The webhook secret must be 8-256 characters.
+  - Webhook URL must use HTTPS.
+  - Zalo sends events with `X-Bot-Api-Secret-Token` header for verification.
+  - Gateway HTTP handles webhook requests at `channels.zalo.webhookPath` (defaults to the webhook URL path).
+  - Requests must use `Content-Type: application/json` (or `+json` media types).
+  - Duplicate events (`event_name + message_id`) are ignored for a short replay window.
+  - Burst traffic is rate-limited per path/source and may return HTTP 429.
+
+**Note:** getUpdates (polling) and webhook are mutually exclusive per Zalo API docs.
+
+## Supported message types
+
+For a quick support snapshot, see [Capabilities](#capabilities). The notes below add detail where the behavior needs extra context.
+
+- **Text messages**: Full support with 2000 character chunking.
+- **Plain URLs in text**: Behave like normal text input.
+- **Link previews / rich link cards**: See the Marketplace-bot status in [Capabilities](#capabilities); they did not reliably trigger a reply.
+- **Image messages**: See the Marketplace-bot status in [Capabilities](#capabilities); inbound image handling was unreliable (typing indicator without a final reply).
+- **Stickers**: See the Marketplace-bot status in [Capabilities](#capabilities).
+- **Voice notes / audio files / video / generic file attachments**: See the Marketplace-bot status in [Capabilities](#capabilities).
+- **Unsupported types**: Logged (for example, messages from protected users).
+
+## Capabilities
+
+This table summarizes current **Zalo Bot Creator / Marketplace bot** behavior in Nodmix.
+
+| Feature                     | Status                                  |
+| --------------------------- | --------------------------------------- |
+| Direct messages             | ✅ Supported                            |
+| Groups                      | ❌ Not available for Marketplace bots   |
+| Media (inbound images)      | ⚠️ Limited / verify in your environment |
+| Media (outbound images)     | ⚠️ Not re-tested for Marketplace bots   |
+| Plain URLs in text          | ✅ Supported                            |
+| Link previews               | ⚠️ Unreliable for Marketplace bots      |
+| Reactions                   | ❌ Not supported                        |
+| Stickers                    | ⚠️ No agent reply for Marketplace bots  |
+| Voice notes / audio / video | ⚠️ No agent reply for Marketplace bots  |
+| File attachments            | ⚠️ No agent reply for Marketplace bots  |
+| Threads                     | ❌ Not supported                        |
+| Polls                       | ❌ Not supported                        |
+| Native commands             | ❌ Not supported                        |
+| Streaming                   | ⚠️ Blocked (2000 char limit)            |
+
+## Delivery targets (CLI/cron)
+
+- Use a chat id as the target.
+- Example: `nodmix message send --channel zalo --target 123456789 --message "hi"`.
+
+## Troubleshooting
+
+**Bot doesn't respond:**
+
+- Check that the token is valid: `nodmix channels status --probe`
+- Verify the sender is approved (pairing or allowFrom)
+- Check gateway logs: `nodmix logs --follow`
+
+**Webhook not receiving events:**
+
+- Ensure webhook URL uses HTTPS
+- Verify secret token is 8-256 characters
+- Confirm the gateway HTTP endpoint is reachable on the configured path
+- Check that getUpdates polling is not running (they're mutually exclusive)
+
+## Configuration reference (Zalo)
+
+Full configuration: [Configuration](/gateway/configuration)
+
+The flat top-level keys (`channels.zalo.botToken`, `channels.zalo.dmPolicy`, and similar) are a legacy single-account shorthand. Prefer `channels.zalo.accounts.<id>.*` for new configs. Both forms are still documented here because they exist in the schema.
+
+Provider options:
+
+- `channels.zalo.enabled`: enable/disable channel startup.
+- `channels.zalo.botToken`: bot token from Zalo Bot Platform.
+- `channels.zalo.tokenFile`: read token from a regular file path. Symlinks are rejected.
+- `channels.zalo.dmPolicy`: `pairing | allowlist | open | disabled` (default: pairing).
+- `channels.zalo.allowFrom`: DM allowlist (user IDs). `open` requires `"*"`. The wizard will ask for numeric IDs.
+- `channels.zalo.groupPolicy`: `open | allowlist | disabled` (default: allowlist). Present in config; see [Capabilities](#capabilities) and [Access control (Groups)](#access-control-groups) for current Marketplace-bot behavior.
+- `channels.zalo.groupAllowFrom`: group sender allowlist (user IDs). Falls back to `allowFrom` when unset.
+- `channels.zalo.mediaMaxMb`: inbound/outbound media cap (MB, default 5).
+- `channels.zalo.webhookUrl`: enable webhook mode (HTTPS required).
+- `channels.zalo.webhookSecret`: webhook secret (8-256 chars).
+- `channels.zalo.webhookPath`: webhook path on the gateway HTTP server.
+- `channels.zalo.proxy`: proxy URL for API requests.
+
+Multi-account options:
+
+- `channels.zalo.accounts.<id>.botToken`: per-account token.
+- `channels.zalo.accounts.<id>.tokenFile`: per-account regular token file. Symlinks are rejected.
+- `channels.zalo.accounts.<id>.name`: display name.
+- `channels.zalo.accounts.<id>.enabled`: enable/disable account.
+- `channels.zalo.accounts.<id>.dmPolicy`: per-account DM policy.
+- `channels.zalo.accounts.<id>.allowFrom`: per-account allowlist.
+- `channels.zalo.accounts.<id>.groupPolicy`: per-account group policy. Present in config; see [Capabilities](#capabilities) and [Access control (Groups)](#access-control-groups) for current Marketplace-bot behavior.
+- `channels.zalo.accounts.<id>.groupAllowFrom`: per-account group sender allowlist.
+- `channels.zalo.accounts.<id>.webhookUrl`: per-account webhook URL.
+- `channels.zalo.accounts.<id>.webhookSecret`: per-account webhook secret.
+- `channels.zalo.accounts.<id>.webhookPath`: per-account webhook path.
+- `channels.zalo.accounts.<id>.proxy`: per-account proxy URL.
+
+## Related
+
+- [Channels Overview](/channels) — all supported channels
+- [Pairing](/channels/pairing) — DM authentication and pairing flow
+- [Groups](/channels/groups) — group chat behavior and mention gating
+- [Channel Routing](/channels/channel-routing) — session routing for messages
+- [Security](/gateway/security) — access model and hardening