fengming 0.3.9 → 0.3.11

package/docs/channels/yuanbao.md

@@ -1,416 +0,0 @@
----
-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 FengMing channel plugin
-connects Yuanbao bots to FengMing 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 FengMing 2026.4.10 or above.** Run `fengming --version` to check. Upgrade with `fengming update`.
-
-<Steps>
-  <Step title="Add the Yuanbao channel with your credentials">
-  ```bash
-  fengming 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
-  fengming gateway restart
-  ```
-  </Step>
-</Steps>
-
-### Interactive setup (alternative)
-
-You can also use the interactive wizard:
-
-```bash
-fengming 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
-fengming pairing list yuanbao
-fengming 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 FengMing            |
-| `/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: `fengming 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: `fengming gateway status`
-4. Check logs: `fengming 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: `fengming 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

@@ -1,253 +0,0 @@
----
-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 FengMing 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: `fengming plugins install @fengming/zalo`
-- Pinned version: `fengming plugins install @fengming/zalo@2026.5.2`
-- Or from a source checkout: `fengming plugins install ./path/to/local/zalo-plugin`
-- Details: [Plugins](/tools/plugin)
-
-## Quick setup (beginner)
-
-1. Ensure the Zalo plugin is available.
-   - Current packaged FengMing 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 FengMing 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:
-  - `fengming pairing list zalo`
-  - `fengming 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 FengMing.
-
-| 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: `fengming message send --channel zalo --target 123456789 --message "hi"`.
-
-## Troubleshooting
-
-**Bot doesn't respond:**
-
-- Check that the token is valid: `fengming channels status --probe`
-- Verify the sender is approved (pairing or allowFrom)
-- Check gateway logs: `fengming 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