fengming 0.3.9 → 0.3.11

package/docs/channels/twitch.md

@@ -1,431 +0,0 @@
----
-summary: "Twitch chat bot configuration and setup"
-read_when:
-  - Setting up Twitch chat integration for FengMing
-title: "Twitch"
-sidebarTitle: "Twitch"
----
-
-Twitch chat support via IRC connection. FengMing connects as a Twitch user (bot account) to receive and send messages in channels.
-
-## Bundled plugin
-
-<Note>
-Twitch ships as a bundled plugin in current FengMing releases, so normal packaged builds do not need a separate install.
-</Note>
-
-If you are on an older build or a custom install that excludes Twitch, install the npm package directly:
-
-<Tabs>
-  <Tab title="npm registry">
-    ```bash
-    fengming plugins install @fengming/twitch
-    ```
-  </Tab>
-  <Tab title="Local checkout">
-    ```bash
-    fengming plugins install ./path/to/local/twitch-plugin
-    ```
-  </Tab>
-</Tabs>
-
-Use the bare package to follow the current official release tag. Pin an exact
-version only when you need a reproducible install.
-
-Details: [Plugins](/tools/plugin)
-
-## Quick setup (beginner)
-
-<Steps>
-  <Step title="Ensure plugin is available">
-    Current packaged FengMing releases already bundle it. Older/custom installs can add it manually with the commands above.
-  </Step>
-  <Step title="Create a Twitch bot account">
-    Create a dedicated Twitch account for the bot (or use an existing account).
-  </Step>
-  <Step title="Generate credentials">
-    Use [Twitch Token Generator](https://twitchtokengenerator.com/):
-
-    - Select **Bot Token**
-    - Verify scopes `chat:read` and `chat:write` are selected
-    - Copy the **Client ID** and **Access Token**
-
-  </Step>
-  <Step title="Find your Twitch user ID">
-    Use [https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/) to convert a username to a Twitch user ID.
-  </Step>
-  <Step title="Configure the token">
-    - Env: `FENGMING_TWITCH_ACCESS_TOKEN=...` (default account only)
-    - Or config: `channels.twitch.accessToken`
-
-    If both are set, config takes precedence (env fallback is default-account only).
-
-  </Step>
-  <Step title="Start the gateway">
-    Start the gateway with the configured channel.
-  </Step>
-</Steps>
-
-<Warning>
-Add access control (`allowFrom` or `allowedRoles`) to prevent unauthorized users from triggering the bot. `requireMention` defaults to `true`.
-</Warning>
-
-Minimal config:
-
-```json5
-{
-  channels: {
-    twitch: {
-      enabled: true,
-      username: "fengming", // Bot's Twitch account
-      accessToken: "oauth:abc123...", // OAuth Access Token (or use FENGMING_TWITCH_ACCESS_TOKEN env var)
-      clientId: "xyz789...", // Client ID from Token Generator
-      channel: "vevisk", // Which Twitch channel's chat to join (required)
-      allowFrom: ["123456789"], // (recommended) Your Twitch user ID only - get it from https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
-    },
-  },
-}
-```
-
-## What it is
-
-- A Twitch channel owned by the Gateway.
-- Deterministic routing: replies always go back to Twitch.
-- Each account maps to an isolated session key `agent:<agentId>:twitch:<accountName>`.
-- `username` is the bot's account (who authenticates), `channel` is which chat room to join.
-
-## Setup (detailed)
-
-### Generate credentials
-
-Use [Twitch Token Generator](https://twitchtokengenerator.com/):
-
-- Select **Bot Token**
-- Verify scopes `chat:read` and `chat:write` are selected
-- Copy the **Client ID** and **Access Token**
-
-<Note>
-No manual app registration needed. Tokens expire after several hours.
-</Note>
-
-### Configure the bot
-
-<Tabs>
-  <Tab title="Env var (default account only)">
-    ```bash
-    FENGMING_TWITCH_ACCESS_TOKEN=oauth:abc123...
-    ```
-  </Tab>
-  <Tab title="Config">
-    ```json5
-    {
-      channels: {
-        twitch: {
-          enabled: true,
-          username: "fengming",
-          accessToken: "oauth:abc123...",
-          clientId: "xyz789...",
-          channel: "vevisk",
-        },
-      },
-    }
-    ```
-  </Tab>
-</Tabs>
-
-If both env and config are set, config takes precedence.
-
-### Access control (recommended)
-
-```json5
-{
-  channels: {
-    twitch: {
-      allowFrom: ["123456789"], // (recommended) Your Twitch user ID only
-    },
-  },
-}
-```
-
-Prefer `allowFrom` for a hard allowlist. Use `allowedRoles` instead if you want role-based access.
-
-**Available roles:** `"moderator"`, `"owner"`, `"vip"`, `"subscriber"`, `"all"`.
-
-<Note>
-**Why user IDs?** Usernames can change, allowing impersonation. User IDs are permanent.
-
-Find your Twitch user ID: [https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/) (Convert your Twitch username to ID)
-</Note>
-
-## Token refresh (optional)
-
-Tokens from [Twitch Token Generator](https://twitchtokengenerator.com/) cannot be automatically refreshed - regenerate when expired.
-
-For automatic token refresh, create your own Twitch application at [Twitch Developer Console](https://dev.twitch.tv/console) and add to config:
-
-```json5
-{
-  channels: {
-    twitch: {
-      clientSecret: "your_client_secret",
-      refreshToken: "your_refresh_token",
-    },
-  },
-}
-```
-
-The bot automatically refreshes tokens before expiration and logs refresh events.
-
-## Multi-account support
-
-Use `channels.twitch.accounts` with per-account tokens. See [Configuration](/gateway/configuration) for the shared pattern.
-
-Example (one bot account in two channels):
-
-```json5
-{
-  channels: {
-    twitch: {
-      accounts: {
-        channel1: {
-          username: "fengming",
-          accessToken: "oauth:abc123...",
-          clientId: "xyz789...",
-          channel: "vevisk",
-        },
-        channel2: {
-          username: "fengming",
-          accessToken: "oauth:def456...",
-          clientId: "uvw012...",
-          channel: "secondchannel",
-        },
-      },
-    },
-  },
-}
-```
-
-<Note>
-Each account needs its own token (one token per channel).
-</Note>
-
-## Access control
-
-<Tabs>
-  <Tab title="User ID allowlist (most secure)">
-    ```json5
-    {
-      channels: {
-        twitch: {
-          accounts: {
-            default: {
-              allowFrom: ["123456789", "987654321"],
-            },
-          },
-        },
-      },
-    }
-    ```
-  </Tab>
-  <Tab title="Role-based">
-    ```json5
-    {
-      channels: {
-        twitch: {
-          accounts: {
-            default: {
-              allowedRoles: ["moderator", "vip"],
-            },
-          },
-        },
-      },
-    }
-    ```
-
-    `allowFrom` is a hard allowlist. When set, only those user IDs are allowed. If you want role-based access, leave `allowFrom` unset and configure `allowedRoles` instead.
-
-  </Tab>
-  <Tab title="Disable @mention requirement">
-    By default, `requireMention` is `true`. To disable and respond to all messages:
-
-    ```json5
-    {
-      channels: {
-        twitch: {
-          accounts: {
-            default: {
-              requireMention: false,
-            },
-          },
-        },
-      },
-    }
-    ```
-
-  </Tab>
-</Tabs>
-
-## Troubleshooting
-
-First, run diagnostic commands:
-
-```bash
-fengming doctor
-fengming channels status --probe
-```
-
-<AccordionGroup>
-  <Accordion title="Bot does not respond to messages">
-    - **Check access control:** Ensure your user ID is in `allowFrom`, or temporarily remove `allowFrom` and set `allowedRoles: ["all"]` to test.
-    - **Check the bot is in the channel:** The bot must join the channel specified in `channel`.
-
-  </Accordion>
-  <Accordion title="Token issues">
-    "Failed to connect" or authentication errors:
-
-    - Verify `accessToken` is the OAuth access token value (typically starts with `oauth:` prefix)
-    - Check token has `chat:read` and `chat:write` scopes
-    - If using token refresh, verify `clientSecret` and `refreshToken` are set
-
-  </Accordion>
-  <Accordion title="Token refresh not working">
-    Check logs for refresh events:
-
-    ```
-    Using env token source for mybot
-    Access token refreshed for user 123456 (expires in 14400s)
-    ```
-
-    If you see "token refresh disabled (no refresh token)":
-
-    - Ensure `clientSecret` is provided
-    - Ensure `refreshToken` is provided
-
-  </Accordion>
-</AccordionGroup>
-
-## Config
-
-### Account config
-
-<ParamField path="username" type="string">
-  Bot username.
-</ParamField>
-<ParamField path="accessToken" type="string">
-  OAuth access token with `chat:read` and `chat:write`.
-</ParamField>
-<ParamField path="clientId" type="string">
-  Twitch Client ID (from Token Generator or your app).
-</ParamField>
-<ParamField path="channel" type="string" required>
-  Channel to join.
-</ParamField>
-<ParamField path="enabled" type="boolean" default="true">
-  Enable this account.
-</ParamField>
-<ParamField path="clientSecret" type="string">
-  Optional: for automatic token refresh.
-</ParamField>
-<ParamField path="refreshToken" type="string">
-  Optional: for automatic token refresh.
-</ParamField>
-<ParamField path="expiresIn" type="number">
-  Token expiry in seconds.
-</ParamField>
-<ParamField path="obtainmentTimestamp" type="number">
-  Token obtained timestamp.
-</ParamField>
-<ParamField path="allowFrom" type="string[]">
-  User ID allowlist.
-</ParamField>
-<ParamField path="allowedRoles" type='Array<"moderator" | "owner" | "vip" | "subscriber" | "all">'>
-  Role-based access control.
-</ParamField>
-<ParamField path="requireMention" type="boolean" default="true">
-  Require @mention.
-</ParamField>
-
-### Provider options
-
-- `channels.twitch.enabled` - Enable/disable channel startup
-- `channels.twitch.username` - Bot username (simplified single-account config)
-- `channels.twitch.accessToken` - OAuth access token (simplified single-account config)
-- `channels.twitch.clientId` - Twitch Client ID (simplified single-account config)
-- `channels.twitch.channel` - Channel to join (simplified single-account config)
-- `channels.twitch.accounts.<accountName>` - Multi-account config (all account fields above)
-
-Full example:
-
-```json5
-{
-  channels: {
-    twitch: {
-      enabled: true,
-      username: "fengming",
-      accessToken: "oauth:abc123...",
-      clientId: "xyz789...",
-      channel: "vevisk",
-      clientSecret: "secret123...",
-      refreshToken: "refresh456...",
-      allowFrom: ["123456789"],
-      allowedRoles: ["moderator", "vip"],
-      accounts: {
-        default: {
-          username: "mybot",
-          accessToken: "oauth:abc123...",
-          clientId: "xyz789...",
-          channel: "your_channel",
-          enabled: true,
-          clientSecret: "secret123...",
-          refreshToken: "refresh456...",
-          expiresIn: 14400,
-          obtainmentTimestamp: 1706092800000,
-          allowFrom: ["123456789", "987654321"],
-          allowedRoles: ["moderator"],
-        },
-      },
-    },
-  },
-}
-```
-
-## Tool actions
-
-The agent can call `twitch` with action:
-
-- `send` - Send a message to a channel
-
-Example:
-
-```json5
-{
-  action: "twitch",
-  params: {
-    message: "Hello Twitch!",
-    to: "#mychannel",
-  },
-}
-```
-
-## Safety and ops
-
-- **Treat tokens like passwords** — Never commit tokens to git.
-- **Use automatic token refresh** for long-running bots.
-- **Use user ID allowlists** instead of usernames for access control.
-- **Monitor logs** for token refresh events and connection status.
-- **Scope tokens minimally** — Only request `chat:read` and `chat:write`.
-- **If stuck**: Restart the gateway after confirming no other process owns the session.
-
-## Limits
-
-- **500 characters** per message (auto-chunked at word boundaries).
-- Markdown is stripped before chunking.
-- No rate limiting (uses Twitch's built-in rate limits).
-
-## Related
-
-- [Channel Routing](/channels/channel-routing) — session routing for messages
-- [Channels Overview](/channels) — all supported channels
-- [Groups](/channels/groups) — group chat behavior and mention gating
-- [Pairing](/channels/pairing) — DM authentication and pairing flow
-- [Security](/gateway/security) — access model and hardening

package/docs/channels/wechat.md

@@ -1,171 +0,0 @@
----
-summary: "WeChat channel setup through the external fengming-weixin plugin"
-read_when:
-  - You want to connect FengMing to WeChat or Weixin
-  - You are installing or troubleshooting the fengming-weixin channel plugin
-  - You need to understand how external channel plugins run beside the Gateway
-title: "WeChat"
----
-
-FengMing connects to WeChat through Tencent's external
-`@tencent-weixin/fengming-weixin` channel plugin.
-
-Status: external plugin. Direct chats and media are supported. Group chats are not
-advertised by the current plugin capability metadata.
-
-## Naming
-
-- **WeChat** is the user-facing name in these docs.
-- **Weixin** is the name used by Tencent's package and by the plugin id.
-- `fengming-weixin` is the FengMing channel id.
-- `@tencent-weixin/fengming-weixin` is the npm package.
-
-Use `fengming-weixin` in CLI commands and config paths.
-
-## How it works
-
-The WeChat code does not live in the FengMing core repo. FengMing provides the
-generic channel plugin contract, and the external plugin provides the
-WeChat-specific runtime:
-
-1. `fengming plugins install` installs `@tencent-weixin/fengming-weixin`.
-2. The Gateway discovers the plugin manifest and loads the plugin entrypoint.
-3. The plugin registers channel id `fengming-weixin`.
-4. `fengming channels login --channel fengming-weixin` starts QR login.
-5. The plugin stores account credentials under the FengMing state directory.
-6. When the Gateway starts, the plugin starts its Weixin monitor for each
-   configured account.
-7. Inbound WeChat messages are normalized through the channel contract, routed to
-   the selected FengMing agent, and sent back through the plugin outbound path.
-
-That separation matters: FengMing core should stay channel-agnostic. WeChat login,
-Tencent iLink API calls, media upload/download, context tokens, and account
-monitoring are owned by the external plugin.
-
-## Install
-
-Quick install:
-
-```bash
-npx -y @tencent-weixin/fengming-weixin-cli install
-```
-
-Manual install:
-
-```bash
-fengming plugins install "@tencent-weixin/fengming-weixin"
-fengming config set plugins.entries.fengming-weixin.enabled true
-```
-
-Restart the Gateway after install:
-
-```bash
-fengming gateway restart
-```
-
-## Login
-
-Run QR login on the same machine that runs the Gateway:
-
-```bash
-fengming channels login --channel fengming-weixin
-```
-
-Scan the QR code with WeChat on your phone and confirm the login. The plugin saves
-the account token locally after a successful scan.
-
-To add another WeChat account, run the same login command again. For multiple
-accounts, isolate direct-message sessions by account, channel, and sender:
-
-```bash
-fengming config set session.dmScope per-account-channel-peer
-```
-
-## Access control
-
-Direct messages use the normal FengMing pairing and allowlist model for channel
-plugins.
-
-Approve new senders:
-
-```bash
-fengming pairing list fengming-weixin
-fengming pairing approve fengming-weixin <CODE>
-```
-
-For the full access-control model, see [Pairing](/channels/pairing).
-
-## Compatibility
-
-The plugin checks the host FengMing version at startup.
-
-| Plugin line | FengMing version        | npm tag  |
-| ----------- | ----------------------- | -------- |
-| `2.x`       | `>=2026.3.22`           | `latest` |
-| `1.x`       | `>=2026.1.0 <2026.3.22` | `legacy` |
-
-If the plugin reports that your FengMing version is too old, either update
-FengMing or install the legacy plugin line:
-
-```bash
-fengming plugins install @tencent-weixin/fengming-weixin@legacy
-```
-
-## Sidecar process
-
-The WeChat plugin can run helper work beside the Gateway while it monitors the
-Tencent iLink API. In issue #68451, that helper path exposed a bug in FengMing's
-generic stale-Gateway cleanup: a child process could try to clean up the parent
-Gateway process, causing restart loops under process managers such as systemd.
-
-Current FengMing startup cleanup excludes the current process and its ancestors,
-so a channel helper must not kill the Gateway that launched it. This fix is
-generic; it is not a WeChat-specific path in core.
-
-## Troubleshooting
-
-Check install and status:
-
-```bash
-fengming plugins list
-fengming channels status --probe
-fengming --version
-```
-
-If the channel shows as installed but does not connect, confirm that the plugin is
-enabled and restart:
-
-```bash
-fengming config set plugins.entries.fengming-weixin.enabled true
-fengming gateway restart
-```
-
-If the Gateway restarts repeatedly after enabling WeChat, update both FengMing and
-the plugin:
-
-```bash
-npm view @tencent-weixin/fengming-weixin version
-fengming plugins install "@tencent-weixin/fengming-weixin" --force
-fengming gateway restart
-```
-
-If startup reports that the installed plugin package `requires compiled runtime
-output for TypeScript entry`, the npm package was published without the compiled
-JavaScript runtime files FengMing needs. Update/reinstall after the plugin
-publisher ships a fixed package, or temporarily disable/uninstall the plugin.
-
-Temporary disable:
-
-```bash
-fengming config set plugins.entries.fengming-weixin.enabled false
-fengming gateway restart
-```
-
-## Related docs
-
-- Channel overview: [Chat Channels](/channels)
-- Pairing: [Pairing](/channels/pairing)
-- Channel routing: [Channel Routing](/channels/channel-routing)
-- Plugin architecture: [Plugin Architecture](/plugins/architecture)
-- Channel plugin SDK: [Channel Plugin SDK](/plugins/sdk-channel-plugins)
-- External package: [@tencent-weixin/fengming-weixin](https://www.npmjs.com/package/@tencent-weixin/fengming-weixin)