@symerian/symi 3.0.21 → 3.0.22

package/docs/zh-CN/channels/tlon.md

@@ -1,136 +0,0 @@
----
-read_when:
-  - 开发 Tlon/Urbit 渠道功能
-summary: Tlon/Urbit 支持状态、功能和配置
-title: Tlon
-x-i18n:
-  generated_at: "2026-02-03T07:44:17Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 19d7ffe23e82239fd2a2e35913e0d52c809b2c2b939dd39184e6c27a539ed97d
-  source_path: channels/tlon.md
-  workflow: 15
----
-
-# Tlon（插件）
-
-Tlon 是一个基于 Urbit 构建的去中心化即时通讯工具。Symi 连接到你的 Urbit ship，可以响应私信和群聊消息。群组回复默认需要 @ 提及，并可通过允许列表进一步限制。
-
-状态：通过插件支持。支持私信、群组提及、话题回复和纯文本媒体回退（URL 附加到说明文字）。不支持表情回应、投票和原生媒体上传。
-
-## 需要插件
-
-Tlon 作为插件提供，不包含在核心安装中。
-
-通过 CLI 安装（npm 仓库）：
-
-```bash
-symi plugins install @symi/tlon
-```
-
-本地检出（从 git 仓库运行时）：
-
-```bash
-symi plugins install ./extensions/tlon
-```
-
-详情：[插件](/tools/plugin)
-
-## 设置
-
-1. 安装 Tlon 插件。
-2. 获取你的 ship URL 和登录代码。
-3. 配置 `channels.tlon`。
-4. 重启 Gateway 网关。
-5. 私信机器人或在群组频道中提及它。
-
-最小配置（单账户）：
-
-```json5
-{
-  channels: {
-    tlon: {
-      enabled: true,
-      ship: "~sampel-palnet",
-      url: "https://your-ship-host",
-      code: "lidlut-tabwed-pillex-ridrup",
-    },
-  },
-}
-```
-
-## 群组频道
-
-默认启用自动发现。你也可以手动固定频道：
-
-```json5
-{
-  channels: {
-    tlon: {
-      groupChannels: ["chat/~host-ship/general", "chat/~host-ship/support"],
-    },
-  },
-}
-```
-
-禁用自动发现：
-
-```json5
-{
-  channels: {
-    tlon: {
-      autoDiscoverChannels: false,
-    },
-  },
-}
-```
-
-## 访问控制
-
-私信允许列表（空 = 允许全部）：
-
-```json5
-{
-  channels: {
-    tlon: {
-      dmAllowlist: ["~zod", "~nec"],
-    },
-  },
-}
-```
-
-群组授权（默认受限）：
-
-```json5
-{
-  channels: {
-    tlon: {
-      defaultAuthorizedShips: ["~zod"],
-      authorization: {
-        channelRules: {
-          "chat/~host-ship/general": {
-            mode: "restricted",
-            allowedShips: ["~zod", "~nec"],
-          },
-          "chat/~host-ship/announcements": {
-            mode: "open",
-          },
-        },
-      },
-    },
-  },
-}
-```
-
-## 投递目标（CLI/cron）
-
-与 `symi message send` 或 cron 投递一起使用：
-
-- 私信：`~sampel-palnet` 或 `dm/~sampel-palnet`
-- 群组：`chat/~host-ship/channel` 或 `group:~host-ship/channel`
-
-## 注意事项
-
-- 群组回复需要提及（例如 `~your-bot-ship`）才能响应。
-- 话题回复：如果入站消息在话题中，Symi 会在话题内回复。
-- 媒体：`sendMedia` 回退为文本 + URL（无原生上传）。

package/docs/zh-CN/channels/troubleshooting.md

@@ -1,34 +0,0 @@
----
-read_when:
-  - 渠道已连接但消息无法流通
-  - 排查渠道配置错误（意图、权限、隐私模式）
-title: 渠道故障排除
-x-i18n:
-  generated_at: "2026-02-01T19:58:09Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 6542ee86b3e50929caeaab127642d135dfbc0d8a44876ec2df0fff15bf57cd63
-  source_path: channels/troubleshooting.md
-  workflow: 14
----
-
-# 渠道故障排除
-
-首先运行：
-
-```bash
-symi doctor
-symi channels status --probe
-```
-
-`channels status --probe` 会在检测到常见渠道配置错误时输出警告，并包含小型实时检查（凭据、部分权限/成员资格）。
-
-## 渠道
-
-- Telegram：[/channels/telegram#troubleshooting](/channels/telegram#troubleshooting)
-- WhatsApp：[/channels/whatsapp#troubleshooting-quick](/channels/whatsapp#troubleshooting-quick)
-
-## Telegram 快速修复
-
-- 日志显示 `HttpError: Network request for 'sendMessage' failed` 或 `sendChatAction` → 检查 IPv6 DNS。如果 `api.telegram.org` 优先解析为 IPv6 而主机缺少 IPv6 出站连接，请强制使用 IPv4 或启用 IPv6。参见 [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting)。
-- 日志显示 `setMyCommands failed` → 检查到 `api.telegram.org` 的出站 HTTPS 和 DNS 可达性（常见于限制严格的 VPS 或代理环境）。

package/docs/zh-CN/channels/twitch.md

@@ -1,385 +0,0 @@
----
-read_when:
-  - 为 Symi 设置 Twitch 聊天集成
-summary: Twitch 聊天机器人配置和设置
-title: Twitch
-x-i18n:
-  generated_at: "2026-02-03T07:44:41Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 0dd1c05bef570470d8b82c1f6dee5337e8b76b57269c5cad6aee2e711483f8ba
-  source_path: channels/twitch.md
-  workflow: 15
----
-
-# Twitch（插件）
-
-通过 IRC 连接支持 Twitch 聊天。Symi 以 Twitch 用户（机器人账户）身份连接，在频道中接收和发送消息。
-
-## 需要插件
-
-Twitch 作为插件发布，未与核心安装捆绑。
-
-通过 CLI 安装（npm 注册表）：
-
-```bash
-symi plugins install @symi/twitch
-```
-
-本地检出（从 git 仓库运行时）：
-
-```bash
-symi plugins install ./extensions/twitch
-```
-
-详情：[插件](/tools/plugin)
-
-## 快速设置（新手）
-
-1. 为机器人创建一个专用的 Twitch 账户（或使用现有账户）。
-2. 生成凭证：[Twitch Token Generator](https://twitchtokengenerator.com/)
-   - 选择 **Bot Token**
-   - 确认已选择 `chat:read` 和 `chat:write` 权限范围
-   - 复制 **Client ID** 和 **Access Token**
-3. 查找你的 Twitch 用户 ID：https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
-4. 配置令牌：
-   - 环境变量：`SYMI_TWITCH_ACCESS_TOKEN=...`（仅限默认账户）
-   - 或配置：`channels.twitch.accessToken`
-   - 如果两者都设置，配置优先（环境变量回退仅适用于默认账户）。
-5. 启动 Gateway 网关。
-
-**⚠️ 重要：** 添加访问控制（`allowFrom` 或 `allowedRoles`）以防止未授权用户触发机器人。`requireMention` 默认为 `true`。
-
-最小配置：
-
-```json5
-{
-  channels: {
-    twitch: {
-      enabled: true,
-      username: "symi", // 机器人的 Twitch 账户
-      accessToken: "oauth:abc123...", // OAuth Access Token（或使用 SYMI_TWITCH_ACCESS_TOKEN 环境变量）
-      clientId: "xyz789...", // Token Generator 中的 Client ID
-      channel: "vevisk", // 要加入的 Twitch 频道聊天（必填）
-      allowFrom: ["123456789"], // （推荐）仅限你的 Twitch 用户 ID - 从 https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/ 获取
-    },
-  },
-}
-```
-
-## 它是什么
-
-- 由 Gateway 网关拥有的 Twitch 渠道。
-- 确定性路由：回复总是返回到 Twitch。
-- 每个账户映射到一个隔离的会话键 `agent:<agentId>:twitch:<accountName>`。
-- `username` 是机器人账户（进行身份验证的账户），`channel` 是要加入的聊天室。
-
-## 设置（详细）
-
-### 生成凭证
-
-使用 [Twitch Token Generator](https://twitchtokengenerator.com/)：
-
-- 选择 **Bot Token**
-- 确认已选择 `chat:read` 和 `chat:write` 权限范围
-- 复制 **Client ID** 和 **Access Token**
-
-无需手动注册应用。令牌在几小时后过期。
-
-### 配置机器人
-
-**环境变量（仅限默认账户）：**
-
-```bash
-SYMI_TWITCH_ACCESS_TOKEN=oauth:abc123...
-```
-
-**或配置：**
-
-```json5
-{
-  channels: {
-    twitch: {
-      enabled: true,
-      username: "symi",
-      accessToken: "oauth:abc123...",
-      clientId: "xyz789...",
-      channel: "vevisk",
-    },
-  },
-}
-```
-
-如果环境变量和配置都设置了，配置优先。
-
-### 访问控制（推荐）
-
-```json5
-{
-  channels: {
-    twitch: {
-      allowFrom: ["123456789"], // （推荐）仅限你的 Twitch 用户 ID
-    },
-  },
-}
-```
-
-优先使用 `allowFrom` 作为硬性允许列表。如果你想要基于角色的访问控制，请改用 `allowedRoles`。
-
-**可用角色：** `"moderator"`、`"owner"`、`"vip"`、`"subscriber"`、`"all"`。
-
-**为什么用用户 ID？** 用户名可以更改，允许冒充。用户 ID 是永久的。
-
-查找你的 Twitch 用户 ID：https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/（将你的 Twitch 用户名转换为 ID）
-
-## 令牌刷新（可选）
-
-来自 [Twitch Token Generator](https://twitchtokengenerator.com/) 的令牌无法自动刷新 - 过期时需要重新生成。
-
-要实现自动令牌刷新，请在 [Twitch Developer Console](https://dev.twitch.tv/console) 创建你自己的 Twitch 应用并添加到配置中：
-
-```json5
-{
-  channels: {
-    twitch: {
-      clientSecret: "your_client_secret",
-      refreshToken: "your_refresh_token",
-    },
-  },
-}
-```
-
-机器人会在令牌过期前自动刷新，并记录刷新事件。
-
-## 多账户支持
-
-使用 `channels.twitch.accounts` 配置每个账户的令牌。参阅 [`gateway/configuration`](/gateway/configuration) 了解共享模式。
-
-示例（一个机器人账户在两个频道中）：
-
-```json5
-{
-  channels: {
-    twitch: {
-      accounts: {
-        channel1: {
-          username: "symi",
-          accessToken: "oauth:abc123...",
-          clientId: "xyz789...",
-          channel: "vevisk",
-        },
-        channel2: {
-          username: "symi",
-          accessToken: "oauth:def456...",
-          clientId: "uvw012...",
-          channel: "secondchannel",
-        },
-      },
-    },
-  },
-}
-```
-
-**注意：** 每个账户需要自己的令牌（每个频道一个令牌）。
-
-## 访问控制
-
-### 基于角色的限制
-
-```json5
-{
-  channels: {
-    twitch: {
-      accounts: {
-        default: {
-          allowedRoles: ["moderator", "vip"],
-        },
-      },
-    },
-  },
-}
-```
-
-### 按用户 ID 允许列表（最安全）
-
-```json5
-{
-  channels: {
-    twitch: {
-      accounts: {
-        default: {
-          allowFrom: ["123456789", "987654321"],
-        },
-      },
-    },
-  },
-}
-```
-
-### 基于角色的访问（替代方案）
-
-`allowFrom` 是硬性允许列表。设置后，只允许这些用户 ID。
-如果你想要基于角色的访问，请不设置 `allowFrom`，改为配置 `allowedRoles`：
-
-```json5
-{
-  channels: {
-    twitch: {
-      accounts: {
-        default: {
-          allowedRoles: ["moderator"],
-        },
-      },
-    },
-  },
-}
-```
-
-### 禁用 @提及要求
-
-默认情况下，`requireMention` 为 `true`。要禁用并响应所有消息：
-
-```json5
-{
-  channels: {
-    twitch: {
-      accounts: {
-        default: {
-          requireMention: false,
-        },
-      },
-    },
-  },
-}
-```
-
-## 故障排除
-
-首先，运行诊断命令：
-
-```bash
-symi doctor
-symi channels status --probe
-```
-
-### 机器人不响应消息
-
-**检查访问控制：** 确保你的用户 ID 在 `allowFrom` 中，或临时移除 `allowFrom` 并设置 `allowedRoles: ["all"]` 来测试。
-
-**检查机器人是否在频道中：** 机器人必须加入 `channel` 中指定的频道。
-
-### 令牌问题
-
-**"Failed to connect"或身份验证错误：**
-
-- 验证 `accessToken` 是 OAuth 访问令牌值（通常以 `oauth:` 前缀开头）
-- 检查令牌具有 `chat:read` 和 `chat:write` 权限范围
-- 如果使用令牌刷新，验证 `clientSecret` 和 `refreshToken` 已设置
-
-### 令牌刷新不工作
-
-**检查日志中的刷新事件：**
-
-```
-Using env token source for mybot
-Access token refreshed for user 123456 (expires in 14400s)
-```
-
-如果你看到"token refresh disabled (no refresh token)"：
-
-- 确保提供了 `clientSecret`
-- 确保提供了 `refreshToken`
-
-## 配置
-
-**账户配置：**
-
-- `username` - 机器人用户名
-- `accessToken` - 具有 `chat:read` 和 `chat:write` 权限的 OAuth 访问令牌
-- `clientId` - Twitch Client ID（来自 Token Generator 或你的应用）
-- `channel` - 要加入的频道（必填）
-- `enabled` - 启用此账户（默认：`true`）
-- `clientSecret` - 可选：用于自动令牌刷新
-- `refreshToken` - 可选：用于自动令牌刷新
-- `expiresIn` - 令牌过期时间（秒）
-- `obtainmentTimestamp` - 令牌获取时间戳
-- `allowFrom` - 用户 ID 允许列表
-- `allowedRoles` - 基于角色的访问控制（`"moderator" | "owner" | "vip" | "subscriber" | "all"`）
-- `requireMention` - 需要 @提及（默认：`true`）
-
-**提供商选项：**
-
-- `channels.twitch.enabled` - 启用/禁用渠道启动
-- `channels.twitch.username` - 机器人用户名（简化的单账户配置）
-- `channels.twitch.accessToken` - OAuth 访问令牌（简化的单账户配置）
-- `channels.twitch.clientId` - Twitch Client ID（简化的单账户配置）
-- `channels.twitch.channel` - 要加入的频道（简化的单账户配置）
-- `channels.twitch.accounts.<accountName>` - 多账户配置（以上所有账户字段）
-
-完整示例：
-
-```json5
-{
-  channels: {
-    twitch: {
-      enabled: true,
-      username: "symi",
-      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"],
-        },
-      },
-    },
-  },
-}
-```
-
-## 工具操作
-
-智能体可以调用 `twitch` 执行以下操作：
-
-- `send` - 向频道发送消息
-
-示例：
-
-```json5
-{
-  action: "twitch",
-  params: {
-    message: "Hello Twitch!",
-    to: "#mychannel",
-  },
-}
-```
-
-## 安全与运维
-
-- **将令牌视为密码** - 永远不要将令牌提交到 git
-- **使用自动令牌刷新** 用于长时间运行的机器人
-- **使用用户 ID 允许列表** 而不是用户名进行访问控制
-- **监控日志** 查看令牌刷新事件和连接状态
-- **最小化令牌权限范围** - 只请求 `chat:read` 和 `chat:write`
-- **如果卡住**：在确认没有其他进程拥有会话后重启 Gateway 网关
-
-## 限制
-
-- 每条消息 **500 个字符**（在单词边界自动分块）
-- 分块前会去除 Markdown
-- 无速率限制（使用 Twitch 内置的速率限制）